@assembly-js/app-foundation 0.3.4 → 0.3.6

package/CHANGELOG.md

@@ -19,6 +19,12 @@ A patch release never changes what an app's build requires; a minor release may
 not by hand; see `changes/README.md`. CI fails a PR that changes a check script without a
 `bump: minor` change file.
 
+## 0.3.6
+- [behavior] `.assembly/app-deps.json` now also records the calls an app makes through another app's generated client (`installerClient.GET('/projects/{id}')`), with `client` in that app's `via`. A client use the scan cannot follow counts as every operation that app exposes. Nothing in the app changes.
+
+## 0.3.5
+- [behavior] At the end of every turn the platform records which other apps' operations the app calls by literal API path in `.assembly/app-deps.json`. Publishing an app that other apps depend on is refused while that file is out of date. Nothing in the app changes.
+
 ## 0.3.4
 - [guidance] The build agent is now taught to authenticate inbound webhook calls inside the route, fail closed when the secret is unset, and never add an unauthenticated test endpoint.
 

package/bin/scan-app-deps.mjs

@@ -0,0 +1,290 @@
+// Finds which other apps' operations an app calls, by literal proxy path or
+// through the generated client, and describes them as `.assembly/app-deps.json`, so publish reads one file
+// instead of Go parsing TypeScript.
+//
+// A second projection beside scan-client-calls: it reuses that detector's
+// parse setup and `fetch` method reading, but looks for literals rather than
+// SDK receivers. A path is reported when the file alone fixes it: a literal, or a
+// template or `+` built from literals and same-file string consts (the usual way an
+// app names the provider's id). Anything else is computed and left to observed traffic.
+//
+// `files` hashes every .ts/.tsx, not only the ones with a hit, so Go can tell
+// a new file the scan never saw from one it saw and found irrelevant.
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { contractTemplate } from './check-contract-routes.mjs';
+import { literalFetchMethod, scriptKind } from './scan-client-calls.mjs';
+import { PROXY_METHODS, byteCompare, hashFiles, listFiles, loadTypeScript } from './scan-routes.mjs';
+
+export const APP_DEPS_OUTPUT = '.assembly/app-deps.json';
+export const CODE_SCAN_FAILED = 'app_deps_scan_failed';
+
+// Mirrored in Go (appdepsfile): the one place a scanned source file is recognised.
+const SOURCE_FILE = /\.tsx?$/;
+const PREFILTER = ['/v1/apps/', 'generated/apps/'];
+const PROXY_PATH = /^\/v1\/apps\/([^/?#]+)\/api(?:\/([^?#]*))?(?:[?#].*)?$/;
+const VIA_PROXY_PATH = 'proxy-path';
+const VIA_CLIENT = 'client';
+// Lets a reader tell a file from a scanner that sees client calls from an older one that
+// would omit them, since both look the same when an app has none.
+const DETECTS = [VIA_PROXY_PATH, VIA_CLIENT];
+const CLIENT_SPECIFIER = /(?:^|\/)generated\/apps\/([^/]+)\/client(?:\.[jt]s)?$/;
+// The generated client's exports that make calls; its other exports (APP_ID, types) do not.
+const CLIENT_EXPORTS = new Set(['installerClient', 'viewerClient']);
+const CLIENT_DOCUMENT = (appId) => path.join('generated/apps', appId, 'openapi.json');
+const OPENAPI_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
+const PATHS_POINTER = '#/paths/';
+// One file per installed provider app, written by the platform; each operation carries
+// `- Method: \`X\`` then `- Path: \`/t\``. Absent for a provider that is not callable.
+const PROVIDER_DOCS_DIR = '.assembly/docs/apps';
+const DOC_OPERATION = /^- Method: `([A-Z]+)`\n- Path: `([^`]+)`$/m;
+const DOC_CATCH_ALL = 'This operation is a catch-all.';
+// An inferred route (handlers the scan could not name) has no method to record.
+const INFERRED_METHOD = 'ANY';
+const TEMPLATE_PARAM = /^\{[^}]+\}$/;
+const CLIENT_VERBS = new Set(['get', 'post', 'put', 'patch', 'delete']);
+
+const isLiteral = (ts, n) => ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n);
+
+// The method a literal's call site states, or null when it is not evident.
+function callSiteMethod(ts, literal) {
+  const call = literal.parent;
+  if (!ts.isCallExpression(call) || call.arguments[0] !== literal) return null;
+  const callee = call.expression;
+  const name = ts.isIdentifier(callee) ? callee.text : ts.isPropertyAccessExpression(callee) ? callee.name.text : null;
+  if (name === 'fetch') return literalFetchMethod(ts, call.arguments[1])?.toUpperCase() ?? null;
+  return CLIENT_VERBS.has(name) && ts.isPropertyAccessExpression(callee) ? name.toUpperCase() : null;
+}
+
+// A name the file binds exactly once, as a `const` initialised with a literal, is the string
+// it spells; any other binding of the same name (a `let`, a parameter) may shadow it.
+function constStrings(ts, sf) {
+  const bindings = new Map(); // name -> declaration, or null once bound a second time
+  const bind = (name, decl) => bindings.set(name, bindings.has(name) ? null : decl);
+  const walk = (node) => {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) bind(node.name.text, node);
+    else if (ts.isParameter(node) && ts.isIdentifier(node.name)) bind(node.name.text, null);
+    ts.forEachChild(node, walk);
+  };
+  walk(sf);
+  const values = new Map();
+  const resolve = (node) => resolveString(ts, node, values);
+  // Source order, so a const built from an earlier one resolves too.
+  for (const [name, decl] of bindings) {
+    if (!decl || !(decl.parent.flags & ts.NodeFlags.Const) || !decl.initializer) continue;
+    const value = resolve(decl.initializer);
+    if (value !== null) values.set(name, value);
+  }
+  return values;
+}
+
+// The string an expression always evaluates to, or null when any part of it is not known.
+function resolveString(ts, node, consts) {
+  if (isLiteral(ts, node)) return node.text;
+  if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node)) return resolveString(ts, node.expression, consts);
+  if (ts.isIdentifier(node)) return consts.get(node.text) ?? null;
+  if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+    const [left, right] = [resolveString(ts, node.left, consts), resolveString(ts, node.right, consts)];
+    return left !== null && right !== null ? left + right : null;
+  }
+  if (ts.isTemplateExpression(node)) {
+    let out = node.head.text;
+    for (const span of node.templateSpans) {
+      const value = resolveString(ts, span.expression, consts);
+      if (value === null) return null;
+      out += value + span.literal.text;
+    }
+    return out;
+  }
+  return null;
+}
+
+// The generated-client bindings one file imports: name -> { appId, namespace }.
+function clientBindings(ts, sf, found) {
+  const bindings = new Map();
+  for (const stmt of sf.statements) {
+    const specifier = stmt.moduleSpecifier;
+    const match = specifier && ts.isStringLiteral(specifier) ? CLIENT_SPECIFIER.exec(specifier.text) : null;
+    if (!match) continue;
+    const appId = match[1];
+    // A re-export hands the client to code this file cannot follow.
+    if (ts.isExportDeclaration(stmt) && !stmt.isTypeOnly) found.push({ appId, client: 'all' });
+    const clause = ts.isImportDeclaration(stmt) ? stmt.importClause : undefined;
+    if (!clause || clause.isTypeOnly) continue;
+    const named = clause.namedBindings;
+    if (named && ts.isNamespaceImport(named)) bindings.set(named.name.text, { appId, namespace: true });
+    for (const spec of named && ts.isNamedImports(named) ? named.elements : []) {
+      if (!spec.isTypeOnly && CLIENT_EXPORTS.has((spec.propertyName ?? spec.name).text)) bindings.set(spec.name.text, { appId, namespace: false });
+    }
+  }
+  return bindings;
+}
+
+// `<client>.<VERB>('<template>')` is one op; any other use of a client could be any op.
+function clientUse(ts, node, binding) {
+  let client = node;
+  if (binding.namespace) {
+    const access = node.parent;
+    if (!ts.isPropertyAccessExpression(access) || access.expression !== node) return { appId: binding.appId, client: 'all' };
+    if (!CLIENT_EXPORTS.has(access.name.text)) return null;
+    client = access;
+  }
+  const verb = client.parent;
+  const call = verb?.parent;
+  const arg = call && ts.isCallExpression(call) && call.expression === verb ? call.arguments[0] : undefined;
+  if (ts.isPropertyAccessExpression(verb) && verb.expression === client && /^[A-Z]+$/.test(verb.name.text) && arg && isLiteral(ts, arg)) {
+    return { appId: binding.appId, client: `${verb.name.text} ${arg.text}` };
+  }
+  return { appId: binding.appId, client: 'all' };
+}
+
+const isReference = (ts, node) =>
+  !(ts.isPropertyAccessExpression(node.parent) && node.parent.name === node) &&
+  !ts.isImportSpecifier(node.parent) && !ts.isNamespaceImport(node.parent) &&
+  !(ts.isPropertyAssignment(node.parent) && node.parent.name === node);
+
+function collectDeps(ts, file, text) {
+  const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, scriptKind(ts, file));
+  const consts = constStrings(ts, sf);
+  const found = [];
+  const bindings = clientBindings(ts, sf, found);
+  const used = new Set();
+  const visit = (node) => {
+    // A bare name is read where its const is declared, not at every use.
+    const value = ts.isIdentifier(node) ? null : resolveString(ts, node, consts);
+    if (value !== null) {
+      const match = PROXY_PATH.exec(value);
+      // `'/v1/apps/x/api/items/' + id` is only the start of a path.
+      const concatenated = ts.isBinaryExpression(node.parent) && node.parent.left === node;
+      // `const BASE = `/v1/apps/${id}/api`` names the provider, it does not call its root.
+      const base = ts.isVariableDeclaration(node.parent) && !match?.[2];
+      // The proxy drops one trailing slash before routing.
+      const template = `/${match?.[2] ?? ''}`.replace(/(.)\/$/, '$1');
+      if (match && !concatenated && !base) found.push({ appId: match[1], template, method: callSiteMethod(ts, node) });
+      // A resolved expression is one path: its parts are not separate calls.
+      return;
+    } else if (ts.isIdentifier(node) && bindings.has(node.text) && isReference(ts, node)) {
+      const dep = clientUse(ts, node, bindings.get(node.text));
+      if (dep) found.push(dep);
+      used.add(node.text);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  for (const [name, { appId }] of bindings) if (!used.has(name)) found.push({ appId, client: 'all' });
+  return found;
+}
+
+// Every op the provider exposes, from the document the client was generated from, or the
+// provider's docs when that is not on disk. Named the way the client names them: without
+// the `/api` prefix, and with a path item that refers to another path serving its operations.
+function allProviderOps(root, appId, provider) {
+  try {
+    const doc = JSON.parse(readFileSync(path.join(root, CLIENT_DOCUMENT(appId)), 'utf8'));
+    const paths = doc.paths ?? {};
+    const resolve = (item) => {
+      const ref = item && typeof item.$ref === 'string' && item.$ref.startsWith(PATHS_POINTER) ? item.$ref : null;
+      return ref ? paths[ref.slice(PATHS_POINTER.length).replace(/~1/g, '/').replace(/~0/g, '~')] : item;
+    };
+    return Object.entries(paths).flatMap(([documented, entry]) => {
+      const item = resolve(entry);
+      const template = contractTemplate(documented) || '/';
+      return OPENAPI_METHODS.filter((m) => item && typeof item === 'object' && m in item).map((m) => `${m.toUpperCase()} ${template}`);
+    });
+  } catch {
+    return (provider ?? []).map((op) => `${op.method} ${op.template}`);
+  }
+}
+
+function providerOps(root, appId) {
+  try {
+    const doc = readFileSync(path.join(root, PROVIDER_DOCS_DIR, `${appId}.md`), 'utf8');
+    return doc.split(/\n(?=#{3,4} )/).flatMap((section) => {
+      const m = DOC_OPERATION.exec(section);
+      return m ? [{ method: m[1], template: m[2], catchAll: section.includes(DOC_CATCH_ALL) }] : [];
+    });
+  } catch {
+    return null;
+  }
+}
+
+// A `{param}` segment in the provider's template stands for any one segment of the call; the
+// last one of a catch-all stands for one or more.
+const templateMatches = ({ template, catchAll }, literal) => {
+  const a = template.split('/');
+  const b = literal.split('/');
+  if (!(catchAll ? b.length >= a.length : b.length === a.length)) return false;
+  return a.every((seg, i) => seg === b[i] || TEMPLATE_PARAM.test(seg));
+};
+
+// The proxy serves the most specific route: per segment static, then dynamic, then catch-all.
+const specificity = ({ template, catchAll }, literal) => {
+  const a = template.split('/');
+  return literal.split('/').map((_, i) => {
+    if (i >= a.length || (catchAll && i === a.length - 1)) return 2;
+    return TEMPLATE_PARAM.test(a[i]) ? 1 : 0;
+  });
+};
+const bySpecificity = (literal) => (x, y) => {
+  const [a, b] = [specificity(x, literal), specificity(y, literal)];
+  const i = a.findIndex((r, k) => r !== b[k]);
+  return i < 0 ? 0 : a[i] - b[i];
+};
+
+// The ops one literal path stands for: the provider's winning template with every method it
+// exposes, or the literal path itself when the provider's operations are not on disk.
+function opsFor(provider, { template, method }) {
+  const matched = (provider ?? []).filter((op) => templateMatches(op, template)).sort(bySpecificity(template));
+  if (matched.length === 0) return (method ? [method] : PROXY_METHODS).map((m) => `${m} ${template}`);
+  const winner = matched.filter((op) => op.template === matched[0].template);
+  if (winner.every((op) => op.method === INFERRED_METHOD)) return [];
+  if (method) return [`${method} ${winner[0].template}`];
+  return winner.filter((op) => op.method !== INFERRED_METHOD).map((op) => `${op.method} ${op.template}`);
+}
+
+export function scanAppDeps(root, { loadTs = loadTypeScript } = {}) {
+  const files = listFiles(root).filter((f) => SOURCE_FILE.test(f)).sort(byteCompare);
+  const contents = new Map(files.map((f) => [f, readFileSync(path.join(root, f))]));
+  const candidates = files.filter((f) => PREFILTER.some((s) => contents.get(f).includes(s)));
+  const ops = new Map(); // appId -> Set of "<METHOD> <template>"
+  const via = new Map(); // appId -> Set of how it is called
+  const providers = new Map(); // appId -> provider operations, or null
+  // Loaded only when there is something to parse, but a missing typescript must
+  // still stop the file being written for a tree that has candidates.
+  const ts = candidates.length ? loadTs() : null;
+  for (const file of candidates) {
+    for (const dep of collectDeps(ts, file, contents.get(file).toString('utf8'))) {
+      if (!ops.has(dep.appId)) ops.set(dep.appId, new Set());
+      if (!via.has(dep.appId)) via.set(dep.appId, new Set());
+      if (!providers.has(dep.appId)) providers.set(dep.appId, providerOps(root, dep.appId));
+      const provider = providers.get(dep.appId);
+      // A client call already names the provider's template, so it needs no matching.
+      const found = !dep.client ? opsFor(provider, dep) : dep.client === 'all' ? allProviderOps(root, dep.appId, provider) : [dep.client];
+      for (const op of found) ops.get(dep.appId).add(op);
+      via.get(dep.appId).add(dep.client ? VIA_CLIENT : VIA_PROXY_PATH);
+    }
+  }
+  const apps = {};
+  for (const appId of [...ops.keys()].filter((id) => ops.get(id).size).sort(byteCompare)) {
+    apps[appId] = { ops: [...ops.get(appId)].sort(byteCompare), via: DETECTS.filter((v) => via.get(appId).has(v)) };
+  }
+  const hashes = hashFiles(root, files, contents);
+  return { apps, detects: DETECTS, files: Object.fromEntries(files.map((f) => [f, hashes.get(f)])) };
+}
+
+export const serializeAppDeps = (result) => JSON.stringify(result, null, 2) + '\n';
+
+// Plug-in row for bin/scan.mjs. Any failure returns a warning and no content,
+// so the previous file stays and publish sees it as stale rather than trusting
+// a scan that did not finish.
+export const appDepsScanner = {
+  name: 'app-deps',
+  output: APP_DEPS_OUTPUT,
+  run: (root, options) => {
+    try {
+      return { content: serializeAppDeps(scanAppDeps(root, options)), warnings: [] };
+    } catch (err) {
+      return { warnings: [{ code: CODE_SCAN_FAILED, message: `${err && err.message ? err.message : err}` }] };
+    }
+  },
+};

package/bin/scan-client-calls.mjs

@@ -163,6 +163,22 @@ const isViewerSource = (name) =>
 
 const lineOf = (sf, node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
 
+// The HTTP method a `fetch` init object states, shared with the cross-app scan. A missing init or
+// method option is a GET; null means the method is not statically evident.
+export function literalFetchMethod(ts, init) {
+  const literal = (n) => n && (ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n));
+  if (!init) return DEFAULT_FETCH_HTTP_METHOD;
+  if (!ts.isObjectLiteralExpression(init)) return null;
+  let method = DEFAULT_FETCH_HTTP_METHOD;
+  for (const prop of init.properties) {
+    if (ts.isSpreadAssignment(prop) || (prop.name && ts.isComputedPropertyName(prop.name))) return null;
+    if (prop.name?.text !== 'method') continue;
+    if (!ts.isPropertyAssignment(prop) || !literal(prop.initializer)) return null;
+    method = prop.initializer.text;
+  }
+  return method;
+}
+
 class Scope {
   constructor(parent) {
     this.parent = parent;
@@ -174,7 +190,7 @@ class Scope {
   }
 }
 
-function scriptKind(ts, file) {
+export function scriptKind(ts, file) {
   if (/\.(?:tsx|jsx)$/.test(file)) return ts.ScriptKind.TSX;
   return /\.[cm]?js$/.test(file) ? ts.ScriptKind.JS : ts.ScriptKind.TS;
 }
@@ -206,16 +222,8 @@ export function collectFileFacts(ts, file, text, sdkMethods = null, localExports
   const fetchRoute = (call) => {
     const [pathArg, init] = call.arguments;
     if (!isLiteralText(pathArg)) return null;
-    let method = DEFAULT_FETCH_HTTP_METHOD;
-    if (init) {
-      if (!ts.isObjectLiteralExpression(init)) return null;
-      for (const prop of init.properties) {
-        if (ts.isSpreadAssignment(prop) || (prop.name && ts.isComputedPropertyName(prop.name))) return null;
-        if (prop.name?.text !== 'method') continue;
-        if (!ts.isPropertyAssignment(prop) || !isLiteralText(prop.initializer)) return null;
-        method = prop.initializer.text;
-      }
-    }
+    const method = literalFetchMethod(ts, init);
+    if (method === null) return null;
     // The SDK prepends the slash a path is missing, so `v1/me` requests `/v1/me`.
     const routePath = pathArg.text.startsWith('/') ? pathArg.text : `/${pathArg.text}`;
     return { path: routePath.replace(/[?#].*$/, ''), method };

package/bin/scan-routes.mjs

@@ -80,7 +80,7 @@ const gitBlobSha = (bytes) =>
 // `git hash-object` applies the repo's clean filters (autocrlf, .gitattributes),
 // so asking git yields the blob that will actually be committed; hashing raw
 // working-tree bytes would not under those filters.
-function hashFiles(root, files, contents) {
+export function hashFiles(root, files, contents) {
   const hashes = new Map();
   const inRepo = existsSync(path.join(root, '.git'));
   const isLink = (f) => lstatSync(path.join(root, f)).isSymbolicLink();

package/bin/scan.mjs

@@ -9,6 +9,7 @@
 import { mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { appDepsScanner } from './scan-app-deps.mjs';
 import { clientCallScanner } from './scan-client-calls.mjs';
 import { scanRoutes, serializeRoutes } from './scan-routes.mjs';
 
@@ -21,6 +22,7 @@ const SCANNERS = [
       return { content: serializeRoutes(result), warnings: result.warnings };
     },
   },
+  appDepsScanner,
 ];
 
 // Scanners whose result goes to the caller, not to a committed file. They run
@@ -48,8 +50,9 @@ export function runScanners(root = process.cwd(), scanners = SCANNERS) {
   const warnings = [];
   const outputs = {};
   for (const { scanner, content, result, warnings: found } of results) {
-    if (scanner.output) writeIfChanged(path.join(root, scanner.output), content);
-    else outputs[scanner.name] = result;
+    // A scanner that failed has no content; its previous file stays, so publish sees it as stale.
+    if (scanner.output && content !== undefined) writeIfChanged(path.join(root, scanner.output), content);
+    else if (!scanner.output) outputs[scanner.name] = result;
     warnings.push(...found.map((w) => ({ scanner: scanner.name, ...w })));
   }
   return { warnings, outputs };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [