@eslint/plugin-kit 0.7.3: 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 TextSourceCodeBase in 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
Demonstrate these symbols/APIs:
  - 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:51e20ef3889b026dd83079805489f7410854b0f7c16300e7fd644965bdd96f82","contract":["TextSourceCodeBase constructor initializes text and ast, lazily splitting lines with lineEndingPattern","TextSourceCodeBase converts between character indices and line-column positions using getLocFromIndex and getIndexFromLoc","TextSourceCodeBase extracts source location and character ranges from both ESTree-style and position-style AST nodes","TextSourceCodeBase.prototype.getText retrieves the entire text or slices around an AST node with optional beforeCount and afterCount","TextSourceCodeBase.prototype.getAncestors traverses parent links from root to parent node and throws TypeError when node argument is missing","TextSourceCodeBase throws RangeError on out-of-bounds coordinates and default traverse and getParent throw Not implemented Error"],"goal":"verify TextSourceCodeBase in pkg:npm/%40eslint/plugin-kit@0.7.3","kind":"HOW","packages":["pkg:npm/%40eslint/plugin-kit@0.7.3"],"schemaVersion":1,"symbols":["TextSourceCodeBase"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","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","symbols":["TextSourceCodeBase"],"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.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",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@eslint/plugin-kit": "0.7.3"
  }
}

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

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

/**
 * Concrete implementation of TextSourceCodeBase with parent-tracking capabilities.
 */
export class StructuredSourceCode extends TextSourceCodeBase {
  #parents = new Map();

