kibi-cli 0.19.0 → 2.0.0

package/dist/extractors/symbol-coordinates.d.ts

@@ -1,4 +1,10 @@
 import type { ManifestSymbolRecord } from "./manifest.js";
+/**
+ * Format version of the generated coordinate artifact. Version 2 binds every
+ * record to the extraction identity that produced it so stale coordinates can
+ * never silently overlay a changed symbol.
+ */
+export declare const SYMBOL_COORDINATES_FORMAT_VERSION = 2;
 export interface SymbolCoordinatesRecord {
     sourceFile: string;
     sourceLine: number;
@@ -6,10 +12,82 @@ export interface SymbolCoordinatesRecord {
     sourceEndLine: number;
     sourceEndColumn: number;
 }
+/** A generated record bound to the extraction identity that produced it. */
+export interface BoundSymbolCoordinatesRecord extends SymbolCoordinatesRecord {
+    readonly identityHash: string;
+    readonly sourceHash: string;
+}
+export type CoordinateArtifactRecord = SymbolCoordinatesRecord | BoundSymbolCoordinatesRecord;
 export interface SymbolCoordinatesArtifact {
-    coordinates: Record<string, SymbolCoordinatesRecord>;
+    coordinates: Record<string, CoordinateArtifactRecord>;
+}
+export interface CoordinateExtractionIdentity {
+    readonly id: string;
+    readonly title?: string;
+    readonly sourceFile?: string;
+    readonly granularity_reason?: string;
+}
+export interface SymbolCoordinateWriteEntry extends SymbolCoordinatesRecord {
+    readonly identityHash?: string;
+    readonly sourceHash?: string;
+}
+export type ParsedCoordinateArtifact = {
+    readonly status: "parsed";
+    readonly formatVersion: typeof SYMBOL_COORDINATES_FORMAT_VERSION;
+    readonly coordinates: Readonly<Record<string, BoundSymbolCoordinatesRecord>>;
+} | {
+    readonly status: "legacy";
+    readonly coordinates: Readonly<Record<string, SymbolCoordinatesRecord>>;
+} | {
+    readonly status: "invalid";
+    readonly reason: string;
+};
+export declare class CoordinateArtifactError extends Error {
+    readonly name = "CoordinateArtifactError";
 }
+/** Deterministic canonical identity string for a symbol extraction state. */
+export declare function coordinateIdentityKey(identity: CoordinateExtractionIdentity): string;
+/** Stable hash binding a generated coordinate record to its extraction identity. */
+export declare function coordinateIdentityHash(identity: CoordinateExtractionIdentity): string;
+/** Stable hash of the exact source text used to generate a coordinate span. */
+export declare function coordinateSourceHash(sourceText: string): string;
+/** Select a stable coarse anchor, preferring a title match over the whole file. */
+export declare function coarseCoordinateSpan(sourceFile: string, title: string, content: string): SymbolCoordinatesRecord;
+/**
+ * Validate a coordinate span against the same rules requirement proof enforces:
+ * nonempty source file, sourceLine >= 1, columns >= 0, endLine >= sourceLine.
+ */
+export declare function isValidCoordinateSpan(value: unknown): value is SymbolCoordinatesRecord;
+/**
+ * Strictly parse a generated coordinate artifact. Records failing span
+ * validation make the whole artifact invalid; consumers must fail closed
+ * instead of silently dropping evidence.
+ */
+export declare function parseCoordinateArtifact(content: string): ParsedCoordinateArtifact;
+/**
+ * Serialize the generated artifact as a version 2 document. Every record is
+ * bound to both its manifest identity and exact source content.
+ * Key order is deterministic without relying on YAML sortKeys so the
+ * human-readable header stays first.
+ */
+export declare function writeCoordinateArtifact(entries: Record<string, SymbolCoordinateWriteEntry>): string;
+/** Serialize a legacy artifact without introducing v2 bindings or metadata. */
+export declare function writeLegacyCoordinateArtifact(entries: Record<string, SymbolCoordinatesRecord>): string;
+/**
+ * Reader kept for diff/traceability surfaces. Legacy records remain available
+ * as spans while v2 records retain their bindings.
+ */
 export declare function readCoordinateArtifact(content: string): SymbolCoordinatesArtifact;
-export declare function writeCoordinateArtifact(coordinates: Record<string, SymbolCoordinatesRecord>): string;
-export declare function mergeCoordinatesWithManifest(symbolRecords: ManifestSymbolRecord[], coordinateArtifact: SymbolCoordinatesArtifact | null): ManifestSymbolRecord[];
+/**
+ * Overlay generated coordinates onto authored manifest records.
+ *
+ * Generated fields are always stripped first so stale spans can never reach
+ * compiled state. Bound v2 records apply only when both their identity hash
+ * and exact source-content hash match the current manifest and source. Legacy
+ * records and inline coordinates are accepted only after live declaration
+ * validation.
+ */
+export declare function mergeCoordinatesWithManifest(symbolRecords: ManifestSymbolRecord[], coordinateArtifact: ParsedCoordinateArtifact | SymbolCoordinatesArtifact | null, options?: {
+    readonly resolveSourceText?: (sourceFile: string) => string | null;
+}): ManifestSymbolRecord[];
 //# sourceMappingURL=symbol-coordinates.d.ts.map

package/dist/extractors/symbol-coordinates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symbol-coordinates.d.ts","sourceRoot":"","sources":["../../src/extractors/symbol-coordinates.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE1D,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;CACtD;AAiED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,GACd,yBAAyB,CAkB3B;AAGD,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,GACnD,MAAM,CAUR;AAGD,wBAAgB,4BAA4B,CAC1C,aAAa,EAAE,oBAAoB,EAAE,EACrC,kBAAkB,EAAE,yBAAyB,GAAG,IAAI,GACnD,oBAAoB,EAAE,CAqBxB"}
+{"version":3,"file":"symbol-coordinates.d.ts","sourceRoot":"","sources":["../../src/extractors/symbol-coordinates.ts"],"names":[],"mappings":"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"}

package/dist/extractors/symbol-coordinates.js

@@ -1,4 +1,18 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
 import { dump as dumpYAML, load as parseYAML } from "js-yaml";
+/**
+ * Format version of the generated coordinate artifact. Version 2 binds every
+ * record to the extraction identity that produced it so stale coordinates can
+ * never silently overlay a changed symbol.
+ */
+// implements REQ-generated-coordinate-persistence
+export const SYMBOL_COORDINATES_FORMAT_VERSION = 2;
+// implements REQ-generated-coordinate-persistence
+export class CoordinateArtifactError extends Error {
+    name = "CoordinateArtifactError";
+}
 const SYMBOL_COORDINATES_COMMENT_BLOCK = `# symbol-coordinates.yaml
 # GENERATED coordinate artifact — do not edit manually.
 # Run \`kibi sync --refresh-symbol-coordinates\` to refresh.
@@ -6,78 +20,402 @@ const SYMBOL_COORDINATES_COMMENT_BLOCK = `# symbol-coordinates.yaml
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function normalizeCoordinateRecord(value) {
-    if (!isRecord(value)) {
-        return null;
+function canonicalIdentityValue(value) {
+    return typeof value === "string" ? value : "";
+}
+/** Deterministic canonical identity string for a symbol extraction state. */
+// implements REQ-generated-coordinate-persistence
+export function coordinateIdentityKey(identity) {
+    return [
+        identity.id,
+        canonicalIdentityValue(identity.title),
+        canonicalIdentityValue(identity.sourceFile),
+        canonicalIdentityValue(identity.granularity_reason),
+    ].join("\u0000");
+}
+/** Stable hash binding a generated coordinate record to its extraction identity. */
+// implements REQ-generated-coordinate-persistence
+export function coordinateIdentityHash(identity) {
+    return createHash("sha256")
+        .update(coordinateIdentityKey(identity))
+        .digest("hex");
+}
+/** Stable hash of the exact source text used to generate a coordinate span. */
+// implements REQ-generated-coordinate-persistence
+export function coordinateSourceHash(sourceText) {
+    return createHash("sha256").update(sourceText).digest("hex");
+}
+/** Select a stable coarse anchor, preferring a title match over the whole file. */
+// implements REQ-generated-coordinate-persistence
+export function coarseCoordinateSpan(sourceFile, title, content) {
+    if (title.length > 0) {
+        const escaped = title.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const pattern = new RegExp(`\\b${escaped}\\b`);
+        const lines = content.split(/\r?\n/);
+        for (let index = 0; index < lines.length; index++) {
+            const line = lines[index];
+            if (line === undefined)
+                continue;
+            const match = pattern.exec(line);
+            if (!match || match.index < 0)
+                continue;
+            return {
+                sourceFile,
+                sourceLine: index + 1,
+                sourceColumn: match.index,
+                sourceEndLine: index + 1,
+                sourceEndColumn: match.index + title.length,
+            };
+        }
     }
-    const { sourceColumn, sourceEndColumn, sourceEndLine, sourceFile, sourceLine, } = value;
-    if (typeof sourceFile !== "string" ||
-        typeof sourceLine !== "number" ||
-        typeof sourceColumn !== "number" ||
-        typeof sourceEndLine !== "number" ||
-        typeof sourceEndColumn !== "number") {
+    const lines = content.split(/\r?\n/);
+    const lastLine = lines[lines.length - 1] ?? "";
+    return {
+        sourceFile,
+        sourceLine: 1,
+        sourceColumn: 0,
+        sourceEndLine: Math.max(1, lines.length),
+        sourceEndColumn: lastLine.length,
+    };
+}
+function isSha256Hash(value) {
+    return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+/**
+ * Validate a coordinate span against the same rules requirement proof enforces:
+ * nonempty source file, sourceLine >= 1, columns >= 0, endLine >= sourceLine.
+ */
+// implements REQ-generated-coordinate-persistence
+export function isValidCoordinateSpan(value) {
+    if (!isRecord(value))
+        return false;
+    const { sourceFile, sourceLine, sourceColumn, sourceEndLine, sourceEndColumn, } = value;
+    return (typeof sourceFile === "string" &&
+        sourceFile.length > 0 &&
+        typeof sourceLine === "number" &&
+        Number.isInteger(sourceLine) &&
+        sourceLine >= 1 &&
+        typeof sourceColumn === "number" &&
+        Number.isInteger(sourceColumn) &&
+        sourceColumn >= 0 &&
+        typeof sourceEndLine === "number" &&
+        Number.isInteger(sourceEndLine) &&
+        sourceEndLine >= sourceLine &&
+        typeof sourceEndColumn === "number" &&
+        Number.isInteger(sourceEndColumn) &&
+        sourceEndColumn >= 0);
+}
+function normalizeRawEntry(value) {
+    if (!isRecord(value))
+        return null;
+    const { identityHash, sourceHash, ...rest } = value;
+    if (!isValidCoordinateSpan(rest))
+        return null;
+    if (("identityHash" in value && !isSha256Hash(identityHash)) ||
+        ("sourceHash" in value && !isSha256Hash(sourceHash))) {
         return null;
     }
     return {
-        sourceFile,
-        sourceLine,
-        sourceColumn,
-        sourceEndLine,
-        sourceEndColumn,
+        span: {
+            sourceFile: rest.sourceFile,
+            sourceLine: rest.sourceLine,
+            sourceColumn: rest.sourceColumn,
+            sourceEndLine: rest.sourceEndLine,
+            sourceEndColumn: rest.sourceEndColumn,
+        },
+        ...(typeof identityHash === "string" && identityHash.length > 0
+            ? { identityHash }
+            : {}),
+        ...(typeof sourceHash === "string" && sourceHash.length > 0
+            ? { sourceHash }
+            : {}),
     };
 }
-function sortCoordinates(coordinates) {
-    const sortedCoordinates = {};
-    for (const symbolId of Object.keys(coordinates).sort((left, right) => left.localeCompare(right))) {
-        const record = normalizeCoordinateRecord(coordinates[symbolId]);
-        if (!record) {
-            continue;
+/**
+ * Strictly parse a generated coordinate artifact. Records failing span
+ * validation make the whole artifact invalid; consumers must fail closed
+ * instead of silently dropping evidence.
+ */
+// implements REQ-generated-coordinate-persistence
+export function parseCoordinateArtifact(content) {
+    let parsed;
+    try {
+        parsed = parseYAML(content);
+    }
+    catch (error) {
+        return {
+            status: "invalid",
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+    if (parsed === null || parsed === undefined) {
+        return { status: "legacy", coordinates: {} };
+    }
+    if (!isRecord(parsed)) {
+        return { status: "invalid", reason: "artifact root is not a mapping" };
+    }
+    const rawCoordinates = parsed.coordinates ?? {};
+    if (!isRecord(rawCoordinates)) {
+        return { status: "invalid", reason: "coordinates is not a mapping" };
+    }
+    const declaredVersion = parsed.version;
+    const entries = {};
+    for (const [id, value] of Object.entries(rawCoordinates)) {
+        const entry = normalizeRawEntry(value);
+        if (entry === null) {
+            return {
+                status: "invalid",
+                reason: `record '${id}' has an invalid coordinate span`,
+            };
         }
-        sortedCoordinates[symbolId] = record;
+        entries[id] = entry;
     }
-    return sortedCoordinates;
-}
-// implements REQ-core-extractors
-export function readCoordinateArtifact(content) {
-    const parsed = parseYAML(content);
-    if (!isRecord(parsed) || !isRecord(parsed.coordinates)) {
-        return { coordinates: {} };
+    if (declaredVersion === undefined) {
+        const legacy = {};
+        for (const [id, entry] of Object.entries(entries)) {
+            legacy[id] = entry.span;
+        }
+        return { status: "legacy", coordinates: legacy };
     }
-    const coordinates = {};
-    for (const [symbolId, record] of Object.entries(parsed.coordinates)) {
-        const normalizedRecord = normalizeCoordinateRecord(record);
-        if (!normalizedRecord) {
-            continue;
+    if (declaredVersion !== SYMBOL_COORDINATES_FORMAT_VERSION) {
+        return {
+            status: "invalid",
+            reason: `unsupported or missing artifact version: ${String(declaredVersion)}`,
+        };
+    }
+    if (declaredVersion === SYMBOL_COORDINATES_FORMAT_VERSION) {
+        const bound = {};
+        for (const [id, entry] of Object.entries(entries)) {
+            const identityHash = entry.identityHash;
+            const sourceHash = entry.sourceHash;
+            if (identityHash === undefined || sourceHash === undefined) {
+                return {
+                    status: "invalid",
+                    reason: `record '${id}' is missing its identity or source binding in a versioned artifact`,
+                };
+            }
+            bound[id] = { ...entry.span, identityHash, sourceHash };
         }
-        coordinates[symbolId] = normalizedRecord;
+        return {
+            status: "parsed",
+            formatVersion: SYMBOL_COORDINATES_FORMAT_VERSION,
+            coordinates: bound,
+        };
     }
-    return { coordinates };
+    return { status: "invalid", reason: "unreachable artifact parser state" };
 }
-// implements REQ-core-extractors
-export function writeCoordinateArtifact(coordinates) {
+/**
+ * Serialize the generated artifact as a version 2 document. Every record is
+ * bound to both its manifest identity and exact source content.
+ * Key order is deterministic without relying on YAML sortKeys so the
+ * human-readable header stays first.
+ */
+// implements REQ-generated-coordinate-persistence
+export function writeCoordinateArtifact(entries) {
+    const coordinates = {};
+    for (const id of Object.keys(entries).sort((left, right) => left.localeCompare(right))) {
+        const entry = entries[id];
+        if (entry === undefined || !isValidCoordinateSpan(entry)) {
+            throw new CoordinateArtifactError(`refusing to publish an invalid or missing coordinate span${id === undefined ? "" : ` for ${id}`}`);
+        }
+        if (!isSha256Hash(entry.identityHash) || !isSha256Hash(entry.sourceHash)) {
+            throw new CoordinateArtifactError(`refusing to publish an invalid or missing identityHash/sourceHash binding for ${id}`);
+        }
+        coordinates[id] = {
+            identityHash: entry.identityHash,
+            sourceHash: entry.sourceHash,
+            sourceColumn: entry.sourceColumn,
+            sourceEndColumn: entry.sourceEndColumn,
+            sourceEndLine: entry.sourceEndLine,
+            sourceFile: entry.sourceFile,
+            sourceLine: entry.sourceLine,
+        };
+    }
     const artifact = {
-        coordinates: sortCoordinates(coordinates),
+        version: SYMBOL_COORDINATES_FORMAT_VERSION,
+        coordinates,
     };
     return `${SYMBOL_COORDINATES_COMMENT_BLOCK}${dumpYAML(artifact, {
         lineWidth: -1,
         noRefs: true,
-        sortKeys: true,
     })}`;
 }
-// implements REQ-core-extractors
-export function mergeCoordinatesWithManifest(symbolRecords, coordinateArtifact) {
-    const coordinates = coordinateArtifact?.coordinates ?? {};
+/** Serialize a legacy artifact without introducing v2 bindings or metadata. */
+// implements REQ-generated-coordinate-persistence
+export function writeLegacyCoordinateArtifact(entries) {
+    const coordinates = {};
+    for (const id of Object.keys(entries).sort((left, right) => left.localeCompare(right))) {
+        const entry = entries[id];
+        if (entry === undefined || !isValidCoordinateSpan(entry)) {
+            throw new CoordinateArtifactError(`refusing to publish an invalid or missing legacy coordinate span for ${id}`);
+        }
+        coordinates[id] = {
+            sourceColumn: entry.sourceColumn,
+            sourceEndColumn: entry.sourceEndColumn,
+            sourceEndLine: entry.sourceEndLine,
+            sourceFile: entry.sourceFile,
+            sourceLine: entry.sourceLine,
+        };
+    }
+    return `${SYMBOL_COORDINATES_COMMENT_BLOCK}${dumpYAML({ coordinates }, { lineWidth: -1, noRefs: true })}`;
+}
+/**
+ * Reader kept for diff/traceability surfaces. Legacy records remain available
+ * as spans while v2 records retain their bindings.
+ */
+// implements REQ-generated-coordinate-persistence
+export function readCoordinateArtifact(content) {
+    const parsed = parseCoordinateArtifact(content);
+    if (parsed.status === "invalid") {
+        throw new CoordinateArtifactError(parsed.reason);
+    }
+    const coordinates = {};
+    for (const [id, record] of Object.entries(parsed.coordinates)) {
+        coordinates[id] = record;
+    }
+    return { coordinates };
+}
+const GENERATED_MANIFEST_FIELDS = [
+    "sourceLine",
+    "sourceColumn",
+    "sourceEndLine",
+    "sourceEndColumn",
+    "coordinatesGeneratedAt",
+];
+function stripGeneratedFields(record) {
+    const next = { ...record };
+    for (const field of GENERATED_MANIFEST_FIELDS) {
+        delete next[field];
+    }
+    return next;
+}
+function manifestSourceFile(record) {
+    if (typeof record.sourceFile === "string" && record.sourceFile.length > 0) {
+        return record.sourceFile;
+    }
+    if (typeof record.source === "string" && record.source.length > 0) {
+        return record.source;
+    }
+    return undefined;
+}
+function defaultResolveSourceText(sourceFile) {
+    const absolute = path.isAbsolute(sourceFile)
+        ? sourceFile
+        : path.resolve(process.cwd(), sourceFile);
+    if (!existsSync(absolute))
+        return null;
+    try {
+        const content = readFileSync(absolute, "utf8");
+        return typeof content === "string" ? content : null;
+    }
+    catch {
+        return null;
+    }
+}
+function overlaySpan(stripped, span) {
+    return {
+        ...stripped,
+        sourceFile: span.sourceFile,
+        sourceLine: span.sourceLine,
+        sourceColumn: span.sourceColumn,
+        sourceEndLine: span.sourceEndLine,
+        sourceEndColumn: span.sourceEndColumn,
+    };
+}
+/**
+ * Overlay generated coordinates onto authored manifest records.
+ *
+ * Generated fields are always stripped first so stale spans can never reach
+ * compiled state. Bound v2 records apply only when both their identity hash
+ * and exact source-content hash match the current manifest and source. Legacy
+ * records and inline coordinates are accepted only after live declaration
+ * validation.
+ */
+export function mergeCoordinatesWithManifest(symbolRecords, coordinateArtifact, options = {}) {
+    if (coordinateArtifact !== null && "status" in coordinateArtifact) {
+        if (coordinateArtifact.status === "invalid") {
+            throw new CoordinateArtifactError(coordinateArtifact.reason);
+        }
+    }
+    const resolveSourceText = options.resolveSourceText ?? defaultResolveSourceText;
+    const rawCoordinates = coordinateArtifact?.coordinates ?? {};
     return symbolRecords.map((symbolRecord) => {
-        const legacyRecord = { ...symbolRecord };
+        const stripped = stripGeneratedFields(symbolRecord);
         const symbolId = typeof symbolRecord.id === "string" ? symbolRecord.id : undefined;
-        const coordinateRecord = symbolId ? coordinates[symbolId] : undefined;
-        if (!coordinateRecord) {
-            return legacyRecord;
+        if (symbolId === undefined)
+            return stripped;
+        const entry = rawCoordinates[symbolId];
+        const candidate = entry ??
+            (coordinateArtifact === null ? inlineSpanOf(symbolRecord) : undefined);
+        if (candidate === undefined)
+            return stripped;
+        const identityHash = candidate.identityHash;
+        const sourceHash = candidate.sourceHash;
+        if (identityHash !== undefined || sourceHash !== undefined) {
+            const recordSourceFile = manifestSourceFile(symbolRecord);
+            const expected = coordinateIdentityHash({
+                id: symbolId,
+                ...(symbolRecord.title === undefined
+                    ? {}
+                    : { title: symbolRecord.title }),
+                ...(recordSourceFile === undefined
+                    ? {}
+                    : { sourceFile: recordSourceFile }),
+                ...(typeof symbolRecord.granularity_reason === "string"
+                    ? { granularity_reason: symbolRecord.granularity_reason }
+                    : {}),
+            });
+            if (!isSha256Hash(identityHash) ||
+                !isSha256Hash(sourceHash) ||
+                identityHash !== expected ||
+                !isValidCoordinateSpan(candidate) ||
+                recordSourceFile === undefined ||
+                candidate.sourceFile !== recordSourceFile) {
+                return stripped;
+            }
+            const sourceText = resolveSourceText(candidate.sourceFile);
+            if (sourceText === null ||
+                coordinateSourceHash(sourceText) !== sourceHash) {
+                return stripped;
+            }
+            return overlaySpan(stripped, candidate);
         }
-        const { coordinatesGeneratedAt: _coordinatesGeneratedAt, ...mergedRecord } = legacyRecord;
-        return {
-            ...mergedRecord,
-            ...coordinateRecord,
-        };
+        if (!isValidCoordinateSpan(candidate))
+            return stripped;
+        if (!legacyRecordMatchesCurrentExtraction(symbolRecord, candidate, resolveSourceText)) {
+            return stripped;
+        }
+        return overlaySpan(stripped, candidate);
     });
 }
+function legacyRecordMatchesCurrentExtraction(record, entry, resolveSourceText) {
+    const sourceFile = manifestSourceFile(record);
+    if (sourceFile === undefined || entry.sourceFile !== sourceFile)
+        return false;
+    const title = typeof record.title === "string" ? record.title : "";
+    const declarationName = title.slice(title.lastIndexOf(".") + 1);
+    if (declarationName.length === 0)
+        return false;
+    const content = resolveSourceText(entry.sourceFile);
+    if (content === null)
+        return false;
+    const lines = content.split(/\r?\n/);
+    const lineText = lines[entry.sourceLine - 1];
+    if (lineText === undefined)
+        return false;
+    if (entry.sourceColumn > lineText.length - declarationName.length) {
+        return false;
+    }
+    return (lineText.slice(entry.sourceColumn, entry.sourceColumn + declarationName.length) === declarationName);
+}
+function inlineSpanOf(record) {
+    const sourceFile = manifestSourceFile(record) ?? "";
+    const span = {
+        sourceFile,
+        sourceLine: typeof record.sourceLine === "number" ? record.sourceLine : -1,
+        sourceColumn: typeof record.sourceColumn === "number" ? record.sourceColumn : -1,
+        sourceEndLine: typeof record.sourceEndLine === "number" ? record.sourceEndLine : -1,
+        sourceEndColumn: typeof record.sourceEndColumn === "number" ? record.sourceEndColumn : -1,
+    };
+    return isValidCoordinateSpan(span) ? span : undefined;
+}

package/dist/extractors/symbols-coordinator.js

@@ -77,7 +77,7 @@ export function analyzeSourceText(filePathOrEntries, contentOrWorkspaceRoot, opt
 export async function enrichSymbolCoordinates(entries, workspaceRoot, deps) {
     // implements REQ-vscode-traceability
     const enrichTsCoordinates = deps?.enrichTsCoordinates ?? enrichSymbolCoordinatesWithTsMorph;
-    const output = entries.map((entry) => ({ ...entry }));
+    const output = entries.map((entry) => withoutGeneratedCoordinates(entry));
     const tsIndices = [];
     const tsEntries = [];
     for (let index = 0; index < output.length; index++) {
@@ -107,6 +107,16 @@ export async function enrichSymbolCoordinates(entries, workspaceRoot, deps) {
     }
     return output;
 }
+function withoutGeneratedCoordinates(entry) {
+    const generatedFields = new Set([
+        "sourceLine",
+        "sourceColumn",
+        "sourceEndLine",
+        "sourceEndColumn",
+        "coordinatesGeneratedAt",
+    ]);
+    return Object.fromEntries(Object.entries(entry).filter(([field]) => !generatedFields.has(field)));
+}
 function enrichWithRegexHeuristic(entry, absolutePath) {
     try {
         const content = fs.readFileSync(absolutePath, "utf8");

package/dist/extractors/symbols-ts.d.ts

@@ -20,4 +20,5 @@ export interface ManifestSymbolEntry {
 }
 export declare function createTsMorphSourceAnalysisProvider(): SourceAnalysisProvider;
 export declare function enrichSymbolCoordinatesWithTsMorph(entries: ManifestSymbolEntry[], workspaceRoot: string): Promise<ManifestSymbolEntry[]>;
+export declare function onlyCandidate<T>(candidates: readonly T[]): T | undefined;
 //# sourceMappingURL=symbols-ts.d.ts.map

package/dist/extractors/symbols-ts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symbols-ts.d.ts","sourceRoot":"","sources":["../../src/extractors/symbols-ts.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EACV,sBAAsB,EAIvB,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAcD,wBAAgB,mCAAmC,IAAI,sBAAsB,CA+B5E;AAED,wBAAsB,kCAAkC,CACtD,OAAO,EAAE,mBAAmB,EAAE,EAC9B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAuEhC"}
+{"version":3,"file":"symbols-ts.d.ts","sourceRoot":"","sources":["../../src/extractors/symbols-ts.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EACV,sBAAsB,EAIvB,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAcD,wBAAgB,mCAAmC,IAAI,sBAAsB,CA+B5E;AAED,wBAAsB,kCAAkC,CACtD,OAAO,EAAE,mBAAmB,EAAE,EAC9B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAuEhC;AAgUD,wBAAgB,aAAa,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,GAAG,SAAS,CAGxE"}