@eslint/plugin-kit 0.7.3

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 pkg:npm/%40eslint/plugin-kit@0.7.3
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40eslint/plugin-kit@0.7.3

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:9fa9d6cc1ba5a5b42a7231683d7bbbbcd432f50a4f6e28a8563414d881aef602","constraints":{"executionContext":"node"},"contract":["assert ConfigCommentParser.parseDirective parses comments into label, value, and justification","assert ConfigCommentParser.parseStringConfig parses string key-value configurations","assert ConfigCommentParser.parseListConfig parses rule name lists into boolean maps","assert ConfigCommentParser.parseJSONLikeConfig parses relaxed JSON configurations","assert Directive constructs directive instances with type, node, value, and justification","assert VisitNodeStep and CallMethodStep construct traversal steps with kind, type, and target","assert TextSourceCodeBase provides lines, getLoc, getRange, getLocFromIndex, getIndexFromLoc, getAncestors, and getText"],"goal":"verify pkg:npm/%40eslint/plugin-kit@0.7.3","kind":"HOW","packages":["pkg:npm/%40eslint/plugin-kit@0.7.3"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","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.7.3"],"schemaVersion":1,"subject":"pkg:npm/%40eslint/plugin-kit@0.7.3","verifierAdapter":"node-typescript@1"}

const {
  ConfigCommentParser,
  Directive,
  VisitNodeStep,
  CallMethodStep,
  TextSourceCodeBase,
} = require('@eslint/plugin-kit');

/**
 * Parses an ESLint directive comment string.
 *
 * @param {string} comment - Raw comment content without delimiters.
 * @returns {object} Parsed directive containing label, value, and justification.
 */
function parseCommentDirective(comment) {
  const parser = new ConfigCommentParser();
  return parser.parseDirective(comment);
}

/**
 * Parses a comma-separated key: value configuration string.
 *
 * @param {string} configText - String configuration representation.
 * @returns {Record<string, string>} Key-value configuration map.
 */
function parseStringConfig(configText) {
  const parser = new ConfigCommentParser();
  return parser.parseStringConfig(configText);
}

/**
 * Parses a comma-separated list of rule names.
 *
 * @param {string} listText - Comma-separated rule list.
 * @returns {Record<string, boolean>} Object with rule names mapped to true.
 */
function parseListConfig(listText) {
  const parser = new ConfigCommentParser();
  return parser.parseListConfig(listText);
}

/**
 * Parses a relaxed/JSON5-like configuration string.
 *
 * @param {string} jsonText - JSON-like configuration text.
 * @returns {{ ok: boolean, config?: unknown, error?: unknown }} Parse outcome.
 */
function parseJSONConfig(jsonText) {
  const parser = new ConfigCommentParser();
  return parser.parseJSONLikeConfig(jsonText);
}

/**
 * Creates a directive descriptor for disabling/enabling rules.
 *
 * @param {object} options - Directive options.
 * @param {string} options.type - Directive type ('disable', 'enable', 'disable-line', 'disable-next-line').
 * @param {object} options.node - Comment AST node.
 * @param {string} options.value - Directive value.
 * @param {string} [options.justification] - Justification comment.
 * @returns {Directive} Directive instance.
 */
function createDirective(options) {
  return new Directive(options);
}

/**
 * Custom SourceCode implementation extending TextSourceCodeBase.
 */
class CustomSourceCode extends TextSourceCodeBase {
  #parents = new Map();

  getParent(node) {
    return this.#parents.get(node);
  }

  setParent(node, parent) {
    this.#parents.set(node, parent);
  }
}

module.exports = {
  ConfigCommentParser,
  Directive,
  VisitNodeStep,
  CallMethodStep,
  TextSourceCodeBase,
  CustomSourceCode,
  parseCommentDirective,
  parseStringConfig,
  parseListConfig,
  parseJSONConfig,
  createDirective,
};

