@jskit-ai/architecture-inspector 0.1.0 → 0.1.2

package/README.md

@@ -1,9 +1,10 @@
 # Architecture Inspector
 
 `@jskit-ai/architecture-inspector/vue` exports
-`inspectVueArchitecture({ projectRoot, input, aliases, httpScope, apiBasePath })`
+`inspectVueArchitecture({ projectRoot, input, aliases, httpScope, apiBasePath, calls, apiPrefixAliases })`
 for finite static architecture inspection, and ships the `jskit-inspect-vue`
-command. It is a plain tool package, not a JSKIT framework runtime package.
+command and the Vue Preview locator `src/previewLocator.js`. It is a plain tool
+package, not a JSKIT framework runtime package.
 
 ## Architecture inspection
 
@@ -16,15 +17,25 @@ Run `jskit-inspect-vue` in the project directory. It reads one bounded JSON
 document from stdin and writes one `genesis.architecture-observations.v1` JSON
 document to stdout. Errors use stderr and a failing exit status. It does not
 import application code, start a server, generate router declarations or retain
-a watcher. The package has no Genesis or Vibe64 dependency.
+a watcher. The package imports no consumer's code: the input contract is its
+own, and it writes the observation format its consumer defines, which it names
+only by schema id. The command runs the
+inspection in a child Node process whose old generation is bounded by the size
+of the declared scripts (192 MB plus 56 MB per MiB), so memory stays near what
+the inspection holds; a caller that starts Node with its own
+`--max-old-space-size` keeps that bound and runs in place.
 
-Input supplies `schema: "vibe64.architecture-inspection-input.v1"`, indexed
+Input supplies `schema: "jskit.architecture-inspection-input.v1"`, indexed
 `files: [{ path, hash }]` and `uiDiscovery.discoveries`. Optional `packages`
 carry `id`, `name`, `manifest`, `declarations`, `root`, `opaque` and public
 `entryPoints: [{ importPath, file }]`; `packageIdentity` binds observations to
-the same inspected public boundaries. Paths are project-relative
+the same inspected public boundaries. A package resolves for the files under
+each manifest that declares it (`declarations: [{ manifest }]`, or its
+`manifest` when it has none), whatever the dependency kind, so the packages of
+a workspace resolve one another when each workspace manifest is declared. Paths are project-relative
 and hashes use `sha256:<hex>`. Only declared, hash-matching UTF-8 files are read;
-symlinks and files over 4 MiB are rejected.
+symlinks and files over 4 MiB are rejected. Optional `stackHash` and
+`cacheDirectory` serve the call cache below; other unknown fields are ignored.
 
 Each discovery supplies `id`, `adapter`, `surface`, `mode`, `registrations`,
 `pageRoots` and `componentRoots`. Supported adapters are `jskit`,
@@ -49,9 +60,21 @@ Each discovery supplies `id`, `adapter`, `surface`, `mode`, `registrations`,
   `default`, namespace `*` and type-only classification. These are import facts,
   not evidence of runtime calls. Coverage remains partial; namespace use does
   not establish which individual exports are consumed.
-- An explicit `--http-scope shop --api-base-path /api` enables scoped literal
-  `fetch` uses and receivers registered through JSKIT's `defineFeature` setup
-  `http.router.register`. Use `--alias @=src` for declared project aliases.
+- An HTTP scope names the application's operations and enables scoped literal
+  `fetch` uses and the routes a `defineFeature` setup registers on its HTTP
+  router. It is the root `package.json` `name`, or `--http-scope shop` when
+  the operations should carry another name; without either, HTTP observations
+  stay unconfigured. Use `--alias @=src` for declared project aliases.
+- `router.register(method, path, options, handler)` becomes an entry operation
+  whose controller is the handler, when the router is `http.router` of the
+  setup's destructured `http` dependency (or `dependencies.http.router`), used
+  in the setup or passed to a project function that registers on the parameter
+  receiving it. Such functions may be local or imported through named imports
+  and re-exports, at most four calls deep. The method and path must be
+  literals, local constants or template literals of them; a call of the
+  kernel's `resolveScopedApiBasePath` with literal options stands for the path
+  it returns. Anything else is reported as `CONTROLLER_UNRESOLVED`.
+  `--api-base-path /api` prefixes these paths.
 - Actual `CrudListScreen` / `CrudAddEditScreen` uses whose bound screen comes from
   the matching JSKIT composable can connect to exported `defineCrudJsonApiFeature`
   controller declarations. The resource must resolve through indexed imports and
