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

package/workflow/types.ts

@@ -74,6 +74,7 @@ export interface WorkflowInputSpec {
   required?: boolean;
   description: string;
   allowedValues?: readonly string[];
+  mustExist?: boolean;
 }
 
 export interface WorkflowStep {

package/workspaceGraph.test.ts

@@ -0,0 +1,121 @@
+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");
+  });
+});
+
+describe("WorkspaceGraph.answer", () => {
+  it("answers a small graph whole, and drops untouched pages and their route-only guards from one past the limit", () => {
+    const fillers = Array.from({ length: 597 }, (_, idx) => node(`method:apps/demo:memo.m${idx}`, "apps/demo"));
+    const guard = { ...node("guard:libs/shared:signedIn", "libs/shared"), detail: ["route"] };
+    const graph = {
+      version: 1 as const,
+      nodes: [
+        node("layout:apps/demo:/", "apps/demo"),
+        node("route:apps/demo:/memo", "apps/demo"),
+        node("route:apps/demo:/peek", "apps/demo"),
+        node("endpoint:apps/demo:memo.pin", "apps/demo", "changed"),
+        guard,
+        ...fillers,
+      ],
+      edges: [
+        edge("layout:apps/demo:/", "route:apps/demo:/memo"),
+        edge("layout:apps/demo:/", "route:apps/demo:/peek"),
+        edge("layout:apps/demo:/", "guard:libs/shared:signedIn"),
+        edge("route:apps/demo:/peek", "endpoint:apps/demo:memo.pin"),
+      ],
+    };
+    const small = WorkspaceGraph.answer({ ...graph, nodes: graph.nodes.slice(0, 5) }, {});
+    if ("diagnostics" in small) throw new Error("expected an answer");
+    expect(small.nodes).toHaveLength(5);
+    const unscoped = WorkspaceGraph.answer(graph, {});
+    if ("diagnostics" in unscoped) throw new Error("expected an answer");
+    expect(unscoped.nodes.slice(0, 2).map(({ id }) => id)).toEqual([
+      "route:apps/demo:/peek",
+      "endpoint:apps/demo:memo.pin",
+    ]);
+    expect(unscoped.nodes).toHaveLength(599);
+    expect(unscoped.edges.map(({ from, to }) => `${from} -> ${to}`)).toEqual([
+      "route:apps/demo:/peek -> endpoint:apps/demo:memo.pin",
+    ]);
+    const scoped = WorkspaceGraph.answer(graph, { app: "demo" });
+    if ("diagnostics" in scoped) throw new Error("expected an answer");
+    expect(scoped.nodes).toHaveLength(602);
+  });
+});
+
+describe("WorkspaceGraph.scope", () => {
+  it("keeps a lib's guard without pulling in every app endpoint that uses it", () => {
+    const guard = "guard:libs/shared:Admin";
+    const own = "endpoint:libs/shared:file.touch";
+    const other = "endpoint:apps/demo:memo.pin";
+    const scoped = WorkspaceGraph.scope(
+      {
+        version: 1,
+        nodes: [node(guard, "libs/shared"), node(own, "libs/shared"), node(other, "apps/demo")],
+        edges: [edge(own, guard), edge(other, guard)],
+      },
+      { app: "shared" },
+    );
+    expect(scoped.nodes.map(({ id }) => id)).toEqual([guard, own]);
+    expect(scoped.edges).toEqual([edge(own, guard)]);
+  });
+});

package/workspaceGraph.ts

