@weftlet/toolkit 0.6.1 → 0.7.1

package/dist/application/saved-code-coverage.js

@@ -0,0 +1,20 @@
+import { renderCodeCoverage } from '../graph/code-coverage-renderer.js';
+import { inspectSavedEvidence } from './saved-evidence.js';
+export class SavedCodeCoverageService {
+    queries;
+    repository;
+    configurationDigest;
+    expectedExtractors;
+    constructor(queries, repository, configurationDigest, expectedExtractors) {
+        this.queries = queries;
+        this.repository = repository;
+        this.configurationDigest = configurationDigest;
+        this.expectedExtractors = expectedExtractors;
+    }
+    async coverage(request) {
+        const report = await this.queries.coverage(request);
+        const evidenceState = await inspectSavedEvidence(report.snapshot, this.repository, this.configurationDigest, this.expectedExtractors);
+        const result = { ...report, evidenceState };
+        return { ...result, markdown: renderCodeCoverage(result) };
+    }
+}

package/dist/application/saved-compatibility.d.ts

@@ -0,0 +1,38 @@
+import type { ContractCompatibilityRequest, ContractCompatibilityService } from '@weftlet/core';
+import type { GitRepository } from '../repository/git.js';
+export declare class SavedContractCompatibilityService implements ContractCompatibilityService {
+    private readonly queries;
+    private readonly repository;
+    private readonly configurationDigest;
+    private readonly expectedExtractors?;
+    constructor(queries: ContractCompatibilityService, repository: GitRepository, configurationDigest: string, expectedExtractors?: Readonly<Record<string, string>> | undefined);
+    assess(request: ContractCompatibilityRequest): Promise<{
+        markdown: string;
+        evidenceState: {
+            readonly currentCommit?: string;
+            readonly excludedWorkingChanges: readonly string[];
+            readonly capturedWorkingChanges?: readonly string[];
+            readonly changedSinceCapture?: readonly string[];
+            readonly overlayFreshness?: "current" | "stale" | "unknown";
+            readonly stale: boolean;
+            readonly configurationMatches: boolean;
+            readonly extractionCompatible?: boolean;
+            readonly incompatibleExtractors?: readonly string[];
+            readonly eligibleForCurrentDiffValidation: false;
+        };
+        snapshot: import("@weftlet/core").ContextPack["snapshot"];
+        selection: ContractCompatibilityRequest;
+        facts: readonly import("@weftlet/core").GraphFact[];
+        coverage: import("@weftlet/core").ContextPack["coverage"];
+        assessment: import("@weftlet/core").ContractCompatibilityAssessment;
+        context: {
+            readonly contractNodeIds: readonly string[];
+            readonly endpointNodeIds: readonly string[];
+            readonly otherIncidentFacts: number;
+            readonly competingFactIds: readonly string[];
+            readonly competingFacts: number;
+            readonly omittedCompetingFacts: number;
+        };
+        diagnostics: import("@weftlet/core").DiagnosticReport;
+    }>;
+}

package/dist/application/saved-compatibility.js

@@ -0,0 +1,20 @@
+import { renderContractCompatibility } from '../graph/compatibility-renderer.js';
+import { inspectSavedEvidence } from './saved-evidence.js';
+export class SavedContractCompatibilityService {
+    queries;
+    repository;
+    configurationDigest;
+    expectedExtractors;
+    constructor(queries, repository, configurationDigest, expectedExtractors) {
+        this.queries = queries;
+        this.repository = repository;
+        this.configurationDigest = configurationDigest;
+        this.expectedExtractors = expectedExtractors;
+    }
+    async assess(request) {
+        const report = await this.queries.assess(request);
+        const evidenceState = await inspectSavedEvidence(report.snapshot, this.repository, this.configurationDigest, this.expectedExtractors);
+        const result = { ...report, evidenceState };
+        return { ...result, markdown: renderContractCompatibility(result) };
+    }
+}

package/dist/application/saved-evidence.d.ts