@@ -61,6 +84,104 @@ Each discovery supplies `id`, `adapter`, `surface`, `mode`, `registrations`,
   than claiming a fully expanded runtime URL. Custom clients, transport/resource
   overrides, dynamic operations and disabled routes do not create guessed links.
   This shows declared entry points; runtime provider activation is not proven.
+  Each such entry operation carries the `actionId` its route runs,
+  `crud.<namespace>.<operation>`. The declaration's custom `actions` (a literal
+  object, bound locally or imported through named re-exports) that declare a
+  literal `route` become `http` entry operations at the declaration's API base
+  path (`scope.routeBase` and `relativePath`) plus the route's `path`, with the
+  action's `id`, or `crud.<namespace>.<name>` without one. Other forms are reported
+  as `CRUD_ACTION_ROUTE_UNRESOLVED`.
+
+- Routes registered through the kernel's `createActionRouteScope` become entry
+  operations with their full path and, for `actionRoute`, their `actionId`.
+  The scope options must be string literals or imported constant strings;
+  each route's method, suffix and `actionId` must be literals, template
+  literals or elements of an enclosing literal array's `.map` or `for...of`
+  (at most 64). Anything else is reported as `ACTION_ROUTE_UNRESOLVED` or
+  `ACTION_ROUTE_SCOPE_UNBOUND`, never guessed.
+
+### Function calls (`--calls`)
+
+`--calls` (library option `calls: true`) adds `functions`, `calls` and
+`entryPoints` and their capabilities. Without it the output is unchanged.
+
+- **Functions.** Every function-like with a body, plus each file's top-level
+  code as `fn:<path>#module`. Other ids are `fn:<path>#<line>:<column>` at the
+  syntax node's start after decorators, `export` and comments, the same
+  position Genesis's syntax sites use. `exported: true` marks exported
+  top-level functions; `container` names an enclosing class or object.
+- **Calls.** One TypeScript program over the declared scripts and Vue script
+  blocks only, plus TypeScript's own libraries; nothing under `node_modules` is
+  loaded. Each call is `exact` (`checker`, `di-binding`, `self`,
+  `route-action` or single-valued `argument-flow`), `probable` (other
+  `argument-flow`, `receiver-name`, or several candidates) or `unresolved`.
+  - `defineFeature` injection binds `requires` tokens to the `setup` outputs
+    that `provides` them: one provider is exact, several are ambiguous.
+  - Argument flow follows the caller. A function passed to a parameter that
+    the callee calls while it runs (in its own body, in callbacks it passes
+    on, or by forwarding it to a function that does) is an `argument-flow`
+    call of the function that passes it, recorded at that call. The callee's
+    own call of the parameter is `unresolved`, so one caller's callback is
+    never reached through another caller. A parameter called only from a
+    closure the callee stores or returns keeps every value its callers pass.
+    Argument flow is exact when it names one function for certain: a passed
+    inline function or a name bound to one function, or a parameter (also a
+    destructured factory parameter such as `createActions({ sessions })`)
+    that receives one value across all the project's calls, when that value
+    resolves exactly. Several values stay probable.
+  - JSDoc types are declared types: `@param`, `@type`, `@typedef` and
+    `import("...")` types, including a package's `./server/types` reached
+    through its declared entry points. A call through a parameter or binding
+    typed that way is a `checker` call. A member a type declares as `typeof` a
+    function (`{ run: typeof run }`, `@property {typeof run} run`) is that
+    function.
+  - Action definitions (`{ id, execute }` in a feature's `actions`, also through
+    `create*Actions` factories, pass-through wrappers and literal-array `.map`,
+    with ids that are literals or module constants) and the custom actions of a
+    CRUD declaration become `action` entry points;
+    `request.executeAction({ actionId: "..." })` reaches their execute
+    function, and the `controllerFunctionId` of each entry operation that names
+    an action is that function.
+  - Calls that are provably external are left out: package imports, builtins,
+    values produced by them (including `let` assignments, `for...of`,
+    destructuring and callbacks they call), Vue's `<script setup>` macros and
+    `emit`.
+  - A method call on an untyped receiver (`receiver-name`) reaches a project
+    function only when exactly one function on that side declares the name
+    (or exactly one in a file the receiver names) and no builtin member has
+    it: the members of TypeScript's libraries and of Node's `EventEmitter`,
+    `fs.Stats` and streams. Otherwise it is `unresolved`, and a builtin name
+    no project function declares is left out.
+  - At most 2,000 call records per file; beyond that `CALLS_TRUNCATED` and a
+    `partial` calls capability.
+- **Transports.** With an HTTP scope, `useEndpointResource`, `useCommand`,
+  `getHttpWebClient().request` and client `fetch` become operation uses that
+  carry `fromFunctionId`; `parentId` is set only in page and component files.
+  Paths are partially evaluated (template literals, constants, imports,
+  parameter defaults, `usePaths().api`, `resolveScopedApiBasePath`). A key is
+  `keyCertainty: "exact"` when every route literal is matched; two or three
+  candidate routes give one `probable` use each, with ids suffixed per
+  candidate. `--api-prefix-alias /api/x=/api/app/:slug/x` (repeatable) rewrites
+  client prefixes before matching.
+- **Cache.** With an absolute, existing `cacheDirectory` outside the project,
+  the command keeps `jskit-calls.json` there. An unchanged rerun reuses the
+  whole result. Otherwise a file keeps its calls when its own and its directly
+  imported sources are unchanged and every target still exists. Calls that
+  injection or argument flow resolve depend on other files' arguments, so they
+  are resolved again on every run; a file whose such calls now reach other
+  functions is resolved again, with every reused file whose calls reach it. Any change to a
+  manifest, lockfile, `tsconfig`/`jsconfig`, the inspector's own manifest or
+  source (even without a version bump), packages, UI discovery, options or
+  `stackHash` rebuilds everything. An absent, unusable or corrupt cache means a
+  cold run.
+
+### Preview locator
+
+`src/previewLocator.js` is a classic script a Preview can inline. It defines
+`globalThis.__jskitLocateElement(element)`, which returns `{ file, name? }` for
+the nearest component with a source file (Vue development builds record it as
+`__file`) that rendered the element, or `null` for plain DOM. It reads only
+Vue's component bookkeeping, never text content or values.
 
 Dynamic routing, template component tokens, runtime placement predicates,
 application request wrappers and dispatcher conventions require more evidence or
