@eslint/plugin-kit 0.4.1: Directive

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify @eslint/plugin-kit.Directive in pkg:npm/%40eslint/plugin-kit@0.4.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40eslint/plugin-kit@0.4.1
Demonstrate these symbols/APIs:
  - @eslint/plugin-kit.Directive

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:6f2ea2643b4b72243cd66420bc2314feb923711bf2f8008d97c384aca2e7ab85","contract":["Directive constructor creates an instance with type, node, value, and justification properties","Directive constructor correctly assigns all supported directive types: disable, enable, disable-line, and disable-next-line","Directive handles empty justification strings when no justification is supplied","Directive preserves reference to the underlying AST comment node without modification","getDirectiveTypeFromLabel accurately maps directive comment labels to DirectiveType values","parseDirectiveFromComment parses directive comment strings and creates corresponding Directive instances","parseDirectiveFromComment returns undefined for non-directive comments or unrecognised labels"],"goal":"verify @eslint/plugin-kit.Directive in pkg:npm/%40eslint/plugin-kit@0.4.1","kind":"HOW","packages":["pkg:npm/%40eslint/plugin-kit@0.4.1"],"schemaVersion":1,"symbols":["@eslint/plugin-kit.Directive"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40eslint/plugin-kit@0.4.1"],"schemaVersion":1,"subject":"pkg:npm/%40eslint/plugin-kit@0.4.1","symbols":["@eslint/plugin-kit.Directive"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-eslint-plugin-kit-directive",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-eslint-plugin-kit-directive",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@eslint/plugin-kit": "0.4.1"
      }
    },
    "node_modules/@eslint/core": {
      "version": "0.17.0",
      "resolved": "https://registry.npmjs.org/@eslint/core/-/core-0.17.0.tgz",
      "integrity": "sha512-yL/sLrpmtDaFEiUj1osRP4TI2MDz1AddJL+jZ7KSqvBuliN4xqYY54IfdN8qD8Toa6g1iloph1fxQNkjOxrrpQ==",
      "license": "Apache-2.0",
      "dependencies": {
        "@types/json-schema": "^7.0.15"
      },
      "engines": {
        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
      }
    },
    "node_modules/@eslint/plugin-kit": {
      "version": "0.4.1",
      "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.4.1.tgz",
      "integrity": "sha512-43/qtrDUokr7LJqoF2c3+RInu/t4zfrpYdoSDfYyhg52rwLV6TnOvdG4fXm7IkSB3wErkcmJS9iEhjVtOSEjjA==",
      "license": "Apache-2.0",
      "dependencies": {
        "@eslint/core": "^0.17.0",
        "levn": "^0.4.1"
      },
      "engines": {
        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
      }
    },
    "node_modules/@types/json-schema": {
      "version": "7.0.15",
      "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.15.tgz",
      "integrity": "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==",
      "license": "MIT"
    },
    "node_modules/levn": {
      "version": "0.4.1",
      "resolved": "https://registry.npmjs.org/levn/-/levn-0.4.1.tgz",
      "integrity": "sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==",
      "license": "MIT",
      "dependencies": {
        "prelude-ls": "^1.2.1",
        "type-check": "~0.4.0"
      },
      "engines": {
        "node": ">= 0.8.0"
      }
    },
    "node_modules/prelude-ls": {
      "version": "1.2.1",
      "resolved": "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.2.1.tgz",
      "integrity": "sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==",
      "license": "MIT",
      "engines": {
        "node": ">= 0.8.0"
      }
    },
    "node_modules/type-check": {
      "version": "0.4.0",
      "resolved": "https://registry.npmjs.org/type-check/-/type-check-0.4.0.tgz",
      "integrity": "sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==",
      "license": "MIT",
      "dependencies": {
        "prelude-ls": "^1.2.1"
      },
      "engines": {
        "node": ">= 0.8.0"
      }
    }
  }
}

{
  "name": "sample-eslint-plugin-kit-directive",
  "version": "1.0.0",
  "description": "Clean-room sample verifying @eslint/plugin-kit Directive",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@eslint/plugin-kit": "0.4.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify @eslint/plugin-kit.Directive in pkg:npm/%40eslint/plugin-kit@0.4.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40eslint/plugin-kit@0.4.1"
  ],
  "symbols": [
    "@eslint/plugin-kit.Directive"
  ]
}

import { Directive, ConfigCommentParser } from '@eslint/plugin-kit';

/**
 * Creates a new Directive instance with explicit options.
 *
 * @param {object} options
 * @param {'disable'|'enable'|'disable-line'|'disable-next-line'} options.type - Directive type.
 * @param {unknown} options.node - The comment AST node representing the directive.
 * @param {string} options.value - Value portion of the directive.
 * @param {string} [options.justification] - Optional justification comment.
 * @returns {Directive} New Directive instance.
 */
export function createDirective({ type, node, value, justification = '' }) {
  return new Directive({ type, node, value, justification });
}

/**
 * Maps an ESLint comment directive label to a DirectiveType.
 *
 * @param {string} label - Directive label (e.g., 'eslint-disable', 'eslint-enable').
 * @returns {'disable'|'enable'|'disable-line'|'disable-next-line'|null} DirectiveType or null.
 */
export function getDirectiveTypeFromLabel(label) {
  switch (label) {
    case 'eslint-disable':
      return 'disable';
    case 'eslint-enable':
      return 'enable';
    case 'eslint-disable-line':
      return 'disable-line';
    case 'eslint-disable-next-line':
      return 'disable-next-line';
    default:
      return null;
  }
}

