@akanjs/devkit 3.1.2-rc.2 → 3.1.2-rc.4

package/akanApp/akanApp.host.ts

@@ -50,7 +50,7 @@ import {
   UNAVAILABLE_REDIS_HOST,
 } from "./devHostPolicy";
 
-const backendMsgTypeSet = new Set<BuilderMessage["type"]>(["build-route", "build-csr"]);
+const backendMsgTypeSet = new Set<BuilderMessage["type"]>(["build-route", "build-csr", "build-graph"]);
 
 const asMib = (bytes: number) => Math.round(bytes / 1024 / 1024);
 
@@ -504,7 +504,7 @@ export class AkanAppHost {
       await this.#handleInvalidate(message);
       return;
     }
-    if (message.type === "build-route-res" || message.type === "build-csr-res") {
+    if (message.type === "build-route-res" || message.type === "build-csr-res" || message.type === "build-graph-res") {
       const answer = this.#builderRequests.settle(message);
       if (!answer) {
         this.logger.verbose(`[builder] dropped a ${message.type} no live backend is waiting for (id=${message.id})`);
@@ -925,6 +925,8 @@ export class AkanAppHost {
       this.#sendToBackend({ type: "build-route-res", id: message.id, ok: false, error });
     else if (message.type === "build-csr")
       this.#sendToBackend({ type: "build-csr-res", id: message.id, ok: false, error });
+    else if (message.type === "build-graph")
+      this.#sendToBackend({ type: "build-graph-res", id: message.id, ok: false, error });
     else return false;
     return true;
   }
@@ -1308,7 +1310,7 @@ export class AkanAppHost {
       this.logger.verbose(`[csr] armed dev CSR rebuilds (${message.reason})`);
     }
     // Renumbered per backend generation; the failure replies below use that backend's own `message.id`.
-    if (message.type === "build-route" || message.type === "build-csr") {
+    if (message.type === "build-route" || message.type === "build-csr" || message.type === "build-graph") {
       const outgoing = this.#builderRequests.issue(message);
       if (this.#builder?.send(outgoing)) return;
       this.#builderRequests.withdraw(outgoing.id);

package/akanMcpContract.ts

@@ -321,6 +321,12 @@ export const readonlyMcpTools: McpToolDefinition[] = [
       "Legacy broad module context. Pass app in monorepos; prefer inspect_akan_context.moduleContext or fieldInsertionContext for typed add-field evidence.",
     inputSchema: { type: "object", properties: { app: stringProperty, module: stringProperty }, required: ["module"] },
   },
+  {
+    name: "get_graph",
+    description:
+      "Read-only Akan Graph from source, no dev server needed: models with their fields and relations, slices and endpoints with guards, the service methods and queries each calls, the store actions that fetch them, and the components and pages that use them. Every node and edge carries its source location. Pass app and/or module to scope a large workspace. Pass since (a git revision such as main, or HEAD for uncommitted work) for the Change Map instead: what changed since HEAD forked from it, working tree included, with each node, field and edge marked added, removed or changed, the unchanged neighbours they call or are called by, and the changed files no node covers, each marked the same way.",
+    inputSchema: { type: "object", properties: { app: stringProperty, module: stringProperty, since: stringProperty } },
+  },
   {
     name: "get_guideline",
     description: "Return an Akan agent guideline resource by name.",

package/applicationBuildReporter.test.ts

@@ -0,0 +1,32 @@
+import { afterEach, describe, expect, spyOn, test } from "bun:test";
+import { Logger } from "akanjs/common";
+import { ApplicationBuildReporter, type ApplicationBuildResult } from "./applicationBuildReporter";
+
+const resultFor = (environment: string): ApplicationBuildResult => ({
+  phases: [],
+  durationMs: 1_200,
+  outputDir: "dist/apps/shop",
+  artifactDir: "dist/apps/shop/.akan/artifact",
+  environment,
+});
+
+describe("ApplicationBuildReporter.printSummary", () => {
+  const rawLog = spyOn(Logger, "rawLog").mockImplementation(() => undefined);
+  afterEach(() => rawLog.mockClear());
+
+  test("names every variable a deployed build needs when the build is for local", () => {
+    ApplicationBuildReporter.printSummary(resultFor("local"));
+
+    const notice = rawLog.mock.calls.map(([line]) => line).at(-1);
+    expect(notice).toBe(ApplicationBuildReporter.localBuildNotice);
+    for (const key of ["AKAN_PUBLIC_ENV=main", "AKAN_PUBLIC_REPO_NAME", "AKAN_PUBLIC_SERVE_DOMAIN"])
+      expect(notice).toContain(key);
+  });
+
+  test("adds nothing to a build for a deployed environment", () => {
+    ApplicationBuildReporter.printSummary(resultFor("main"));
+
+    expect(rawLog.mock.calls.map(([line]) => line)).not.toContain(ApplicationBuildReporter.localBuildNotice);
+    expect(rawLog.mock.calls.at(-1)?.[0]).toBe("Done in 1.2s");
+  });
+});

package/applicationBuildReporter.ts

@@ -15,6 +15,7 @@ export interface ApplicationBuildResult {
   durationMs: number;
   outputDir: string;
   artifactDir: string;
+  environment: string;
 }
 
 export interface ApplicationBuildProgressReporter {
@@ -35,8 +36,12 @@ export class ApplicationBuildReporter {
     Logger.rawLog(`Route artifacts: ${result.artifactDir}`);
     Logger.rawLog(`Server output: ${result.outputDir}`);
     Logger.rawLog(`Done in ${ApplicationBuildReporter.formatDuration(result.durationMs)}`);
+    if (result.environment === "local") Logger.rawLog(ApplicationBuildReporter.localBuildNotice);
   }
 
+  static readonly localBuildNotice =
+    "Built for local, which serves the dev routes to every caller. For a host others can reach, build with AKAN_PUBLIC_ENV=main, AKAN_PUBLIC_REPO_NAME and AKAN_PUBLIC_SERVE_DOMAIN set.";
+
   static formatError(error: unknown, workspaceRoot = process.cwd()): string {
     if (error instanceof AggregateError) {
       const nestedMessages = error.errors

package/applicationBuildRunner.ts

@@ -182,6 +182,7 @@ export class ApplicationBuildRunner {
       durationMs: Date.now() - this.#startedAt,
       outputDir: this.#app.dist.cwdPath,
       artifactDir: path.join(this.#app.dist.cwdPath, ".akan/artifact"),
+      environment,
     };
   }
 

package/codeAgent/skills/akan-page/SKILL.md

@@ -34,6 +34,25 @@ export default page()
 6. Re-skin an `akanjs/ui` component for a subtree with `_overrides.tsx`:
    `export default override({ Slot: AppComponent })`, no logic.
 
+## API at a glance
+
+`page`, `layout` and `router` come from `akanjs/client`, `Link` from `akanjs/ui`, `usePageLocation` from
+`akanjs/webkit`. A stage receives the declared params and search keys plus `lang`.
+
+- Data-driven title: `.head(async ({ name }) => <title>{(await fetch.pokemon(name))?.label}</title>)`.
+- Async page: `.render(async ({ name }) => { const pokemon = await fetch.pokemon(name); if (!pokemon) router.notFound(); … })`;
+  the same query in `.head()` and `.render()` is one request.
+- `router.notFound()` from `.guard()`, `.head()` or `.render()` answers 404 with the nearest layout's `.notFound()`
+  above it (an unmatched URL: the deepest layout covering it), else the built-in 404.
+- A layout's own 404 and error views: `.notFound(({ pathname }) => …)` and `.error(({ error }) => …)` on `layout()`
+  or `rootLayout()`.
+- `<Link href="/pokemon/deoxys">`: write the path without the locale; Link adds it, or leaves it off for the default
+  locale under `i18n.localePrefix: "as-needed"`. `activeClassName` marks the current one.
+- From a handler: `router.push(href)` / `router.replace(href)`; in a server stage, `router.redirect(href)`.
+- A client filter kept in the URL without reloading the page: ``router.replace(`/pokemon?q=${q}`, { shallow: true,
+  scrollToTop: false })`` in a `"use client"` component, read back with `usePageLocation().searchParams`. Shallow
+  holds only while the path stays the same; a server `.search()` sees the value at the next full navigation.
+
 ## Never
 
 - A `fetch.<mutation>()` while rendering — it throws `base.error.mutationInRender`, because opening a link would

package/codeAgent/skills/akan-service/SKILL.md

@@ -31,4 +31,51 @@ registered under `<refName>`, and the `Service` suffix is required.
 An external API or piece of infrastructure is an `adapt()` class in `srvkit/`, injected with `plug`. It
 self-registers, so do **not** add it to `lib/option.ts`.
 
+## Recipe: pages backed by an external HTTP API
+
+`akan create-service pokeapi <app>` scaffolds `lib/_pokeapi/`; the adapter beside it is yours.
+
+```ts
+// srvkit/pokeApi.ts — read at boot, so the built server takes API_BASE_URL from the host that runs it
+export class PokeApi extends adapt("pokeApi" as const, ({ env }) => ({
+  baseUrl: env(() => process.env.API_BASE_URL ?? "http://localhost:9000"),
+})) {
+  async get<T>(path: string): Promise<T | null> {
+    try {
+      const res = await fetch(`${this.baseUrl}/${path}`, { signal: AbortSignal.timeout(20_000) });
+      if (res.ok) return (await res.json()) as T;
+      if (res.status !== 404) this.logger.warn(`${path} answered ${res.status}`);
+    } catch (error) {
+      this.logger.warn(`${path} failed: ${String(error)}`);
+    }
+    return null;
+  }
+}
+
+// lib/_pokeapi/pokeapi.service.ts — shape the upstream JSON here, not in the page
+export class PokeapiService extends serve("pokeapi" as const, ({ plug }) => ({ pokeApi: plug(PokeApi) })) {
+  async getPokemon(name: string) {
+    const pokemon = await this.pokeApi.get<ApiPokemon>(`pokemon/${name}`);
+    return pokemon && { id: pokemon.id, name: pokemon.name };
+  }
+}
+
+// lib/_pokeapi/pokeapi.signal.ts — Any answers plain JSON; nullable lets it answer null for "not found"
+export class PokeapiEndpoint extends endpoint(srv.pokeapi, ({ query }) => ({
+  pokemon: query(Any, { guards: [Public], nullable: true })
+    .param("name", String)
+    .exec(async function (name) {
+      return await this.pokeapiService.getPokemon(name);
+    }),
+})) {}
+
+// lib/_pokeapi/pokeapi.dictionary.ts — typecheck asks a label for every endpoint
+  .endpoint<PokeapiEndpoint>((fn) => ({ pokemon: fn(["Pokémon", "포켓몬"]) }))
+```
+
+The page calls it as `await fetch.pokemon(name)` (`fetch` from `@apps/<app>/client`) and answers
+`router.notFound()` on `null`. An `Any` return reaches the page as `unknown`: type it with an interface in
+`common/`, or return a scalar (`akan create-scalar`) for a typed wire shape. A query that answers `null` without
+`nullable: true` fails the render, naming the endpoint.
+
 Full detail: `get_guideline` with `modelService`.

package/gitRevision.test.ts

@@ -0,0 +1,82 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdir, mkdtemp, rm, unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { GitRevision } from "./gitRevision";
+
+const roots: string[] = [];
+const byName = (a: string, b: string) => (a < b ? -1 : a > b ? 1 : 0);
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+const repoOf = async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "akan-git-"));
+  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);
+  };
+  git("init", "-q", "-b", "main");
+  return { root, git, write };
+};
+
+describe("GitRevision", () => {
+  it("lists each changed file with its change, a rename as a removal and an addition", async () => {
+    const { root, git, write } = await repoOf();
+    await write(".gitignore", "apps/*/scripts\n");
+    await write("apps/demo/lib/memo/memo.constant.ts", "a\n");
+    await write("apps/demo/lib/memo/memo.service.ts", "b\n");
+    await write("apps/demo/lib/memo/memo.store.ts", "c\n");
+    git("add", "-A");
+    git("commit", "-q", "--no-verify", "-m", "base");
+    const base = git("rev-parse", "HEAD");
+    await write("apps/demo/lib/memo/memo.constant.ts", "a2\n");
+    await unlink(path.join(root, "apps/demo/lib/memo/memo.service.ts"));
+    git("mv", "apps/demo/lib/memo/memo.store.ts", "apps/demo/lib/memo/memo2.store.ts");
+    await write("apps/demo/lib/memo/memo.signal.ts", "d\n");
+    await write("apps/demo/scripts/seed.ts", "e\n");
+    const git2 = new GitRevision(root);
+    expect(await git2.changedFilesSince(base)).toEqual([
+      { file: "apps/demo/lib/memo/memo.constant.ts", change: "changed" },
+      { file: "apps/demo/lib/memo/memo.service.ts", change: "removed" },
+      { file: "apps/demo/lib/memo/memo.signal.ts", change: "added" },
+      { file: "apps/demo/lib/memo/memo.store.ts", change: "removed" },
+      { file: "apps/demo/lib/memo/memo2.store.ts", change: "added" },
+    ]);
+    expect((await git2.workingFiles()).sort(byName)).toEqual([
+      "apps/demo/lib/memo/memo.constant.ts",
+      "apps/demo/lib/memo/memo.service.ts",
+      "apps/demo/lib/memo/memo.signal.ts",
+      "apps/demo/lib/memo/memo2.store.ts",
+    ]);
+    expect([...(await git2.filesAt(base, () => true)).keys()].sort(byName)).toEqual([
+      "apps/demo/lib/memo/memo.constant.ts",
+      "apps/demo/lib/memo/memo.service.ts",
+      "apps/demo/lib/memo/memo.store.ts",
+    ]);
+  });
+
+  it("says so when HEAD shares no commit with the revision, instead of comparing with its tip", async () => {
+    const { git, write, root } = await repoOf();
+    await write("apps/demo/a.ts", "a\n");
+    git("add", "-A");
+    git("commit", "-q", "--no-verify", "-m", "main");
+    git("checkout", "-q", "--orphan", "other");
+    await write("apps/demo/b.ts", "b\n");
+    git("add", "-A");
+    git("commit", "-q", "--no-verify", "-m", "other");
+    const revision = new GitRevision(root);
+    expect((await revision.forkPointOf("main")).error).toContain("shares no commit with main");
+    expect((await revision.forkPointOf(null)).error).toContain("shares no commit with main");
+    expect((await revision.forkPointOf("-x")).error).toBe("-x is not a commit in this repository.");
+  });
+});

package/gitRevision.ts

@@ -0,0 +1,124 @@
+import type { AkanChangedFile } from "@akanjs/language";
+
+export type ForkPoint = { sha: string; error?: undefined } | { sha?: undefined; error: string };
+
+const systemPaths = ["apps", "libs"];
+const changeOfStatus: { [status: string]: AkanChangedFile["change"] | undefined } = { A: "added", D: "removed" };
+
+//? Commands run in the workspace root, which may sit below the repository root; `./<path>` and `--relative` keep every
+//? path git reads or prints relative to the workspace.
+export class GitRevision {
+  static readonly #defaultBranches = ["upstream/HEAD", "upstream/main", "origin/HEAD", "origin/main", "main", "master"];
+  //? Studio and MCP read git beside the user's own commands; without this, `git diff` may take index.lock to refresh it.
+  static readonly #env = { ...process.env, GIT_OPTIONAL_LOCKS: "0" };
+  readonly #root: string;
+
+  constructor(root: string) {
+    this.#root = root;
+  }
+
+  async forkPointOf(since: string | null): Promise<ForkPoint> {
+    if ((await this.#git(["rev-parse", "--is-inside-work-tree"]))?.trim() !== "true")
+      return { error: "The Change Map compares with git history, and this workspace is not in a git repository." };
+    if (since !== null) {
+      //? A leading `-` would reach git as an option.
+      const sha = /^[^-\s][^\s]*$/.test(since)
+        ? (await this.#git(["rev-parse", "--verify", "--quiet", `${since}^{commit}`]))?.trim()
+        : undefined;
+      if (!sha) return { error: `${since} is not a commit in this repository.` };
+      return await this.#mergeBase(since, sha);
+    }
+    for (const branch of GitRevision.#defaultBranches)
+      if ((await this.#git(["rev-parse", "--verify", "--quiet", `${branch}^{commit}`])) !== null)
+        return await this.#mergeBase(branch, branch);
+    const head = (await this.#git(["rev-parse", "--verify", "--quiet", "HEAD^{commit}"]))?.trim();
+    return head ? { sha: head } : { error: "The repository has no commit to compare with yet." };
+  }
+
+  async #mergeBase(name: string, revision: string): Promise<ForkPoint> {
+    const sha = (await this.#git(["merge-base", "HEAD", revision]))?.trim();
+    if (sha) return { sha };
+    return {
+      error: `HEAD shares no commit with ${name} here. In a shallow clone, \`git fetch --unshallow\` brings the history in.`,
+    };
+  }
+
+  async filesAt(sha: string, isWanted: (file: string) => boolean): Promise<Map<string, string>> {
+    const listed = await this.#git(["ls-tree", "-r", "-z", "--name-only", sha, "--", ...systemPaths]);
+    if (listed === null) throw new Error(`git ls-tree failed for ${sha}`);
+    const files = listed.split("\0").filter((file) => file && isWanted(file));
+    const texts = new Map<string, string>();
+    if (!files.length) return texts;
+    const proc = Bun.spawn(["git", "cat-file", "--batch"], {
+      cwd: this.#root,
+      env: GitRevision.#env,
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    const output = new Response(proc.stdout).arrayBuffer();
+    proc.stdin.write(files.map((file) => `${sha}:./${file}\n`).join(""));
+    await proc.stdin.end();
+    const bytes = new Uint8Array(await output);
+    if ((await proc.exited) !== 0) throw new Error(`git cat-file failed for ${sha}`);
+    const decoder = new TextDecoder();
+    let offset = 0;
+    for (const file of files) {
+      const lineEnd = bytes.indexOf(10, offset);
+      if (lineEnd < 0) throw new Error(`git cat-file ended before ${file} at ${sha}`);
+      const header = decoder.decode(bytes.subarray(offset, lineEnd));
+      offset = lineEnd + 1;
+      if (header.endsWith(" missing")) continue;
+      const [, type, size] = header.split(" ");
+      const length = Number(size);
+      if (type === "blob") texts.set(file, decoder.decode(bytes.subarray(offset, offset + length)));
+      offset += length + 1;
+    }
+    return texts;
+  }
+
+  async changedFilesSince(sha: string): Promise<AkanChangedFile[]> {
+    const [tracked, untracked] = await Promise.all([
+      this.#git(["diff", "--name-status", "--no-renames", "--relative", "-z", sha, "--", ...systemPaths]),
+      this.#git(["ls-files", "-z", "--others", "--exclude-standard", "--", ...systemPaths]),
+    ]);
+    if (tracked === null || untracked === null) throw new Error(`git could not list the changes since ${sha}`);
+    const changes = new Map<string, AkanChangedFile["change"]>();
+    const fields = tracked.split("\0");
+    for (let idx = 0; idx + 1 < fields.length; idx += 2)
+      changes.set(fields[idx + 1], changeOfStatus[fields[idx]] ?? "changed");
+    for (const file of untracked.split("\0")) if (file) changes.set(file, "added");
+    return [...changes].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([file, change]) => ({ file, change }));
+  }
+
+  //? Tracked and untracked files, `.gitignore` applied, so the working side of a Change Map sees what the base side
+  //? can: a glob would read ignored files the base never has and mark them added.
+  async workingFiles(): Promise<string[]> {
+    const listed = await this.#git([
+      "ls-files",
+      "-z",
+      "--cached",
+      "--others",
+      "--exclude-standard",
+      "--",
+      ...systemPaths,
+    ]);
+    if (listed === null) throw new Error("git ls-files failed");
+    return [...new Set(listed.split("\0").filter(Boolean))];
+  }
+
+  async #git(args: string[]) {
+    try {
+      const proc = Bun.spawn(["git", ...args], {
+        cwd: this.#root,
+        env: GitRevision.#env,
+        stdout: "pipe",
+        stderr: "ignore",
+      });
+      const [text, exitCode] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+      return exitCode === 0 ? text : null;
+    } catch {
+      return null;
+    }
+  }
+}

package/incrementalBuilder/builderRequestRouter.ts

@@ -1,7 +1,4 @@
-import type { BuilderCsrReq, BuilderCsrRes, BuilderReq, BuilderRes } from "akanjs/server";
-
-type BuilderRequest = BuilderReq | BuilderCsrReq;
-type BuilderResponse = BuilderRes | BuilderCsrRes;
+import type { BuilderRequest, BuilderResponse } from "akanjs/server";
 
 // `BuilderRpc` numbers from 1 per backend process while the builder outlives backends, so ids collide across a
 // restart; host-owned ids keep a dead generation's answer from settling the new backend's request.

package/incrementalBuilder/incrementalBuilder.host.test.ts

@@ -108,6 +108,7 @@ describe("IncrementalBuilderHost", () => {
     const { spawns, messages, host } = startRecordingHost();
     expect(host.send({ type: "build-route", id: 1, routeId: "a", seeds: [], knownEntries: [] })).toBe(true);
     expect(host.send({ type: "build-csr", id: 2, reason: "device webview" })).toBe(true);
+    expect(host.send({ type: "build-graph", id: 4 })).toBe(true);
     // Answered before the exit, so this one must not be failed again afterwards.
     expect(host.send({ type: "build-route", id: 3, routeId: "c", seeds: [], knownEntries: [] })).toBe(true);
     spawns[0]?.options.ipc?.({ type: "build-route-res", id: 3, ok: true, data: { routeId: "c" } });
@@ -129,6 +130,12 @@ describe("IncrementalBuilderHost", () => {
         ok: false,
         error: "builder exited to release bundler memory before answering; reload to retry",
       },
+      {
+        type: "build-graph-res",
+        id: 4,
+        ok: false,
+        error: "builder exited to release bundler memory before answering; reload to retry",
+      },
     ]);
 
     // The replacement owes nothing, so its own exit stays quiet.

package/incrementalBuilder/incrementalBuilder.host.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { Logger } from "akanjs/common";
-import type { BuilderMessage } from "akanjs/server";
+import type { BuilderMessage, BuilderRequest } from "akanjs/server";
 import { CSR_DEV_DIRNAME, CSR_DEV_PATCHING_MARKER, SSR_DEV_DIRNAME } from "akanjs/server/hmr/csrDevManifest";
 import { MemoryLimit } from "akanjs/server/memoryLimit";
 import type { App } from "../commandDecorators";
@@ -9,6 +9,7 @@ import type { App } from "../commandDecorators";
 const builderMsgTypeSet = new Set<BuilderMessage["type"]>([
   "build-route-res",
   "build-csr-res",
+  "build-graph-res",
   "builder-ready",
   "invalidate",
   "css-updated",
@@ -73,7 +74,7 @@ export class IncrementalBuilderHost {
   #manualStop = false;
   // Nothing else answers a request whose builder exits holding it: a crash or kill sends nothing, and a drain races
   // its own exit, so an unanswered page request would spin forever.
-  readonly #inFlight = new Map<number, "build-route" | "build-csr">();
+  readonly #inFlight = new Map<number, BuilderRequest["type"]>();
   #startOptions: IncrementalBuilderStartOptions = {};
   constructor({
     app,
@@ -129,7 +130,8 @@ export class IncrementalBuilderHost {
       ipc: (msg: BuilderMessage) => {
         if (this.#proc !== proc) return;
         if (!msg || typeof msg !== "object") return;
-        if (msg.type === "build-route-res" || msg.type === "build-csr-res") this.#inFlight.delete(msg.id);
+        if (msg.type === "build-route-res" || msg.type === "build-csr-res" || msg.type === "build-graph-res")
+          this.#inFlight.delete(msg.id);
         if (builderMsgTypeSet.has(msg.type)) this.#onMessage(msg);
         if (msg.type === "builder-ready" && !this.ready) {
           this.ready = true;
@@ -269,7 +271,8 @@ export class IncrementalBuilderHost {
     }
     try {
       this.#proc.send(message);
-      if (message.type === "build-route" || message.type === "build-csr") this.#inFlight.set(message.id, message.type);
+      if (message.type === "build-route" || message.type === "build-csr" || message.type === "build-graph")
+        this.#inFlight.set(message.id, message.type);
       return true;
     } catch (error) {
       this.logger.warn(

package/incrementalBuilder/incrementalBuilder.proc.test.ts

@@ -129,6 +129,104 @@ process.send({ type: "build-batch-result", data: { generation, errors, artifact:
     expect(messages.some((message) => message.type === "build-status")).toBe(false);
   }, 30_000);
 
+  test("draws the app's graph and Change Map on request, with the libs it reaches and no other app", async () => {
+    const { root } = track(await createTempApp("demo"));
+    const appDir = path.join(root, "apps/demo");
+    await writeText(
+      path.join(root, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      `const { generation } = JSON.parse(process.argv[2]);
+process.send({ type: "build-batch-result", data: { generation, errors: {}, artifact: {}, optimizedFonts: { css: "", files: [] } } });
+`,
+    );
+    await writeText(path.join(appDir, "page/_index.tsx"), "export default () => null;\n");
+    const moduleFiles = (owner: string, name: string) => {
+      const model = `${name[0].toUpperCase()}${name.slice(1)}`;
+      return [
+        writeText(
+          path.join(root, owner, `lib/${name}/${name}.constant.ts`),
+          `export class ${model} extends via((field) => ({ name: field(String) })) {}\n`,
+        ),
+        writeText(
+          path.join(root, owner, `lib/${name}/${name}.service.ts`),
+          `export class ${model}Service extends serve(db.${name}, () => ({})) {}\n`,
+        ),
+      ];
+    };
+    await Promise.all([
+      ...moduleFiles("apps/demo", "memo"),
+      ...moduleFiles("apps/other", "note"),
+      ...moduleFiles("libs/shared", "file"),
+    ]);
+    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);
+    };
+    git("init", "-q", "-b", "main");
+    git("add", "-A");
+    git("commit", "-q", "--no-verify", "-m", "base");
+    await Promise.all(
+      [
+        ["apps/demo/lib/memo/memo.constant.ts", "Memo"],
+        ["apps/other/lib/note/note.constant.ts", "Note"],
+      ].map(([file, model]) =>
+        writeText(
+          path.join(root, file),
+          `export class ${model} extends via((field) => ({ name: field(String), pinned: field(Boolean) })) {}\n`,
+        ),
+      ),
+    );
+    const messages: BuilderMessage[] = [];
+    const proc = Bun.spawn(["bun", path.join(import.meta.dir, "incrementalBuilder.proc.ts")], {
+      cwd: appDir,
+      env: {
+        ...process.env,
+        AKAN_WORKSPACE_ROOT: root,
+        AKAN_PUBLIC_APP_NAME: "demo",
+        AKAN_PUBLIC_REPO_NAME: "repo",
+        AKAN_PUBLIC_SERVE_DOMAIN: "localhost",
+        AKAN_PUBLIC_ENV: "local",
+        AKAN_WATCH: "0",
+      },
+      stdio: ["ignore", "ignore", "pipe"],
+      serialization: "advanced",
+      ipc: (message: BuilderMessage) => {
+        messages.push(message);
+      },
+    });
+    try {
+      await until(proc, "builder-ready", () => messages.some((message) => message.type === "builder-ready"));
+      proc.send({ type: "build-graph", id: 5 } satisfies BuilderMessage);
+      proc.send({ type: "build-graph", id: 6, changes: { since: null } } satisfies BuilderMessage);
+      proc.send({ type: "build-graph", id: 7, changes: { since: "main" } } satisfies BuilderMessage);
+      await until(
+        proc,
+        "build-graph-res",
+        () => messages.filter((message) => message.type === "build-graph-res").length === 3,
+      );
+    } finally {
+      proc.kill();
+      await proc.exited;
+    }
+    const answerTo = (id: number) => {
+      const answer = messages.find((message) => message.type === "build-graph-res" && message.id === id);
+      if (answer?.type !== "build-graph-res" || !answer.ok) throw new Error(`no graph: ${JSON.stringify(answer)}`);
+      return answer.data;
+    };
+    const graph = answerTo(5);
+    if (!("graph" in graph)) throw new Error("build-graph answered with changes");
+    expect(graph.workspaceRoot).toBe(root);
+    expect(graph.graph.nodes.map((node) => node.id).sort()).toEqual(["model:apps/demo:memo", "model:libs/shared:file"]);
+    const changes = answerTo(6);
+    if (!("changes" in changes) || "error" in changes.changes)
+      throw new Error(`no changes: ${JSON.stringify(changes)}`);
+    expect(changes.changes.nodes.map(({ id, change }) => [id, change])).toEqual([["model:apps/demo:memo", "changed"]]);
+    expect(changes.changes.summary).toEqual({ added: 0, removed: 0, changed: 1 });
+    expect(answerTo(7)).toEqual(changes);
+  }, 30_000);
+
   test("answers a second shell request in the same generation without building again", async () => {
     const { root } = track(await createTempApp("demo"));
     const appDir = path.join(root, "apps/demo");

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -18,13 +18,18 @@ import { RouteClientBuilder } from "@akanjs/devkit/frontendBuild/routeClientBuil
 import { ServerGraphFile } from "@akanjs/devkit/frontendBuild/serverGraphFile";
 import { SsrDevBundler } from "@akanjs/devkit/frontendBuild/ssrDevBundler";
 import { WatchRootResolver } from "@akanjs/devkit/frontendBuild/watchRootResolver";
+import { GitRevision } from "@akanjs/devkit/gitRevision";
+import { WorkspaceGraph } from "@akanjs/devkit/workspaceGraph";
 import { Logger } from "akanjs/common";
 import type {
   BaseBuildArtifact,
+  BuildChangesPayload,
   BuilderCsrReq,
+  BuilderGraphReq,
   BuilderMessage,
   BuilderReq,
   BuilderRes,
+  BuildGraphPayload,
   BuildPhase,
   BuildRouteResultPayload,
   ChangeBatch,
@@ -64,6 +69,8 @@ class IncrementalBuilder {
   #watcher: HmrWatcher | null = null;
   #generation = 0;
   #shellKey: string | null = null;
+  #graph: { generation: number; payload: BuildGraphPayload } | null = null;
+  #changes: { key: string; payload: Promise<BuildChangesPayload> } | null = null;
   #discoveredThrough = 0;
   #csrActive = IncrementalBuilder.#csrArmedByEnv();
   #csrBundler: CsrDevBundler;
@@ -873,6 +880,46 @@ class IncrementalBuilder {
     this.#logger.verbose(`announced boot state after recycle generation=${generation}`);
   }
 
+  async handleBuildGraph(msg: BuilderGraphReq): Promise<void> {
+    try {
+      const data = msg.changes ? await this.#changesPayload(msg.changes.since) : await this.#graphPayload();
+      await BuilderChannel.send({ type: "build-graph-res", id: msg.id, ok: true, data });
+    } catch (err) {
+      const error = ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot);
+      this.#logger.error(`build-graph failed: ${error}`);
+      await BuilderChannel.send({ type: "build-graph-res", id: msg.id, ok: false, error });
+    }
+  }
+
+  async #graphPayload(): Promise<BuildGraphPayload> {
+    const generation = this.#generation;
+    if (this.#graph?.generation !== generation) {
+      const { workspace } = this.#app;
+      const graph = WorkspaceGraph.visibleTo(await WorkspaceGraph.build(workspace), this.#app.name);
+      this.#graph = { generation, payload: { workspaceRoot: workspace.workspaceRoot, graph } };
+    }
+    return this.#graph.payload;
+  }
+
+  async #changesPayload(since: string | null): Promise<BuildChangesPayload> {
+    const { workspace, name } = this.#app;
+    const { workspaceRoot } = workspace;
+    const forkPoint = await new GitRevision(workspaceRoot).forkPointOf(since);
+    if (forkPoint.error !== undefined) return { workspaceRoot, changes: { error: forkPoint.error } };
+    const key = `${this.#generation}:${forkPoint.sha}`;
+    if (this.#changes?.key !== key) {
+      const payload = WorkspaceGraph.changesAt(workspace, forkPoint.sha).then((changes) => ({
+        workspaceRoot,
+        changes: WorkspaceGraph.changesVisibleTo(changes, name),
+      }));
+      payload.catch(() => {
+        if (this.#changes?.payload === payload) this.#changes = null;
+      });
+      this.#changes = { key, payload };
+    }
+    return await this.#changes.payload;
+  }
+
   // On demand: dev serves CSR only via the opt-in `/__csr` and `?csr=true` routes; once built, it rebuilds every save.
   async handleBuildCsr(msg: BuilderCsrReq): Promise<void> {
     if (msg.shell) {
@@ -1080,13 +1127,18 @@ class IncrementalBuilder {
         void builder.shutdown(msg.reason);
         return;
       }
-      if (msg.type !== "build-route" && msg.type !== "build-csr") return;
+      if (msg.type !== "build-route" && msg.type !== "build-csr" && msg.type !== "build-graph") return;
       if (!builder || builder.shuttingDown) {
         const error = builder?.shuttingDown ? recyclingError : bootingError;
         BuilderChannel.emit({ type: `${msg.type}-res`, id: msg.id, ok: false, error });
         return;
       }
-      const handled = msg.type === "build-route" ? builder.handleBuildRoute(msg) : builder.handleBuildCsr(msg);
+      const handled =
+        msg.type === "build-route"
+          ? builder.handleBuildRoute(msg)
+          : msg.type === "build-csr"
+            ? builder.handleBuildCsr(msg)
+            : builder.handleBuildGraph(msg);
       // Unhandled, a rejection (an ipc write that failed) would exit the builder and drop the watcher with it.
       void handled.catch((err: unknown) =>
         logger.error(`${msg.type} failed: ${err instanceof Error ? err.message : String(err)}`),

package/lint/__fixtures__/no-daisyui-legacy-class/bad.tsx

@@ -1,5 +1,7 @@
-export const CompoundButton = () => <button className="btn-primary" />; // @flag
-export const CompoundBadge = () => <span className="badge-success" />; // @flag
+export const CompoundButton = () => <button className="btn-primary" />; // @warn
+export const CompoundBadge = () => <span className="badge-success" />; // @warn
+export const CompoundStatValue = () => <div className="md:stat-value" />; // @warn
+export const BothHalvesReportTheColourSlot = () => <div className="btn-primary bg-base-100" />; // @flag
 export const DroppedBaseSurface = () => <div className="bg-base-100" />; // @flag
 export const DroppedBaseContentWithOpacity = () => <div className="text-base-content/70" />; // @flag
 export const DroppedBaseOnABorderSide = () => <div className="border-t-base-300" />; // @flag

package/lint/__fixtures__/no-js-private-class-method/bad.tsx

@@ -1,3 +1,5 @@
 export class SyncPrivate { #compute() { return 1; } } // @flag
 export class AsyncPrivate { async #load() { return 1; } } // @flag
+export class StaticPrivate { static #make() { return 1; } } // @flag
 export class CallsPrivate { run() { this.#compute(); } } // @flag
+export class CallsPrivateOptionally { run() { this.#compute?.(); } } // @flag

package/lint/__fixtures__/no-js-private-class-method/good.tsx

@@ -1,3 +1,4 @@
-export class TypescriptPrivate { private _compute() { return 1; } } // @ok
-export class CallsUnderscore { run() { this._compute(); } } // @ok
+export class TypescriptPrivate { private compute() { return 1; } } // @ok
+export class CallsTypescriptPrivate { run() { this.compute(); } } // @ok
 export class PrivateField { #cache = new Map(); } // @ok
+export class CallsOnAPrivateField { #cache = new Map<string, number>(); run() { return this.#cache.get("a"); } } // @ok

package/lint/no-daisyui-legacy-class.grit

@@ -9,8 +9,10 @@ language js(typescript, jsx)
 // Tailwind or app classes (`card`, `input`, `badge`, `btn`, `divider`) are deliberately not
 // flagged, and colour slots that survived into the semantic vocabulary (`primary`, `info`,
 // `success`, `warning`, `neutral`) are not either — only the slots the vocabulary dropped.
-// Biome keeps only the first diagnostic a single plugin registers on a node, so a string
-// carrying both halves reports the component one and surfaces the colour one on the next run.
+// A component name is a warning: an app's own CSS may define `stat-value`, which this rule cannot read, and
+// `akan verify` drops it when the app's or a lib's stylesheet does (cli verifyStyleClasses.ts).
+// Biome keeps only the first diagnostic a single plugin registers on a node, so the colour slot, an error, is
+// tried first: a string carrying both halves reports it, and the component warning surfaces on the next run.
 or {
   JsxString() as $s,
   JsStringLiteralExpression() as $s,
@@ -18,19 +20,19 @@ or {
 } where {
   any {
     and {
-      $s <: r"[\s\S]*(?:^|[\s\"'`{(\[:!])(?:btn-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|link|outline|square|circle|wide|block|xs|sm|md|lg)|badge-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|outline)|alert-(?:info|success|warning|error)|input-(?:bordered|primary|secondary|accent|ghost|error)|select-(?:bordered|primary|ghost)|textarea-(?:bordered|primary|ghost)|checkbox-(?:primary|secondary|accent)|toggle-(?:primary|secondary|accent)|loading-(?:spinner|dots|ring|ball|bars|infinity)|card-(?:body|title|actions)|modal-(?:box|action|backdrop)|collapse-(?:title|content|arrow|plus)|dropdown-(?:content|end|start|hover)|stat-(?:title|value|desc)|tabs-(?:boxed|lifted|bordered)|tab-active|menu-(?:title|dropdown)|steps-(?:horizontal|vertical)|join-item|mockup-(?:code|phone|browser|window)|drawer-(?:side|content|toggle))(?:[\s\"'`})\]:/!,]|$)[\s\S]*",
+      $s <: r"[\s\S]*(?:^|[\s\"'`{(\[:!])(?:bg|text|border(?:-[tblrxy])?(?:-[se])?|ring(?:-offset)?|fill|stroke|shadow|from|to|via|divide|outline|decoration|placeholder|caret|accent)-(?:base-(?:100|200|300|content)|(?:primary|secondary|accent|neutral|info|success|warning|error)-content|error)(?:[\s\"'`})\]:/!,]|$)[\s\S]*",
       register_diagnostic(
         span = $s,
-        message = "daisyUI legacy class - daisyUI was removed, so this renders unstyled. Use akanjs/ui components and recipes (Button, buttonRecipe, badgeRecipe, ...) with semantic tokens instead.",
+        message = "daisyUI colour slot - the closed colour vocabulary has no CSS for it, so this renders unstyled. base-100/200/300 -> background/muted/border, base-content -> foreground, <colour>-content -> <colour>-foreground, error -> destructive.",
         severity = "error"
       )
     },
     and {
-      $s <: r"[\s\S]*(?:^|[\s\"'`{(\[:!])(?:bg|text|border(?:-[tblrxy])?(?:-[se])?|ring(?:-offset)?|fill|stroke|shadow|from|to|via|divide|outline|decoration|placeholder|caret|accent)-(?:base-(?:100|200|300|content)|(?:primary|secondary|accent|neutral|info|success|warning|error)-content|error)(?:[\s\"'`})\]:/!,]|$)[\s\S]*",
+      $s <: r"[\s\S]*(?:^|[\s\"'`{(\[:!])(?:btn-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|link|outline|square|circle|wide|block|xs|sm|md|lg)|badge-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|outline)|alert-(?:info|success|warning|error)|input-(?:bordered|primary|secondary|accent|ghost|error)|select-(?:bordered|primary|ghost)|textarea-(?:bordered|primary|ghost)|checkbox-(?:primary|secondary|accent)|toggle-(?:primary|secondary|accent)|loading-(?:spinner|dots|ring|ball|bars|infinity)|card-(?:body|title|actions)|modal-(?:box|action|backdrop)|collapse-(?:title|content|arrow|plus)|dropdown-(?:content|end|start|hover)|stat-(?:title|value|desc)|tabs-(?:boxed|lifted|bordered)|tab-active|menu-(?:title|dropdown)|steps-(?:horizontal|vertical)|join-item|mockup-(?:code|phone|browser|window)|drawer-(?:side|content|toggle))(?:[\s\"'`})\]:/!,]|$)[\s\S]*",
       register_diagnostic(
         span = $s,
-        message = "daisyUI colour slot - the closed colour vocabulary has no CSS for it, so this renders unstyled. base-100/200/300 -> background/muted/border, base-content -> foreground, <colour>-content -> <colour>-foreground, error -> destructive.",
-        severity = "error"
+        message = "daisyUI legacy class - daisyUI was removed, so this renders unstyled unless your own CSS defines it. Otherwise use akanjs/ui components and recipes (Button, buttonRecipe, badgeRecipe, ...) with semantic tokens instead.",
+        severity = "warn"
       )
     }
   }

package/lint/no-js-private-class-method.grit

@@ -1,42 +1,23 @@
 engine biome(1.0)
 language js(typescript, jsx)
 
+// No rewrite: one node's rewrite cannot rename every reference, skip a taken name, or leave a `#field` alone, so
+// `akan verify` renames a class's `#method`s and their calls in one pass instead (cli verifyPrivateMethods.ts).
+// A call is matched by its callee, so `this.#cache.get()` on a `#private` field is not a private method call.
 or {
   JsMethodClassMember() as $method where {
-    $method <: contains JsPrivateClassMemberName() as $name,
-    $method <: r"async\s+#",
-    $method <: contains `async` as $asyncToken,
-    $name <: r"#(.*)"($bareName),
-    $privateName = join(list = ["_", $bareName], separator = ""),
+    $method <: contains JsPrivateClassMemberName(),
     register_diagnostic(
       span = $method,
-      message = "JavaScript private class methods (#) should not be used in mixin-enabled modules. Use a TypeScript private method with an underscore prefix instead.",
+      message = "A `#private` method breaks once this class is mixed into another. Use a TypeScript `private` method, `private name()` called as `this.name()`; `akan verify` renames it unless the class already has that name.",
       severity = "error"
-    ),
-    $asyncToken => `private async`,
-    $name => $privateName
+    )
   },
-  JsMethodClassMember() as $method where {
-    $method <: contains JsPrivateClassMemberName() as $name,
-    not $method <: r"async\s+#",
-    $name <: r"#(.*)"($bareName),
-    $privateName = join(list = ["private _", $bareName], separator = ""),
-    register_diagnostic(
-      span = $method,
-      message = "JavaScript private class methods (#) should not be used in mixin-enabled modules. Use a TypeScript private method with an underscore prefix instead.",
-      severity = "error"
-    ),
-    $name => $privateName
-  },
-  JsCallExpression() as $call where {
-    $call <: contains JsPrivateName() as $name,
-    $name <: r"#(.*)"($bareName),
-    $privateName = join(list = ["_", $bareName], separator = ""),
+  JsCallExpression(callee = JsStaticMemberExpression(member = JsPrivateName())) as $call where {
     register_diagnostic(
       span = $call,
-      message = "Calls to JavaScript private class methods (#) should use the underscore-prefixed TypeScript private method.",
+      message = "A call to a `#private` method: call the TypeScript `private` method that replaces it, `this.name()`.",
       severity = "error"
-    ),
-    $name => $privateName
+    )
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.2-rc.2",
+  "version": "3.1.2-rc.4",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -41,7 +41,7 @@
     "./*": "./*.ts"
   },
   "dependencies": {
-    "@akanjs/language": "3.1.2-rc.2",
+    "@akanjs/language": "3.1.2-rc.4",
     "@earendil-works/pi-agent-core": "1.3.0",
     "@earendil-works/pi-ai": "1.3.0",
     "@earendil-works/pi-codemode": "1.3.0",
@@ -50,7 +50,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.1.2-rc.2",
+    "akanjs": "3.1.2-rc.4",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/typeChecker.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import * as ts from "typescript";
+import { tempDirs, writeJson, writeText } from "./testHelpers";
+import { TypeChecker } from "./typeChecker";
+
+const makeTempRoot = tempDirs("akan-devkit-type-checker-");
+
+//? `lib: []` adds global diagnostics (TS2318), and `emitDecoratorMetadata` alone an options one (TS5052).
+const project = async (declaration: boolean) => {
+  const root = await makeTempRoot();
+  const configPath = path.join(root, "tsconfig.json");
+  await writeJson(configPath, {
+    compilerOptions: {
+      strict: true,
+      lib: [],
+      types: [],
+      target: "esnext",
+      module: "esnext",
+      moduleResolution: "bundler",
+      noEmit: true,
+      incremental: true,
+      tsBuildInfoFile: "./.cache/tsconfig.tsbuildinfo",
+      declaration,
+      emitDecoratorMetadata: true,
+    },
+    include: ["src/**/*.ts"],
+  });
+  await writeText(path.join(root, "src/port.ts"), "export const port: number = 8282;\n");
+  await writeText(
+    path.join(root, "src/next.ts"),
+    'import { port } from "./port";\nexport const next: number = port + 1;\n',
+  );
+  await writeText(path.join(root, "src/semantic.ts"), 'export const name: number = "akan";\n');
+  await writeText(path.join(root, "src/syntax.ts"), "export const broken = (;\n");
+  await writeText(path.join(root, "src/declaration.ts"), "export const make = () => class { private secret = 1; };\n");
+  return { root, configPath };
+};
+
+const describeAll = (root: string, diagnostics: readonly ts.Diagnostic[]) =>
+  diagnostics.map((diagnostic) => ({
+    file: diagnostic.file ? path.relative(root, diagnostic.file.fileName) : null,
+    start: diagnostic.start,
+    length: diagnostic.length,
+    code: diagnostic.code,
+    category: diagnostic.category,
+    message: ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"),
+  }));
+
+const preEmitDiagnostics = (root: string, configPath: string) => {
+  const { fileNames, options } = TypeChecker.parseConfig(configPath);
+  return describeAll(root, ts.getPreEmitDiagnostics(ts.createProgram({ rootNames: fileNames, options })));
+};
+
+const nextFileToCheck = (configPath: string) => {
+  const { fileNames, options } = TypeChecker.parseConfig(configPath);
+  const next = ts
+    .createIncrementalProgram({ rootNames: fileNames, options })
+    .getSemanticDiagnosticsOfNextAffectedFile();
+  return next && ("fileName" in next.affected ? next.affected.fileName : "the whole program");
+};
+
+describe("TypeChecker.checkProject", () => {
+  test.each([true, false])(
+    "reports what getPreEmitDiagnostics does, cold and warm (declaration: %p)",
+    async (declaration) => {
+      const { root, configPath } = await project(declaration);
+      const expected = preEmitDiagnostics(root, configPath);
+      expect(new Set(expected.map((diagnostic) => diagnostic.code))).toEqual(
+        new Set([5052, 1109, 2318, 2322, ...(declaration ? [4094] : [])]),
+      );
+
+      expect(describeAll(root, TypeChecker.checkProject(configPath).diagnostics)).toEqual(expected);
+      expect(describeAll(root, TypeChecker.checkProject(configPath).diagnostics)).toEqual(expected);
+    },
+  );
+
+  test("leaves a cache from which a resumed build has no file left to check", async () => {
+    const { configPath } = await project(true);
+    TypeChecker.checkProject(configPath);
+    expect(nextFileToCheck(configPath)).toBeUndefined();
+    TypeChecker.checkProject(configPath);
+    expect(nextFileToCheck(configPath)).toBeUndefined();
+  });
+
+  test("reports an edit's new errors, and its importer's, and drops a fixed one on a warm run", async () => {
+    const { root, configPath } = await project(true);
+    TypeChecker.checkProject(configPath);
+    await writeText(path.join(root, "src/port.ts"), "export const port: string = 8282;\n");
+    await writeText(path.join(root, "src/semantic.ts"), 'export const name: string = "akan";\n');
+
+    const warm = describeAll(root, TypeChecker.checkProject(configPath).diagnostics);
+    expect(warm).toEqual(preEmitDiagnostics(root, configPath));
+    expect(warm.filter((diagnostic) => diagnostic.code === 2322).map((diagnostic) => diagnostic.file)).toEqual([
+      path.join("src", "next.ts"),
+      path.join("src", "port.ts"),
+    ]);
+    expect(nextFileToCheck(configPath)).toBeUndefined();
+  });
+});

package/typeChecker.ts

@@ -177,8 +177,7 @@ export class TypeChecker {
       configFileParsingDiagnostics: parsedConfig.errors,
       host,
     });
-    const program = builderProgram.getProgram();
-    const diagnostics = [...ts.getPreEmitDiagnostics(program), ...builderProgram.emit().diagnostics];
+    const diagnostics = [...TypeChecker.#preEmitDiagnostics(builderProgram), ...builderProgram.emit().diagnostics];
     const errors = diagnostics.filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error);
     const warnings = diagnostics.filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Warning);
     return {
@@ -190,6 +189,19 @@ export class TypeChecker {
     };
   }
 
+  //* getPreEmitDiagnostics on the Program re-checks every file; the builder answers unchanged ones from .tsbuildinfo.
+  static #preEmitDiagnostics(builderProgram: ts.BuilderProgram) {
+    const { declaration, composite } = builderProgram.getCompilerOptions();
+    return ts.sortAndDeduplicateDiagnostics([
+      ...builderProgram.getConfigFileParsingDiagnostics(),
+      ...builderProgram.getOptionsDiagnostics(),
+      ...builderProgram.getSyntacticDiagnostics(),
+      ...builderProgram.getGlobalDiagnostics(),
+      ...builderProgram.getSemanticDiagnostics(),
+      ...(declaration || composite ? builderProgram.getDeclarationDiagnostics() : []),
+    ]);
+  }
+
   static parseConfig(configPath: string): ts.ParsedCommandLine {
     const configFile = ts.readConfigFile(configPath, (fileName) => ts.sys.readFile(fileName));
     const configDiagnostics = configFile.error ? [configFile.error] : [];

package/workspaceGraph.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "bun:test";
+import type { AkanChangeMap, AkanGraphEdge, AkanGraphNode } from "@akanjs/language";
+import { WorkspaceGraph } from "./workspaceGraph";
+
+const node = (id: string, owner: string | null, change?: AkanGraphNode["change"]): AkanGraphNode => ({
+  id,
+  kind: id.split(":")[0] as AkanGraphNode["kind"],
+  name: id,
+  label: id,
+  owner,
+  module: null,
+  detail: [],
+  at: null,
+  ...(change ? { change } : {}),
+});
+const edge = (from: string, to: string, change?: AkanGraphEdge["change"]): AkanGraphEdge => ({
+  from,
+  to,
+  kind: "calls",
+  label: null,
+  count: 1,
+  at: null,
+  ...(change ? { change } : {}),
+});
+
+describe("WorkspaceGraph.changesVisibleTo", () => {
+  it("keeps the app's and the libs' changes, and an unchanged neighbour only while an edge still reaches it", () => {
+    const changes: AkanChangeMap = {
+      version: 1,
+      nodes: [
+        node("endpoint:apps/demo:memo.pin", "apps/demo", "added"),
+        node("method:libs/shared:file.touch", "libs/shared"),
+        node("method:libs/shared:file.open", "libs/shared"),
+        node("component:apps/admin/page/a.tsx#default", "apps/admin", "changed"),
+        node("guard:Owner", null, "added"),
+      ],
+      edges: [
+        edge("endpoint:apps/demo:memo.pin", "method:libs/shared:file.touch", "added"),
+        edge("component:apps/admin/page/a.tsx#default", "method:libs/shared:file.open"),
+      ],
+      since: "0123456789ab",
+      summary: { added: 2, removed: 0, changed: 1 },
+      unmapped: [
+        { file: "apps/admin/page/b.tsx", change: "added" },
+        { file: "apps/demo/lib/memo/memo.dictionary.ts", change: "changed" },
+        { file: "libs/shared/lib/file/file.md", change: "removed" },
+      ],
+    };
+    const visible = WorkspaceGraph.changesVisibleTo(changes, "demo");
+    expect(visible.nodes.map(({ id }) => id)).toEqual([
+      "endpoint:apps/demo:memo.pin",
+      "method:libs/shared:file.touch",
+      "guard:Owner",
+    ]);
+    expect(visible.edges).toHaveLength(1);
+    expect(visible.summary).toEqual({ added: 2, removed: 0, changed: 0 });
+    expect(visible.unmapped.map(({ file }) => file)).toEqual([
+      "apps/demo/lib/memo/memo.dictionary.ts",
+      "libs/shared/lib/file/file.md",
+    ]);
+    expect(visible.since).toBe("0123456789ab");
+  });
+});

package/workspaceGraph.ts

@@ -0,0 +1,177 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { type AkanChangeMap, type AkanGraph, AkanGraphDiff, type AkanGraphNode, AkanIndex } from "@akanjs/language";
+import ts from "typescript";
+import type { Workspace } from "./commandDecorators";
+import { GitRevision } from "./gitRevision";
+
+export interface GraphScope {
+  app?: string | null;
+  module?: string | null;
+}
+
+//? `env/` holds each environment's secrets in plain TypeScript; the graph never needs to read it.
+const indexedPath = /^(apps|libs)\/(?!(?:.*\/)?(?:node_modules|dist|\.akan|env)\/).*\.tsx?$/;
+const hiddenPath = /(?:^|\/)(?:node_modules|dist|\.akan|env)\//;
+const unscopedNodeLimit = 600;
+const cachedBaseLimit = 4;
+const slashed = (fileName: string) => fileName.replace(/\\/g, "/");
+
+export class WorkspaceGraph {
+  static readonly #bases = new Map<string, Promise<AkanGraph>>();
+
+  static async build(workspace: Workspace, { digests = false } = {}): Promise<AkanGraph> {
+    const root = workspace.workspaceRoot;
+    const files = (await workspace.getAllFiles("{apps,libs}/**/*.{ts,tsx}"))
+      .map(slashed)
+      .filter((file) => indexedPath.test(file));
+    return WorkspaceGraph.#graphOf(root, await WorkspaceGraph.#textsOf(root, files), digests);
+  }
+
+  static async #textsOf(root: string, files: string[]) {
+    const read = await Promise.all(
+      files.map(async (file) => [file, await readFile(path.join(root, file), "utf8").catch(() => null)] as const),
+    );
+    return new Map(read.filter((entry): entry is readonly [string, string] => entry[1] !== null));
+  }
+
+  static async changes(workspace: Workspace, since: string | null): Promise<AkanChangeMap | { error: string }> {
+    const forkPoint = await new GitRevision(workspace.workspaceRoot).forkPointOf(since);
+    if (forkPoint.error !== undefined) return { error: forkPoint.error };
+    return await WorkspaceGraph.changesAt(workspace, forkPoint.sha);
+  }
+
+  static async changesAt(workspace: Workspace, sha: string): Promise<AkanChangeMap> {
+    const root = workspace.workspaceRoot;
+    const git = new GitRevision(root);
+    const [before, after, files] = await Promise.all([
+      WorkspaceGraph.#baseAt(root, sha),
+      git
+        .workingFiles()
+        .then((working) =>
+          WorkspaceGraph.#textsOf(
+            root,
+            working.filter((file) => indexedPath.test(file)),
+          ),
+        )
+        .then((texts) => WorkspaceGraph.#graphOf(root, texts, true)),
+      git.changedFilesSince(sha),
+    ]);
+    const changes = AkanGraphDiff.between(before, after);
+    const mapped = new Set([
+      ...changes.nodes
+        .filter((node) => node.change)
+        .flatMap((node) => [
+          node.at?.file,
+          ...(node.fields ?? []).filter((field) => field.change).map(({ at }) => at.file),
+        ]),
+      ...changes.edges.filter((edge) => edge.change).map((edge) => edge.at?.file),
+    ]);
+    const unmapped = files.filter(({ file }) => !mapped.has(file) && !hiddenPath.test(file));
+    return { ...changes, since: sha.slice(0, 12), unmapped };
+  }
+
+  static #baseAt(root: string, sha: string) {
+    const key = `${root}\n${sha}`;
+    const cached = WorkspaceGraph.#bases.get(key);
+    if (cached) return cached;
+    const graph = new GitRevision(root)
+      .filesAt(sha, (file) => indexedPath.test(file))
+      .then((texts) => WorkspaceGraph.#graphOf(root, texts, true));
+    graph.catch(() => WorkspaceGraph.#bases.delete(key));
+    WorkspaceGraph.#bases.set(key, graph);
+    for (const old of [...WorkspaceGraph.#bases.keys()].slice(0, -cachedBaseLimit)) WorkspaceGraph.#bases.delete(old);
+    return graph;
+  }
+
+  static #graphOf(root: string, texts: Map<string, string>, digests: boolean) {
+    const index = new AkanIndex({ ts, root });
+    const byFileName = new Map<string, string>();
+    for (const [file, text] of texts) {
+      const fileName = slashed(path.join(root, file));
+      byFileName.set(fileName, text);
+      index.setFile(fileName, text);
+    }
+    return index.graph((fileName) => byFileName.get(fileName), { digests });
+  }
+
+  static scope(graph: AkanGraph, { app, module }: GraphScope): AkanGraph {
+    if (!app && !module) return graph;
+    const owners = app ? new Set([`apps/${app}`, `libs/${app}`]) : null;
+    const seeds = new Set(
+      graph.nodes
+        .filter((node) => (!owners || owners.has(node.owner ?? "")) && (!module || node.module === module))
+        .map((node) => node.id),
+    );
+    const edges = graph.edges.filter((edge) => seeds.has(edge.from) || seeds.has(edge.to));
+    const ids = new Set([...seeds, ...edges.flatMap((edge) => [edge.from, edge.to])]);
+    return { version: 1, nodes: graph.nodes.filter((node) => ids.has(node.id)), edges };
+  }
+
+  static visibleTo(graph: AkanGraph, app: string): AkanGraph {
+    const appOwner = `apps/${app}`;
+    const isVisible = ({ owner }: AkanGraphNode) => !owner || owner === appOwner || owner.startsWith("libs/");
+    const nodes = graph.nodes.filter(isVisible);
+    const ids = new Set(nodes.map((node) => node.id));
+    return { version: 1, nodes, edges: graph.edges.filter((edge) => ids.has(edge.from) && ids.has(edge.to)) };
+  }
+
+  static changesVisibleTo(changes: AkanChangeMap, app: string): AkanChangeMap {
+    const visible = WorkspaceGraph.visibleTo(changes, app);
+    const linked = new Set(visible.edges.flatMap((edge) => [edge.from, edge.to]));
+    const nodes = visible.nodes.filter((node) => node.change || linked.has(node.id));
+    const appPath = `apps/${app}/`;
+    return {
+      ...changes,
+      nodes,
+      edges: visible.edges,
+      summary: WorkspaceGraph.#summaryOf(nodes),
+      unmapped: changes.unmapped.filter(({ file }) => file.startsWith(appPath) || file.startsWith("libs/")),
+    };
+  }
+
+  static #summaryOf(nodes: AkanGraphNode[]) {
+    const summary = { added: 0, removed: 0, changed: 0 };
+    for (const { change } of nodes) if (change) summary[change] += 1;
+    return summary;
+  }
+
+  static answerChanges(changes: AkanChangeMap | { error: string }, scope: GraphScope) {
+    if ("error" in changes)
+      return {
+        diagnostics: [{ severity: "error", code: "graph-since-unknown", message: changes.error, input: "since" }],
+      };
+    const answer = WorkspaceGraph.answer(
+      changes,
+      scope,
+      changes.nodes.filter((node) => node.change),
+    );
+    if ("diagnostics" in answer) return { since: changes.since, summary: changes.summary, ...answer };
+    const summary = WorkspaceGraph.#summaryOf(answer.nodes);
+    const owners = scope.app ? [`apps/${scope.app}/`, `libs/${scope.app}/`] : null;
+    const modules = scope.module ? [`/lib/${scope.module}/`, `/lib/_${scope.module}/`] : null;
+    const unmapped = changes.unmapped.filter(
+      ({ file }) =>
+        (!owners || owners.some((owner) => file.startsWith(owner))) &&
+        (!modules || modules.some((segment) => file.includes(segment))),
+    );
+    return { since: changes.since, summary, ...answer, unmapped };
+  }
+
+  static answer(graph: AkanGraph, scope: GraphScope, counted = graph.nodes) {
+    if (scope.app || scope.module || graph.nodes.length <= unscopedNodeLimit) return WorkspaceGraph.scope(graph, scope);
+    const owners = new Map<string, number>();
+    for (const node of counted) if (node.owner) owners.set(node.owner, (owners.get(node.owner) ?? 0) + 1);
+    return {
+      diagnostics: [
+        {
+          severity: "error",
+          code: "graph-scope-required",
+          message: `The graph has ${graph.nodes.length} nodes. Pass app, module or both to scope it.`,
+          input: "app",
+        },
+      ],
+      owners: Object.fromEntries([...owners].sort(([a], [b]) => (a < b ? -1 : 1))),
+    };
+  }
+}