reverseport 0.0.0-stage → 1.2.0

package/dist/domain/javascript/javascriptSemanticPromises.js

@@ -0,0 +1,321 @@
+import * as t from "@babel/types";
+import { semanticCallableIdForNode } from "./javascriptSemanticProjection.js";
+import { semanticStaticPropertyName, unwrapJavaScriptExpression, } from "./javascriptAstValues.js";
+import { resolveSemanticBindingState, semanticResolutionBlocked, } from "./javascriptSemanticState.js";
+import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
+import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
+import { range } from "./javascriptStaticAnalysisHelpers.js";
+import { assignedSemanticResultBindings, dataEffectMemberCallee, scalarAssignedResultBinding, } from "./javascriptSemanticDataEffectHelpers.js";
+/** Recover explicit Promise construction, chaining, aggregation, and ownership. */
+export const collectJavaScriptSemanticPromises = (program, state, callables) => {
+    const candidates = collectCandidates(program, state, callables);
+    const returnSiteIdFor = createReturnSiteLookup(callables);
+    const candidateByNode = new WeakMap();
+    for (const candidate of candidates)
+        candidateByNode.set(candidate.node, candidate);
+    return candidates.map((candidate) => {
+        const ownership = promiseOwnership(candidate, candidateByNode, state, returnSiteIdFor);
+        const sources = promiseSources(candidate, candidateByNode, state);
+        return {
+            promiseId: candidate.promiseId,
+            kind: candidate.kind,
+            method: candidate.method,
+            location: range(candidate.node),
+            ownerCallableId: candidate.ownerCallableId,
+            ...ownership,
+            sourcePromiseIds: [...new Set(sources.promiseIds)].sort(compareUnicodeCodePoints),
+            sourceResolution: sources.status,
+        };
+    });
+};
+const collectCandidates = (program, state, callables) => {
+    const output = [];
+    const admittedCallables = new Set(callables.map(({ callableId }) => callableId));
+    const callableStack = [];
+    const ancestors = [];
+    traverseJavaScriptAst(program, {
+        enter: (node) => {
+            const callableId = semanticCallableIdForNode(node);
+            if (callableId !== null && admittedCallables.has(callableId))
+                callableStack.push(callableId);
+            const details = promiseCandidateDetails(node, state);
+            if (details !== null) {
+                output.push({
+                    node,
+                    ...details,
+                    promiseId: semanticPromiseId(details.kind, node),
+                    ownerCallableId: callableStack.at(-1) ?? null,
+                    ancestors: [...ancestors],
+                });
+            }
+            ancestors.push(node);
+        },
+        exit: (node) => {
+            ancestors.pop();
+            const callableId = semanticCallableIdForNode(node);
+            if (callableId !== null && callableStack.at(-1) === callableId)
+                callableStack.pop();
+        },
+    });
+    return output;
+};
+const promiseCandidateDetails = (node, state) => {
+    if (t.isNewExpression(node) &&
+        t.isIdentifier(node.callee, { name: "Promise" }) &&
+        isUnshadowedGlobalPromise(node.callee, state))
+        return { kind: "constructor", method: "new" };
+    if (t.isCallExpression(node) || t.isOptionalCallExpression(node)) {
+        const member = dataEffectMemberCallee(node);
+        if (member === null)
+            return null;
+        const method = semanticStaticPropertyName(member.property, member.computed);
+        if (t.isIdentifier(member.object, { name: "Promise" }) &&
+            isUnshadowedGlobalPromise(member.object, state)) {
+            if (method === "all" || method === "allSettled")
+                return { kind: "aggregate", method };
+            if (method === "resolve" || method === "reject")
+                return { kind: "static", method };
+        }
+        if (method === "then" || method === "catch" || method === "finally")
+            return { kind: "chain", method };
+    }
+    if (t.isAwaitExpression(node) && !isPromiseProducer(node.argument, state))
+        return { kind: "awaited-expression", method: "await" };
+    return null;
+};
+const isUnshadowedGlobalPromise = (node, state) => resolveSemanticBindingState(state, node, "Promise") === undefined &&
+    !semanticResolutionBlocked(state, node, "Promise");
+const isPromiseProducer = (node, state) => promiseCandidateDetails(unwrapJavaScriptExpression(node).node, state) !==
+    null;
+const semanticPromiseId = (kind, node) => `promise:${kind}:${String(node.start ?? -1)}:${String(node.end ?? -1)}`;
+const promiseOwnership = (candidate, candidateByNode, state, returnSiteIdFor) => {
+    if (candidate.kind === "awaited-expression")
+        return emptyOwnership("awaited");
+    const context = {
+        candidate,
+        candidateByNode,
+        state,
+        returnSiteIdFor,
+    };
+    for (let index = candidate.ancestors.length - 1; index >= 0; index -= 1) {
+        const ancestor = candidate.ancestors[index];
+        if (ancestor === undefined)
+            continue;
+        const ownership = ownershipAtAncestor(ancestor, context);
+        if (ownership === "boundary")
+            break;
+        if (ownership !== null)
+            return ownership;
+    }
+    return emptyOwnership("unknown");
+};
+const ownershipAtAncestor = (ancestor, context) => {
+    const { candidate, candidateByNode, state, returnSiteIdFor } = context;
+    if (t.isAwaitExpression(ancestor))
+        return unwrapJavaScriptExpression(ancestor.argument).node === candidate.node
+            ? emptyOwnership("awaited")
+            : "boundary";
+    const outer = candidateByNode.get(ancestor);
+    if (outer !== undefined &&
+        outer.ownerCallableId === candidate.ownerCallableId &&
+        outerConsumesCandidate(outer, candidate))
+        return outer.kind === "chain"
+            ? emptyOwnership("chained")
+            : emptyOwnership("aggregated");
+    if (isUnmodeledCall(ancestor, outer))
+        return "boundary";
+    const assigned = assignedPromiseBinding(ancestor, candidate.node, state);
+    if (assigned !== undefined)
+        return {
+            ownership: "assigned",
+            ownerBindingId: assigned,
+            returnSiteId: null,
+        };
+    if (t.isReturnStatement(ancestor)) {
+        if (ancestor.argument == null ||
+            unwrapJavaScriptExpression(ancestor.argument).node !== candidate.node)
+            return "boundary";
+        return returnedPromiseOwnership(candidate.ownerCallableId, range(ancestor), returnSiteIdFor);
+    }
+    if (t.isExpressionStatement(ancestor))
+        return unwrapJavaScriptExpression(ancestor.expression).node ===
+            candidate.node
+            ? emptyOwnership("detached")
+            : "boundary";
+    const callableId = semanticCallableIdForNode(ancestor);
+    if (callableId === null || callableId !== candidate.ownerCallableId)
+        return null;
+    return t.isArrowFunctionExpression(ancestor) &&
+        unwrapJavaScriptExpression(ancestor.body).node === candidate.node
+        ? returnedPromiseOwnership(candidate.ownerCallableId, range(ancestor.body), returnSiteIdFor)
+        : "boundary";
+};
+const isUnmodeledCall = (node, candidate) => candidate === undefined &&
+    (t.isCallExpression(node) ||
+        t.isOptionalCallExpression(node) ||
+        t.isNewExpression(node));
+const assignedPromiseBinding = (ancestor, candidate, state) => {
+    if (!t.isVariableDeclarator(ancestor) && !t.isAssignmentExpression(ancestor))
+        return undefined;
+    const source = t.isVariableDeclarator(ancestor)
+        ? ancestor.init
+        : ancestor.right;
+    if (source == null)
+        return undefined;
+    if (unwrapJavaScriptExpression(source).node !== candidate)
+        return undefined;
+    return scalarAssignedResultBinding(assignedSemanticResultBindings(source, [ancestor], state));
+};
+const returnedPromiseOwnership = (callableId, location, returnSiteIdFor) => ({
+    ownership: "returned",
+    ownerBindingId: null,
+    returnSiteId: returnSiteIdFor(callableId, location),
+});
+const outerConsumesCandidate = (outer, candidate) => {
+    if (outer.kind === "chain" &&
+        (t.isCallExpression(outer.node) || t.isOptionalCallExpression(outer.node))) {
+        const member = dataEffectMemberCallee(outer.node);
+        return (member !== null &&
+            unwrapJavaScriptExpression(member.object).node === candidate.node);
+    }
+    if (outer.kind === "aggregate" &&
+        (t.isCallExpression(outer.node) || t.isOptionalCallExpression(outer.node))) {
+        const input = outer.node.arguments[0];
+        return (t.isArrayExpression(input) &&
+            input.elements.some((element) => element !== null &&
+                !t.isSpreadElement(element) &&
+                unwrapJavaScriptExpression(element).node === candidate.node));
+    }
+    return false;
+};
+const emptyOwnership = (ownership) => ({
+    ownership,
+    ownerBindingId: null,
+    returnSiteId: null,
+});
+const indexReturnSites = (callable) => {
+    const output = new Map();
+    for (const site of callable.returnSites) {
+        const key = returnSiteKey(site.location);
+        if (!output.has(key))
+            output.set(key, site.returnSiteId);
+    }
+    return output;
+};
+const createReturnSiteLookup = (callables) => {
+    let callablesById;
+    let returnSiteIdsByCallable;
+    return (callableId, location) => {
+        if (callableId === null)
+            return null;
+        callablesById ??= indexCallablesById(callables);
+        const callable = callablesById.get(callableId);
+        if (callable === undefined)
+            return null;
+        returnSiteIdsByCallable ??= new Map();
+        let returnSiteIds = returnSiteIdsByCallable.get(callableId);
+        if (returnSiteIds === undefined) {
+            returnSiteIds = indexReturnSites(callable);
+            returnSiteIdsByCallable.set(callableId, returnSiteIds);
+        }
+        return returnSiteIds.get(returnSiteKey(location)) ?? null;
+    };
+};
+const indexCallablesById = (callables) => {
+    const output = new Map();
+    for (const callable of callables) {
+        if (output.has(callable.callableId))
+            continue;
+        output.set(callable.callableId, callable);
+    }
+    return output;
+};
+const returnSiteKey = (location) => `${location.start.line}:${location.start.column}:${location.end.line}:${location.end.column}`;
+const promiseSources = (candidate, candidateByNode, state) => {
+    if (candidate.kind === "chain") {
+        const member = t.isCallExpression(candidate.node) ||
+            t.isOptionalCallExpression(candidate.node)
+            ? dataEffectMemberCallee(candidate.node)
+            : null;
+        return member === null
+            ? unresolvedPromise()
+            : resolvePromiseExpression(member.object, promiseResolutionContext(candidate, candidateByNode, state));
+    }
+    if (candidate.kind === "aggregate")
+        return aggregateSources(candidate, candidateByNode, state);
+    if (candidate.kind === "awaited-expression")
+        return t.isAwaitExpression(candidate.node)
+            ? resolvePromiseExpression(candidate.node.argument, promiseResolutionContext(candidate, candidateByNode, state))
+            : unresolvedPromise();
+    return { promiseIds: [], status: "complete" };
+};
+const aggregateSources = (candidate, candidateByNode, state) => {
+    if (!t.isCallExpression(candidate.node) &&
+        !t.isOptionalCallExpression(candidate.node))
+        return unresolvedPromise();
+    const input = candidate.node.arguments[0];
+    if (!t.isArrayExpression(input))
+        return unresolvedPromise();
+    const resolutions = input.elements.map((element) => {
+        if (element === null)
+            return completePromise();
+        if (t.isSpreadElement(element))
+            return unresolvedPromise();
+        if (isObviouslyNonPromise(element))
+            return completePromise();
+        return resolvePromiseExpression(element, promiseResolutionContext(candidate, candidateByNode, state));
+    });
+    return combinePromiseResolutions(resolutions);
+};
+const resolvePromiseExpression = (rawNode, context) => {
+    const { current, candidateByNode, state, seenBindings } = context;
+    const node = unwrapJavaScriptExpression(rawNode).node;
+    const direct = candidateByNode.get(node);
+    if (direct !== undefined && direct.promiseId !== current.promiseId)
+        return { promiseIds: [direct.promiseId], status: "complete" };
+    if (!t.isIdentifier(node))
+        return unresolvedPromise();
+    const binding = resolveSemanticBindingState(state, node, node.name);
+    if (binding === undefined ||
+        binding.mutable ||
+        binding.initializers.length !== 1 ||
+        seenBindings.has(binding.bindingId))
+        return unresolvedPromise();
+    const initializer = binding.initializers[0];
+    if (initializer === undefined || initializer.projection.length > 0)
+        return unresolvedPromise();
+    const nestedSeen = new Set(seenBindings);
+    nestedSeen.add(binding.bindingId);
+    return resolvePromiseExpression(initializer.node, {
+        ...context,
+        seenBindings: nestedSeen,
+    });
+};
+const promiseResolutionContext = (current, candidateByNode, state) => ({
+    current,
+    candidateByNode,
+    state,
+    seenBindings: new Set(),
+});
+const combinePromiseResolutions = (resolutions) => ({
+    promiseIds: resolutions.flatMap(({ promiseIds }) => promiseIds),
+    status: resolutions.some(({ status }) => status === "unresolved")
+        ? resolutions.some(({ status }) => status === "complete")
+            ? "partial"
+            : "unresolved"
+        : resolutions.some(({ status }) => status === "partial")
+            ? "partial"
+            : "complete",
+});
+const completePromise = () => ({
+    promiseIds: [],
+    status: "complete",
+});
+const unresolvedPromise = () => ({
+    promiseIds: [],
+    status: "unresolved",
+});
+const isObviouslyNonPromise = (node) => t.isLiteral(node) ||
+    t.isObjectExpression(node) ||
+    t.isFunction(node) ||
+    t.isClassExpression(node);