@@ -72,13 +193,14 @@ Example consumer-owned Stack operation:
 
 ```markdown
 
-### Inspector `vue`: Inspect Vue pages
+### Inspector `vue`: Inspect Vue pages and function calls
 
 - Runtime: `nodejs`
 - Directory: `.`
-- Command: `node` `node_modules/@jskit-ai/architecture-inspector/src/cli.js` `--alias` `@=src`
-- Timeout seconds: `30`
-- Max output bytes: `4194304`
+- Command: `node` `node_modules/@jskit-ai/architecture-inspector/src/cli.js` `--alias` `@=src` `--calls`
+- Timeout seconds: `90`
+- Max output bytes: `67108864`
+- Preview locator: `node_modules/@jskit-ai/architecture-inspector/src/previewLocator.js`
 ```
 
 The consumer owns command admission, runtime selection, cancellation, publication

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/architecture-inspector",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Static Vue architecture inspector for the portable architecture-inspection command contract.",
   "type": "module",
   "files": [
@@ -18,7 +18,9 @@
   },
   "dependencies": {
     "@babel/parser": "7.29.9",
-    "@vue/compiler-sfc": "3.5.44"
+    "@jskit-ai/kernel": "0.2.4",
+    "@vue/compiler-sfc": "3.5.44",
+    "typescript": "6.0.3"
   },
   "peerDependencies": {
     "vue-router": "^5.3.1"

package/src/calls/cache.js

@@ -0,0 +1,97 @@
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync } from "node:fs";
+import { readFile, rename, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// v3: each file keeps its checker sites, the candidates injection or argument
+// flow can resolve, and the sites they resolved to, apart.
+const CACHE_SCHEMA = "jskit.architecture-calls-cache.v3";
+const CACHE_FILE = "jskit-calls.json";
+// Manifests, lockfiles and compiler configurations change how every file
+// resolves, so any change to them rebuilds everything.
+const PROJECT_FILE_PATTERN = /(?:^|\/)(?:package\.json|package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|[jt]sconfig(?:\.[\w.-]+)?\.json)$/u;
+const INSPECTOR_ROOT = fileURLToPath(new URL("../../", import.meta.url));
+
+function digest(value) {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+
+// The inspector's manifest (its version and dependency pins) and every source
+// file, read once per run. A changed resolver changes the key even without a
+// version bump, as in source development or a linked checkout.
+let inspectorIdentity = null;
+function inspectorSourceHash() {
+  if (!inspectorIdentity) {
+    const hash = createHash("sha256").update(readFileSync(path.join(INSPECTOR_ROOT, "package.json")));
+    const sourceRoot = path.join(INSPECTOR_ROOT, "src");
+    for (const file of readdirSync(sourceRoot, { recursive: true }).filter((name) => name.endsWith(".js")).sort()) {
+      hash.update(`\0${file}\0`).update(readFileSync(path.join(sourceRoot, file)));
+    }
+    inspectorIdentity = hash.digest("hex");
+  }
+  return inspectorIdentity;
+}
+
+// The cache file inside the caller's cache directory, or null when the
+// directory is not an existing absolute directory outside the project.
+async function cacheLocation(projectRoot, directory) {
+  if (typeof directory !== "string" || !path.isAbsolute(directory)) {
+    return null;
+  }
+  const resolved = path.resolve(directory);
+  if (resolved === projectRoot || resolved.startsWith(`${projectRoot}${path.sep}`)) {
+    return null;
+  }
+  const entry = await stat(resolved).catch(() => null);
+  return entry?.isDirectory() ? path.join(resolved, CACHE_FILE) : null;
+}
+
+async function readCallCache(location, key) {
+  try {
+    const cache = JSON.parse(await readFile(location, "utf8"));
+    return cache?.schema === CACHE_SCHEMA && cache.key === key && cache.files && typeof cache.files === "object" ? cache : null;
+  } catch {
+    return null;
+  }
+}
+
+// Written beside the final file and renamed into place; a cache that cannot
+// be written only means the next run is cold.
+async function writeCallCache(location, cache) {
+  const temporary = `${location}.${process.pid}.tmp`;
+  try {
+    await writeFile(temporary, JSON.stringify({ schema: CACHE_SCHEMA, ...cache }));
+    await rename(temporary, location);
+  } catch {
+    // An unusable cache directory leaves the inspection result unchanged.
+  }
+}
+
+// Keys for one inspection: everything that affects every file, each file's
+// own and directly imported sources, and the whole run.
+function cacheKeys({ input, files, imports, scripts, options }) {
+  const projectFiles = [...files.values()]
+    .filter((file) => PROJECT_FILE_PATTERN.test(file.path))
+    .map((file) => [file.path, file.hash])
+    .sort();
+  const key = digest({
+    inspector: inspectorSourceHash(),
+    stackHash: input.stackHash ?? null,
+    packages: input.packages ?? null,
+    uiDiscovery: input.uiDiscovery ?? null,
+    options,
+    projectFiles
+  });
+  const importsByFile = new Map();
+  for (const use of imports) {
+    importsByFile.set(use.fromFile, (importsByFile.get(use.fromFile) || new Set()).add(use.targetFile));
+  }
+  const fileKeys = new Map(scripts.map((file) => [file, digest([
+    files.get(file).hash,
+    [...(importsByFile.get(file) || [])].sort().map((target) => [target, files.get(target)?.hash ?? null])
+  ])]));
+  return { key, fileKeys, runKey: digest([key, [...fileKeys].sort()]) };
+}
+
+export { cacheKeys, cacheLocation, readCallCache, writeCallCache };