lines-and-columns 1.2.4: map string index offset to line and column location and index for location

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: map string index offset to line and column location and index for location
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/lines-and-columns@1.2.4
Demonstrate these symbols/APIs:
  - LinesAndColumns
  - LinesAndColumns.indexForLocation
  - LinesAndColumns.locationForIndex

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:bed2e717c5c377f07394aff6caf97a4d033fc25c79f328f6715a7dc0431b2907","contract":["assert LinesAndColumns.locationForIndex maps 0-based character offset to { line, column } location","assert LinesAndColumns.locationForIndex returns null for negative offset or offset beyond string length","assert LinesAndColumns.indexForLocation maps { line, column } location to character offset","assert LinesAndColumns.indexForLocation returns null for out-of-bounds line or column","assert LinesAndColumns handles LF, CR, and CRLF line endings with round-trip location-to-index fidelity"],"goal":"map string index offset to line and column location and index for location","kind":"HOW","packages":["pkg:npm/lines-and-columns@1.2.4"],"schemaVersion":1,"symbols":["LinesAndColumns","LinesAndColumns.indexForLocation","LinesAndColumns.locationForIndex"]},"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/lines-and-columns@1.2.4"],"schemaVersion":1,"subject":"pkg:npm/lines-and-columns@1.2.4","symbols":["LinesAndColumns","LinesAndColumns.indexForLocation","LinesAndColumns.locationForIndex"],"verifierAdapter":"node-typescript@1"}

const { LinesAndColumns } = require('lines-and-columns');

/**
 * Creates a LinesAndColumns index parser instance for a given string.
 *
 * @param {string} source - The source string to index.
 * @returns {LinesAndColumns} LinesAndColumns instance.
 */
function createIndex(source) {
  return new LinesAndColumns(source);
}

/**
 * Converts a 0-based character offset into 0-based { line, column } location.
 *
 * @param {LinesAndColumns} indexer - The LinesAndColumns instance.
 * @param {number} offset - The 0-based character index.
 * @returns {{ line: number, column: number } | null} The line and column location or null if out of bounds.
 */
function getSourceLocation(indexer, offset) {
  return indexer.locationForIndex(offset);
}

/**
 * Converts a 0-based { line, column } location into a 0-based character offset.
 *
 * @param {LinesAndColumns} indexer - The LinesAndColumns instance.
 * @param {{ line: number, column: number }} location - The source location object.
 * @returns {number | null} Character index offset or null if out of bounds.
 */
function getCharacterOffset(indexer, location) {
  return indexer.indexForLocation(location);
}

module.exports = {
  LinesAndColumns,
  createIndex,
  getSourceLocation,
  getCharacterOffset,
};

{
  "name": "sample-lines-and-columns",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-lines-and-columns",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "lines-and-columns": "1.2.4"
      }
    },
    "node_modules/lines-and-columns": {
      "version": "1.2.4",
      "resolved": "https://registry.npmjs.org/lines-and-columns/-/lines-and-columns-1.2.4.tgz",
      "integrity": "sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-lines-and-columns",
  "version": "1.0.0",
  "description": "Clean-room sample demonstrating lines-and-columns mapping between offsets and line/column locations",
  "main": "index.js",
  "license": "MIT-0",
  "dependencies": {
    "lines-and-columns": "1.2.4"
  }
}

{
  "schemaVersion": 1,
  "goal": "map string index offset to line and column location and index for location",
  "kind": "HOW",
  "packages": [
    "pkg:npm/lines-and-columns@1.2.4"
  ],
  "symbols": [
    "LinesAndColumns",
    "LinesAndColumns.indexForLocation",
    "LinesAndColumns.locationForIndex"
  ]
}

import assert from 'node:assert';
import { LinesAndColumns } from 'lines-and-columns';
import {
  createIndex,
  getSourceLocation,
  getCharacterOffset,
} from '../index.js';

// 1. Basic multi-line text with LF
const sampleText = 'first line\nsecond line\nthird line';
const indexer = createIndex(sampleText);
assert(indexer instanceof LinesAndColumns, 'createIndex should return an instance of LinesAndColumns');

// 2. locationForIndex on first line (0-indexed)
const loc0 = getSourceLocation(indexer, 0);
assert.deepStrictEqual(loc0, { line: 0, column: 0 }, 'offset 0 should be line 0, column 0');

const loc5 = getSourceLocation(indexer, 5);
assert.deepStrictEqual(loc5, { line: 0, column: 5 }, 'offset 5 should be line 0, column 5');

// 3. locationForIndex on second line (offset 11 is start of 'second line' after '\n')
const loc11 = getSourceLocation(indexer, 11);
assert.deepStrictEqual(loc11, { line: 1, column: 0 }, 'offset 11 should be line 1, column 0');

const loc15 = getSourceLocation(indexer, 15);
assert.deepStrictEqual(loc15, { line: 1, column: 4 }, 'offset 15 should be line 1, column 4');

// 4. locationForIndex at end of string (length = 33)
const locEnd = getSourceLocation(indexer, sampleText.length);
assert.deepStrictEqual(locEnd, { line: 2, column: 10 }, 'offset at string length should be line 2, column 10');

// 5. locationForIndex out-of-bounds returns null
assert.strictEqual(getSourceLocation(indexer, -1), null, 'negative index must return null');
assert.strictEqual(getSourceLocation(indexer, sampleText.length + 1), null, 'index beyond length must return null');

// 6. indexForLocation valid locations
const idx0 = getCharacterOffset(indexer, { line: 0, column: 0 });
assert.strictEqual(idx0, 0, 'location { line: 0, column: 0 } must resolve to offset 0');

const idx11 = getCharacterOffset(indexer, { line: 1, column: 0 });
assert.strictEqual(idx11, 11, 'location { line: 1, column: 0 } must resolve to offset 11');

const idx15 = getCharacterOffset(indexer, { line: 1, column: 4 });
assert.strictEqual(idx15, 15, 'location { line: 1, column: 4 } must resolve to offset 15');

// 7. indexForLocation out-of-bounds returns null
assert.strictEqual(getCharacterOffset(indexer, { line: -1, column: 0 }), null, 'negative line must return null');
assert.strictEqual(getCharacterOffset(indexer, { line: 10, column: 0 }), null, 'line beyond line count must return null');
assert.strictEqual(getCharacterOffset(indexer, { line: 0, column: -1 }), null, 'negative column must return null');
assert.strictEqual(getCharacterOffset(indexer, { line: 0, column: 100 }), null, 'column beyond line length must return null');

// 8. Round-trip fidelity across text with CRLF and CR
const crlfText = 'foo\r\nbar\rbaz\nqux';
const crlfIndexer = new LinesAndColumns(crlfText);
for (let i = 0; i <= crlfText.length; i++) {
  const loc = crlfIndexer.locationForIndex(i);
  assert(loc !== null, `location for valid index ${i} must not be null`);
  const back = crlfIndexer.indexForLocation(loc);
  assert.strictEqual(back, i, `round-trip indexForLocation(locationForIndex(${i})) must match ${i}`);
}

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