@jskit-ai/architecture-inspector 0.1.0 → 0.1.2

package/src/calls/index.js

@@ -0,0 +1,343 @@
+import ts from "typescript";
+import { bindFeatures } from "./features.js";
+import { collectFileFunctions, isFunctionLike, point } from "./functions.js";
+import { createEvaluator } from "./evaluate.js";
+import { loadCallProgram } from "./program.js";
+import { createResolver } from "./resolve.js";
+import { createSymbols } from "./symbols.js";
+import { collectTransportSites, matchSite, routeTable, sitePatterns } from "./transports.js";
+
+const MAX_CALLS_PER_FILE = 2000;
+const MAX_CALLEE_LENGTH = 120;
+
+function calleeText(call) {
+  return call.expression.getText().replace(/\s+/gu, " ").slice(0, MAX_CALLEE_LENGTH);
+}
+
+// The callee's own name token, so calls that start together (`a.b().c()`)
+// keep distinct identities.
+function callIdentityPosition(call) {
+  const callee = call.expression;
+  if (ts.isPropertyAccessExpression(callee)) {
+    return callee.name.getStart();
+  }
+  if (ts.isElementAccessExpression(callee)) {
+    return callee.argumentExpression.getStart();
+  }
+  return callee.getStart();
+}
+
+function rangeOf(sourceFile, node) {
+  return { start: point(sourceFile, node.getStart(sourceFile)), end: point(sourceFile, node.end) };
+}
+
+// Function-level facts for the declared project scripts: per-file functions,
+// 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 or the sites
+// other files' arguments resolve in them have changed.
+function inspectCalls({
+  projectRoot,
+  sources,
+  hashes,
+  resolveImport,
+  entryOperations,
+  handlerRanges,
+  transports,
+  parentIdForFile,
+  prefixAliases,
+  diagnose,
+  reuse = new Map()
+}) {
+  const loaded = loadCallProgram({ projectRoot, sources, resolveImport });
+  const { checker, sourceFiles, fileOf } = loaded;
+  // TypeScript recovers from syntax errors; such a file's functions and calls
+  // may be incomplete.
+  let complete = loaded.complete;
+  for (const [file, sourceFile] of sourceFiles) {
+    if (loaded.program.getSyntacticDiagnostics(sourceFile).length) {
+      complete = false;
+      diagnose("SCRIPT_SYNTAX_RECOVERED", "The script has syntax errors, so its functions and calls may be incomplete.", file);
+    }
+  }
+  const symbols = createSymbols({ checker, fileOf, resolveImport, isLibrary: loaded.isLibrary });
+  const evaluator = createEvaluator({ symbols, fileOf });
+
+  const functionsByFile = new Map();
+  const nodeById = new Map();
+  const recordByNode = new Map();
+  const moduleByFile = new Map();
+  const startByNode = new Map();
+  const functionNames = new Map();
+  const callsByFile = new Map();
+  const allCalls = [];
+  for (const [file, sourceFile] of sourceFiles) {
+    const collected = collectFileFunctions({ file, hash: hashes.get(file), sourceFile, checker });
+    functionsByFile.set(file, collected.functions);
+    moduleByFile.set(file, collected.module);
+    for (const { node, record, startPosition } of collected.nodes) {
+      recordByNode.set(node, record);
+      nodeById.set(record.id, node);
+      startByNode.set(node, startPosition);
+      if (record.name && record.kind !== "constructor") {
+        functionNames.set(record.name, [...(functionNames.get(record.name) || []), node]);
+      }
+    }
+    const calls = [];
+    const visit = (node) => {
+      if ((ts.isCallExpression(node) || ts.isNewExpression(node)) && node.expression) {
+        calls.push(node);
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    callsByFile.set(file, calls);
+    allCalls.push(...calls);
+  }
+
+  const features = bindFeatures({ calls: allCalls.filter((call) => ts.isCallExpression(call)), symbols, evaluator });
+  const actionsById = new Map();
+  const unresolvedActionFiles = new Set();
+  for (const action of features.actions) {
+    if (!action.actionId) {
+      unresolvedActionFiles.add(fileOf(action.object));
+      continue;
+    }
+    const known = actionsById.get(action.actionId) || [];
+    if (!known.some((entry) => entry.object === action.object)) {
+      actionsById.set(action.actionId, [...known, action]);
+    }
+  }
+  for (const file of unresolvedActionFiles) {
+    diagnose("ACTION_ID_UNRESOLVED", "An action definition's id is not a literal, constant or literal-array element.", file);
+  }
+
+  const resolver = createResolver({
+    program: loaded.program,
+    checker,
+    symbols,
+    evaluator,
+    bindings: features.bindings,
+    actionsById,
+    fileOf,
+    functionNames
+  });
+  const functionId = (node) => recordByNode.get(node)?.id;
+  const functionIds = new Set(nodeById.keys());
+  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. 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 (reusable.has(file)) {
+      const cached = reuse.get(file);
+      const callAt = new Map(calls.map((call) => [call.getStart(), call]));
+      for (const [position, targets] of cached.sites) {
+        resolver.indexSite(callAt.get(position), targets.map((target) => nodeById.get(target)));
+      }
+      sitesByFile.set(file, cached.sites);
+      candidatesByFile.set(file, resolver.boundCandidates(cached.boundCandidates.map((position) => callAt.get(position))));
+      continue;
+    }
+    const sites = [];
+    resolver.indexCalls(calls).forEach((targets, index) => {
+      if (targets.length) {
+        sites.push([calls[index].getStart(), targets.map(functionId)]);
+      }
+    });
+    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) {
+    const position = node.getStart();
+    for (let current = node.parent; current; current = current.parent) {
+      if (isFunctionLike(current) && startByNode.get(current) <= position) {
+        return recordByNode.get(current);
+      }
+    }
+    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), ...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);
+      }
+      continue;
+    }
+    const sourceFile = sourceFiles.get(file);
+    const records = [];
+    let fileTruncated = false;
+    const identities = new Set();
+    let count = 0;
+    for (const call of calls) {
+      const from = enclosingFunction(call);
+      // The call itself, then what it reaches through the functions it passes.
+      const results = from ? [resolver.resolve(call, file), resolver.passedCall(call)].filter(Boolean) : [];
+      if (count + results.length > MAX_CALLS_PER_FILE) {
+        fileTruncated = true;
+        truncated = true;
+        diagnose("CALLS_TRUNCATED", `Only the first ${MAX_CALLS_PER_FILE} calls of this file are recorded.`, file);
+        break;
+      }
+      const position = point(sourceFile, callIdentityPosition(call));
+      for (const result of results) {
+        count += 1;
+        let id = `call:jskit:${file}#${position.line}:${position.column}`;
+        for (let suffix = 2; identities.has(id); suffix += 1) {
+          id = `call:jskit:${file}#${position.line}:${position.column}~${suffix}`;
+        }
+        identities.add(id);
+        records.push({
+          id,
+          resolution: result.resolution,
+          certainty: result.certainty,
+          method: result.method,
+          fromFunctionId: from.id,
+          targets: result.targets.map(functionId),
+          callee: calleeText(call),
+          evidence: [{ path: file, hash: hashes.get(file), ...rangeOf(sourceFile, call) }]
+        });
+      }
+    }
+    fileRecords.set(file, { functions: functionsByFile.get(file), ...fileSites(file), calls: records, truncated: fileTruncated });
+  }
+
+  const routes = routeTable(entryOperations);
+  const operationUses = [];
+  for (const site of transports ? collectTransportSites({ calls: allCalls, symbols, evaluator, fileOf }) : []) {
+    const sourceFile = sourceFiles.get(site.file);
+    const from = enclosingFunction(site.call);
+    if (!from) {
+      continue;
+    }
+    const position = point(sourceFile, site.call.getStart());
+    const baseId = `operation-use:${site.file}#${position.line}:${position.column}`;
+    const parentId = parentIdForFile(site.file);
+    const evidence = [{ path: site.file, hash: hashes.get(site.file), ...rangeOf(sourceFile, site.call) }];
+    const matched = matchSite({ patterns: sitePatterns(site, evaluator), methods: site.methods }, routes, prefixAliases)
+      .flatMap(({ method, matches }) => (matches.length ? matches : [{ method, route: null }]).map((match) => ({ method, ...match })));
+    const uses = matched.length ? matched : [{ method: null, route: null }];
+    uses.forEach((use, index) => {
+      operationUses.push({
+        id: uses.length === 1 ? baseId : `${baseId}:${use.method || "ANY"}:${index + 1}`,
+        ...(parentId ? { parentId } : {}),
+        fromFunctionId: from.id,
+        resolution: use.route ? "resolved" : "unresolved",
+        ...(use.route ? { key: use.route.key, keyCertainty: use.keyCertainty } : {}),
+        evidence
+      });
+    });
+  }
+
+  const entryPoints = [];
+  for (const [actionId, definitions] of actionsById) {
+    const executes = [...new Set(definitions.flatMap((definition) => definition.execute))];
+    const first = definitions[0].object;
+    const file = fileOf(first);
+    entryPoints.push({
+      id: `entry:action:${actionId}`,
+      resolution: "resolved",
+      kind: "action",
+      title: actionId,
+      file,
+      functionIds: executes.map(functionId).filter(Boolean),
+      pageId: null,
+      componentId: null,
+      operationKey: null,
+      actionId,
+      evidence: definitions.map((definition) => {
+        const owner = fileOf(definition.object);
+        return { path: owner, hash: hashes.get(owner), ...rangeOf(sourceFiles.get(owner), definition.object) };
+      })
+    });
+  }
+
+  function actionController(actionId) {
+    const definitions = actionsById.get(actionId) || [];
+    const executes = definitions.flatMap((definition) => definition.execute);
+    return definitions.length === 1 && executes.length === 1 ? functionId(executes[0]) : null;
+  }
+  // The function whose source range (start offset .. end offset) is given.
+  function functionAt({ file, start, end }) {
+    const sourceFile = sourceFiles.get(file);
+    let found = null;
+    const visit = (node) => {
+      if (found || node.end < start || node.pos > end) {
+        return;
+      }
+      if (isFunctionLike(node) && node.getStart(sourceFile) === start && node.end === end) {
+        found = recordByNode.get(node);
+        return;
+      }
+      ts.forEachChild(node, visit);
+    };
+    if (sourceFile) {
+      visit(sourceFile);
+    }
+    return found?.id || null;
+  }
+  // Each entry operation's controller: its action's execute function, or the
+  // inline handler. Only plain records are returned, so the program can be
+  // released before the output is written.
+  const controllers = new Map();
+  for (const entry of entryOperations) {
+    const handler = handlerRanges.get(entry);
+    const controller = entry.actionId ? actionController(entry.actionId) : handler && functionAt(handler);
+    if (controller) {
+      controllers.set(entry, controller);
+    }
+  }
+
+  return { fileRecords, operationUses, entryPoints, controllers, complete, truncated };
+}
+
+export { inspectCalls };

