@eslint/plugin-kit 0.2.8: parse directive and configuration comments using ConfigCommentParser

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: parse directive and configuration comments using ConfigCommentParser
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40eslint/plugin-kit@0.2.8
Demonstrate these symbols/APIs:
  - ConfigCommentParser
  - ConfigCommentParser.parseDirective
  - ConfigCommentParser.parseJSONLikeConfig
  - ConfigCommentParser.parseListConfig
  - ConfigCommentParser.parseStringConfig

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:432c90792053d065d7a819424b1dae58611689aec8908a4f664ba25fa902689a","contract":["ConfigCommentParser.parseDirective extracts label, value, and justification separated by double dash","ConfigCommentParser.parseDirective extracts directive without justification returning empty string for justification","ConfigCommentParser.parseDirective returns undefined when string does not match directive pattern","ConfigCommentParser.parseStringConfig parses comma or whitespace separated name-value pairs defaulting missing values to null","ConfigCommentParser.parseListConfig parses comma-separated rule names into boolean map trimming quotes","ConfigCommentParser.parseJSONLikeConfig parses valid rule configurations into ok result object with config map","ConfigCommentParser.parseJSONLikeConfig returns error object when configuration contains invalid JSON syntax","createCommentParser helper creates a valid ConfigCommentParser instance"],"goal":"parse directive and configuration comments using ConfigCommentParser","kind":"HOW","packages":["pkg:npm/%40eslint/plugin-kit@0.2.8"],"schemaVersion":1,"symbols":["ConfigCommentParser","ConfigCommentParser.parseDirective","ConfigCommentParser.parseJSONLikeConfig","ConfigCommentParser.parseListConfig","ConfigCommentParser.parseStringConfig"]},"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.2.8"],"schemaVersion":1,"subject":"pkg:npm/%40eslint/plugin-kit@0.2.8","symbols":["ConfigCommentParser","ConfigCommentParser.parseDirective","ConfigCommentParser.parseJSONLikeConfig","ConfigCommentParser.parseListConfig","ConfigCommentParser.parseStringConfig"],"verifierAdapter":"node-typescript@1"}

{
  "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.2.8"
      }
    },
    "node_modules/@eslint/core": {
      "version": "0.13.0",
      "resolved": "https://registry.npmjs.org/@eslint/core/-/core-0.13.0.tgz",
      "integrity": "sha512-yfkgDw1KR66rkT5A8ci4irzDysN7FRpq3ttJolR88OqQikAWqwA8j5VZyas+vjyBNFIJ7MfybJ9plMILI2UrCw==",
      "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.2.8",
      "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.2.8.tgz",
      "integrity": "sha512-ZAoA40rNMPwSm+AeHpCq8STiNAwzWLJuP8Xv4CHIc9wv/PSuExjMrmjfYNj682vW0OOiZ1HKxzvjQr9XZIisQA==",
      "license": "Apache-2.0",
      "dependencies": {
        "@eslint/core": "^0.13.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",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@eslint/plugin-kit": "0.2.8"
  }
}

{
  "schemaVersion": 1,
  "goal": "parse directive and configuration comments using ConfigCommentParser",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40eslint/plugin-kit@0.2.8"
  ],
  "symbols": [
    "ConfigCommentParser",
    "ConfigCommentParser.parseDirective",
    "ConfigCommentParser.parseJSONLikeConfig",
    "ConfigCommentParser.parseListConfig",
    "ConfigCommentParser.parseStringConfig"
  ]
}

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

/**
 * Creates a new ConfigCommentParser instance.
 * @returns {ConfigCommentParser} A new ConfigCommentParser instance.
 */
export function createCommentParser() {
  return new ConfigCommentParser();
}

/**
 * Parses an inline directive comment (e.g. "eslint-disable rule-name -- reason").
 * @param {string} comment Text of the directive comment.
 * @returns {import('@eslint/plugin-kit').DirectiveComment|undefined} Parsed directive or undefined.
 */
export function parseDirectiveComment(comment) {
  const parser = new ConfigCommentParser();
  return parser.parseDirective(comment);
}

/**
 * Parses a comma- or whitespace-separated list of string configuration options.
 * @param {string} text Configuration text.
 * @returns {Record<string, string|null>} Parsed map of option names and values.
 */
export function parseStringConfiguration(text) {
  const parser = new ConfigCommentParser();
  return parser.parseStringConfig(text);
}

/**
 * Parses a comma-separated list of rule names or options into boolean flags.
 * @param {string} text List configuration text.
 * @returns {Record<string, boolean>} Map of rule names to true.
 */
export function parseListConfiguration(text) {
  const parser = new ConfigCommentParser();
  return parser.parseListConfig(text);
}

