@jskit-ai/architecture-inspector 0.1.1 → 0.1.2

package/README.md

@@ -17,17 +17,22 @@ Run `jskit-inspect-vue` in the project directory. It reads one bounded JSON
 document from stdin and writes one `genesis.architecture-observations.v1` JSON
 document to stdout. Errors use stderr and a failing exit status. It does not
 import application code, start a server, generate router declarations or retain
-a watcher. The package has no Genesis or Vibe64 dependency. The command runs the
+a watcher. The package imports no consumer's code: the input contract is its
+own, and it writes the observation format its consumer defines, which it names
+only by schema id. The command runs the
 inspection in a child Node process whose old generation is bounded by the size
 of the declared scripts (192 MB plus 56 MB per MiB), so memory stays near what
 the inspection holds; a caller that starts Node with its own
 `--max-old-space-size` keeps that bound and runs in place.
 
-Input supplies `schema: "vibe64.architecture-inspection-input.v1"`, indexed
+Input supplies `schema: "jskit.architecture-inspection-input.v1"`, indexed
 `files: [{ path, hash }]` and `uiDiscovery.discoveries`. Optional `packages`
 carry `id`, `name`, `manifest`, `declarations`, `root`, `opaque` and public
 `entryPoints: [{ importPath, file }]`; `packageIdentity` binds observations to
-the same inspected public boundaries. Paths are project-relative
+the same inspected public boundaries. A package resolves for the files under
+each manifest that declares it (`declarations: [{ manifest }]`, or its
+`manifest` when it has none), whatever the dependency kind, so the packages of
+a workspace resolve one another when each workspace manifest is declared. Paths are project-relative
 and hashes use `sha256:<hex>`. Only declared, hash-matching UTF-8 files are read;
 symlinks and files over 4 MiB are rejected. Optional `stackHash` and
 `cacheDirectory` serve the call cache below; other unknown fields are ignored.
@@ -56,11 +61,20 @@ Each discovery supplies `id`, `adapter`, `surface`, `mode`, `registrations`,
   not evidence of runtime calls. Coverage remains partial; namespace use does
   not establish which individual exports are consumed.
 - An HTTP scope names the application's operations and enables scoped literal
-  `fetch` uses and receivers registered through JSKIT's `defineFeature` setup
-  `http.router.register`. It is the root `package.json` `name`, or
-  `--http-scope shop` when the operations should carry another name; without
-  either, HTTP observations stay unconfigured. `--api-base-path /api` prefixes
-  `http.router.register` paths. Use `--alias @=src` for declared project aliases.
+  `fetch` uses and the routes a `defineFeature` setup registers on its HTTP
+  router. It is the root `package.json` `name`, or `--http-scope shop` when
+  the operations should carry another name; without either, HTTP observations
+  stay unconfigured. Use `--alias @=src` for declared project aliases.
+- `router.register(method, path, options, handler)` becomes an entry operation
+  whose controller is the handler, when the router is `http.router` of the
+  setup's destructured `http` dependency (or `dependencies.http.router`), used
+  in the setup or passed to a project function that registers on the parameter
+  receiving it. Such functions may be local or imported through named imports
+  and re-exports, at most four calls deep. The method and path must be
+  literals, local constants or template literals of them; a call of the
+  kernel's `resolveScopedApiBasePath` with literal options stands for the path
+  it returns. Anything else is reported as `CONTROLLER_UNRESOLVED`.
+  `--api-base-path /api` prefixes these paths.
 - Actual `CrudListScreen` / `CrudAddEditScreen` uses whose bound screen comes from
   the matching JSKIT composable can connect to exported `defineCrudJsonApiFeature`
   controller declarations. The resource must resolve through indexed imports and
@@ -70,6 +84,13 @@ Each discovery supplies `id`, `adapter`, `surface`, `mode`, `registrations`,
   than claiming a fully expanded runtime URL. Custom clients, transport/resource
   overrides, dynamic operations and disabled routes do not create guessed links.
   This shows declared entry points; runtime provider activation is not proven.
