@akanjs/devkit 3.1.1-rc.9 → 3.1.1

package/testOnlyExportScanner.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import type { SourceFileInfo } from "./qualityScanner";
+import { TestOnlyExportScanner } from "./testOnlyExportScanner";
+
+const fileOf = (file: string, content: string): SourceFileInfo => ({
+  file,
+  absolutePath: `/repo/${file}`,
+  content,
+  sourceFile: ts.createSourceFile(
+    file,
+    content,
+    ts.ScriptTarget.Latest,
+    true,
+    file.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+  ),
+});
+
+const scan = (files: Record<string, string>) =>
+  new TestOnlyExportScanner().scan(Object.entries(files).map(([file, content]) => fileOf(file, content)));
+
+const layout = [
+  "export const groupLabelHeight = 30;",
+  "export const computeGroupBoxes = () => [groupLabelHeight];",
+  "export const groupEdgeStrips = (pad: number): number[] => (pad > 0 ? groupEdgeStrips(pad - 1) : []);",
+  "export const layoutBoard = () => 1;",
+  "",
+].join("\n");
+
+const layoutTest = [
+  'import { computeGroupBoxes, groupEdgeStrips, groupLabelHeight, layoutBoard } from "./boardLayout";',
+  "test(() => [computeGroupBoxes(), groupEdgeStrips(1), groupLabelHeight, layoutBoard()]);",
+  "",
+].join("\n");
+
+describe("TestOnlyExportScanner", () => {
+  test("flags an export only tests reference, even when it calls itself", () => {
+    const warnings = scan({
+      "apps/demo/webkit/boardLayout.ts": layout,
+      "apps/demo/webkit/boardLayout.test.ts": layoutTest,
+      "apps/demo/ui/Board.tsx":
+        'import { layoutBoard } from "@apps/demo/webkit";\nexport const Board = () => layoutBoard();\n',
+    });
+
+    expect(warnings.map((warning) => warning.message)).toEqual([
+      'Exported "computeGroupBoxes" is referenced only by tests: apps/demo/webkit/boardLayout.test.ts.',
+      'Exported "groupEdgeStrips" is referenced only by tests: apps/demo/webkit/boardLayout.test.ts.',
+    ]);
+    expect(warnings[0]).toMatchObject({
+      rule: "akan.global.test-only-export",
+      scope: "global",
+      file: "apps/demo/webkit/boardLayout.ts",
+      line: 2,
+      locations: [{ file: "apps/demo/webkit/boardLayout.test.ts", line: 1 }],
+    });
+  });
+
+  test("passes an export another source file uses, or that a function in its own file uses", () => {
+    const warnings = scan({
+      "apps/demo/webkit/boardLayout.ts": layout,
+      "apps/demo/webkit/boardLayout.test.ts": layoutTest,
+      "apps/demo/ui/Board.tsx": [
+        'import * as webkit from "@apps/demo/webkit";',
+        "export const Board = () => [webkit.computeGroupBoxes(), webkit.groupEdgeStrips(2), webkit.layoutBoard()];",
+        "",
+      ].join("\n"),
+    });
+
+    expect(warnings).toEqual([]);
+  });
+
+  test("passes an export no test references, and leaves lib facets and lib modules alone", () => {
+    expect(
+      scan({
+        "apps/demo/common/unused.ts": "export const unused = 1;\n",
+        "libs/demo/webkit/signedIn.ts": "export const signedIn = () => true;\n",
+        "libs/demo/webkit/signedIn.test.ts": 'import { signedIn } from "./signedIn";\ntest(() => signedIn());\n',
+        "apps/demo/lib/post/post.constant.ts": "export class PostInput {}\n",
+        "apps/demo/lib/post/post.signal.test.ts": "const input = new PostInput();\n",
+      }),
+    ).toEqual([]);
+  });
+});

package/testOnlyExportScanner.ts