package/dist/domain/javascript/javascriptSemanticPropertyPaths.js

@@ -0,0 +1,100 @@
+/** Read only canonical JavaScript array indices, excluding named properties. */
+export const semanticArrayIndex = (key) => {
+    const index = Number(key);
+    return Number.isInteger(index) &&
+        index >= 0 &&
+        index < 4_294_967_295 &&
+        String(index) === String(key)
+        ? index
+        : null;
+};
+/** Test an exact key, wildcard, or copied-slot selection against an own key. */
+export const semanticPropertyPathKeyMatches = (key, name) => {
+    if (key === null)
+        return true;
+    if (typeof key !== "object")
+        return String(key) === name;
+    if (key.excludedKeys.includes(name))
+        return false;
+    if (key.startIndex === undefined)
+        return true;
+    const index = semanticArrayIndex(name);
+    return index !== null && index >= key.startIndex;
+};
+const coverageNode = () => ({
+    terminal: false,
+    exact: new Map(),
+    selectors: new Map(),
+});
+/** Index exact effect prefixes without widening distinct member paths. */
+export class SemanticPropertyPathCoverage {
+    #root = coverageNode();
+    /** Retain a path only when no previously retained prefix covers it. */
+    retain(path) {
+        if (this.covers(path))
+            return false;
+        let node = this.#root;
+        for (const key of path) {
+            if (key !== null && typeof key !== "object") {
+                const name = String(key);
+                let child = node.exact.get(name);
+                if (child === undefined) {
+                    child = coverageNode();
+                    node.exact.set(name, child);
+                }
+                node = child;
+            }
+            else {
+                const identity = JSON.stringify(key);
+                let selected = node.selectors.get(identity);
+                if (selected === undefined) {
+                    selected = { key, node: coverageNode() };
+                    node.selectors.set(identity, selected);
+                }
+                node = selected.node;
+            }
+        }
+        node.terminal = true;
+        node.exact.clear();
+        node.selectors.clear();
+        return true;
+    }
+    /** Query retained prefixes without changing the coverage index. */
+    covers(path) {
+        const pending = [{ node: this.#root, offset: 0 }];
+        while (pending.length > 0) {
+            const current = pending.pop();
+            if (current === undefined)
+                break;
+            if (current.node.terminal)
+                return true;
+            const key = path[current.offset];
+            if (key === undefined)
+                continue;
+            if (key !== null && typeof key !== "object") {
+                const exact = current.node.exact.get(String(key));
+                if (exact !== undefined)
+                    pending.push({ node: exact, offset: current.offset + 1 });
+            }
+            for (const selected of current.node.selectors.values()) {
+                if (keyCovers(selected.key, key))
+                    pending.push({ node: selected.node, offset: current.offset + 1 });
+            }
+        }
+        return false;
+    }
+}
+const keyCovers = (covering, key) => {
+    if (covering === null)
+        return true;
+    if (key === null)
+        return false;
+    if (typeof key !== "object")
+        return typeof covering === "object"
+            ? semanticPropertyPathKeyMatches(covering, String(key))
+            : String(covering) === String(key);
+    return (typeof covering === "object" &&
+        covering.excludedKeys.every((name) => key.excludedKeys.includes(name)) &&
+        (covering.startIndex === undefined ||
+            (key.startIndex !== undefined && covering.startIndex <= key.startIndex)));
+};

package/dist/domain/javascript/javascriptSemanticProvenance.js

@@ -0,0 +1,29 @@
+import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
+/** Construct exact local provenance without inventing module origins. */
+export const semanticLocalProvenance = () => ({
+    status: "local",
+    origins: [],
+    reason: null,
+});
+/** Construct an unresolved provenance outcome with an actionable reason. */
+export const semanticUnresolvedProvenance = (status, reason) => ({ status, origins: [], reason });
+/** Construct ambiguous provenance while retaining every origin. */
+export const semanticAmbiguousProvenance = (origins, reason) => ({ status: "ambiguous", origins, reason });
+/** Normalize exact module origins into one provenance classification. */
+export const semanticOriginsProvenance = (origins) => {
+    const unique = uniqueSemanticOrigins(origins);
+    const origin = unique[0];
+    return unique.length === 1 && origin !== undefined
+        ? { status: "module", origins: [origin], reason: null }
+        : semanticAmbiguousProvenance(unique, "Multiple module origins.");
+};
+/** Deduplicate and canonically order module origins. */
+export const uniqueSemanticOrigins = (origins) => [
+    ...new Map(origins.map((origin) => [semanticOriginKey(origin), origin])).values(),
+].sort((left, right) => compareUnicodeCodePoints(semanticOriginKey(left), semanticOriginKey(right)));
+const semanticOriginKey = (origin) => JSON.stringify([origin.specifier, origin.importedPath]);
+/** Canonically distinguish primitive values across type boundaries. */
+export const semanticPrimitiveKey = (value) => `${value === null ? "null" : typeof value}:${JSON.stringify(value)}`;
+/** Match namespace paths only after the caller has identified a Node built-in. */
+export const semanticBuiltinNamespacePath = (importedPath) => importedPath.length === 0 ||
+    (importedPath.length === 1 && importedPath[0] === "default");

package/dist/domain/javascript/javascriptSemanticQuery.js

@@ -0,0 +1,175 @@
+import { isJavaScriptSemanticOwnershipRelation as ownershipRelation } from "./javascriptSemanticQueryRelations.js";
+import { javaScriptSemanticQueryInputSchema, javaScriptSemanticQueryResultSchema, } from "./javascriptSemanticQuerySchemas.js";
+import { assessJavaScriptSemanticQuery } from "./javascriptSemanticQueryAssessment.js";
+import { javaScriptSemanticQueryIdentifier as queryIdentifier, resolveJavaScriptSemanticQuerySeeds as resolveSeeds, } from "./javascriptSemanticQueryIdentity.js";
+/** Run one deterministic traversal over a verified semantic graph. */
+export const queryJavaScriptSemanticGraph = (graph, rawInput) => {
+    const input = javaScriptSemanticQueryInputSchema.parse(rawInput);
+    const queryId = queryIdentifier(graph, input);
+    const seeds = resolveSeeds(graph, input);
+    const nodes = new Map(graph.nodes.map((node) => [node.node_id, node]));
+    const adjacency = buildAdjacency(graph.relations, input);
+    const traversal = traverse(nodes, seeds, adjacency);
+    const result = createQueryResult(graph, traversal);
+    const relevantUnknowns = relevantUnknownFrontiers(graph, traversal.nodeIds, input);
+    const candidateRelations = relevantCandidateRelationCount(graph, traversal.nodeIds, input);
+    const expectedMatches = expectedMatchesFor(result.retainedNodes, result.retainedRelations, input);
+    const retainedContextIds = new Set([
+        ...result.retainedNodes.map(({ evidence }) => evidence.context_id),
+        ...result.retainedRelations.map(({ evidence }) => evidence.context_id),
+        ...relevantUnknowns.map(({ evidence }) => evidence.context_id),
+    ]);
+    const assessment = assessJavaScriptSemanticQuery({
+        graph,
+        totalSeeds: seeds.length,
+        expectedMatches: expectedMatches.length,
+        hasExpectation: input.expected !== null,
+        unknowns: relevantUnknowns,
+        candidateRelations,
+    });
+    return javaScriptSemanticQueryResultSchema.parse({
+        query_id: queryId,
+        source_graph_id: graph.graph_id,
+        seed: input.seed,
+        direction: input.direction,
+        status: assessment.status,
+        seed_node_ids: seeds,
+        evidence_contexts: graph.evidence_contexts.filter(({ context_id }) => retainedContextIds.has(context_id)),
+        nodes: result.retainedNodes,
+        relations: result.retainedRelations,
+        unknowns: relevantUnknowns,
+        expected_match_node_ids: expectedMatches.map(({ node_id }) => node_id),
+        summary: {
+            total_seed_matches: seeds.length,
+            traversed_nodes: traversal.nodeIds.size,
+            traversed_relations: traversal.relationIds.size,
+            traversed_functions: traversal.functionIds.size,
+            traversed_modules: traversal.modules.size,
+            relevant_unknowns: relevantUnknowns.length,
+        },
+        coverage: assessment.coverage,
+        limitations: assessment.limitations,
+    });
+};
+const createQueryResult = (graph, traversal) => {
+    const retainedNodes = graph.nodes.filter(({ node_id }) => traversal.nodeIds.has(node_id));
+    const retainedRelations = graph.relations.filter(({ relation_id }) => traversal.relationIds.has(relation_id));
+    return { retainedNodes, retainedRelations };
+};
+const buildAdjacency = (relations, input) => {
+    const adjacency = new Map();
+    const allowed = input.allowed_relations === undefined
+        ? null
+        : new Set(input.allowed_relations);
+    for (const relation of relations) {
+        if (allowed !== null && !allowed.has(relation.relation))
+            continue;
+        if (relation.resolution === "candidate" &&
+            !input.include_ambiguous_dynamic_edges)
+            continue;
+        addDirectedEntries(adjacency, relation, input.direction);
+    }
+    return adjacency;
+};
+const addDirectedEntries = (adjacency, relation, direction) => {
+    if (direction === "callers") {
+        if (relation.relation === "calls")
+            addEntry(adjacency, relation.target_node_id, relation.source_node_id, relation);
+        return;
+    }
+    if (direction === "ownership") {
+        if (!ownershipRelation(relation.relation))
+            return;
+        addEntry(adjacency, relation.source_node_id, relation.target_node_id, relation);
+        addEntry(adjacency, relation.target_node_id, relation.source_node_id, relation);
+        return;
+    }
+    if (direction === "backward-provenance")
+        addEntry(adjacency, relation.target_node_id, relation.source_node_id, relation);
+    else
+        addEntry(adjacency, relation.source_node_id, relation.target_node_id, relation);
+};
+const addEntry = (adjacency, from, nextNodeId, relation) => {
+    const entries = adjacency.get(from) ?? [];
+    entries.push({ relation, nextNodeId });
+    adjacency.set(from, entries);
+};
+const traverse = (nodes, seeds, adjacency) => {
+    const nodeIds = new Set(seeds);
+    const relationIds = new Set();
+    const functionIds = new Set();
+    const modules = new Set();
+    const queue = [...nodeIds];
+    for (const nodeId of nodeIds)
+        retainOwners(nodes.get(nodeId), functionIds, modules);
+    for (let offset = 0; offset < queue.length; offset += 1) {
+        const current = queue[offset];
+        if (current === undefined)
+            continue;
+        for (const entry of adjacency.get(current) ?? []) {
+            relationIds.add(entry.relation.relation_id);
+            if (nodeIds.has(entry.nextNodeId))
+                continue;
+            const node = nodes.get(entry.nextNodeId);
+            if (node === undefined)
+                continue;
+            nodeIds.add(entry.nextNodeId);
+            retainOwners(node, functionIds, modules);
+            queue.push(entry.nextNodeId);
+        }
+    }
+    return {
+        nodeIds,
+        relationIds,
+        functionIds,
+        modules,
+    };
+};
+const retainOwners = (node, functions, modules) => {
+    if (node === undefined)
+        return;
+    const functionId = node.kind === "function" ? node.node_id : node.function_node_id;
+    if (functionId !== null)
+        functions.add(functionId);
+    modules.add(node.identity.module_path);
+};
+const relevantUnknownFrontiers = (graph, nodeIds, input) => {
+    const allowed = input.allowed_relations === undefined
+        ? null
+        : new Set(input.allowed_relations);
+    return graph.unknowns.filter((unknown) => (unknown.node_id === null || nodeIds.has(unknown.node_id)) &&
+        (allowed === null ||
+            unknown.relation_kinds.some((relation) => allowed.has(relation))));
+};
+const relevantCandidateRelationCount = (graph, nodeIds, input) => {
+    const allowed = input.allowed_relations === undefined
+        ? null
+        : new Set(input.allowed_relations);
+    let relevant = 0;
+    for (const relation of graph.relations) {
+        if (relation.resolution !== "candidate" ||
+            (allowed !== null && !allowed.has(relation.relation)))
+            continue;
+        const sourceIsRelevant = nodeIds.has(relation.source_node_id);
+        const targetIsRelevant = nodeIds.has(relation.target_node_id);
+        if ((input.direction === "callers" &&
+            relation.relation === "calls" &&
+            targetIsRelevant) ||
+            (input.direction === "ownership" &&
+                ownershipRelation(relation.relation) &&
+                (sourceIsRelevant || targetIsRelevant)) ||
+            (input.direction === "backward-provenance" && targetIsRelevant) ||
+            (input.direction === "forward-influence" && sourceIsRelevant))
+            relevant += 1;
+    }
+    return relevant;
+};
+const expectedMatchesFor = (nodes, relations, input) => {
+    if (input.expected === null)
+        return [];
+    const classes = new Set(input.expected.classes);
+    const connected = new Set(relations.map((relation) => input.expected?.role === "source"
+        ? relation.target_node_id
+        : relation.source_node_id));
+    return nodes.filter(({ kind, node_id }) => classes.has(kind) && !connected.has(node_id));
+};

package/dist/domain/javascript/javascriptSemanticQueryAssessment.js

@@ -0,0 +1,45 @@
+import { uniqueSorted } from "../canonicalOrdering.js";
+/** Classify a complete semantic traversal without promoting unknowns to absence. */
+export const assessJavaScriptSemanticQuery = (input) => ({
+    status: queryStatus(input),
+    coverage: queryCoverage(input),
+    limitations: queryLimitations(input),
+});
+const queryCoverage = (input) => ({
+    status: input.graph.coverage.status === "unavailable"
+        ? "unavailable"
+        : input.unknowns.length > 0 ||
+            input.candidateRelations > 0 ||
+            input.graph.coverage.status !== "complete" ||
+            input.graph.coverage.truncated
+            ? "partial"
+            : "complete",
+});
+const queryStatus = (input) => {
+    if (input.graph.coverage.status === "unavailable")
+        return "unsupported";
+    if (input.candidateRelations > 0)
+        return "ambiguous";
+    if (input.totalSeeds === 0 ||
+        (input.hasExpectation && input.expectedMatches === 0))
+        return input.unknowns.length > 0 ||
+            input.graph.coverage.status !== "complete" ||
+            input.graph.coverage.truncated
+            ? "partial"
+            : "no-match";
+    return input.totalSeeds > 1 ? "ambiguous" : "found";
+};
+const queryLimitations = (input) => uniqueSorted([
+    "Semantic graph reachability is a static inference and does not prove runtime execution.",
+    ...input.graph.limitations,
+    ...(input.unknowns.length === 0
+        ? []
+        : [
+            "Relevant dynamic, unsupported, incomplete, or ambiguous semantics remain unknown.",
+        ]),
+    ...(input.candidateRelations === 0
+        ? []
+        : [
+            "Candidate relations remain ambiguous and do not establish a resolved semantic path.",
+        ]),
+]);