+  Each such entry operation carries the `actionId` its route runs,
+  `crud.<namespace>.<operation>`. The declaration's custom `actions` (a literal
+  object, bound locally or imported through named re-exports) that declare a
+  literal `route` become `http` entry operations at the declaration's API base
+  path (`scope.routeBase` and `relativePath`) plus the route's `path`, with the
+  action's `id`, or `crud.<namespace>.<name>` without one. Other forms are reported
+  as `CRUD_ACTION_ROUTE_UNRESOLVED`.
 
 - Routes registered through the kernel's `createActionRouteScope` become entry
   operations with their full path and, for `actionRoute`, their `actionId`.
@@ -108,10 +129,19 @@ Each discovery supplies `id`, `adapter`, `surface`, `mode`, `registrations`,
     destructured factory parameter such as `createActions({ sessions })`)
     that receives one value across all the project's calls, when that value
     resolves exactly. Several values stay probable.
+  - JSDoc types are declared types: `@param`, `@type`, `@typedef` and
+    `import("...")` types, including a package's `./server/types` reached
+    through its declared entry points. A call through a parameter or binding
+    typed that way is a `checker` call. A member a type declares as `typeof` a
+    function (`{ run: typeof run }`, `@property {typeof run} run`) is that
+    function.
   - Action definitions (`{ id, execute }` in a feature's `actions`, also through
-    pass-through wrappers and literal-array `.map`) become `action` entry
-    points; `request.executeAction({ actionId: "..." })` reaches their execute
-    function, and each action route's `controllerFunctionId` names it.
+    `create*Actions` factories, pass-through wrappers and literal-array `.map`,
+    with ids that are literals or module constants) and the custom actions of a
+    CRUD declaration become `action` entry points;
+    `request.executeAction({ actionId: "..." })` reaches their execute
+    function, and the `controllerFunctionId` of each entry operation that names
+    an action is that function.
   - Calls that are provably external are left out: package imports, builtins,
     values produced by them (including `let` assignments, `for...of`,
     destructuring and callbacks they call), Vue's `<script setup>` macros and
@@ -136,7 +166,10 @@ Each discovery supplies `id`, `adapter`, `surface`, `mode`, `registrations`,
 - **Cache.** With an absolute, existing `cacheDirectory` outside the project,
   the command keeps `jskit-calls.json` there. An unchanged rerun reuses the
   whole result. Otherwise a file keeps its calls when its own and its directly
-  imported sources are unchanged and every target still exists. Any change to a
+  imported sources are unchanged and every target still exists. Calls that
+  injection or argument flow resolve depend on other files' arguments, so they
+  are resolved again on every run; a file whose such calls now reach other
+  functions is resolved again, with every reused file whose calls reach it. Any change to a
   manifest, lockfile, `tsconfig`/`jsconfig`, the inspector's own manifest or
   source (even without a version bump), packages, UI discovery, options or
   `stackHash` rebuilds everything. An absent, unusable or corrupt cache means a
@@ -145,7 +178,7 @@ Each discovery supplies `id`, `adapter`, `surface`, `mode`, `registrations`,
 ### Preview locator
 
 `src/previewLocator.js` is a classic script a Preview can inline. It defines
-`globalThis.__vibe64LocateElement(element)`, which returns `{ file, name? }` for
+`globalThis.__jskitLocateElement(element)`, which returns `{ file, name? }` for
 the nearest component with a source file (Vue development builds record it as
 `__file`) that rendered the element, or `null` for plain DOM. It reads only
 Vue's component bookkeeping, never text content or values.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/architecture-inspector",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Static Vue architecture inspector for the portable architecture-inspection command contract.",
   "type": "module",
   "files": [
@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "@babel/parser": "7.29.9",
-    "@jskit-ai/kernel": "0.2.3",
+    "@jskit-ai/kernel": "0.2.4",
     "@vue/compiler-sfc": "3.5.44",
     "typescript": "6.0.3"
   },

