@jskit-ai/architecture-inspector 0.1.0 → 0.1.2

package/src/calls/symbols.js

@@ -0,0 +1,201 @@
+import ts from "typescript";
+import { isFunctionLike, safeAliased, unwrapExpression } from "./functions.js";
+
+const MAX_DEPTH = 8;
+
+function isClassLike(node) {
+  return Boolean(node) && (ts.isClassDeclaration(node) || ts.isClassExpression(node));
+}
+
+function isBareSpecifier(specifier) {
+  return typeof specifier === "string" && !specifier.startsWith(".") && !specifier.startsWith("/");
+}
+
+// Symbol and declaration helpers over one loaded call program.
+function createSymbols(context) {
+  const { checker, fileOf, resolveImport } = context;
+
+  function symbolAt(node) {
+    if (!node) {
+      return undefined;
+    }
+    const parent = node.parent;
+    if (parent && ts.isShorthandPropertyAssignment(parent) && parent.name === node) {
+      return checker.getShorthandAssignmentValueSymbol(parent);
+    }
+    return checker.getSymbolAtLocation(node);
+  }
+
+  function resolved(symbol) {
+    return symbol && symbol.flags & ts.SymbolFlags.Alias ? safeAliased(checker, symbol) : symbol;
+  }
+
+  function declarationOf(node) {
+    const symbol = resolved(symbolAt(node));
+    return symbol?.valueDeclaration || symbol?.declarations?.[0] || null;
+  }
+
+  // The import an identifier is bound to: { specifier, imported }, or null.
+  function importOf(identifier) {
+    const symbol = symbolAt(identifier);
+    if (!symbol || !(symbol.flags & ts.SymbolFlags.Alias)) {
+      return null;
+    }
+    const declaration = symbol.declarations?.[0];
+    if (!declaration) {
+      return null;
+    }
+    let importDeclaration = declaration;
+    while (importDeclaration && !ts.isImportDeclaration(importDeclaration)) {
+      importDeclaration = importDeclaration.parent;
+    }
+    if (!importDeclaration || !ts.isStringLiteralLike(importDeclaration.moduleSpecifier)) {
+      return null;
+    }
+    let imported = "default";
+    if (ts.isImportSpecifier(declaration)) {
+      imported = (declaration.propertyName || declaration.name).text;
+    } else if (ts.isNamespaceImport(declaration)) {
+      imported = "*";
+    }
+    return { specifier: importDeclaration.moduleSpecifier.text, imported, file: fileOf(declaration) };
+  }
+
+  // A package import that does not resolve to declared project source.
+  function isPackageImport(identifier) {
+    const binding = importOf(identifier);
+    return Boolean(binding) && isBareSpecifier(binding.specifier) && !resolveImport(binding.file, binding.specifier);
+  }
+
+  function isImportOf(identifier, packagePrefix, names) {
+    const binding = importOf(identifier);
+    return Boolean(binding) &&
+      (binding.specifier === packagePrefix || binding.specifier.startsWith(`${packagePrefix}/`)) &&
+      names.includes(binding.imported);
+  }
+
+  // The project function (or class) a declaration ultimately names.
+  function declarationImplementations(declaration, depth = 0) {
+    if (!declaration || depth > MAX_DEPTH) {
+      return [];
+    }
+    if (isFunctionLike(declaration) || isClassLike(declaration)) {
+      return fileOf(declaration) ? [declaration] : [];
+    }
+    if (ts.isVariableDeclaration(declaration) || ts.isPropertyAssignment(declaration) || ts.isPropertyDeclaration(declaration)) {
+      return expressionImplementations(declaration.initializer, depth + 1);
+    }
+    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);
+    }
+    if (ts.isExportAssignment(declaration)) {
+      return expressionImplementations(declaration.expression, depth + 1);
+    }
+    if (ts.isBinaryExpression(declaration) && declaration.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+      return expressionImplementations(declaration.right, depth + 1);
+    }
+    if ((ts.isPropertyAccessExpression(declaration) || ts.isElementAccessExpression(declaration)) &&
+      ts.isBinaryExpression(declaration.parent) && declaration.parent.left === declaration) {
+      return expressionImplementations(declaration.parent.right, depth + 1);
+    }
+    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) {
+      return [];
+    }
+    if (isFunctionLike(value) || isClassLike(value)) {
+      return fileOf(value) ? [value] : [];
+    }
+    if (ts.isIdentifier(value)) {
+      return symbolImplementations(symbolAt(value), depth + 1);
+    }
+    if (ts.isPropertyAccessExpression(value)) {
+      return symbolImplementations(checker.getSymbolAtLocation(value.name), depth + 1);
+    }
+    if (ts.isCallExpression(value)) {
+      // A factory-returned closure: `fileArea: createFileArea(service)`.
+      const declaration = checker.getTypeAtLocation(value).getSymbol()?.valueDeclaration;
+      return declaration && isFunctionLike(declaration) && fileOf(declaration) ? [declaration] : [];
+    }
+    return [];
+  }
+
+  function symbolImplementations(symbol, depth = 0) {
+    const target = resolved(symbol);
+    const found = new Set();
+    for (const declaration of target?.declarations || []) {
+      for (const implementation of declarationImplementations(declaration, depth)) {
+        found.add(implementation);
+      }
+    }
+    return [...found];
+  }
+
+  // Whether a symbol's declarations all live in TypeScript's default libraries.
+  function isLibrarySymbol(symbol) {
+    const target = resolved(symbol);
+    const declarations = target?.declarations || [];
+    return declarations.length > 0 && declarations.every((declaration) => context.isLibrary(declaration));
+  }
+
+  // The leftmost identifier of a receiver chain, through calls and member access.
+  function receiverRoot(expression) {
+    let current = unwrapExpression(expression);
+    while (current) {
+      if (ts.isPropertyAccessExpression(current) || ts.isElementAccessExpression(current)) {
+        current = unwrapExpression(current.expression);
+      } else if (ts.isCallExpression(current) || ts.isNewExpression(current)) {
+        current = unwrapExpression(current.expression);
+      } else if (ts.isAwaitExpression(current)) {
+        current = unwrapExpression(current.expression);
+      } else {
+        return current;
+      }
+    }
+    return null;
+  }
+
+  return {
+    symbolAt,
+    resolved,
+    declarationOf,
+    importOf,
+    isPackageImport,
+    isImportOf,
+    symbolImplementations,
+    expressionImplementations,
+    isLibrarySymbol,
+    receiverRoot
+  };
+}
+
+export { createSymbols, isClassLike };