@@ -0,0 +1,124 @@
+import ts from "typescript";
+import type { QualityWarning, SourceFileInfo } from "./qualityScanner";
+
+interface ExportedDeclaration {
+  name: string;
+  line: number;
+  statement: ts.Statement;
+}
+
+interface TestReference {
+  file: string;
+  line: number;
+}
+
+export class TestOnlyExportScanner {
+  static readonly rule = "akan.global.test-only-export";
+  static #facets = new Set(["common", "webkit", "srvkit", "ui"]);
+
+  scan(sourceFiles: SourceFileInfo[]): QualityWarning[] {
+    const liveFileNumByName = new Map<string, number>();
+    const testRefsByName = new Map<string, TestReference[]>();
+    for (const { file, sourceFile } of sourceFiles) {
+      const isTest = TestOnlyExportScanner.#isTest(file);
+      for (const [name, line] of TestOnlyExportScanner.#identifierLinesOf(sourceFile)) {
+        if (!isTest) liveFileNumByName.set(name, (liveFileNumByName.get(name) ?? 0) + 1);
+        else if (testRefsByName.has(name)) testRefsByName.get(name)?.push({ file, line });
+        else testRefsByName.set(name, [{ file, line }]);
+      }
+    }
+    return sourceFiles
+      .filter(({ file }) => TestOnlyExportScanner.#isFacetSource(file))
+      .flatMap(({ file, sourceFile }) => {
+        const declarations = TestOnlyExportScanner.#exportedDeclarationsOf(sourceFile);
+        return declarations
+          .filter(({ name }) => (liveFileNumByName.get(name) ?? 0) <= 1)
+          .filter(({ name }) => !TestOnlyExportScanner.#isUsedInFile(sourceFile, name, declarations))
+          .flatMap(({ name, line }) => {
+            const testRefs = testRefsByName.get(name);
+            if (!testRefs?.length) return [];
+            return [
+              {
+                rule: TestOnlyExportScanner.rule,
+                scope: "global" as const,
+                severity: "warning" as const,
+                file,
+                line,
+                message: `Exported "${name}" is referenced only by tests: ${testRefs.map((ref) => ref.file).join(", ")}.`,
+                locations: testRefs,
+              },
+            ];
+          });
+      });
+  }
+
+  static #isTest(file: string) {
+    return /\.(test|spec)\.tsx?$/.test(file);
+  }
+
+  //? A lib's facets are public API for every workspace that installs it, so an export no app here calls is not dead.
+  static #isFacetSource(file: string) {
+    const segments = file.split("/");
+    if (segments[0] !== "apps") return false;
+    return TestOnlyExportScanner.#facets.has(segments[2] ?? "") && !TestOnlyExportScanner.#isTest(file);
+  }
+
+  static #identifierLinesOf(sourceFile: ts.SourceFile) {
+    const lines = new Map<string, number>();
+    const visit = (node: ts.Node) => {
+      if (ts.isIdentifier(node) && !lines.has(node.text))
+        lines.set(node.text, sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1);
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return lines;
+  }
+
+  static #exportedDeclarationsOf(sourceFile: ts.SourceFile): ExportedDeclaration[] {
+    return sourceFile.statements.flatMap((statement) => {
+      if (!TestOnlyExportScanner.#isNamedExport(statement)) return [];
+      return TestOnlyExportScanner.#declaredNamesOf(statement).map((identifier) => ({
+        name: identifier.text,
+        line: sourceFile.getLineAndCharacterOfPosition(identifier.getStart(sourceFile)).line + 1,
+        statement,
+      }));
+    });
+  }
+
+  static #isNamedExport(statement: ts.Statement) {
+    if (!ts.canHaveModifiers(statement)) return false;
+    const modifiers = ts.getModifiers(statement) ?? [];
+    return (
+      modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) &&
+      !modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword)
+    );
+  }
+
+  static #declaredNamesOf(statement: ts.Statement): ts.Identifier[] {
+    if (ts.isVariableStatement(statement))
+      return statement.declarationList.declarations
+        .map((declaration) => declaration.name)
+        .filter((name): name is ts.Identifier => ts.isIdentifier(name));
+    if (
+      ts.isFunctionDeclaration(statement) ||
+      ts.isClassDeclaration(statement) ||
+      ts.isInterfaceDeclaration(statement) ||
+      ts.isTypeAliasDeclaration(statement) ||
+      ts.isEnumDeclaration(statement)
+    )
+      return statement.name ? [statement.name] : [];
+    return [];
+  }
+
+  static #isUsedInFile(sourceFile: ts.SourceFile, name: string, declarations: ExportedDeclaration[]) {
+    const ownStatements = new Set(declarations.filter((entry) => entry.name === name).map((entry) => entry.statement));
+    let used = false;
+    const visit = (node: ts.Node) => {
+      if (used || ownStatements.has(node as ts.Statement)) return;
+      if (ts.isIdentifier(node) && node.text === name) used = true;
+      else ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return used;
+  }
+}

