@assembly-js/app-foundation 0.3.5 → 0.3.6

package/CHANGELOG.md

@@ -19,6 +19,9 @@ 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.
 

package/bin/scan-app-deps.mjs

@@ -1,5 +1,5 @@
-// Finds which other apps' operations an app calls by literal proxy path and
-// describes them as `.assembly/app-deps.json`, so publish reads one file
+// 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
@@ -12,6 +12,7 @@
 // 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';
 
@@ -23,6 +24,16 @@ 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';
@@ -88,10 +99,56 @@ function resolveString(ts, node, consts) {
   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);
@@ -106,13 +163,39 @@ function collectDeps(ts, file, text) {
       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');
@@ -164,6 +247,7 @@ export function scanAppDeps(root, { loadTs = loadTypeScript } = {}) {
   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.
@@ -171,16 +255,21 @@ export function scanAppDeps(root, { loadTs = loadTypeScript } = {}) {
   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));
-      for (const op of opsFor(providers.get(dep.appId), dep)) ops.get(dep.appId).add(op);
+      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: [VIA_PROXY_PATH] };
+    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, files: Object.fromEntries(files.map((f) => [f, hashes.get(f)])) };
+  return { apps, detects: DETECTS, files: Object.fromEntries(files.map((f) => [f, hashes.get(f)])) };
 }
 
 export const serializeAppDeps = (result) => JSON.stringify(result, null, 2) + '\n';

package/package.json

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