package/src/calls/transports.js

@@ -0,0 +1,194 @@
+import ts from "typescript";
+import { resolveScopedApiBasePath } from "@jskit-ai/kernel/shared/surface";
+import { isFunctionLike, unwrapExpression } from "./functions.js";
+import { ANY, SEGMENT, isLiteralPattern } from "./evaluate.js";
+import { codeSide } from "./resolve.js";
+
+const HTTP_WEB = "@jskit-ai/http-web";
+const METHOD_PATTERN = /^[A-Za-z]+$/u;
+const MAX_PROBABLE_ROUTES = 3;
+
+function literalMethods(evaluator, node) {
+  if (!node) {
+    return undefined;
+  }
+  const values = evaluator.evaluate(node);
+  return values.every((value) => isLiteralPattern(value) && METHOD_PATTERN.test(value))
+    ? [...new Set(values.map((value) => value.toUpperCase()))]
+    : null;
+}
+
+function isFalse(node) {
+  return unwrapExpression(node)?.kind === ts.SyntaxKind.FalseKeyword;
+}
+
+// JSKIT client transport call sites with their partially evaluated paths and
+// methods (`methods: null` means any method).
+function collectTransportSites({ calls, symbols, evaluator, fileOf }) {
+  const sites = [];
+  const option = (call, name, index = 0) => {
+    const options = unwrapExpression(call.arguments[index]);
+    return options && ts.isObjectLiteralExpression(options) ? evaluator.propertyInitializer(options, name) : undefined;
+  };
+  const isHttpClient = (expression) => {
+    let value = unwrapExpression(expression);
+    if (value && ts.isIdentifier(value)) {
+      const declaration = symbols.declarationOf(value);
+      value = declaration && ts.isVariableDeclaration(declaration) ? unwrapExpression(declaration.initializer) : null;
+    }
+    return Boolean(value) && ts.isCallExpression(value) && ts.isIdentifier(value.expression) &&
+      symbols.isImportOf(value.expression, HTTP_WEB, ["getHttpWebClient"]);
+  };
+  for (const call of calls) {
+    if (!ts.isCallExpression(call)) {
+      continue;
+    }
+    const callee = unwrapExpression(call.expression);
+    const file = fileOf(call);
+    if (ts.isIdentifier(callee) && symbols.isImportOf(callee, HTTP_WEB, ["useEndpointResource"])) {
+      const reads = !isFalse(option(call, "enabled"));
+      const writeMethod = option(call, "writeMethod");
+      const writes = writeMethod ? literalMethods(evaluator, writeMethod) : reads ? [] : ["PATCH"];
+      sites.push({ call, file, kind: "useEndpointResource", path: option(call, "path"), methods: writes === null ? null : [...(reads ? ["GET"] : []), ...writes] });
+    } else if (ts.isIdentifier(callee) && symbols.isImportOf(callee, HTTP_WEB, ["useCommand"])) {
+      const build = unwrapExpression(option(call, "buildCommandOptions"));
+      const built = build && isFunctionLike(build) ? unwrapExpression(evaluator.functionReturns(build)[0]) : null;
+      const builtObject = built && ts.isObjectLiteralExpression(built) ? built : null;
+      const builtPath = builtObject && evaluator.propertyInitializer(builtObject, "path");
+      const builtMethod = builtObject && literalMethods(evaluator, evaluator.propertyInitializer(builtObject, "method"));
+      const writeMethod = literalMethods(evaluator, option(call, "writeMethod"));
+      sites.push({
+        call,
+        file,
+        kind: "useCommand",
+        path: builtPath || null,
+        apiSuffix: builtPath ? null : option(call, "apiSuffix"),
+        methods: builtMethod || writeMethod || (writeMethod === null ? null : ["POST"])
+      });
+    } else if (ts.isPropertyAccessExpression(callee) && callee.name.text === "request" && isHttpClient(callee.expression)) {
+      const method = option(call, "method", 1);
+      sites.push({ call, file, kind: "request", path: call.arguments[0], methods: method ? literalMethods(evaluator, method) : ["GET"] });
+    } else if (ts.isIdentifier(callee) && callee.text === "fetch" && codeSide(file) !== "server") {
+      const symbol = symbols.symbolAt(callee);
+      if (symbol && symbols.isLibrarySymbol(symbol)) {
+        const method = option(call, "method", 1);
+        sites.push({ call, file, kind: "fetch", path: call.arguments[0], methods: method ? literalMethods(evaluator, method) : ["GET"] });
+      }
+    }
+  }
+  return sites;
+}
+
+function sitePatterns(site, evaluator) {
+  if (site.path) {
+    return evaluator.evaluate(site.path);
+  }
+  if (site.apiSuffix) {
+    return evaluator.evaluate(site.apiSuffix).map((suffix) =>
+      resolveScopedApiBasePath({ relativePath: suffix.startsWith("/") || suffix.startsWith(ANY) ? suffix : `/${suffix}`, strictParams: false }));
+  }
+  return [];
+}
+
+// Client path pattern -> path segments, after the declared prefix aliases.
+function clientSegments(pattern, prefixAliases) {
+  let value = pattern.replace(/^https?:\/\/[^/]+/u, "").split("?")[0].split("#")[0];
+  for (const { client, route } of prefixAliases) {
+    if (value === client || value.startsWith(`${client}/`)) {
+      value = `${route}${value.slice(client.length)}`;
+      break;
+    }
+  }
+  return value.split("/").filter(Boolean);
+}
+
+// Aligns client segments with a route template. ANY spans one or more route
+// segments; SEGMENT and alias parameters (`:slug`) fill one. The score counts
+// route literals matched by client literals and by wildcards.
+function matchSegments(client, route, clientIndex = 0, routeIndex = 0, score = { literal: 0, wildcard: 0 }) {
+  if (clientIndex === client.length) {
+    return routeIndex === route.length ? score : null;
+  }
+  const segment = client[clientIndex];
+  if (segment.includes(ANY)) {
+    let best = null;
+    for (let take = 1; routeIndex + take <= route.length; take += 1) {
+      const covered = route.slice(routeIndex, routeIndex + take).filter((part) => !part.startsWith(":")).length;
+      const result = matchSegments(client, route, clientIndex + 1, routeIndex + take, { literal: score.literal, wildcard: score.wildcard + covered });
+      if (result && (!best || result.literal > best.literal || (result.literal === best.literal && result.wildcard < best.wildcard))) {
+        best = result;
+      }
+    }
+    return best;
+  }
+  if (routeIndex >= route.length) {
+    return null;
+  }
+  const target = route[routeIndex];
+  if (target.startsWith(":")) {
+    return matchSegments(client, route, clientIndex + 1, routeIndex + 1, score);
+  }
+  if (segment.includes(SEGMENT) || segment.startsWith(":")) {
+    const [prefix, suffix = ""] = segment.startsWith(":") ? ["", ""] : segment.split(SEGMENT);
+    if (!target.startsWith(prefix) || !target.endsWith(suffix)) {
+      return null;
+    }
+    return matchSegments(client, route, clientIndex + 1, routeIndex + 1, { literal: score.literal, wildcard: score.wildcard + 1 });
+  }
+  return segment === target
+    ? matchSegments(client, route, clientIndex + 1, routeIndex + 1, { literal: score.literal + 1, wildcard: score.wildcard })
+    : null;
+}
+
+function routeLiterals(route) {
+  return route.segments.filter((part) => !part.startsWith(":")).length;
+}
+
+// Matches one site against the statically discovered HTTP entry operations.
+// Returns, per method, the matched routes and whether each key was evaluated
+// exactly: one best route (or one per evaluated alternative) whose every
+// literal segment aligns with a client literal.
+function matchSite({ patterns, methods }, routes, prefixAliases) {
+  const literal = patterns.map((pattern) => clientSegments(pattern, prefixAliases))
+    .filter((segments) => segments.some((segment) => isLiteralPattern(segment) && !segment.startsWith(":") && segment !== "api"));
+  const methodsToMatch = methods || [...new Set(routes.map((route) => route.key.method))];
+  return methodsToMatch.map((method) => {
+    if (!literal.length) {
+      return { method, matches: [] };
+    }
+    const candidates = new Map();
+    for (const segments of literal) {
+      for (const route of routes) {
+        if (route.key.method !== method) {
+          continue;
+        }
+        const score = matchSegments(segments, route.segments);
+        const previous = candidates.get(route);
+        if (score && (!previous || previous.literal < score.literal)) {
+          candidates.set(route, score);
+        }
+      }
+    }
+    const ranked = [...candidates.entries()].sort((left, right) => right[1].literal - left[1].literal || left[1].wildcard - right[1].wildcard);
+    if (!ranked.length) {
+      return { method, matches: [] };
+    }
+    const top = ranked.filter(([, score]) => score.literal === ranked[0][1].literal);
+    const exact = top.length <= literal.length && top.every(([route, score]) => score.wildcard === 0 && score.literal === routeLiterals(route));
+    if (exact) {
+      return { method, matches: top.map(([route]) => ({ route, keyCertainty: "exact" })) };
+    }
+    if (top.length <= MAX_PROBABLE_ROUTES) {
+      return { method, matches: top.map(([route]) => ({ route, keyCertainty: "probable" })) };
+    }
+    return { method, matches: [] };
+  }).filter((entry) => methods || entry.matches.length);
+}
+
+function routeTable(entryOperations) {
+  return entryOperations
+    .filter((entry) => entry.resolution === "resolved" && entry.key?.protocol === "http" && typeof entry.key.operation === "string")
+    .map((entry) => ({ key: entry.key, segments: entry.key.operation.split("/").filter(Boolean) }));
+}
+
+export { collectTransportSites, matchSite, routeTable, sitePatterns };

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 {};

