@akanjs/devkit 3.0.0-beta.19 → 3.0.0-beta.20

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
       ? [
           {

package/workflow/render.ts

@@ -1,6 +1,9 @@
 import type {
+  PrimitiveFormat,
+  PrimitiveWriteReport,
   RepairReport,
   WorkflowApplyReport,
+  WorkflowDiagnostic,
   WorkflowFormat,
   WorkflowPlan,
   WorkflowRunArtifact,
@@ -9,6 +12,23 @@ import type {
 } from "./types";
 import { jsonText } from "./utils";
 
+const listOr = <T>(items: readonly T[] | undefined, render: (item: T) => string, empty = "- none") =>
+  items?.length ? items.map(render) : [empty];
+
+const renderDiagnostic = (diagnostic: WorkflowDiagnostic) =>
+  `- [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`;
+
+const renderCommand = (entry: { command: string; reason: string }) => `- \`${entry.command}\`: ${entry.reason}`;
+
+const renderFile = (file: { action: string; path: string; reason: string }) =>
+  `- \`${file.action}\` ${file.path}: ${file.reason}`;
+
+const renderRecommendation = (recommendation: WorkflowApplyReport["recommendations"][number]) => {
+  const target = recommendation.target ? ` ${recommendation.target}` : "";
+  const action = recommendation.action ? ` Action: ${recommendation.action}` : "";
+  return `- [${recommendation.kind}]${target} ${recommendation.message}${action}`;
+};
+
 export const renderWorkflowList = (specs: readonly WorkflowSpec[]) =>
   [
     "# Akan Workflows",
@@ -41,7 +61,7 @@ export const renderWorkflowExplain = (spec: WorkflowSpec) =>
     ...spec.steps.map((step, index) => `${index + 1}. \`${step.id}\` (${step.tool}): ${step.description}`),
     "",
     "## Validation",
-    ...spec.validation.map((validation) => `- \`${validation.command}\`: ${validation.reason}`),
+    ...spec.validation.map(renderCommand),
     "",
   ].join("\n");
 
@@ -71,43 +91,16 @@ export const renderWorkflowPlan = (plan: WorkflowPlan) =>
     }),
     "",
     "## Validation",
-    ...plan.validation.map((validation) => `- \`${validation.command}\`: ${validation.reason}`),
+    ...plan.validation.map(renderCommand),
     "",
     "## Diagnostics",
-    ...(plan.diagnostics.length
-      ? plan.diagnostics.map((diagnostic) => `- [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`)
-      : ["- none"]),
+    ...listOr(plan.diagnostics, renderDiagnostic),
     "",
     "## Recommendations",
-    ...(plan.recommendations.length
-      ? plan.recommendations.map((recommendation) => `- [${recommendation.kind}] ${recommendation.message}`)
-      : ["- none"]),
+    ...listOr(plan.recommendations, (recommendation) => `- [${recommendation.kind}] ${recommendation.message}`),
     "",
   ].join("\n");
 
