@akanjs/devkit 3.1.2-rc.3 → 3.2.0-rc.0

package/commandDecorators/commandDecorators.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 import path from "node:path";
-import { AppExecutor, LibExecutor, WorkspaceExecutor } from "../executors";
+import { AppExecutor, LibExecutor, PkgExecutor, WorkspaceExecutor } from "../executors";
 import { makeCliTempWorkspace, tempRoots, writeText } from "../testHelpers";
 import {
   App,
@@ -15,7 +15,13 @@ import {
   SysOrOnlyApp,
   Workspace,
 } from "./argMeta";
-import { getAppsArgumentValue, getArgumentValue, getInternalArgumentValue, getOptionValue } from "./command";
+import {
+  getAppsArgumentValue,
+  getArgumentValue,
+  getInternalArgumentValue,
+  getOptionValue,
+  rerunCommandOf,
+} from "./command";
 import { command } from "./commandBuilder";
 import {
   assertUniqueDependencies,
@@ -499,6 +505,129 @@ describe("a Sys that defaults to the only app", () => {
     expect(app instanceof AppExecutor ? app.name : null).toBe("admin");
     expect(asked).toEqual([["web", "admin", "util"]]);
   });
+
+  test("a terminal is still asked when the workspace holds a single app or lib", async () => {
+    setTTY(true);
+    answer = "web";
+    const workspace = workspaceWith([]);
+    workspace.getExecs = async () => [["web"], [], []];
+    const app = await getInternalArgumentValue(sysMetaOf("sync"), undefined, workspace);
+    expect(app instanceof AppExecutor ? app.name : null).toBe("web");
+    expect(asked).toEqual([["web"]]);
+  });
+
+  test("without a terminal, an Exec takes the workspace's only app, lib or pkg", async () => {
+    setTTY(undefined);
+    const workspace = workspaceWith([]);
+    workspace.getExecs = async () => [[], [], ["tools"]];
+    const pkg = await getInternalArgumentValue({ key: "", idx: 0, type: "Exec" }, undefined, workspace);
+    expect(pkg instanceof PkgExecutor ? pkg.name : null).toBe("tools");
+    expect(asked).toEqual([]);
+  });
+
+  test("without a terminal, the only lib, pkg or module is not taken, as a command may be removing it", async () => {
+    setTTY(undefined);
+    const workspace = workspaceWith([]);
+    workspace.getExecs = async () => [[], ["util"], []];
+    workspace.getPkgs = async () => ["tools"];
+    const rerunOf = (name: string) => rerunCommandOf([name], [undefined], 0);
+    await expect(
+      getInternalArgumentValue({ key: "", idx: 0, type: "Lib" }, undefined, workspace, rerunOf("remove-library")),
+    ).rejects.toThrow("so rerun it as `akan remove-library <lib>` (choices: util).");
+    await expect(
+      getInternalArgumentValue({ key: "", idx: 0, type: "Pkg" }, undefined, workspace, rerunOf("remove-package")),
+    ).rejects.toThrow("so rerun it as `akan remove-package <pkg>` (choices: tools).");
+    expect(asked).toEqual([]);
+  });
+
+  test("without a terminal, a named target the workspace lacks is refused, not swapped for the only one", async () => {
+    setTTY(undefined);
+    const workspace = workspaceWith([]);
+    workspace.getExecs = async () => [["web"], [], []];
+    await expect(
+      getInternalArgumentValue(sysMetaOf("sync"), "webb", workspace, rerunCommandOf(["sync", "webb"], ["webb"], 0)),
+    ).rejects.toThrow(
+      "Unknown app or lib 'webb': stdin is not a terminal to prompt on, so rerun it as `akan sync <app-or-lib>` (choices: web).",
+    );
+    expect(asked).toEqual([]);
+  });
+});
+
+describe("the line a refused target is rerun with", () => {
+  test("puts the target in its operand slot, after the operands before it, keeping every option", () => {
+    expect(rerunCommandOf(["test", "--write", "false"], [undefined, undefined], 0)("<t>")).toBe(
+      "akan test <t> --write false",
+    );
+    expect(rerunCommandOf(["create-module", "--page", "true", "photo"], ["photo", undefined], 1)("web")).toBe(
+      "akan create-module --page true photo web",
+    );
+    expect(rerunCommandOf(["build", "--env", "it's main"], [undefined], 0)("web")).toBe(
+      "akan build web --env 'it'\\''s main'",
+    );
+  });
+
+  test("takes the place of a target that was given but is not in the workspace", () => {
+    expect(rerunCommandOf(["sync", "nope"], ["nope"], 0)("<app-or-lib>")).toBe("akan sync <app-or-lib>");
+  });
+});
+
+describe("a target left out where no terminal can ask for it", () => {
+  const track = tempRoots();
+  const run = async (apps: string[]) => {
+    const { root } = track(await makeCliTempWorkspace());
+    await writeText(path.join(root, "package.json"), '{ "name": "repo", "version": "1.0.0" }\n');
+    await writeText(path.join(root, "tsconfig.json"), "{}\n");
+    for (const app of apps) await writeText(path.join(root, "apps", app, "akan.config.ts"), "export default {};\n");
+    const entry = path.join(root, "cli.ts");
+    await writeText(
+      entry,
+      [
+        `import { command, runCommands, Sys } from ${JSON.stringify(path.join(import.meta.dir, "index.ts"))};`,
+        'class ThingCommand extends command("thing", ({ public: target }) => ({',
+        '  createThing: target({ desc: "creates a thing" })',
+        '    .arg("thing", String, { desc: "name of the thing" })',
+        "    .with(Sys)",
+        '    .option("force", Boolean, { default: false })',
+        "    .exec(async function (thing, sys, force) {",
+        '      process.stdout.write(thing + " in " + sys.name + ", force " + force + "\\n");',
+        "    }),",
+        "})) {}",
+        "await runCommands(ThingCommand);",
+        "",
+      ].join("\n"),
+    );
+    const proc = Bun.spawn(["bun", entry, "create-thing", "photo", "--force"], {
+      cwd: root,
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    return { stdout, stderr, code };
+  };
+
+  test("runs on the workspace's only app or lib, naming it on stderr", async () => {
+    const ran = await run(["web"]);
+    expect(ran.code).toBe(0);
+    expect(ran.stdout).toContain("photo in web, force true\n");
+    expect(ran.stderr).toContain(
+      "No app or lib named, so this runs on 'web', the only one in this workspace: akan create-thing photo web --force",
+    );
+  }, 30_000);
+
+  test("exits at once with the choices and the line to rerun when there are several", async () => {
+    const refused = await run(["web", "admin"]);
+    expect(refused.code).toBe(1);
+    expect(refused.stdout).toContain(
+      "Missing app or lib: stdin is not a terminal to prompt on, so rerun it as `akan create-thing photo <app-or-lib> --force`",
+    );
+    expect(refused.stdout).toMatch(/\(choices: (web, admin|admin, web)\)\./);
+    expect(refused.stdout).not.toContain("photo in");
+  }, 30_000);
 });
 
 describe("the exit code of a command that failed", () => {

package/declarationReader.ts

@@ -0,0 +1,211 @@
+import path from "node:path";
+import ts from "typescript";
+
+export interface MemberFilter {
+  only?: string[];
+  omit?: string[];
+  prefix?: string;
+}
+
+const nodeFlags =
+  ts.NodeBuilderFlags.NoTruncation |
+  ts.NodeBuilderFlags.UseAliasDefinedOutsideCurrentScope |
+  ts.NodeBuilderFlags.OmitParameterModifiers;
+const typeFlags = ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope;
+
+export class DeclarationReader {
+  static readonly #printer = ts.createPrinter({ removeComments: true, omitTrailingSemicolon: true });
+  readonly #dir: string;
+  readonly #program: ts.Program;
+  readonly #checker: ts.TypeChecker;
+  readonly #entries: Map<string, string>;
+  readonly #scratch: ts.SourceFile;
+
+  constructor(akanjsDir: string) {
+    this.#dir = akanjsDir;
+    const configPath = path.join(akanjsDir, "tsconfig.json");
+    const config = ts.readConfigFile(configPath, ts.sys.readFile);
+    const parsed = ts.parseJsonConfigFileContent(config.config, ts.sys, akanjsDir, undefined, configPath);
+    this.#entries = DeclarationReader.#entryFiles(akanjsDir);
+    this.#program = ts.createProgram({
+      rootNames: [...new Set(this.#entries.values())],
+      options: { ...parsed.options, noEmit: true },
+    });
+    this.#checker = this.#program.getTypeChecker();
+    this.#scratch = ts.createSourceFile("reference.ts", "", ts.ScriptTarget.Latest);
+  }
+
+  static #entryFiles(akanjsDir: string) {
+    const manifest = JSON.parse(ts.sys.readFile(path.join(akanjsDir, "package.json")) ?? "{}") as {
+      exports: Record<string, unknown>;
+    };
+    const entries = new Map<string, string>();
+    for (const [key, value] of Object.entries(manifest.exports)) {
+      const target = typeof value === "string" ? value : (value as { types?: string; import?: string }).types;
+      if (key.includes("*") || typeof target !== "string" || !/\.tsx?$/.test(target)) continue;
+      entries.set(key === "." ? "akanjs" : `akanjs/${key.slice(2)}`, path.join(akanjsDir, target));
+    }
+    return entries;
+  }
+
+  exported(from: string, name: string): ts.Symbol {
+    const file = this.#entries.get(from);
+    const source = file ? this.#program.getSourceFile(file) : undefined;
+    const module = source ? this.#checker.getSymbolAtLocation(source) : undefined;
+    const symbol = module ? this.#checker.getExportsOfModule(module).find((each) => each.name === name) : undefined;
+    if (!symbol) throw new Error(`${name} is not exported from ${from}: update the API reference manifest`);
+    return symbol.flags & ts.SymbolFlags.Alias ? this.#checker.getAliasedSymbol(symbol) : symbol;
+  }
+
+  declared(file: string, name: string): ts.Symbol {
+    const source = this.#program.getSourceFile(path.join(this.#dir, file));
+    const statement = source?.statements.find(
+      (each) =>
+        (ts.isClassDeclaration(each) || ts.isInterfaceDeclaration(each) || ts.isTypeAliasDeclaration(each)) &&
+        each.name?.text === name,
+    ) as ts.ClassDeclaration | ts.InterfaceDeclaration | ts.TypeAliasDeclaration | undefined;
+    const symbol = statement?.name ? this.#checker.getSymbolAtLocation(statement.name) : undefined;
+    if (!symbol) throw new Error(`${name} is not declared in ${file}: update the API reference manifest`);
+    return symbol;
+  }
+
+  declaredType(symbol: ts.Symbol): ts.Type {
+    return this.#checker.getDeclaredTypeOfSymbol(symbol);
+  }
+
+  instanceType(symbol: ts.Symbol): ts.Type {
+    if (symbol.flags & (ts.SymbolFlags.Class | ts.SymbolFlags.Interface | ts.SymbolFlags.TypeAlias))
+      return this.declaredType(symbol);
+    const type = this.#checker.getTypeOfSymbol(symbol);
+    const [signature] = type.getCallSignatures();
+    return signature ? signature.getReturnType() : type;
+  }
+
+  declarationText(symbol: ts.Symbol): string {
+    const [declaration] = symbol.declarations ?? [];
+    if (!declaration) throw new Error(`${symbol.name} has no declaration`);
+    return DeclarationReader.#print(declaration, declaration.getSourceFile()).replace(/^export /, "");
+  }
+
+  signatures(symbol: ts.Symbol, name: string): string[] {
+    const type = this.#checker.getTypeOfSymbol(symbol);
+    const signatures = type.getCallSignatures();
+    if (signatures.length === 0) throw new Error(`${name} is not callable`);
+    return signatures.map((signature) => `${name}${this.#checker.signatureToString(signature, undefined, typeFlags)}`);
+  }
+
+  props(type: ts.Type, omit: string[] = []): string[] {
+    const lines: string[] = [];
+    const properties = this.#checker.getPropertiesOfType(type);
+    DeclarationReader.#assertNamed(properties, omit);
+    for (const property of properties) {
+      if (omit.includes(property.name) || DeclarationReader.#isInternalName(property.name)) continue;
+      const [declaration] = property.declarations ?? [];
+      if (declaration && !this.#isOwn(declaration)) continue;
+      const optional = property.flags & ts.SymbolFlags.Optional ? "?" : "";
+      const propertyType = declaration
+        ? this.#checker.getTypeOfSymbolAtLocation(property, declaration)
+        : this.#checker.getTypeOfSymbol(property);
+      const shown = this.#checker.typeToString(
+        optional ? this.#checker.getNonNullableType(propertyType) : propertyType,
+        undefined,
+        typeFlags,
+      );
+      const doc = this.#firstSentence(property);
+      if (doc) lines.push(`/** ${doc} */`);
+      lines.push(`${property.name}${optional}: ${shown};`);
+    }
+    return lines;
+  }
+
+  members(type: ts.Type, { only, omit = [], prefix = "." }: MemberFilter): [string, string][] {
+    const properties = this.#checker.getPropertiesOfType(type);
+    DeclarationReader.#assertNamed(properties, [...(only ?? []), ...omit]);
+    const found: [string, string][] = [];
+    for (const property of properties) {
+      const name = property.name;
+      if ((only && !only.includes(name)) || omit.includes(name) || DeclarationReader.#isInternalName(name)) continue;
+      const [declaration] = property.declarations ?? [];
+      if (!declaration || DeclarationReader.#isHidden(declaration)) continue;
+      const signatures = this.#checker.getTypeOfSymbolAtLocation(property, declaration).getCallSignatures();
+      for (const signature of signatures)
+        found.push([name, `${prefix}${name}${this.#withoutReturn(signature, declaration)}`]);
+    }
+    return found;
+  }
+
+  static #assertNamed(properties: ts.Symbol[], names: string[]) {
+    for (const name of names)
+      if (!properties.some((property) => property.name === name))
+        throw new Error(`${name} is not a member any more: update the API reference manifest`);
+  }
+
+  static #isInternalName(name: string) {
+    return name.startsWith("_") || name.startsWith("#");
+  }
+
+  #isOwn(declaration: ts.Declaration) {
+    return !path.relative(this.#dir, declaration.getSourceFile().fileName).startsWith("..");
+  }
+
+  static #isHidden(declaration: ts.Declaration) {
+    const flags = ts.getCombinedModifierFlags(declaration);
+    return (
+      (flags & (ts.ModifierFlags.Private | ts.ModifierFlags.Protected | ts.ModifierFlags.Static)) !== 0 ||
+      (ts.isPropertyDeclaration(declaration) && !declaration.type && !declaration.initializer) ||
+      ts.isConstructorDeclaration(declaration)
+    );
+  }
+
+  #withoutReturn(signature: ts.Signature, enclosing: ts.Declaration) {
+    const node = this.#checker.signatureToSignatureDeclaration(
+      signature,
+      ts.SyntaxKind.MethodSignature,
+      enclosing,
+      nodeFlags,
+    ) as ts.MethodSignature | undefined;
+    if (!node) throw new Error(`${this.#checker.signatureToString(signature)} cannot be printed`);
+    const typeParameters = node.typeParameters?.filter((each) => !each.name.text.startsWith("_"));
+    const parameters = node.parameters.map((parameter) =>
+      parameter.questionToken && parameter.type && ts.isUnionTypeNode(parameter.type)
+        ? ts.factory.updateParameterDeclaration(
+            parameter,
+            parameter.modifiers,
+            parameter.dotDotDotToken,
+            parameter.name,
+            parameter.questionToken,
+            DeclarationReader.#withoutUndefined(parameter.type),
+            parameter.initializer,
+          )
+        : parameter,
+    );
+    const stripped = ts.factory.createMethodSignature(
+      undefined,
+      "x",
+      undefined,
+      typeParameters?.length ? typeParameters : undefined,
+      parameters,
+      undefined,
+    );
+    return DeclarationReader.#print(stripped, this.#scratch)
+      .replace(/^x/, "")
+      .replace(/;$/, "")
+      .replaceAll(" & Record<never, never>", "");
+  }
+
+  static #print(node: ts.Node, source: ts.SourceFile) {
+    return DeclarationReader.#printer.printNode(ts.EmitHint.Unspecified, node, source).replace(/\s+/g, " ");
+  }
+
+  static #withoutUndefined(type: ts.UnionTypeNode): ts.TypeNode {
+    const kept = type.types.filter((each) => each.kind !== ts.SyntaxKind.UndefinedKeyword);
+    return kept.length === 1 ? kept[0] : ts.factory.createUnionTypeNode(kept);
+  }
+
+  #firstSentence(symbol: ts.Symbol) {
+    const text = ts.displayPartsToString(symbol.getDocumentationComment(this.#checker)).replace(/\s+/g, " ").trim();
+    if (!text) return "";
+    const end = text.search(/\.(\s|$)/);
+    return (end === -1 ? text : text.slice(0, end + 1)).replace(/\*\//g, "*\\/");
+  }
+}

package/executors.test.ts

@@ -304,8 +304,8 @@ describe("Executor filesystem helpers", () => {
 
     await exec.applyTemplate({ basePath: "app", template: "app", dict: { appName: "demo" }, options: { libs: [] } });
     const templateRoot = path.resolve(import.meta.dir, "../cli/templates/app/public");
-    await expect(readFile(path.join(root, "app/public/logo.png"))).resolves.toEqual(
-      await readFile(path.join(templateRoot, "logo.png")),
+    await expect(readFile(path.join(root, "app/public/apple-touch-icon.png"))).resolves.toEqual(
+      await readFile(path.join(templateRoot, "apple-touch-icon.png")),
     );
     await expect(readFile(path.join(root, "app/public/favicon.ico"))).resolves.toEqual(
       await readFile(path.join(templateRoot, "favicon.ico")),
@@ -315,22 +315,32 @@ describe("Executor filesystem helpers", () => {
   test("keeps a static file already there when overwrite is false, and reports it unwritten", async () => {
     const root = await makeTempRoot();
     const exec = new Executor("fixture", root);
-    await writeText(path.join(root, "app/public/logo.png"), "the app's own logo");
+    await writeText(path.join(root, "app/public/favicon.ico"), "the app's own icon");
 
     const applied = await exec.applyTemplate({
       basePath: "app/public",
-      template: "app/public/logo.png",
+      template: "app/public/favicon.ico",
       overwrite: false,
     });
 
-    expect(await readFile(path.join(root, "app/public/logo.png"), "utf8")).toBe("the app's own logo");
+    expect(await readFile(path.join(root, "app/public/favicon.ico"), "utf8")).toBe("the app's own icon");
     expect(applied).toEqual([
-      expect.objectContaining({ filePath: path.join(root, "app/public/logo.png"), written: false }),
+      expect.objectContaining({ filePath: path.join(root, "app/public/favicon.ico"), written: false }),
     ]);
   });
 });
 
 describe("Workspace and app executor environment contracts", () => {
+  const baseDevEnvKeys = [
+    "AKAN_PUBLIC_APP_NAME",
+    "AKAN_WORKSPACE_ROOT",
+    "AKAN_WORKSPACE_ID",
+    "AKAN_PUBLIC_REPO_NAME",
+    "AKAN_PUBLIC_SERVE_DOMAIN",
+    "AKAN_PUBLIC_ENV",
+    "PORT_OFFSET",
+  ];
+
   test("reads base development environment", () => {
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";
     process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
@@ -427,8 +437,7 @@ describe("Workspace and app executor environment contracts", () => {
         "",
       ].join("\n"),
     );
-    delete process.env.AKAN_PUBLIC_REPO_NAME;
-    delete process.env.AKAN_PUBLIC_SERVE_DOMAIN;
+    for (const key of baseDevEnvKeys) delete process.env[key];
 
     expect(WorkspaceExecutor.getBaseDevEnv(path.join(root, ".env"))).toEqual({
       appName: "file-app",
@@ -458,6 +467,7 @@ describe("Workspace and app executor environment contracts", () => {
         "",
       ].join("\r\n"),
     );
+    for (const key of baseDevEnvKeys) delete process.env[key];
 
     expect(WorkspaceExecutor.getBaseDevEnv(path.join(root, ".env"))).toEqual({
       appName: 'say \\"hi\\"\nagain',
@@ -471,6 +481,53 @@ describe("Workspace and app executor environment contracts", () => {
     });
   });
 
+  test("the shell outranks the workspace .env key by key, and a default stands in for what neither sets", async () => {
+    const root = await makeTempRoot();
+    await writeFile(
+      path.join(root, ".env"),
+      [
+        "AKAN_PUBLIC_ENV=local",
+        "AKAN_PUBLIC_REPO_NAME=file-repo",
+        "AKAN_PUBLIC_SERVE_DOMAIN=file.example.com",
+        "",
+      ].join("\n"),
+    );
+    for (const key of baseDevEnvKeys) delete process.env[key];
+    Object.assign(process.env, { AKAN_PUBLIC_ENV: "main", AKAN_PUBLIC_SERVE_DOMAIN: "shell.example.com" });
+
+    expect(WorkspaceExecutor.getBaseDevEnv(path.join(root, ".env"))).toMatchObject({
+      env: "main",
+      repoName: "file-repo",
+      serveDomain: "shell.example.com",
+      defaulted: [],
+    });
+
+    delete process.env.AKAN_PUBLIC_ENV;
+    await writeFile(path.join(root, ".env"), "AKAN_PUBLIC_ENV=local\n");
+    expect(WorkspaceExecutor.getBaseDevEnv(path.join(root, ".env"))).toMatchObject({
+      env: "local",
+      serveDomain: "shell.example.com",
+      defaulted: ["AKAN_PUBLIC_REPO_NAME"],
+    });
+  });
+
+  test("an empty export reads as unset, so the .env's value stands", async () => {
+    const root = await makeTempRoot();
+    await writeFile(
+      path.join(root, ".env"),
+      "AKAN_PUBLIC_ENV=main\nAKAN_PUBLIC_REPO_NAME=file-repo\nAKAN_PUBLIC_SERVE_DOMAIN=file.example.com\n",
+    );
+    for (const key of baseDevEnvKeys) delete process.env[key];
+    Object.assign(process.env, { AKAN_PUBLIC_ENV: "", AKAN_PUBLIC_REPO_NAME: "", AKAN_PUBLIC_SERVE_DOMAIN: "" });
+
+    expect(WorkspaceExecutor.getBaseDevEnv(path.join(root, ".env"))).toMatchObject({
+      env: "main",
+      repoName: "file-repo",
+      serveDomain: "file.example.com",
+      defaulted: [],
+    });
+  });
+
   test("builds app command environment and prepareCommand artifacts", async () => {
     const root = await makeTempRoot();
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";

package/executors.ts

@@ -156,7 +156,7 @@ const parseEnvValue = (value: string) => {
   return inner.replace(/\\(.)/g, (pair, char: string) => (char === "n" ? "\n" : char === "r" ? "\r" : pair));
 };
 
-const parseEnvFile = (envPath: string): Record<string, string> => {
+export const parseEnvFile = (envPath: string): Record<string, string> => {
   const env: Record<string, string> = {};
   const content = (() => {
     try {
@@ -683,13 +683,15 @@ export class WorkspaceExecutor extends Executor {
   } = {}) {
     return new WorkspaceExecutor({ workspaceRoot, repoName });
   }
-  /** The public env a native build was told to reproduce (`--public-env`): it outranks `.env`, which outranks the rest. */
+  /** The public env a native build was told to reproduce (`--public-env`): it outranks the shell, which outranks `.env`. */
   static publicEnvPin: Record<string, string> | null = null;
   static readonly localServeDomain = "localhost";
   static getBaseDevEnv(envPath?: string) {
     // Bun auto-loads .env, so we use process.env directly
     const sourceEnv = {
-      ...(envPath ? { ...process.env, ...parseEnvFile(envPath) } : process.env),
+      ...(envPath ? parseEnvFile(envPath) : {}),
+      //? An empty export reads as unset, unlike in dotenv, so it can't blank a key the .env sets.
+      ...Object.fromEntries(Object.entries(process.env).filter(([, value]) => value)),
       ...WorkspaceExecutor.publicEnvPin,
     };
 

package/frameworkGraph.test.ts

@@ -0,0 +1,121 @@
+import { 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 { FrameworkGraph } from "./frameworkGraph";
+
+const workspaceRoot = path.resolve(import.meta.dir, "../../..");
+//? The other end of these lies outside the source read here: @akanjs/native's desktop shell answers file and secret
+//? requests, AkanApp's child reports a boot error from a code string, and the browser tab sends `sync-navigation` and
+//? handles every HmrMessage in a script string. `ws.*` and HMR `ok` have no site.
+const unrecognised = [
+  "AkanIpcMessage ws.opened sender",
+  "AkanIpcMessage ws.opened handler",
+  "AkanIpcMessage ws.closed sender",
+  "AkanIpcMessage ws.closed handler",
+  "AkanIpcMessage file.resolve handler",
+  "AkanIpcMessage file.resolved sender",
+  "AkanIpcMessage secret.request handler",
+  "AkanIpcMessage secret.answer sender",
+  "AkanIpcMessage error sender",
+  "HmrMessage sync-navigation sender",
+  "HmrMessage ok sender",
+];
+const handledInBrowser = new Set(["HmrMessage"]);
+
+const withWorkspace = async (files: Record<string, string>, run: (root: string) => Promise<void>) => {
+  const root = await mkdtemp(path.join(tmpdir(), "akan-framework-"));
+  try {
+    for (const [file, text] of Object.entries(files)) {
+      await mkdir(path.dirname(path.join(root, file)), { recursive: true });
+      await writeFile(path.join(root, file), text);
+    }
+    await run(root);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+};
+
+const installed = (version: string) => ({
+  "node_modules/akanjs/package.json": JSON.stringify({
+    name: "akanjs",
+    version,
+    exports: { ".": "./index.ts", "./package.json": "./package.json" },
+  }),
+  "node_modules/akanjs/index.ts": `export * from "./base";\n`,
+  "node_modules/akanjs/base/scalar.ts": "export class Scalar {}\n",
+  "node_modules/akanjs/native/bridge.ts": `import { Native } from "../vendor/@akanjs/native/index";\nexport class Bridge {}\n`,
+  "node_modules/akanjs/vendor/@akanjs/native/index.ts": "export class Native {}\n",
+  "node_modules/akanjs/vendor/use-agentic/index.ts": "export class Agentic {}\n",
+  "node_modules/akanjs/types/base/index.ts": "export class Declared {}\n",
+});
+
+describe("FrameworkGraph", () => {
+  it(`keeps ${FrameworkGraph.architectureFile} current with the source it describes`, async () => {
+    const architecture = await FrameworkGraph.architecture(workspaceRoot);
+    expect(architecture).not.toBeNull();
+    if (!architecture) return;
+    const { map } = architecture;
+    expect(map.missing).toEqual([]);
+    expect(map.cycles).toEqual([]);
+    expect(architecture.unknownClasses).toEqual([]);
+    const unmatched = map.channels.flatMap(({ name, messages }) =>
+      messages.flatMap(({ type, senders, handlers }) => [
+        ...(senders.length ? [] : [`${name} ${type} sender`]),
+        ...(handlers.length || handledInBrowser.has(name) ? [] : [`${name} ${type} handler`]),
+      ]),
+    );
+    expect(unmatched).toEqual(unrecognised);
+    if (architecture.next !== architecture.current)
+      throw new Error(`${FrameworkGraph.architectureFile} is stale. Regenerate it: bun run akan sync-architecture`);
+  });
+
+  it("reads a consumer's installed akanjs without its bundled vendor and declaration folders", async () => {
+    await withWorkspace({ "package.json": "{}" }, async (root) => {
+      expect(await FrameworkGraph.build(root)).toBeNull();
+    });
+    await withWorkspace(installed("3.1.0"), async (root) => {
+      expect(await FrameworkGraph.packagesOf(root)).toEqual([
+        { name: "akanjs", root: "node_modules/akanjs", split: true },
+      ]);
+      const map = await FrameworkGraph.build(root);
+      expect(map?.facets.map(({ id, layer, classes }) => `${id}:${layer}:${classes.map(({ name }) => name)}`)).toEqual([
+        "akanjs/base:0:Scalar",
+        "akanjs/native:0:Bridge",
+      ]);
+      expect(await FrameworkGraph.architecture(root)).toBeNull();
+    });
+  });
+
+  it("rebuilds an installed map on a new version, and an in-repo one on a save under it", async () => {
+    await withWorkspace(installed("3.1.0"), async (root) => {
+      const first = await FrameworkGraph.cached(root);
+      FrameworkGraph.touched(root, [path.join(root, "node_modules/akanjs/base/scalar.ts")]);
+      expect(await FrameworkGraph.cached(root)).toBe(first);
+      await writeFile(path.join(root, "node_modules/akanjs/package.json"), JSON.stringify({ version: "3.1.1" }));
+      expect(await FrameworkGraph.cached(root)).not.toBe(first);
+    });
+    await withWorkspace({ "pkgs/akanjs/base/scalar.ts": "export class Scalar {}\n" }, async (root) => {
+      const first = await FrameworkGraph.cached(root);
+      FrameworkGraph.touched(root, [path.join(root, "apps/demo/page/_index.tsx")]);
+      expect(await FrameworkGraph.cached(root)).toBe(first);
+      FrameworkGraph.touched(root, [path.join(root, "pkgs/akanjs/base/scalar.ts")]);
+      expect(await FrameworkGraph.cached(root)).not.toBe(first);
+    });
+  });
+
+  it("reads a document checked out with CRLF line endings as current", async () => {
+    const files = {
+      "pkgs/akanjs/base/scalar.ts": "export class Scalar {}\n",
+      [FrameworkGraph.architectureFile]: "# A\n",
+    };
+    await withWorkspace(files, async (root) => {
+      const first = await FrameworkGraph.architecture(root);
+      if (!first) throw new Error("no architecture");
+      await writeFile(path.join(root, FrameworkGraph.architectureFile), first.next.replace(/\n/g, "\r\n"));
+      const second = await FrameworkGraph.architecture(root);
+      expect(second?.current).toBe(first.next);
+      expect(second?.next).toBe(first.next);
+    });
+  });
+});