package/src/calls/program.js

@@ -0,0 +1,143 @@
+import path from "node:path";
+import ts from "typescript";
+import { parse as parseSfc } from "@vue/compiler-sfc";
+
+const SCRIPT_EXTENSIONS = Object.freeze({
+  ".js": ts.Extension.Js,
+  ".mjs": ts.Extension.Mjs,
+  ".cjs": ts.Extension.Cjs,
+  ".jsx": ts.Extension.Jsx,
+  ".ts": ts.Extension.Ts,
+  ".tsx": ts.Extension.Tsx
+});
+const LIBRARIES = Object.freeze(["lib.es2023.d.ts", "lib.dom.d.ts", "lib.dom.iterable.d.ts"]);
+const COMPILER_OPTIONS = Object.freeze({
+  allowJs: true,
+  checkJs: false,
+  noEmit: true,
+  strict: false,
+  target: ts.ScriptTarget.ES2022,
+  module: ts.ModuleKind.ESNext,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  jsx: ts.JsxEmit.Preserve,
+  skipLibCheck: true,
+  skipDefaultLibCheck: true,
+  allowArbitraryExtensions: true,
+  allowImportingTsExtensions: true,
+  maxNodeModuleJsDepth: 0,
+  types: [],
+  lib: LIBRARIES
+});
+
+// A Vue component's script blocks at their original offsets; template and
+// style text become spaces so every position matches the component file.
+function vueScriptText(source, filePath) {
+  const { descriptor, errors } = parseSfc(source, { filename: filePath, sourceMap: false });
+  if (errors.length) {
+    return null;
+  }
+  const characters = source.replace(/[^\n]/gu, " ").split("");
+  let extension = ".js";
+  for (const script of [descriptor.script, descriptor.scriptSetup].filter((entry) => entry && !entry.src)) {
+    const start = script.loc.start.offset;
+    for (let index = 0; index < script.content.length; index += 1) {
+      characters[start + index] = script.content[index];
+    }
+    if (script.lang === "ts" || script.lang === "tsx") {
+      extension = `.${script.lang}`;
+    } else if (script.lang === "jsx" && extension === ".js") {
+      extension = ".jsx";
+    }
+  }
+  return { text: characters.join(""), extension };
+}
+
+// One TypeScript program over the declared, hash-verified project
+// scripts only. Imports resolve through the inspector's own resolver
+// (relative, aliases, declared package entry points); everything else, including
+// every node_modules package, stays outside the program. TypeScript's default
+// libraries remain so builtin calls are recognised and dropped.
+function loadCallProgram({ projectRoot, sources, resolveImport }) {
+  const virtual = new Map();
+  const realToVirtual = new Map();
+  let complete = true;
+  for (const [file, source] of sources) {
+    const absolute = path.join(projectRoot, file);
+    let text = source;
+    let name = absolute;
+    if (file.endsWith(".vue")) {
+      const script = vueScriptText(source, file);
+      if (!script) {
+        complete = false;
+        continue;
+      }
+      text = script.text;
+      name = `${absolute}${script.extension}`;
+    } else if (!SCRIPT_EXTENSIONS[path.extname(file)]) {
+      continue;
+    }
+    virtual.set(name, { file, text });
+    realToVirtual.set(file, name);
+  }
+
+  const libraryDirectory = path.dirname(ts.getDefaultLibFilePath(COMPILER_OPTIONS));
+  const isLibraryFile = (name) => path.dirname(name) === libraryDirectory && /^lib\.[\w.]*\.d\.ts$/u.test(path.basename(name));
+  const resolutions = new Map();
+  function resolveModule(specifier, containing) {
+    const from = virtual.get(containing)?.file;
+    if (!from) {
+      return undefined;
+    }
+    const key = `${path.posix.dirname(from)}\0${specifier}`;
+    if (!resolutions.has(key)) {
+      const target = resolveImport(from, specifier);
+      const name = target && realToVirtual.get(target);
+      const extension = name && SCRIPT_EXTENSIONS[path.extname(name)];
+      resolutions.set(key, extension ? { resolvedFileName: name, extension, isExternalLibraryImport: false } : undefined);
+    }
+    return resolutions.get(key);
+  }
+
+  const host = {
+    getSourceFile(name, languageVersion) {
+      const text = virtual.get(name)?.text ?? (isLibraryFile(name) ? ts.sys.readFile(name) : undefined);
+      return text === undefined ? undefined : ts.createSourceFile(name, text, languageVersion);
+    },
+    getDefaultLibFileName: (options) => ts.getDefaultLibFilePath(options),
+    writeFile: () => {},
+    getCurrentDirectory: () => projectRoot,
+    getCanonicalFileName: (name) => name,
+    useCaseSensitiveFileNames: () => true,
+    getNewLine: () => "\n",
+    fileExists: (name) => virtual.has(name) || (isLibraryFile(name) && ts.sys.fileExists(name)),
+    readFile: (name) => virtual.get(name)?.text ?? (isLibraryFile(name) ? ts.sys.readFile(name) : undefined),
+    directoryExists: (name) => name === libraryDirectory || name === projectRoot || name.startsWith(`${projectRoot}${path.sep}`),
+    getDirectories: () => [],
+    realpath: (name) => name,
+    resolveModuleNameLiterals: (literals, containing) =>
+      literals.map((literal) => ({ resolvedModule: resolveModule(literal.text, containing) })),
+    resolveTypeReferenceDirectiveReferences: (references) =>
+      references.map(() => ({ resolvedTypeReferenceDirective: undefined }))
+  };
+  const program = ts.createProgram({ rootNames: [...virtual.keys()], options: COMPILER_OPTIONS, host });
+  const sourceFiles = new Map();
+  for (const sourceFile of program.getSourceFiles()) {
+    const file = virtual.get(sourceFile.fileName)?.file;
+    if (file) {
+      sourceFiles.set(file, sourceFile);
+    }
+  }
+  return {
+    ts,
+    complete,
+    program,
+    checker: program.getTypeChecker(),
+    sourceFiles,
+    fileOf: (node) => virtual.get(node.getSourceFile().fileName)?.file ?? null,
+    isLibrary: (node) => program.isSourceFileDefaultLibrary(node.getSourceFile()),
+    programFiles: program.getSourceFiles().map((sourceFile) =>
+      virtual.get(sourceFile.fileName)?.file ?? path.relative(projectRoot, sourceFile.fileName))
+  };
+}
+
+export { loadCallProgram };