-const renderRecommendation = (recommendation: WorkflowApplyReport["recommendations"][number]) => {
-  const target = recommendation.target ? ` ${recommendation.target}` : "";
-  const action = recommendation.action ? ` Action: ${recommendation.action}` : "";
-  return `- [${recommendation.kind}]${target} ${recommendation.message}${action}`;
-};
-
-const renderDiagnostic = (diagnostic: WorkflowApplyReport["diagnostics"][number]) =>
-  `- [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`;
-
-const renderNextAction = (action: WorkflowApplyReport["nextActions"][number]) =>
-  `- \`${action.command}\`: ${action.reason}`;
-
-const applySourceStatus = (report: WorkflowApplyReport) =>
-  report.diagnostics.some(
-    (diagnostic) =>
-      diagnostic.severity === "error" &&
-      (diagnostic.failureScope === "source-change" ||
-        !diagnostic.failureScope ||
-        diagnostic.failureScope === "unknown"),
-  )
-    ? "failed"
-    : "passed";
-
 export const renderWorkflowApplyReport = (report: WorkflowApplyReport) => {
   const applySummary = {
     sourceFilesChanged: report.summary?.sourceFilesChanged ?? report.changedFiles,
@@ -140,7 +133,7 @@ export const renderWorkflowApplyReport = (report: WorkflowApplyReport) => {
     "",
     `- Mode: ${report.mode}`,
     `- Status: ${report.status}`,
-    `- Source-change status: ${applySourceStatus(report)}`,
+    `- Source-change status: ${sourceBlockers.length ? "failed" : "passed"}`,
     `- Workspace status: ${validationBlockers.length ? "blocked" : "not blocked during apply"}`,
     `- Source files changed: ${applySummary.sourceFilesChanged.length}`,
     `- Generated files queued for sync: ${applySummary.generatedFilesSynced.length}`,
@@ -155,24 +148,16 @@ export const renderWorkflowApplyReport = (report: WorkflowApplyReport) => {
     ...(sourceBlockers.length ? sourceBlockers : ["- none"]),
     "",
     "## Automatically Modified",
-    ...(applySummary.sourceFilesChanged.length
-      ? applySummary.sourceFilesChanged.map((file) => `- \`${file.action}\` ${file.path}: ${file.reason}`)
-      : ["- none"]),
+    ...listOr(applySummary.sourceFilesChanged, renderFile),
     "",
     "## Generated Sync",
-    ...(applySummary.generatedFilesSynced.length
-      ? applySummary.generatedFilesSynced.map((file) => `- \`${file.action}\` ${file.path}: ${file.reason}`)
-      : ["- none"]),
+    ...listOr(applySummary.generatedFilesSynced, renderFile),
     "",
     "## Applied Commands",
-    ...(report.appliedCommands.length
-      ? report.appliedCommands.map((command) => `- \`${command.command}\`: ${command.reason}`)
-      : ["- none"]),
+    ...listOr(report.appliedCommands, renderCommand),
     "",
     "## Recommended Validation Commands",
-    ...(report.recommendedValidationCommands.length
-      ? report.recommendedValidationCommands.map((command) => `- \`${command.command}\`: ${command.reason}`)
-      : ["- none"]),
+    ...listOr(report.recommendedValidationCommands, renderCommand),
     "",
     "## User Review Required",
     ...(manualReviewItems.length ? manualReviewItems : ["- none"]),
@@ -185,13 +170,13 @@ export const renderWorkflowApplyReport = (report: WorkflowApplyReport) => {
         : ["- none"]),
     "",
     "## Diagnostics",
-    ...(report.diagnostics.length ? report.diagnostics.map(renderDiagnostic) : ["- none"]),
+    ...listOr(report.diagnostics, renderDiagnostic),
     "",
     "## Recommendations",
-    ...(report.recommendations.length ? report.recommendations.slice(0, 3).map(renderRecommendation) : ["- none"]),
+    ...listOr(report.recommendations.slice(0, 3), renderRecommendation),
     "",
     "## Next Actions",
-    ...(report.nextActions.length ? report.nextActions.slice(0, 3).map(renderNextAction) : ["- none"]),
+    ...listOr(report.nextActions.slice(0, 3), renderCommand),
     "",
   ].join("\n");
 };
@@ -229,21 +214,16 @@ export const renderWorkflowValidationRunReport = (report: WorkflowValidationRunR
     `- Environment: ${report.summary.environment}`,
     "",
     "## Source Change Diagnostics",
-    ...(report.workflowDiagnostics?.length
-      ? report.workflowDiagnostics.map(
-          (diagnostic) => `- [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`,
-        )
-      : ["- none"]),
+    ...listOr(report.workflowDiagnostics, renderDiagnostic),
     "",
     "## Existing Workspace Blockers",
     `- Status: ${baselineSummary.status}`,
     `- Errors: ${baselineSummary.totalErrors}`,
     `- Warnings: ${baselineSummary.totalWarnings}`,
-    ...(baselineSummary.byCode.length
-      ? baselineSummary.byCode.map(
-          (item) => `- [${item.severity}] ${item.code} (${item.count}x): ${item.sampleMessage}`,
-        )
-      : ["- none"]),
+    ...listOr(
+      baselineSummary.byCode,
+      (item) => `- [${item.severity}] ${item.code} (${item.count}x): ${item.sampleMessage}`,
+    ),
     ...(baselineSummary.detailsIncluded
       ? []
       : [
@@ -251,46 +231,30 @@ export const renderWorkflowValidationRunReport = (report: WorkflowValidationRunR
         ]),
     "",
     "## Existing Workspace Blocker Details",
-    ...(report.baselineDiagnostics?.length
-      ? report.baselineDiagnostics.map(
-          (diagnostic) => `- [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`,
-        )
-      : baselineSummary.detailsIncluded
-        ? ["- none"]
-        : ["- omitted"]),
+    ...listOr(report.baselineDiagnostics, renderDiagnostic, baselineSummary.detailsIncluded ? "- none" : "- omitted"),
     "",
     "## Known Blockers",
-    ...(report.knownBlockers.length
-      ? report.knownBlockers.map((blocker) => {
-          const command = blocker.command ? ` \`${blocker.command}\`` : "";
-          const count = blocker.count > 1 ? ` (${blocker.count}x)` : "";
-          const known = blocker.known ? " known" : "";
-          return `- [${blocker.failureScope}${known}]${command}${count}: ${blocker.message}`;
-        })
-      : ["- none"]),
+    ...listOr(report.knownBlockers, (blocker) => {
+      const command = blocker.command ? ` \`${blocker.command}\`` : "";
+      const count = blocker.count > 1 ? ` (${blocker.count}x)` : "";
+      const known = blocker.known ? " known" : "";
+      return `- [${blocker.failureScope}${known}]${command}${count}: ${blocker.message}`;
+    }),
     "",
     "## Commands",
-    ...(report.commands.length
-      ? report.commands.map((command) => {
-          const scope = command.failureScope ? ` (${command.failureScope})` : "";
-          return `- [${command.status}] \`${command.command}\`${scope}: ${command.reason}`;
-        })
-      : ["- none"]),
+    ...listOr(report.commands, (command) => {
+      const scope = command.failureScope ? ` (${command.failureScope})` : "";
+      return `- [${command.status}] \`${command.command}\`${scope}: ${command.reason}`;
+    }),
     "",
     "## Diagnostics",
-    ...(report.diagnostics.length
-      ? report.diagnostics.map((diagnostic) => `- [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`)
-      : ["- none"]),
+    ...listOr(report.diagnostics, renderDiagnostic),
     "",
     "## Repair Actions",
-    ...(report.repairActions.length
-      ? report.repairActions.map((action) => `- \`${action.command}\`: ${action.reason}`)
-      : ["- none"]),
+    ...listOr(report.repairActions, renderCommand),
     "",
     "## Next Actions",
-    ...(report.nextActions.length
-      ? report.nextActions.map((action) => `- \`${action.command}\`: ${action.reason}`)
-      : ["- none"]),
+    ...listOr(report.nextActions, renderCommand),
     "",
   ].join("\n");
 };
@@ -306,19 +270,13 @@ export const renderRepairReportMarkdown = (report: RepairReport) =>
     `- Target: ${report.target ?? "none"}`,
     "",
     "## Commands",
-    ...(report.commands.length
-      ? report.commands.map((command) => `- [${command.status}] \`${command.command}\`: ${command.reason}`)
-      : ["- none"]),
+    ...listOr(report.commands, (command) => `- [${command.status}] \`${command.command}\`: ${command.reason}`),
     "",
     "## Diagnostics",
-    ...(report.diagnostics.length
-      ? report.diagnostics.map((diagnostic) => `- [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`)
-      : ["- none"]),
+    ...listOr(report.diagnostics, renderDiagnostic),
     "",
     "## Next Actions",
-    ...(report.nextActions.length
-      ? report.nextActions.map((action) => `- \`${action.command}\`: ${action.reason}`)
-      : ["- none"]),
+    ...listOr(report.nextActions, renderCommand),
     "",
   ].join("\n");
 
@@ -333,3 +291,29 @@ export const renderWorkflowRunArtifact = (artifact: WorkflowRunArtifact, format:
   }
   return jsonText(artifact);
 };