package/src/cli.js

@@ -1,33 +1,112 @@
 #!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
-import { inspectVueArchitecture } from "./inspectVueArchitecture.js";
 
-try {
+const MAX_INPUT_BYTES = 4 * 1024 * 1024;
+const SCRIPT_FILE_PATTERN = /\.(?:[cm]?js|jsx|tsx?|vue)$/u;
+// The inspection's old generation is bounded by the size of the declared
+// scripts. It holds about 45 MiB per MiB of script; the bound leaves roughly a
+// third more, so garbage is collected before memory grows far past what the
+// inspection really holds.
+const HEAP_BASE_MB = 192;
+const HEAP_MB_PER_SCRIPT_MB = 56;
+
+function pairs(entries, usage) {
+  return entries.map((entry) => {
+    const separator = entry.indexOf("=");
+    if (separator < 1 || separator === entry.length - 1) {
+      throw new Error(usage);
+    }
+    return [entry.slice(0, separator), entry.slice(separator + 1)];
+  });
+}
+
+function readOptions() {
   const { values } = parseArgs({ options: {
     "http-scope": { type: "string", default: "" },
     "api-base-path": { type: "string", default: "" },
-    alias: { type: "string", multiple: true, default: [] }
+    alias: { type: "string", multiple: true, default: [] },
+    "api-prefix-alias": { type: "string", multiple: true, default: [] },
+    calls: { type: "boolean", default: false }
   } });
+  const aliases = {};
+  for (const [name, directory] of pairs(values.alias, "Use --alias name=project-directory.")) {
+    if (Object.hasOwn(aliases, name)) throw new Error("Duplicate architecture alias.");
+    aliases[name] = directory;
+  }
+  const apiPrefixAliases = pairs(values["api-prefix-alias"], "Use --api-prefix-alias client-prefix=route-prefix.")
+    .map(([client, route]) => ({ client, route }));
+  if (new Set(apiPrefixAliases.map(({ client }) => client)).size !== apiPrefixAliases.length) {
+    throw new Error("Duplicate API prefix alias.");
+  }
+  return {
+    projectRoot: process.cwd(),
+    aliases,
+    httpScope: values["http-scope"],
+    apiBasePath: values["api-base-path"],
+    calls: values.calls,
+    apiPrefixAliases
+  };
+}
+
+async function readInput() {
   const chunks = [];
   let length = 0;
   for await (const chunk of process.stdin) {
     length += chunk.length;
-    if (length > 4 * 1024 * 1024) throw new Error("Architecture inspection input exceeds 4 MiB.");
+    if (length > MAX_INPUT_BYTES) throw new Error("Architecture inspection input exceeds 4 MiB.");
     chunks.push(chunk);
   }
-  const aliases = {};
-  for (const entry of values.alias) {
-    const separator = entry.indexOf("=");
-    if (separator < 1 || separator === entry.length - 1) throw new Error("Use --alias name=project-directory.");
-    const name = entry.slice(0, separator);
-    if (Object.hasOwn(aliases, name)) throw new Error("Duplicate architecture alias.");
-    aliases[name] = entry.slice(separator + 1);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+// File sizes only: the inspection itself validates every declared path.
+async function heapLimitMb(projectRoot, input) {
+  let bytes = 0;
+  for (const file of Array.isArray(input?.files) ? input.files : []) {
+    const absolute = typeof file?.path === "string" && SCRIPT_FILE_PATTERN.test(file.path) &&
+      path.resolve(projectRoot, file.path);
+    if (absolute && absolute.startsWith(`${projectRoot}${path.sep}`)) {
+      bytes += (await lstat(absolute).catch(() => null))?.size || 0;
+    }
   }
-  const result = await inspectVueArchitecture({
-    projectRoot: process.cwd(), input: JSON.parse(Buffer.concat(chunks).toString("utf8")),
-    aliases, httpScope: values["http-scope"], apiBasePath: values["api-base-path"]
+  return Math.ceil(HEAP_BASE_MB + HEAP_MB_PER_SCRIPT_MB * bytes / (1024 * 1024));
+}
+
+// The bounded inspection runs in a child Node process started with the old
+// generation bound; a bound given by the caller is kept as it is.
+async function launch(inputText) {
+  const limit = await heapLimitMb(process.cwd(), JSON.parse(inputText));
+  const child = spawn(process.execPath, [`--max-old-space-size=${limit}`, fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
+    stdio: ["pipe", "inherit", "pipe"]
   });
+  const errors = [];
+  child.stderr.on("data", (chunk) => errors.push(chunk));
+  child.stdin.end(inputText);
+  const [code, signal] = await once(child, "close");
+  const message = Buffer.concat(errors).toString("utf8");
+  if (code !== 0) {
+    throw new Error(signal || /heap out of memory/u.test(message)
+      ? `Architecture inspection needs more than its ${limit} MB memory bound.`
+      : message.trim() || "Architecture inspection failed.");
+  }
+}
+
+async function inspect(inputText) {
+  // Loaded here, so the launching process stays small.
+  const { inspectVueArchitecture } = await import("./inspectVueArchitecture.js");
+  const result = await inspectVueArchitecture({ ...readOptions(), input: JSON.parse(inputText) });
   process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+try {
+  readOptions();
+  const inputText = await readInput();
+  await (process.execArgv.some((argument) => argument.startsWith("--max-old-space-size")) ? inspect(inputText) : launch(inputText));
 } catch (error) {
   process.stderr.write(`${error.message}\n`);
   process.exitCode = 1;