@weftlet/toolkit 0.6.0 → 0.7.0

package/dist/extraction/scip-runtime.d.ts

@@ -0,0 +1,39 @@
+export interface ScipOccurrence {
+    readonly range: readonly number[];
+    readonly symbol: string;
+    readonly symbol_roles: number;
+    readonly enclosing_range?: readonly number[];
+}
+export interface ScipDocument {
+    readonly relative_path: string;
+    readonly occurrences: readonly ScipOccurrence[];
+    readonly symbols: readonly ScipSymbolInformation[];
+}
+interface ScipSymbolInformation {
+    documentation: string[];
+}
+export interface ScipIndex {
+    readonly documents: readonly ScipDocument[];
+    readonly external_symbols: readonly ScipSymbolInformation[];
+    readonly metadata?: {
+        project_root: string;
+    };
+    serializeBinary(): Uint8Array;
+}
+interface ScipRuntime {
+    readonly scip: {
+        readonly Index: {
+            deserializeBinary(bytes: Uint8Array): ScipIndex;
+        };
+    };
+}
+export declare function loadScipRuntime(): ScipRuntime;
+export interface ScipIndexResult {
+    readonly path: string;
+    readonly digest: string;
+    readonly mode: 'full' | 'package';
+    readonly version: string;
+    /** Exact document paths observed in the normalized index, including zero-occurrence documents. */
+    readonly indexedPaths?: readonly string[];
+}
+export {};

package/dist/extraction/scip-runtime.js

@@ -0,0 +1,8 @@
+// Modified for standalone extraction; see docs/extraction-manifest.json.
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+export function loadScipRuntime() {
+    const require = createRequire(import.meta.url);
+    const main = require.resolve('@sourcegraph/scip-typescript');
+    return require(join(dirname(main), 'scip.js'));
+}

package/dist/extraction/scip-symbols.d.ts

@@ -0,0 +1,21 @@
+import { type ExtractionContext, type FactExtractor, type GraphFact } from '@weftlet/core';
+import type { GitRepository } from '../repository/git.js';
+import type { ScipIndexResult } from './scip-runtime.js';
+export declare const scipSymbolExtractorIdentity: {
+    readonly id: "scip-symbol-extractor";
+    readonly version: "2.1.0";
+};
+export declare class ScipSymbolExtractor implements FactExtractor {
+    private readonly repository;
+    private readonly index;
+    readonly identity: {
+        readonly id: "scip-symbol-extractor";
+        readonly version: "2.1.0";
+    };
+    constructor(repository: GitRepository, index: ScipIndexResult);
+    extract(context: ExtractionContext): Promise<readonly GraphFact[]>;
+    extractWithDiagnostics(context: ExtractionContext): Promise<{
+        facts: GraphFact[];
+        diagnostics: import("@weftlet/core").GraphDiagnostic[];
+    }>;
+}

package/dist/extraction/scip-symbols.js