+
+export const renderPrimitiveWriteReport = (report: PrimitiveWriteReport) =>
+  [
+    `# Primitive Write: ${report.command}`,
+    "",
+    `- Status: ${report.status}`,
+    "",
+    "## Changed Files",
+    ...listOr(report.changedFiles, renderFile),
+    "",
+    "## Generated Files",
+    ...listOr(report.generatedFiles, renderFile),
+    "",
+    "## Validation Commands",
+    ...listOr(report.validationCommands, renderCommand),
+    "",
+    "## Diagnostics",
+    ...listOr(report.diagnostics, renderDiagnostic),
+    "",
+    "## Next Actions",
+    ...listOr(report.nextActions, renderCommand),
+    "",
+  ].join("\n");
+
+export const renderPrimitiveReport = (report: PrimitiveWriteReport, format: PrimitiveFormat = "markdown") =>
+  format === "json" ? jsonText(report) : renderPrimitiveWriteReport(report);

package/workflow/source.ts

@@ -1,13 +1,23 @@
+import { lowerlize } from "akanjs/common";
 import ts from "typescript";
 import type { Sys } from "../commandDecorators";
 import { generatedFilePathsForTarget } from "./artifacts";
-import { createPrimitiveWriteReport } from "./primitive";
+import {
+  callExpressionName,
+  expressionName,
+  firstObjectReturnedByArrow,
+  heritageCall,
+  nodeName,
+  propertyName,
+  sourceFileFor,
+} from "./sourceAst";
 import type {
   PrimitiveChangedFile,
   PrimitiveFileMap,
   PrimitiveGeneratedFile,
   PrimitiveNextAction,
   PrimitiveValidationCommand,
+  PrimitiveWriteReport,
   WorkflowDiagnostic,
 } from "./types";
 
