@akanjs/devkit 3.0.0-alpha.70 → 3.0.0-alpha.72

package/akanApp/BackendImportGraph.test.ts

@@ -0,0 +1,120 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Logger } from "akanjs/common";
+import type { App } from "../commandDecorators";
+import { BackendImportGraph } from "./BackendImportGraph";
+import { filesChangedSince } from "./devHostPolicy";
+
+describe("BackendImportGraph", () => {
+  const tempRoots: string[] = [];
+
+  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);
+    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);
+    }
+    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',
+      "server.ts": 'import { handler } from "./lib/handler";\nexport default handler;\n',
+      "lib/handler.ts": "export const handler = () => null;\n",
+      "lib/unreachable.ts": "export const nope = 1;\n",
+    });
+
+    expect(await graph.refresh()).toBe(true);
+    expect(graph.has(path.join(cwdPath, "lib/handler.ts"))).toBe(true);
+    expect(graph.has(path.join(cwdPath, "lib/unreachable.ts"))).toBe(false);
+  });
+
+  test("picks up an import added to an already-scanned file", async () => {
+    const { graph, cwdPath } = await makeGraph({
+      "main.ts": 'import "./server";\n',
+      "server.ts": "export default 1;\n",
+      "lib/added.ts": "export const added = 1;\n",
+    });
+    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();
+    expect(graph.has(path.join(cwdPath, "lib/added.ts"))).toBe(true);
+  });
+
+  test("drops a file that left the graph", async () => {
+    const { graph, cwdPath } = await makeGraph({
+      "main.ts": 'import "./server";\n',
+      "server.ts": 'import "./lib/leaving";\nexport default 1;\n',
+      "lib/leaving.ts": "export const leaving = 1;\n",
+    });
+    await graph.refresh();
+    expect(graph.has(path.join(cwdPath, "lib/leaving.ts"))).toBe(true);
+
+    await writeFile(path.join(cwdPath, "server.ts"), "export default 1;\n");
+    await graph.refresh();
+    expect(graph.has(path.join(cwdPath, "lib/leaving.ts"))).toBe(false);
+  });
+
+  test("reports which backend files moved while nobody was watching", async () => {
+    const { graph, cwdPath } = await makeGraph({
+      "main.ts": 'import "./server";\n',
+      "server.ts": 'import "./lib/handler";\nexport default 1;\n',
+      "lib/handler.ts": "export const handler = () => null;\n",
+    });
+    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.
+    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")]);
+  });
+
+  test("says nothing when the tree is untouched, and names a deleted file", async () => {
+    const { graph, cwdPath } = await makeGraph({
+      "main.ts": 'import "./server";\n',
+      "server.ts": 'import "./lib/handler";\nexport default 1;\n',
+      "lib/handler.ts": "export const handler = () => null;\n",
+    });
+    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")]);
+  });
+
+  test("keeps the previous graph when a refresh finds no entrypoints", async () => {
+    const { graph, cwdPath } = await makeGraph({
+      "main.ts": 'import "./lib/kept";\n',
+      "lib/kept.ts": "export const kept = 1;\n",
+    });
+    await graph.refresh();
+    expect(graph.ready).toBe(true);
+
+    await rm(path.join(cwdPath, "main.ts"));
+    await graph.refresh();
+    // An empty scan is not a failure, so the graph legitimately empties out.
+    expect(graph.has(path.join(cwdPath, "lib/kept.ts"))).toBe(false);
+  });
+});

package/akanApp/BackendImportGraph.ts

