@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/workflow/executor.ts

@@ -1,3 +1,4 @@
+import { capitalize } from "akanjs/common";
 import ts from "typescript";
 import type { AkanModuleContext } from "../akanContext";
 import type { Sys, Workspace } from "../commandDecorators";
@@ -47,16 +48,13 @@ const workflowStringListInput = (value: WorkflowInputValue | undefined) =>
 const workflowStringArrayInput = (value: WorkflowInputValue | undefined) => (Array.isArray(value) ? value : null);
 const workflowBooleanInput = (value: WorkflowInputValue | undefined) => (typeof value === "boolean" ? value : null);
 
-const postApplyDiagnostic = (code: string, message: string, target: string): WorkflowDiagnostic => ({
-  severity: "error",
-  code,
-  message,
-  failureScope: "source-change",
-  context: { target },
-});
-
-const postApplyWarning = (code: string, message: string, target: string): WorkflowDiagnostic => ({
-  severity: "warning",
+const postApplyDiagnostic = (
+  code: string,
+  message: string,
+  target: string,
+  severity: WorkflowDiagnostic["severity"] = "error",
+): WorkflowDiagnostic => ({
+  severity,
   code,
   message,
   failureScope: "source-change",
@@ -113,27 +111,23 @@ const checkTypeScriptSyntax = async (workspace: Workspace, filePath: string) =>
 
 const checkChangedFile = async (workspace: Workspace, file: PrimitiveChangedFile): Promise<WorkflowStepResult> => {
   if (file.action === "remove") return { postApplyChecks: [] };
-  const diagnostics: WorkflowDiagnostic[] = [];
-  const checks: WorkflowPostApplyCheck[] = [];
-  const pathIssue = await checkPathCasing(workspace, file.path);
-  if (pathIssue) {
-    diagnostics.push(postApplyDiagnostic(pathIssue.code, pathIssue.message, file.path));
-    checks.push({ ...pathIssue, target: file.path, status: "failed" });
-    return { diagnostics, postApplyChecks: checks };
+  const issue = (await checkPathCasing(workspace, file.path)) ?? (await checkTypeScriptSyntax(workspace, file.path));
+  if (issue) {
+    return {
+      diagnostics: [postApplyDiagnostic(issue.code, issue.message, file.path)],
+      postApplyChecks: [{ ...issue, target: file.path, status: "failed" }],
+    };
   }
-  const syntaxIssue = await checkTypeScriptSyntax(workspace, file.path);
-  if (syntaxIssue) {
-    diagnostics.push(postApplyDiagnostic(syntaxIssue.code, syntaxIssue.message, file.path));
-    checks.push({ ...syntaxIssue, target: file.path, status: "failed" });
-    return { diagnostics, postApplyChecks: checks };
-  }
-  checks.push({
-    code: "workflow-post-apply-file-valid",
-    target: file.path,
-    status: "passed",
-    message: "Changed file exists with exact casing and parses as source when applicable.",
-  });
-  return { postApplyChecks: checks };
+  return {
+    postApplyChecks: [
+      {
+        code: "workflow-post-apply-file-valid",
+        target: file.path,
+        status: "passed",
+        message: "Changed file exists with exact casing and parses as source when applicable.",
+      },
+    ],
+  };
 };
 
 const checkRecommendationPath = async (
@@ -198,18 +192,6 @@ const workflowModuleContext = async (workspace: Workspace, plan: WorkflowPlan):
   };
 };
 
-const structureCheck = (
-  code: string,
-  target: string,
-  status: WorkflowPostApplyCheck["status"],
-  message: string,
-): WorkflowPostApplyCheck => ({
-  code,
-  target,
-  status,
-  message,
-});
-
 const checkAddFieldStructure = async (workspace: Workspace, plan: WorkflowPlan): Promise<WorkflowStepResult> => {
   if (plan.workflow !== "add-field" && plan.workflow !== "add-enum-field") return {};
   const app = workflowStringInput(plan.inputs.app);
@@ -259,16 +241,14 @@ const checkAddFieldStructure = async (workspace: Workspace, plan: WorkflowPlan):
       .map((diagnostic) => diagnostic.message),
   ].filter((failure): failure is string => failure !== null);
   const constantValid = constantFailures.length === 0;
-  postApplyChecks.push(
-    structureCheck(
-      constantValid ? "workflow-post-apply-constant-shape-valid" : "workflow-post-apply-structure-invalid",
-      constantPath,
-      constantValid ? "passed" : "failed",
-      constantValid
-        ? `${inputClassName} keeps via structure, builder usage, imports, and requested field presence.`
-        : constantFailures.join(" "),
-    ),
-  );
+  postApplyChecks.push({
+    code: constantValid ? "workflow-post-apply-constant-shape-valid" : "workflow-post-apply-structure-invalid",
+    target: constantPath,
+    status: constantValid ? "passed" : "failed",
+    message: constantValid
+      ? `${inputClassName} keeps via structure, builder usage, imports, and requested field presence.`
+      : constantFailures.join(" "),
+  });
   if (!constantValid) {
     diagnostics.push(
       postApplyDiagnostic("workflow-post-apply-structure-invalid", constantFailures.join(" "), constantPath),
@@ -293,16 +273,14 @@ const checkAddFieldStructure = async (workspace: Workspace, plan: WorkflowPlan):
       .map((diagnostic) => diagnostic.message),
   ].filter((failure): failure is string => failure !== null);
   const dictionaryValid = dictionaryFailures.length === 0;
-  postApplyChecks.push(
-    structureCheck(
-      dictionaryValid ? "workflow-post-apply-dictionary-shape-valid" : "workflow-post-apply-structure-invalid",
-      dictionaryPath,
-      dictionaryValid ? "passed" : "failed",
-      dictionaryValid
-        ? `.model<${moduleClassName}> keeps the requested field inside the model object and preserves dictionary chain order.`
-        : dictionaryFailures.join(" "),
-    ),
-  );
+  postApplyChecks.push({
+    code: dictionaryValid ? "workflow-post-apply-dictionary-shape-valid" : "workflow-post-apply-structure-invalid",
+    target: dictionaryPath,
+    status: dictionaryValid ? "passed" : "failed",
+    message: dictionaryValid
+      ? `.model<${moduleClassName}> keeps the requested field inside the model object and preserves dictionary chain order.`
+      : dictionaryFailures.join(" "),
+  });
   if (!dictionaryValid) {
     diagnostics.push(
       postApplyDiagnostic("workflow-post-apply-structure-invalid", dictionaryFailures.join(" "), dictionaryPath),
@@ -312,22 +290,21 @@ const checkAddFieldStructure = async (workspace: Workspace, plan: WorkflowPlan):
   const constantOrderValid = fieldOrderValid(constantNames, fieldName);
   const dictionaryOrderValid = fieldOrderValid(dictionaryStructure.fields, fieldName);
   const orderValid = constantOrderValid && dictionaryOrderValid;
-  postApplyChecks.push(
-    structureCheck(
-      "workflow-post-apply-field-order-valid",
-      `${constantPath}, ${dictionaryPath}`,
-      orderValid ? "passed" : "failed",
-      orderValid
-        ? `Field "${fieldName}" follows the shared priority ordering policy.`
-        : `Field "${fieldName}" is present but does not match the shared priority ordering policy.`,
-    ),
-  );
+  postApplyChecks.push({
+    code: "workflow-post-apply-field-order-valid",
+    target: `${constantPath}, ${dictionaryPath}`,
+    status: orderValid ? "passed" : "failed",
+    message: orderValid
+      ? `Field "${fieldName}" follows the shared priority ordering policy.`
+      : `Field "${fieldName}" is present but does not match the shared priority ordering policy.`,
+  });
   if (!orderValid) {
     diagnostics.push(
-      postApplyWarning(
+      postApplyDiagnostic(
         "workflow-post-apply-field-order-mismatch",
         `Field "${fieldName}" is present but does not match the shared priority ordering policy.`,
         `${constantPath}, ${dictionaryPath}`,
+        "warning",
       ),
     );
   }
@@ -364,6 +341,14 @@ const unsupportedInput = (input: string, message: string): WorkflowDiagnostic =>
   message,
 });
 
+const surfaceReview = (
+  plan: WorkflowPlan,
+  { code, target, action, message, reason }: Record<"code" | "target" | "action" | "message" | "reason", string>,
+): WorkflowStepResult => ({
+  recommendations: [{ code, kind: "manual-action", target, action, confidence: "medium", message }],
+  nextActions: [{ command: `akan workflow explain ${plan.workflow}`, reason }],
+});
+
 const addFieldUiSurfaceInspection = (plan: WorkflowPlan): WorkflowStepResult => {
   const app = workflowStringInput(plan.inputs.app);
   const module = workflowStringInput(plan.inputs.module) ?? "<module>";
@@ -373,27 +358,41 @@ const addFieldUiSurfaceInspection = (plan: WorkflowPlan): WorkflowStepResult =>
   const surfaces = workflowStringArrayInput(plan.inputs.surfaces);
   const templateRequested = surfaces?.includes("template") ?? false;
   const moduleClassName = moduleComponentName(module);
-  const target = `${app ? `apps/${app}` : "*"}/${moduleSourcePaths(module).template}`;
-  return {
-    recommendations: [
-      {
-        code: "add-field-ui-surface-review",
-        kind: "manual-action",
-        target,
-        action: templateRequested
-          ? `Template was requested for ${field}. If no Template file changed, users will not see the field in the form yet because the file was missing, the generated ${module}Form/Layout.Template pattern was not found, or ${policy.component} needs option binding. Add it inside Layout.Template near existing Field components.`
-          : `Template was not selected, so users will not see ${field} in the form from this apply. If list/card display is needed, include ${field} in Light${moduleClassName} projection data and place it in the local Unit/View card layout.`,
-        confidence: "medium",
-        message: `Review user-visible UI for ${module}.${field}; recommended component is ${policy.component}.`,
-      },
-    ],
-    nextActions: [
-      {
-        command: `akan workflow explain ${plan.workflow}`,
-        reason: "Review UI surface guidance before manually editing ambiguous UI files.",
-      },
-    ],
-  };
+  return surfaceReview(plan, {
+    code: "add-field-ui-surface-review",
+    target: `${app ? `apps/${app}` : "*"}/${moduleSourcePaths(module).template}`,
+    action: templateRequested
+      ? `Template was requested for ${field}. If no Template file changed, users will not see the field in the form yet because the file was missing, the generated ${module}Form/Layout.Template pattern was not found, or ${policy.component} needs option binding. Add it inside Layout.Template near existing Field components.`
+      : `Template was not selected, so users will not see ${field} in the form from this apply. If list/card display is needed, include ${field} in Light${moduleClassName} projection data and place it in the local Unit/View card layout.`,
+    message: `Review user-visible UI for ${module}.${field}; recommended component is ${policy.component}.`,
+    reason: "Review UI surface guidance before manually editing ambiguous UI files.",
+  });
+};
+
+const addMutationActionSurfaceInspection = (plan: WorkflowPlan): WorkflowStepResult => {
+  const module = workflowStringInput(plan.inputs.module) ?? "<module>";
+  const mutation = workflowStringInput(plan.inputs.mutation) ?? "<mutation>";
+  const moduleClassName = moduleComponentName(module);
+  return surfaceReview(plan, {
+    code: "add-mutation-action-surface-review",
+    target: `*/${moduleSourcePaths(module).store}`,
+    action: `Name the endpoint's guards and add its dictionary .endpoint() entry with a .desc(). After sync, fetch.${mutation} exists; write a store action only for a toast, an optimistic update, or a multi-field write, and put the control that calls it in ${moduleClassName}.Util.tsx.`,
+    message: `Workflow apply does not write store or UI code for ${module}.${mutation}; review whether a screen should call it.`,
+    reason: "Review action surface guidance before manually editing store or UI files.",
+  });
+};
+
+const addSliceViewSurfaceInspection = (plan: WorkflowPlan): WorkflowStepResult => {
+  const module = workflowStringInput(plan.inputs.module) ?? "<module>";
+  const slice = workflowStringInput(plan.inputs.slice) ?? "<slice>";
+  const moduleClassName = moduleComponentName(module);
+  return surfaceReview(plan, {
+    code: "add-slice-view-surface-review",
+    target: `*/${moduleSourcePaths(module).zone}`,
+    action: `Fill in the service query stub and add the dictionary .slice() entry. After sync, load fetch.init${moduleClassName}${capitalize(slice)}() in the page and pass the result to a ${moduleClassName}.Zone as an init prop.`,
+    message: `Workflow apply does not write page or Zone code for ${module}.${slice}; review where the list should render.`,
+    reason: "Review view surface guidance before manually editing Zone or page files.",
+  });
 };
 
 export const createWorkflowStepRegistry = ({
@@ -494,6 +493,8 @@ export const createWorkflowStepRegistry = ({
         }),
       ),
     [workflowStepKey("add-mutation", "update-signal")]: inspect,
+    [workflowStepKey("add-mutation", "update-action-surfaces")]: async (_step, plan) =>
+      addMutationActionSurfaceInspection(plan),
     [workflowStepKey("add-slice", "update-service-query")]: async (_step, plan) =>
       primitiveReportToWorkflowStepResult(
         await addSlice({
@@ -503,6 +504,7 @@ export const createWorkflowStepRegistry = ({
         }),
       ),
     [workflowStepKey("add-slice", "update-signal-slice")]: inspect,
+    [workflowStepKey("add-slice", "connect-view-surfaces")]: async (_step, plan) => addSliceViewSurfaceInspection(plan),
   };
 };
 
@@ -529,9 +531,8 @@ export class WorkflowExecutor {
     const postApplyChecks: WorkflowPostApplyCheck[] = [];
     const recommendations = [...plan.recommendations];
     const nextActions: PrimitiveNextAction[] = [];
-
-    if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
-      return createWorkflowApplyReport({
+    const report = () =>
+      createWorkflowApplyReport({
         workflow: plan.workflow,
         mode: "apply",
         changedFiles,
@@ -543,7 +544,8 @@ export class WorkflowExecutor {
         nextActions,
         plan,
       });
-    }
+
+    if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) return report();
 
     recommendedValidationCommands.push(...workflowCommandsForPlan(plan));
     nextActions.push(...workflowCommandsForPlan(plan));
@@ -594,17 +596,6 @@ export class WorkflowExecutor {
       );
     }
 
-    return createWorkflowApplyReport({
-      workflow: plan.workflow,
-      mode: "apply",
-      changedFiles,
-      generatedFiles,
-      recommendedValidationCommands,
-      diagnostics,
-      postApplyChecks,
-      recommendations,
-      nextActions,
-      plan,
-    });
+    return report();
   }
 }

package/workflow/index.ts

@@ -2,7 +2,6 @@ export * from "./artifacts";
 export * from "./executor";
 export * from "./moduleIndex";
 export * from "./plan";
-export * from "./primitive";
 export * from "./render";
 export * from "./rolloutGate";
 export * from "./source";

package/workflow/moduleIndex.test.ts

@@ -1,31 +1,20 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
 import path from "node:path";
 import type { AkanModuleContext } from "../akanContext";
 import type { Workspace } from "../commandDecorators";
+import { tempDirs, writeText } from "../testHelpers";
 import { buildAkanModuleContextIndex } from "./moduleIndex";
 
-const tempRoots: string[] = [];
-
-afterEach(async () => {
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
+const tempRoot = tempDirs("akan-module-index-");
 
 const makeWorkspace = async () => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-module-index-"));
-  tempRoots.push(root);
+  const root = await tempRoot();
   return {
     root,
     workspace: { workspaceRoot: root } as Workspace,
   };
 };
 
-const writeText = async (filePath: string, content: string) => {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, content);
-};
-
 const moduleContext = (files: string[], name = "post"): AkanModuleContext => ({
   kind: "domain",
   name,

package/workflow/moduleIndex.ts

@@ -4,6 +4,15 @@ import ts from "typescript";
 import type { AkanModuleContext } from "../akanContext";
 import type { Workspace } from "../commandDecorators";
 import { moduleComponentName, moduleSourcePaths } from "./source";
+import {
+  callExpressionName,
+  expressionName,
+  firstObjectReturnedByArrow,
+  heritageCall,
+  nodeName,
+  propertyName,
+  sourceFileFor,
+} from "./sourceAst";
 import type {
   AkanConstantIndex,
   AkanDictionaryIndex,
@@ -52,9 +61,6 @@ const fileExists = async (filePath: string) => {
   }
 };
 
-const sourceFileFor = (filePath: string, content: string) =>
-  ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-
 const parseDiagnosticsFor = (source: ts.SourceFile, filePath: string): WorkflowDiagnostic[] => {
   const parseDiagnostics =
     (source as ts.SourceFile & { parseDiagnostics?: readonly ts.DiagnosticWithLocation[] }).parseDiagnostics ?? [];
@@ -83,25 +89,6 @@ const spanFor = (source: ts.SourceFile, file: string, node: ts.Node): AkanSource
   };
 };
 
-const nodeName = (node: ts.PropertyName | ts.BindingName | undefined) => {
-  if (!node) return null;
-  if (ts.isIdentifier(node) || ts.isStringLiteral(node) || ts.isNumericLiteral(node)) return node.text;
-  return null;
-};
-
-const propertyName = (node: ts.ObjectLiteralElementLike) =>
-  ts.isPropertyAssignment(node) || ts.isShorthandPropertyAssignment(node) || ts.isMethodDeclaration(node)
-    ? nodeName(node.name)
-    : null;
-
-const expressionName = (expression: ts.Expression): string | null => {
-  if (ts.isIdentifier(expression)) return expression.text;
-  if (ts.isPropertyAccessExpression(expression)) return expression.name.text;
-  if (ts.isCallExpression(expression)) return expressionName(expression.expression);
-  if (ts.isAsExpression(expression)) return expressionName(expression.expression);
-  return null;
-};
-
 const expressionSummary = (expression: ts.Expression): string => {
   if (ts.isAsExpression(expression)) return expressionSummary(expression.expression);
   if (ts.isIdentifier(expression) || ts.isPropertyAccessExpression(expression))
@@ -151,30 +138,6 @@ const fieldsFromObject = (
     })
     .filter((field): field is AkanFieldOutline => field !== null);
 
-const firstObjectReturnedByArrow = (node: ts.Node): ts.ObjectLiteralExpression | null => {
-  if (!ts.isArrowFunction(node) && !ts.isFunctionExpression(node)) return null;
-  if (ts.isObjectLiteralExpression(node.body)) return node.body;
-  if (ts.isParenthesizedExpression(node.body) && ts.isObjectLiteralExpression(node.body.expression)) {
-    return node.body.expression;
-  }
-  if (!ts.isBlock(node.body)) return null;
-  for (const statement of node.body.statements) {
-    if (ts.isReturnStatement(statement) && statement.expression && ts.isObjectLiteralExpression(statement.expression)) {
-      return statement.expression;
-    }
-  }
-  return null;
-};
-
-const isViaCall = (expression: ts.Expression) =>
-  ts.isCallExpression(expression) && expressionName(expression.expression) === "via";
-
-const heritageCall = (node: ts.ClassDeclaration) => {
-  const heritage = node.heritageClauses?.flatMap((clause) => [...clause.types]) ?? [];
-  const expression = heritage.find((clause) => isViaCall(clause.expression))?.expression;
-  return expression && ts.isCallExpression(expression) ? expression : null;
-};
-
 interface ParsedConstantIndex {
   index: AkanConstantIndex;
   diagnostics: WorkflowDiagnostic[];
@@ -297,9 +260,6 @@ const parseConstantIndex = (filePath: string, content: string, moduleClassName:
   };
 };
 
-const callExpressionName = (node: ts.CallExpression) =>
-  ts.isPropertyAccessExpression(node.expression) ? node.expression.name.text : expressionName(node.expression);
-
 const parseDictionaryIndex = (filePath: string, content: string, moduleClassName: string): ParsedDictionaryIndex => {
   const source = sourceFileFor(filePath, content);
   const diagnostics = parseDiagnosticsFor(source, filePath);

package/workflow/plan.ts

@@ -206,31 +206,24 @@ const createAddFieldRecommendations = (inputs: Record<string, WorkflowInputValue
           },
         ]
       : []),
-    ...(!includeInLight
-      ? [
-          {
-            code: "add-field-light-projection-choice",
-            kind: "manual-action" as const,
-            target: paths.constant,
-            action: `Pass includeInLight=true when users should see ${field} in list/card data. Without it, the field can exist on ${capitalize(
-              module,
-            )}Input but stay absent from Light${capitalize(module)} projections.`,
-            confidence: "medium" as const,
-            message: `${module}.${field} is not selected for list/card projection data.`,
-          },
-        ]
-      : []),
-    ...(includeInLight
-      ? [
-          {
-            code: "add-field-light-projection",
-            kind: "placement" as const,
-            target: paths.constant,
-            confidence: "high" as const,
-            message: `Add ${field} to Light${capitalize(module)} projection fields.`,
-          },
-        ]
-      : []),
+    includeInLight
+      ? {
+          code: "add-field-light-projection",
+          kind: "placement",
+          target: paths.constant,
+          confidence: "high",
+          message: `Add ${field} to Light${capitalize(module)} projection fields.`,
+        }
+      : {
+          code: "add-field-light-projection-choice",
+          kind: "manual-action",
+          target: paths.constant,
+          action: `Pass includeInLight=true when users should see ${field} in list/card data. Without it, the field can exist on ${capitalize(
+            module,
+          )}Input but stay absent from Light${capitalize(module)} projections.`,
+          confidence: "medium",
+          message: `${module}.${field} is not selected for list/card projection data.`,
+        },
     ...(surfaces && !templateRequested
       ? [
           {