@akanjs/devkit 3.2.0-rc.0 → 3.2.0-rc.2

package/transforms/barrelAnalyzer.ts

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 import { Logger } from "akanjs/common";
 import { parseNamedList } from "./moduleSyntax";
@@ -41,6 +42,8 @@ export class BarrelAnalyzer {
   readonly #logger = new Logger("BarrelAnalyzer");
   readonly #opts: BarrelAnalyzerOptions;
   readonly #cache = new Map<string, Promise<BarrelExportMap | null>>();
+  readonly #read = new Map<string, Set<string>>();
+  readonly #realDirs = new Map<string, string>();
   readonly #tsTranspiler = new Bun.Transpiler({ loader: "ts" });
   readonly #tsxTranspiler = new Bun.Transpiler({ loader: "tsx" });
 
@@ -56,12 +59,44 @@ export class BarrelAnalyzer {
     return promise;
   }
 
+  async filesOf(pkgName: string): Promise<string[]> {
+    await this.analyze(pkgName);
+    return [...(this.#read.get(pkgName) ?? [])];
+  }
+
+  //? A file beside one the analysis read counts too: created, it can take over a star export's specifier (`Foo.tsx`
+  //? beside `Foo/index.tsx`) with no read file changed. Both sides by realpath: a watcher names a symlinked lib's
+  //? files by their real path, where the walk went through the link.
+  forget(files: string[]): Map<string, Promise<BarrelExportMap | null>> {
+    const dirs = new Set(files.map((file) => realDirOf(file)));
+    const forgotten = new Map<string, Promise<BarrelExportMap | null>>();
+    for (const [pkgName, read] of this.#read) {
+      const analysis = this.#cache.get(pkgName);
+      if (!analysis || ![...read].some((file) => dirs.has(this.#realDirOf(file)))) continue;
+      forgotten.set(pkgName, analysis);
+      this.#cache.delete(pkgName);
+      this.#read.delete(pkgName);
+    }
+    return forgotten;
+  }
+
+  #realDirOf(file: string): string {
+    let dir = this.#realDirs.get(file);
+    if (dir === undefined) {
+      dir = realDirOf(file);
+      this.#realDirs.set(file, dir);
+    }
+    return dir;
+  }
+
   async #analyzeSafe(pkgName: string): Promise<BarrelExportMap | null> {
     try {
       const pkg = await this.#opts.resolvePackage(pkgName);
       if (!pkg) return null;
       const map: BarrelExportMap = new Map();
-      await this.#walk(pkg.entryFile, pkg, map, new Set());
+      const read = new Set<string>();
+      this.#read.set(pkgName, read);
+      await this.#walk(pkg.entryFile, pkg, map, read);
       return map;
     } catch (err) {
       this.#logger.error(`analyze failed for ${pkgName}: ${(err as Error).message}`);
@@ -170,6 +205,16 @@ export class BarrelAnalyzer {
   }
 }
 
+const realDirOf = (file: string): string => {
+  const dir = path.dirname(path.resolve(file));
+  try {
+    return fs.realpathSync.native(dir);
+  } catch {
+    // A directory removed with the file keeps its own path.
+    return dir;
+  }
+};
+
 const isRelative = (spec: string): boolean => {
   return spec.startsWith("./") || spec.startsWith("../") || spec === "." || spec === "..";
 };

package/transforms/barrelImportsPlugin.ts

@@ -4,7 +4,7 @@ import ts from "typescript";
 import { StoreBootstrap } from "../artifact/storeBootstrap";
 import type { App } from "../commandDecorators";
 import { BarrelAnalyzer, type BarrelExportMap, type PackageEntry } from "./barrelAnalyzer";
-import { loaderFor, type NamedItem, parseNamedList } from "./moduleSyntax";
+import { loaderFor, type NamedItem } from "./moduleSyntax";
 
 export interface BarrelImportsPluginOptions {
   /** Absolute paths whose content is returned unchanged (e.g. node_modules). */
@@ -234,10 +234,22 @@ const resolveFileCandidate = async (candidate: string): Promise<string | null> =
 
 const MACRO_ATTR_RE = /with\s*\{\s*type\s*:\s*["']macro["']\s*\}/;
 
+export interface RewriteBarrelImportsOptions {
+  /** Each replacement takes one line plus the newlines the statement spanned, so later lines keep their numbers. */
+  keepLines?: boolean;
+  specifierOf?: (subpath: string) => string;
+  /** Called for each import of a listed barrel with the value names whose rewrite reads its export map. */
+  onImport?: (barrel: string, names: string[]) => void;
+}
+
+export const workspaceBarrels = (barrels: readonly string[]): string[] =>
+  barrels.filter((barrel) => /^@(?:apps|libs)\//.test(barrel));
+
 export const rewriteBarrelImports = async (
   source: string,
   barrels: string[],
   analyzer: BarrelAnalyzer,
+  { keepLines = false, specifierOf = (subpath: string) => subpath, onImport }: RewriteBarrelImportsOptions = {},
 ): Promise<string | null> => {
   // Sound pre-filter before the costly parse: a static import cannot name a specifier absent from the text.
   if (!barrels.some((barrel) => source.includes(barrel))) return null;
@@ -251,20 +263,32 @@ export const rewriteBarrelImports = async (
     const stmt = statements[i];
     if (!stmt) continue;
     if (!barrels.includes(stmt.specifier)) continue;
+    const names = valueNamesOf(stmt.clause);
+    if (names.length > 0) onImport?.(stmt.specifier, names);
     const map = await analyzer.analyze(stmt.specifier);
     if (!map || map.size === 0) continue;
-    const replacement = rewriteSingleStatement(stmt, map);
-    if (replacement === null) continue;
+    const lines = rewriteSingleStatement(stmt, map, specifierOf);
+    if (lines === null) continue;
+    const replacement = keepLines
+      ? `${lines.join(" ")}${"\n".repeat(source.slice(stmt.start, stmt.end).split("\n").length - 1)}`
+      : lines.join("\n");
     out = out.slice(0, stmt.start) + replacement + out.slice(stmt.end);
     changed = true;
   }
   return changed ? out : null;
 };
 
+interface ParsedClause {
+  defaultImport?: string;
+  namespaceImport?: string;
+  named?: NamedItem[];
+  typeOnly: boolean;
+}
+
 interface ImportStatement {
   start: number;
   end: number;
-  clause: string;
+  clause: ParsedClause | null;
   specifier: string;
 }
 
@@ -286,52 +310,42 @@ const findImportStatements = (source: string): ImportStatement[] => {
     statements.push({
       start: statement.getStart(sourceFile),
       end: statement.end,
-      clause: source.slice(importClause.getStart(sourceFile), importClause.end).trim(),
+      clause: clauseOf(importClause),
       specifier: statement.moduleSpecifier.text,
     });
   }
   return statements;
 };
 
-interface ParsedClause {
-  defaultImport?: string;
-  namespaceImport?: string;
-  named?: NamedItem[];
-  typeOnly: boolean;
-}
-
-const parseImportClause = (clause: string): ParsedClause | null => {
-  let rest = clause.trim();
-  let typeOnly = false;
-  if (rest.startsWith("type ")) {
-    typeOnly = true;
-    rest = rest.slice(5).trim();
-  }
-  const parsed: ParsedClause = { typeOnly };
-  const commaMatch = /^(\w+)\s*,\s*(.+)$/.exec(rest);
-  if (commaMatch) {
-    parsed.defaultImport = commaMatch[1];
-    rest = commaMatch[2] ?? "";
-  } else if (/^\w+$/.test(rest)) {
-    parsed.defaultImport = rest;
-    return parsed;
-  }
-  if (rest.startsWith("*")) {
-    const ns = /^\*\s+as\s+(\w+)$/.exec(rest);
-    if (!ns) return null;
-    parsed.namespaceImport = ns[1];
-    return parsed;
-  }
-  if (rest.startsWith("{")) {
-    const close = rest.indexOf("}");
-    if (close === -1) return null;
-    parsed.named = parseNamedList(rest.slice(1, close));
+const clauseOf = (importClause: ts.ImportClause): ParsedClause | null => {
+  const parsed: ParsedClause = { typeOnly: importClause.phaseModifier === ts.SyntaxKind.TypeKeyword };
+  if (importClause.name) parsed.defaultImport = importClause.name.text;
+  const bindings = importClause.namedBindings;
+  if (!bindings) return parsed;
+  if (ts.isNamespaceImport(bindings)) return { ...parsed, namespaceImport: bindings.name.text };
+  const named: NamedItem[] = [];
+  for (const element of bindings.elements) {
+    if (element.propertyName && !ts.isIdentifier(element.propertyName)) return null;
+    named.push({
+      imported: (element.propertyName ?? element.name).text,
+      local: element.name.text,
+      isType: element.isTypeOnly,
+    });
   }
-  return parsed;
+  return { ...parsed, named };
 };
 
-const rewriteSingleStatement = (stmt: ImportStatement, map: BarrelExportMap): string | null => {
-  const clause = parseImportClause(stmt.clause);
+const valueNamesOf = (clause: ParsedClause | null): string[] => {
+  if (!clause || clause.namespaceImport || clause.typeOnly) return [];
+  return (clause.named ?? []).filter((item) => !item.isType).map((item) => item.imported);
+};
+
+const rewriteSingleStatement = (
+  stmt: ImportStatement,
+  map: BarrelExportMap,
+  specifierOf: (subpath: string) => string,
+): string[] | null => {
+  const { clause } = stmt;
   if (!clause) return null;
   // Namespace imports need the whole barrel — cannot rewrite safely.
   if (clause.namespaceImport) return null;
@@ -353,7 +367,7 @@ const rewriteSingleStatement = (stmt: ImportStatement, map: BarrelExportMap): st
       continue;
     }
     if (target.namespace) {
-      namespaceLines.push(`import * as ${item.local} from "${target.subpath}";`);
+      namespaceLines.push(`import * as ${item.local} from ${JSON.stringify(specifierOf(target.subpath))};`);
       continue;
     }
     const list = rewrites.get(target.subpath) ?? [];
@@ -364,7 +378,9 @@ const rewriteSingleStatement = (stmt: ImportStatement, map: BarrelExportMap): st
   if (rewrites.size === 0 && namespaceLines.length === 0) return null;
 
   //? An app or lib client barrel's import-time side effects are its client runtime and store, not its module UI.
-  const lines: string[] = [...(StoreBootstrap.ofClientBarrel(stmt.specifier, map) ?? [])];
+  const lines = (StoreBootstrap.ofClientBarrel(stmt.specifier, map) ?? []).map(
+    (specifier) => `import ${JSON.stringify(specifierOf(specifier))};`,
+  );
 
   if (clause.defaultImport || remaining.length > 0) {
     const parts: string[] = [];
@@ -374,11 +390,11 @@ const rewriteSingleStatement = (stmt: ImportStatement, map: BarrelExportMap): st
   }
 
   for (const [subpath, items] of rewrites) {
-    lines.push(`import { ${items.map(serializeNamedItem).join(", ")} } from "${subpath}";`);
+    lines.push(`import { ${items.map(serializeNamedItem).join(", ")} } from ${JSON.stringify(specifierOf(subpath))};`);
   }
   lines.push(...namespaceLines);
 
-  return lines.join("\n");
+  return lines;
 };
 
 const serializeNamedItem = (item: NamedItem): string => {

package/transforms/transforms.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import fs from "node:fs";
 import path from "node:path";
 import { ApplicationBuildReporter } from "../applicationBuildReporter";
 import { tempDirs, writeText as write } from "../testHelpers";
@@ -262,6 +263,27 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
     expect(await rewriteBarrelImports(source, ["@libs/util/common"], analyzer)).toBeNull();
   });
 
+  test("forgets an analysis when a file beside one it read changes, under the link or the real path", async () => {
+    const root = await makeTempRoot();
+    await write(path.join(root, "real/ui/index.ts"), 'export * from "./Foo";\n');
+    await write(path.join(root, "real/ui/Foo.ts"), "export const Foo = 1;\n");
+    await write(path.join(root, "real/other/Bar.ts"), "export const Bar = 1;\n");
+    fs.symlinkSync(path.join(root, "real"), path.join(root, "linked"));
+    const pkgDir = path.join(root, "linked/ui");
+    const analyzer = new BarrelAnalyzer({
+      resolvePackage: async () => ({ pkgName: "@scope/ui", entryFile: path.join(pkgDir, "index.ts"), pkgDir }),
+    });
+    const analyzed = async () => {
+      await analyzer.analyze("@scope/ui");
+      return analyzer;
+    };
+
+    expect([...(await analyzed()).forget([path.join(root, "real/other/Bar.ts")]).keys()]).toEqual([]);
+    expect([...(await analyzed()).forget([path.join(root, "real/ui/Foo.ts")]).keys()]).toEqual(["@scope/ui"]);
+    expect([...(await analyzed()).forget([path.join(pkgDir, "Created.ts")]).keys()]).toEqual(["@scope/ui"]);
+    expect([...analyzer.forget([path.join(pkgDir, "Foo.ts")]).keys()]).toEqual([]);
+  });
+
   test("rewrites flattenable named imports and preserves default, type, and unknown imports", async () => {
     const analyzer = fakeAnalyzer([
       ["A", { subpath: "@scope/pkg/leaf", originalName: "A" }],
@@ -287,6 +309,27 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
     expect(await rewriteBarrelImports('import { A } from "@other/pkg";', ["@scope/pkg"], analyzer)).toBeNull();
   });
 
+  test("reads every name of an import whose braces hold comments, aliases and type-only names", async () => {
+    const analyzer = fakeAnalyzer([
+      ["A", { subpath: "@scope/pkg/leaf", originalName: "A" }],
+      ["st", { subpath: "@scope/pkg/store", originalName: "st" }],
+    ]);
+    const rewrite = async (source: string) => await rewriteBarrelImports(source, ["@scope/pkg"], analyzer);
+    const narrowed = 'import { A } from "@scope/pkg/leaf";\nimport { st } from "@scope/pkg/store";\n';
+
+    expect(await rewrite('import {\n  A, // the leaf\n  st,\n} from "@scope/pkg";\n')).toBe(narrowed);
+    expect(await rewrite('import { A, /* the store */ st } from "@scope/pkg";\n')).toBe(narrowed);
+    expect(await rewrite('import { type Shape, A as Leaf, st as store } from "@scope/pkg";\n')).toBe(
+      [
+        'import { type Shape } from "@scope/pkg";',
+        'import { A as Leaf } from "@scope/pkg/leaf";',
+        'import { st as store } from "@scope/pkg/store";',
+        "",
+      ].join("\n"),
+    );
+    expect(await rewrite('import { "A" as quoted } from "@scope/pkg";\n')).toBeNull();
+  });
+
   test("keeps a client barrel's runtime and store, never its module UI, when flattening an app or lib import", async () => {
     const root = await makeTempRoot();
     for (const sys of ["apps/demo", "libs/kit"]) {
@@ -308,13 +351,15 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
     }
     await write(path.join(root, "libs/hand/client.ts"), 'export { thing } from "./lib/thing";\n');
     await write(path.join(root, "libs/hand/lib/thing.ts"), "export const thing = 1;\n");
+    await write(path.join(root, "libs/half/client.ts"), 'export { st } from "./lib/st";\n');
+    await write(path.join(root, "libs/half/lib/st.ts"), "export const st = {};\n");
     const analyzer = new BarrelAnalyzer({
       resolvePackage: await createTsconfigPackageResolver({
         workspace: { workspaceRoot: root },
         getTsConfig: async () => ({ compilerOptions: { paths: { "@apps/*": ["./apps/*"], "@libs/*": ["./libs/*"] } } }),
       } as never),
     });
-    const barrels = ["@apps/demo/client", "@libs/kit/client", "@libs/hand/client"];
+    const barrels = ["@apps/demo/client", "@libs/kit/client", "@libs/hand/client", "@libs/half/client"];
     const rewrite = async (source: string) => await rewriteBarrelImports(source, barrels, analyzer);
 
     expect(await rewrite('import { Memo, st } from "@apps/demo/client";\n')).toBe(
@@ -348,6 +393,27 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
     expect(await rewrite('import { thing } from "@libs/hand/client";\n')).toBe(
       ['import "@libs/hand/client";', 'import { thing } from "@libs/hand/lib/thing";', ""].join("\n"),
     );
+    expect(await rewrite('import { st } from "@libs/half/client";\n')).toBe(
+      ['import "@libs/half/client";', 'import { st } from "@libs/half/lib/st";', ""].join("\n"),
+    );
+  });
+
+  test("keeps each statement's line count and writes the specifier specifierOf gives a target", async () => {
+    const analyzer = fakeAnalyzer([
+      ["A", { subpath: "@scope/pkg/leaf", originalName: "A" }],
+      ["ns", { subpath: "@scope/pkg/namespace", originalName: "ns", namespace: true }],
+    ]);
+    const source = 'import {\n  A,\n  ns,\n} from "@scope/pkg";\nconsole.log(A, ns);\n';
+
+    const rewritten = await rewriteBarrelImports(source, ["@scope/pkg"], analyzer, {
+      keepLines: true,
+      specifierOf: (subpath) => `./${subpath.slice("@scope/pkg/".length)}.ts`,
+    });
+
+    expect(rewritten).toBe(
+      'import { A } from "./leaf.ts"; import * as ns from "./namespace.ts";\n\n\n\nconsole.log(A, ns);\n',
+    );
+    expect(rewritten?.split("\n")).toHaveLength(source.split("\n").length);
   });
 
   test("does not rewrite import-looking code inside template literals", async () => {

package/workflow/artifacts.ts

@@ -16,6 +16,7 @@ import type {
   WorkflowNextActionCode,
   WorkflowOverallStatus,
   WorkflowPlan,
+  WorkflowRecommendation,
   WorkflowRunArtifact,
   WorkflowRunSource,
   WorkflowValidationCommandResult,
@@ -133,6 +134,11 @@ export const createWorkflowApplyReport = ({
   };
 };
 
+export const withoutApplyHints = (recommendations: readonly WorkflowRecommendation[]) =>
+  recommendations.filter(
+    (recommendation) => recommendation.kind !== "auto-apply" && recommendation.kind !== "validation",
+  );
+
 export const resolveWorkflowCommand = (command: string, plan: WorkflowPlan) => {
   const target = typeof plan.inputs.app === "string" ? plan.inputs.app : "<app-or-lib>";
   return command
@@ -526,6 +532,17 @@ export const createWorkflowValidationRunReport = async ({
 };
 
 export const createDryRunWorkflowApplyReport = (plan: WorkflowPlan) => {
+  if (workflowStatus(plan.diagnostics) === "failed")
+    return createWorkflowApplyReport({
+      workflow: plan.workflow,
+      mode: "dry-run",
+      changedFiles: [],
+      generatedFiles: [],
+      diagnostics: [...plan.diagnostics],
+      recommendations: withoutApplyHints(plan.recommendations),
+      nextActions: [],
+      plan,
+    });
   const changedFiles: PrimitiveChangedFile[] = plan.predictedChanges.flatMap((change) => {
     if (change.action !== "create" && change.action !== "modify") return [];
     return [

package/workflow/plan.ts

@@ -1,6 +1,6 @@
 import { capitalize } from "akanjs/common";
 import type { Sys, Workspace } from "../commandDecorators";
-import { workflowPlanApproval } from "./artifacts";
+import { withoutApplyHints, workflowPlanApproval } from "./artifacts";
 import { resolveWorkflowSys } from "./executor";
 import { InteractionScaffold } from "./interactionScaffold";
 import { KeyRename } from "./keyRename";
@@ -17,6 +17,7 @@ import type {
   WorkflowSurfaceMode,
 } from "./types";
 import { addFieldUiPolicyForType } from "./uiPolicy";
+import { workflowStatus } from "./utils";
 
 const surfaceModes = new Set<WorkflowSurfaceMode>(["infer", "include", "skip"]);
 
@@ -487,7 +488,7 @@ const syssHolding = async (workspace: Workspace, module: string, except: Sys) =>
       .map(async (name) => await resolveWorkflowSys(workspace, name)),
   );
   const holding = await Promise.all(
-    others.map(async (other) => (other && (await other.readdir("lib")).includes(module) ? other : null)),
+    others.map(async (other) => (other && (await other.getDatabaseModules()).includes(module) ? other : null)),
   );
   return holding.filter((other): other is Sys => other !== null);
 };
@@ -495,24 +496,53 @@ const syssHolding = async (workspace: Workspace, module: string, except: Sys) =>
 const moduleMissing = async (workspace: Workspace, sys: Sys, module: string): Promise<WorkflowDiagnostic | null> => {
   if ((await sys.readdir("lib")).includes(module)) return null;
   const root = getSysRoot(sys);
-  const modules = [...(await sys.getDatabaseModules()), ...(await sys.getServiceModules())];
-  const sameName = modules.find((name) => name.replace(/^_/, "").toLowerCase() === module.toLowerCase());
+  const modules = await sys.getDatabaseModules();
+  const sameName = modules.find((name) => name.toLowerCase() === module.toLowerCase());
+  const service = (await sys.getServiceModules()).find(
+    (name) => name.replace(/^_/, "").toLowerCase() === module.replace(/^_/, "").toLowerCase(),
+  );
   const isScalar = (await sys.getScalarModules()).includes(module);
-  const [holder] = sameName || isScalar ? [] : await syssHolding(workspace, module, sys);
+  const [holder] = sameName || service || isScalar ? [] : await syssHolding(workspace, module, sys);
   return {
     severity: "error",
     code: "workflow-module-missing",
     input: "module",
     message: [
       `No module named ${module} in ${root}: ${root}/lib/${module} does not exist.`,
-      modules.length ? `Its modules are ${modules.join(", ")}.` : `${root} has no modules yet.`,
+      modules.length ? `Its database modules are ${modules.join(", ")}.` : `${root} has no database modules yet.`,
       sameName
         ? `Did you mean ${sameName}?`
-        : isScalar
-          ? `${root}/lib/__scalar/${module} is a scalar, and this workflow writes only into a module under ${root}/lib.`
-          : holder
-            ? `${module} is in ${getSysRoot(holder)}, so plan this with --app ${holder.name}.`
-            : `If ${module} is a new model, create it with the create-module workflow first, then plan this again.`,
+        : service
+          ? `${root}/lib/${service} is a service module, which stores no model, and this workflow writes only into a database module.`
+          : isScalar
+            ? `${root}/lib/__scalar/${module} is a scalar, and this workflow writes only into a module under ${root}/lib.`
+            : holder
+              ? `${module} is in ${getSysRoot(holder)}, so plan this with --app ${holder.name}.`
+              : `If ${module} is a new model, create it with the create-module workflow first, then plan this again.`,
+    ].join(" "),
+  };
+};
+
+const moduleNotDatabase = async (sys: Sys, spec: WorkflowSpec, module: string): Promise<WorkflowDiagnostic | null> => {
+  const databaseModules = await sys.getDatabaseModules();
+  if (databaseModules.includes(module)) return null;
+  const root = getSysRoot(sys);
+  const isServiceModule = module.startsWith("_") && !module.startsWith("__");
+  return {
+    severity: "error",
+    code: "workflow-module-not-database",
+    input: "module",
+    message: [
+      isServiceModule
+        ? `${module} in ${root} is a service module, which stores no model.`
+        : `${root}/lib/${module} is not a database module: it has no ${module}.constant.ts.`,
+      `${spec.name} needs a database module, one with lib/<model>/<model>.constant.ts.`,
+      databaseModules.length
+        ? `Its database modules are ${databaseModules.join(", ")}.`
+        : `${root} has no database modules yet.`,
+      spec.inputs.field
+        ? "Add the field to one of them, or create its model with the create-module workflow first; a value several models embed is a scalar, made with create-scalar and added to a model as a field of that type."
+        : "Plan this on one of them, or create the model with the create-module workflow first.",
     ].join(" "),
   };
 };
@@ -539,11 +569,11 @@ export const workflowTargetDiagnostics = async (
   const module = planString(inputs, "module");
   const moduleSpec: WorkflowInputSpec | undefined = spec.inputs.module;
   if (!module || !moduleSpec?.mustExist) return [];
-  const missing = await moduleMissing(workspace, sys, module);
-  return missing ? [missing] : [];
+  const refused = (await moduleMissing(workspace, sys, module)) ?? (await moduleNotDatabase(sys, spec, module));
+  return refused ? [refused] : [];
 };
 
-export const inspectWorkflowPlan = async (
+const inspectPlanTarget = async (
   workspace: Workspace,
   spec: WorkflowSpec,
   plan: WorkflowPlan,
@@ -586,3 +616,13 @@ export const inspectWorkflowPlan = async (
     recommendations: [...plan.recommendations, ...inspected.recommendations],
   };
 };
+
+export const inspectWorkflowPlan = async (
+  workspace: Workspace,
+  spec: WorkflowSpec,
+  plan: WorkflowPlan,
+): Promise<WorkflowPlan> => {
+  const inspected = await inspectPlanTarget(workspace, spec, plan);
+  if (workflowStatus(inspected.diagnostics) === "passed") return inspected;
+  return { ...inspected, recommendations: withoutApplyHints(inspected.recommendations) };
+};

package/workspaceGraph.test.ts

@@ -1,7 +1,16 @@
-import { describe, expect, it } from "bun:test";
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
 import type { AkanChangeMap, AkanGraphEdge, AkanGraphNode } from "@akanjs/language";
+import type { Workspace } from "./commandDecorators";
 import { WorkspaceGraph } from "./workspaceGraph";
 
+const roots: string[] = [];
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
 const node = (id: string, owner: string | null, change?: AkanGraphNode["change"]): AkanGraphNode => ({
   id,
   kind: id.split(":")[0] as AkanGraphNode["kind"],
@@ -13,10 +22,15 @@ const node = (id: string, owner: string | null, change?: AkanGraphNode["change"]
   at: null,
   ...(change ? { change } : {}),
 });
-const edge = (from: string, to: string, change?: AkanGraphEdge["change"]): AkanGraphEdge => ({
+const edge = (
+  from: string,
+  to: string,
+  change?: AkanGraphEdge["change"],
+  kind: AkanGraphEdge["kind"] = "calls",
+): AkanGraphEdge => ({
   from,
   to,
-  kind: "calls",
+  kind,
   label: null,
   count: 1,
   at: null,
@@ -102,6 +116,60 @@ describe("WorkspaceGraph.answer", () => {
   });
 });
 
+describe("WorkspaceGraph.answer past the node limit", () => {
+  const changeMapOf = (nodes: AkanGraphNode[], edges: AkanGraphEdge[]): AkanChangeMap => ({
+    version: 1,
+    nodes,
+    edges,
+    since: "0123456789ab",
+    summary: { added: 0, removed: 0, changed: nodes.filter((item) => item.change).length },
+    unmapped: [],
+  });
+
+  it("drops the layout that only wraps a changed route, and keeps the route", () => {
+    const fillers = Array.from({ length: 599 }, (_, idx) => node(`method:apps/demo:memo.m${idx}`, "apps/demo"));
+    const answer = WorkspaceGraph.answer(
+      {
+        version: 1,
+        nodes: [
+          node("layout:apps/demo:/", "apps/demo"),
+          node("route:apps/demo:/memo", "apps/demo", "changed"),
+          ...fillers,
+        ],
+        edges: [edge("layout:apps/demo:/", "route:apps/demo:/memo", undefined, "wraps")],
+      },
+      {},
+    );
+    if ("diagnostics" in answer) throw new Error("expected an answer");
+    expect(answer.nodes.filter((item) => item.kind !== "method").map(({ id }) => id)).toEqual([
+      "route:apps/demo:/memo",
+    ]);
+    expect(answer.edges).toEqual([]);
+  });
+
+  it("answers a Change Map whole once its unchanged pages are set aside", () => {
+    const routes = Array.from({ length: 10 }, (_, idx) => node(`route:apps/demo:/r${idx}`, "apps/demo"));
+    const changed = Array.from({ length: 595 }, (_, idx) =>
+      node(`method:apps/demo:memo.m${idx}`, "apps/demo", "changed"),
+    );
+    const answer = WorkspaceGraph.answerChanges(changeMapOf([...routes, ...changed], []), {});
+    if ("diagnostics" in answer) throw new Error("expected an answer");
+    expect(answer.nodes).toHaveLength(595);
+    expect(answer.summary).toEqual({ added: 0, removed: 0, changed: 595 });
+  });
+
+  it("counts the changed pages it keeps when it names the owners to scope to", () => {
+    const routes = Array.from({ length: 650 }, (_, idx) => node(`route:apps/demo:/r${idx}`, "apps/demo", "changed"));
+    const answer = WorkspaceGraph.answerChanges(
+      changeMapOf([...routes, node("method:libs/shared:file.touch", "libs/shared", "changed")], []),
+      {},
+    );
+    if (!("owners" in answer)) throw new Error("expected a scope request");
+    expect(answer.diagnostics.map(({ message }) => message).join("\n")).toContain("651 nodes");
+    expect(answer.owners).toEqual({ "apps/demo": 650, "libs/shared": 1 });
+  });
+});
+
 describe("WorkspaceGraph.scope", () => {
   it("keeps a lib's guard without pulling in every app endpoint that uses it", () => {
     const guard = "guard:libs/shared:Admin";
@@ -119,3 +187,48 @@ describe("WorkspaceGraph.scope", () => {
     expect(scoped.edges).toEqual([edge(own, guard)]);
   });
 });
+
+describe("WorkspaceGraph.changesAt", () => {
+  it("maps an edit to a factory in one lib onto the guards it makes in another, and lists no file as unmapped", async () => {
+    const root = await mkdtemp(path.join(tmpdir(), "akan-graph-"));
+    roots.push(root);
+    const git = (...args: string[]) => {
+      const result = Bun.spawnSync(
+        ["git", "-c", "user.name=akan", "-c", "user.email=akan@example.com", "-c", "commit.gpgsign=false", ...args],
+        { cwd: root, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" } },
+      );
+      expect(result.exitCode).toBe(0);
+      return result.stdout.toString().trim();
+    };
+    const write = async (file: string, text: string) => {
+      await mkdir(path.dirname(path.join(root, file)), { recursive: true });
+      await writeFile(path.join(root, file), text);
+    };
+    const factory = (body: string) => `import type { Guard } from "akanjs/signal";
+export const resourceGuard = (field: string) =>
+  class implements Guard {
+    canPass() {
+      return ${body};
+    }
+  };
+`;
+    git("init", "-q", "-b", "main");
+    await write("libs/util/srvkit/resource.ts", factory("!!field"));
+    await write(
+      "apps/demo/srvkit/guards.ts",
+      `import { resourceGuard } from "@libs/util/srvkit";\nexport const Member = resourceGuard("member");\n`,
+    );
+    git("add", "-A");
+    git("commit", "-q", "--no-verify", "-m", "base");
+    await write("libs/util/srvkit/resource.ts", factory("field.length > 0"));
+    const changes = await WorkspaceGraph.changesAt(
+      { workspaceRoot: root } as unknown as Workspace,
+      git("rev-parse", "HEAD"),
+    );
+    expect(changes.nodes.filter((node) => node.change).map(({ id, change }) => `${change} ${id}`)).toEqual([
+      "changed guard:apps/demo:Member",
+    ]);
+    expect(changes.unmapped).toEqual([]);
+    expect(changes.nodes.some((node) => "sources" in node)).toBe(false);
+  });
+});