@@ -1,8 +1,9 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { type AkanGraph, type AkanGraphNode, AkanIndex } from "@akanjs/language";
+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;
@@ -11,26 +12,88 @@ export interface GraphScope {
 
 //? `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 pageKinds = new Set<AkanGraphNode["kind"]>(["route", "layout"]);
+const cachedBaseLimit = 4;
 const slashed = (fileName: string) => fileName.replace(/\\/g, "/");
 
 export class WorkspaceGraph {
-  static async build(workspace: Workspace): Promise<AkanGraph> {
+  static readonly #bases = new Map<string, Promise<AkanGraph>>();
+
+  static async build(workspace: Workspace, { digests = false } = {}): Promise<AkanGraph> {
     const root = workspace.workspaceRoot;
-    const index = new AkanIndex({ ts, root });
-    const texts = new Map<string, string>();
     const files = (await workspace.getAllFiles("{apps,libs}/**/*.{ts,tsx}"))
       .map(slashed)
       .filter((file) => indexedPath.test(file));
-    await Promise.all(
-      files.map(async (file) => {
-        const fileName = slashed(path.join(root, file));
-        const text = await readFile(fileName, "utf8");
-        texts.set(fileName, text);
-        index.setFile(fileName, text);
-      }),
+    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 index.graph((fileName) => texts.get(fileName));
+    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 {
@@ -41,11 +104,36 @@ export class WorkspaceGraph {
         .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));
+    //? A lib's guard is linked from every app's endpoints; through it, a scope would reach all of them.
+    const guards = new Set(graph.nodes.filter((node) => node.kind === "guard").map((node) => node.id));
+    const reaches = (id: string) => seeds.has(id) && !guards.has(id);
+    const edges = graph.edges.filter((edge) => reaches(edge.from) || reaches(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 };
   }
 
+  //? Pages are many and most only wrap one another, so a graph too large to answer whole drops the pages that neither
+  //? changed nor use a change first, and the route-only guards they leave unlinked.
+  static #withoutPages(graph: AkanGraph): AkanGraph {
+    const changed = new Set(graph.nodes.filter((node) => node.change).map((node) => node.id));
+    const touching = new Set(
+      graph.edges
+        .filter((edge) => edge.kind !== "wraps" && (changed.has(edge.from) || changed.has(edge.to)))
+        .flatMap((edge) => [edge.from, edge.to]),
+    );
+    const dropped = new Set(
+      graph.nodes
+        .filter((node) => pageKinds.has(node.kind) && !node.change && !touching.has(node.id))
+        .map((node) => node.id),
+    );
+    const edges = graph.edges.filter((edge) => !dropped.has(edge.from) && !dropped.has(edge.to));
+    const linked = new Set(edges.flatMap((edge) => [edge.from, edge.to]));
+    const isRouteOnly = (node: AkanGraphNode) =>
+      node.kind === "guard" && node.detail.includes("route") && !node.change && !linked.has(node.id);
+    const nodes = graph.nodes.filter((node) => !dropped.has(node.id) && !isRouteOnly(node));
+    return { version: 1, nodes, edges };
+  }
+
   static visibleTo(graph: AkanGraph, app: string): AkanGraph {
     const appOwner = `apps/${app}`;
     const isVisible = ({ owner }: AkanGraphNode) => !owner || owner === appOwner || owner.startsWith("libs/");
@@ -54,16 +142,61 @@ export class WorkspaceGraph {
     return { version: 1, nodes, edges: graph.edges.filter((edge) => ids.has(edge.from) && ids.has(edge.to)) };
   }
 
-  static answer(graph: AkanGraph, scope: GraphScope) {
+  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 unscoped = WorkspaceGraph.#withoutPages(graph);
+    if (unscoped.nodes.length <= unscopedNodeLimit) return unscoped;
     const owners = new Map<string, number>();
-    for (const node of graph.nodes) if (node.owner) owners.set(node.owner, (owners.get(node.owner) ?? 0) + 1);
+    for (const node of counted)
+      if (node.owner && !pageKinds.has(node.kind)) 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.`,
+          message: `The graph has ${unscoped.nodes.length} nodes besides its pages. Pass app, module or both to scope it.`,
           input: "app",
         },
       ],

package/workspaceLayout.ts

@@ -8,6 +8,7 @@ export const appRootAllowedFiles = new Set([
   "CLAUDE.md",
   "akan.app.json",
   "akan.baseline.json",
+  "akan.budget.json",
   "akan.config.ts",
   "client.ts",
   "main.ts",