@akanjs/devkit 3.0.0-beta.9 → 3.0.0

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/rolloutGate.test.ts

@@ -24,7 +24,7 @@ const workspacePackageManifestPaths = async () => {
   for (const workspace of workspaces) {
     const glob = new Bun.Glob(`${workspace}/package.json`);
     for await (const relativePath of glob.scan({ cwd: workspaceRoot, onlyFiles: true })) {
-      paths.add(relativePath);
+      paths.add(relativePath.split(path.sep).join("/"));
     }
   }
   return [...paths].sort();

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: "예산",
@@ -160,21 +189,27 @@ export const normalizeFieldType = (typeName: string) => {
   return normalizedTypes[typeName.toLowerCase()] ?? typeName;
 };
 
-export const ensureBaseTypeImport = (content: string, typeName: string) => {
-  if (typeName !== "Int" && typeName !== "Float") return content;
-  const source = sourceFileFor("constant.ts", content);
-  const baseImport = findNamedImport(source, "akanjs/base");
-  if (baseImport) {
-    if (baseImport.names.includes(typeName)) return content;
-    const nextNames = [...baseImport.names, typeName].sort();
+export const ensureNamedImport = (content: string, moduleSpecifier: string, name: string) => {
+  const source = sourceFileFor("source.ts", content);
+  const namedImport = findNamedImport(source, moduleSpecifier);
+  if (namedImport) {
+    if (namedImport.names.includes(name)) return content;
+    const nextNames = [...namedImport.names, name].sort();
     return spliceText(
       content,
-      baseImport.namedBindingsStart,
-      baseImport.namedBindingsEnd,
+      namedImport.namedBindingsStart,
+      namedImport.namedBindingsEnd,
       `{ ${nextNames.join(", ")} }`,
     );
   }
-  return `import { ${typeName} } from "akanjs/base";\n${content}`;
+  return `import { ${name} } from "${moduleSpecifier}";\n${content}`;
+};
+
+export const ensureBaseImport = (content: string, name: string) => ensureNamedImport(content, "akanjs/base", name);
+
+export const ensureBaseTypeImport = (content: string, typeName: string) => {
+  if (typeName !== "Int" && typeName !== "Float") return content;
+  return ensureBaseImport(content, typeName);
 };
 
 export type FieldDefaultValue = string | number | boolean | null;
@@ -200,12 +235,12 @@ const booleanDefault = (rawDefault: FieldDefaultValue): string | null => {
 };
 
 const dateDefault = (rawDefault: FieldDefaultValue): string | null => {
-  if (typeof rawDefault === "number" && Number.isFinite(rawDefault)) return `new Date(${rawDefault})`;
+  if (typeof rawDefault === "number" && Number.isFinite(rawDefault)) return `() => dayjs(${rawDefault})`;
   if (typeof rawDefault !== "string") return null;
   const trimmed = rawDefault.trim();
   if (!trimmed) return null;
-  if (trimmed === "now") return "new Date()";
-  if (!Number.isNaN(Date.parse(trimmed))) return `new Date(${JSON.stringify(trimmed)})`;
+  if (trimmed === "now") return "() => dayjs()";
+  if (!Number.isNaN(Date.parse(trimmed))) return `() => dayjs(${JSON.stringify(trimmed)})`;
   return null;
 };
 
@@ -373,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;
 
@@ -392,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(),
@@ -863,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));
 
@@ -982,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.test.ts

@@ -6,6 +6,7 @@ import {
   isScannedRootEntry,
   libRootAllowedDirs,
   libRootAllowedFiles,
+  rootEntryHintOf,
 } from "./workspaceLayout";
 
 describe("app root layout allowlist", () => {
@@ -15,16 +16,30 @@ describe("app root layout allowlist", () => {
   });
 
   test("admits every documented app root folder", () => {
-    for (const dirname of ["mobile", "plugin", "secrets", "srvkit", "webkit"]) {
+    for (const dirname of [".akan", "plugin", "script", "secrets", "srvkit", "webkit"]) {
       expect(appRootAllowedDirs.has(dirname)).toBe(true);
     }
   });
 
+  test("admits the native plugins an app owns, and a lib too", () => {
+    expect(appRootAllowedDirs.has("native")).toBe(true);
+    expect(libRootAllowedDirs.has("native")).toBe(true);
+  });
+
   test("rejects an app root entry no facet owns", () => {
     expect(appRootAllowedFiles.has("helper.ts")).toBe(false);
     expect(appRootAllowedDirs.has("base")).toBe(false);
   });
 
+  test("names what a Capacitor app kept in its root as a leftover, not an unknown entry", () => {
+    for (const name of ["android", "ios", "mobile", "capacitor.config.ts", "capacitor.config.json"]) {
+      expect(appRootAllowedFiles.has(name) || appRootAllowedDirs.has(name)).toBe(false);
+      expect(rootEntryHintOf("app", name)).toContain(".akan/native/<target>");
+    }
+    expect(rootEntryHintOf("app", "base")).toBeNull();
+    expect(rootEntryHintOf("lib", "ios")).toBeNull();
+  });
+
   test("skips dotfile artifacts the sync glob never sees, but keeps .akan", () => {
     expect(isScannedRootEntry("app", ".DS_Store")).toBe(false);
     expect(isScannedRootEntry("app", ".akan")).toBe(true);
@@ -48,10 +63,10 @@ describe("lib root layout allowlist", () => {
   });
 
   test("rejects the app-only run and mobile entries", () => {
-    for (const filename of ["main.ts", "capacitor.config.ts", "akan.app.json"]) {
+    for (const filename of ["main.ts", "akan.app.json"]) {
       expect(libRootAllowedFiles.has(filename)).toBe(false);
     }
-    for (const dirname of [".akan", "android", "ios", "mobile", "script", "secrets"]) {
+    for (const dirname of [".akan", "script", "secrets"]) {
       expect(libRootAllowedDirs.has(dirname)).toBe(false);
     }
   });