@akanjs/devkit 2.3.9-rc.7 → 2.3.9-rc.9

package/workflow/render.ts

@@ -51,6 +51,7 @@ export const renderWorkflowPlan = (plan: WorkflowPlan) =>
     "",
     `- Mode: ${plan.mode}`,
     `- Requires approval: ${plan.requiresApproval}`,
+    `- Approval: ${plan.approval?.meaning ?? "Review this read-only plan before applying workflow mutations."}`,
     "",
     "## Inputs",
     ...Object.entries(plan.inputs).map(
@@ -93,6 +94,9 @@ const renderRecommendation = (recommendation: WorkflowApplyReport["recommendatio
 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) =>
@@ -105,6 +109,10 @@ const applySourceStatus = (report: WorkflowApplyReport) =>
     : "passed";
 
 export const renderWorkflowApplyReport = (report: WorkflowApplyReport) => {
+  const applySummary = {
+    sourceFilesChanged: report.summary?.sourceFilesChanged ?? report.changedFiles,
+    generatedFilesSynced: report.summary?.generatedFilesSynced ?? report.generatedFiles,
+  };
   const manualReviewItems = [
     ...report.diagnostics.filter((diagnostic) => diagnostic.severity === "warning").map(renderDiagnostic),
     ...report.recommendations
@@ -134,6 +142,8 @@ export const renderWorkflowApplyReport = (report: WorkflowApplyReport) => {
     `- Status: ${report.status}`,
     `- Source-change status: ${applySourceStatus(report)}`,
     `- Workspace status: ${validationBlockers.length ? "blocked" : "not blocked during apply"}`,
+    `- Source files changed: ${applySummary.sourceFilesChanged.length}`,
+    `- Generated files queued for sync: ${applySummary.generatedFilesSynced.length}`,
     ...(report.validationTarget ? [`- Validation target: ${report.validationTarget}`] : []),
     "",
     "## Apply Checks",
@@ -145,13 +155,13 @@ export const renderWorkflowApplyReport = (report: WorkflowApplyReport) => {
     ...(sourceBlockers.length ? sourceBlockers : ["- none"]),
     "",
     "## Automatically Modified",
-    ...(report.changedFiles.length
-      ? report.changedFiles.map((file) => `- \`${file.action}\` ${file.path}: ${file.reason}`)
+    ...(applySummary.sourceFilesChanged.length
+      ? applySummary.sourceFilesChanged.map((file) => `- \`${file.action}\` ${file.path}: ${file.reason}`)
       : ["- none"]),
     "",
     "## Generated Sync",
-    ...(report.generatedFiles.length
-      ? report.generatedFiles.map((file) => `- \`${file.action}\` ${file.path}: ${file.reason}`)
+    ...(applySummary.generatedFilesSynced.length
+      ? applySummary.generatedFilesSynced.map((file) => `- \`${file.action}\` ${file.path}: ${file.reason}`)
       : ["- none"]),
     "",
     "## Applied Commands",
@@ -181,9 +191,7 @@ export const renderWorkflowApplyReport = (report: WorkflowApplyReport) => {
     ...(report.recommendations.length ? report.recommendations.slice(0, 3).map(renderRecommendation) : ["- none"]),
     "",
     "## Next Actions",
-    ...(report.nextActions.length
-      ? report.nextActions.map((action) => `- \`${action.command}\`: ${action.reason}`)
-      : ["- none"]),
+    ...(report.nextActions.length ? report.nextActions.slice(0, 3).map(renderNextAction) : ["- none"]),
     "",
   ].join("\n");
 };
@@ -191,19 +199,32 @@ export const renderWorkflowApplyReport = (report: WorkflowApplyReport) => {
 export const renderWorkflowApply = (report: WorkflowApplyReport, format: WorkflowFormat = "markdown") =>
   format === "json" ? jsonText(report) : renderWorkflowApplyReport(report);
 
-export const renderWorkflowValidationRunReport = (report: WorkflowValidationRunReport) =>
-  [
+export const renderWorkflowValidationRunReport = (report: WorkflowValidationRunReport) => {
+  const baselineSummary = report.baselineSummary ?? {
+    status: report.baselineDiagnostics?.some((diagnostic) => diagnostic.severity === "error") ? "failed" : "unknown",
+    total: report.baselineDiagnostics?.length ?? 0,
+    totalErrors: report.baselineDiagnostics?.filter((diagnostic) => diagnostic.severity === "error").length ?? 0,
+    totalWarnings: report.baselineDiagnostics?.filter((diagnostic) => diagnostic.severity === "warning").length ?? 0,
+    detailsIncluded: true,
+    knownBlockerCount: report.knownBlockers.filter((blocker) => blocker.known).length,
+    byCode: [],
+  };
+  return [
     `# Workflow Validation: ${report.workflow}`,
     "",
     `- Run: ${report.runId}`,
     `- Status: ${report.status}`,
     `- Source status: ${report.sourceStatus}`,
     `- Workspace status: ${report.workspaceStatus}`,
+    `- Validation commands status: ${report.validationCommandsStatus ?? "unknown"}`,
+    `- Baseline status: ${report.baselineStatus ?? baselineSummary.status}`,
     `- Overall status: ${report.overallStatus}`,
     "",
     "## Status Summary",
     `- Source-change: ${report.summary.sourceChange}`,
     `- Generated sync: ${report.summary.generatedSync}`,
+    `- Validation commands: ${report.summary.validationCommands ?? "unknown"}`,
+    `- Baseline: ${report.summary.baseline ?? baselineSummary.status}`,
     `- Workspace config: ${report.summary.workspaceConfig}`,
     `- Environment: ${report.summary.environment}`,
     "",
@@ -215,11 +236,28 @@ export const renderWorkflowValidationRunReport = (report: WorkflowValidationRunR
       : ["- none"]),
     "",
     "## 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"]),
+    ...(baselineSummary.detailsIncluded
+      ? []
+      : [
+          "- Baseline details are summarized by default. Re-run validation with includeBaselineDetails=true for full baselineDiagnostics.",
+        ]),
+    "",
+    "## Existing Workspace Blocker Details",
     ...(report.baselineDiagnostics?.length
       ? report.baselineDiagnostics.map(
           (diagnostic) => `- [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`,
         )
-      : ["- none"]),
+      : baselineSummary.detailsIncluded
+        ? ["- none"]
+        : ["- omitted"]),
     "",
     "## Known Blockers",
     ...(report.knownBlockers.length
@@ -255,6 +293,7 @@ export const renderWorkflowValidationRunReport = (report: WorkflowValidationRunR
       : ["- none"]),
     "",
   ].join("\n");
+};
 
 export const renderWorkflowValidation = (report: WorkflowValidationRunReport, format: WorkflowFormat = "markdown") =>
   format === "json" ? jsonText(report) : renderWorkflowValidationRunReport(report);

package/workflow/rolloutGate.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import type { PackageJson } from "../types";
+import { findToolingRolloutViolations } from "./rolloutGate";
+
+const manifest = (overrides: Partial<PackageJson>): PackageJson => ({
+  name: "fixture",
+  version: "0.0.0",
+  description: "fixture",
+  ...overrides,
+});
+
+const workspaceRoot = path.join(import.meta.dir, "../../../..");
+
+const readWorkspaceManifest = (relativePath: string) =>
+  Bun.file(path.join(workspaceRoot, relativePath)).json() as Promise<PackageJson>;
+
+const workspacePackageManifestPaths = async () => {
+  const rootManifest = await readWorkspaceManifest("package.json");
+  const workspaces = Array.isArray(rootManifest.workspaces)
+    ? rootManifest.workspaces.filter((workspace): workspace is string => typeof workspace === "string")
+    : [];
+  const paths = new Set(["package.json"]);
+  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);
+    }
+  }
+  return [...paths].sort();
+};
+
+describe("tooling rollout gate", () => {
+  test("allows the stable TypeScript Compiler API baseline", () => {
+    expect(
+      findToolingRolloutViolations(
+        manifest({
+          dependencies: { typescript: "^6.0.3" },
+        }),
+      ),
+    ).toEqual([]);
+  });
+
+  test("rejects reference-only and experiment-only AST dependencies in package manifests", () => {
+    const violations = findToolingRolloutViolations(
+      manifest({
+        dependencies: {
+          "@ttsc/graph": "0.1.0",
+          "ast-grep": "0.39.0",
+          recast: "0.23.11",
+          "ts-morph": "27.0.2",
+        },
+        optionalDependencies: {
+          "typescript-go": "0.0.0",
+        },
+      }),
+    );
+
+    expect(violations.map((violation) => `${violation.packageName}:${violation.status}`).sort()).toEqual([
+      "@ttsc/graph:reference-only",
+      "ast-grep:experiment-only",
+      "recast:experiment-only",
+      "ts-morph:experiment-only",
+      "typescript-go:blocked",
+    ]);
+  });
+
+  test("rejects TypeScript rc or native-preview toolchain transitions", () => {
+    const violations = findToolingRolloutViolations(
+      manifest({
+        devDependencies: {
+          "@typescript/native-preview": "0.0.1",
+          typescript: "npm:typescript@rc",
+        },
+      }),
+    );
+
+    expect(violations).toContainEqual(
+      expect.objectContaining({
+        packageName: "typescript",
+        section: "devDependencies",
+        status: "blocked",
+      }),
+    );
+    expect(violations).toContainEqual(
+      expect.objectContaining({
+        packageName: "@typescript/native-preview",
+        section: "devDependencies",
+        status: "blocked",
+      }),
+    );
+  });
+
+  test("keeps workspace package manifests free of blocked AST and graph dependencies", async () => {
+    const manifestPaths = await workspacePackageManifestPaths();
+    expect(manifestPaths).toEqual(
+      expect.arrayContaining([
+        "package.json",
+        "pkgs/@akanjs/devkit/package.json",
+        "pkgs/@akanjs/cli/package.json",
+        "pkgs/akanjs/package.json",
+        "pkgs/create-akan-workspace/package.json",
+      ]),
+    );
+    const manifests = await Promise.all(manifestPaths.map(readWorkspaceManifest));
+
+    expect(manifests.flatMap(findToolingRolloutViolations)).toEqual([]);
+  });
+});

package/workflow/rolloutGate.ts

@@ -0,0 +1,141 @@
+import type { PackageJson } from "../types";
+
+export type ToolingRolloutDependencySection =
+  | "dependencies"
+  | "devDependencies"
+  | "peerDependencies"
+  | "optionalDependencies";
+
+export type ToolingRolloutCandidateStatus = "allowed" | "reference-only" | "experiment-only" | "blocked";
+
+export interface ToolingRolloutCandidate {
+  packageName: string;
+  status: ToolingRolloutCandidateStatus;
+  role: string;
+  adoptionGate: string;
+}
+
+export interface ToolingRolloutViolation {
+  packageName: string;
+  version: string;
+  section: ToolingRolloutDependencySection;
+  status: Exclude<ToolingRolloutCandidateStatus, "allowed">;
+  reason: string;
+}
+
+type RestrictedToolingRolloutCandidate = ToolingRolloutCandidate & {
+  status: Exclude<ToolingRolloutCandidateStatus, "allowed">;
+};
+
+const dependencySections = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies",
+] as const satisfies readonly ToolingRolloutDependencySection[];
+
+export const toolingRolloutCandidates = [
+  {
+    packageName: "typescript",
+    status: "allowed",
+    role: "Primary TypeScript Compiler API baseline for AST locator, text splice, and reparse checks.",
+    adoptionGate: "Already present; keep using stable Bun-compatible package builds.",
+  },
+  {
+    packageName: "@ttsc/graph",
+    status: "reference-only",
+    role: "Source-free graph shape and lazy resident model reference.",
+    adoptionGate: "Do not add as an Akan runtime dependency without a separate proposal or milestone update.",
+  },
+  {
+    packageName: "ts-morph",
+    status: "experiment-only",
+    role: "Prototype candidate for complex object literal insertion, import update, and class traversal.",
+    adoptionGate: "Use only in isolated prototypes until package size and formatting churn are measured.",
+  },
+  {
+    packageName: "ast-grep",
+    status: "experiment-only",
+    role: "Prototype candidate for shape detection, CI rules, and migration rules.",
+    adoptionGate: "Use as a local rule/check experiment, not as the edit engine.",
+  },
+  {
+    packageName: "recast",
+    status: "experiment-only",
+    role: "Prototype candidate for formatting preservation.",
+    adoptionGate: "Low priority; require proof that formatting churn is lower than the baseline.",
+  },
+  {
+    packageName: "typescript-go",
+    status: "blocked",
+    role: "TypeScript-Go toolchain transition placeholder.",
+    adoptionGate: "Out of scope for Season 2 rollout.",
+  },
+  {
+    packageName: "@typescript/native-preview",
+    status: "blocked",
+    role: "TypeScript-Go native preview package placeholder.",
+    adoptionGate: "Out of scope for Season 2 rollout.",
+  },
+] as const satisfies readonly ToolingRolloutCandidate[];
+
+export const toolingRolloutGate = {
+  schemaVersion: 1,
+  strategy: "reference-first-dependency-later",
+  dependencyPolicy:
+    "Season 2 keeps new AST and graph tooling as references or isolated experiments until a separate proposal or milestone update approves adoption.",
+  gateConditions: [
+    "Works in Bun runtime and published package artifacts.",
+    "Does not break dist/pkgs package verification.",
+    "Keeps generated source formatting churn limited.",
+    "Reduces add-field regression fixture failures compared with the current TypeScript API baseline.",
+    "Does not move MCP responses toward returning source bodies.",
+  ],
+  candidates: toolingRolloutCandidates,
+};
+
+const isRestrictedCandidate = (candidate: ToolingRolloutCandidate): candidate is RestrictedToolingRolloutCandidate =>
+  candidate.status !== "allowed";
+
+const restrictedCandidates = new Map<string, RestrictedToolingRolloutCandidate>();
+for (const candidate of toolingRolloutCandidates) {
+  if (isRestrictedCandidate(candidate)) restrictedCandidates.set(candidate.packageName, candidate);
+}
+
+const blockedTypeScriptVersion = (version: string) =>
+  /(?:^|[^\w])(?:rc|next|beta|canary|insiders)(?:[^\w]|$)/i.test(version) || /typescript@rc/i.test(version);
+
+export const findToolingRolloutViolations = (packageJson: PackageJson): ToolingRolloutViolation[] => {
+  const violations: ToolingRolloutViolation[] = [];
+
+  for (const section of dependencySections) {
+    const dependencies = packageJson[section];
+    if (!dependencies) continue;
+
+    for (const [packageName, version] of Object.entries(dependencies)) {
+      const candidate = restrictedCandidates.get(packageName);
+      if (candidate) {
+        violations.push({
+          packageName,
+          version,
+          section,
+          status: candidate.status,
+          reason: candidate.adoptionGate,
+        });
+        continue;
+      }
+
+      if (packageName === "typescript" && blockedTypeScriptVersion(version)) {
+        violations.push({
+          packageName,
+          version,
+          section,
+          status: "blocked",
+          reason: "TypeScript-Go or typescript@rc toolchain transitions are out of scope for Season 2 rollout.",
+        });
+      }
+    }
+  }
+
+  return violations;
+};

package/workflow/source.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test";
+import { inspectDictionaryStructure } from "./source";
+
+describe("inspectDictionaryStructure", () => {
+  test("preserves protected dictionary chain order around the model object", () => {
+    const structure = inspectDictionaryStructure(
+      `
+import { modelDictionary } from "akanjs/dictionary";
+import type { Article, ArticleSlice } from "./article.constant";
+
+export const dictionary = modelDictionary(["en", "ko"])
+  .of((t) => t(["Article", "Article"]))
+  .model<Article>((t) => ({
+    title: t(["Title", "제목"]),
+  }))
+  .slice<ArticleSlice>((fn) => ({
+    inPublic: fn(["Article In Public", "Article 공개"]),
+  }))
+  .enum<ArticleStatus>("articleStatus", (t) => ({}))
+  .error({})
+  .translate({});
+`,
+      "Article",
+    );
+
+    expect(structure).toMatchObject({
+      parseValid: true,
+      modelObjectFound: true,
+      chainOrderValid: true,
+      fields: ["title"],
+    });
+    expect(structure.chainMethods).toEqual(["modelDictionary", "of", "model", "slice", "enum", "error", "translate"]);
+  });
+
+  test("reports broken dictionary chain order even when the field remains inside model", () => {
+    const structure = inspectDictionaryStructure(
+      `
+import { modelDictionary } from "akanjs/dictionary";
+import type { Article, ArticleSlice } from "./article.constant";
+
+export const dictionary = modelDictionary(["en", "ko"])
+  .slice<ArticleSlice>((fn) => ({
+    inPublic: fn(["Article In Public", "Article 공개"]),
+  }))
+  .model<Article>((t) => ({
+    title: t(["Title", "제목"]),
+  }))
+  .translate({})
+  .error({});
+`,
+      "Article",
+    );
+
+    expect(structure).toMatchObject({
+      parseValid: true,
+      modelObjectFound: true,
+      chainOrderValid: false,
+      fields: ["title"],
+    });
+    expect(structure.chainMethods).toEqual(["modelDictionary", "slice", "model", "translate", "error"]);
+  });
+});