@jskit-ai/architecture-inspector 0.1.1 → 0.1.2

package/src/calls/resolve.js

@@ -2,19 +2,15 @@ import { EventEmitter } from "node:events";
 import { Stats } from "node:fs";
 import { Duplex } from "node:stream";
 import ts from "typescript";
-import { isFunctionLike, unwrapExpression } from "./functions.js";
+import { isCalledInPlace, isFunctionLike, owningParameter, parameterNames, runsDuring, unwrapExpression } from "./functions.js";
 import { isClassLike } from "./symbols.js";
 import { isLiteralPattern } from "./evaluate.js";
+import { NODE_GLOBALS, createExternalValues, isComponentFile } from "./external.js";
 
 const MAX_TARGETS = 16;
 const MAX_TYPE_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"]);
-// Vue's `<script setup>` compiler macros are globals of component scripts;
-// emit functions and model refs they return are Vue's own values.
+// Vue's `<script setup>` compiler macros are globals of component scripts.
 const VUE_MACROS = new Set(["defineProps", "defineEmits", "defineExpose", "defineOptions", "defineSlots", "defineModel", "withDefaults"]);
-const VUE_EXTERNAL_VALUES = new Set(["defineEmits", "defineModel"]);
 // Node objects untyped receivers most often hold; TypeScript's libraries do
 // not declare their members, so the names are read from Node itself.
 const NODE_MEMBER_SOURCES = Object.freeze([EventEmitter.prototype, Stats.prototype, Duplex.prototype]);
@@ -41,15 +37,6 @@ function codeSide(file) {
   return "shared";
 }
 
-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");
-}
-
 function compatibleSides(left, right) {
   return left === "shared" || right === "shared" || left === right;
 }
@@ -78,47 +65,6 @@ function libraryMemberNames(program) {
   return names;
 }
 
