@akanjs/devkit 3.1.2-rc.4 → 3.2.0-rc.1

package/workflow/plan.ts

@@ -1,11 +1,11 @@
 import { capitalize } from "akanjs/common";
-import type { Workspace } from "../commandDecorators";
+import type { Sys, Workspace } from "../commandDecorators";
 import { workflowPlanApproval } from "./artifacts";
 import { resolveWorkflowSys } from "./executor";
 import { InteractionScaffold } from "./interactionScaffold";
 import { KeyRename } from "./keyRename";
 import { MutationScaffold } from "./mutationScaffold";
-import { coerceFieldDefault, moduleSourcePaths } from "./source";
+import { coerceFieldDefault, getSysRoot, moduleSourcePaths } from "./source";
 import type {
   WorkflowDiagnostic,
   WorkflowInputSpec,
@@ -479,25 +479,87 @@ const inspectRenameKeyPlan = async (workspace: Workspace, plan: WorkflowPlan): P
   };
 };
 
-export const inspectWorkflowPlan = async (workspace: Workspace, plan: WorkflowPlan): Promise<WorkflowPlan> => {
-  if (plan.workflow === "rename-key") return await inspectRenameKeyPlan(workspace, plan);
-  if (plan.workflow !== "add-mutation" && plan.workflow !== "create-interaction") return plan;
-  const app = planString(plan.inputs, "app");
-  if (!app) return plan;
+const syssHolding = async (workspace: Workspace, module: string, except: Sys) => {
+  const [apps, libs] = await workspace.getSyss();
+  const others = await Promise.all(
+    [...apps, ...libs]
+      .filter((name) => name !== except.name)
+      .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)),
+  );
+  return holding.filter((other): other is Sys => other !== null);
+};
+
+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 isScalar = (await sys.getScalarModules()).includes(module);
+  const [holder] = sameName || 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.`,
+      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.`,
+    ].join(" "),
+  };
+};
+
+export const workflowTargetDiagnostics = async (
+  workspace: Workspace,
+  spec: WorkflowSpec,
+  inputs: Record<string, WorkflowInputValue>,
+): Promise<WorkflowDiagnostic[]> => {
+  const app = planString(inputs, "app");
+  if (!app) return [];
   const sys = await resolveWorkflowSys(workspace, app).catch(() => null);
-  if (!sys)
+  if (!sys) {
+    const [apps, libs] = await workspace.getSyss();
+    return [
+      {
+        severity: "error",
+        code: "workflow-target-missing",
+        input: "app",
+        message: `No app or library named ${app}. Apps: ${apps.join(", ") || "none"}. Libraries: ${libs.join(", ") || "none"}.`,
+      },
+    ];
+  }
+  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] : [];
+};
+
+export const inspectWorkflowPlan = async (
+  workspace: Workspace,
+  spec: WorkflowSpec,
+  plan: WorkflowPlan,
+): Promise<WorkflowPlan> => {
+  const targetDiagnostics = await workflowTargetDiagnostics(workspace, spec, plan.inputs);
+  if (targetDiagnostics.length)
     return {
       ...plan,
-      diagnostics: [
-        ...plan.diagnostics,
-        {
-          severity: "error",
-          code: "workflow-target-missing",
-          input: "app",
-          message: `No app or library named ${app}.`,
-        },
-      ],
+      predictedChanges: [],
+      diagnostics: [...plan.diagnostics, ...targetDiagnostics],
+      recommendations: [],
     };
+  if (plan.workflow === "rename-key") return await inspectRenameKeyPlan(workspace, plan);
+  if (plan.workflow !== "add-mutation" && plan.workflow !== "create-interaction") return plan;
+  const sys = await resolveWorkflowSys(workspace, planString(plan.inputs, "app")).catch(() => null);
+  if (!sys) return plan;
   const inspected =
     plan.workflow === "add-mutation"
       ? await MutationScaffold.build(

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

@@ -61,3 +61,61 @@ describe("WorkspaceGraph.changesVisibleTo", () => {
     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

@@ -14,6 +14,7 @@ export interface GraphScope {
 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, "/");
 
@@ -103,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/");
@@ -160,14 +186,17 @@ export class WorkspaceGraph {
 
   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 counted) 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",