@eslint/plugin-kit 0.4.1: TextSourceCodeBase

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.TextSourceCodeBase 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.TextSourceCodeBase

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:c99a993b2379d09aecadc59f87be709bed492f14ae80c3d8fcb19bdc8c8ed071","contract":["assert TextSourceCodeBase initializes ast, text, and lazily calculates frozen lines array","assert TextSourceCodeBase extracts ESTree and Position style loc and range coordinates","assert TextSourceCodeBase converts bidirectionally between character indices and line-column locations","assert TextSourceCodeBase getText retrieves full source text or slices by node range with offset padding","assert TextSourceCodeBase delegates getParent and traverses ancestors from root to parent","assert TextSourceCodeBase defines traversal contract throwing on unimplemented base methods"],"goal":"verify @eslint/plugin-kit.TextSourceCodeBase 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.TextSourceCodeBase"]},"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.4.1"],"schemaVersion":1,"subject":"pkg:npm/%40eslint/plugin-kit@0.4.1","symbols":["@eslint/plugin-kit.TextSourceCodeBase"],"verifierAdapter":"node-typescript@1"}

const { TextSourceCodeBase } = require('@eslint/plugin-kit');

/**
 * Custom SourceCode implementation extending TextSourceCodeBase.
 * Implements getParent, setParent, and traverse to fulfill the TextSourceCodeBase abstract contracts.
 */
class CustomSourceCode extends TextSourceCodeBase {
  #parents = new Map();

  /**
   * Returns the parent of the given node.
   * @param {object} node The AST node.
   * @returns {object|undefined} The parent node or undefined.
   */
  getParent(node) {
    return this.#parents.get(node);
  }

  /**
   * Sets the parent of the given node.
   * @param {object} node The child AST node.
   * @param {object} parent The parent AST node.
   */
  setParent(node, parent) {
    this.#parents.set(node, parent);
  }

  /**
   * Traverses the AST yielding traversal steps.
   * @returns {Iterable<{type: string, kind: number, target: object, phase: number, args: any[]}>}
   */
  *traverse() {
    function* visit(node, parent) {
      if (!node || typeof node !== 'object') return;
      yield { type: 'visit', kind: 1, target: node, phase: 1, args: [node, parent] };
      for (const [key, value] of Object.entries(node)) {
        if (key === 'parent' || key === 'loc' || key === 'range') continue;
        if (Array.isArray(value)) {
          for (const item of value) {
            if (item && typeof item === 'object') {
              yield* visit(item, node);
            }
          }
        } else if (value && typeof value === 'object') {
          yield* visit(value, node);
        }
      }
      yield { type: 'visit', kind: 1, target: node, phase: 2, args: [node, parent] };
    }
    yield* visit(this.ast, null);
  }
}

/**
 * Factory to create a CustomSourceCode instance.
 * @param {object} options
 * @param {string} options.text
 * @param {object} options.ast
 * @param {RegExp} [options.lineEndingPattern]
 * @returns {CustomSourceCode}
 */
function createSourceCode(options) {
  return new CustomSourceCode(options);
}

module.exports = {
  TextSourceCodeBase,
  CustomSourceCode,
  createSourceCode,
};

{
  "name": "sample-eslint-plugin-kit-textsourcecodebase",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-eslint-plugin-kit-textsourcecodebase",
      "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-textsourcecodebase",
  "version": "1.0.0",
  "description": "Clean-room sample verifying @eslint/plugin-kit TextSourceCodeBase",
  "main": "index.js",
  "license": "MIT-0",
  "dependencies": {
    "@eslint/plugin-kit": "0.4.1"
  }
}

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

import assert from 'node:assert';
import {
  TextSourceCodeBase,
  CustomSourceCode,
  createSourceCode,
} from '../index.js';

// 1. TextSourceCodeBase initializes ast, text, and lazily calculates frozen lines array
const sampleText = 'const a = 1;\nconst b = 2;\nconsole.log(a + b);\n';
const astIdentifier = {
  type: 'Identifier',
  name: 'a',
  range: [6, 7],
  loc: {
    start: { line: 1, column: 6 },
    end: { line: 1, column: 7 },
  },
};
const astVarDecl = {
  type: 'VariableDeclaration',
  range: [0, 12],
  loc: {
    start: { line: 1, column: 0 },
    end: { line: 1, column: 12 },
  },
  declarations: [
    {
      type: 'VariableDeclarator',
      id: astIdentifier,
      range: [6, 11],
      loc: {
        start: { line: 1, column: 6 },
        end: { line: 1, column: 11 },
      },
    },
  ],
};
const rootAst = {
  type: 'Program',
  range: [0, sampleText.length],
  loc: {
    start: { line: 1, column: 0 },
    end: { line: 4, column: 0 },
  },
  body: [astVarDecl],
};