{
  "name": "sample-eslint-plugin-kit",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-eslint-plugin-kit",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@eslint/plugin-kit": "0.7.3"
      }
    },
    "node_modules/@eslint/core": {
      "version": "1.2.1",
      "resolved": "https://registry.npmjs.org/@eslint/core/-/core-1.2.1.tgz",
      "integrity": "sha512-MwcE1P+AZ4C6DWlpin/OmOA54mmIZ/+xZuJiQd4SyB29oAJjN30UW9wkKNptW2ctp4cEsvhlLY/CsQ1uoHDloQ==",
      "license": "Apache-2.0",
      "dependencies": {
        "@types/json-schema": "^7.0.15"
      },
      "engines": {
        "node": "^20.19.0 || ^22.13.0 || >=24"
      }
    },
    "node_modules/@eslint/plugin-kit": {
      "version": "0.7.3",
      "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.7.3.tgz",
      "integrity": "sha512-IkO+/KEUvwbVpiURZg+P7zF74z5Jxe0UgJxVni+RtoHQ6IZieXaO02kmadomap/q+l6bc/jdPGGqTjhuZnuz1Q==",
      "license": "Apache-2.0",
      "dependencies": {
        "@eslint/core": "^1.2.1",
        "levn": "^0.4.1"
      },
      "engines": {
        "node": "^20.19.0 || ^22.13.0 || >=24"
      }
    },
    "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",
  "version": "1.0.0",
  "description": "Clean-room sample verifying @eslint/plugin-kit core utilities",
  "main": "index.js",
  "license": "MIT-0",
  "dependencies": {
    "@eslint/plugin-kit": "0.7.3"
  }
}

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

import assert from 'node:assert';
import {
  ConfigCommentParser,
  Directive,
  VisitNodeStep,
  CallMethodStep,
  TextSourceCodeBase,
  CustomSourceCode,
  parseCommentDirective,
  parseStringConfig,
  parseListConfig,
  parseJSONConfig,
  createDirective,
} from '../index.js';

// 1. Verify ConfigCommentParser.parseDirective
const parsedDirective = parseCommentDirective(
  'eslint-disable no-alert, no-console -- suppress warnings in test fixtures'
);
assert.strictEqual(parsedDirective.label, 'eslint-disable');
assert.strictEqual(parsedDirective.value, 'no-alert, no-console');
assert.strictEqual(
  parsedDirective.justification,
  'suppress warnings in test fixtures'
);

const directParser = new ConfigCommentParser();
const directDirective = directParser.parseDirective('eslint-enable no-eval');
assert.strictEqual(directDirective.label, 'eslint-enable');
assert.strictEqual(directDirective.value, 'no-eval');
assert.strictEqual(directDirective.justification, '');

// 2. Verify ConfigCommentParser.parseStringConfig
const stringConfig = parseStringConfig('quotes: single, semi: always');
assert.deepStrictEqual(
  stringConfig,
  Object.assign(Object.create(null), {
    quotes: 'single',
    semi: 'always',
  })
);

// 3. Verify ConfigCommentParser.parseListConfig
const listConfig = parseListConfig('no-unused-vars, eqeqeq, curly');
assert.deepStrictEqual(
  listConfig,
  Object.assign(Object.create(null), {
    'no-unused-vars': true,
    eqeqeq: true,
    curly: true,
  })
);

// 4. Verify ConfigCommentParser.parseJSONLikeConfig
const validJSON = parseJSONConfig('quotes: ["error", "single"], semi: 0');
assert.strictEqual(validJSON.ok, true);
assert.deepStrictEqual(validJSON.config, {
  quotes: ['error', 'single'],
  semi: 0,
});

const invalidJSON = parseJSONConfig('invalid { json string');
assert.strictEqual(invalidJSON.ok, false);
assert.ok(invalidJSON.error);

