@akanjs/devkit 3.0.0-beta.19 → 3.0.0-beta.20

package/abstractDoc.test.ts

@@ -1,29 +1,20 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
 import path from "node:path";
 import { AbstractDoc } from "./abstractDoc";
 import { AppExecutor, WorkspaceExecutor } from "./executors";
+import { tempDirs, writeText } from "./testHelpers";
 
-const tempRoots: string[] = [];
+const makeTempRoot = tempDirs("akan-abstract-doc-");
 
 const makeApp = async (files: Record<string, string>) => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-abstract-doc-"));
-  tempRoots.push(root);
+  const root = await makeTempRoot();
   const appName = "abstractDemo";
-  for (const [filePath, content] of Object.entries(files)) {
-    const absolutePath = path.join(root, "apps", appName, filePath);
-    await mkdir(path.dirname(absolutePath), { recursive: true });
-    await writeFile(absolutePath, content);
-  }
+  for (const [filePath, content] of Object.entries(files))
+    await writeText(path.join(root, "apps", appName, filePath), content);
   const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: "repo" });
   return AppExecutor.from(workspace, appName);
 };
 
-afterEach(async () => {
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
-
 describe("AbstractDoc.kindOf", () => {
   test("reads the module kind off the sys-relative path", () => {
     expect(AbstractDoc.kindOf("lib/user/user.abstract.md")).toBe("domain");

package/abstractDoc.ts

@@ -3,7 +3,6 @@ import type { SysExecutor } from "./executors";
 
 export type AbstractKind = "domain" | "service" | "scalar" | "other";
 
-/** One `*.abstract.md` file: the agent-facing summary a module carries next to its source. */
 export class AbstractDoc {
   static readonly suffix = ".abstract.md";
   /** `akan quality` warns above this. */
@@ -17,7 +16,6 @@ export class AbstractDoc {
   static lineCountOf(content: string) {
     return content.split(/\r?\n/).length;
   }
-  /** Module kind read off the sys-relative path; anything outside a `lib/` module folder is "other". */
   static kindOf(filePath: string): AbstractKind {
     const [root, folder, ...rest] = filePath.split("/");
     if (root !== "lib" || !folder) return "other";
@@ -60,8 +58,7 @@ export class AbstractDoc {
   get lineCount() {
     return AbstractDoc.lineCountOf(this.content);
   }
-  // An AI editor answers in prose when it decides nothing needs changing, and that prose would silently
-  // replace the abstract — so a candidate must look like a markdown file and be shorter than what it replaces.
+  // An AI editor that decides nothing needs changing answers in prose, which must not replace the abstract.
   canReplaceWith(candidate: string) {
     const next = candidate.trim();
     if (!next.startsWith("#")) return false;

package/agentsIndex.test.ts

@@ -1,6 +1,4 @@
 import { describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
 import path from "node:path";
 import {
   AGENT_BLOCK_END,
@@ -14,6 +12,7 @@ import {
   upsertAgentBlock,
 } from "./agentsIndex";
 import type { RecipeInfo } from "./recipeScanner";
+import { tempDirs, writeText } from "./testHelpers";
 
 const button: RecipeInfo = {
   name: "buttonRecipe",
@@ -79,12 +78,10 @@ describe("upsertAgentBlock / extractAgentBlock", () => {
 });
 
 describe("collectScopeRecipeSources", () => {
+  const makeTempRoot = tempDirs("agents-index-");
   test("collects own + dependency lib recipes, never the framework's", async () => {
-    const root = await mkdtemp(path.join(tmpdir(), "agents-index-"));
-    const write = async (rel: string, content: string) => {
-      await mkdir(path.dirname(path.join(root, rel)), { recursive: true });
-      await writeFile(path.join(root, rel), content);
-    };
+    const root = await makeTempRoot();
+    const write = async (rel: string, content: string) => await writeText(path.join(root, rel), content);
     await write("apps/minimal/ui/Recipe/appCard.ts", `export const appCard = recipe(tv({ base: "x" }));`);
     await write("libs/shared/ui/Recipe/panel.ts", `export const panelRecipe = recipe(tv({ base: "y" }));`);
     await write("pkgs/akanjs/ui/recipe/buttonRecipe.ts", `export const buttonRecipe = recipe(tv({ base: "z" }));`);

package/agentsIndex.ts

@@ -1,31 +1,18 @@
 import type { RecipeInfo, RecipeSource } from "./recipeScanner";
 
-// recipeScanner 는 상단에서 typescript(~65MB)를 끌어온다. 이 모듈은 executors(CLI 엔트리 그래프)에
-// 상주하므로 스캔 스택은 첫 사용 시점에 지연 로드한다 — 정적 import 로 되돌리면 entryModuleGraph 테스트가 깨진다.
+// Lazy: recipeScanner loads `typescript` (~65MB) and this module sits in the CLI entry graph (entryModuleGraph test).
 let recipeScannerLoad: Promise<typeof import("./recipeScanner")> | null = null;
 const loadRecipeScanner = () => (recipeScannerLoad ??= import("./recipeScanner"));
 
-/**
- * agentsIndex — 스코프별 에이전트 색인의 단일 렌더러.
- *
- * 색인은 소유 경계로 쪼갠다: 루트 AGENTS.md 는 프레임워크(akanjs/ui) 레시피만 싣고, 각 앱/lib 은
- * 자기 스코프에서 import 가능한 레시피(own + 의존 lib)를 자기 AGENTS.md 에 싣는다. 항상 로드되는
- * 컨텍스트가 앱 수에 비례해 커지는 것과, import 불가능한 이웃 앱 레시피가 환상을 유발하는 것을 막는다.
- *
- * 신선도는 두 지점이 보장한다: `SysExecutor.scan(write)` 가 재생성하고(akan sync/build/start 가 전부
- * 지나가는 길목), `akan lint` 가 스캔 결과와 커밋된 블록을 비교해 stale 이면 실패시킨다.
- */
+//* Split by ownership (root: framework recipes; each app/lib: what it may import), so always-loaded context does not
+//* grow with the app count and no unimportable neighbour recipe is listed.
 
 export const AGENT_BLOCK_START = "<!-- akan:agent:start -->";
 export const AGENT_BLOCK_END = "<!-- akan:agent:end -->";
 
 const AGENT_VERSION_PREFIX = "<!-- akan:agent:version ";
 
-/**
- * The generating release, stamped into the workspace block. Nothing re-runs `akan agent install` on its own, so
- * without a stamp a workspace carrying conventions from four releases ago is indistinguishable from a current one —
- * `akan doctor` compares this against the installed devkit and says so.
- */
+/** Nothing re-runs `akan agent install` on its own, so `akan doctor` compares this stamp against the installed devkit. */
 export const stampBlockVersion = (block: string, version: string): string =>
   `${AGENT_VERSION_PREFIX}${version} -->\n\n${block}`;
 
@@ -36,7 +23,7 @@ export const extractBlockVersion = (content: string): string | null =>
 /** The running `@akanjs/devkit` version; null when its package.json is unreadable, which must not fail a doctor run. */
 export const readDevkitVersion = async (): Promise<string | null> => {
   const { readFile } = await import("node:fs/promises");
-  const { getDirname } = await import("./getDirname");
+  const { getDirname } = await import("./fileSys");
   try {
     const raw = await readFile(`${getDirname(import.meta.url)}/package.json`, "utf-8");
     return (JSON.parse(raw) as { version?: string }).version ?? null;
@@ -97,10 +84,7 @@ export const renderRecipeEntries = (recipes: RecipeInfo[]): string => {
     .join("\n\n");
 };
 
-/**
- * Every recipe source importable from the scope: its own `ui/Recipe/` plus each dependency lib's.
- * Framework recipes are excluded on purpose — they live in the root AGENTS.md, valid for every scope.
- */
+/** Own `ui/Recipe/` plus each dependency lib's; framework recipes live in the root AGENTS.md instead. */
 export const collectScopeRecipeSources = async (
   workspaceRoot: string,
   scope: AgentsIndexScope,

package/akanApp/BackendImportGraph.test.ts

@@ -1,34 +1,24 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
+import { realpath, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { Logger } from "akanjs/common";
 import type { App } from "../commandDecorators";
+import { tempDirs, writeText } from "../testHelpers";
 import { BackendImportGraph } from "./BackendImportGraph";
 import { filesChangedSince } from "./devHostPolicy";
 
 describe("BackendImportGraph", () => {
-  const tempRoots: string[] = [];
+  const makeTempRoot = tempDirs("akan-devkit-graph-");
 
   const makeGraph = async (files: Record<string, string>) => {
-    // Realpath, not the mkdtemp path: `Bun.resolveSync` returns real paths, and on macOS `/var/folders`
-    // is a symlink, so an unresolved root makes every resolved import look like it escapes the workspace.
-    const workspaceRoot = await realpath(await mkdtemp(path.join(os.tmpdir(), "akan-devkit-graph-")));
-    tempRoots.push(workspaceRoot);
+    // Realpath: `Bun.resolveSync` returns real paths, and macOS `/var/folders` is a symlink.
+    const workspaceRoot = await realpath(await makeTempRoot());
     const cwdPath = path.join(workspaceRoot, "apps/demo");
-    for (const [rel, source] of Object.entries(files)) {
-      const filePath = path.join(cwdPath, rel);
-      await mkdir(path.dirname(filePath), { recursive: true });
-      await writeFile(filePath, source);
-    }
+    for (const [rel, source] of Object.entries(files)) await writeText(path.join(cwdPath, rel), source);
     const app = { cwdPath, workspace: { workspaceRoot } } as unknown as App;
     return { graph: new BackendImportGraph(app, new Logger("test")), cwdPath };
   };
 
-  afterEach(async () => {
-    await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-  });
-
   test("walks the backend entrypoints' import graph", async () => {
     const { graph, cwdPath } = await makeGraph({
       "main.ts": 'import "./server";\n',
@@ -51,7 +41,6 @@ describe("BackendImportGraph", () => {
     await graph.refresh();
     expect(graph.has(path.join(cwdPath, "lib/added.ts"))).toBe(false);
 
-    // The scan cache is keyed on (mtimeMs, size), so the rewrite must invalidate it.
     await writeFile(path.join(cwdPath, "server.ts"), 'import "./lib/added";\nexport default 1;\n');
 
     await graph.refresh();
@@ -81,8 +70,7 @@ describe("BackendImportGraph", () => {
     await graph.refresh();
     const before = await graph.fingerprint();
 
-    // The builder is gone here, so no watcher event exists for this save — which is the whole reason
-    // the stamps are taken. `mtimeMs` has a coarse clock on Linux, so the size has to move too.
+    // `mtimeMs` has a coarse clock on Linux, so the size has to move too.
     await writeFile(path.join(cwdPath, "lib/handler.ts"), "export const handler = () => 'changed';\n");
 
     expect(filesChangedSince(before, await graph.fingerprint())).toEqual([path.join(cwdPath, "lib/handler.ts")]);
@@ -96,11 +84,9 @@ describe("BackendImportGraph", () => {
     });
     await graph.refresh();
     const before = await graph.fingerprint();
-    // A recycle with no edit in it is the common case, and it must not cost a backend restart.
     expect(filesChangedSince(before, await graph.fingerprint())).toEqual([]);
 
     await rm(path.join(cwdPath, "lib/handler.ts"));
-    // Deleted counts as changed: the backend is still running what used to be there.
     expect(filesChangedSince(before, await graph.fingerprint())).toEqual([path.join(cwdPath, "lib/handler.ts")]);
   });
 

package/akanApp/BackendImportGraph.ts

@@ -22,14 +22,7 @@ export class BackendImportGraph {
   readonly #jsTranspiler = new Bun.Transpiler({ loader: "js" });
   readonly #jsxTranspiler = new Bun.Transpiler({ loader: "jsx" });
   #files = new Set<string>();
-  /**
-   * `refresh()` runs on every server-side save and on every dev-host recycle, and re-reading plus
-   * re-parsing files that did not change is the whole cost of it. Keyed on (mtimeMs, size).
-   *
-   * Specifiers are cached, not resolved paths: creating a file can change what an *unchanged* importer's
-   * specifier resolves to, and `Bun.resolveSync` is cheap next to a read plus a transpiler scan. Only
-   * the scan result is retained — never the source text.
-   */
+  // Specifiers, not resolved paths: a new file can change what an unchanged importer's specifier resolves to.
   #scanCache = new Map<string, { mtimeMs: number; size: number; specifiers: Bun.Import[] }>();
   #ready = false;
   #lastRefreshSucceeded = false;
@@ -51,17 +44,6 @@ export class BackendImportGraph {
     return this.#files.has(path.resolve(file));
   }
 
-  /**
-   * Stamp every file the backend runs, so a caller can ask later what moved.
-   *
-   * Taken when the builder goes away and compared when its replacement is up, because nothing watches
-   * the tree in between: the departing builder's watcher left with it, and the replacement's index
-   * primes from the disk it finds, so an edit that lands in the gap is *baseline* to it and is never
-   * reported at all. The client half of such an edit is rescued by the replacement's boot build; the
-   * backend half is a server left running code that no longer exists, with nothing on screen to say so.
-   *
-   * One `stat` per graph file, against a gap that costs a whole boot build anyway.
-   */
   async fingerprint(): Promise<SourceFingerprints> {
     const stamps = await Promise.all(
       [...this.#files].map(async (file) => {
@@ -117,7 +99,6 @@ export class BackendImportGraph {
     return files;
   }
 
-  /** Null when the file is gone, which is the existence check the walk used to make separately. */
   async #importsOf(file: string): Promise<Bun.Import[] | null> {
     const stats = await stat(file).catch(() => null);
     if (!stats?.isFile()) return null;

package/akanApp/akanApp.host.test.ts

@@ -5,13 +5,11 @@ describe("readProcessRssBytes", () => {
   test("reads this process's own rss", async () => {
     const rssBytes = await AkanAppHost.readProcessRssBytes(process.pid);
     if (rssBytes === null) throw new Error("expected to read this process's own rss");
-    // Loose bounds on purpose: the point is that it read a real number from the OS, not which number.
     expect(rssBytes).toBeGreaterThan(1024 * 1024);
     expect(rssBytes).toBeLessThan(64 * 1024 * 1024 * 1024);
   });
 
-  // Null rather than 0, because callers must treat an unreadable pid as "no new information" — a 0
-  // would read as "settled below the ceiling" and cancel a recycle that should happen.
+  // A 0 would read as "settled below the ceiling" and cancel a recycle that should happen.
   test("returns null for a pid that does not exist", async () => {
     expect(await AkanAppHost.readProcessRssBytes(2_147_483_646)).toBeNull();
   });