const sourceCode = createSourceCode({ text: sampleText, ast: rootAst });
assert.strictEqual(sourceCode.text, sampleText);
assert.strictEqual(sourceCode.ast, rootAst);
assert.deepStrictEqual(sourceCode.lines, [
  'const a = 1;',
  'const b = 2;',
  'console.log(a + b);',
  '',
]);
assert.ok(Object.isFrozen(sourceCode.lines));

// 2. TextSourceCodeBase extracts ESTree and Position style loc and range coordinates
assert.deepStrictEqual(sourceCode.getLoc(astIdentifier), {
  start: { line: 1, column: 6 },
  end: { line: 1, column: 7 },
});
assert.deepStrictEqual(sourceCode.getRange(astIdentifier), [6, 7]);

const posNode = {
  type: 'MarkdownHeading',
  position: {
    start: { line: 2, column: 6, offset: 19 },
    end: { line: 2, column: 7, offset: 20 },
  },
};
assert.deepStrictEqual(sourceCode.getLoc(posNode), {
  start: { line: 2, column: 6, offset: 19 },
  end: { line: 2, column: 7, offset: 20 },
});
assert.deepStrictEqual(sourceCode.getRange(posNode), [19, 20]);

assert.throws(
  () => sourceCode.getLoc({}),
  /Custom getLoc\(\) method must be implemented/
);
assert.throws(
  () => sourceCode.getRange({}),
  /Custom getRange\(\) method must be implemented/
);

// 3. TextSourceCodeBase converts bidirectionally between character indices and line-column locations
assert.deepStrictEqual(sourceCode.getLocFromIndex(0), { line: 1, column: 0 });
assert.deepStrictEqual(sourceCode.getLocFromIndex(6), { line: 1, column: 6 });
assert.deepStrictEqual(sourceCode.getLocFromIndex(13), { line: 2, column: 0 });
assert.deepStrictEqual(sourceCode.getLocFromIndex(sampleText.length), {
  line: 4,
  column: 0,
});

assert.strictEqual(sourceCode.getIndexFromLoc({ line: 1, column: 0 }), 0);
assert.strictEqual(sourceCode.getIndexFromLoc({ line: 1, column: 6 }), 6);
assert.strictEqual(sourceCode.getIndexFromLoc({ line: 2, column: 0 }), 13);
assert.strictEqual(
  sourceCode.getIndexFromLoc({ line: 4, column: 0 }),
  sampleText.length
);

assert.throws(() => sourceCode.getLocFromIndex(-1), RangeError);
assert.throws(
  () => sourceCode.getLocFromIndex(sampleText.length + 1),
  RangeError
);
assert.throws(
  () => sourceCode.getIndexFromLoc({ line: 0, column: 0 }),
  RangeError
);
assert.throws(
  () => sourceCode.getIndexFromLoc({ line: 10, column: 0 }),
  RangeError
);

// 4. TextSourceCodeBase getText retrieves full source text or slices by node range with offset padding
assert.strictEqual(sourceCode.getText(), sampleText);
assert.strictEqual(sourceCode.getText(astIdentifier), 'a');
assert.strictEqual(sourceCode.getText(astIdentifier, 6), 'const a');
assert.strictEqual(sourceCode.getText(astIdentifier, 0, 4), 'a = 1');

// 5. TextSourceCodeBase delegates getParent and traverses ancestors from root to parent
sourceCode.setParent(astVarDecl, rootAst);
sourceCode.setParent(astIdentifier, astVarDecl);

assert.strictEqual(sourceCode.getParent(astIdentifier), astVarDecl);
assert.strictEqual(sourceCode.getParent(astVarDecl), rootAst);
assert.deepStrictEqual(sourceCode.getAncestors(astIdentifier), [
  rootAst,
  astVarDecl,
]);
assert.throws(() => sourceCode.getAncestors(), TypeError);

// 6. TextSourceCodeBase defines traversal contract throwing on unimplemented base methods
const baseInstance = new TextSourceCodeBase({
  text: sampleText,
  ast: rootAst,
});
assert.throws(() => baseInstance.getParent(astIdentifier), /Not implemented/);
assert.throws(() => baseInstance.traverse(), /Not implemented/);

const steps = Array.from(sourceCode.traverse());
assert.ok(steps.length > 0);
assert.strictEqual(steps[0].type, 'visit');
assert.strictEqual(steps[0].target, rootAst);

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