/**
 * Creates a Directive instance by parsing a raw comment text using ConfigCommentParser.
 *
 * @param {string} commentText - Raw comment string (without comment delimiters).
 * @param {unknown} commentNode - The comment AST node.
 * @returns {Directive|undefined} Parsed Directive instance, or undefined if parsing failed or directive is unsupported.
 */
export function parseDirectiveFromComment(commentText, commentNode) {
  const parser = new ConfigCommentParser();
  const parsed = parser.parseDirective(commentText);
  if (!parsed) {
    return undefined;
  }

  const type = getDirectiveTypeFromLabel(parsed.label);
  if (!type) {
    return undefined;
  }

  return new Directive({
    type,
    node: commentNode,
    value: parsed.value,
    justification: parsed.justification,
  });
}

export { Directive, ConfigCommentParser };
export default Directive;

import assert from 'node:assert/strict';
import { Directive, ConfigCommentParser } from '@eslint/plugin-kit';
import {
  createDirective,
  getDirectiveTypeFromLabel,
  parseDirectiveFromComment,
} from '../src/index.mjs';

// 1. Directive constructor creates an instance with type, node, value, and justification properties
{
  const mockNode = {
    type: 'Block',
    value: 'eslint-disable no-console -- debugging only',
    loc: { start: { line: 5, column: 2 }, end: { line: 5, column: 48 } },
  };

  const directive = new Directive({
    type: 'disable',
    node: mockNode,
    value: 'no-console',
    justification: 'debugging only',
  });

  assert.ok(directive instanceof Directive);
  assert.equal(directive.type, 'disable');
  assert.equal(directive.node, mockNode);
  assert.equal(directive.value, 'no-console');
  assert.equal(directive.justification, 'debugging only');

  const helperDirective = createDirective({
    type: 'disable',
    node: mockNode,
    value: 'no-alert',
    justification: 'production cleanup',
  });
  assert.ok(helperDirective instanceof Directive);
  assert.equal(helperDirective.type, 'disable');
  assert.equal(helperDirective.value, 'no-alert');
  assert.equal(helperDirective.justification, 'production cleanup');
}

// 2. Directive constructor correctly assigns all supported directive types: disable, enable, disable-line, and disable-next-line
{
  const supportedTypes = ['disable', 'enable', 'disable-line', 'disable-next-line'];
  const mockNode = { type: 'Line', value: 'eslint-disable-line no-eval' };

  for (const type of supportedTypes) {
    const directive = new Directive({
      type,
      node: mockNode,
      value: 'no-eval',
      justification: 'intentional eval usage',
    });

    assert.equal(directive.type, type);
    assert.equal(directive.node, mockNode);
    assert.equal(directive.value, 'no-eval');
    assert.equal(directive.justification, 'intentional eval usage');
  }
}

// 3. Directive handles empty justification strings when no justification is supplied
{
  const mockNode = { type: 'Line', value: 'eslint-disable-next-line' };

  const directive = new Directive({
    type: 'disable-next-line',
    node: mockNode,
    value: '',
    justification: '',
  });

  assert.equal(directive.type, 'disable-next-line');
  assert.equal(directive.value, '');
  assert.equal(directive.justification, '');

  const helperDirective = createDirective({
    type: 'enable',
    node: mockNode,
    value: 'no-debugger',
  });
  assert.equal(helperDirective.justification, '');
}

// 4. Directive preserves reference to the underlying AST comment node without modification
{
  const complexNode = {
    type: 'Block',
    value: 'eslint-disable no-warning-comments',
    range: [100, 140],
    loc: { start: { line: 10, column: 0 }, end: { line: 10, column: 40 } },
    metadata: { customField: 42 },
  };

  const directive = new Directive({
    type: 'disable',
    node: complexNode,
    value: 'no-warning-comments',
    justification: '',
  });

  assert.strictEqual(directive.node, complexNode);
  assert.strictEqual(directive.node.metadata.customField, 42);
}

// 5. getDirectiveTypeFromLabel accurately maps directive comment labels to DirectiveType values
{
  assert.equal(getDirectiveTypeFromLabel('eslint-disable'), 'disable');
  assert.equal(getDirectiveTypeFromLabel('eslint-enable'), 'enable');
  assert.equal(getDirectiveTypeFromLabel('eslint-disable-line'), 'disable-line');
  assert.equal(getDirectiveTypeFromLabel('eslint-disable-next-line'), 'disable-next-line');
  assert.equal(getDirectiveTypeFromLabel('eslint-env'), null);
  assert.equal(getDirectiveTypeFromLabel('unknown-label'), null);
}

// 6. parseDirectiveFromComment parses directive comment strings and creates corresponding Directive instances
{
  const mockNode = {
    type: 'Block',
    value: 'eslint-disable-next-line no-undef, eqeqeq -- legacy code compatibility',
  };

  const directive = parseDirectiveFromComment(
    'eslint-disable-next-line no-undef, eqeqeq -- legacy code compatibility',
    mockNode
  );

  assert.ok(directive instanceof Directive);
  assert.equal(directive.type, 'disable-next-line');
  assert.equal(directive.node, mockNode);
  assert.equal(directive.value, 'no-undef, eqeqeq');
  assert.equal(directive.justification, 'legacy code compatibility');
}

// 7. parseDirectiveFromComment returns undefined for non-directive comments or unrecognised labels
{
  const mockNode = { type: 'Line', value: 'just a normal comment' };

  const invalidDirective1 = parseDirectiveFromComment('just a normal comment', mockNode);
  assert.equal(invalidDirective1, undefined);

  const invalidDirective2 = parseDirectiveFromComment('eslint-env browser', mockNode);
  assert.equal(invalidDirective2, undefined);

  const invalidDirective3 = parseDirectiveFromComment('', mockNode);
  assert.equal(invalidDirective3, undefined);
}

console.log('Contract tests passed successfully.');