@@ -0,0 +1,167 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import type { Logger } from "akanjs/common";
+import type { App } from "../commandDecorators";
+import { SOURCE_EXTS, type SourceFingerprints } from "./devHostPolicy";
+
+const NON_SOURCE_EXT_RE =
+  /\.(css|scss|sass|less|json|svg|png|jpe?g|webp|gif|avif|ico|woff2?|ttf|otf|mp3|mp4|wav|html)$/i;
+
+const GRAPH_IMPORT_KINDS = new Set<Bun.ImportKind>([
+  "import-statement",
+  "require-call",
+  "require-resolve",
+  "dynamic-import",
+]);
+
+export class BackendImportGraph {
+  readonly #app: App;
+  readonly #logger: Logger;
+  readonly #tsTranspiler = new Bun.Transpiler({ loader: "ts" });
+  readonly #tsxTranspiler = new Bun.Transpiler({ loader: "tsx" });
+  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.
+   */
+  #scanCache = new Map<string, { mtimeMs: number; size: number; specifiers: Bun.Import[] }>();
+  #ready = false;
+  #lastRefreshSucceeded = false;
+
+  constructor(app: App, logger: Logger) {
+    this.#app = app;
+    this.#logger = logger;
+  }
+
+  get ready() {
+    return this.#ready;
+  }
+
+  get lastRefreshSucceeded() {
+    return this.#lastRefreshSucceeded;
+  }
+
+  has(file: string) {
+    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) => {
+        const stats = await stat(file).catch(() => null);
+        return [file, stats ? `${Math.round(stats.mtimeMs)}:${stats.size}` : "(gone)"] as const;
+      }),
+    );
+    return new Map(stamps);
+  }
+
+  async refresh(): Promise<boolean> {
+    try {
+      const files = await this.#build();
+      this.#files = files;
+      this.#ready = true;
+      this.#lastRefreshSucceeded = true;
+      this.#logger.verbose(`[backend-graph] scanned ${files.size} files`);
+      return true;
+    } catch (err) {
+      this.#ready = this.#files.size > 0;
+      this.#lastRefreshSucceeded = false;
+      this.#logger.warn(
+        `[backend-graph] scan failed; ${this.#ready ? "using previous graph" : "using fallback rules"}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return this.#ready;
+    }
+  }
+
+  async #build(): Promise<Set<string>> {
+    const roots = await this.#entrypoints();
+    const files = new Set<string>();
+    const queue = [...roots];
+    const workspaceRoot = path.resolve(this.#app.workspace.workspaceRoot);
+
+    while (queue.length > 0) {
+      const current = path.resolve(queue.pop() as string);
+      if (files.has(current)) continue;
+      if (!this.#isWorkspaceSource(current, workspaceRoot)) continue;
+      const imports = await this.#importsOf(current);
+      if (!imports) continue;
+
+      files.add(current);
+      const importerDir = path.dirname(current);
+      for (const imp of imports) {
+        if (!GRAPH_IMPORT_KINDS.has(imp.kind) || !imp.path || NON_SOURCE_EXT_RE.test(imp.path)) continue;
+        const resolved = this.#resolve(imp.path, importerDir);
+        if (!resolved || files.has(resolved)) continue;
+        queue.push(resolved);
+      }
+    }
+    // Files that dropped out of the graph would otherwise be cached for the life of the dev session.
+    for (const cached of this.#scanCache.keys()) if (!files.has(cached)) this.#scanCache.delete(cached);
+    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;
+    const mtimeMs = Math.round(stats.mtimeMs);
+    const cached = this.#scanCache.get(file);
+    if (cached && cached.mtimeMs === mtimeMs && cached.size === stats.size) return cached.specifiers;
+    const specifiers = this.#scanImports(file, await Bun.file(file).text());
+    this.#scanCache.set(file, { mtimeMs, size: stats.size, specifiers });
+    return specifiers;
+  }
+
+  async #entrypoints(): Promise<string[]> {
+    const roots = [`${this.#app.cwdPath}/main.ts`, `${this.#app.cwdPath}/server.ts`];
+    const existing: string[] = [];
+    for (const root of roots) {
+      const abs = path.resolve(root);
+      if (await Bun.file(abs).exists()) existing.push(abs);
+    }
+    return existing;
+  }
+
+  #resolve(specifier: string, importerDir: string): string | null {
+    try {
+      const resolved = Bun.resolveSync(specifier, importerDir);
+      if (!path.isAbsolute(resolved)) return null;
+      if (!SOURCE_EXTS.has(path.extname(resolved).toLowerCase())) return null;
+      return path.resolve(resolved);
+    } catch {
+      return null;
+    }
+  }
+
+  #isWorkspaceSource(file: string, workspaceRoot: string): boolean {
+    const rel = path.relative(workspaceRoot, file);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) return false;
+    if (rel.includes(`${path.sep}node_modules${path.sep}`) || rel.includes(`${path.sep}.akan${path.sep}`)) return false;
+    return SOURCE_EXTS.has(path.extname(file).toLowerCase());
+  }
+
+  #scanImports(file: string, source: string): Bun.Import[] {
+    const ext = path.extname(file).toLowerCase();
+    if (ext === ".tsx") return this.#tsxTranspiler.scanImports(source);
+    if (ext === ".jsx") return this.#jsxTranspiler.scanImports(source);
+    if (ext === ".js" || ext === ".mjs" || ext === ".cjs") return this.#jsTranspiler.scanImports(source);
+    return this.#tsTranspiler.scanImports(source);
+  }
+}