@akanjs/devkit 3.2.0-rc.1 → 3.2.0-rc.3

package/workflow/plan.ts

@@ -1,10 +1,11 @@
 import { capitalize } from "akanjs/common";
 import type { Sys, Workspace } from "../commandDecorators";
-import { workflowPlanApproval } from "./artifacts";
+import { withoutApplyHints, workflowPlanApproval } from "./artifacts";
 import { resolveWorkflowSys } from "./executor";
 import { InteractionScaffold } from "./interactionScaffold";
 import { KeyRename } from "./keyRename";
 import { MutationScaffold } from "./mutationScaffold";
+import { identifierPattern, sysNamePattern } from "./plainName";
 import { coerceFieldDefault, getSysRoot, moduleSourcePaths } from "./source";
 import type {
   WorkflowDiagnostic,
@@ -17,11 +18,10 @@ import type {
   WorkflowSurfaceMode,
 } from "./types";
 import { addFieldUiPolicyForType } from "./uiPolicy";
+import { workflowStatus } from "./utils";
 
 const surfaceModes = new Set<WorkflowSurfaceMode>(["infer", "include", "skip"]);
 
-const sysNamePattern = /^[a-z0-9][a-zA-Z0-9_-]*$/;
-const identifierPattern = /^_{0,2}[a-zA-Z][a-zA-Z0-9_-]*$/;
 //? These inputs become path segments, identifiers and command arguments, so none may carry a separator or a dot.
 const nameInputPatterns: Record<string, RegExp> = {
   app: sysNamePattern,
@@ -35,11 +35,6 @@ const nameInputPatterns: Record<string, RegExp> = {
   interaction: identifierPattern,
 };
 
-export const isWorkflowSysName = (value: unknown): value is string =>
-  typeof value === "string" && sysNamePattern.test(value);
-export const isWorkflowModuleName = (value: unknown): value is string =>
-  typeof value === "string" && identifierPattern.test(value);
-
 const parseStringList = (value: unknown) => {
   if (Array.isArray(value)) {
     const values = value.filter((item): item is string => typeof item === "string" && item.trim().length > 0);
@@ -487,7 +482,7 @@ const syssHolding = async (workspace: Workspace, module: string, except: Sys) =>
       .map(async (name) => await resolveWorkflowSys(workspace, name)),
   );
   const holding = await Promise.all(
-    others.map(async (other) => (other && (await other.readdir("lib")).includes(module) ? other : null)),
+    others.map(async (other) => (other && (await other.getDatabaseModules()).includes(module) ? other : null)),
   );
   return holding.filter((other): other is Sys => other !== null);
 };
@@ -495,24 +490,53 @@ const syssHolding = async (workspace: Workspace, module: string, except: Sys) =>
 const moduleMissing = async (workspace: Workspace, sys: Sys, module: string): Promise<WorkflowDiagnostic | null> => {
   if ((await sys.readdir("lib")).includes(module)) return null;
   const root = getSysRoot(sys);
-  const modules = [...(await sys.getDatabaseModules()), ...(await sys.getServiceModules())];
-  const sameName = modules.find((name) => name.replace(/^_/, "").toLowerCase() === module.toLowerCase());
+  const modules = await sys.getDatabaseModules();
+  const sameName = modules.find((name) => name.toLowerCase() === module.toLowerCase());
+  const service = (await sys.getServiceModules()).find(
+    (name) => name.replace(/^_/, "").toLowerCase() === module.replace(/^_/, "").toLowerCase(),
+  );
   const isScalar = (await sys.getScalarModules()).includes(module);
-  const [holder] = sameName || isScalar ? [] : await syssHolding(workspace, module, sys);
+  const [holder] = sameName || service || isScalar ? [] : await syssHolding(workspace, module, sys);
   return {
     severity: "error",
     code: "workflow-module-missing",
     input: "module",
     message: [
       `No module named ${module} in ${root}: ${root}/lib/${module} does not exist.`,
-      modules.length ? `Its modules are ${modules.join(", ")}.` : `${root} has no modules yet.`,
+      modules.length ? `Its database modules are ${modules.join(", ")}.` : `${root} has no database modules yet.`,
       sameName
         ? `Did you mean ${sameName}?`
-        : isScalar
-          ? `${root}/lib/__scalar/${module} is a scalar, and this workflow writes only into a module under ${root}/lib.`
-          : holder
-            ? `${module} is in ${getSysRoot(holder)}, so plan this with --app ${holder.name}.`
-            : `If ${module} is a new model, create it with the create-module workflow first, then plan this again.`,
+        : service
+          ? `${root}/lib/${service} is a service module, which stores no model, and this workflow writes only into a database module.`
+          : isScalar
+            ? `${root}/lib/__scalar/${module} is a scalar, and this workflow writes only into a module under ${root}/lib.`
+            : holder
+              ? `${module} is in ${getSysRoot(holder)}, so plan this with --app ${holder.name}.`
+              : `If ${module} is a new model, create it with the create-module workflow first, then plan this again.`,
+    ].join(" "),
+  };
+};
+
+const moduleNotDatabase = async (sys: Sys, spec: WorkflowSpec, module: string): Promise<WorkflowDiagnostic | null> => {
+  const databaseModules = await sys.getDatabaseModules();
+  if (databaseModules.includes(module)) return null;
+  const root = getSysRoot(sys);
+  const isServiceModule = module.startsWith("_") && !module.startsWith("__");
+  return {
+    severity: "error",
+    code: "workflow-module-not-database",
+    input: "module",
+    message: [
+      isServiceModule
+        ? `${module} in ${root} is a service module, which stores no model.`
+        : `${root}/lib/${module} is not a database module: it has no ${module}.constant.ts.`,
+      `${spec.name} needs a database module, one with lib/<model>/<model>.constant.ts.`,
+      databaseModules.length
+        ? `Its database modules are ${databaseModules.join(", ")}.`
+        : `${root} has no database modules yet.`,
+      spec.inputs.field
+        ? "Add the field to one of them, or create its model with the create-module workflow first; a value several models embed is a scalar, made with create-scalar and added to a model as a field of that type."
+        : "Plan this on one of them, or create the model with the create-module workflow first.",
     ].join(" "),
   };
 };
@@ -539,11 +563,11 @@ export const workflowTargetDiagnostics = async (
   const module = planString(inputs, "module");
   const moduleSpec: WorkflowInputSpec | undefined = spec.inputs.module;
   if (!module || !moduleSpec?.mustExist) return [];
-  const missing = await moduleMissing(workspace, sys, module);
-  return missing ? [missing] : [];
+  const refused = (await moduleMissing(workspace, sys, module)) ?? (await moduleNotDatabase(sys, spec, module));
+  return refused ? [refused] : [];
 };
 
-export const inspectWorkflowPlan = async (
+const inspectPlanTarget = async (
   workspace: Workspace,
   spec: WorkflowSpec,
   plan: WorkflowPlan,
@@ -586,3 +610,13 @@ export const inspectWorkflowPlan = async (
     recommendations: [...plan.recommendations, ...inspected.recommendations],
   };
 };
+
+export const inspectWorkflowPlan = async (
+  workspace: Workspace,
+  spec: WorkflowSpec,
+  plan: WorkflowPlan,
+): Promise<WorkflowPlan> => {
+  const inspected = await inspectPlanTarget(workspace, spec, plan);
+  if (workflowStatus(inspected.diagnostics) === "passed") return inspected;
+  return { ...inspected, recommendations: withoutApplyHints(inspected.recommendations) };
+};

package/workspaceGraph.test.ts

@@ -1,7 +1,17 @@
-import { describe, expect, it } from "bun:test";
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
 import type { AkanChangeMap, AkanGraphEdge, AkanGraphNode } from "@akanjs/language";
+import { AkanGraphDiff } from "@akanjs/language";
+import type { Workspace } from "./commandDecorators";
 import { WorkspaceGraph } from "./workspaceGraph";
 
+const roots: string[] = [];
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
 const node = (id: string, owner: string | null, change?: AkanGraphNode["change"]): AkanGraphNode => ({
   id,
   kind: id.split(":")[0] as AkanGraphNode["kind"],
@@ -13,10 +23,15 @@ const node = (id: string, owner: string | null, change?: AkanGraphNode["change"]
   at: null,
   ...(change ? { change } : {}),
 });
-const edge = (from: string, to: string, change?: AkanGraphEdge["change"]): AkanGraphEdge => ({
+const edge = (
+  from: string,
+  to: string,
+  change?: AkanGraphEdge["change"],
+  kind: AkanGraphEdge["kind"] = "calls",
+): AkanGraphEdge => ({
   from,
   to,
-  kind: "calls",
+  kind,
   label: null,
   count: 1,
   at: null,
@@ -102,6 +117,60 @@ describe("WorkspaceGraph.answer", () => {
   });
 });
 
+describe("WorkspaceGraph.answer past the node limit", () => {
+  const changeMapOf = (nodes: AkanGraphNode[], edges: AkanGraphEdge[]): AkanChangeMap => ({
+    version: 1,
+    nodes,
+    edges,
+    since: "0123456789ab",
+    summary: { added: 0, removed: 0, changed: nodes.filter((item) => item.change).length },
+    unmapped: [],
+  });
+
+  it("drops the layout that only wraps a changed route, and keeps the route", () => {
+    const fillers = Array.from({ length: 599 }, (_, idx) => node(`method:apps/demo:memo.m${idx}`, "apps/demo"));
+    const answer = WorkspaceGraph.answer(
+      {
+        version: 1,
+        nodes: [
+          node("layout:apps/demo:/", "apps/demo"),
+          node("route:apps/demo:/memo", "apps/demo", "changed"),
+          ...fillers,
+        ],
+        edges: [edge("layout:apps/demo:/", "route:apps/demo:/memo", undefined, "wraps")],
+      },
+      {},
+    );
+    if ("diagnostics" in answer) throw new Error("expected an answer");
+    expect(answer.nodes.filter((item) => item.kind !== "method").map(({ id }) => id)).toEqual([
+      "route:apps/demo:/memo",
+    ]);
+    expect(answer.edges).toEqual([]);
+  });
+
+  it("answers a Change Map whole once its unchanged pages are set aside", () => {
+    const routes = Array.from({ length: 10 }, (_, idx) => node(`route:apps/demo:/r${idx}`, "apps/demo"));
+    const changed = Array.from({ length: 595 }, (_, idx) =>
+      node(`method:apps/demo:memo.m${idx}`, "apps/demo", "changed"),
+    );
+    const answer = WorkspaceGraph.answerChanges(changeMapOf([...routes, ...changed], []), {});
+    if ("diagnostics" in answer) throw new Error("expected an answer");
+    expect(answer.nodes).toHaveLength(595);
+    expect(answer.summary).toEqual({ added: 0, removed: 0, changed: 595 });
+  });
+
+  it("counts the changed pages it keeps when it names the owners to scope to", () => {
+    const routes = Array.from({ length: 650 }, (_, idx) => node(`route:apps/demo:/r${idx}`, "apps/demo", "changed"));
+    const answer = WorkspaceGraph.answerChanges(
+      changeMapOf([...routes, node("method:libs/shared:file.touch", "libs/shared", "changed")], []),
+      {},
+    );
+    if (!("owners" in answer)) throw new Error("expected a scope request");
+    expect(answer.diagnostics.map(({ message }) => message).join("\n")).toContain("651 nodes");
+    expect(answer.owners).toEqual({ "apps/demo": 650, "libs/shared": 1 });
+  });
+});
+
 describe("WorkspaceGraph.scope", () => {
   it("keeps a lib's guard without pulling in every app endpoint that uses it", () => {
     const guard = "guard:libs/shared:Admin";
@@ -118,4 +187,132 @@ describe("WorkspaceGraph.scope", () => {
     expect(scoped.nodes.map(({ id }) => id)).toEqual([guard, own]);
     expect(scoped.edges).toEqual([edge(own, guard)]);
   });
+
+  it("follows a role the scope's method calls to the implementation its app binds", () => {
+    const role = "adaptor::LlmAdaptorRole";
+    const binds = (to: string, label: string): AkanGraphEdge => ({ ...edge(role, to), kind: "binds", label });
+    const graph = {
+      version: 1 as const,
+      nodes: [
+        { ...node("method:apps/sceny:plan.draft", "apps/sceny"), module: "plan" },
+        { ...node("method:apps/angelo:chat.reply", "apps/angelo"), module: "chat" },
+        { ...node("method:libs/genai:prompt.run", "libs/genai"), module: "prompt" },
+        node(role, null),
+        node("adaptor::AnthropicLlm", null),
+        node("adaptor:apps/angelo:ChatCompletionsLlm", "apps/angelo"),
+        node("adaptor:libs/genai:GenaiLlm", "libs/genai"),
+      ],
+      edges: [
+        edge("method:apps/sceny:plan.draft", role),
+        edge("method:apps/angelo:chat.reply", role),
+        edge("method:libs/genai:prompt.run", role),
+        binds("adaptor::AnthropicLlm", "apps/sceny"),
+        binds("adaptor:apps/angelo:ChatCompletionsLlm", "apps/angelo"),
+        binds("adaptor:libs/genai:GenaiLlm", "libs/genai"),
+      ],
+    };
+    const bound = (scope: { app?: string; module?: string }) =>
+      WorkspaceGraph.scope(graph, scope)
+        .edges.filter(({ kind }) => kind === "binds")
+        .map(({ to, label }) => `${label} ${to}`);
+    expect(bound({ app: "sceny" })).toEqual(["apps/sceny adaptor::AnthropicLlm"]);
+    expect(WorkspaceGraph.scope(graph, { app: "sceny" }).nodes.map(({ id }) => id)).toContain("adaptor::AnthropicLlm");
+    expect(bound({ app: "angelo" })).toEqual(["apps/angelo adaptor:apps/angelo:ChatCompletionsLlm"]);
+    expect(bound({ app: "genai" })).toEqual([
+      "apps/sceny adaptor::AnthropicLlm",
+      "apps/angelo adaptor:apps/angelo:ChatCompletionsLlm",
+      "libs/genai adaptor:libs/genai:GenaiLlm",
+    ]);
+    expect(bound({ module: "plan" })).toHaveLength(3);
+    expect(
+      WorkspaceGraph.visibleTo(graph, "sceny")
+        .edges.filter(({ kind }) => kind === "binds")
+        .map(({ label }) => label),
+    ).toEqual(["apps/sceny"]);
+  });
+
+  it("scopes a Change Map to the binding the app runs, whether or not that binding changed", () => {
+    const role = "adaptor::LlmAdaptorRole";
+    const versioned = (id: string, owner: string | null, digest: string, module: string | null = null) => ({
+      ...node(id, owner),
+      module,
+      digest,
+      at: { file: `${owner ?? "akanjs"}/x.ts`, line: 1, column: 1 },
+    });
+    const binds = (to: string, label: string): AkanGraphEdge => ({ ...edge(role, to), kind: "binds", label });
+    const graphOf = (ownBinding: boolean, method: string, lib: string) => ({
+      version: 1 as const,
+      nodes: [
+        versioned("method:apps/sceny:plan.draft", "apps/sceny", method, "plan"),
+        node(role, null),
+        node("adaptor::AnthropicLlm", null),
+        versioned("adaptor:libs/genai:GenaiLlm", "libs/genai", lib),
+      ],
+      edges: [
+        edge("method:apps/sceny:plan.draft", role),
+        ...(ownBinding ? [binds("adaptor::AnthropicLlm", "apps/sceny")] : []),
+        binds("adaptor:libs/genai:GenaiLlm", "libs/genai"),
+      ],
+    });
+    const scopedBinds = (base: ReturnType<typeof graphOf>, head: ReturnType<typeof graphOf>) => {
+      const changes = { ...AkanGraphDiff.between(base, head), since: "0123456789ab", unmapped: [] };
+      const answer = WorkspaceGraph.answerChanges(changes, { app: "sceny" });
+      if (!("edges" in answer)) throw new Error("expected an answer");
+      return answer.edges
+        .filter(({ kind }) => kind === "binds")
+        .map(({ label, to, change }) => `${change ?? "unchanged"} ${label} ${to}`);
+    };
+    expect(scopedBinds(graphOf(true, "1", "1"), graphOf(true, "2", "2"))).toEqual([
+      "unchanged apps/sceny adaptor::AnthropicLlm",
+    ]);
+    expect(scopedBinds(graphOf(true, "1", "1"), graphOf(false, "1", "2"))).toEqual([
+      "unchanged libs/genai adaptor:libs/genai:GenaiLlm",
+      "removed apps/sceny adaptor::AnthropicLlm",
+    ]);
+  });
+});
+
+describe("WorkspaceGraph.changesAt", () => {
+  it("maps an edit to a factory in one lib onto the guards it makes in another, and lists no file as unmapped", async () => {
+    const root = await mkdtemp(path.join(tmpdir(), "akan-graph-"));
+    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);
+    };
+    const factory = (body: string) => `import type { Guard } from "akanjs/signal";
+export const resourceGuard = (field: string) =>
+  class implements Guard {
+    canPass() {
+      return ${body};
+    }
+  };
+`;
+    git("init", "-q", "-b", "main");
+    await write("libs/util/srvkit/resource.ts", factory("!!field"));
+    await write(
+      "apps/demo/srvkit/guards.ts",
+      `import { resourceGuard } from "@libs/util/srvkit";\nexport const Member = resourceGuard("member");\n`,
+    );
+    git("add", "-A");
+    git("commit", "-q", "--no-verify", "-m", "base");
+    await write("libs/util/srvkit/resource.ts", factory("field.length > 0"));
+    const changes = await WorkspaceGraph.changesAt(
+      { workspaceRoot: root } as unknown as Workspace,
+      git("rev-parse", "HEAD"),
+    );
+    expect(changes.nodes.filter((node) => node.change).map(({ id, change }) => `${change} ${id}`)).toEqual([
+      "changed guard:apps/demo:Member",
+    ]);
+    expect(changes.unmapped).toEqual([]);
+    expect(changes.nodes.some((node) => "sources" in node)).toBe(false);
+  });
 });

package/workspaceGraph.ts

@@ -1,6 +1,13 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { type AkanChangeMap, type AkanGraph, AkanGraphDiff, type AkanGraphNode, AkanIndex } from "@akanjs/language";
+import {
+  type AkanChangeMap,
+  type AkanGraph,
+  AkanGraphDiff,
+  type AkanGraphEdge,
+  type AkanGraphNode,
+  AkanIndex,
+} from "@akanjs/language";
 import ts from "typescript";
 import type { Workspace } from "./commandDecorators";
 import { GitRevision } from "./gitRevision";
@@ -64,12 +71,14 @@ export class WorkspaceGraph {
         .filter((node) => node.change)
         .flatMap((node) => [
           node.at?.file,
+          ...(node.sources ?? []),
           ...(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 };
+    const nodes = changes.nodes.map(({ sources: _sources, ...node }) => node);
+    return { ...changes, nodes, since: sha.slice(0, 12), unmapped };
   }
 
   static #baseAt(root: string, sha: string) {
@@ -107,9 +116,30 @@ export class WorkspaceGraph {
     //? 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 };
+    const edges = graph.edges.filter((edge) => edge.kind !== "binds" && (reaches(edge.from) || reaches(edge.to)));
+    const kept = new Set([...seeds, ...edges.flatMap((edge) => [edge.from, edge.to])]);
+    const isLib =
+      !!app &&
+      graph.nodes.some((node) => node.owner === `libs/${app}`) &&
+      !graph.nodes.some((node) => node.owner === `apps/${app}`);
+    const applicable = WorkspaceGraph.#bindingsOf(graph, app && !isLib ? `apps/${app}` : null);
+    const isOwn = (edge: AkanGraphEdge) => !module && !!owners?.has(edge.label ?? "");
+    const roles = new Set(
+      applicable.filter((edge) => isOwn(edge) || kept.has(edge.from) || reaches(edge.to)).map((edge) => edge.from),
+    );
+    const bindings = applicable.filter((edge) => roles.has(edge.from));
+    const ids = new Set([...kept, ...bindings.flatMap((edge) => [edge.from, edge.to])]);
+    return { version: 1, nodes: graph.nodes.filter((node) => ids.has(node.id)), edges: [...edges, ...bindings] };
+  }
+
+  //? An app runs a role as its own `applyAdaptor` binds it, else as a lib's does; a lib's code runs under every app's.
+  static #bindingsOf(graph: AkanGraph, appOwner: string | null) {
+    const binds = graph.edges.filter((edge) => edge.kind === "binds");
+    if (!appOwner) return binds;
+    const own = new Set(
+      binds.filter((edge) => edge.label === appOwner && edge.change !== "removed").map((edge) => edge.from),
+    );
+    return binds.filter((edge) => edge.label === appOwner || (!edge.label?.startsWith("apps/") && !own.has(edge.from)));
   }
 
   //? Pages are many and most only wrap one another, so a graph too large to answer whole drops the pages that neither
@@ -139,7 +169,14 @@ export class WorkspaceGraph {
     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)) };
+    const bindings = new Set(WorkspaceGraph.#bindingsOf(graph, appOwner));
+    return {
+      version: 1,
+      nodes,
+      edges: graph.edges.filter(
+        (edge) => ids.has(edge.from) && ids.has(edge.to) && (edge.kind !== "binds" || bindings.has(edge)),
+      ),
+    };
   }
 
   static changesVisibleTo(changes: AkanChangeMap, app: string): AkanChangeMap {
@@ -188,15 +225,16 @@ export class WorkspaceGraph {
     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 kept = new Set(unscoped.nodes.map((node) => node.id));
     const owners = new Map<string, number>();
     for (const node of counted)
-      if (node.owner && !pageKinds.has(node.kind)) owners.set(node.owner, (owners.get(node.owner) ?? 0) + 1);
+      if (node.owner && kept.has(node.id)) owners.set(node.owner, (owners.get(node.owner) ?? 0) + 1);
     return {
       diagnostics: [
         {
           severity: "error",
           code: "graph-scope-required",
-          message: `The graph has ${unscoped.nodes.length} nodes besides its pages. Pass app, module or both to scope it.`,
+          message: `The graph has ${unscoped.nodes.length} nodes once unchanged pages are set aside. Pass app, module or both to scope it.`,
           input: "app",
         },
       ],