@akanjs/devkit 2.3.9-rc.2 → 2.3.9-rc.4

package/akanContext.ts

@@ -4,7 +4,15 @@ import { capitalize } from "akanjs/common";
 import { AppExecutor, LibExecutor, type SysExecutor, type WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
 import type { PackageJson } from "./types";
-import type { RepairAction } from "./workflow";
+import {
+  type GeneratedSyncState,
+  type RepairAction,
+  type WorkflowApplyReport,
+  type WorkflowPlan,
+  type WorkflowRunArtifact,
+  workflowRunArtifactPath,
+  workflowSyncDir,
+} from "./workflow";
 
 export type AkanContextFormat = "json" | "markdown";
 export type AkanModuleKind = "domain" | "service" | "scalar";
@@ -61,6 +69,29 @@ export interface AkanDiagnostic {
   message: string;
   path?: string;
   repairActions?: RepairAction[];
+  scope?: "baseline" | "workflow" | "unknown";
+  context?: {
+    workflow?: string;
+    planPath?: string;
+    runId?: string;
+    target?: string;
+    paths?: string[];
+  };
+}
+
+export interface GeneratedFilesFreshness {
+  status: "fresh" | "stale" | "missing" | "unknown";
+  message: string;
+  refreshCommand: string;
+  verifyingCommands: string[];
+  targets?: {
+    target: string;
+    status: "fresh" | "stale" | "missing" | "unknown";
+    lastSyncedAt?: string;
+    runId?: string;
+    generatedFiles: string[];
+    reason: string;
+  }[];
 }
 
 export interface AkanDoctorResult {
@@ -71,14 +102,11 @@ export interface AkanDoctorResult {
   status: "passed" | "failed";
   diagnostics: AkanDiagnostic[];
   generatedFiles: string[];
-  generatedFilesFreshness: {
-    status: "unknown";
-    message: string;
-    refreshCommand: string;
-    verifyingCommands: string[];
-  };
+  generatedFilesFreshness: GeneratedFilesFreshness;
   validationCommands: string[];
   repairActions: RepairAction[];
+  baselineDiagnostics?: AkanDiagnostic[];
+  workflowDiagnostics?: AkanDiagnostic[];
 }
 
 export type JsonRpcRequest = {
@@ -136,6 +164,7 @@ export const renderDoctorText = (result: AkanDoctorResult) => {
   lines.push(
     "",
     "Generated file freshness:",
+    `Status: ${result.generatedFilesFreshness.status}`,
     result.generatedFilesFreshness.message,
     `Refresh: ${result.generatedFilesFreshness.refreshCommand}`,
     "",
@@ -182,7 +211,7 @@ const validationCommands = [
   "akan doctor --strict --format json",
 ];
 
-const generatedFilesFreshness = {
+const unknownGeneratedFilesFreshness: GeneratedFilesFreshness = {
   status: "unknown" as const,
   message: "Run sync before validation so generated Akan files match the current source conventions.",
   refreshCommand: "akan sync <app-or-lib>",
@@ -269,6 +298,135 @@ const safeReadJson = async <T>(filePath: string) => {
   }
 };
 
+const isWorkflowPlan = (value: unknown): value is WorkflowPlan =>
+  typeof value === "object" &&
+  value !== null &&
+  "schemaVersion" in value &&
+  value.schemaVersion === 1 &&
+  "mode" in value &&
+  value.mode === "plan";
+
+const isWorkflowApplyReport = (value: unknown): value is WorkflowApplyReport =>
+  typeof value === "object" &&
+  value !== null &&
+  "schemaVersion" in value &&
+  value.schemaVersion === 1 &&
+  "mode" in value &&
+  (value.mode === "apply" || value.mode === "dry-run");
+
+const isWorkflowRunArtifact = (value: unknown): value is WorkflowRunArtifact =>
+  typeof value === "object" && value !== null && "schemaVersion" in value && value.schemaVersion === 1;
+
+const planInputString = (plan: WorkflowPlan, key: string) => {
+  const value = plan.inputs[key];
+  return typeof value === "string" ? value : "";
+};
+
+const expandWorkflowTarget = (target: string, plan: WorkflowPlan) => {
+  const app = planInputString(plan, "app");
+  const module = planInputString(plan, "module");
+  const moduleClass = module ? capitalize(module) : "<Module>";
+  return target
+    .replace(/^\*\//, app ? `apps/${app}/` : "")
+    .replaceAll("<module>", module || "<module>")
+    .replaceAll("<Module>", moduleClass);
+};
+
+const workflowPathsForPlan = (plan: WorkflowPlan) =>
+  plan.predictedChanges.map((change) => expandWorkflowTarget(change.target, plan));
+
+const workflowPathsForArtifact = (artifact: WorkflowRunArtifact) => {
+  if (isWorkflowPlan(artifact)) return workflowPathsForPlan(artifact);
+  if (isWorkflowApplyReport(artifact)) {
+    return [
+      ...artifact.changedFiles.map((file) => file.path),
+      ...artifact.generatedFiles.map((file) => file.path),
+      ...workflowPathsForPlan(artifact.plan),
+    ];
+  }
+  if ("mode" in artifact && artifact.mode === "validate" && artifact.plan) return workflowPathsForPlan(artifact.plan);
+  return [];
+};
+
+const loadWorkflowContextPaths = async (
+  workspace: WorkspaceExecutor,
+  runIdOrPlan: string | null,
+  changedFiles: string[],
+) => {
+  const paths = [...changedFiles];
+  if (!runIdOrPlan) return paths;
+  const inputPath = path.isAbsolute(runIdOrPlan) ? runIdOrPlan : path.join(workspace.workspaceRoot, runIdOrPlan);
+  const artifact =
+    (await safeReadJson<WorkflowRunArtifact | WorkflowPlan>(inputPath)) ??
+    (await safeReadJson<WorkflowRunArtifact>(path.join(workspace.workspaceRoot, workflowRunArtifactPath(runIdOrPlan))));
+  if (artifact && isWorkflowRunArtifact(artifact)) paths.push(...workflowPathsForArtifact(artifact));
+  return [...new Set(paths.filter(Boolean))];
+};
+
+const pathKey = (value: string) =>
+  value
+    .replaceAll("\\", "/")
+    .replaceAll("*", "")
+    .replace(/<[^>]+>/g, "")
+    .replace(/\/+/g, "/")
+    .replace(/^\/|\/$/g, "");
+
+const isWorkflowRelatedDiagnostic = (diagnostic: AkanDiagnostic, workflowPaths: string[]) => {
+  if (!diagnostic.path) return false;
+  const diagnosticPath = pathKey(diagnostic.path);
+  return workflowPaths.some((workflowPath) => {
+    const candidate = pathKey(workflowPath);
+    if (!candidate) return false;
+    return (
+      diagnosticPath.startsWith(candidate) || candidate.startsWith(diagnosticPath) || diagnosticPath.includes(candidate)
+    );
+  });
+};
+
+const readGeneratedSyncStates = async (workspace: WorkspaceExecutor) => {
+  const syncDir = path.join(workspace.workspaceRoot, workflowSyncDir);
+  const entries = await safeReadDir(syncDir);
+  const states = await Promise.all(
+    entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+      .map((entry) => safeReadJson<GeneratedSyncState>(path.join(syncDir, entry.name))),
+  );
+  return states.filter(
+    (state): state is GeneratedSyncState =>
+      !!state && state.schemaVersion === 1 && typeof state.target === "string" && typeof state.syncedAt === "string",
+  );
+};
+
+const generatedFreshnessFromStates = async (workspace: WorkspaceExecutor): Promise<GeneratedFilesFreshness> => {
+  const states = await readGeneratedSyncStates(workspace);
+  if (states.length === 0) return unknownGeneratedFilesFreshness;
+  const targets = states
+    .sort((a, b) => a.target.localeCompare(b.target))
+    .map((state) => ({
+      target: state.target,
+      status: state.status === "passed" ? ("fresh" as const) : ("stale" as const),
+      lastSyncedAt: state.syncedAt,
+      runId: state.runId,
+      generatedFiles: state.generatedFiles.map((file) => file.path),
+      reason:
+        state.status === "passed"
+          ? `Generated files were refreshed by ${state.command}.`
+          : `Last generated repair command failed: ${state.command}.`,
+    }));
+  const lastFresh = targets
+    .filter((target) => target.status === "fresh" && target.lastSyncedAt)
+    .sort((a, b) => (b.lastSyncedAt ?? "").localeCompare(a.lastSyncedAt ?? ""))[0];
+  return {
+    status: targets.some((target) => target.status === "fresh") ? "fresh" : "stale",
+    message: lastFresh
+      ? `Generated files were refreshed for ${lastFresh.target} at ${lastFresh.lastSyncedAt}.`
+      : "Generated sync state exists, but the last recorded repair did not pass.",
+    refreshCommand: "akan sync <app-or-lib>",
+    verifyingCommands: ["akan lint <app-or-lib-or-pkg>", "akan build <app-name>"],
+    targets,
+  };
+};
+
 const parseAbstractSummary = (
   relativePath: string,
   content: string | null,
@@ -422,9 +580,14 @@ export class AkanContextAnalyzer {
 
   static async doctor(
     workspace: WorkspaceExecutor,
-    { strict = false }: { strict?: boolean } = {},
+    {
+      strict = false,
+      runIdOrPlan = null,
+      changedFiles = [],
+    }: { strict?: boolean; runIdOrPlan?: string | null; changedFiles?: string[] } = {},
   ): Promise<AkanDoctorResult> {
     const context = await AkanContextAnalyzer.analyze(workspace);
+    const workflowPaths = await loadWorkflowContextPaths(workspace, runIdOrPlan, changedFiles);
     const diagnostics: AkanDiagnostic[] = [];
     const repairActions: RepairAction[] = [
       repairAction("generated", "akan repair generated --app <app-or-lib>", "Refresh generated Akan files.", true),
@@ -524,22 +687,40 @@ export class AkanContextAnalyzer {
       }
     }
 
+    const scopedDiagnostics = diagnostics.map((diagnostic) => ({
+      ...diagnostic,
+      scope: workflowPaths.length
+        ? isWorkflowRelatedDiagnostic(diagnostic, workflowPaths)
+          ? ("workflow" as const)
+          : ("baseline" as const)
+        : diagnostic.scope,
+      context: workflowPaths.length ? { ...diagnostic.context, paths: workflowPaths } : diagnostic.context,
+    }));
+    const workflowDiagnostics = scopedDiagnostics.filter((diagnostic) => diagnostic.scope === "workflow");
+    const baselineDiagnostics = scopedDiagnostics.filter((diagnostic) => diagnostic.scope === "baseline");
     return {
       schemaVersion: 1,
       repoName: context.repoName,
       root: context.root,
       strict,
-      status: diagnostics.some((diagnostic) => diagnostic.severity === "error") ? "failed" : "passed",
-      diagnostics,
+      status: scopedDiagnostics.some((diagnostic) => diagnostic.severity === "error") ? "failed" : "passed",
+      diagnostics: scopedDiagnostics,
       generatedFiles: context.generatedFiles,
-      generatedFilesFreshness,
+      generatedFilesFreshness: await generatedFreshnessFromStates(workspace),
       validationCommands: context.validationCommands,
       repairActions,
+      ...(workflowPaths.length ? { baselineDiagnostics, workflowDiagnostics } : {}),
     };
   }
 
-  static findModules(context: AkanWorkspaceContext, moduleName?: string | null) {
-    const modules = [...context.apps, ...context.libs].flatMap((sys) => sys.modules);
+  static findModules(
+    context: AkanWorkspaceContext,
+    moduleName?: string | null,
+    { app = null }: { app?: string | null } = {},
+  ) {
+    const modules = [...context.apps, ...context.libs]
+      .filter((sys) => !app || sys.name === app)
+      .flatMap((sys) => sys.modules);
     return moduleName
       ? modules.filter((module) => module.name === moduleName || module.folderName === moduleName)
       : modules;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.3.9-rc.2",
+  "version": "2.3.9-rc.4",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -32,7 +32,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.3.9-rc.2",
+    "akanjs": "2.3.9-rc.4",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/workflow/artifacts.ts

@@ -0,0 +1,396 @@
+import type { Workspace } from "../commandDecorators";
+import type {
+  GeneratedSyncState,
+  PrimitiveChangedFile,
+  PrimitiveGeneratedFile,
+  RepairAction,
+  RepairReport,
+  WorkflowApplyCommand,
+  WorkflowApplyReport,
+  WorkflowDiagnostic,
+  WorkflowFailureScope,
+  WorkflowKnownBlocker,
+  WorkflowPlan,
+  WorkflowRunArtifact,
+  WorkflowRunSource,
+  WorkflowValidationCommandResult,
+  WorkflowValidationRunReport,
+  WorkflowValidationStatus,
+} from "./types";
+import { commandStatus, jsonText, uniqueBy, workflowStatus } from "./utils";
+
+export const createWorkflowApplyReport = ({
+  workflow,
+  mode,
+  changedFiles = [],
+  generatedFiles = [],
+  appliedCommands = [],
+  recommendedValidationCommands,
+  commands = [],
+  diagnostics = [],
+  recommendations = [],
+  nextActions = [],
+  plan,
+}: Omit<
+  WorkflowApplyReport,
+  | "schemaVersion"
+  | "runId"
+  | "applyReportPath"
+  | "validationTarget"
+  | "status"
+  | "appliedCommands"
+  | "recommendedValidationCommands"
+  | "commands"
+  | "recommendations"
+> & {
+  appliedCommands?: WorkflowApplyCommand[];
+  recommendedValidationCommands?: WorkflowApplyCommand[];
+  commands?: WorkflowApplyCommand[];
+  recommendations?: WorkflowApplyReport["recommendations"];
+}): WorkflowApplyReport => {
+  const validationCommands = recommendedValidationCommands ?? commands;
+  return {
+    schemaVersion: 1,
+    workflow,
+    mode,
+    status: workflowStatus(diagnostics),
+    changedFiles: uniqueBy(changedFiles, (file) => `${file.action}:${file.path}:${file.reason}`),
+    generatedFiles: uniqueBy(generatedFiles, (file) => `${file.action}:${file.path}:${file.reason}`),
+    appliedCommands: uniqueBy(appliedCommands, (command) => command.command),
+    recommendedValidationCommands: uniqueBy(validationCommands, (command) => command.command),
+    commands: uniqueBy(validationCommands, (command) => command.command),
+    diagnostics,
+    recommendations: uniqueBy(recommendations, (recommendation) => `${recommendation.kind}:${recommendation.code}`),
+    nextActions: uniqueBy(nextActions, (action) => action.command),
+    plan,
+  };
+};
+
+export const resolveWorkflowCommand = (command: string, plan: WorkflowPlan) => {
+  const target = typeof plan.inputs.app === "string" ? plan.inputs.app : "<app-or-lib>";
+  return command
+    .replaceAll("<app-or-lib-or-pkg>", target)
+    .replaceAll("<app-or-lib>", target)
+    .replaceAll("<app-name>", target);
+};
+
+export const workflowCommandsForPlan = (plan: WorkflowPlan) =>
+  plan.validation.map((validation) => ({
+    command: resolveWorkflowCommand(validation.command, plan),
+    reason: validation.reason,
+    kind: validation.kind,
+  })) satisfies WorkflowApplyCommand[];
+
+export const workflowRunsDir = ".akan/workflows/runs";
+
+export const createWorkflowRunId = (prefix = "run") =>
+  `${prefix}-${new Date()
+    .toISOString()
+    .replace(/[-:.TZ]/g, "")
+    .slice(0, 14)}-${Math.random().toString(36).slice(2, 8)}`;
+
+const getRunId = (artifact: WorkflowRunArtifact) => {
+  if ("runId" in artifact && artifact.runId) return artifact.runId;
+  return createWorkflowRunId("mode" in artifact ? artifact.mode : artifact.kind);
+};
+
+export const workflowRunArtifactPath = (runId: string) => `${workflowRunsDir}/${runId}.json`;
+
+const withWorkflowRunMetadata = (
+  artifact: WorkflowRunArtifact,
+  runId: string,
+  artifactPath: string,
+): WorkflowRunArtifact => {
+  if ("mode" in artifact && (artifact.mode === "apply" || artifact.mode === "dry-run")) {
+    return { ...artifact, runId, applyReportPath: artifactPath, validationTarget: artifactPath };
+  }
+  if ("kind" in artifact) return { ...artifact, runId, repairReportPath: artifactPath };
+  return artifact;
+};
+
+export const writeWorkflowRunArtifact = async (workspace: Workspace, artifact: WorkflowRunArtifact) => {
+  const runId = getRunId(artifact);
+  const artifactPath = workflowRunArtifactPath(runId);
+  const artifactWithMetadata = withWorkflowRunMetadata(artifact, runId, artifactPath);
+  await workspace.writeFile(artifactPath, jsonText(artifactWithMetadata), { silent: true });
+  return { runId, path: artifactPath, artifact: artifactWithMetadata };
+};
+
+export const workflowSyncDir = ".akan/workflows/sync";
+
+const syncStateSlug = (target: string) =>
+  target
+    .trim()
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+
+export const workflowSyncStatePath = (target: string) => `${workflowSyncDir}/${syncStateSlug(target) || "target"}.json`;
+
+export const generatedFilePathsForTarget = (targetRoot: string, reason = "Generated files were refreshed by sync.") =>
+  [
+    { path: `${targetRoot}/lib/cnst.ts`, action: "sync", reason },
+    { path: `${targetRoot}/lib/dict.ts`, action: "sync", reason },
+    { path: `${targetRoot}/lib/option.ts`, action: "sync", reason },
+    { path: `${targetRoot}/lib/index.ts`, action: "sync", reason },
+  ] satisfies PrimitiveGeneratedFile[];
+
+export const writeGeneratedSyncState = async (workspace: Workspace, state: GeneratedSyncState) => {
+  const statePath = workflowSyncStatePath(state.target);
+  await workspace.writeFile(statePath, jsonText(state), { silent: true });
+  return statePath;
+};
+
+export const readWorkflowRunArtifact = async (workspace: Workspace, runId: string) => {
+  const artifactPath = workflowRunArtifactPath(runId);
+  if (!(await workspace.exists(artifactPath))) throw new Error(`Workflow run artifact does not exist: ${artifactPath}`);
+  return (await workspace.readJson(artifactPath)) as WorkflowRunArtifact;
+};
+
+export type WorkflowValidationCommandExecutor = (
+  command: WorkflowApplyCommand,
+) => Promise<WorkflowValidationCommandResult>;
+
+const failedCommandScopes = (commands: readonly WorkflowValidationCommandResult[]) =>
+  commands.filter((command) => command.status === "failed").map((command) => command.failureScope ?? "unknown");
+
+const errorDiagnosticScopes = (diagnostics: readonly WorkflowDiagnostic[]) =>
+  diagnostics
+    .filter((diagnostic) => diagnostic.severity === "error")
+    .map(
+      (diagnostic) =>
+        diagnostic.failureScope ??
+        (diagnostic.scope === "baseline"
+          ? "workspace-config"
+          : diagnostic.scope === "workflow"
+            ? "source-change"
+            : "unknown"),
+    );
+
+const hasScopeFailure = (
+  scopes: readonly WorkflowFailureScope[],
+  scope: WorkflowFailureScope,
+  diagnostics: readonly WorkflowDiagnostic[] = [],
+) =>
+  scopes.includes(scope) ||
+  diagnostics.some((diagnostic) => diagnostic.severity === "error" && diagnostic.failureScope === scope);
+
+const statusForScope = (
+  commands: readonly WorkflowValidationCommandResult[],
+  diagnostics: readonly WorkflowDiagnostic[],
+  scopes: readonly WorkflowFailureScope[],
+  expectedScope: WorkflowFailureScope,
+): WorkflowValidationStatus => {
+  const hasCommands = commands.length > 0 || diagnostics.length > 0;
+  if (!hasCommands) return "unknown";
+  return hasScopeFailure(scopes, expectedScope, diagnostics) ? "failed" : "passed";
+};
+
+const createKnownBlockers = (
+  commands: readonly WorkflowValidationCommandResult[],
+  diagnostics: readonly WorkflowDiagnostic[],
+): WorkflowKnownBlocker[] => {
+  const commandBlockers = commands
+    .filter(
+      (command) =>
+        command.status === "failed" &&
+        (command.failureScope === "workspace-config" || command.failureScope === "environment"),
+    )
+    .map((command) => ({
+      code: `workflow-validation-${command.failureScope}`,
+      message: `${command.failureScope === "environment" ? "Environment" : "Workspace configuration"} blocker: ${command.command}`,
+      failureScope: command.failureScope ?? "unknown",
+      command: command.command,
+      kind: command.kind,
+      count: 1,
+    }));
+  const diagnosticBlockers = diagnostics
+    .filter(
+      (diagnostic) =>
+        diagnostic.severity === "error" &&
+        (diagnostic.failureScope === "workspace-config" ||
+          diagnostic.failureScope === "environment" ||
+          diagnostic.scope === "baseline"),
+    )
+    .map((diagnostic) => ({
+      code: diagnostic.code,
+      message: diagnostic.message,
+      failureScope: diagnostic.failureScope ?? ("workspace-config" as const),
+      command: diagnostic.command,
+      kind: diagnostic.kind,
+      count: 1,
+    }));
+  const grouped = new Map<string, WorkflowKnownBlocker>();
+  for (const blocker of [...commandBlockers, ...diagnosticBlockers]) {
+    const key = `${blocker.failureScope}:${blocker.code}:${blocker.command ?? ""}:${blocker.message}`;
+    const existing = grouped.get(key);
+    if (existing) existing.count += blocker.count;
+    else grouped.set(key, blocker);
+  }
+  return [...grouped.values()];
+};
+
+const createValidationStatuses = (
+  commands: readonly WorkflowValidationCommandResult[],
+  diagnostics: readonly WorkflowDiagnostic[],
+) => {
+  const scopes = [...failedCommandScopes(commands), ...errorDiagnosticScopes(diagnostics)];
+  const sourceStatus = statusForScope(commands, diagnostics, scopes, "source-change");
+  const workspaceStatus =
+    hasScopeFailure(scopes, "workspace-config", diagnostics) || hasScopeFailure(scopes, "environment", diagnostics)
+      ? "failed"
+      : commands.length || diagnostics.length
+        ? "passed"
+        : "unknown";
+  const overallStatus = hasScopeFailure(scopes, "source-change", diagnostics)
+    ? "failed"
+    : hasScopeFailure(scopes, "workspace-config", diagnostics)
+      ? "blocked-by-workspace-config"
+      : hasScopeFailure(scopes, "environment", diagnostics)
+        ? "blocked-by-environment"
+        : workflowStatus(diagnostics) === "failed" || commandStatus(commands) === "failed"
+          ? "failed"
+          : "passed";
+  return { sourceStatus, workspaceStatus, overallStatus };
+};
+
+export const createWorkflowValidationRunReport = async ({
+  runId = createWorkflowRunId("validation"),
+  workflow,
+  source,
+  plan,
+  commands,
+  execute,
+  diagnostics = [],
+  baselineDiagnostics = [],
+  workflowDiagnostics = [],
+  repairActions = [],
+}: {
+  runId?: string;
+  workflow: string;
+  source: WorkflowRunSource;
+  plan?: WorkflowPlan;
+  commands: WorkflowApplyCommand[];
+  execute: WorkflowValidationCommandExecutor;
+  diagnostics?: WorkflowDiagnostic[];
+  baselineDiagnostics?: WorkflowDiagnostic[];
+  workflowDiagnostics?: WorkflowDiagnostic[];
+  repairActions?: RepairAction[];
+}): Promise<WorkflowValidationRunReport> => {
+  const results: WorkflowValidationCommandResult[] = [];
+  for (const command of commands) {
+    results.push(await execute(command));
+  }
+  const commandDiagnostics = results.flatMap((result) =>
+    result.status === "failed"
+      ? [
+          {
+            severity: "error" as const,
+            code: "workflow-validation-command-failed",
+            message: `Validation command failed: ${result.command}`,
+            command: result.command,
+            kind: result.kind,
+            failureScope: result.failureScope,
+          },
+        ]
+      : [],
+  );
+  const reportDiagnostics = [...diagnostics, ...commandDiagnostics];
+  const scopedDiagnostics = [...reportDiagnostics, ...baselineDiagnostics, ...workflowDiagnostics];
+  const statuses = createValidationStatuses(results, scopedDiagnostics);
+  return {
+    schemaVersion: 1,
+    runId,
+    workflow,
+    mode: "validate",
+    source,
+    status: statuses.overallStatus === "passed" ? "passed" : "failed",
+    ...statuses,
+    knownBlockers: createKnownBlockers(results, scopedDiagnostics),
+    commands: results,
+    diagnostics: reportDiagnostics,
+    baselineDiagnostics,
+    workflowDiagnostics,
+    repairActions: uniqueBy(repairActions, (action) => action.command),
+    nextActions: results
+      .filter((result) => result.status === "failed")
+      .map((result) => ({ command: result.command, reason: "Re-run this validation command after repair." })),
+    plan,
+  };
+};
+
+export const createDryRunWorkflowApplyReport = (plan: WorkflowPlan) => {
+  const changedFiles: PrimitiveChangedFile[] = plan.predictedChanges.flatMap((change) => {
+    if (change.action !== "create" && change.action !== "modify") return [];
+    return [
+      {
+        path: change.target,
+        action: change.action,
+        reason: change.reason,
+      },
+    ];
+  });
+  const generatedFiles: PrimitiveGeneratedFile[] = plan.predictedChanges.flatMap((change) => {
+    if (change.action !== "sync") return [];
+    return [
+      {
+        path: change.target,
+        action: "sync",
+        reason: change.reason,
+      },
+    ];
+  });
+  const diagnostics = [...plan.diagnostics];
+  return createWorkflowApplyReport({
+    workflow: plan.workflow,
+    mode: "dry-run",
+    changedFiles,
+    generatedFiles,
+    commands: workflowCommandsForPlan(plan),
+    diagnostics,
+    recommendations: plan.recommendations,
+    nextActions: workflowCommandsForPlan(plan),
+    plan,
+  });
+};
+
+export const createRepairReport = ({
+  command,
+  kind,
+  target = null,
+  diagnostics = [],
+  repairActions = [],
+  nextActions = [],
+  commands = [],
+  generatedFiles = [],
+  syncedAt,
+}: Omit<
+  RepairReport,
+  | "schemaVersion"
+  | "runId"
+  | "repairReportPath"
+  | "status"
+  | "target"
+  | "diagnostics"
+  | "repairActions"
+  | "nextActions"
+  | "commands"
+> &
+  Partial<
+    Pick<
+      RepairReport,
+      "target" | "diagnostics" | "repairActions" | "nextActions" | "commands" | "generatedFiles" | "syncedAt"
+    >
+  >): RepairReport => ({
+  schemaVersion: 1,
+  command,
+  kind,
+  target,
+  status: workflowStatus(diagnostics) === "failed" || commandStatus(commands) === "failed" ? "failed" : "passed",
+  diagnostics,
+  repairActions: uniqueBy(repairActions, (action) => action.command),
+  nextActions: uniqueBy(nextActions, (action) => action.command),
+  commands,
+  generatedFiles,
+  ...(syncedAt ? { syncedAt } : {}),
+});