  /**
   * Records the parent node for a child node.
   * @param {object} child The child AST node.
   * @param {object} parent The parent AST node.
   */
  setParent(child, parent) {
    this.#parents.set(child, parent);
  }

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

export { TextSourceCodeBase };
export default StructuredSourceCode;

import assert from 'node:assert/strict';
import { TextSourceCodeBase, StructuredSourceCode } from '../src/index.mjs';

// 1. TextSourceCodeBase constructor initializes text and ast, lazily splitting lines with lineEndingPattern
{
  const text = 'line one\r\nline two\r\nline three';
  const ast = {
    type: 'Program',
    loc: {
      start: { line: 1, column: 0 },
      end: { line: 3, column: 10 },
    },
    range: [0, text.length],
  };

  const sourceCode = new TextSourceCodeBase({
    text,
    ast,
    lineEndingPattern: /\r\n/u,
  });

  assert.equal(sourceCode.text, text);
  assert.equal(sourceCode.ast, ast);
  assert.equal(sourceCode.lines.length, 3);
  assert.equal(sourceCode.lines[0], 'line one');
  assert.equal(sourceCode.lines[1], 'line two');
  assert.equal(sourceCode.lines[2], 'line three');
  assert.ok(Object.isFrozen(sourceCode.lines));
}

// 2. TextSourceCodeBase converts between character indices and line-column positions using getLocFromIndex and getIndexFromLoc
{
  const text = 'alpha\nbeta\ngamma';
  const ast = {
    type: 'Program',
    loc: {
      start: { line: 1, column: 0 },
      end: { line: 3, column: 5 },
    },
    range: [0, text.length],
  };

  const sourceCode = new TextSourceCodeBase({ text, ast });

  // Index 0 -> line 1, col 0
  assert.deepEqual(sourceCode.getLocFromIndex(0), { line: 1, column: 0 });
  // Index 6 ('b') -> line 2, col 0
  assert.deepEqual(sourceCode.getLocFromIndex(6), { line: 2, column: 0 });
  // Index 8 ('t') -> line 2, col 2
  assert.deepEqual(sourceCode.getLocFromIndex(8), { line: 2, column: 2 });
  // Index text.length (16) -> line 3, col 5
  assert.deepEqual(sourceCode.getLocFromIndex(text.length), { line: 3, column: 5 });

  // Reverse mapping via getIndexFromLoc
  assert.equal(sourceCode.getIndexFromLoc({ line: 1, column: 0 }), 0);
  assert.equal(sourceCode.getIndexFromLoc({ line: 2, column: 0 }), 6);
  assert.equal(sourceCode.getIndexFromLoc({ line: 2, column: 2 }), 8);
  assert.equal(sourceCode.getIndexFromLoc({ line: 3, column: 5 }), text.length);
}

// 3. TextSourceCodeBase extracts source location and character ranges from both ESTree-style and position-style AST nodes
{
  const estreeNode = {
    type: 'Identifier',
    name: 'foo',
    loc: {
      start: { line: 1, column: 0 },
      end: { line: 1, column: 3 },
    },
    range: [0, 3],
  };

  const posNode = {
    type: 'MarkdownHeading',
    position: {
      start: { line: 2, column: 1, offset: 4 },
      end: { line: 2, column: 10, offset: 13 },
    },
  };

  const rootAst = {
    type: 'Root',
    loc: {
      start: { line: 1, column: 0 },
      end: { line: 2, column: 10 },
    },
    range: [0, 13],
  };

  const sourceCode = new TextSourceCodeBase({
    text: 'foo\n# Heading',
    ast: rootAst,
  });

  assert.deepEqual(sourceCode.getLoc(estreeNode), estreeNode.loc);
  assert.deepEqual(sourceCode.getRange(estreeNode), [0, 3]);

  assert.deepEqual(sourceCode.getLoc(posNode), posNode.position);
  assert.deepEqual(sourceCode.getRange(posNode), [4, 13]);

  assert.throws(
    () => sourceCode.getLoc({ type: 'BareNode' }),
    {
      name: 'Error',
      message: 'Custom getLoc() method must be implemented in the subclass.',
    },
  );
  assert.throws(
    () => sourceCode.getRange({ type: 'BareNode' }),
    {
      name: 'Error',
      message: 'Custom getRange() method must be implemented in the subclass.',
    },
  );
}

// 4. TextSourceCodeBase.prototype.getText retrieves the entire text or slices around an AST node with optional beforeCount and afterCount
{
  const text = 'const message = "hello";';
  const node = {
    type: 'Literal',
    value: 'hello',
    range: [16, 23],
    loc: {
      start: { line: 1, column: 16 },
      end: { line: 1, column: 23 },
    },
  };
  const ast = {
    type: 'Program',
    range: [0, text.length],
    loc: {
      start: { line: 1, column: 0 },
      end: { line: 1, column: text.length },
    },
  };

  const sourceCode = new TextSourceCodeBase({ text, ast });

  assert.equal(sourceCode.getText(), text);
  assert.equal(sourceCode.getText(node), '"hello"');
  assert.equal(sourceCode.getText(node, 2), '= "hello"');
  assert.equal(sourceCode.getText(node, 2, 1), '= "hello";');
}

// 5. TextSourceCodeBase.prototype.getAncestors traverses parent links from root to parent node and throws TypeError when node argument is missing
{
  const root = {
    type: 'Program',
    loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 20 } },
  };
  const stmt = {
    type: 'ExpressionStatement',
    loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 20 } },
  };
  const call = {
    type: 'CallExpression',
    loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 19 } },
  };
  const callee = {
    type: 'Identifier',
    name: 'fn',
    loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 2 } },
  };

  const sourceCode = new StructuredSourceCode({
    text: 'fn();',
    ast: root,
  });

  sourceCode.setParent(callee, call);
  sourceCode.setParent(call, stmt);
  sourceCode.setParent(stmt, root);

  assert.throws(
    () => sourceCode.getAncestors(),
    {
      name: 'TypeError',
      message: 'Missing required argument: node.',
    },
  );

  const ancestors = sourceCode.getAncestors(callee);
  assert.deepEqual(ancestors, [root, stmt, call]);
  assert.equal(sourceCode.getParent(callee), call);
}

// 6. TextSourceCodeBase throws RangeError on out-of-bounds coordinates and default traverse and getParent throw Not implemented Error
{
  const text = 'foo bar';
  const ast = {
    type: 'Program',
    loc: {
      start: { line: 1, column: 0 },
      end: { line: 1, column: 7 },
    },
    range: [0, 7],
  };

  const base = new TextSourceCodeBase({ text, ast });

  assert.throws(
    () => base.getParent(ast),
    {
      name: 'Error',
      message: 'Not implemented.',
    },
  );

  assert.throws(
    () => base.traverse(),
    {
      name: 'Error',
      message: 'Not implemented.',
    },
  );

  assert.throws(() => base.getLocFromIndex(-1), RangeError);
  assert.throws(() => base.getLocFromIndex(100), RangeError);
  assert.throws(() => base.getLocFromIndex('abc'), TypeError);

  assert.throws(() => base.getIndexFromLoc({ line: 0, column: 0 }), RangeError);
  assert.throws(() => base.getIndexFromLoc({ line: 2, column: 0 }), RangeError);
  assert.throws(() => base.getIndexFromLoc({ line: 1, column: 99 }), RangeError);
  assert.throws(() => base.getIndexFromLoc(null), TypeError);
}

console.log('All TextSourceCodeBase contract assertions passed.');