Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
feat(javascript): add local semantic call flow
morlutoa26a1c73df01
diff --git a/src/domain/javascriptSemanticAnalysis.ts b/src/domain/javascriptSemanticAnalysis.tsindex 15818eba2..6e39f758d 100644--- a/src/domain/javascriptSemanticAnalysis.ts+++ b/src/domain/javascriptSemanticAnalysis.ts@@ -35,6 +35,7 @@ import {collectSemanticReturns,resolveSemanticModuleCallables,} from "./javascriptSemanticReturns.js";+import { collectJavaScriptSemanticCalls } from "./javascriptSemanticCalls.js";import {compareCodePoints,propertyName,@@ -86,14 +87,16 @@ export const analyzeJavaScriptSemantics = (const bindings = immutableSemanticBindings(state);const callables = collectSemanticReturns(file.program, state, parserPartial);const moduleLinks = resolveSemanticModuleCallables(state, callables);+ const calls = collectJavaScriptSemanticCalls(file.program, state, callables);return {schema: "JavaScriptSemanticIR",- schemaVersion: 2,+ schemaVersion: 3,scopes: immutableSemanticScopes(state),bindings,callables,references,moduleLinks,+ ...calls,coverage: {status:state.limitsReached.size > 0@@ -115,6 +118,7 @@ export const analyzeJavaScriptSemantics = (: ["Semantic recovery stopped retaining facts at explicit limits."]),"Values and aliases were recovered from inert syntax only; no JavaScript was executed.","Return sites include only direct callable returns; nested callable returns remain separate.",+ "Local call, argument, return, and closure relations are static candidates and do not prove runtime invocation.","Cross-function mutation and dynamic property resolution remain unknown.",],};@@ -139,6 +143,7 @@ const createState = (scopeByNode: new WeakMap([[program, root]]),bindingsById: new Map(),callables: [],+ callableNodesById: new Map(),moduleLinks: [],limitsReached: new Set(),omittedCount: 0,diff --git a/src/domain/javascriptSemanticCallResolution.ts b/src/domain/javascriptSemanticCallResolution.tsnew file mode 100644index 000000000..62873dc22--- /dev/null+++ b/src/domain/javascriptSemanticCallResolution.ts@@ -0,0 +1,229 @@+import * as t from "@babel/types";++import type {+ JavaScriptSemanticArgumentFlow,+ JavaScriptSemanticCallable,+} from "./javascriptSemanticIr.js";+import {+ reachSemanticLimit,+ semanticCallableIdForNode,+} from "./javascriptSemanticProjection.js";+import {+ resolveSemanticBindingState,+ type JavaScriptSemanticAnalysisState,+ type JavaScriptSemanticBindingState,+} from "./javascriptSemanticState.js";+import { compareCodePoints, range } from "./javascriptStaticAnalysisHelpers.js";++/** Resolution of one call target within the currently analyzed source. */+export interface LocalCallableResolution {+ readonly callableIds: readonly string[];+ readonly complete: boolean;+ readonly reason: string;+}++interface CallResolutionContext {+ readonly state: JavaScriptSemanticAnalysisState;+ readonly callableById: ReadonlyMap<string, JavaScriptSemanticCallable>;+ readonly seenBindings: ReadonlySet<string>;+ readonly depth: number;+ readonly bindingCache: Map<string, LocalCallableResolution>;+}++/** Inputs needed to resolve one local call target. */+export interface ResolveLocalCallablesInput {+ readonly node: t.Node;+ readonly state: JavaScriptSemanticAnalysisState;+ readonly callableById: ReadonlyMap<string, JavaScriptSemanticCallable>;+ readonly seenBindings: ReadonlySet<string>;+ readonly depth: number;+ readonly bindingCache: Map<string, LocalCallableResolution>;+}++/** Resolve bounded local callable candidates without following dynamic properties. */+export const resolveLocalCallables = (+ input: ResolveLocalCallablesInput,+): LocalCallableResolution =>+ resolveCallables(input.node, {+ state: input.state,+ callableById: input.callableById,+ seenBindings: input.seenBindings,+ depth: input.depth,+ bindingCache: input.bindingCache,+ });++const resolveCallables = (+ node: t.Node,+ context: CallResolutionContext,+): LocalCallableResolution => {+ if (context.depth >= context.state.limits.maxValueDepth) {+ reachSemanticLimit(context.state, "maxValueDepth");+ return {+ callableIds: [],+ complete: false,+ reason: "Call target depth limit reached.",+ };+ }+ const direct = semanticCallableIdForNode(node);+ if (direct !== null && context.callableById.has(direct))+ return {+ callableIds: [direct],+ complete: true,+ reason: "Direct local callable.",+ };+ if (t.isIdentifier(node)) return resolveIdentifier(node, context);+ if (+ t.isTSAsExpression(node) ||+ t.isTSTypeAssertion(node) ||+ t.isTSNonNullExpression(node)+ )+ return resolveCallables(node.expression, nestedContext(context));+ if (t.isConditionalExpression(node) || t.isLogicalExpression(node))+ return resolveAlternatives(+ t.isConditionalExpression(node) ? node.consequent : node.left,+ t.isConditionalExpression(node) ? node.alternate : node.right,+ context,+ );+ return {+ callableIds: [],+ complete: false,+ reason: `Unsupported ${node.type} call target.`,+ };+};++const resolveIdentifier = (+ node: t.Identifier,+ context: CallResolutionContext,+): LocalCallableResolution => {+ const binding = resolveSemanticBindingState(context.state, node, node.name);+ return binding === undefined+ ? {+ callableIds: [],+ complete: false,+ reason: `Unresolved call target ${node.name}.`,+ }+ : resolveBindingCallables(binding, nestedContext(context));+};++const resolveAlternatives = (+ left: t.Node,+ right: t.Node,+ context: CallResolutionContext,+): LocalCallableResolution => {+ const candidates = [left, right].map((candidate) =>+ resolveCallables(candidate, nestedContext(context)),+ );+ return {+ callableIds: uniqueCallableIds(+ candidates.flatMap(({ callableIds }) => callableIds),+ ),+ complete: candidates.every(({ complete }) => complete),+ reason: "Conditional or logical call target has multiple candidates.",+ };+};++const resolveBindingCallables = (+ binding: JavaScriptSemanticBindingState,+ context: CallResolutionContext,+): LocalCallableResolution => {+ const cached = context.bindingCache.get(binding.bindingId);+ if (cached !== undefined) return cached;+ if (context.seenBindings.has(binding.bindingId))+ return {+ callableIds: [],+ complete: false,+ reason: `Call target alias cycle at ${binding.name}.`,+ };+ if (binding.initializers.length === 0)+ return missingBindingInitializer(binding);+ const candidateContext = {+ ...nestedContext(context),+ seenBindings: new Set([...context.seenBindings, binding.bindingId]),+ };+ const candidates = binding.initializers.map(({ node, projection }) =>+ projection.length === 0+ ? resolveCallables(node, candidateContext)+ : {+ callableIds: [],+ complete: false,+ reason: `Projected call target ${binding.name} is unresolved.`,+ },+ );+ const callableIds = uniqueCallableIds(+ candidates.flatMap((candidate) => candidate.callableIds),+ );+ const resolution = {+ callableIds,+ complete: candidates.every(({ complete }) => complete),+ reason:+ callableIds.length === 1 && candidates.every(({ complete }) => complete)+ ? "Unique local callable target."+ : `Call target ${binding.name} has ambiguous or unsupported assignments.`,+ };+ if (resolution.complete)+ context.bindingCache.set(binding.bindingId, resolution);+ return resolution;+};++const missingBindingInitializer = (+ binding: JavaScriptSemanticBindingState,+): LocalCallableResolution => ({+ callableIds: [],+ complete: false,+ reason:+ binding.kind === "import"+ ? `Call target ${binding.name} is imported from outside this source.`+ : `Call target ${binding.name} has no local initializer.`,+});++/** Find all bindings introduced by one positional parameter pattern. */+export const parameterBindings = (+ callable: JavaScriptSemanticCallable,+ index: number,+ state: JavaScriptSemanticAnalysisState,+): JavaScriptSemanticBindingState[] => {+ if (callable.bodyScopeId === null) return [];+ const scope = state.scopesById.get(callable.bodyScopeId);+ if (scope === undefined) return [];+ return [...scope.bindings.values()]+ .filter(+ (binding) =>+ binding.kind === "parameter" &&+ binding.definitions.some(+ ({ kind, location }) =>+ kind === "parameter" &&+ parameterIndex(callable, location, state) === index,+ ),+ )+ .sort((left, right) => compareCodePoints(left.bindingId, right.bindingId));+};++const parameterIndex = (+ callable: JavaScriptSemanticCallable,+ location: JavaScriptSemanticArgumentFlow["parameterLocation"],+ state: JavaScriptSemanticAnalysisState,+): number => {+ const node = state.callableNodesById.get(callable.callableId);+ if (!t.isFunction(node)) return -1;+ return node.params.findIndex((parameter) =>+ rangeContains(range(parameter), location),+ );+};++const rangeContains = (+ outer: JavaScriptSemanticArgumentFlow["parameterLocation"],+ inner: JavaScriptSemanticArgumentFlow["parameterLocation"],+): boolean =>+ (outer.start.line < inner.start.line ||+ (outer.start.line === inner.start.line &&+ outer.start.column <= inner.start.column)) &&+ (outer.end.line > inner.end.line ||+ (outer.end.line === inner.end.line &&+ outer.end.column >= inner.end.column));++const nestedContext = (+ context: CallResolutionContext,+): CallResolutionContext => ({ ...context, depth: context.depth + 1 });++const uniqueCallableIds = (values: readonly string[]): string[] =>+ [...new Set(values)].sort(compareCodePoints);diff --git a/src/domain/javascriptSemanticCalls.ts b/src/domain/javascriptSemanticCalls.tsnew file mode 100644index 000000000..31c2c8aa2--- /dev/null+++ b/src/domain/javascriptSemanticCalls.ts@@ -0,0 +1,386 @@+import * as t from "@babel/types";++import type {+ JavaScriptSemanticArgumentFlow,+ JavaScriptSemanticCallable,+ JavaScriptSemanticCallReturnFlow,+ JavaScriptSemanticCallSite,+ JavaScriptSemanticClosureCapture,+ JavaScriptSemanticFrontier,+} from "./javascriptSemanticIr.js";+import {+ reachSemanticLimit,+ semanticCallableIdForNode,+ semanticReferenceRole,+ semanticStaticPropertyName,+} from "./javascriptSemanticProjection.js";+import {+ resolveSemanticBindingState,+ type JavaScriptSemanticAnalysisState,+ type JavaScriptSemanticBindingState,+} from "./javascriptSemanticState.js";+import {+ type LocalCallableResolution,+ parameterBindings,+ resolveLocalCallables,+} from "./javascriptSemanticCallResolution.js";+import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";+import { range } from "./javascriptStaticAnalysisHelpers.js";++/** Local call, flow, capture, and unsupported-frontier facts. */+export interface JavaScriptSemanticCallAnalysis {+ readonly callSites: readonly JavaScriptSemanticCallSite[];+ readonly argumentFlows: readonly JavaScriptSemanticArgumentFlow[];+ readonly callReturnFlows: readonly JavaScriptSemanticCallReturnFlow[];+ readonly closureCaptures: readonly JavaScriptSemanticClosureCapture[];+ readonly frontiers: readonly JavaScriptSemanticFrontier[];+}++interface MutableCallAnalysis {+ readonly callSites: JavaScriptSemanticCallSite[];+ readonly argumentFlows: JavaScriptSemanticArgumentFlow[];+ readonly callReturnFlows: JavaScriptSemanticCallReturnFlow[];+ readonly closureCaptures: JavaScriptSemanticClosureCapture[];+ readonly frontiers: JavaScriptSemanticFrontier[];+ retainedArguments: number;+}++interface CallCollectionContext {+ readonly state: JavaScriptSemanticAnalysisState;+ readonly callableById: ReadonlyMap<string, JavaScriptSemanticCallable>;+ readonly output: MutableCallAnalysis;+ readonly bindingResolutionCache: Map<string, LocalCallableResolution>;+ readonly parameterBindingCache: Map<+ string,+ readonly JavaScriptSemanticBindingState[]+ >;+}++/** Recover bounded direct-call and lexical-capture candidates from inert syntax. */+export const collectJavaScriptSemanticCalls = (+ program: t.Program,+ state: JavaScriptSemanticAnalysisState,+ callables: readonly JavaScriptSemanticCallable[],+): JavaScriptSemanticCallAnalysis => {+ const output: MutableCallAnalysis = {+ callSites: [],+ argumentFlows: [],+ callReturnFlows: [],+ closureCaptures: [],+ frontiers: [],+ retainedArguments: 0,+ };+ const callableById = new Map(+ callables.map((callable) => [callable.callableId, callable]),+ );+ const context: CallCollectionContext = {+ state,+ callableById,+ output,+ bindingResolutionCache: new Map(),+ parameterBindingCache: new Map(),+ };+ const callableStack: JavaScriptSemanticCallable[] = [];+ traverseJavaScriptAst(program, {+ enter: (node, parent) => {+ const callableId = semanticCallableIdForNode(node);+ const callable =+ callableId === null ? undefined : callableById.get(callableId);+ if (callable !== undefined) callableStack.push(callable);+ const owner = enclosingFunction(callableStack);+ collectCapture(node, parent, owner, context);+ collectDynamicProperty(node, owner, state, output);+ if (+ t.isCallExpression(node) ||+ t.isOptionalCallExpression(node) ||+ t.isNewExpression(node)+ )+ collectCallSite(node, owner, context);+ },+ exit: (node) => {+ const callableId = semanticCallableIdForNode(node);+ if (+ callableId !== null &&+ callableStack.at(-1)?.callableId === callableId+ )+ callableStack.pop();+ },+ });+ return {+ callSites: output.callSites,+ argumentFlows: output.argumentFlows,+ callReturnFlows: output.callReturnFlows,+ closureCaptures: output.closureCaptures,+ frontiers: output.frontiers,+ };+};++const collectCallSite = (+ node: t.CallExpression | t.OptionalCallExpression | t.NewExpression,+ owner: JavaScriptSemanticCallable | undefined,+ context: CallCollectionContext,+): void => {+ const { state, callableById, output } = context;+ if (output.callSites.length >= state.limits.maxCallSites) {+ reachSemanticLimit(state, "maxCallSites");+ return;+ }+ const resolution = resolveLocalCallables({+ node: node.callee,+ state,+ callableById,+ seenBindings: new Set(),+ depth: 0,+ bindingCache: context.bindingResolutionCache,+ });+ const callSiteId = semanticCallSiteId(node);+ const argumentsValue = retainedArguments(node.arguments, state, output);+ const site: JavaScriptSemanticCallSite = {+ callSiteId,+ kind: t.isNewExpression(node) ? "construct" : "call",+ callerCallableId: owner?.callableId ?? null,+ location: range(node),+ calleeLocation: range(node.callee),+ resolution:+ resolution.callableIds.length === 1 && resolution.complete+ ? "exact"+ : resolution.callableIds.length > 0+ ? "ambiguous"+ : "unresolved",+ calleeCallableIds: resolution.callableIds,+ arguments: argumentsValue,+ };+ output.callSites.push(site);+ if (site.resolution !== "exact")+ addFrontier(+ {+ kind: "dynamic-call",+ callableId: owner?.callableId ?? null,+ location: range(node.callee),+ reason: resolution.reason,+ },+ state,+ output,+ );+ collectArgumentFlows(site, node, context);+ if (site.kind === "call")+ collectReturnFlows(site, callableById, state, output);+};++const retainedArguments = (+ nodes: readonly (+ | t.Expression+ | t.SpreadElement+ | t.JSXNamespacedName+ | t.ArgumentPlaceholder+ )[],+ state: JavaScriptSemanticAnalysisState,+ output: MutableCallAnalysis,+): JavaScriptSemanticCallSite["arguments"] => {+ const retained: JavaScriptSemanticCallSite["arguments"][number][] = [];+ for (const [index, node] of nodes.entries()) {+ if (output.retainedArguments >= state.limits.maxCallArguments) {+ reachSemanticLimit(state, "maxCallArguments");+ break;+ }+ output.retainedArguments += 1;+ retained.push({+ index,+ location: range(node),+ spread: t.isSpreadElement(node),+ });+ }+ return retained;+};++const collectArgumentFlows = (+ site: JavaScriptSemanticCallSite,+ node: t.CallExpression | t.OptionalCallExpression | t.NewExpression,+ context: CallCollectionContext,+): void => {+ const { state, callableById, output } = context;+ const retainedIndexes = new Set(site.arguments.map(({ index }) => index));+ let positionIsExact = true;+ for (const [index, argument] of node.arguments.entries()) {+ if (t.isSpreadElement(argument)) {+ positionIsExact = false;+ continue;+ }+ if (+ !positionIsExact ||+ !retainedIndexes.has(index) ||+ !t.isExpression(argument)+ )+ continue;+ for (const callableId of site.calleeCallableIds) {+ const callable = callableById.get(callableId);+ if (callable === undefined) continue;+ for (const parameter of cachedParameterBindings(+ callable,+ index,+ context,+ )) {+ if (output.argumentFlows.length >= state.limits.maxArgumentFlows) {+ reachSemanticLimit(state, "maxArgumentFlows");+ return;+ }+ const definition = parameter.definitions.find(+ ({ kind }) => kind === "parameter",+ );+ if (definition === undefined) continue;+ output.argumentFlows.push({+ callSiteId: site.callSiteId,+ argumentIndex: index,+ argumentLocation: range(argument),+ callableId,+ parameterBindingId: parameter.bindingId,+ parameterLocation: definition.location,+ });+ }+ }+ }+};++const cachedParameterBindings = (+ callable: JavaScriptSemanticCallable,+ index: number,+ context: CallCollectionContext,+): readonly JavaScriptSemanticBindingState[] => {+ const key = `${callable.callableId}:${String(index)}`;+ const cached = context.parameterBindingCache.get(key);+ if (cached !== undefined) return cached;+ const bindings = parameterBindings(callable, index, context.state);+ context.parameterBindingCache.set(key, bindings);+ return bindings;+};++const collectReturnFlows = (+ site: JavaScriptSemanticCallSite,+ callableById: ReadonlyMap<string, JavaScriptSemanticCallable>,+ state: JavaScriptSemanticAnalysisState,+ output: MutableCallAnalysis,+): void => {+ for (const callableId of site.calleeCallableIds) {+ const callable = callableById.get(callableId);+ if (callable === undefined) continue;+ for (const returnSite of callable.returnSites) {+ if (output.callReturnFlows.length >= state.limits.maxCallReturnFlows) {+ reachSemanticLimit(state, "maxCallReturnFlows");+ return;+ }+ output.callReturnFlows.push({+ callSiteId: site.callSiteId,+ callableId,+ returnSiteId: returnSite.returnSiteId,+ returnLocation: returnSite.location,+ });+ }+ }+};++const collectCapture = (+ node: t.Node,+ parent: t.Node | null,+ owner: JavaScriptSemanticCallable | undefined,+ context: CallCollectionContext,+): void => {+ const { state, output } = context;+ if (+ !t.isIdentifier(node) ||+ parent === null ||+ owner === undefined ||+ owner.bodyScopeId === null+ )+ return;+ if (semanticReferenceRole(node, parent) === null) return;+ const binding = resolveSemanticBindingState(state, node, node.name);+ if (+ binding === undefined ||+ bindingIsWithinCallable(binding, owner.bodyScopeId, state)+ )+ return;+ if (output.closureCaptures.length >= state.limits.maxClosureCaptures) {+ reachSemanticLimit(state, "maxClosureCaptures");+ return;+ }+ output.closureCaptures.push({+ callableId: owner.callableId,+ bindingId: binding.bindingId,+ referenceLocation: range(node),+ });+};++const collectDynamicProperty = (+ node: t.Node,+ owner: JavaScriptSemanticCallable | undefined,+ state: JavaScriptSemanticAnalysisState,+ output: MutableCallAnalysis,+): void => {+ if (+ (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) &&+ semanticStaticPropertyName(node.property, node.computed) === ""+ )+ addFrontier(+ {+ kind: "dynamic-property",+ callableId: owner?.callableId ?? null,+ location: range(node.property),+ reason: "Computed member property is not a static string or number.",+ },+ state,+ output,+ );+ else if (+ (t.isObjectProperty(node) || t.isObjectMethod(node)) &&+ node.computed &&+ semanticStaticPropertyName(node.key, true) === ""+ )+ addFrontier(+ {+ kind: "dynamic-property",+ callableId: owner?.callableId ?? null,+ location: range(node.key),+ reason: "Computed object property is not a static string or number.",+ },+ state,+ output,+ );+};++const addFrontier = (+ frontier: JavaScriptSemanticFrontier,+ state: JavaScriptSemanticAnalysisState,+ output: MutableCallAnalysis,+): void => {+ if (output.frontiers.length >= state.limits.maxFrontiers) {+ reachSemanticLimit(state, "maxFrontiers");+ return;+ }+ output.frontiers.push(frontier);+};++const bindingIsWithinCallable = (+ binding: JavaScriptSemanticBindingState,+ bodyScopeId: string,+ state: JavaScriptSemanticAnalysisState,+): boolean => {+ let scope = state.scopesById.get(binding.scopeId);+ while (scope !== undefined) {+ if (scope.scopeId === bodyScopeId) return true;+ scope =+ scope.parentScopeId === null+ ? undefined+ : state.scopesById.get(scope.parentScopeId);+ }+ return false;+};++const enclosingFunction = (+ stack: readonly JavaScriptSemanticCallable[],+): JavaScriptSemanticCallable | undefined =>+ stack.findLast(({ kind }) => kind !== "class");++const semanticCallSiteId = (+ node: t.CallExpression | t.OptionalCallExpression | t.NewExpression,+): string =>+ `call:${t.isNewExpression(node) ? "construct" : "call"}:${String(node.start ?? -1)}:${String(node.end ?? -1)}`;diff --git a/src/domain/javascriptSemanticIr.ts b/src/domain/javascriptSemanticIr.tsindex ed89b2cf1..7cb47e217 100644--- a/src/domain/javascriptSemanticIr.ts+++ b/src/domain/javascriptSemanticIr.ts@@ -8,6 +8,12 @@ export interface JavaScriptSemanticLimits {readonly maxReferences: number;readonly maxModuleLinks: number;readonly maxReturnSites: number;+ readonly maxCallSites: number;+ readonly maxCallArguments: number;+ readonly maxArgumentFlows: number;+ readonly maxCallReturnFlows: number;+ readonly maxClosureCaptures: number;+ readonly maxFrontiers: number;readonly maxValueDepth: number;readonly maxUnionValues: number;readonly maxObjectProperties: number;@@ -21,6 +27,12 @@ export const DEFAULT_JAVASCRIPT_SEMANTIC_LIMITS: JavaScriptSemanticLimits = {maxReferences: 100_000,maxModuleLinks: 20_000,maxReturnSites: 20_000,+ maxCallSites: 20_000,+ maxCallArguments: 100_000,+ maxArgumentFlows: 100_000,+ maxCallReturnFlows: 100_000,+ maxClosureCaptures: 100_000,+ maxFrontiers: 20_000,maxValueDepth: 16,maxUnionValues: 32,maxObjectProperties: 256,@@ -139,10 +151,63 @@ export interface JavaScriptSemanticCallable {/** One direct return expression belonging to exactly one callable. */export interface JavaScriptSemanticReturnSite {+ readonly returnSiteId: string;readonly location: JavaScriptSourceRange;readonly value: JavaScriptSemanticValue;}+/** One statically visible call or construction expression. */+export interface JavaScriptSemanticCallSite {+ readonly callSiteId: string;+ readonly kind: "call" | "construct";+ readonly callerCallableId: string | null;+ readonly location: JavaScriptSourceRange;+ readonly calleeLocation: JavaScriptSourceRange;+ readonly resolution: "exact" | "ambiguous" | "unresolved";+ readonly calleeCallableIds: readonly string[];+ readonly arguments: readonly JavaScriptSemanticCallArgument[];+}++/** One argument occurrence retained without evaluating application code. */+export interface JavaScriptSemanticCallArgument {+ readonly index: number;+ readonly location: JavaScriptSourceRange;+ readonly spread: boolean;+}++/** One positional argument that may initialize one local parameter binding. */+export interface JavaScriptSemanticArgumentFlow {+ readonly callSiteId: string;+ readonly argumentIndex: number;+ readonly argumentLocation: JavaScriptSourceRange;+ readonly callableId: string;+ readonly parameterBindingId: string;+ readonly parameterLocation: JavaScriptSourceRange;+}++/** One direct local return that may supply a call expression's value. */+export interface JavaScriptSemanticCallReturnFlow {+ readonly callSiteId: string;+ readonly callableId: string;+ readonly returnSiteId: string;+ readonly returnLocation: JavaScriptSourceRange;+}++/** One resolved outer lexical binding referenced by a nested callable. */+export interface JavaScriptSemanticClosureCapture {+ readonly callableId: string;+ readonly bindingId: string;+ readonly referenceLocation: JavaScriptSourceRange;+}++/** One syntax location where exact local semantic continuation is unavailable. */+export interface JavaScriptSemanticFrontier {+ readonly kind: "dynamic-call" | "dynamic-property";+ readonly callableId: string | null;+ readonly location: JavaScriptSourceRange;+ readonly reason: string;+}+/** Exact retention state for one callable's direct returns. */interface JavaScriptSemanticReturnCoverage {readonly status: "complete" | "partial" | "truncated";@@ -174,15 +239,20 @@ interface JavaScriptSemanticCoverage {readonly limitsReached: readonly (keyof JavaScriptSemanticLimits)[];}-/** Provider-neutral JavaScript semantic IR v2. */+/** Provider-neutral JavaScript semantic IR v3. */export interface JavaScriptSemanticIr {readonly schema: "JavaScriptSemanticIR";- readonly schemaVersion: 2;+ readonly schemaVersion: 3;readonly scopes: readonly JavaScriptSemanticScope[];readonly bindings: readonly JavaScriptSemanticBinding[];readonly callables: readonly JavaScriptSemanticCallable[];readonly references: readonly JavaScriptSemanticReference[];readonly moduleLinks: readonly JavaScriptSemanticModuleLink[];+ readonly callSites: readonly JavaScriptSemanticCallSite[];+ readonly argumentFlows: readonly JavaScriptSemanticArgumentFlow[];+ readonly callReturnFlows: readonly JavaScriptSemanticCallReturnFlow[];+ readonly closureCaptures: readonly JavaScriptSemanticClosureCapture[];+ readonly frontiers: readonly JavaScriptSemanticFrontier[];readonly coverage: JavaScriptSemanticCoverage;readonly limitations: readonly string[];}@@ -208,12 +278,17 @@ export const semanticBinding = (/** Fail-closed result when Babel cannot produce an inert syntax tree. */export const failedJavaScriptSemanticIr = (): JavaScriptSemanticIr => ({schema: "JavaScriptSemanticIR",- schemaVersion: 2,+ schemaVersion: 3,scopes: [],bindings: [],callables: [],references: [],moduleLinks: [],+ callSites: [],+ argumentFlows: [],+ callReturnFlows: [],+ closureCaptures: [],+ frontiers: [],coverage: { status: "failed", omittedCount: null, limitsReached: [] },limitations: ["JavaScript parsing failed; no semantic absence claim is available.",diff --git a/src/domain/javascriptSemanticProjection.ts b/src/domain/javascriptSemanticProjection.tsindex e8ed83cec..c13bfe954 100644--- a/src/domain/javascriptSemanticProjection.ts+++ b/src/domain/javascriptSemanticProjection.ts@@ -42,8 +42,10 @@ export const collectSemanticCallable = (input: CollectCallableInput): void => {reachSemanticLimit(state, "maxCallables");return;}+ const callableId =+ semanticCallableIdForNode(node) ?? "callable:unknown:-1:-1";state.callables.push({- callableId: semanticCallableIdForNode(node) ?? "callable:unknown:-1:-1",+ callableId,kind,name: callableName(node, parent),containerScopeId: containerScope.scopeId,@@ -60,6 +62,7 @@ export const collectSemanticCallable = (input: CollectCallableInput): void => {limitsReached: [],},});+ state.callableNodesById.set(callableId, node);};/** Collect one static import/export relationship for later composition. */@@ -102,7 +105,7 @@ export const collectSemanticReferences = (traverseJavaScriptAst(program, {enter: (node, parent) => {if (!t.isIdentifier(node) || parent === null) return;- const role = referenceRole(node, parent);+ const role = semanticReferenceRole(node, parent);if (role === null) return;const key = `${String(node.start)}:${role}:${node.name}`;if (seen.has(key)) return;@@ -403,7 +406,8 @@ const declarationCallableId = (: semanticCallableIdForNode(declarator.init);};-const referenceRole = (+/** Classify one identifier occurrence consistently with semantic references. */+export const semanticReferenceRole = (node: t.Identifier,parent: t.Node,): JavaScriptSemanticReference["role"] | null => {diff --git a/src/domain/javascriptSemanticReturns.ts b/src/domain/javascriptSemanticReturns.tsindex c078f4a02..017a032cd 100644--- a/src/domain/javascriptSemanticReturns.ts+++ b/src/domain/javascriptSemanticReturns.ts@@ -55,6 +55,10 @@ export const collectSemanticReturns = (}retained += 1;sites.push({+ returnSiteId: semanticReturnSiteId(+ callable.callableId,+ expression.location,+ ),location: expression.location,value:expression.node === null@@ -76,6 +80,12 @@ export const collectSemanticReturns = (});};+const semanticReturnSiteId = (+ callableId: string,+ location: JavaScriptSemanticReturnSite["location"],+): string =>+ `${callableId}:return:${String(location.start.line)}:${String(location.start.column)}:${String(location.end.line)}:${String(location.end.column)}`;+/** Link exports to callables only when lexical resolution is unique and exact. */export const resolveSemanticModuleCallables = (state: JavaScriptSemanticAnalysisState,diff --git a/src/domain/javascriptSemanticState.ts b/src/domain/javascriptSemanticState.tsindex 69ad149cf..ee0a73e55 100644--- a/src/domain/javascriptSemanticState.ts+++ b/src/domain/javascriptSemanticState.ts@@ -45,6 +45,7 @@ export interface JavaScriptSemanticAnalysisState {readonly scopeByNode: WeakMap<t.Node, JavaScriptSemanticScopeState>;readonly bindingsById: Map<string, JavaScriptSemanticBindingState>;readonly callables: JavaScriptSemanticCallable[];+ readonly callableNodesById: Map<string, t.Node>;readonly moduleLinks: JavaScriptSemanticModuleLink[];readonly limitsReached: Set<keyof JavaScriptSemanticLimits>;omittedCount: number;diff --git a/tests/javascriptSemanticAnalysis.test.ts b/tests/javascriptSemanticAnalysis.test.tsindex d846b480c..e182e4d86 100644--- a/tests/javascriptSemanticAnalysis.test.ts+++ b/tests/javascriptSemanticAnalysis.test.ts@@ -200,6 +200,153 @@ describe("JavaScript semantic analysis", () => {expect(bindingsNamed(ir, "method")).toEqual([]);});+ it("links exact local calls to parameters, returns, and closure captures", () => {+ const ir = analyzeJavaScriptSemantics(`+ const prefix = "rea";+ function render(value, { mode }) {+ return prefix + value + mode;+ }+ const alias = render;+ const result = alias(input, { mode: "fast" });+ `);++ expect(ir.schemaVersion).toBe(3);+ const render = onlyCallable(ir, "render");+ const call = ir.callSites.find(+ ({ calleeCallableIds }) => calleeCallableIds[0] === render.callableId,+ );+ expect(call).toMatchObject({+ kind: "call",+ callerCallableId: null,+ resolution: "exact",+ calleeCallableIds: [render.callableId],+ arguments: [+ { index: 0, spread: false },+ { index: 1, spread: false },+ ],+ });+ if (call === undefined) throw new Error("Missing render call");+ expect(+ ir.argumentFlows+ .filter(({ callSiteId }) => callSiteId === call.callSiteId)+ .map(({ argumentIndex, parameterBindingId }) => ({+ argumentIndex,+ parameter: semanticBinding(ir, parameterBindingId)?.name,+ })),+ ).toEqual([+ { argumentIndex: 0, parameter: "value" },+ { argumentIndex: 1, parameter: "mode" },+ ]);+ expect(ir.callReturnFlows).toEqual([+ expect.objectContaining({+ callSiteId: call.callSiteId,+ callableId: render.callableId,+ returnSiteId: render.returnSites[0]?.returnSiteId,+ }),+ ]);+ expect(ir.closureCaptures).toEqual([+ expect.objectContaining({+ callableId: render.callableId,+ bindingId: topLevelBinding(ir, "prefix").bindingId,+ }),+ ]);+ expect(ir.frontiers).toEqual([]);+ });++ it("retains ambiguous local callees and explicit dynamic frontiers", () => {+ const ir = analyzeJavaScriptSemantics(`+ function left(value) { return value; }+ function right(value) { return value; }+ const selected = chooseLeft ? left : right;+ selected(input);+ receiver[key](input);+ external(input);+ `);++ const selected = ir.callSites.find(+ ({ resolution }) => resolution === "ambiguous",+ );+ expect(selected?.calleeCallableIds).toEqual(+ [+ onlyCallable(ir, "left").callableId,+ onlyCallable(ir, "right").callableId,+ ].sort(),+ );+ expect(+ ir.argumentFlows.filter(+ ({ callSiteId }) => callSiteId === selected?.callSiteId,+ ),+ ).toHaveLength(2);+ expect(ir.frontiers).toEqual(+ expect.arrayContaining([+ expect.objectContaining({+ kind: "dynamic-call",+ reason: expect.stringMatching(/ambiguous/iu),+ }),+ expect.objectContaining({+ kind: "dynamic-property",+ reason: expect.stringMatching(/computed member/iu),+ }),+ expect.objectContaining({+ kind: "dynamic-call",+ reason: "Unresolved call target external.",+ }),+ ]),+ );+ });++ it("does not project positional argument flow after a spread", () => {+ const ir = analyzeJavaScriptSemantics(`+ function target(first, second, third) { return third; }+ target(one, ...rest, three);+ `);++ expect(ir.argumentFlows.map(({ argumentIndex }) => argumentIndex)).toEqual([+ 0,+ ]);+ });++ it("applies independent hard bounds to every new semantic fact family", () => {+ const ir = analyzeJavaScriptSemantics(+ `+ const captured = 1;+ function target(value, other) { return value + other + captured; }+ target(1, 2);+ target(3, 4);+ object[first];+ object[second];+ `,+ {+ maxCallSites: 1,+ maxCallArguments: 1,+ maxArgumentFlows: 0,+ maxCallReturnFlows: 0,+ maxClosureCaptures: 0,+ maxFrontiers: 1,+ },+ );++ expect(ir.callSites).toHaveLength(1);+ expect(ir.callSites[0]?.arguments).toEqual([+ expect.objectContaining({ index: 0, spread: false }),+ ]);+ expect(ir.argumentFlows).toEqual([]);+ expect(ir.callReturnFlows).toEqual([]);+ expect(ir.closureCaptures).toEqual([]);+ expect(ir.frontiers).toHaveLength(1);+ expect(ir.coverage).toMatchObject({+ status: "truncated",+ limitsReached: expect.arrayContaining([+ "maxCallSites",+ "maxCallArguments",+ "maxArgumentFlows",+ "maxCallReturnFlows",+ "maxClosureCaptures",+ "maxFrontiers",+ ]),+ });+ });+it("recovers only direct return sites with literal and unknown object fields", () => {const ir = analyzeJavaScriptSemantics(`export default function parseMarkdown(value) {