@jskit-ai/architecture-inspector 0.1.0 → 0.1.1

package/src/calls/features.js

@@ -0,0 +1,273 @@
+import ts from "typescript";
+import { isFunctionLike, unwrapExpression } from "./functions.js";
+
+const FEATURE_PACKAGE = "@jskit-ai/kernel";
+const MAX_ACTION_DEPTH = 6;
+
+function memberNamed(objectLiteral, name) {
+  return objectLiteral.properties.find((property) =>
+    property.name && !ts.isComputedPropertyName(property.name) && property.name.text === name);
+}
+
+function isActionObject(node) {
+  return Boolean(node) && ts.isObjectLiteralExpression(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.
+function bindFeatures({ calls, symbols, evaluator }) {
+  const features = [];
+  for (const call of calls) {
+    const callee = unwrapExpression(call.expression);
+    if (!ts.isIdentifier(callee) || !symbols.isImportOf(callee, FEATURE_PACKAGE, ["defineFeature"])) {
+      continue;
+    }
+    const definition = unwrapExpression(call.arguments[0]);
+    if (definition && ts.isObjectLiteralExpression(definition)) {
+      features.push(readFeature(definition));
+    }
+  }
+
+  function memberFunctions(member) {
+    if (!member) {
+      return [];
+    }
+    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 [];
+  }
+
+  function tokens(member) {
+    const result = new Map();
+    const value = member && ts.isPropertyAssignment(member) ? unwrapExpression(member.initializer) : null;
+    if (!value || !ts.isObjectLiteralExpression(value)) {
+      return result;
+    }
+    for (const property of value.properties) {
+      const initializer = ts.isPropertyAssignment(property) ? property.initializer
+        : ts.isShorthandPropertyAssignment(property) ? property.name : null;
+      const token = initializer && evaluator.evaluateLiteral(initializer);
+      if (token && property.name && !ts.isComputedPropertyName(property.name)) {
+        result.set(property.name.text, token);
+      }
+    }
+    return result;
+  }
+
+  function returnedObject(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 value && ts.isObjectLiteralExpression(value) ? value : null;
+  }
+
+  function setupOutputs(setups) {
+    const outputs = new Map();
+    for (const setup of setups) {
+      for (const expression of evaluator.functionReturns(setup)) {
+        const object = returnedObject(expression);
+        for (const property of object?.properties || []) {
+          if (ts.isShorthandPropertyAssignment(property)) {
+            outputs.set(property.name.text, [...(outputs.get(property.name.text) || []), property.name]);
+          } else if (ts.isPropertyAssignment(property) && !ts.isComputedPropertyName(property.name)) {
+            outputs.set(property.name.text, [...(outputs.get(property.name.text) || []), property.initializer]);
+          }
+        }
+      }
+    }
+    return outputs;
+  }
+
+  function readFeature(definition) {
+    const setups = memberFunctions(memberNamed(definition, "setup"));
+    const actionsMember = memberNamed(definition, "actions");
+    return {
+      definition,
+      requires: new Map([...tokens(memberNamed(definition, "optional")), ...tokens(memberNamed(definition, "requires"))]),
+      provides: tokens(memberNamed(definition, "provides")),
+      setups,
+      actionFunctions: memberFunctions(actionsMember),
+      actionsMember,
+      outputs: setupOutputs(setups)
+    };
+  }
+
+  const providers = new Map();
+  for (const feature of features) {
+    for (const [name, token] of feature.provides) {
+      for (const expression of feature.outputs.get(name) || []) {
+        providers.set(token, [...(providers.get(token) || []), expression]);
+      }
+    }
+  }
+
+  const bindings = new Map();
+  function bindPattern(fn, valuesFor) {
+    const parameter = fn.parameters[0];
+    if (!parameter || !ts.isObjectBindingPattern(parameter.name)) {
+      return;
+    }
+    for (const element of parameter.name.elements) {
+      const key = element.propertyName || element.name;
+      if (!ts.isIdentifier(key) || !ts.isIdentifier(element.name)) {
+        continue;
+      }
+      const expressions = valuesFor(key.text);
+      if (expressions.length) {
+        bindings.set(element, { expressions, exact: expressions.length === 1 });
+      }
+    }
+  }
+  for (const feature of features) {
+    const provided = (name) => providers.get(feature.requires.get(name)) || [];
+    for (const setup of feature.setups) {
+      bindPattern(setup, provided);
+    }
+    for (const actions of feature.actionFunctions) {
+      bindPattern(actions, (name) => feature.outputs.get(name) || provided(name));
+    }
+  }
+
+  return { features, bindings, actions: collectFeatureActions(features, { symbols, evaluator }) };
+}
+
+// Action definitions inside each feature's actions() result: object literals
+// with `id` and `execute`, possibly wrapped by a pass-through call, through
+// arrays, spreads, project factory functions and literal-array `.map`.
+function collectFeatureActions(features, { symbols, evaluator }) {
+  const found = [];
+  const seenFunctions = new Set();
+
+  function collect(node, indexes, depth) {
+    const value = unwrapExpression(node);
+    if (!value || depth > MAX_ACTION_DEPTH) {
+      return;
+    }
+    if (ts.isObjectLiteralExpression(value)) {
+      if (isActionObject(value)) {
+        found.push({ object: value, indexes });
+        return;
+      }
+      for (const property of value.properties) {
+        if (ts.isSpreadAssignment(property)) {
+          collect(property.expression, indexes, depth + 1);
+        }
+      }
+      return;
+    }
+    if (ts.isArrayLiteralExpression(value)) {
+      for (const element of value.elements) {
+        collect(ts.isSpreadElement(element) ? element.expression : element, indexes, depth + 1);
+      }
+      return;
+    }
+    if (ts.isConditionalExpression(value)) {
+      collect(value.whenTrue, indexes, depth + 1);
+      collect(value.whenFalse, indexes, depth + 1);
+      return;
+    }
+    if (isFunctionLike(value)) {
+      for (const expression of evaluator.functionReturns(value)) {
+        collect(expression, indexes, depth + 1);
+      }
+      return;
+    }
+    if (ts.isIdentifier(value)) {
+      const declaration = symbols.declarationOf(value);
+      if (declaration && ts.isVariableDeclaration(declaration) && declaration.initializer) {
+        collect(declaration.initializer, indexes, depth + 1);
+      }
+      return;
+    }
+    if (ts.isCallExpression(value)) {
+      collectCall(value, indexes, depth);
+    }
+  }
+
+  function collectCall(call, indexes, depth) {
+    const passedThrough = call.arguments.map(unwrapExpression).filter(isActionObject);
+    if (passedThrough.length) {
+      for (const object of passedThrough) {
+        found.push({ object, indexes });
+      }
+      return;
+    }
+    const callee = unwrapExpression(call.expression);
+    const callback = unwrapExpression(call.arguments[0]);
+    if (ts.isPropertyAccessExpression(callee) && callee.name.text === "map" && isFunctionLike(callback)) {
+      const elements = evaluator.literalArray(callee.expression);
+      const returns = evaluator.functionReturns(callback);
+      if (!elements) {
+        returns.forEach((expression) => collect(expression, indexes, depth + 1));
+        return;
+      }
+      elements.forEach((_, index) => {
+        const elementIndexes = new Map(indexes).set(callback, index);
+        returns.forEach((expression) => collect(expression, elementIndexes, depth + 1));
+      });
+      return;
+    }
+    const implementations = symbols.expressionImplementations(callee, 0).filter(isFunctionLike);
+    if (implementations.length) {
+      for (const fn of implementations) {
+        if (!seenFunctions.has(fn)) {
+          seenFunctions.add(fn);
+          collect(fn, indexes, depth + 1);
+          seenFunctions.delete(fn);
+        }
+      }
+      return;
+    }
+    if (ts.isPropertyAccessExpression(callee)) {
+      collect(callee.expression, indexes, depth + 1);
+    }
+    for (const argument of call.arguments) {
+      collect(argument, indexes, depth + 1);
+    }
+  }
+
+  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) {
+      feature.actionFunctions.forEach((fn) => collect(fn, new Map(), 0));
+    } else if (feature.actionsMember && ts.isPropertyAssignment(feature.actionsMember)) {
+      collect(feature.actionsMember.initializer, new Map(), 0);
+    }
+    for (const { object, indexes } of found) {
+      const idMember = memberNamed(object, "id");
+      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")) });
+    }
+  }
+  return actions;
+}
+
+export { bindFeatures };