/**
 * Parses a JSON-like configuration string into a configuration object.
 * @param {string} text JSON-like configuration text.
 * @returns {{ ok: true, config: Record<string, unknown> } | { ok: false, error: { message: string } }} Parse result.
 */
export function parseJSONLikeConfiguration(text) {
  const parser = new ConfigCommentParser();
  return parser.parseJSONLikeConfig(text);
}

export { ConfigCommentParser };
export default ConfigCommentParser;

import assert from 'node:assert/strict';
import { ConfigCommentParser } from '@eslint/plugin-kit';
import {
  createCommentParser,
  parseDirectiveComment,
  parseStringConfiguration,
  parseListConfiguration,
  parseJSONLikeConfiguration,
} from '../src/index.mjs';

// 1. ConfigCommentParser.parseDirective extracts label, value, and justification separated by double dash
{
  const parser = new ConfigCommentParser();
  const directive = parser.parseDirective('eslint-disable prefer-const, semi -- I do not want these rules');

  assert.ok(directive !== undefined);
  assert.equal(directive.label, 'eslint-disable');
  assert.equal(directive.value, 'prefer-const, semi');
  assert.equal(directive.justification, 'I do not want these rules');

  const helperDirective = parseDirectiveComment('eslint-enable no-console -- re-enabling console');
  assert.ok(helperDirective !== undefined);
  assert.equal(helperDirective.label, 'eslint-enable');
  assert.equal(helperDirective.value, 'no-console');
  assert.equal(helperDirective.justification, 're-enabling console');
}

// 2. ConfigCommentParser.parseDirective extracts directive without justification returning empty string for justification
{
  const parser = new ConfigCommentParser();
  const directive = parser.parseDirective('eslint-disable-next-line no-unused-vars');

  assert.ok(directive !== undefined);
  assert.equal(directive.label, 'eslint-disable-next-line');
  assert.equal(directive.value, 'no-unused-vars');
  assert.equal(directive.justification, '');
}

// 3. ConfigCommentParser.parseDirective returns undefined when string does not match directive pattern
{
  const parser = new ConfigCommentParser();
  const invalidResult = parser.parseDirective('  -- only justification');
  assert.equal(invalidResult, undefined);

  const emptyResult = parser.parseDirective('');
  assert.equal(emptyResult, undefined);
}

// 4. ConfigCommentParser.parseStringConfig parses comma or whitespace separated name-value pairs defaulting missing values to null
{
  const parser = new ConfigCommentParser();
  const config = parser.parseStringConfig('foo:off, bar, baz:on');

  assert.deepEqual(config, {
    foo: 'off',
    bar: null,
    baz: 'on',
  });

  const helperConfig = parseStringConfiguration('env1:readonly env2:writable');
  assert.deepEqual(helperConfig, {
    env1: 'readonly',
    env2: 'writable',
  });
}

// 5. ConfigCommentParser.parseListConfig parses comma-separated rule names into boolean map trimming quotes
{
  const parser = new ConfigCommentParser();
  const list = parser.parseListConfig('prefer-const, "semi", \'no-console\'');

  assert.deepEqual(list, {
    'prefer-const': true,
    semi: true,
    'no-console': true,
  });

  const helperList = parseListConfiguration('rule-a, rule-b');
  assert.deepEqual(helperList, {
    'rule-a': true,
    'rule-b': true,
  });
}

// 6. ConfigCommentParser.parseJSONLikeConfig parses valid rule configurations into ok result object with config map
{
  const parser = new ConfigCommentParser();
  const result = parser.parseJSONLikeConfig('semi: [error, never], prefer-const: warn, quotes: ["error", "single"]');

  assert.equal(result.ok, true);
  assert.deepEqual(result.config, {
    semi: ['error', 'never'],
    'prefer-const': 'warn',
    quotes: ['error', 'single'],
  });

  const helperResult = parseJSONLikeConfiguration('no-unused-vars: 2');
  assert.equal(helperResult.ok, true);
  assert.deepEqual(helperResult.config, {
    'no-unused-vars': 2,
  });
}

// 7. ConfigCommentParser.parseJSONLikeConfig returns error object when configuration contains invalid JSON syntax
{
  const parser = new ConfigCommentParser();
  const result = parser.parseJSONLikeConfig('invalid: [unclosed');

  assert.equal(result.ok, false);
  assert.ok(typeof result.error?.message === 'string');
  assert.ok(result.error.message.includes('Failed to parse JSON'));

  const helperResult = parseJSONLikeConfiguration('semi: {bad');
  assert.equal(helperResult.ok, false);
  assert.ok(typeof helperResult.error?.message === 'string');
}

// 8. createCommentParser helper creates a valid ConfigCommentParser instance
{
  const parser = createCommentParser();
  assert.ok(parser instanceof ConfigCommentParser);
}

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