package/src/calls/cache.js

@@ -4,8 +4,9 @@ import { readFile, rename, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-// v2: calls a function makes through the callbacks it passes are its own records.
-const CACHE_SCHEMA = "jskit.architecture-calls-cache.v2";
+// v3: each file keeps its checker sites, the candidates injection or argument
+// flow can resolve, and the sites they resolved to, apart.
+const CACHE_SCHEMA = "jskit.architecture-calls-cache.v3";
 const CACHE_FILE = "jskit-calls.json";
 // Manifests, lockfiles and compiler configurations change how every file
 // resolves, so any change to them rebuilds everything.

package/src/calls/evaluate.js

@@ -40,6 +40,11 @@ function normalizedSegment(value) {
   return value.startsWith("/") || value.startsWith(ANY) || value === "" ? value : `/${value}`;
 }
 
+/**
+ * @param {object} dependencies
+ * @param {import("./types.js").CallSymbols} dependencies.symbols
+ * @param {import("./types.js").FileOf} dependencies.fileOf
+ */
 function createEvaluator({ symbols, fileOf }) {
   const unrolled = new Map();
 

package/src/calls/external.js

@@ -0,0 +1,123 @@
+import ts from "typescript";
+import { isFunctionLike, unwrapExpression } from "./functions.js";
+
+const MAX_DEPTH = 6;
+// Node globals TypeScript's default libraries do not declare. Calls to them
+// are provably external.
+const NODE_GLOBALS = new Set(["process", "Buffer", "require", "module", "exports", "__dirname", "__filename", "global", "setImmediate", "clearImmediate"]);
+// Emit functions and model refs Vue's `<script setup>` macros return are
+// Vue's own values.
+const VUE_EXTERNAL_VALUES = new Set(["defineEmits", "defineModel"]);
+
+function isComponentFile(file) {
+  return Boolean(file) && file.endsWith(".vue");
+}
+
+function isNullish(expression) {
+  const value = unwrapExpression(expression);
+  return value.kind === ts.SyntaxKind.NullKeyword || (ts.isIdentifier(value) && value.text === "undefined");
+}
+
+/**
+ * Whether values are provably produced by a package or builtin, so calls on
+ * them leave the project.
+ * @param {object} dependencies
+ * @param {import("typescript").TypeChecker} dependencies.checker
+ * @param {import("./types.js").CallSymbols} dependencies.symbols
+ * @param {import("./types.js").FileOf} dependencies.fileOf
+ */
+function createExternalValues({ checker, symbols, fileOf }) {
+  // Whether a value is provably produced by a package or builtin.
+  function isExternalValue(expression, depth = 0) {
+    const root = symbols.receiverRoot(expression);
+    if (!root || depth > MAX_DEPTH) {
+      return false;
+    }
+    if (ts.isIdentifier(root)) {
+      if (symbols.isPackageImport(root)) {
+        return true;
+      }
+      const symbol = symbols.symbolAt(root);
+      if (!symbol) {
+        return NODE_GLOBALS.has(root.text) || (isComponentFile(fileOf(root)) && VUE_EXTERNAL_VALUES.has(root.text));
+      }
+      if (symbols.isLibrarySymbol(symbol)) {
+        return true;
+      }
+      const declaration = symbols.declarationOf(root);
+      return Boolean(declaration) && isExternalDeclaration(declaration, depth + 1);
+    }
+    return ts.isStringLiteralLike(root) || ts.isArrayLiteralExpression(root) || ts.isRegularExpressionLiteral(root) ||
+      ts.isTemplateExpression(root) || ts.isNumericLiteral(root);
+  }
+
+  // Whether every value a declared name can hold comes from a package or
+  // builtin: its initializer and later assignments, the iterable it is taken
+  // from, the value it is destructured from, or the external call a callback
+  // parameter is supplied by.
+  function isExternalDeclaration(declaration, depth) {
+    let current = declaration;
+    while (current && ts.isBindingElement(current)) {
+      current = current.parent.parent;
+    }
+    if (!current || depth > MAX_DEPTH) {
+      return false;
+    }
+    if (ts.isParameter(current)) {
+      const fn = current.parent;
+      const call = fn.parent;
+      return (ts.isCallExpression(call) || ts.isNewExpression(call)) && Boolean(call.arguments?.includes(fn)) &&
+        isExternalCallee(call.expression, depth + 1);
+    }
+    if (!ts.isVariableDeclaration(current)) {
+      return false;
+    }
+    const statement = current.parent?.parent;
+    if (statement && ts.isForOfStatement(statement) && statement.initializer === current.parent) {
+      return isExternalValue(statement.expression, depth + 1);
+    }
+    const values = [current.initializer, ...assignedValues(current)].filter((value) => value && !isNullish(value));
+    return values.length > 0 && values.every((value) => isExternalValue(value, depth + 1));
+  }
+
+  function isExternalCallee(expression, depth) {
+    const callee = unwrapExpression(expression);
+    if (ts.isIdentifier(callee)) {
+      const symbol = symbols.symbolAt(callee);
+      return symbol ? symbols.isPackageImport(callee) || symbols.isLibrarySymbol(symbol) : NODE_GLOBALS.has(callee.text);
+    }
+    return ts.isPropertyAccessExpression(callee) && isExternalValue(callee.expression, depth);
+  }
+
+  // The values later assigned to a `let` or `var` name within its scope.
+  const assignments = new Map();
+  function assignedValues(declaration) {
+    if (!ts.isIdentifier(declaration.name) || declaration.parent.flags & ts.NodeFlags.Const) {
+      return [];
+    }
+    if (!assignments.has(declaration)) {
+      const symbol = checker.getSymbolAtLocation(declaration.name);
+      let scope = declaration.parent;
+      while (scope && !isFunctionLike(scope) && !ts.isSourceFile(scope)) {
+        scope = scope.parent;
+      }
+      const values = [];
+      const visit = (node) => {
+        if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+          ts.isIdentifier(node.left) && node.left.text === declaration.name.text && checker.getSymbolAtLocation(node.left) === symbol) {
+          values.push(node.right);
+        }
+        ts.forEachChild(node, visit);
+      };
+      if (scope) {
+        visit(scope);
+      }
+      assignments.set(declaration, values);
+    }
+    return assignments.get(declaration);
+  }
+
+  return Object.freeze({ isExternalValue, isExternalDeclaration });
+}
+
+export { NODE_GLOBALS, createExternalValues, isComponentFile };

package/src/calls/features.js

@@ -2,7 +2,13 @@ import ts from "typescript";
 import { isFunctionLike, unwrapExpression } from "./functions.js";
 
 const FEATURE_PACKAGE = "@jskit-ai/kernel";
-const MAX_ACTION_DEPTH = 6;
+const CRUD_PACKAGE = "@jskit-ai/crud-core";
+const CRUD_RESOURCE_PACKAGE = "@jskit-ai/resource-crud-core";
+// How many arrays, spreads, conditionals, calls and functions an action
+// definition may sit under in a feature's actions() result: enough for a
+// flagged spread of a create*Actions call whose definitions are each frozen.
+const MAX_ACTION_DEPTH = 10;
+const MAX_OBJECT_DEPTH = 8;
 
 function memberNamed(objectLiteral, name) {
   return objectLiteral.properties.find((property) =>
@@ -14,15 +20,28 @@ function isActionObject(node) {
     Boolean(memberNamed(node, "id")) && Boolean(memberNamed(node, "execute"));
 }
 
-// JSKIT's defineFeature dependency injection, read statically:
-// requires/optional tokens, provides tokens, setup outputs and the actions()
-// definitions. Feature setup and actions parameters are bound to the
-// expressions their providers return. One provider is exact; several are
-// ambiguous; none leaves the parameter unbound.
+/**
+ * JSKIT's defineFeature dependency injection, read statically:
+ * requires/optional tokens, provides tokens, setup outputs and the actions()
+ * definitions. Feature setup and actions parameters are bound to the
+ * expressions their providers return. One provider is exact; several are
+ * ambiguous; none leaves the parameter unbound.
+ * @param {object} dependencies
+ * @param {import("typescript").CallExpression[]} dependencies.calls
+ * @param {import("./types.js").CallSymbols} dependencies.symbols
+ * @param {import("./types.js").CallEvaluator} dependencies.evaluator
+ */
 function bindFeatures({ calls, symbols, evaluator }) {
   const features = [];
+  const crudDeclarations = [];
   for (const call of calls) {
     const callee = unwrapExpression(call.expression);
+    if (ts.isIdentifier(callee) && symbols.isImportOf(callee, CRUD_PACKAGE, ["defineCrudJsonApiFeature"])) {
+      const config = objectLiteral(call.arguments[0], symbols);
+      if (config) {
+        crudDeclarations.push(config);
+      }
+    }
     if (!ts.isIdentifier(callee) || !symbols.isImportOf(callee, FEATURE_PACKAGE, ["defineFeature"])) {
       continue;
     }
@@ -141,7 +160,98 @@ function bindFeatures({ calls, symbols, evaluator }) {
     }
   }
 
-  return { features, bindings, actions: collectFeatureActions(features, { symbols, evaluator }) };
+  return {
+    features,
+    bindings,
+    actions: [...collectFeatureActions(features, { symbols, evaluator }), ...collectCrudActions(crudDeclarations, { symbols, evaluator })]
+  };
+}
+
+// The object literal an expression holds, through const bindings, imports and
+// `Object.freeze`, or null.
+function objectLiteral(expression, symbols, depth = 0) {
+  let value = unwrapExpression(expression);
+  if (value && ts.isCallExpression(value) && value.arguments.length === 1 && ts.isPropertyAccessExpression(value.expression) &&
+    value.expression.name.text === "freeze" && ts.isIdentifier(value.expression.expression) && value.expression.expression.text === "Object") {
+    value = unwrapExpression(value.arguments[0]);
+  }
+  if (!value || depth > MAX_OBJECT_DEPTH) {
+    return null;
+  }
+  if (ts.isObjectLiteralExpression(value)) {
+    return value;
+  }
+  const declaration = ts.isIdentifier(value) ? symbols.declarationOf(value) : null;
+  return declaration && ts.isVariableDeclaration(declaration) ? objectLiteral(declaration.initializer, symbols, depth + 1) : null;
+}
+
+function memberValue(member) {
+  if (!member) {
+    return null;
+  }
+  if (ts.isPropertyAssignment(member)) {
+    return member.initializer;
+  }
+  return ts.isShorthandPropertyAssignment(member) ? member.name : null;
+}
+
+/**
+ * The functions an action's `execute` member runs.
+ * @param {import("typescript").Node} member
+ * @param {import("./types.js").CallSymbols} symbols
+ */
+function executeFunctions(member, symbols) {
+  if (isFunctionLike(member)) {
+    return [member];
+  }
+  if (ts.isPropertyAssignment(member)) {
+    return symbols.expressionImplementations(member.initializer, 0).filter(isFunctionLike);
+  }
+  if (ts.isShorthandPropertyAssignment(member)) {
+    return symbols.symbolImplementations(symbols.symbolAt(member.name)).filter(isFunctionLike);
+  }
+  return [];
+}
+
+// The custom actions a CRUD declaration adds (`actions: { name: { execute } }`).
+// Each runs its own execute; its id is the declared `id`, or
+// `crud.<resource namespace>.<name>` as crud-core names it.
+function collectCrudActions(declarations, { symbols, evaluator }) {
+  const actions = [];
+  for (const config of declarations) {
+    const definitions = objectLiteral(memberValue(memberNamed(config, "actions")), symbols);
+    for (const property of definitions?.properties || []) {
+      const name = ts.isPropertyAssignment(property) && (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) ? property.name.text : "";
+      const object = name ? objectLiteral(property.initializer, symbols) : null;
+      const execute = object && memberNamed(object, "execute");
+      if (!execute) {
+        continue;
+      }
+      // A declared id that is not a literal stays unresolved.
+      const idMember = memberNamed(object, "id");
+      const declared = idMember ? evaluator.evaluateLiteral(memberValue(idMember))?.trim() : "";
+      const namespace = declared === "" ? crudNamespace(config, { symbols, evaluator }) : null;
+      const actionId = declared || (namespace ? `crud.${namespace}.${name}` : null);
+      actions.push({ actionId, object, execute: executeFunctions(execute, symbols) });
+    }
+  }
+  return actions;
+}
+
+// The literal namespace of a CRUD declaration's `defineCrudResource` resource.
+function crudNamespace(config, { symbols, evaluator }) {
+  let resource = unwrapExpression(memberValue(memberNamed(config, "resource")));
+  for (let depth = 0; resource && ts.isIdentifier(resource) && depth < MAX_OBJECT_DEPTH; depth += 1) {
+    const declaration = symbols.declarationOf(resource);
+    resource = declaration && ts.isVariableDeclaration(declaration) ? unwrapExpression(declaration.initializer) : null;
+  }
+  const callee = resource && ts.isCallExpression(resource) ? unwrapExpression(resource.expression) : null;
+  if (!callee || !ts.isIdentifier(callee) || !symbols.isImportOf(callee, CRUD_RESOURCE_PACKAGE, ["defineCrudResource"])) {
+    return null;
+  }
+  const definition = objectLiteral(resource.arguments[0], symbols);
+  const namespace = definition && evaluator.evaluateLiteral(memberValue(memberNamed(definition, "namespace")));
+  return namespace?.trim() || null;
 }
 
 // Action definitions inside each feature's actions() result: object literals
@@ -240,18 +350,6 @@ function collectFeatureActions(features, { symbols, evaluator }) {
   }
 
   const actions = [];
-  const executeFunctions = (member) => {
-    if (isFunctionLike(member)) {
-      return [member];
-    }
-    if (ts.isPropertyAssignment(member)) {
-      return symbols.expressionImplementations(member.initializer, 0).filter(isFunctionLike);
-    }
-    if (ts.isShorthandPropertyAssignment(member)) {
-      return symbols.symbolImplementations(symbols.symbolAt(member.name)).filter(isFunctionLike);
-    }
-    return [];
-  };
   for (const feature of features) {
     found.length = 0;
     if (feature.actionFunctions.length) {
@@ -264,7 +362,7 @@ function collectFeatureActions(features, { symbols, evaluator }) {
       const idExpression = ts.isPropertyAssignment(idMember) ? idMember.initializer
         : ts.isShorthandPropertyAssignment(idMember) ? idMember.name : null;
       const actionId = idExpression && evaluator.evaluateLiteral(idExpression, { indexes, values: new Map() });
-      actions.push({ actionId, object, execute: executeFunctions(memberNamed(object, "execute")) });
+      actions.push({ actionId, object, execute: executeFunctions(memberNamed(object, "execute"), symbols) });
     }
   }
   return actions;

package/src/calls/functions.js

@@ -193,6 +193,69 @@ function collectFileFunctions({ file, hash, sourceFile, checker }) {
   return { module, functions: module ? [module, ...records] : records, nodes };
 }
 
+// A function that runs while the code around it runs: one passed straight to
+// a call, or called in place.
+function isCalledInPlace(fn) {
+  let child = fn;
+  let parent = fn.parent;
+  while (parent && ts.isParenthesizedExpression(parent)) {
+    child = parent;
+    parent = parent.parent;
+  }
+  return Boolean(parent) && (ts.isCallExpression(parent) || ts.isNewExpression(parent)) &&
+    (parent.expression === child || Boolean(parent.arguments?.includes(child)));
+}
+
+// Whether code at `node` runs while `fn` runs: no function between them is
+// stored, returned or declared to run later.
+function runsDuring(node, fn) {
+  for (let current = node.parent; current; current = current.parent) {
+    if (current === fn) {
+      return true;
+    }
+    if (isFunctionLike(current) && !isCalledInPlace(current)) {
+      return false;
+    }
+  }
+  return false;
+}
+
+// The names a function's parameters bind, destructured ones included.
+function parameterNames(fn) {
+  const names = new Set();
+  const visit = (name) => {
+    if (ts.isIdentifier(name)) {
+      names.add(name.text);
+    } else if (ts.isObjectBindingPattern(name) || ts.isArrayBindingPattern(name)) {
+      name.elements.forEach((element) => ts.isBindingElement(element) && visit(element.name));
+    }
+  };
+  fn.parameters.forEach((parameter) => visit(parameter.name));
+  return names;
+}
+
+// The function (and parameter position) a parameter or destructured
+// parameter element belongs to, with its property path.
+function owningParameter(declaration) {
+  const pathParts = [];
+  let current = declaration;
+  while (current && ts.isBindingElement(current)) {
+    if (!ts.isObjectBindingPattern(current.parent)) {
+      return null;
+    }
+    const key = current.propertyName || current.name;
+    if (!ts.isIdentifier(key) && !ts.isStringLiteralLike(key)) {
+      return null;
+    }
+    pathParts.unshift(key.text);
+    current = current.parent.parent;
+  }
+  if (!current || !ts.isParameter(current) || !isFunctionLike(current.parent)) {
+    return null;
+  }
+  return { fn: current.parent, index: current.parent.parameters.indexOf(current), path: pathParts };
+}
+
 function safeAliased(checker, symbol) {
   try {
     return checker.getAliasedSymbol(symbol);
@@ -201,4 +264,14 @@ function safeAliased(checker, symbol) {
   }
 }
 
-export { collectFileFunctions, isFunctionLike, point, safeAliased, unwrapExpression };
+export {
+  collectFileFunctions,
+  isCalledInPlace,
+  isFunctionLike,
+  owningParameter,
+  parameterNames,
+  point,
+  runsDuring,
+  safeAliased,
+  unwrapExpression
+};

package/src/calls/index.js

@@ -35,7 +35,8 @@ function rangeOf(sourceFile, node) {
 // resolved calls and call sites, transport operation uses, named action entry
 // points and entry operation controllers. `reuse` holds
 // earlier call records of files whose own and directly imported sources are
-// unchanged; they are kept unless a target no longer exists.
+// unchanged; they are kept unless a target no longer exists or the sites
+// other files' arguments resolve in them have changed.
 function inspectCalls({
   projectRoot,
   sources,
@@ -124,19 +125,25 @@ function inspectCalls({
   });
   const functionId = (node) => recordByNode.get(node)?.id;
   const functionIds = new Set(nodeById.keys());
-  const reused = new Set([...reuse].filter(([file, cached]) => callsByFile.has(file) &&
-    cached.calls.every((record) => record.targets.every((target) => functionIds.has(target)))).map(([file]) => file));
+  const targetsExist = (entries) => entries.every(({ 1: targets }) => targets.every((target) => functionIds.has(target)));
+  const reusable = new Set([...reuse].filter(([file, cached]) => callsByFile.has(file) &&
+    targetsExist(cached.sites) && cached.calls.every((record) => record.targets.every((target) => functionIds.has(target))))
+    .map(([file]) => file));
   // Each file's checker targets per call position, in call order, so argument
   // flow into closures that run later sees the same call sites whether a file
-  // is reused or resolved.
+  // is reused or resolved. A reused file's checker sites depend only on its own
+  // and directly imported sources, so they come from the cache.
   const sitesByFile = new Map();
+  const candidatesByFile = new Map();
   for (const [file, calls] of callsByFile) {
-    if (reused.has(file)) {
+    if (reusable.has(file)) {
+      const cached = reuse.get(file);
       const callAt = new Map(calls.map((call) => [call.getStart(), call]));
-      for (const [position, targets] of reuse.get(file).sites) {
+      for (const [position, targets] of cached.sites) {
         resolver.indexSite(callAt.get(position), targets.map((target) => nodeById.get(target)));
       }
-      sitesByFile.set(file, reuse.get(file).sites);
+      sitesByFile.set(file, cached.sites);
+      candidatesByFile.set(file, resolver.boundCandidates(cached.boundCandidates.map((position) => callAt.get(position))));
       continue;
     }
     const sites = [];
@@ -146,6 +153,36 @@ function inspectCalls({
       }
     });
     sitesByFile.set(file, sites);
+    candidatesByFile.set(file, resolver.boundCandidates(calls));
+  }
+  // The sites injection and argument flow resolve depend on other files'
+  // arguments, so they are resolved on every run, for every file. A site
+  // carries a third element when its targets are a guess.
+  const candidates = [...candidatesByFile.values()].flat();
+  const boundByFile = new Map([...callsByFile.keys()].map((file) => [file, []]));
+  resolver.indexBoundCalls(candidates).forEach(({ targets, probable }, index) => {
+    const call = candidates[index];
+    const file = fileOf(call);
+    const ids = targets.map(functionId);
+    if (ids.length && ids.every(Boolean) && !sitesByFile.get(file).some(([position]) => position === call.getStart())) {
+      boundByFile.get(file).push(probable ? [call.getStart(), ids, 1] : [call.getStart(), ids]);
+    }
+  });
+  // A reused file keeps its records while its bound sites are the ones they
+  // were resolved with, and while every file its records reach keeps its own.
+  const sameSites = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+  const reused = new Set([...reusable].filter((file) => sameSites(reuse.get(file).boundSites, boundByFile.get(file))));
+  const changedBound = new Set([...reusable].filter((file) => !reused.has(file)));
+  for (let changed = changedBound.size > 0; changed;) {
+    changed = false;
+    for (const file of reused) {
+      const reaches = reuse.get(file).calls.some((record) => record.targets.some((target) => changedBound.has(fileOf(nodeById.get(target)))));
+      if (reaches) {
+        reused.delete(file);
+        changedBound.add(file);
+        changed = true;
+      }
+    }
   }
 
   function enclosingFunction(node) {
@@ -158,12 +195,18 @@ function inspectCalls({
     return moduleByFile.get(fileOf(node));
   }
 
+  // What the cache keeps of a file's sites for the next run.
+  const fileSites = (file) => ({
+    sites: sitesByFile.get(file),
+    boundCandidates: candidatesByFile.get(file).map((call) => call.getStart()),
+    boundSites: boundByFile.get(file)
+  });
   const fileRecords = new Map();
   let truncated = false;
   for (const [file, calls] of callsByFile) {
     if (reused.has(file)) {
       const cached = reuse.get(file);
-      fileRecords.set(file, { functions: functionsByFile.get(file), calls: cached.calls, sites: cached.sites, truncated: cached.truncated });
+      fileRecords.set(file, { functions: functionsByFile.get(file), ...fileSites(file), calls: cached.calls, truncated: cached.truncated });
       if (cached.truncated) {
         truncated = true;
         diagnose("CALLS_TRUNCATED", `Only the first ${MAX_CALLS_PER_FILE} calls of this file are recorded.`, file);
@@ -205,7 +248,7 @@ function inspectCalls({
         });
       }
     }
-    fileRecords.set(file, { functions: functionsByFile.get(file), calls: records, sites: sitesByFile.get(file), truncated: fileTruncated });
+    fileRecords.set(file, { functions: functionsByFile.get(file), ...fileSites(file), calls: records, truncated: fileTruncated });
   }
 
   const routes = routeTable(entryOperations);