@weftlet/toolkit 0.6.1 → 0.7.1

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

@@ -2,7 +2,7 @@
 import { withCommittedTree } from "../repository/committed-tree.js";
 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";
@@ -12,6 +12,7 @@ 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;
@@ -60,19 +61,18 @@ export class ScipTypeScriptIndexer {
         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];
@@ -96,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[];

package/dist/extraction/symbol-selectors.js

@@ -0,0 +1,51 @@
+import { canonicalDocumentLinks, resolveCanonicalDocumentLink } from './canonical-document-links.js';
+const keys = new Set(['weftlet-symbol', 'weftlet-line', 'weftlet-column']);
+const positive = (value) => value !== null && /^[1-9][0-9]*$/.test(value) && Number.isSafeInteger(Number(value));
+/** Only the explicit weftlet-symbol fragment opts a link in; ordinary headings keep their existing meaning. */
+export function documentSymbolLinks(sourcePath, content) {
+    const result = [];
+    for (const link of canonicalDocumentLinks(content, { includeTitles: true })) {
+        const targets = link.kind === 'ambiguous-reference' ? link.definitions?.map(definition => definition.target) ?? [] : [link.target ?? ''];
+        if (!targets.some(target => /#weftlet-symbol(?:=|&|$)/.test(target)))
+            continue;
+        const fail = (problem) => result.push({ link, predicate: 'references', problem });
+        if (link.kind === 'ambiguous-reference') {
+            fail('Conflicting reference definitions; no symbol binding selected.');
+            continue;
+        }
+        const target = link.target;
+        const path = resolveCanonicalDocumentLink(sourcePath, target);
+        if (path.kind !== 'path' || path.directoryHint || target.split('#')[0].includes('?')) {
+            fail('Symbol link must name an exact repository file.');
+            continue;
+        }
+        const parsed = selectorFragment(target);
+        if ('problem' in parsed) {
+            fail(parsed.problem);
+            continue;
+        }
+        const annotation = link.title;
+        const match = annotation?.match(/^weftlet:(implementedBy|verifiedBy) ([^\s]+)$/);
+        if (annotation?.startsWith('weftlet:') && !match) {
+            fail('Invalid mapping annotation; expected weftlet:implementedBy or weftlet:verifiedBy and an exact subject ID.');
+            continue;
+        }
+        result.push({ link, selector: { path: path.path, ...parsed },
+            predicate: match ? match[1] : 'references', ...(match ? { subjectId: match[2] } : {}) });
+    }
+    return result;
+}
+function selectorFragment(target) {
+    const fragment = target.slice(target.indexOf('#') + 1);
+    if (/%(?![a-f0-9]{2})/i.test(fragment))
+        return { problem: 'Malformed percent encoding in symbol selector.' };
+    const params = new URLSearchParams(fragment);
+    const symbol = params.get('weftlet-symbol');
+    const line = params.get('weftlet-line'), column = params.get('weftlet-column');
+    if ([...params.keys()].some(key => !keys.has(key) || params.getAll(key).length !== 1) ||
+        !symbol || symbol !== symbol.trim() || symbol.length > 2048 || /[\x00-\x1f\x7f-\x9f\uFFFD]/.test(symbol) ||
+        ((line !== null || column !== null) && (!positive(line) || !positive(column)))) {
+        return { problem: 'Invalid symbol selector; use one symbol and optionally both positive line and column.' };
+    }
+    return { symbol, ...(line !== null ? { line: Number(line), column: Number(column) } : {}) };
+}

package/dist/graph/binding-rdf.d.ts

@@ -0,0 +1,7 @@
+import { type Store, type NamedNode } from 'n3';
+import type { GraphFact } from '@weftlet/core';
+export declare function addBindingEvidence(dataset: Store, record: NamedNode, fact: GraphFact, factIri: (id: string) => string): void;
+type FactsById = ReadonlyMap<string, GraphFact>;
+/** Supplements shape validation by comparing proofs with the actual same-snapshot assertions. */
+export declare function bindingEvidenceIssues(fact: GraphFact, byId: FactsById): readonly string[];
+export {};

package/dist/graph/binding-rdf.js

@@ -0,0 +1,109 @@
+import { DataFactory } from 'n3';
+import { stableJson } from '../infrastructure/util.js';
+import { CG, RDF, XSD } from './shacl-shapes.js';
+import { invalidCodeRange } from './code-rdf.js';
+const { namedNode: iri, literal } = DataFactory;
+export function addBindingEvidence(dataset, record, fact, factIri) {
+    const binding = fact.codeBinding;
+    if (!binding)
+        return;
+    const prop = (node, key, value) => {
+        if (value !== undefined)
+            dataset.addQuad(node, iri(CG + key), literal(String(value), iri(XSD + (typeof value === 'number' ? 'integer' : 'string'))));
+    };
+    dataset.addQuad(record, iri(RDF + 'type'), iri(CG + 'DocumentCodeBinding'));
+    prop(record, 'bindingVersion', binding.schemaVersion);
+    prop(record, 'bindingMethod', binding.method);
+    for (const [key, value] of Object.entries(binding.selector ?? {}))
+        prop(record, `bindingSelector/${key}`, value);
+    const citations = (key, spans, proofs) => spans.forEach((span, index) => {
+        const term = iri(`${record.value}:${key}:${index}`);
+        dataset.addQuad(record, iri(CG + key), term);
+        dataset.addQuad(term, iri(RDF + 'type'), iri(CG + 'BindingCitation'));
+        for (const [name, value] of Object.entries(span))
+            prop(term, name, value);
+        if (proofs)
+            dataset.addQuad(term, iri(CG + 'bindingFact'), iri(factIri(proofs[index].factId)));
+    });
+    citations('bindingDocument', binding.documentCitations ?? []);
+    citations('bindingSelection', (binding.selectedOccurrences ?? []).map(item => item.provenance), binding.selectedOccurrences);
+    citations('bindingDefinition', (binding.definitions ?? []).map(item => item.provenance), binding.definitions);
+    citations('bindingSubject', (binding.subjectEvidence ?? []).map(item => item.provenance), binding.subjectEvidence);
+}
+function proofIssues(proof, byId) {
+    const issues = [], original = byId.get(proof.factId);
+    if (!original || stableJson(original.provenance) !== stableJson(proof.provenance))
+        issues.push('Binding proof is absent or has different provenance');
+    if (invalidCodeRange(proof.provenance) || proof.provenance.endLine < proof.provenance.startLine)
+        issues.push('Invalid binding proof range');
+    return issues;
+}
+function selectionIssues(proof, fact, byId) {
+    const issues = [...proofIssues(proof, byId)], original = byId.get(proof.factId);
+    const selector = fact.codeBinding.selector;
+    if (!original?.codeOccurrence)
+        return [...issues, 'Binding selection must cite an indexed occurrence'];
+    const target = original.codeOccurrence.role === 'definition' ? original.subject : original.object;
+    if (target.id !== fact.object.id || proof.provenance.path !== selector?.path)
+        issues.push('Binding selection does not identify the target symbol in its selected file');
+    if (selector?.line !== undefined && (selector.line !== proof.provenance.startLine || selector.column !== proof.provenance.startColumn))
+        issues.push('Binding selected occurrence differs from its exact selector');
+    if (selector?.line === undefined && original.codeOccurrence.role !== 'definition')
+        issues.push('A name selector requires a definition');
+    if (proof.provenance.commitSha !== fact.provenance.commitSha)
+        issues.push('Binding selection uses another revision');
+    return issues;
+}
+function definitionIssues(proof, fact, byId) {
+    const issues = [...proofIssues(proof, byId)], original = byId.get(proof.factId);
+    if (original?.codeOccurrence?.role !== 'definition' || original.subject.id !== fact.object.id)
+        issues.push('Binding definition does not define its target symbol');
+    if (proof.provenance.commitSha !== fact.provenance.commitSha)
+        issues.push('Binding definition uses another revision');
+    return issues;
+}
+function subjectIssues(proof, fact, byId) {
+    const issues = [...proofIssues(proof, byId)], original = byId.get(proof.factId);
+    if (!original || ![original.subject, original.object].some(node => node.id === fact.subject.id) ||
+        original.authority !== proof.authority || original.sourceAuthority !== proof.sourceAuthority || original.extractionReview !== proof.extractionReview) {
+        issues.push('Binding subject evidence or its authority was changed');
+    }
+    return issues;
+}
+function documentIssues(fact) {
+    const documents = fact.codeBinding.documentCitations ?? [];
+    if (!documents.some(span => stableJson(span) === stableJson(fact.provenance)) || documents.some(span => span.path !== fact.provenance.path || span.digest !== fact.provenance.digest || span.commitSha !== fact.provenance.commitSha ||
+        span.endLine < span.startLine || invalidCodeRange(span)))
+        return ['Binding document citations do not match their source'];
+    return [];
+}
+function mappingIssues(fact) {
+    const binding = fact.codeBinding, issues = [];
+    if (fact.predicate !== 'references' && !(binding.subjectEvidence?.length))
+        issues.push('Business mapping requires cited subject evidence');
+    if (fact.predicate !== 'references' && !['Capability', 'Workflow', 'Contract', 'Invariant'].includes(fact.subject.kind))
+        issues.push('Business mapping requires a business subject');
+    if (fact.authority === 'draft' && fact.sourceAuthority !== 'draft')
+        issues.push('Draft bindings require draft source authority');
+    if (fact.sourceRole === 'validation' && fact.predicate === 'implementedBy')
+        issues.push('Validation evidence cannot establish an implementation mapping');
+    if (binding.subjectEvidence?.some(proof => proof.extractionReview === 'unreviewed') && fact.extractionReview !== 'unreviewed')
+        issues.push('Binding cannot approve unreviewed subject evidence');
+    return issues;
+}
+/** Supplements shape validation by comparing proofs with the actual same-snapshot assertions. */
+export function bindingEvidenceIssues(fact, byId) {
+    const binding = fact.codeBinding;
+    if (!binding)
+        return [];
+    const issues = [...documentIssues(fact), ...mappingIssues(fact)], selector = binding.selector;
+    const positive = (n) => typeof n === 'number' && Number.isSafeInteger(n) && n > 0;
+    if ((selector?.line !== undefined || selector?.column !== undefined) && (!positive(selector.line) || !positive(selector.column))) {
+        issues.push('Exact occurrence selectors require positive line and column');
+    }
+    return [...issues,
+        ...(binding.selectedOccurrences ?? []).flatMap(proof => selectionIssues(proof, fact, byId)),
+        ...(binding.definitions ?? []).flatMap(proof => definitionIssues(proof, fact, byId)),
+        ...(binding.subjectEvidence ?? []).flatMap(proof => subjectIssues(proof, fact, byId)),
+    ];
+}

package/dist/graph/call-rdf.d.ts

@@ -0,0 +1,4 @@
+import { type Store, type NamedNode } from 'n3';
+import { type GraphFact } from '@weftlet/core';
+export declare function addCallEvidence(dataset: Store, record: NamedNode, fact: GraphFact, factIri: (id: string) => string): void;
+export declare function callEvidenceIssues(fact: GraphFact, byId: ReadonlyMap<string, GraphFact>): readonly string[];

package/dist/graph/call-rdf.js

@@ -0,0 +1,94 @@
+import { DataFactory } from 'n3';
+import { repositoryFileNode } from '@weftlet/core';
+import { CG, RDF, XSD } from './shacl-shapes.js';
+import { stableJson } from '../infrastructure/util.js';
+import { invalidCodeRange } from './code-rdf.js';
+const { namedNode: iri, literal } = DataFactory;
+function containsRange(outer, inner) {
+    const compare = (a, b, c, d) => a - c || (b ?? 0) - (d ?? 0);
+    return compare(outer.startLine, outer.startColumn, inner.startLine, inner.startColumn) <= 0 &&
+        compare(outer.endLine, outer.endColumn, inner.endLine, inner.endColumn) >= 0;
+}
+export function addCallEvidence(dataset, record, fact, factIri) {
+    const call = fact.codeCall;
+    if (!call && fact.predicate !== 'calls')
+        return;
+    // Type calls even when metadata is missing so SHACL rejects them without a global OR scan.
+    dataset.addQuad(record, iri(RDF + 'type'), iri(CG + 'CodeCall'));
+    if (!call)
+        return;
+    const prop = (node, key, value) => {
+        if (value !== undefined)
+            dataset.addQuad(node, iri(CG + key), literal(String(value), iri(XSD +
+                (typeof value === 'number' ? 'integer' : typeof value === 'boolean' ? 'boolean' : 'string'))));
+    };
+    for (const [key, value] of Object.entries({ callVersion: call.schemaVersion, callMethod: call.method,
+        callSyntax: call.syntax, callDispatch: call.dispatch, callOptional: call.optional, callCaller: call.caller,
+        callTarget: call.target, callRuntime: call.runtime }))
+        prop(record, key, value);
+    const proofs = (key, values) => values.forEach((proof, index) => {
+        const term = iri(`${record.value}:${key}:${index}`);
+        dataset.addQuad(record, iri(CG + key), term);
+        dataset.addQuad(term, iri(RDF + 'type'), iri(CG + 'CallProof'));
+        dataset.addQuad(term, iri(CG + 'callFact'), iri(factIri(proof.factId)));
+        for (const [key, value] of Object.entries(proof.provenance))
+            prop(term, key, value);
+    });
+    proofs('callCallerDefinition', call.callerDefinitions ?? []);
+    proofs('callOccurrence', call.targetOccurrences ?? []);
+    proofs('callTargetDefinition', call.targetDefinitions ?? []);
+}
+function proofIssues(fact, proof, byId, role, nodeId) {
+    const issues = [];
+    const original = byId.get(proof.factId);
+    if (!original || stableJson(original.provenance) !== stableJson(proof.provenance) || original.codeOccurrence?.role !== role ||
+        (role === 'definition' ? original.subject.id : original.object.id) !== nodeId ||
+        proof.provenance.commitSha !== fact.provenance.commitSha || invalidCodeRange(proof.provenance)) {
+        issues.push('Call proof is missing, changed, from another revision or does not identify its endpoint');
+    }
+    return issues;
+}
+function occurrenceIssues(fact, proof, byId) {
+    const issues = proofIssues(fact, proof, byId, 'reference', fact.object.id);
+    if (proof.provenance.path !== fact.provenance.path || proof.provenance.digest !== fact.provenance.digest ||
+        !containsRange(fact.provenance, proof.provenance))
+        issues.push('Target occurrence must lie within the cited call site');
+    return issues;
+}
+function callerIssues(fact, byId) {
+    const call = fact.codeCall, callers = call.callerDefinitions ?? [], issues = [];
+    if (call.caller !== 'indexed-callable') {
+        if (callers.length || fact.subject.id !== repositoryFileNode(fact.provenance.path).id)
+            issues.push('File-scope calls require their canonical physical file');
+        return issues;
+    }
+    if (!callers.length || fact.subject.kind !== 'CodeSymbol')
+        issues.push('Indexed caller requires callable definition evidence');
+    for (const proof of callers) {
+        issues.push(...proofIssues(fact, proof, byId, 'definition', fact.subject.id));
+        if (proof.provenance.path !== fact.provenance.path || proof.provenance.digest !== fact.provenance.digest)
+            issues.push('Caller and call site must share source bytes');
+    }
+    return issues;
+}
+export function callEvidenceIssues(fact, byId) {
+    const call = fact.codeCall;
+    if (!call)
+        return fact.predicate === 'calls' ? ['A call requires static syntax and indexed proof metadata'] : [];
+    const issues = [];
+    if (fact.codeBinding || fact.codeOccurrence)
+        issues.push('A call assertion must remain separate from its supporting reference');
+    const targets = call.targetDefinitions ?? [], occurrences = call.targetOccurrences ?? [];
+    issues.push(...callerIssues(fact, byId));
+    if ((call.target === 'external') !== (targets.length === 0))
+        issues.push('Call target resolution disagrees with its indexed definitions');
+    if (call.target === 'indexed-class' && call.syntax !== 'construct')
+        issues.push('A class target requires construction syntax');
+    if ((call.syntax === 'construct') !== (call.dispatch === 'construct'))
+        issues.push('Construction and dispatch disagree');
+    for (const proof of targets)
+        issues.push(...proofIssues(fact, proof, byId, 'definition', fact.object.id));
+    for (const proof of occurrences)
+        issues.push(...occurrenceIssues(fact, proof, byId));
+    return issues;
+}