-// 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;
-}
-
 function constructorOf(implementation) {
   if (!isClassLike(implementation)) {
     return implementation;
@@ -126,16 +72,50 @@ function constructorOf(implementation) {
   return implementation.members.find((member) => ts.isConstructorDeclaration(member) && member.body) || null;
 }
 
-// Call resolution over one program: TypeScript checker targets, defineFeature
-// injection, argument flow, literal-array unrolling and receiver names, each
-// labelled with its certainty. Provably external calls are dropped.
+/**
+ * Call resolution over one program: TypeScript checker targets, defineFeature
+ * injection, argument flow, literal-array unrolling and receiver names, each
+ * labelled with its certainty. Provably external calls are dropped.
+ * @param {object} dependencies
+ * @param {import("typescript").Program} dependencies.program
+ * @param {import("typescript").TypeChecker} dependencies.checker
+ * @param {import("./types.js").CallSymbols} dependencies.symbols
+ * @param {import("./types.js").CallEvaluator} dependencies.evaluator
+ * @param {import("./types.js").FeatureBindings["bindings"]} dependencies.bindings
+ * @param {Map<string, import("./types.js").FeatureBindings["actions"]>} dependencies.actionsById
+ * @param {import("./types.js").FileOf} dependencies.fileOf
+ * @param {Map<string, import("typescript").Node[]>} dependencies.functionNames
+ */
 function createResolver({ program, checker, symbols, evaluator, bindings, actionsById, fileOf, functionNames }) {
   const builtinMembers = libraryMemberNames(program);
+  const { isExternalValue, isExternalDeclaration } = createExternalValues({ checker, symbols, fileOf });
+  /** @type {Map<import("typescript").Node, import("typescript").CallExpression[]>} */
   const callSites = new Map();
   const direct = new Map();
+  // The functions each indexed call reaches, and the calls whose index entry
+  // came from a guess (several values or an ambiguous injection).
+  /** @type {Map<import("typescript").CallExpression, import("typescript").Node[]>} */
+  const indexedTargets = new Map();
+  /** @type {Set<import("typescript").CallExpression>} */
+  const probableSites = new Set();
 
   function implementationsFor(symbol) {
-    return symbols.symbolImplementations(symbol).map(constructorOf).filter(Boolean);
+    const found = symbols.symbolImplementations(symbol).map(constructorOf).filter(Boolean);
+    return found.length ? found : declaredMemberImplementations(symbol);
+  }
+
+  // A member a type declares without a value (`{ run: typeof run }` or
+  // `@property {typeof run} run`) holds the function or class its type names.
+  function declaredMemberImplementations(symbol) {
+    const declarations = symbol?.declarations || [];
+    if (!declarations.length || !declarations.every((declaration) => ts.isPropertySignature(declaration) || ts.isJSDocPropertyTag(declaration))) {
+      return [];
+    }
+    const type = checker.getTypeOfSymbol(symbol);
+    if (!type.getCallSignatures().length && !type.getConstructSignatures().length) {
+      return [];
+    }
+    return symbols.symbolImplementations(type.getSymbol()).map(constructorOf).filter(Boolean);
   }
 
   // Pass 1: what the checker resolves on its own, and the call-site index
@@ -179,14 +159,26 @@ function createResolver({ program, checker, symbols, evaluator, bindings, action
     return { kind: "other" };
   }
 
-  // Records that a call reaches these functions, for argument flow.
-  function indexSite(call, targets) {
+  // Records that a call reaches these functions, for argument flow. A
+  // probable site's values are never exact.
+  function indexSite(call, targets, probable = false) {
+    const known = indexedTargets.get(call) || [];
     for (const target of targets) {
+      if (known.includes(target)) {
+        continue;
+      }
+      known.push(target);
       if (!callSites.has(target)) {
         callSites.set(target, []);
       }
       callSites.get(target).push(call);
     }
+    if (known.length) {
+      indexedTargets.set(call, known);
+    }
+    if (probable) {
+      probableSites.add(call);
+    }
   }
 
   // The checker's own targets of each call; returns them per call.
@@ -199,28 +191,6 @@ function createResolver({ program, checker, symbols, evaluator, bindings, action
     });
   }
 
-  // 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 };
-  }
-
   // The value one call gives a parameter: the argument, or the property of an
   // object literal argument a destructured parameter takes, with the rest of
   // its property path.
@@ -242,7 +212,13 @@ function createResolver({ program, checker, symbols, evaluator, bindings, action
 
   function argumentValues(declaration) {
     const owner = owningParameter(declaration);
-    return owner ? (callSites.get(owner.fn) || []).map((call) => argumentValue(call, owner)).filter(Boolean) : [];
+    if (!owner) {
+      return [];
+    }
+    return (callSites.get(owner.fn) || []).map((call) => {
+      const value = argumentValue(call, owner);
+      return value && { ...value, probable: probableSites.has(call) };
+    }).filter(Boolean);
   }
 
   function propertyValueExpressions(property) {
@@ -389,11 +365,24 @@ function createResolver({ program, checker, symbols, evaluator, bindings, action
     return { resolution: "unresolved", certainty: "unresolved", method: "none", targets: [] };
   }
 
-  // The functions a passed value can be, added to `targets`.
-  function addValueTargets(value, targets, exact = false) {
+  // The functions a passed value can be, added to `targets`. With `passedOn`,
+  // the path of parameters followed so far, a parameter the value passes on
+  // holds what its own callers give it; a callback a helper runs (passedCall)
+  // is never followed to another caller's value.
+  function addValueTargets(value, targets, exact = false, passedOn = null) {
     const found = value.path.length
       ? [...targetsFromTypes(valueTypes({ expression: value.expression, path: value.path.slice(0, -1) }, 0, new Set()), [value.path.at(-1)]).targets.keys()]
       : symbols.expressionImplementations(value.expression, 0).map(constructorOf).filter(Boolean);
+    const expression = unwrapExpression(value.expression);
+    const parameter = passedOn && !found.length && !value.path.length && ts.isIdentifier(expression) ? symbols.declarationOf(expression) : null;
+    if (parameter && (ts.isParameter(parameter) || ts.isBindingElement(parameter)) &&
+      !passedOn.includes(parameter) && passedOn.length < MAX_TYPE_DEPTH) {
+      const values = argumentValues(parameter);
+      for (const passed of values) {
+        addValueTargets(passed, targets, exact && values.length === 1 && !passed.probable, [...passedOn, parameter]);
+      }
+      return;
+    }
     for (const target of found) {
       targets.set(target, { exact: exact && found.length === 1 && !value.path.length, via: "argument-flow" });
     }
@@ -419,7 +408,7 @@ function createResolver({ program, checker, symbols, evaluator, bindings, action
     }
     const values = argumentValues(declaration);
     for (const value of values) {
-      addValueTargets(value, targets, values.length === 1);
+      addValueTargets(value, targets, values.length === 1 && !value.probable, []);
     }
     return targets;
   }
@@ -431,6 +420,46 @@ function createResolver({ program, checker, symbols, evaluator, bindings, action
     return direct.get(call).targets || [];
   }
 
+  // The functions a call reaches as the index knows them: the checker's, or
+  // those injection or argument flow resolved.
+  function siteTargets(call) {
+    return indexedTargets.get(call) || checkerTargets(call);
+  }
+
+  // The calls whose callee is a parameter or a destructured name: those
+  // injection or argument flow can resolve. What a call's callee is declared
+  // as depends only on its own file.
+  function boundCandidates(calls) {
+    return calls.filter((call) => {
+      checkerTargets(call);
+      const declaration = direct.get(call).declaration;
+      return declaration && (ts.isParameter(declaration) || ts.isBindingElement(declaration));
+    });
+  }
+
+  // Calls the checker cannot resolve but injection or argument flow can are
+  // call sites too, so argument flow and the callbacks a call passes reach
+  // through them. Each round can expose more; the targets and guesses only
+  // grow, so the rounds stop. Takes the candidates of every file, since one
+  // file's arguments decide another's targets, and returns each candidate's
+  // targets and whether they are a guess.
+  function indexBoundCalls(candidates) {
+    for (let changed = true; changed;) {
+      changed = false;
+      for (const call of candidates) {
+        const found = boundFunctionTargets(direct.get(call).declaration, call);
+        const targets = found.size > MAX_TARGETS ? [] : [...found.keys()];
+        const probable = targets.length !== 1 || !found.get(targets[0]).exact;
+        const known = indexedTargets.get(call) || [];
+        if (targets.some((target) => !known.includes(target)) || (probable && targets.length && !probableSites.has(call))) {
+          indexSite(call, targets, probable);
+          changed = true;
+        }
+      }
+    }
+    return candidates.map((call) => ({ targets: indexedTargets.get(call) || [], probable: probableSites.has(call) }));
+  }
+
   // The parameters ({ index, path }) a function calls while it runs: in its
   // own body, in callbacks it passes on, or by forwarding them to a function
   // that does. A cycle adds nothing.
@@ -462,7 +491,7 @@ function createResolver({ program, checker, symbols, evaluator, bindings, action
         }
         node.arguments.forEach((argument, position) => {
           const forwarded = own(argument);
-          for (const target of forwarded ? checkerTargets(node) : []) {
+          for (const target of forwarded ? siteTargets(node) : []) {
             for (const inner of invokedParameters(target)) {
               if (inner.index === position) {
                 add(forwarded.index, [...forwarded.path, ...inner.path]);
@@ -486,11 +515,11 @@ function createResolver({ program, checker, symbols, evaluator, bindings, action
       return null;
     }
     const targets = new Map();
-    for (const callee of checkerTargets(call)) {
+    for (const callee of siteTargets(call)) {
       for (const parameter of invokedParameters(callee)) {
         const value = argumentValue(call, parameter);
         if (value) {
-          addValueTargets(value, targets, true);
+          addValueTargets(value, targets, !probableSites.has(call));
         }
       }
     }
@@ -498,96 +527,6 @@ function createResolver({ program, checker, symbols, evaluator, bindings, action
     return result?.resolution === "unresolved" ? null : result;
   }
 
-  // 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_TYPE_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_TYPE_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);
-  }
-
   function receiverHint(receiver, candidates) {
     const text = receiver?.getText().split(".").pop()?.replace(/Service$/u, "").toLowerCase();
     if (!text || !/^[a-z][\w]*$/u.test(text)) {
@@ -713,7 +652,7 @@ function createResolver({ program, checker, symbols, evaluator, bindings, action
     }
   }
 
-  return { indexCalls, indexSite, resolve, passedCall, builtinMembers };
+  return { indexCalls, indexSite, boundCandidates, indexBoundCalls, resolve, passedCall, builtinMembers };
 }
 
 export { codeSide, createResolver };

package/src/calls/symbols.js

@@ -88,6 +88,9 @@ function createSymbols(context) {
     if (ts.isShorthandPropertyAssignment(declaration)) {
       return symbolImplementations(checker.getShorthandAssignmentValueSymbol(declaration), depth + 1);
     }
+    if (ts.isBindingElement(declaration)) {
+      return bindingElementImplementations(declaration, depth + 1);
+    }
     if (ts.isExportSpecifier(declaration) || ts.isImportSpecifier(declaration) || ts.isImportClause(declaration)) {
       return symbolImplementations(checker.getSymbolAtLocation(declaration.name), depth + 1);
     }
@@ -104,6 +107,26 @@ function createSymbols(context) {
     return [];
   }
 
+  // A name an object pattern binds (`const { a: b } = source`, a parameter's
+  // pattern, or one nested in another) holds the property it reads from the
+  // type of what the pattern destructures.
+  function bindingElementImplementations(element, depth) {
+    const key = element.propertyName || element.name;
+    if (!ts.isObjectBindingPattern(element.parent) || element.dotDotDotToken || !(ts.isIdentifier(key) || ts.isStringLiteralLike(key))) {
+      return [];
+    }
+    const property = checker.getTypeAtLocation(element.parent).getProperty(key.text);
+    const found = new Set();
+    for (const declaration of property?.declarations || []) {
+      if (declaration !== element) {
+        for (const implementation of declarationImplementations(declaration, depth)) {
+          found.add(implementation);
+        }
+      }
+    }
+    return [...found];
+  }
+
   function expressionImplementations(expression, depth) {
     const value = unwrapExpression(expression);
     if (!value || depth > MAX_DEPTH) {

package/src/calls/types.js

@@ -0,0 +1,9 @@
+// The collaborators the call layer's factories hand each other over one
+// loaded call program.
+
+/** @typedef {ReturnType<typeof import("./program.js").loadCallProgram>["fileOf"]} FileOf */
+/** @typedef {ReturnType<typeof import("./symbols.js").createSymbols>} CallSymbols */
+/** @typedef {ReturnType<typeof import("./evaluate.js").createEvaluator>} CallEvaluator */
+/** @typedef {ReturnType<typeof import("./features.js").bindFeatures>} FeatureBindings */
+
+export {};