@@ -0,0 +1,91 @@
+// Modified for standalone extraction; see docs/extraction-manifest.json.
+import { readFile } from 'node:fs/promises';
+import { repositoryFileNode } from '@weftlet/core';
+import { loadScipRuntime } from './scip-runtime.js';
+import { extractCodeOccurrences } from './scip-occurrences.js';
+import { extractStaticCalls } from './static-calls.js';
+import { sha256, stableJson } from '../infrastructure/util.js';
+export const scipSymbolExtractorIdentity = { id: 'scip-symbol-extractor', version: '2.1.0' };
+export class ScipSymbolExtractor {
+    repository;
+    index;
+    identity = scipSymbolExtractorIdentity;
+    constructor(repository, index) {
+        this.repository = repository;
+        this.index = index;
+    }
+    async extract(context) {
+        return (await this.extractWithDiagnostics(context)).facts;
+    }
+    async extractWithDiagnostics(context) {
+        const parsed = loadScipRuntime().scip.Index.deserializeBinary(await readFile(this.index.path));
+        const symbols = new Map();
+        const sources = new Map();
+        for (const document of parsed.documents) {
+            const path = document.relative_path.replace(/\\/g, '/');
+            const content = await this.repository.readFileAt(context.commitSha, path);
+            sources.set(path, content);
+            const digest = sha256(content);
+            const component = repositoryFileNode(path);
+            for (const occurrence of document.occurrences) {
+                if (!occurrence.symbol || occurrence.symbol.startsWith('local '))
+                    continue;
+                const definition = (occurrence.symbol_roles & 1) === 1;
+                const sites = symbols.get(occurrence.symbol) ?? {
+                    definitions: new Map(),
+                    references: new Map(),
+                };
+                symbols.set(occurrence.symbol, sites);
+                const target = definition ? sites.definitions : sites.references;
+                if (target.has(path))
+                    continue;
+                target.set(path, {
+                    path,
+                    line: (occurrence.range[0] ?? 0) + 1,
+                    digest,
+                    component,
+                });
+            }
+        }
+        const facts = [];
+        for (const [symbolText, sites] of [...symbols.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+            const definitionPaths = new Set(sites.definitions.keys());
+            const downstream = [...sites.references.values()].filter((site) => !definitionPaths.has(site.path));
+            if (sites.definitions.size === 0 || downstream.length === 0)
+                continue;
+            const symbol = {
+                id: `symbol:scip:${sha256(symbolText)}`,
+                kind: 'Contract',
+                label: symbolText,
+                attributes: { scipIndexDigest: this.index.digest },
+            };
+            const relationships = [
+                ...[...sites.definitions.values()].map((site) => ({ site, definition: true })),
+                ...downstream.map((site) => ({ site, definition: false })),
+            ];
+            for (const { site, definition } of relationships) {
+                const relation = definition ? 'definition' : 'reference';
+                const provenance = {
+                    path: site.path,
+                    startLine: site.line,
+                    endLine: site.line,
+                    digest: site.digest,
+                    commitSha: context.commitSha,
+                };
+                facts.push({
+                    id: sha256(stableJson({ relation, path: site.path, symbol: symbolText, provenance })),
+                    subject: site.component,
+                    predicate: definition ? 'contains' : 'consumes',
+                    object: symbol,
+                    provenance,
+                    extractor: this.identity,
+                    confidence: 1,
+                    snapshotId: context.snapshotId,
+                });
+            }
+        }
+        const occurrences = extractCodeOccurrences(parsed, sources, context, this.index.digest, this.identity);
+        const calls = extractStaticCalls(sources, occurrences, context);
+        return { facts: [...facts, ...occurrences, ...calls.facts], diagnostics: calls.diagnostics };
+    }
+}

package/dist/extraction/semantic.d.ts

@@ -14,7 +14,7 @@ export interface ExtractedAssertion {
         readonly kind: GraphNodeKind;
         readonly label: string;
     };
-    readonly predicate: GraphPredicate;
+    readonly predicate: Exclude<GraphPredicate, 'calls'>;
     readonly object: {
         readonly id: string;
         readonly kind: GraphNodeKind;

package/dist/extraction/semantic.js

@@ -7,6 +7,9 @@ export { semanticCommandEnvironment } from './codex-auth.js';
 import { resolveCodexInvocation } from './codex-command.js';
 import { runSemanticProcess, SemanticProviderError } from "./semantic-process.js";
 export { SemanticProviderError } from "./semantic-process.js";
+import { graphPredicates } from "@weftlet/core";
+// Calls require indexed syntax/proofs. Keep the prose schema and its cache identity unchanged.
+const predicates = graphPredicates.filter(predicate => predicate !== 'calls');
 import { sha256, stableJson } from "../infrastructure/util.js";
 import { canonicalizeRepositoryDocumentNode } from './repository-nodes.js';
 import { semanticArtifactKey, semanticArtifactOutputDigest, semanticProviderIdentity } from './semantic-identity.js';
@@ -79,6 +82,8 @@ function renderOml(key, assertions) {
     const instances = [...nodes.entries()]
         .sort(([left], [right]) => left.localeCompare(right))
         .map(([id, node]) => {
+        if (node.kind === 'CodeSymbol')
+            throw new Error('Code symbols require deterministic code extraction');
         const local = localNames.get(id);
         const properties = [
             `    cg:hasIdentifier "${omlEscape(node.id)}"`,
@@ -119,23 +124,6 @@ const kinds = [
     'PersistenceModel',
     'Scope',
 ];
-const predicates = [
-    'realizes',
-    'implementedBy',
-    'consumes',
-    'emits',
-    'persistsTo',
-    'governedBy',
-    'definedBy',
-    'verifiedBy',
-    'operationallyOwnedBy',
-    'decisionAuthority',
-    'routesThrough',
-    'authorizedBy',
-    'sourcedFrom',
-    'references',
-    'contains',
-];
 export function semanticOutputSchema(lineCount) {
     const node = {
         type: 'object',

package/dist/extraction/static-calls.d.ts

@@ -0,0 +1,10 @@
+import { type ExtractionContext, type GraphDiagnostic, type GraphFact } from '@weftlet/core';
+export declare const staticCallIdentity: {
+    readonly id: "typescript-call-extractor";
+    readonly version: "1.0.0";
+};
+/** Parse only the exact committed documents already indexed by SCIP. No second resolver or name guessing. */
+export declare function extractStaticCalls(sources: ReadonlyMap<string, string>, codeFacts: readonly GraphFact[], context: ExtractionContext): {
+    facts: GraphFact[];
+    diagnostics: GraphDiagnostic[];
+};

package/dist/extraction/static-calls.js

@@ -0,0 +1,133 @@
+import ts from 'typescript';
+import { repositoryFileNode } from '@weftlet/core';
+import { sha256, stableJson } from '../infrastructure/util.js';
+import { calleeToken, callableName, factsAt, isAmbient, isCallable, parseCallSource, syntaxSpan } from './call-syntax.js';
+export const staticCallIdentity = { id: 'typescript-call-extractor', version: '1.0.0' };
+const proof = (fact) => ({ factId: fact.id, provenance: fact.provenance });
+function targetResolution(syntax, defs, kinds) {
+    if (!defs.length)
+        return 'external';
+    if (syntax === 'construct' && kinds?.has('class'))
+        return 'indexed-class';
+    if (kinds?.has('body'))
+        return 'indexed-body';
+    if (kinds?.has('declaration'))
+        return 'declaration-only';
+    return undefined;
+}
+/** Parse only the exact committed documents already indexed by SCIP. No second resolver or name guessing. */
+export function extractStaticCalls(sources, codeFacts, context) {
+    const parsed = [], kinds = new Map();
+    const definitions = new Map(), local = new Map();
+    for (const fact of codeFacts.filter(f => f.codeOccurrence)) {
+        const group = local.get(fact.provenance.path) ?? [];
+        group.push(fact);
+        local.set(fact.provenance.path, group);
+        if (fact.codeOccurrence.role === 'definition') {
+            const defs = definitions.get(fact.subject.id) ?? [];
+            defs.push(fact);
+            definitions.set(fact.subject.id, defs);
+        }
+    }
+    for (const [path, text] of sources) {
+        const digest = sha256(text), facts = local.get(path) ?? [];
+        if (facts.some(f => f.provenance.commitSha !== context.commitSha || f.provenance.digest !== digest)) {
+            throw new Error('Call analysis requires matching committed SCIP source bytes');
+        }
+        const file = parseCallSource(path, text, digest, facts);
+        parsed.push(file);
+        if (file.parseErrors.length)
+            continue;
+        const classify = (node) => {
+            const name = isCallable(node) ? callableName(node) : ts.isClassDeclaration(node) || ts.isClassExpression(node) ? node.name :
+                ts.isMethodSignature(node) ? node.name : undefined;
+            const kind = isCallable(node) ? node.body && !isAmbient(node) ? 'body' : 'declaration' :
+                ts.isClassDeclaration(node) || ts.isClassExpression(node) ? isAmbient(node) ? 'declaration' : 'class' : ts.isMethodSignature(node) ? 'declaration' : undefined;
+            if (kind)
+                for (const fact of factsAt(name, file, context.commitSha, 'definition')) {
+                    const values = kinds.get(fact.subject.id) ?? new Set();
+                    values.add(kind);
+                    kinds.set(fact.subject.id, values);
+                }
+            ts.forEachChild(node, classify);
+        };
+        classify(file.source);
+    }
+    const facts = [], diagnostics = [];
+    for (const file of parsed) {
+        const physical = repositoryFileNode(file.source.fileName);
+        const gap = (node, caller, reason, targets = []) => {
+            const record = { kind: 'implementationGaps', reason: `Static call: ${reason}`,
+                provenance: [syntaxSpan(node, file.source, file.digest, context.commitSha)],
+                relatedNodeIds: [...new Set([physical.id, caller.node.id, ...targets.map(n => n.id)])].sort(), evidenceScope: 'source' };
+            diagnostics.push({ ...record, id: sha256(stableJson({ ...record, extractor: staticCallIdentity })) });
+        };
+        if (file.parseErrors.length) {
+            gap(file.source, { node: physical, definitions: [] }, 'TypeScript syntax errors prevent call analysis in this indexed document.');
+            continue;
+        }
+        const emit = (node, caller) => {
+            const token = calleeToken(node.expression), selected = factsAt(token, file, context.commitSha, 'reference');
+            const targets = [...new Map(selected.map(f => [f.object.id, f.object])).values()];
+            if (caller.unresolved) {
+                gap(node, caller, 'Enclosing anonymous callable or initializer has no exact indexed callable identity.', targets);
+                return;
+            }
+            if (targets.length !== 1) {
+                gap(node, caller, 'Callee expression has no single exact indexed target; dynamic dispatch is unresolved.', targets);
+                return;
+            }
+            const target = targets[0], defs = definitions.get(target.id) ?? [], targetKinds = kinds.get(target.id);
+            const syntax = ts.isNewExpression(node) ? 'construct' : 'call';
+            const resolution = targetResolution(syntax, defs, targetKinds);
+            if (!resolution) {
+                gap(node, caller, 'Indexed value is not a known callable body or declaration; value flow, callbacks and dispatch are unresolved.', [target]);
+                return;
+            }
+            const call = { schemaVersion: 1, method: 'typescript-ast+scip', syntax,
+                dispatch: syntax === 'construct' ? 'construct' : token && (ts.isPropertyAccessExpression(token.parent) || ts.isElementAccessExpression(token.parent)) ? 'member' : 'lexical',
+                optional: Boolean(node.flags & ts.NodeFlags.OptionalChain), caller: caller.definitions.length ? 'indexed-callable' : 'file-scope',
+                target: resolution, runtime: 'not-observed', callerDefinitions: caller.definitions.map(proof),
+                targetOccurrences: selected.map(proof), targetDefinitions: defs.map(proof) };
+            const fact = { subject: caller.node, predicate: 'calls', object: target,
+                provenance: syntaxSpan(node, file.source, file.digest, context.commitSha), codeCall: call,
+                extractor: staticCallIdentity, authority: 'implemented', extractionReview: 'deterministic', confidence: 1 };
+            facts.push({ ...fact, id: sha256(stableJson(fact)), snapshotId: context.snapshotId });
+            if (resolution === 'external' || resolution === 'declaration-only')
+                gap(node, caller, 'The selected declaration has no indexed callable body; runtime implementation remains unknown.', [target]);
+        };
+        const walk = (node, caller) => {
+            // Ambient declarations describe types; decorators/default syntax there is not executed.
+            if (ts.canHaveModifiers(node) && ts.getModifiers(node)?.some(modifier => modifier.kind === ts.SyntaxKind.DeclareKeyword))
+                return;
+            if (isCallable(node)) {
+                const defs = factsAt(callableName(node), file, context.commitSha, 'definition');
+                const ids = new Set(defs.map(f => f.subject.id));
+                const inner = ids.size === 1 ? { node: defs[0].subject, definitions: defs }
+                    : { node: caller.node, definitions: [], unresolved: true };
+                // Decorators/computed names execute in the outer context, not in the function body.
+                ts.forEachChild(node, child => {
+                    if (ts.isParameter(child))
+                        ts.forEachChild(child, part => walk(part, part === child.initializer ? inner : caller));
+                    else
+                        walk(child, child === node.body ? inner : caller);
+                });
+                return;
+            }
+            if (ts.isPropertyDeclaration(node) && node.initializer) {
+                ts.forEachChild(node, child => walk(child, child === node.initializer ? { node: caller.node, definitions: [], unresolved: true } : caller));
+                return;
+            }
+            if (ts.isClassStaticBlockDeclaration(node)) {
+                ts.forEachChild(node, child => walk(child, { node: caller.node, definitions: [], unresolved: true }));
+                return;
+            }
+            if (ts.isCallExpression(node) || ts.isNewExpression(node))
+                emit(node, caller);
+            ts.forEachChild(node, child => walk(child, caller));
+        };
+        if (!file.source.isDeclarationFile)
+            walk(file.source, { node: physical, definitions: [] });
+    }
+    return { facts: facts.sort((a, b) => a.id.localeCompare(b.id)), diagnostics: diagnostics.sort((a, b) => a.id.localeCompare(b.id)) };
+}

package/dist/extraction/static.d.ts

@@ -1,12 +1,8 @@
 import type { ContextGraphConfig } from "../configuration/config.js";
 import { type ExtractionContext, type FactExtractor, type GraphFact } from "@weftlet/core";
 import { GitRepository } from "../repository/git.js";
-export interface ScipIndexResult {
-    readonly path: string;
-    readonly digest: string;
-    readonly mode: 'full' | 'package';
-    readonly version: string;
-}
+import type { ScipIndexResult } from './scip-runtime.js';
+export type { ScipIndexResult } from './scip-runtime.js';
 export interface StaticIndexer {
     index(context: ExtractionContext): Promise<ScipIndexResult>;
 }
@@ -17,20 +13,7 @@ export declare class ScipTypeScriptIndexer implements StaticIndexer {
     index(context: ExtractionContext): Promise<ScipIndexResult>;
 }
 export declare function normalizeScipCheckout(bytes: Uint8Array, checkoutRoot: string): Uint8Array;
-export declare const scipSymbolExtractorIdentity: {
-    readonly id: "scip-symbol-extractor";
-    readonly version: "1.1.0";
-};
-export declare class ScipSymbolExtractor implements FactExtractor {
-    private readonly repository;
-    private readonly index;
-    readonly identity: {
-        readonly id: "scip-symbol-extractor";
-        readonly version: "1.1.0";
-    };
-    constructor(repository: GitRepository, index: ScipIndexResult);
-    extract(context: ExtractionContext): Promise<readonly GraphFact[]>;
-}
+export { ScipSymbolExtractor, scipSymbolExtractorIdentity } from './scip-symbols.js';
 export declare const repositoryFileExtractorIdentity: {
     readonly id: "repository-file-extractor";
     readonly version: "2.0.0";

package/dist/extraction/static.js

@@ -1,9 +1,8 @@
 // Modified for standalone extraction; see docs/extraction-manifest.json.
-import { randomUUID } from 'node:crypto';
 import { withCommittedTree } from "../repository/committed-tree.js";
-import { copyFile, mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { copyFile, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
-import { dirname, join } from 'node:path';
+import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { repositoryFileNode } from "@weftlet/core";
 import { GitRepository } from "../repository/git.js";
@@ -13,6 +12,8 @@ import { moduleRequestNode } from './module-request.js';
 import { matchesRepositoryGlob } from "../repository/glob.js";
 import { runProcess } from "../infrastructure/process.js";
 import { sha256, stableJson } from "../infrastructure/util.js";
+import { loadScipRuntime } from './scip-runtime.js';
+import { physicalArtifactKey, temporaryArtifactPath } from '../infrastructure/artifact-paths.js';
 export class ScipTypeScriptIndexer {
     config;
     storageRoot;
@@ -26,9 +27,9 @@ export class ScipTypeScriptIndexer {
             assertSourceProjectInvocation(this.config.command, this.config.args);
         }
         const require = createRequire(import.meta.url);
-        const destination = join(this.storageRoot, 'scip', `${context.snapshotId}.scip`);
+        const destination = join(this.storageRoot, 'scip', `${physicalArtifactKey(context.snapshotId)}.scip`);
         await mkdir(join(this.storageRoot, 'scip'), { recursive: true });
-        const temporary = `${destination}.${randomUUID()}.tmp`;
+        const temporary = temporaryArtifactPath(destination);
         const command = this.config.command === 'bundled-scip-typescript' ? process.execPath : this.config.command;
         const args = this.config.command === 'bundled-scip-typescript'
             ? [
@@ -38,36 +39,40 @@ export class ScipTypeScriptIndexer {
                 temporary,
             ]
             : this.config.args;
-        await withCommittedTree(context.repositoryRoot, context.commitSha, async (worktreeRoot) => {
-            const project = this.config.sourceProject ? await prepareScipSourceProject(worktreeRoot, this.config.sourceProject, await new GitRepository(context.repositoryRoot).listAllFilesAt(context.commitSha)) : undefined;
-            await runProcess(command, project ? [...args, project] : args, worktreeRoot, {
-                ...process.env,
-                NODE_OPTIONS: process.env.NODE_OPTIONS ?? '--max-old-space-size=8192',
+        try {
+            await withCommittedTree(context.repositoryRoot, context.commitSha, async (worktreeRoot) => {
+                const project = this.config.sourceProject ? await prepareScipSourceProject(worktreeRoot, this.config.sourceProject, await new GitRepository(context.repositoryRoot).listAllFilesAt(context.commitSha)) : undefined;
+                await runProcess(command, project ? [...args, project] : args, worktreeRoot, {
+                    ...process.env,
+                    NODE_OPTIONS: process.env.NODE_OPTIONS ?? '--max-old-space-size=8192',
+                });
+                const source = this.config.command === 'bundled-scip-typescript'
+                    ? temporary
+                    : join(worktreeRoot, 'index.scip');
+                await stat(source);
+                if (source !== temporary)
+                    await copyFile(source, temporary);
+                // SCIP embeds this disposable checkout in metadata and inferred-type hover text.
+                // Store the normalized artifact itself so its digest still authenticates its bytes.
+                await writeFile(temporary, normalizeScipCheckout(await readFile(temporary), worktreeRoot));
             });
-            const source = this.config.command === 'bundled-scip-typescript'
-                ? temporary
-                : join(worktreeRoot, 'index.scip');
-            await stat(source);
-            if (source !== temporary)
-                await copyFile(source, temporary);
-            // SCIP embeds this disposable checkout in metadata and inferred-type hover text.
-            // Store the normalized artifact itself so its digest still authenticates its bytes.
-            await writeFile(temporary, normalizeScipCheckout(await readFile(temporary), worktreeRoot));
-        });
-        await rename(temporary, destination);
+            await rename(temporary, destination);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+        const bytes = await readFile(destination);
+        const indexedPaths = [...new Set(loadScipRuntime().scip.Index.deserializeBinary(bytes).documents
+                .map(document => document.relative_path.replaceAll('\\', '/')))].sort();
         return {
             path: destination,
-            digest: sha256(await readFile(destination)),
+            digest: sha256(bytes),
             mode: 'full',
             version: this.config.version,
+            indexedPaths,
         };
     }
 }
-function loadScipRuntime() {
-    const require = createRequire(import.meta.url);
-    const main = require.resolve('@sourcegraph/scip-typescript');
-    return require(join(dirname(main), 'scip.js'));
-}
 export function normalizeScipCheckout(bytes, checkoutRoot) {
     const runtime = loadScipRuntime();
     const roots = [pathToFileURL(checkoutRoot).href, checkoutRoot.replace(/\\/g, '/'), checkoutRoot];
@@ -91,83 +96,7 @@ export function normalizeScipCheckout(bytes, checkoutRoot) {
     }
     return index.serializeBinary();
 }
-export const scipSymbolExtractorIdentity = { id: 'scip-symbol-extractor', version: '1.1.0' };
-export class ScipSymbolExtractor {
-    repository;
-    index;
-    identity = scipSymbolExtractorIdentity;
-    constructor(repository, index) {
-        this.repository = repository;
-        this.index = index;
-    }
-    async extract(context) {
-        const parsed = loadScipRuntime().scip.Index.deserializeBinary(await readFile(this.index.path));
-        const symbols = new Map();
-        for (const document of parsed.documents) {
-            const path = document.relative_path.replace(/\\/g, '/');
-            const content = await this.repository.readFileAt(context.commitSha, path);
-            const digest = sha256(content);
-            const component = repositoryFileNode(path);
-            for (const occurrence of document.occurrences) {
-                if (!occurrence.symbol || occurrence.symbol.startsWith('local '))
-                    continue;
-                const definition = (occurrence.symbol_roles & 1) === 1;
-                const sites = symbols.get(occurrence.symbol) ?? {
-                    definitions: new Map(),
-                    references: new Map(),
-                };
-                symbols.set(occurrence.symbol, sites);
-                const target = definition ? sites.definitions : sites.references;
-                if (target.has(path))
-                    continue;
-                target.set(path, {
-                    path,
-                    line: (occurrence.range[0] ?? 0) + 1,
-                    digest,
-                    component,
-                });
-            }
-        }
-        const facts = [];
-        for (const [symbolText, sites] of [...symbols.entries()].sort(([left], [right]) => left.localeCompare(right))) {
-            const definitionPaths = new Set(sites.definitions.keys());
-            const downstream = [...sites.references.values()].filter((site) => !definitionPaths.has(site.path));
-            if (sites.definitions.size === 0 || downstream.length === 0)
-                continue;
-            const symbol = {
-                id: `symbol:scip:${sha256(symbolText)}`,
-                kind: 'Contract',
-                label: symbolText,
-                attributes: { scipIndexDigest: this.index.digest },
-            };
-            const relationships = [
-                ...[...sites.definitions.values()].map((site) => ({ site, definition: true })),
-                ...downstream.map((site) => ({ site, definition: false })),
-            ];
-            for (const { site, definition } of relationships) {
-                const relation = definition ? 'definition' : 'reference';
-                const provenance = {
-                    path: site.path,
-                    startLine: site.line,
-                    endLine: site.line,
-                    digest: site.digest,
-                    commitSha: context.commitSha,
-                };
-                facts.push({
-                    id: sha256(stableJson({ relation, path: site.path, symbol: symbolText, provenance })),
-                    subject: site.component,
-                    predicate: definition ? 'contains' : 'consumes',
-                    object: symbol,
-                    provenance,
-                    extractor: this.identity,
-                    confidence: 1,
-                    snapshotId: context.snapshotId,
-                });
-            }
-        }
-        return facts;
-    }
-}
+export { ScipSymbolExtractor, scipSymbolExtractorIdentity } from './scip-symbols.js';
 export const repositoryFileExtractorIdentity = { id: 'repository-file-extractor', version: '2.0.0' };
 export class RepositoryFileExtractor {
     repository;

package/dist/extraction/symbol-resolution.d.ts

@@ -0,0 +1,12 @@
+import type { DocumentCodeBinding, GraphFact, GraphNode } from '@weftlet/core';
+type Selector = DocumentCodeBinding['selector'];
+export type SymbolResolution = {
+    readonly node: GraphNode;
+    readonly selected: readonly GraphFact[];
+    readonly definitions: readonly GraphFact[];
+} | {
+    readonly problem: string;
+    readonly candidates: readonly string[];
+};
+export declare function resolveSymbolSelector(selector: Selector, facts: readonly GraphFact[], sourceText: string): SymbolResolution;
+export {};

package/dist/extraction/symbol-resolution.js

@@ -0,0 +1,51 @@
+import { stableJson } from '../infrastructure/util.js';
+function occurrenceNode(fact) {
+    return fact.codeOccurrence?.role === 'definition' ? fact.subject : fact.object;
+}
+function textAt(span, text) {
+    const lines = text.split('\n');
+    if (!span.startColumn || !span.endColumn || span.columnEncoding !== 'utf-16' || span.startLine !== span.endLine)
+        return undefined;
+    return lines[span.startLine - 1]?.slice(span.startColumn - 1, span.endColumn - 1);
+}
+/** Qualification follows indexed lexical parents only; absent or conflicting parents are never invented. */
+function qualifiedName(fact, localDefinitions, seen = new Set()) {
+    const node = occurrenceNode(fact), parentId = fact.codeOccurrence?.enclosingSymbolId;
+    if (seen.has(node.id) || seen.size >= 64)
+        return undefined;
+    if (!parentId)
+        return node.label;
+    const parents = localDefinitions.get(parentId) ?? [];
+    if (!parents.length)
+        return undefined;
+    const named = parents.filter(candidate => candidate.codeOccurrence?.locationKind !== 'zero-width-anchor');
+    if (!named.length)
+        return node.label;
+    const names = new Set(named.map(parent => qualifiedName(parent, localDefinitions, new Set([...seen, node.id]))));
+    return names.size === 1 && !names.has(undefined) ? `${[...names][0]}.${node.label}` : undefined;
+}
+export function resolveSymbolSelector(selector, facts, sourceText) {
+    const local = facts.filter(fact => fact.codeOccurrence && fact.provenance.path === selector.path);
+    const definitions = local.filter(fact => fact.codeOccurrence.role === 'definition' && fact.codeOccurrence.locationKind === 'name');
+    const parents = new Map();
+    for (const fact of local.filter(item => item.codeOccurrence.role === 'definition')) {
+        const entries = parents.get(fact.subject.id) ?? [];
+        entries.push(fact);
+        parents.set(fact.subject.id, entries);
+    }
+    const selected = selector.line !== undefined
+        ? local.filter(fact => fact.provenance.startLine === selector.line && fact.provenance.startColumn === selector.column &&
+            (occurrenceNode(fact).id === selector.symbol || textAt(fact.provenance, sourceText) === selector.symbol))
+        : definitions.filter(fact => fact.subject.id === selector.symbol || fact.subject.label === selector.symbol ||
+            qualifiedName(fact, parents) === selector.symbol);
+    const identities = [...new Set(selected.map(fact => occurrenceNode(fact).id))].sort();
+    if (identities.length !== 1)
+        return { problem: identities.length ? 'Ambiguous indexed symbol; use a qualified name or exact occurrence.'
+                : 'No indexed symbol matches this exact selector; no name, path, alias or line was guessed.', candidates: identities };
+    const target = occurrenceNode(selected[0]);
+    const resolved = facts.filter(fact => fact.codeOccurrence?.role === 'definition' && fact.subject.id === target.id);
+    if (!resolved.length)
+        return { problem: 'The occurrence has no indexed definition; implementation is unresolved in this saved scope.', candidates: identities };
+    const sorted = (items) => [...items].sort((a, b) => stableJson(a.provenance).localeCompare(stableJson(b.provenance)) || a.id.localeCompare(b.id));
+    return { node: target, selected: sorted(selected), definitions: sorted(resolved) };
+}

package/dist/extraction/symbol-selectors.d.ts

@@ -0,0 +1,11 @@
+import type { CanonicalDocumentLink } from './canonical-document-links.js';
+import type { DocumentCodeBinding } from '@weftlet/core';
+export interface SymbolLink {
+    readonly link: CanonicalDocumentLink;
+    readonly selector?: DocumentCodeBinding['selector'];
+    readonly subjectId?: string;
+    readonly predicate: 'references' | 'implementedBy' | 'verifiedBy';
+    readonly problem?: string;
+}
+/** Only the explicit weftlet-symbol fragment opts a link in; ordinary headings keep their existing meaning. */
+export declare function documentSymbolLinks(sourcePath: string, content: string): readonly SymbolLink[];