@@ -57,6 +67,27 @@ export const nextActionsForTarget = (target: string) =>
     { command: `akan lint ${target}`, reason: "Validate the target after generated files are refreshed." },
   ] satisfies PrimitiveNextAction[];
 
+export const createPrimitiveWriteReport = ({
+  command,
+  status,
+  changedFiles = [],
+  generatedFiles = [],
+  validationCommands = [],
+  diagnostics = [],
+  nextActions = [],
+}: Omit<PrimitiveWriteReport, "schemaVersion" | "status"> & {
+  status?: PrimitiveWriteReport["status"];
+}): PrimitiveWriteReport => ({
+  schemaVersion: 1,
+  command,
+  status: status ?? (diagnostics.some((diagnostic) => diagnostic.severity === "error") ? "failed" : "passed"),
+  changedFiles,
+  generatedFiles,
+  validationCommands,
+  diagnostics,
+  nextActions,
+});
+
 export const createPassedPrimitiveReport = ({
   command,
   changedFiles,
@@ -90,8 +121,6 @@ export const titleize = (value: string) =>
     .replace(/[-_]+/g, " ")
     .replace(/\b\w/g, (char) => char.toUpperCase());
 
-export const lowerlize = (value: string) => `${value.slice(0, 1).toLowerCase()}${value.slice(1)}`;
-
 const koLabels: Record<string, string> = {
   amount: "금액",
   budget: "예산",
@@ -379,9 +408,6 @@ export interface AkanDictionaryStructure {
   fields: string[];
 }
 
-const sourceFileFor = (fileName: string, content: string, scriptKind = ts.ScriptKind.TS) =>
-  ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, scriptKind);
-
 const hasParseDiagnostics = (source: ts.SourceFile) =>
   ((source as ts.SourceFile & { parseDiagnostics?: readonly ts.Diagnostic[] }).parseDiagnostics ?? []).length > 0;
 
@@ -398,52 +424,6 @@ const lineEndAt = (content: string, position: number) => {
 const lineIndentAt = (content: string, position: number) =>
   /^[ \t]*/.exec(content.slice(lineStartAt(content, position)))?.[0] ?? "";
 
-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 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;
-};
-
-const callExpressionName = (node: ts.CallExpression) =>
-  ts.isPropertyAccessExpression(node.expression) ? node.expression.name.text : expressionName(node.expression);
-
 const locatedObject = (source: ts.SourceFile, objectLiteral: ts.ObjectLiteralExpression): ObjectInsertionLocator => ({
   objectStart: objectLiteral.getStart(source),
   objectEnd: objectLiteral.getEnd(),
@@ -869,8 +849,6 @@ export const parseValues = (value: string | null) =>
     .map((item) => item.trim())
     .filter(Boolean) ?? [];
 
-// ---- Service / signal insertion (add-mutation, add-slice) ----
-
 export const hasSourceParseErrors = (content: string, fileName = "source.ts") =>
   hasParseDiagnostics(sourceFileFor(fileName, content));
 
@@ -988,8 +966,7 @@ export const insertSignalFactoryEntry = (
   if (!located) return null;
   const locator = locatedObject(source, located.object);
   if (locator.fields.some((field) => field.name === entryName)) return content;
-  // Compute the param edit first (its offsets precede the object), but apply it last so the
-  // object splice (at a higher offset) does not invalidate the param region positions.
+  // Apply the param edit last: it sits before the object, so applying it first would shift the object's offsets.
   const paramEdit = factoryParamEdit(content, source, located.arrow, param);
   if (paramEdit === null) return null;
   const withEntry = insertOrderedFieldLine(content, locator, entryName, entryLine, {

package/workflow/sourceAst.ts

@@ -0,0 +1,50 @@
+import ts from "typescript";
+
+export const sourceFileFor = (fileName: string, content: string) =>
+  ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+
+export 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;
+};
+
+export const propertyName = (node: ts.ObjectLiteralElementLike) =>
+  ts.isPropertyAssignment(node) || ts.isShorthandPropertyAssignment(node) || ts.isMethodDeclaration(node)
+    ? nodeName(node.name)
+    : null;
+
+export 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;
+};
+
+export const callExpressionName = (node: ts.CallExpression) =>
+  ts.isPropertyAccessExpression(node.expression) ? node.expression.name.text : expressionName(node.expression);
+
+export 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";
+
+export 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;
+};

package/workspaceLayout.ts

@@ -1,16 +1,9 @@
-/**
- * App/lib 루트 레이아웃 허용 목록 — 단일 소스.
- *
- * 같은 규칙을 scanInfo(`akan sync`, hard error) · akanContext(`akan doctor`, diagnostic) ·
- * qualityScanner(`akan quality scan`, warning) 세 곳이 각자 복사해 두면서 실제로 어긋났다
- * (스코프 AGENTS.md/CLAUDE.md 는 sync 만 허용, `plugin` 은 문서에만, `secrets` 는 doctor 만 거부).
- * 규칙을 추가할 때는 이 파일만 고치고, 루트 AGENTS.md 의 목록도 같이 갱신한다.
- */
+// The one source of the app/lib root allowlists (sync, doctor and quality scan read it); mirror a change into the
+// root AGENTS.md list.
 
 export type SysType = "app" | "lib";
 
 export const appRootAllowedFiles = new Set([
-  // 스코프 에이전트 가이드 — scan(write) 이 유지하는 색인 + 마커 밖 hand-written 내용 (agentsIndex.ts)
   "AGENTS.md",
   "CLAUDE.md",
   "akan.app.json",
@@ -43,12 +36,7 @@ export const appRootAllowedDirs = new Set([
   "webkit",
 ]);
 
-/**
- * 라이브러리 루트는 앱 루트에서 실행/모바일 전용 항목(`main.ts`, `capacitor.config.ts`, `.akan`,
- * `android`, `ios`, `mobile`, `script`, `secrets`)을 뺀 집합이다 — 라이브러리는 부팅되지도, 패키징되지도
- * 않는다. `index.ts` 는 lib 에만 생성되고, `README.md` / `tsconfig.spec.json` 은 라이브러리가 패키지로
- * 배포되기 때문에 남는다. `public` / `private` 은 syncAssets 가 앱으로 심링크하므로 라이브러리도 가진다.
- */
+// A library is never booted or packaged as an app, so the run/mobile entries are out; it is published, so README stays.
 export const libRootAllowedFiles = new Set([
   "AGENTS.md",
   "CLAUDE.md",
@@ -98,9 +86,6 @@ const libFacetRootTestPattern = /^[A-Za-z][A-Za-z0-9_-]*\.signal\.(test|spec)\.(
 export const isAllowedLibFacetRootFile = (filename: string) =>
   libFacetRootAllowedFiles.has(filename) || libFacetRootTestPattern.test(filename);
 
-/**
- * scanSync 는 루트를 `Bun.Glob("*")` 로 읽어 dotfile 을 아예 보지 못한다. 디렉터리를 직접 읽는
- * doctor 가 그 차이만큼 `.DS_Store` 같은 툴 산출물을 에러로 올리므로 같은 기준으로 걸러낸다.
- */
+// scanSync reads roots through `Bun.Glob("*")`, which skips dotfiles, so doctor skips them the same way.
 export const isScannedRootEntry = (type: SysType, name: string) =>
   !name.startsWith(".") || rootAllowedDirs[type].has(name);

package/commandDecorators/commandMeta.ts

@@ -1,7 +0,0 @@
-import type { Cls } from "./types";
-
-export const Commands = () => {
-  return (target: Cls) => {
-    // not implemented yet
-  };
-};