package/src/calls/functions.js

@@ -0,0 +1,204 @@
+import ts from "typescript";
+
+const SKIPPED_MODIFIERS = new Set([ts.SyntaxKind.ExportKeyword, ts.SyntaxKind.DefaultKeyword, ts.SyntaxKind.DeclareKeyword]);
+
+function isFunctionLike(node) {
+  return Boolean(node) && (
+    ts.isFunctionDeclaration(node) ||
+    ts.isFunctionExpression(node) ||
+    ts.isArrowFunction(node) ||
+    ts.isMethodDeclaration(node) ||
+    ts.isConstructorDeclaration(node) ||
+    ts.isGetAccessorDeclaration(node) ||
+    ts.isSetAccessorDeclaration(node)
+  ) && Boolean(node.body);
+}
+
+function unwrapExpression(node) {
+  let current = node;
+  while (current && (
+    ts.isParenthesizedExpression(current) ||
+    ts.isAsExpression(current) ||
+    ts.isNonNullExpression(current) ||
+    ts.isSatisfiesExpression(current) ||
+    ts.isTypeAssertionExpression(current)
+  )) {
+    current = current.expression;
+  }
+  return current;
+}
+
+// The canonical start (spec Decision 6): the first token of the tree-sitter
+// function node, excluding decorators and the export/default wrapper that
+// tree-sitter places outside the function node. Leading comments are trivia.
+function canonicalStart(node) {
+  const sourceFile = node.getSourceFile();
+  const modifiers = node.modifiers || [];
+  let skippedEnd = -1;
+  for (const modifier of modifiers) {
+    if (ts.isDecorator(modifier) || SKIPPED_MODIFIERS.has(modifier.kind)) {
+      skippedEnd = modifier.end;
+      continue;
+    }
+    return modifier.getStart(sourceFile);
+  }
+  return skippedEnd < 0 ? node.getStart(sourceFile) : ts.skipTrivia(sourceFile.text, skippedEnd);
+}
+
+function point(sourceFile, position) {
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(position);
+  return { line: line + 1, column: character + 1 };
+}
+
+function functionKind(node) {
+  if (ts.isConstructorDeclaration(node)) {
+    return "constructor";
+  }
+  if (ts.isMethodDeclaration(node) || ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node)) {
+    return "method";
+  }
+  if (ts.isArrowFunction(node)) {
+    return "arrow";
+  }
+  return ts.isFunctionExpression(node) ? "closure" : "function";
+}
+
+function propertyNameText(name, sourceFile) {
+  if (!name) {
+    return "";
+  }
+  if (ts.isIdentifier(name) || ts.isPrivateIdentifier(name) || ts.isStringLiteralLike(name) || ts.isNumericLiteral(name)) {
+    return name.text;
+  }
+  return name.getText(sourceFile);
+}
+
+// The name a function is declared or bound under; "" when anonymous.
+function functionName(node) {
+  const sourceFile = node.getSourceFile();
+  if (ts.isConstructorDeclaration(node)) {
+    return "constructor";
+  }
+  if (node.name) {
+    return propertyNameText(node.name, sourceFile);
+  }
+  let parent = node.parent;
+  while (parent && (ts.isParenthesizedExpression(parent) || ts.isAsExpression(parent) || ts.isSatisfiesExpression(parent))) {
+    parent = parent.parent;
+  }
+  if (!parent) {
+    return "";
+  }
+  if ((ts.isVariableDeclaration(parent) || ts.isPropertyDeclaration(parent) || ts.isPropertyAssignment(parent)) && parent.name) {
+    return ts.isObjectBindingPattern(parent.name) || ts.isArrayBindingPattern(parent.name) ? "" : propertyNameText(parent.name, sourceFile);
+  }
+  if (ts.isBinaryExpression(parent) && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken && unwrapExpression(parent.right) === node) {
+    const target = parent.left;
+    if (ts.isIdentifier(target)) {
+      return target.text;
+    }
+    if (ts.isPropertyAccessExpression(target)) {
+      return target.name.text;
+    }
+  }
+  if (ts.isExportAssignment(parent)) {
+    return "default";
+  }
+  return "";
+}
+
+// The enclosing class, or the variable an enclosing object literal is bound to.
+function functionContainer(node) {
+  const parent = ts.isPropertyAssignment(node.parent) || ts.isPropertyDeclaration(node.parent) ? node.parent.parent : node.parent;
+  if (parent && (ts.isClassDeclaration(parent) || ts.isClassExpression(parent))) {
+    return parent.name?.text || (ts.isVariableDeclaration(parent.parent) && ts.isIdentifier(parent.parent.name) ? parent.parent.name.text : undefined);
+  }
+  if (parent && ts.isObjectLiteralExpression(parent)) {
+    let holder = parent.parent;
+    while (holder && (ts.isParenthesizedExpression(holder) || ts.isAsExpression(holder) || ts.isCallExpression(holder))) {
+      holder = holder.parent;
+    }
+    if (holder && ts.isVariableDeclaration(holder) && ts.isIdentifier(holder.name)) {
+      return holder.name.text;
+    }
+  }
+  return undefined;
+}
+
+function isTopLevelDeclaration(node) {
+  if (ts.isFunctionDeclaration(node)) {
+    return ts.isSourceFile(node.parent);
+  }
+  const declaration = node.parent;
+  return Boolean(declaration) && ts.isVariableDeclaration(declaration) &&
+    declaration.initializer === node &&
+    ts.isVariableStatement(declaration.parent?.parent) &&
+    ts.isSourceFile(declaration.parent.parent.parent);
+}
+
+// Every function-like with a body in one script, plus the file's top-level
+// `module` function (`fn:<path>#module`, 1:1 to the end of the file).
+// Positions are 1-based and cover the original file.
+function collectFileFunctions({ file, hash, sourceFile, checker }) {
+  const records = [];
+  const nodes = [];
+  const end = point(sourceFile, Math.max(1, sourceFile.text.length - (sourceFile.text.endsWith("\n") ? 1 : 0)));
+  const moduleRecord = {
+    id: `fn:${file}#module`,
+    resolution: "resolved",
+    file,
+    name: "",
+    kind: "module",
+    start: { line: 1, column: 1 },
+    end,
+    evidence: [{ path: file, hash, start: { line: 1, column: 1 }, end }]
+  };
+  const exported = new Set();
+  const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+  for (const symbol of moduleSymbol ? checker.getExportsOfModule(moduleSymbol) : []) {
+    const target = symbol.flags & ts.SymbolFlags.Alias ? safeAliased(checker, symbol) : symbol;
+    for (const declaration of target?.declarations || []) {
+      exported.add(declaration);
+      if (ts.isVariableDeclaration(declaration) && declaration.initializer) {
+        exported.add(unwrapExpression(declaration.initializer));
+      }
+    }
+  }
+  const visit = (node) => {
+    if (isFunctionLike(node)) {
+      const startPosition = canonicalStart(node);
+      const start = point(sourceFile, startPosition);
+      const finish = point(sourceFile, node.end);
+      const container = functionContainer(node);
+      const record = {
+        id: `fn:${file}#${start.line}:${start.column}`,
+        resolution: "resolved",
+        file,
+        name: functionName(node),
+        kind: functionKind(node),
+        ...(container ? { container } : {}),
+        ...(isTopLevelDeclaration(node) && exported.has(node) ? { exported: true } : {}),
+        start,
+        end: finish,
+        evidence: [{ path: file, hash, start, end: finish }]
+      };
+      records.push(record);
+      nodes.push({ node, record, startPosition });
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  // An empty file has no code, so no module function either.
+  const module = sourceFile.text.length ? moduleRecord : null;
+  return { module, functions: module ? [module, ...records] : records, nodes };
+}
+
+function safeAliased(checker, symbol) {
+  try {
+    return checker.getAliasedSymbol(symbol);
+  } catch {
+    return symbol;
+  }
+}
+
+export { collectFileFunctions, isFunctionLike, point, safeAliased, unwrapExpression };