package/typeChecker.ts

@@ -13,6 +13,16 @@ export interface ProjectTypecheckResult {
   message: string;
 }
 
+export interface TypecheckRecord {
+  /** Relative to the workspace root, `/`-separated; `null` for a diagnostic tied to no file. */
+  file: string | null;
+  line: number;
+  col: number;
+  code: string;
+  severity: "error" | "warning";
+  message: string;
+}
+
 export class TypeChecker {
   readonly configPath: string;
   readonly configFile: { config?: any; error?: ts.Diagnostic };
@@ -198,6 +208,28 @@ export class TypeChecker {
     return parsedConfig;
   }
 
+  static toRecords(diagnostics: ts.Diagnostic[], root: string): TypecheckRecord[] {
+    return diagnostics
+      .filter(
+        (diagnostic) =>
+          diagnostic.category === ts.DiagnosticCategory.Error || diagnostic.category === ts.DiagnosticCategory.Warning,
+      )
+      .map((diagnostic) => {
+        const position =
+          diagnostic.file && diagnostic.start !== undefined
+            ? diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start)
+            : null;
+        return {
+          file: diagnostic.file ? path.relative(root, diagnostic.file.fileName).split(path.sep).join("/") : null,
+          line: position ? position.line + 1 : 0,
+          col: position ? position.character + 1 : 0,
+          code: `TS${diagnostic.code}`,
+          severity: diagnostic.category === ts.DiagnosticCategory.Error ? "error" : "warning",
+          message: ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"),
+        };
+      });
+  }
+
   static formatDiagnosticMessages(diagnostics: ts.Diagnostic[]): string {
     return ts.formatDiagnosticsWithColorAndContext(diagnostics, {
       getCanonicalFileName: (fileName) => fileName,

package/typecheck/projectTypecheck.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import path from "node:path";
 import { tempDirs, writeText as write } from "../testHelpers";
 import { ProjectTypecheck } from "./projectTypecheck";
+import { TypecheckFailure } from "./typecheckFailure";
 
 const makeTempRoot = tempDirs("akan-devkit-project-typecheck-");
 
@@ -29,4 +30,21 @@ describe("ProjectTypecheck", () => {
     expect((error as Error).message).toContain("lib/user/user.signal.test.ts");
     expect((error as Error).message).not.toContain("old.test.ts");
   }, 60_000);
+
+  test("hands back one record per diagnostic when asked for records", async () => {
+    const { root, dir } = await project();
+    const error = await new ProjectTypecheck(dir, root, { ...process.env })
+      .run(["../../server.ts"], { tests: true, report: "records" })
+      .catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(TypecheckFailure);
+    const [record, ...rest] = (error as TypecheckFailure).records;
+    expect(rest).toEqual([]);
+    expect(record).toMatchObject({
+      file: "libs/demo/lib/user/user.signal.test.ts",
+      line: 1,
+      col: 14,
+      code: "TS2322",
+      severity: "error",
+    });
+  }, 60_000);
 });

package/typecheck/projectTypecheck.ts

@@ -1,11 +1,15 @@
 import { mkdir, rm } from "node:fs/promises";
 import path from "node:path";
+import type { TypecheckRecord } from "../typeChecker";
+import { TypecheckFailure } from "./typecheckFailure";
 
 export interface ProjectTypecheckOptions {
   clean?: boolean;
   incremental?: boolean;
   /** The project's own `*.test.ts` / `*.spec.ts` as well. */
   tests?: boolean;
+  /** `records` fails with a `TypecheckFailure` carrying one record per diagnostic instead of the printed report. */
+  report?: "pretty" | "records";
 }
 
 //* tsc checks what the entries import, and nothing imports a test, so a test is checked only when it is included by
@@ -25,7 +29,10 @@ export class ProjectTypecheck {
   }
 
   /** `entries`: relative to the typecheck folder (`../../server.ts`). */
-  async run(entries: string[], { clean = false, incremental = true, tests = false }: ProjectTypecheckOptions = {}) {
+  async run(
+    entries: string[],
+    { clean = false, incremental = true, tests = false, report = "pretty" }: ProjectTypecheckOptions = {},
+  ) {
     const name = tests ? "tsconfig.tests" : "tsconfig";
     await mkdir(this.typecheckDir, { recursive: true });
     const tsconfig = {
@@ -38,14 +45,19 @@ export class ProjectTypecheck {
     const tsconfigPath = path.join(this.typecheckDir, `${name}.json`);
     await Bun.write(tsconfigPath, `${JSON.stringify(tsconfig, null, 2)}\n`);
     if (clean) await rm(path.join(this.typecheckDir, `${name}.tsbuildinfo`), { force: true });
-    await this.#check(tsconfigPath);
+    await this.check(tsconfigPath, report);
     return tsconfigPath;
   }
 
-  async #check(tsconfigPath: string) {
+  async check(tsconfigPath: string, report: "pretty" | "records" = "pretty") {
     const proc = Bun.spawn([process.execPath, await ProjectTypecheck.workerEntry(this.workspaceRoot)], {
       cwd: this.workspaceRoot,
-      env: { ...this.env, AKAN_COMMAND_TYPE: "typecheck", AKAN_TYPECHECK_TSCONFIG: tsconfigPath },
+      env: {
+        ...this.env,
+        AKAN_COMMAND_TYPE: "typecheck",
+        AKAN_TYPECHECK_TSCONFIG: tsconfigPath,
+        ...(report === "records" ? { AKAN_TYPECHECK_FORMAT: "json", AKAN_TYPECHECK_ROOT: this.workspaceRoot } : {}),
+      },
       stdout: "pipe",
       stderr: "pipe",
     });
@@ -54,7 +66,19 @@ export class ProjectTypecheck {
       new Response(proc.stderr).text(),
       proc.exited,
     ]);
-    if (exitCode !== 0) throw new Error((stderr || stdout).trim() || `Typecheck failed with exit code ${exitCode}`);
+    if (exitCode === 0) return;
+    const records = report === "records" ? ProjectTypecheck.#parseRecords(stdout) : null;
+    if (records?.length) throw new TypecheckFailure(records);
+    throw new Error((stderr || stdout).trim() || `Typecheck failed with exit code ${exitCode}`);
+  }
+
+  static #parseRecords(stdout: string): TypecheckRecord[] | null {
+    try {
+      const parsed: unknown = JSON.parse(stdout);
+      return Array.isArray(parsed) ? (parsed as TypecheckRecord[]) : null;
+    } catch {
+      return null;
+    }
   }
 
   //? The workspace's own devkit first, then an installed one, then the entry a bundle puts beside its chunks.

package/typecheck/typecheck.proc.ts

@@ -24,6 +24,12 @@ try {
   const configPath = process.env.AKAN_TYPECHECK_TSCONFIG;
   if (!configPath) throw new Error("AKAN_TYPECHECK_TSCONFIG is required");
   const result = TypeChecker.checkProject(configPath);
+  if (process.env.AKAN_TYPECHECK_FORMAT === "json") {
+    //? Not process.cwd(): that is the realpath (/private/var on macOS) while TypeScript keeps the spelling it was given.
+    const root = process.env.AKAN_TYPECHECK_ROOT ?? process.cwd();
+    process.stdout.write(JSON.stringify(TypeChecker.toRecords(result.errors, root)));
+    process.exit(result.errors.length > 0 ? 1 : 0);
+  }
   if (result.errors.length > 0) {
     console.error(result.message);
     process.exit(1);

package/typecheck/typecheckFailure.ts

@@ -0,0 +1,13 @@
+import type { TypecheckRecord } from "../typeChecker";
+
+export class TypecheckFailure extends Error {
+  constructor(readonly records: TypecheckRecord[]) {
+    super(
+      records
+        .slice(0, 20)
+        .map((record) => `${record.file ?? "-"}:${record.line}:${record.col} ${record.code} ${record.message}`)
+        .join("\n") || "Typecheck failed",
+    );
+    this.name = "TypecheckFailure";
+  }
+}

package/types.ts

@@ -12,6 +12,7 @@ export interface PackageJson {
   optionalDependencies?: Record<string, string>;
   trustedDependencies?: string[];
   overrides?: Record<string, string>;
+  resolutions?: Record<string, string>;
   engines?: Record<string, string>;
   exports?: Record<string, string | Record<string, string>>;
   bun?: {

package/workflow/artifacts.ts

@@ -1,5 +1,6 @@
 import { capitalize } from "akanjs/common";
 import type { Workspace } from "../commandDecorators";
+import { InteractionScaffold } from "./interactionScaffold";
 import type {
   GeneratedSyncState,
   PrimitiveChangedFile,
@@ -156,11 +157,15 @@ export const workflowPathsForPlan = (plan: WorkflowPlan) => {
   const app = planInputString(plan, "app");
   const module = planInputString(plan, "module");
   const moduleClass = module ? capitalize(module) : "<Module>";
+  const rawInteraction = planInputString(plan, "interaction");
+  const interaction = rawInteraction ? (InteractionScaffold.nameOf(rawInteraction) ?? rawInteraction) : null;
   return plan.predictedChanges.map((change) =>
     change.target
       .replace(/^\*\//, app ? `apps/${app}/` : "")
       .replaceAll("<module>", module || "<module>")
-      .replaceAll("<Module>", moduleClass),
+      .replaceAll("<Module>", moduleClass)
+      .replaceAll("<interaction>", interaction || "<interaction>")
+      .replaceAll("<Interaction>", interaction ? capitalize(interaction) : "<Interaction>"),
   );
 };
 
@@ -277,6 +282,15 @@ const statusForValidationKind = (
   return matching.some((command) => command.status === "failed") ? "failed" : "passed";
 };
 
+//? `akan verify` syncs first and names a failed sync in its header line (`sync 1 error`), so one run answers both.
+const generatedSyncStatus = (commands: readonly WorkflowValidationCommandResult[]): WorkflowValidationStatus => {
+  const sync = statusForValidationKind(commands, "sync");
+  const verify = commands.filter((command) => command.kind === "verify");
+  if (sync !== "unknown" || verify.length === 0) return sync;
+  const syncFailed = verify.some((command) => /^verify fail · .*\bsync \d+ errors?\b/m.test(command.stdout ?? ""));
+  return syncFailed ? "failed" : "passed";
+};
+
 const statusForCommands = (commands: readonly WorkflowValidationCommandResult[]): WorkflowValidationStatus => {
   if (commands.length === 0) return "unknown";
   return commandStatus(commands) === "failed" ? "failed" : "passed";
@@ -433,7 +447,7 @@ const createValidationStatuses = (
     overallStatus,
     summary: {
       sourceChange: sourceStatus,
-      generatedSync: statusForValidationKind(commands, "sync"),
+      generatedSync: generatedSyncStatus(commands),
       validationCommands: validationCommandsStatus,
       baseline: baselineStatus,
       workspaceConfig: statusForScope(commands, diagnostics, scopes, "workspace-config"),

package/workflow/executor.ts

@@ -312,7 +312,7 @@ const checkAddFieldStructure = async (workspace: Workspace, plan: WorkflowPlan):
   return { diagnostics, postApplyChecks };
 };
 
-const resolveWorkflowSys = async (workspace: Workspace, target: string | null): Promise<Sys | null> => {
+export const resolveWorkflowSys = async (workspace: Workspace, target: string | null): Promise<Sys | null> => {
   if (!target) return null;
   const [apps, libs] = await workspace.getSyss();
   if (apps.includes(target)) return AppExecutor.from(workspace, target);
@@ -375,10 +375,10 @@ const addMutationActionSurfaceInspection = (plan: WorkflowPlan): WorkflowStepRes
   const moduleClassName = moduleComponentName(module);
   return surfaceReview(plan, {
     code: "add-mutation-action-surface-review",
-    target: `*/${moduleSourcePaths(module).store}`,
-    action: `Name the endpoint's guards and add its dictionary .endpoint() entry with a .desc(). After sync, fetch.${mutation} exists; write a store action only for a toast, an optimistic update, or a multi-field write, and put the control that calls it in ${moduleClassName}.Util.tsx.`,
-    message: `Workflow apply does not write store or UI code for ${module}.${mutation}; review whether a screen should call it.`,
-    reason: "Review action surface guidance before manually editing store or UI files.",
+    target: `*/${moduleSourcePaths(module).util}`,
+    action: `Fill the ${moduleClassName} chain method (validate, mutate, return this) and replace its transition comment. After sync, call st.do.${mutation}(id) from the control in ${moduleClassName}.Util.tsx; a second write that must land with it is another with/after entry, never a second fetch in the store action.`,
+    message: `Workflow apply does not write UI code for ${module}.${mutation}; review which screen calls it.`,
+    reason: "Review action surface guidance before manually editing UI files.",
   });
 };
 
@@ -404,6 +404,7 @@ export const createWorkflowStepRegistry = ({
   addEnumField,
   addMutation,
   addSlice,
+  createInteraction,
 }: WorkflowPrimitiveOperations): WorkflowStepRegistry => {
   const inspect = async () => undefined;
   const commandOnly = async () => undefined;
@@ -484,17 +485,31 @@ export const createWorkflowStepRegistry = ({
       ),
     [workflowStepKey("add-enum-field", "update-dictionary")]: inspect,
     [workflowStepKey("add-enum-field", "update-option")]: inspect,
-    [workflowStepKey("add-mutation", "update-service")]: async (_step, plan) =>
+    [workflowStepKey("add-mutation", "update-document")]: async (_step, plan) =>
       primitiveReportToWorkflowStepResult(
         await addMutation({
           app: workflowStringInput(plan.inputs.app),
           module: workflowStringInput(plan.inputs.module),
           mutation: workflowStringInput(plan.inputs.mutation),
+          guards: workflowStringArrayInput(plan.inputs.guard),
+          withCalls: workflowStringArrayInput(plan.inputs.with),
+          afterCalls: workflowStringArrayInput(plan.inputs.after),
         }),
       ),
+    [workflowStepKey("add-mutation", "update-service")]: inspect,
     [workflowStepKey("add-mutation", "update-signal")]: inspect,
-    [workflowStepKey("add-mutation", "update-action-surfaces")]: async (_step, plan) =>
+    [workflowStepKey("add-mutation", "update-store")]: inspect,
+    [workflowStepKey("add-mutation", "update-dictionary")]: inspect,
+    [workflowStepKey("add-mutation", "add-signal-test")]: inspect,
+    [workflowStepKey("add-mutation", "connect-action-ui")]: async (_step, plan) =>
       addMutationActionSurfaceInspection(plan),
+    [workflowStepKey("create-interaction", "create-interaction")]: async (_step, plan) =>
+      primitiveReportToWorkflowStepResult(
+        await createInteraction({
+          app: workflowStringInput(plan.inputs.app),
+          interaction: workflowStringInput(plan.inputs.interaction),
+        }),
+      ),
     [workflowStepKey("add-slice", "update-service-query")]: async (_step, plan) =>
       primitiveReportToWorkflowStepResult(
         await addSlice({

package/workflow/guardCatalog.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { createTempApp, tempRoots, writeJson, writeText } from "../testHelpers";
+import { GuardCatalog } from "./guardCatalog";
+
+const track = tempRoots();
+
+const guardFile = (names: string[]) =>
+  names.map((name) => `export class ${name} implements Guard {\n  canPass() {\n    return true;\n  }\n}\n`).join("\n");
+
+const createAppWithLibs = async () => {
+  const temp = track(await createTempApp("demo"));
+  const lib = (name: string, files: Record<string, string>) =>
+    Promise.all([
+      writeText(path.join(temp.root, "libs", name, "akan.config.ts"), "export default {};\n"),
+      ...Object.entries(files).map(([file, content]) => writeText(path.join(temp.root, "libs", name, file), content)),
+    ]);
+  await lib("shared", {
+    "srvkit/guards.ts": guardFile(["Admin", "User"]),
+    "srvkit/internalArgs.ts": "export class Self implements InternalArg {}\n",
+    "srvkit/guards.signal.test.ts": guardFile(["TestOnly"]),
+    "akan.lib.json": JSON.stringify({ libDeps: ["util"] }),
+  });
+  await lib("util", { "srvkit/guards.ts": guardFile(["Machine"]) });
+  await lib("other", { "srvkit/guards.ts": guardFile(["Elsewhere"]) });
+  await writeText(path.join(temp.root, "apps/demo/srvkit/guards.ts"), guardFile(["LocalOnly"]));
+  return temp;
+};
+
+describe("GuardCatalog", () => {
+  test("reads the target's srvkit, the libs it reaches, and the framework's Public", async () => {
+    const { root, app } = await createAppWithLibs();
+    await writeJson(path.join(root, "apps/demo/akan.app.json"), { libDeps: ["shared"] });
+
+    const catalog = await GuardCatalog.load(app);
+
+    expect(catalog.reachedLibs).toEqual(["shared", "util"]);
+    expect(catalog.names.sort()).toEqual(["Admin", "LocalOnly", "Machine", "Public", "User"]);
+    expect(catalog.resolve("LocalOnly").specifier).toBe("@apps/demo/srvkit");
+    expect(catalog.resolve("Admin").specifier).toBe("@libs/shared/srvkit");
+    expect(catalog.resolve("Public").specifier).toBe("akanjs/signal");
+    expect(catalog.resolve("Elsewhere").specifier).toBeNull();
+  });
+
+  test("falls back to every workspace lib before a sync has recorded the target's deps", async () => {
+    const { app } = await createAppWithLibs();
+
+    expect((await GuardCatalog.load(app)).resolve("Elsewhere").specifier).toBe("@libs/other/srvkit");
+  });
+
+  test("names the acting user only when the guard guarantees one and its internal arg exists", async () => {
+    const { app } = await createAppWithLibs();
+    const catalog = await GuardCatalog.load(app);
+
+    expect(catalog.actingUserOf(["User"])).toMatchObject({ argName: "Self", specifier: "@libs/shared/srvkit" });
+    expect(catalog.actingUserOf(["Admin"])).toBeNull();
+    expect(catalog.actingUserOf(["SignedIn"])).toBeNull();
+  });
+});