// 5. Verify Directive instance
const mockCommentNode = {
  type: 'BlockComment',
  value: 'eslint-disable-next-line no-debugger',
};
const directiveInstance = createDirective({
  type: 'disable-next-line',
  node: mockCommentNode,
  value: 'no-debugger',
  justification: 'temporary debugging statement',
});
assert.strictEqual(directiveInstance.type, 'disable-next-line');
assert.strictEqual(directiveInstance.node, mockCommentNode);
assert.strictEqual(directiveInstance.value, 'no-debugger');
assert.strictEqual(
  directiveInstance.justification,
  'temporary debugging statement'
);

// 6. Verify VisitNodeStep and CallMethodStep
const astIdentifier = {
  type: 'Identifier',
  name: 'myVariable',
  range: [6, 16],
  loc: {
    start: { line: 1, column: 6 },
    end: { line: 1, column: 16 },
  },
};

const visitStep = new VisitNodeStep({
  target: astIdentifier,
  phase: 1,
  args: [astIdentifier, null],
});
assert.strictEqual(visitStep.type, 'visit');
assert.strictEqual(visitStep.kind, 1);
assert.strictEqual(visitStep.phase, 1);
assert.strictEqual(visitStep.target, astIdentifier);
assert.deepStrictEqual(visitStep.args, [astIdentifier, null]);

const callStep = new CallMethodStep({
  target: 'onCodePathStart',
  args: ['codePath1', astIdentifier],
});
assert.strictEqual(callStep.type, 'call');
assert.strictEqual(callStep.kind, 2);
assert.strictEqual(callStep.target, 'onCodePathStart');
assert.deepStrictEqual(callStep.args, ['codePath1', astIdentifier]);

// 7. Verify TextSourceCodeBase and CustomSourceCode methods
const sourceText = 'const myVariable = 42;\nconst nextLine = true;\n';
const varDecl = {
  type: 'VariableDeclaration',
  kind: 'const',
  range: [0, 22],
  loc: {
    start: { line: 1, column: 0 },
    end: { line: 1, column: 22 },
  },
  declarations: [astIdentifier],
};
const rootAst = {
  type: 'Program',
  range: [0, sourceText.length],
  loc: {
    start: { line: 1, column: 0 },
    end: { line: 3, column: 0 },
  },
  body: [varDecl],
};

const sourceCode = new CustomSourceCode({
  ast: rootAst,
  text: sourceText,
});
sourceCode.setParent(astIdentifier, varDecl);
sourceCode.setParent(varDecl, rootAst);

assert.strictEqual(sourceCode.lines.length, 3);
assert.strictEqual(sourceCode.lines[0], 'const myVariable = 42;');
assert.strictEqual(sourceCode.lines[1], 'const nextLine = true;');
assert.strictEqual(sourceCode.lines[2], '');

// getText with node, offsets, and default (whole text for omitted/null)
assert.strictEqual(sourceCode.getText(astIdentifier), 'myVariable');
assert.strictEqual(sourceCode.getText(astIdentifier, 6), 'const myVariable');
assert.strictEqual(sourceCode.getText(astIdentifier, 0, 5), 'myVariable = 42');
assert.strictEqual(sourceCode.getText(), sourceText);
assert.strictEqual(sourceCode.getText(null), sourceText);
assert.strictEqual(sourceCode.getText(undefined), sourceText);

// getAncestors from root to parent
const ancestors = sourceCode.getAncestors(astIdentifier);
assert.deepStrictEqual(ancestors, [rootAst, varDecl]);

assert.deepStrictEqual(sourceCode.getLoc(astIdentifier), {
  start: { line: 1, column: 6 },
  end: { line: 1, column: 16 },
});
assert.deepStrictEqual(sourceCode.getRange(astIdentifier), [6, 16]);

assert.deepStrictEqual(sourceCode.getLocFromIndex(6), {
  line: 1,
  column: 6,
});
assert.strictEqual(sourceCode.getIndexFromLoc({ line: 2, column: 6 }), 29);
assert.strictEqual(sourceCode.getParent(astIdentifier), varDecl);

console.log('All @eslint/plugin-kit contract assertions passed successfully.');