@@ -1,4 +1,4 @@
-import type { ImpactQueryService, ImpactScanRequest } from "@weftlet/core";
+import type { ContextPack, ImpactQueryService, ImpactScanRequest } from "@weftlet/core";
 import type { GitRepository } from "../repository/git.js";
 /** Read-side metadata; never calls an indexer, model, compiler, or refresh operation. */
 export declare class SavedEvidenceQueryService implements ImpactQueryService {
@@ -10,16 +10,16 @@ export declare class SavedEvidenceQueryService implements ImpactQueryService {
     scan(request: ImpactScanRequest): Promise<{
         markdown: string;
         evidenceState: {
-            eligibleForCurrentDiffValidation: false;
-            extractionCompatible?: boolean | undefined;
-            incompatibleExtractors?: readonly string[] | undefined;
-            stale: boolean;
-            configurationMatches: boolean;
-            overlayFreshness?: "unknown" | "current" | "stale" | undefined;
-            capturedWorkingChanges?: string[] | undefined;
-            changedSinceCapture?: string[] | undefined;
-            currentCommit: string | undefined;
-            excludedWorkingChanges: string[];
+            readonly currentCommit?: string;
+            readonly excludedWorkingChanges: readonly string[];
+            readonly capturedWorkingChanges?: readonly string[];
+            readonly changedSinceCapture?: readonly string[];
+            readonly overlayFreshness?: "current" | "stale" | "unknown";
+            readonly stale: boolean;
+            readonly configurationMatches: boolean;
+            readonly extractionCompatible?: boolean;
+            readonly incompatibleExtractors?: readonly string[];
+            readonly eligibleForCurrentDiffValidation: false;
         };
         snapshot: Pick<import("@weftlet/core").SnapshotManifest, "snapshotId" | "commitSha" | "contentDigest" | "configurationDigest" | "scope" | "baseSha" | "overlayDigest" | "overlayCapture"> & Partial<Pick<import("@weftlet/core").SnapshotManifest, "extractorVersions" | "documentSelection">>;
         capabilities: readonly import("@weftlet/core").GraphNode[];
@@ -31,6 +31,10 @@ export declare class SavedEvidenceQueryService implements ImpactQueryService {
         diagnostics: import("@weftlet/core").DiagnosticReport;
         exploration?: {
             readonly rankingVersion?: string;
+            readonly codeTraversalVersion?: string;
+            readonly unexpandedCodeTargets?: readonly string[];
+            readonly unexpandedCodeTargetCount?: number;
+            readonly unexpandedCodeTargetsTruncated?: boolean;
             readonly returned: number;
             readonly reachableFacts: number;
             readonly maxDepth: number;
@@ -40,3 +44,5 @@ export declare class SavedEvidenceQueryService implements ImpactQueryService {
         };
     }>;
 }
+/** Shared read-side state for impact scans and exact-node exploration. */
+export declare function inspectSavedEvidence(snapshot: ContextPack['snapshot'], repository: GitRepository, configurationDigest: string, expectedExtractors?: Readonly<Record<string, string>>): Promise<NonNullable<ContextPack['evidenceState']>>;

package/dist/application/saved-evidence.js

@@ -16,50 +16,54 @@ export class SavedEvidenceQueryService {
     }
     async scan(request) {
         const pack = await this.queries.scan(request);
-        const currentCommit = await this.repository.resolveRef('HEAD').catch(() => undefined);
-        const workingChanges = await this.repository.workingChanges();
-        const capturedWorkingChanges = [];
-        const changedSinceCapture = new Set();
-        let overlayFreshness;
-        if (pack.snapshot.overlayDigest) {
-            overlayFreshness = 'unknown';
-            const capture = pack.snapshot.overlayCapture;
-            if (capture) {
-                overlayFreshness = 'current';
-                for (const file of capture.files) {
-                    try {
-                        const content = await readWorkingContent(this.repository.root, file.path);
-                        if ((content === null ? null : sha256(content)) === file.digest)
-                            capturedWorkingChanges.push(file.path);
-                        else
-                            changedSinceCapture.add(file.path);
-                    }
-                    catch {
-                        overlayFreshness = 'unknown';
+        const evidenceState = await inspectSavedEvidence(pack.snapshot, this.repository, this.configurationDigest, this.expectedExtractors);
+        const result = { ...pack, evidenceState };
+        return { ...result, markdown: new MarkdownContextPackRenderer().render(result) };
+    }
+}
+/** Shared read-side state for impact scans and exact-node exploration. */
+export async function inspectSavedEvidence(snapshot, repository, configurationDigest, expectedExtractors) {
+    const currentCommit = await repository.resolveRef('HEAD').catch(() => undefined);
+    const workingChanges = await repository.workingChanges();
+    const capturedWorkingChanges = [];
+    const changedSinceCapture = new Set();
+    let overlayFreshness;
+    if (snapshot.overlayDigest) {
+        overlayFreshness = 'unknown';
+        const capture = snapshot.overlayCapture;
+        if (capture) {
+            overlayFreshness = 'current';
+            for (const file of capture.files) {
+                try {
+                    const content = await readWorkingContent(repository.root, file.path);
+                    if ((content === null ? null : sha256(content)) === file.digest)
+                        capturedWorkingChanges.push(file.path);
+                    else
                         changedSinceCapture.add(file.path);
-                    }
                 }
-                for (const path of workingChanges) {
-                    if (!capturedWorkingChanges.includes(path) && inWorkingScope(path, capture.sourcePatterns))
-                        changedSinceCapture.add(path);
+                catch {
+                    overlayFreshness = 'unknown';
+                    changedSinceCapture.add(file.path);
                 }
-                if (changedSinceCapture.size && overlayFreshness !== 'unknown')
-                    overlayFreshness = 'stale';
             }
+            for (const path of workingChanges) {
+                if (!capturedWorkingChanges.includes(path) && inWorkingScope(path, capture.sourcePatterns))
+                    changedSinceCapture.add(path);
+            }
+            if (changedSinceCapture.size && overlayFreshness !== 'unknown')
+                overlayFreshness = 'stale';
         }
-        const excludedWorkingChanges = workingChanges.filter((path) => !capturedWorkingChanges.includes(path));
-        const incompatibleExtractors = this.expectedExtractors
-            ? incompatibleSnapshotExtractors(pack.snapshot.extractorVersions, this.expectedExtractors) : undefined;
-        const evidenceState = {
-            currentCommit,
-            excludedWorkingChanges,
-            ...(overlayFreshness ? { overlayFreshness, capturedWorkingChanges, changedSinceCapture: [...changedSinceCapture].sort() } : {}),
-            stale: currentCommit !== pack.snapshot.commitSha || (overlayFreshness !== undefined && overlayFreshness !== 'current'),
-            configurationMatches: pack.snapshot.configurationDigest === this.configurationDigest,
-            ...(incompatibleExtractors ? { extractionCompatible: incompatibleExtractors.length === 0, incompatibleExtractors } : {}),
-            eligibleForCurrentDiffValidation: false,
-        };
-        const result = { ...pack, evidenceState };
-        return { ...result, markdown: new MarkdownContextPackRenderer().render(result) };
     }
+    const excludedWorkingChanges = workingChanges.filter((path) => !capturedWorkingChanges.includes(path));
+    const incompatibleExtractors = expectedExtractors
+        ? incompatibleSnapshotExtractors(snapshot.extractorVersions, expectedExtractors) : undefined;
+    return {
+        currentCommit,
+        excludedWorkingChanges,
+        ...(overlayFreshness ? { overlayFreshness, capturedWorkingChanges, changedSinceCapture: [...changedSinceCapture].sort() } : {}),
+        stale: currentCommit !== snapshot.commitSha || (overlayFreshness !== undefined && overlayFreshness !== 'current'),
+        configurationMatches: snapshot.configurationDigest === configurationDigest,
+        ...(incompatibleExtractors ? { extractionCompatible: incompatibleExtractors.length === 0, incompatibleExtractors } : {}),
+        eligibleForCurrentDiffValidation: false,
+    };
 }

package/dist/application/saved-exploration.d.ts

@@ -0,0 +1,57 @@
+import type { GraphExplorationService, GraphNeighborsRequest } from '@weftlet/core';
+import type { GitRepository } from '../repository/git.js';
+/** Adds checkout/overlay state without extracting, refreshing or changing a saved graph. */
+export declare class SavedGraphExplorationService implements GraphExplorationService {
+    private readonly queries;
+    private readonly repository;
+    private readonly configurationDigest;
+    private readonly expectedExtractors?;
+    constructor(queries: GraphExplorationService, repository: GitRepository, configurationDigest: string, expectedExtractors?: Readonly<Record<string, string>> | undefined);
+    neighbors(request: GraphNeighborsRequest): Promise<{
+        markdown: string;
+        evidenceState: {
+            readonly currentCommit?: string;
+            readonly excludedWorkingChanges: readonly string[];
+            readonly capturedWorkingChanges?: readonly string[];
+            readonly changedSinceCapture?: readonly string[];
+            readonly overlayFreshness?: "current" | "stale" | "unknown";
+            readonly stale: boolean;
+            readonly configurationMatches: boolean;
+            readonly extractionCompatible?: boolean;
+            readonly incompatibleExtractors?: readonly string[];
+            readonly eligibleForCurrentDiffValidation: false;
+        };
+        snapshot: import("@weftlet/core").ContextPack["snapshot"];
+        focus: {
+            readonly nodeId: string;
+            readonly status: "present" | "absent-from-snapshot";
+        };
+        facts: readonly import("@weftlet/core").GraphFact[];
+        coverage: import("@weftlet/core").ContextPack["coverage"];
+        diagnostics: import("@weftlet/core").ContextPack["diagnostics"];
+        selection: {
+            readonly version: string;
+            readonly direction: import("@weftlet/core").GraphDirection;
+            readonly predicates: readonly import("@weftlet/core").GraphPredicate[];
+            readonly maxFacts: number;
+            readonly incidentFacts: number;
+            readonly matchingFacts: number;
+            readonly filteredFacts: number;
+            readonly offset: number;
+            readonly returnedFacts: number;
+            readonly remainingFacts: number;
+            readonly truncated: boolean;
+            readonly continuation?: string;
+        };
+        frontier: {
+            readonly scope: "selected-one-hop-neighborhood";
+            readonly totalNeighbors: number;
+            readonly remainingNeighbors: number;
+            readonly neighbors: readonly {
+                readonly nodeId: string;
+                readonly factIds: readonly string[];
+                readonly otherIncidentFacts: number;
+            }[];
+        };
+    }>;
+}

package/dist/application/saved-exploration.js

@@ -0,0 +1,21 @@
+import { renderGraphNeighborhood } from '../graph/neighborhood-renderer.js';
+import { inspectSavedEvidence } from './saved-evidence.js';
+/** Adds checkout/overlay state without extracting, refreshing or changing a saved graph. */
+export class SavedGraphExplorationService {
+    queries;
+    repository;
+    configurationDigest;
+    expectedExtractors;
+    constructor(queries, repository, configurationDigest, expectedExtractors) {
+        this.queries = queries;
+        this.repository = repository;
+        this.configurationDigest = configurationDigest;
+        this.expectedExtractors = expectedExtractors;
+    }
+    async neighbors(request) {
+        const result = await this.queries.neighbors(request);
+        const evidenceState = await inspectSavedEvidence(result.snapshot, this.repository, this.configurationDigest, this.expectedExtractors);
+        const withState = { ...result, evidenceState };
+        return { ...withState, markdown: renderGraphNeighborhood(withState) };
+    }
+}

package/dist/application/saved-paths.d.ts

@@ -0,0 +1,58 @@
+import type { GraphPathQueryService, GraphPathsRequest } from '@weftlet/core';
+import type { GitRepository } from '../repository/git.js';
+export declare class SavedGraphPathService implements GraphPathQueryService {
+    private readonly queries;
+    private readonly repository;
+    private readonly configurationDigest;
+    private readonly expectedExtractors?;
+    constructor(queries: GraphPathQueryService, repository: GitRepository, configurationDigest: string, expectedExtractors?: Readonly<Record<string, string>> | undefined);
+    paths(request: GraphPathsRequest): Promise<{
+        markdown: string;
+        evidenceState: {
+            readonly currentCommit?: string;
+            readonly excludedWorkingChanges: readonly string[];
+            readonly capturedWorkingChanges?: readonly string[];
+            readonly changedSinceCapture?: readonly string[];
+            readonly overlayFreshness?: "current" | "stale" | "unknown";
+            readonly stale: boolean;
+            readonly configurationMatches: boolean;
+            readonly extractionCompatible?: boolean;
+            readonly incompatibleExtractors?: readonly string[];
+            readonly eligibleForCurrentDiffValidation: false;
+        };
+        snapshot: import("@weftlet/core").ContextPack["snapshot"];
+        endpoints: {
+            readonly from: {
+                readonly nodeId: string;
+                readonly status: "present" | "absent-from-snapshot";
+            };
+            readonly to: {
+                readonly nodeId: string;
+                readonly status: "present" | "absent-from-snapshot";
+            };
+        };
+        paths: readonly import("@weftlet/core").EvidencePath[];
+        facts: readonly import("@weftlet/core").GraphFact[];
+        coverage: import("@weftlet/core").ContextPack["coverage"];
+        diagnostics: import("@weftlet/core").ContextPack["diagnostics"];
+        search: {
+            readonly version: string;
+            readonly order: "fact-id-depth-first";
+            readonly direction: import("@weftlet/core").GraphDirection;
+            readonly predicates: readonly import("@weftlet/core").GraphPredicate[];
+            readonly maxDepth: number;
+            readonly maxPaths: number;
+            readonly maxSteps: number;
+            readonly searchLimit: number;
+            readonly replayedSteps: number;
+            readonly examinedSteps: number;
+            readonly totalSteps: number;
+            readonly stopReason: "exhausted" | "path-page-limit" | "work-page-limit" | "search-limit";
+            readonly exhaustedWithinDepth: boolean;
+            readonly depthLimitReached: boolean;
+            readonly truncated: boolean;
+            readonly continuation?: string;
+        };
+        frontier: import("@weftlet/core").PathFrontier;
+    }>;
+}

package/dist/application/saved-paths.js

@@ -0,0 +1,20 @@
+import { renderGraphPaths } from '../graph/paths-renderer.js';
+import { inspectSavedEvidence } from './saved-evidence.js';
+export class SavedGraphPathService {
+    queries;
+    repository;
+    configurationDigest;
+    expectedExtractors;
+    constructor(queries, repository, configurationDigest, expectedExtractors) {
+        this.queries = queries;
+        this.repository = repository;
+        this.configurationDigest = configurationDigest;
+        this.expectedExtractors = expectedExtractors;
+    }
+    async paths(request) {
+        const result = await this.queries.paths(request);
+        const evidenceState = await inspectSavedEvidence(result.snapshot, this.repository, this.configurationDigest, this.expectedExtractors);
+        const withState = { ...result, evidenceState };
+        return { ...withState, markdown: renderGraphPaths(withState) };
+    }
+}

package/dist/application/semantic-run.d.ts

@@ -7,7 +7,7 @@ export interface HydrationProgressEvent {
     readonly total?: number;
     readonly sourceId?: string;
     readonly elapsedMs?: number;
-    readonly status?: 'started' | 'completed' | 'failed';
+    readonly status?: 'started' | 'completed' | 'failed' | 'progress';
     readonly factCount?: number;
     readonly nodeCount?: number;
 }

package/dist/extraction/call-syntax.d.ts

@@ -0,0 +1,18 @@
+import ts from 'typescript';
+import type { GraphFact, SourceSpan } from '@weftlet/core';
+export type Callable = ts.FunctionDeclaration | ts.FunctionExpression | ts.ArrowFunction | ts.MethodDeclaration | ts.GetAccessorDeclaration | ts.SetAccessorDeclaration | ts.ConstructorDeclaration;
+export declare const isCallable: (node: ts.Node) => node is Callable;
+export declare function callableName(node: Callable): ts.Node | undefined;
+/** Ambient declarations may occur in .ts namespaces too; they supply no runtime body. */
+export declare function isAmbient(node: ts.Node): boolean;
+export declare function syntaxSpan(node: ts.Node, source: ts.SourceFile, digest: string, commitSha: string): SourceSpan;
+export declare const positionKey: (span: SourceSpan) => string;
+export declare function calleeToken(expression: ts.Expression): ts.Node | undefined;
+export interface ParsedCallSource {
+    readonly source: ts.SourceFile;
+    readonly digest: string;
+    readonly byPosition: ReadonlyMap<string, readonly GraphFact[]>;
+    readonly parseErrors: readonly ts.Diagnostic[];
+}
+export declare function parseCallSource(path: string, text: string, digest: string, facts: readonly GraphFact[]): ParsedCallSource;
+export declare function factsAt(node: ts.Node | undefined, parsed: ParsedCallSource, commitSha: string, role: 'definition' | 'reference'): GraphFact[];

package/dist/extraction/call-syntax.js

@@ -0,0 +1,61 @@
+import ts from 'typescript';
+export const isCallable = (node) => ts.isFunctionDeclaration(node) ||
+    ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node) ||
+    ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node) || ts.isConstructorDeclaration(node);
+export function callableName(node) {
+    if ('name' in node && node.name)
+        return node.name;
+    if (ts.isConstructorDeclaration(node))
+        return node.getFirstToken();
+    const parent = node.parent;
+    if ((ts.isVariableDeclaration(parent) || ts.isPropertyDeclaration(parent) || ts.isPropertyAssignment(parent)) &&
+        parent.initializer === node && (ts.isIdentifier(parent.name) || ts.isPrivateIdentifier(parent.name)))
+        return parent.name;
+    return undefined;
+}
+/** Ambient declarations may occur in .ts namespaces too; they supply no runtime body. */
+export function isAmbient(node) {
+    if (node.getSourceFile().isDeclarationFile)
+        return true;
+    for (let current = node; current; current = current.parent) {
+        if (ts.canHaveModifiers(current) && ts.getModifiers(current)?.some(modifier => modifier.kind === ts.SyntaxKind.DeclareKeyword))
+            return true;
+    }
+    return false;
+}
+export function syntaxSpan(node, source, digest, commitSha) {
+    const start = source.getLineAndCharacterOfPosition(node.getStart(source));
+    const end = source.getLineAndCharacterOfPosition(node.getEnd());
+    return { path: source.fileName, startLine: start.line + 1, startColumn: start.character + 1,
+        endLine: end.line + 1, endColumn: end.character + 1, columnEncoding: 'utf-16', digest, commitSha };
+}
+export const positionKey = (span) => `${span.path}:${span.startLine}:${span.startColumn}:${span.endLine}:${span.endColumn}`;
+export function calleeToken(expression) {
+    while (ts.isParenthesizedExpression(expression) || ts.isNonNullExpression(expression) ||
+        ts.isAsExpression(expression) || ts.isTypeAssertionExpression(expression) || ts.isSatisfiesExpression(expression))
+        expression = expression.expression;
+    if (ts.isIdentifier(expression) || expression.kind === ts.SyntaxKind.SuperKeyword)
+        return expression;
+    if (ts.isPropertyAccessExpression(expression))
+        return expression.name;
+    if (ts.isElementAccessExpression(expression) && ts.isStringLiteral(expression.argumentExpression))
+        return expression.argumentExpression;
+    return undefined;
+}
+export function parseCallSource(path, text, digest, facts) {
+    const source = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, path.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const byPosition = new Map();
+    for (const fact of facts) {
+        const key = positionKey(fact.provenance), group = byPosition.get(key) ?? [];
+        group.push(fact);
+        byPosition.set(key, group);
+    }
+    return { source, digest, byPosition,
+        parseErrors: source.parseDiagnostics };
+}
+export function factsAt(node, parsed, commitSha, role) {
+    if (!node)
+        return [];
+    return (parsed.byPosition.get(positionKey(syntaxSpan(node, parsed.source, parsed.digest, commitSha))) ?? [])
+        .filter(fact => fact.codeOccurrence?.role === role);
+}

package/dist/extraction/canonical-document-links.d.ts

@@ -1,10 +1,12 @@
 export interface CanonicalDocumentDefinition {
     readonly target: string;
+    readonly title?: string;
     readonly startLine: number;
     readonly endLine: number;
 }
 export interface CanonicalDocumentLink {
     readonly kind: 'link' | 'ambiguous-reference';
+    readonly title?: string;
     readonly target?: string;
     readonly startLine: number;
     readonly endLine: number;
@@ -15,7 +17,9 @@ export interface CanonicalDocumentLink {
     readonly referenceEndLine?: number;
 }
 /** Explicit Markdown links only: this deliberately does not change the graph linker's policy. */
-export declare function canonicalDocumentLinks(content: string): readonly CanonicalDocumentLink[];
+export declare function canonicalDocumentLinks(content: string, options?: {
+    readonly includeTitles?: boolean;
+}): readonly CanonicalDocumentLink[];
 export type CanonicalDocumentLinkResolution = {
     readonly kind: 'path';
     readonly path: string;

package/dist/extraction/canonical-document-links.js

@@ -1,7 +1,7 @@
 import { posix } from 'node:path';
 import { fromMarkdown } from 'mdast-util-from-markdown';
 /** Explicit Markdown links only: this deliberately does not change the graph linker's policy. */
-export function canonicalDocumentLinks(content) {
+export function canonicalDocumentLinks(content, options = {}) {
     const tree = fromMarkdown(content);
     const definitions = new Map();
     const collect = (node) => {
@@ -18,20 +18,20 @@ export function canonicalDocumentLinks(content) {
     const links = [];
     const visit = (node) => {
         if (node.type === 'link' && node.position) {
-            links.push({ kind: 'link', target: node.url,
+            links.push({ kind: 'link', target: node.url, ...(options.includeTitles && node.title ? { title: node.title } : {}),
                 startLine: node.position.start.line, endLine: node.position.end.line });
             return;
         }
         if (node.type === 'linkReference' && node.position) {
             const declared = (definitions.get(node.identifier) ?? []).flatMap(definition => definition.position
-                ? [{ target: definition.url, startLine: definition.position.start.line, endLine: definition.position.end.line }]
+                ? [{ target: definition.url, ...(options.includeTitles && definition.title ? { title: definition.title } : {}), startLine: definition.position.start.line, endLine: definition.position.end.line }]
                 : []);
             const first = declared[0];
             if (!first)
                 return;
             const reference = { identifier: node.identifier,
                 referenceStartLine: node.position.start.line, referenceEndLine: node.position.end.line };
-            if (new Set(declared.map(definition => definition.target)).size > 1) {
+            if (new Set(declared.map(definition => JSON.stringify([definition.target, definition.title]))).size > 1) {
                 // Never silently choose the first conflicting definition, as normal Markdown rendering does.
                 links.push({ kind: 'ambiguous-reference', ...reference,
                     startLine: node.position.start.line, endLine: node.position.end.line, definitions: declared });

package/dist/extraction/code-inventory.d.ts

@@ -0,0 +1,6 @@
+import type { CodeInventory } from '@weftlet/core';
+import type { GitTreeEntry } from '../repository/git.js';
+import type { ScipSourceProject } from '../configuration/scip-project.js';
+import type { ScipIndexResult } from './scip-runtime.js';
+/** No package contents, dependencies or active checkout are read. Boundary names are physical paths. */
+export declare function buildCodeInventory(entries: readonly GitTreeEntry[], selectedPaths: readonly string[], codeRoots: readonly string[], project: ScipSourceProject | undefined, index: ScipIndexResult): CodeInventory;

package/dist/extraction/code-inventory.js

@@ -0,0 +1,26 @@
+import { matchesRepositoryGlob } from '../repository/glob.js';
+import { sha256, stableJson } from '../infrastructure/util.js';
+/** No package contents, dependencies or active checkout are read. Boundary names are physical paths. */
+export function buildCodeInventory(entries, selectedPaths, codeRoots, project, index) {
+    const regular = entries.filter(entry => entry.type === 'blob' && ['100644', '100755'].includes(entry.mode));
+    const manifests = regular.filter(entry => entry.path === 'package.json' || entry.path.endsWith('/package.json'));
+    const roots = new Map(manifests.map(entry => [entry.path === 'package.json' ? '.' : entry.path.slice(0, -'/package.json'.length),
+        { path: entry.path, blobId: entry.objectId }]));
+    const orderedRoots = [...roots.keys()].filter(root => root !== '.').sort((a, b) => b.length - a.length || a.localeCompare(b));
+    const indexed = index.indexedPaths === undefined ? undefined : new Set(index.indexedPaths);
+    const selected = new Set(selectedPaths);
+    const files = regular.filter(entry => /\.(?:[cm]?ts|tsx)$/.test(entry.path)).map(entry => ({
+        path: entry.path, blobId: entry.objectId, projectRoot: orderedRoots.find(root => entry.path.startsWith(`${root}/`)) ?? '.',
+        codeRootSelected: selected.has(entry.path),
+        requested: project ? project.include.some(pattern => matchesRepositoryGlob(entry.path, pattern)) ? 'included' : 'excluded' : 'unknown',
+        ...(indexed ? { indexed: indexed.has(entry.path) } : {}),
+    })).sort((a, b) => a.path.localeCompare(b.path));
+    const projects = [...new Set(['.', ...roots.keys()])].sort().map(root => ({ root, ...(roots.has(root) ? { manifest: roots.get(root) } : {}) }));
+    const known = new Set(files.map(file => file.path));
+    const plain = { version: 'committed-code-inventory-v1', scipIndexDigest: index.digest,
+        selection: project ? 'source-project' : 'indexer-command',
+        indexObservation: indexed ? 'recorded' : 'unavailable', codeRoots: [...codeRoots],
+        ...(project ? { includePatterns: [...project.include] } : {}), projects, files,
+        ...(indexed ? { otherIndexedFiles: [...indexed].filter(path => !known.has(path)).length } : {}) };
+    return { ...plain, digest: sha256(stableJson(plain)) };
+}

package/dist/extraction/document-code-bindings.d.ts

@@ -0,0 +1,14 @@
+import type { ExtractionContext, GraphDiagnostic, GraphFact, SemanticSource } from '@weftlet/core';
+import type { GitRepository } from '../repository/git.js';
+export declare const documentCodeBindingIdentity: {
+    readonly id: "document-code-binding-extractor";
+    readonly version: "1.0.0";
+};
+export interface BindingSource extends SemanticSource {
+    readonly metadata: Pick<GraphFact, 'sourceAuthority' | 'sourceRole' | 'sourceOwnership' | 'sourcePolicyDigest'>;
+}
+/** Resolve only explicit declarations against current indexed evidence; no provider, checkout or basename search. */
+export declare function extractDocumentCodeBindings(repository: Pick<GitRepository, 'listEntriesAt' | 'readFileAt'>, context: ExtractionContext, sources: readonly BindingSource[], codeFacts: readonly GraphFact[], subjectFacts: readonly GraphFact[]): Promise<{
+    facts: readonly GraphFact[];
+    diagnostics: readonly GraphDiagnostic[];
+}>;