@beignet/cli 0.0.41 → 0.0.43

package/src/inspect.ts

@@ -1,4 +1,4 @@
-import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { parseProviderPackageMetadata } from "@beignet/core/providers";
 import { createPainter } from "./ansi.js";
@@ -15,6 +15,18 @@ import {
   type ResolvedBeignetConfig,
   resolveConfig,
 } from "./config.js";
+import {
+  applyPlannedDoctorFixes,
+  createDoctorFixPlan,
+  type DoctorFixApplyResult,
+  type DoctorFixOperationId,
+  type DoctorFixPlan,
+  type InspectFix,
+  type PlannedDoctorFixOperation,
+  type PlannedDoctorFixPlan,
+  planDoctorFixFileChange,
+  publicDoctorFixPlan,
+} from "./doctor-fixes.js";
 import {
   formatGithubAnnotation,
   type GithubAnnotationSeverity,
@@ -47,6 +59,7 @@ import {
   appendToNamedArray,
   appendToOutboxRegistryArray,
   arrayInitializerInfo,
+  codeCharacterIndexes,
   identifiersFromArrayExpression,
   insertAfterImports,
   matchingDelimiterIndex,
@@ -55,6 +68,7 @@ import {
 import {
   currentGeneratedPackageScripts,
   externalVersions,
+  isLegacyGeneratedPackageScript,
   legacyGeneratedPackageScripts,
 } from "./templates/shared.js";
 import { testSupportTemplateFiles } from "./templates/testing.js";
@@ -117,16 +131,14 @@ export type InspectDiagnostic = {
   message: string;
   file?: string;
   contract?: string;
+  /** Stable declaration identity for diagnostics about a named app concept. */
+  subject?: {
+    file: string;
+    exportName: string;
+  };
 };
 
-/**
- * Automatic doctor fix that was applied.
- */
-export type InspectFix = {
-  code: string;
-  message: string;
-  file: string;
-};
+export type { InspectFix } from "./doctor-fixes.js";
 
 /**
  * Detected app convention and missing convention files.
@@ -157,6 +169,18 @@ export type InspectAppResult = {
   fixes: InspectFix[];
 };
 
+/** Read-only doctor fix plan paired with the diagnostics it was derived from. */
+export type DoctorFixPlanResult = DoctorFixPlan & {
+  convention: InspectConvention;
+  diagnostics: InspectDiagnostic[];
+};
+
+/** Post-apply inspection paired with the guarded plan metadata that ran. */
+export type DoctorFixInspectionResult = InspectAppResult & {
+  planId: string;
+  operationIds: DoctorFixOperationId[];
+};
+
 type RouteExport = {
   method: HttpMethod;
   handlerFile: string;
@@ -235,9 +259,66 @@ export async function inspectApp(
   };
 }
 
+/** Options for guarded all-or-selected doctor fix application. */
+export type ApplyDoctorFixPlanOptions = InspectAppOptions & {
+  planId: string;
+  fixIds?: readonly DoctorFixOperationId[];
+};
+
+/** Plan every currently available low-risk doctor repair without writing. */
+export async function planDoctorFixes(
+  options: InspectAppOptions = {},
+): Promise<DoctorFixPlanResult> {
+  const plan = publicDoctorFixPlan(await buildDoctorFixPlan(options));
+  const inspected = await inspectApp(options);
+  return {
+    ...plan,
+    convention: inspected.convention,
+    diagnostics: inspected.diagnostics,
+  };
+}
+
+/** Apply a current doctor fix plan after verifying its plan ID. */
+export async function applyDoctorFixPlan(
+  options: ApplyDoctorFixPlanOptions,
+): Promise<DoctorFixApplyResult> {
+  const plan = await buildDoctorFixPlan(options);
+  if (plan.planId !== options.planId) {
+    throw new Error(
+      "Doctor fix plan is stale because the available repairs changed. No files were changed; run beignet doctor --fix --dry-run again.",
+    );
+  }
+  return applyPlannedDoctorFixes(plan, options.fixIds);
+}
+
 export async function applyDoctorFixes(
   options: InspectAppOptions = {},
 ): Promise<InspectFix[]> {
+  return (await applyDoctorFixesWithResult(options)).fixes;
+}
+
+export async function applyDoctorFixesWithResult(
+  options: InspectAppOptions = {},
+): Promise<DoctorFixApplyResult> {
+  const plan = await buildDoctorFixPlan(options);
+  return applyPlannedDoctorFixes(plan);
+}
+
+export function createDoctorFixInspectionResult(
+  inspected: InspectAppResult,
+  applied: DoctorFixApplyResult,
+): DoctorFixInspectionResult {
+  return {
+    ...inspected,
+    planId: applied.planId,
+    operationIds: applied.operationIds,
+    fixes: applied.fixes,
+  };
+}
+
+async function buildDoctorFixPlan(
+  options: InspectAppOptions = {},
+): Promise<PlannedDoctorFixPlan> {
   const targetDir = path.resolve(options.cwd ?? process.cwd());
   await assertDirectory(targetDir);
 
@@ -253,44 +334,63 @@ export async function applyDoctorFixes(
     config,
     contracts,
   );
-  const fixes: InspectFix[] = [];
+  const operations: PlannedDoctorFixOperation[] = [];
 
-  const packageFix = await fixPackageScripts(targetDir, files, convention);
-  if (packageFix) fixes.push(packageFix);
+  const packageFix = await planPackageScripts(targetDir, files, convention);
+  if (packageFix) operations.push(packageFix);
 
-  const routeGroupFix = await fixUnregisteredRouteGroups(
+  const routeGroupFix = await planUnregisteredRouteGroups(
     targetDir,
     files,
     config,
   );
-  if (routeGroupFix) fixes.push(routeGroupFix);
+  if (routeGroupFix) operations.push(routeGroupFix);
 
   const drift = await workflowRegistrationDrift(targetDir, files, config);
 
-  const scheduleFix = await fixUnregisteredSchedules(
+  if (config.paths.schedules === config.paths.tasks) {
+    const workflowFix = await planCoLocatedScheduleAndTaskRegistries(
+      targetDir,
+      files,
+      drift,
+      config,
+    );
+    if (workflowFix) operations.push(workflowFix);
+  } else {
+    const scheduleFix = await planUnregisteredSchedules(
+      targetDir,
+      files,
+      drift,
+      config,
+    );
+    if (scheduleFix) operations.push(scheduleFix);
+
+    const taskFix = await planUnregisteredTasks(
+      targetDir,
+      files,
+      drift,
+      config,
+    );
+    if (taskFix) operations.push(taskFix);
+  }
+
+  const outboxFix = await planUnregisteredOutboxEntries(
     targetDir,
     files,
     drift,
     config,
   );
-  if (scheduleFix) fixes.push(scheduleFix);
-
-  const taskFix = await fixUnregisteredTasks(targetDir, files, drift, config);
-  if (taskFix) fixes.push(taskFix);
+  if (outboxFix) operations.push(outboxFix);
 
-  fixes.push(
-    ...(await fixUnregisteredOutboxEntries(targetDir, files, drift, config)),
-  );
-
-  const listenerFix = await fixUnregisteredListeners(
+  const listenerFix = await planUnregisteredListeners(
     targetDir,
     files,
     drift,
     config,
   );
-  if (listenerFix) fixes.push(listenerFix);
+  if (listenerFix) operations.push(listenerFix);
 
-  const openApiFix = await fixDirectOpenApiArrayDrift(
+  const openApiFix = await planDirectOpenApiArrayDrift(
     targetDir,
     files,
     config,
@@ -298,9 +398,13 @@ export async function applyDoctorFixes(
     contracts,
     matchedRoutes,
   );
-  if (openApiFix) fixes.push(openApiFix);
+  if (openApiFix) operations.push(openApiFix);
 
-  return fixes;
+  return createDoctorFixPlan({
+    targetDir,
+    strict: Boolean(options.strict),
+    operations,
+  });
 }
 
 /**
@@ -329,12 +433,97 @@ export function formatRoutes(result: InspectAppResult): string {
   ]);
 }
 
+/**
+ * Format a read-only doctor fix plan with exact patches and apply commands.
+ */
+export function formatDoctorFixPlan(
+  plan: DoctorFixPlanResult,
+  options: { color?: boolean } = {},
+): string {
+  const paint = createPainter(options.color);
+  const lines: string[] = [];
+  if (plan.operations.length === 0) {
+    lines.push(`No applicable Beignet fixes found in ${plan.targetDir}.`);
+  } else {
+    const strictFlag = plan.strict ? " --strict" : "";
+    lines.push(
+      `Planned ${plan.operations.length} Beignet fix operation${plan.operations.length === 1 ? "" : "s"} in ${plan.targetDir}:`,
+      "",
+    );
+    for (const operation of plan.operations) {
+      lines.push(
+        `${paint("PLAN", "cyan")} ${operation.id}`,
+        ...operation.fixes.map(
+          (fix) => `  ${fix.code} ${fix.file}\n    ${fix.message}`,
+        ),
+        ...operation.changes.flatMap((change) => [
+          `  ${change.kind === "create" ? "Create" : "Update"} ${change.file}`,
+          change.patch.trimEnd(),
+        ]),
+        "",
+      );
+    }
+
+    lines.push(
+      `Plan ID: ${plan.planId}`,
+      "",
+      "Apply the complete plan:",
+      `  beignet doctor --fix${strictFlag} --plan ${plan.planId}`,
+      "",
+      "Apply selected operations:",
+      `  beignet doctor --fix${strictFlag} --plan ${plan.planId} --only ${plan.operations.map((operation) => operation.id).join(",")}`,
+    );
+  }
+
+  lines.push(
+    "",
+    formatDoctorResult(
+      {
+        targetDir: plan.targetDir,
+        strict: plan.strict,
+        diagnostics: plan.diagnostics,
+        fixes: [],
+      },
+      options,
+    ),
+  );
+  return lines.join("\n");
+}
+
+/**
+ * Format planned fixes as GitHub Actions notice annotations.
+ */
+export function formatDoctorFixPlanGithub(plan: DoctorFixPlanResult): string {
+  return [
+    ...plan.operations.map((operation) =>
+      formatGithubAnnotation({
+        severity: "notice",
+        file: operation.changes[0]?.file,
+        message: `${operation.id}: ${operation.fixes.map((fix) => fix.message).join(" ")} Plan ${plan.planId}.`,
+      }),
+    ),
+    ...formatDoctorDiagnosticsGithub(plan.diagnostics),
+  ].join("\n");
+}
+
+type DoctorFormatResult = Pick<
+  InspectAppResult,
+  "targetDir" | "strict" | "diagnostics" | "fixes"
+>;
+
 /**
  * Format doctor diagnostics and applied fixes for CLI output.
  */
 export function formatDoctor(
   result: InspectAppResult,
   options: { color?: boolean } = {},
+): string {
+  return formatDoctorResult(result, options);
+}
+
+function formatDoctorResult(
+  result: DoctorFormatResult,
+  options: { color?: boolean } = {},
 ): string {
   const paint = createPainter(options.color);
   const fixLines =
@@ -456,7 +645,7 @@ function productionHardeningChecklist(
   ];
 }
 
-function formatDoctorFooter(result: InspectAppResult): string {
+function formatDoctorFooter(result: DoctorFormatResult): string {
   const count = (severity: InspectDiagnostic["severity"]) =>
     result.diagnostics.filter((diagnostic) => diagnostic.severity === severity)
       .length;
@@ -469,15 +658,19 @@ function formatDoctorFooter(result: InspectAppResult): string {
  * Format doctor diagnostics as GitHub Actions annotations.
  */
 export function formatDoctorGithub(result: InspectAppResult): string {
-  return result.diagnostics
-    .map((diagnostic) =>
-      formatGithubAnnotation({
-        severity: githubAnnotationSeverity(diagnostic.severity),
-        file: diagnostic.file,
-        message: `${diagnostic.code}: ${diagnostic.message}`,
-      }),
-    )
-    .join("\n");
+  return formatDoctorDiagnosticsGithub(result.diagnostics).join("\n");
+}
+
+function formatDoctorDiagnosticsGithub(
+  diagnostics: InspectDiagnostic[],
+): string[] {
+  return diagnostics.map((diagnostic) =>
+    formatGithubAnnotation({
+      severity: githubAnnotationSeverity(diagnostic.severity),
+      file: diagnostic.file,
+      message: `${diagnostic.code}: ${diagnostic.message}`,
+    }),
+  );
 }
 
 function githubAnnotationSeverity(
@@ -878,73 +1071,19 @@ function balancedObjectSource(
   startIndex: number,
 ): string | undefined {
   if (source[startIndex] !== "{") return undefined;
-
-  let depth = 0;
-  let quote: '"' | "'" | "`" | undefined;
-  let escaped = false;
-
-  for (let index = startIndex; index < source.length; index += 1) {
-    const char = source[index];
-
-    if (quote) {
-      if (escaped) {
-        escaped = false;
-        continue;
-      }
-      if (char === "\\") {
-        escaped = true;
-        continue;
-      }
-      if (char === quote) quote = undefined;
-      continue;
-    }
-
-    if (char === '"' || char === "'" || char === "`") {
-      quote = char;
-      continue;
-    }
-
-    if (char === "{") {
-      depth += 1;
-      continue;
-    }
-
-    if (char === "}") {
-      depth -= 1;
-      if (depth === 0) return source.slice(startIndex, index + 1);
-    }
-  }
-
-  return undefined;
+  const endIndex = matchingDelimiterIndex(source, startIndex, "{", "}");
+  return endIndex === -1 ? undefined : source.slice(startIndex, endIndex + 1);
 }
 
 function topLevelObjectKeys(body: string): string[] {
   const keys: string[] = [];
   let depth = 0;
-  let quote: '"' | "'" | "`" | undefined;
-  let escaped = false;
+  let skipUntil = 0;
 
-  for (let index = 0; index < body.length; index += 1) {
+  for (const index of codeCharacterIndexes(body)) {
+    if (index < skipUntil) continue;
     const char = body[index];
 
-    if (quote) {
-      if (escaped) {
-        escaped = false;
-        continue;
-      }
-      if (char === "\\") {
-        escaped = true;
-        continue;
-      }
-      if (char === quote) quote = undefined;
-      continue;
-    }
-
-    if (char === '"' || char === "'" || char === "`") {
-      quote = char;
-      continue;
-    }
-
     if (char === "{" || char === "[" || char === "(") {
       depth += 1;
       continue;
@@ -963,8 +1102,7 @@ function topLevelObjectKeys(body: string): string[] {
     const name = identifier[0];
     const next = body.slice(index + name.length).match(/^\s*:/);
     if (next) keys.push(name);
-
-    index += name.length - 1;
+    skipUntil = index + name.length;
   }
 
   return keys;
@@ -3831,6 +3969,7 @@ async function inspectWorkflowRegistrationDrift(
           severity: "error",
           code,
           file: centralExists ? centralFile : registry.indexFile,
+          subject: workflowArtifactSubject(registry, member),
           message: centralExists
             ? `${workflowArtifactOrigin(registry, member)}, but it is not registered in ${registrationTarget} in ${centralFile}, so the ${noun} never runs. Import ${registry.registryName} and spread it into the ${kind} list.`
             : `${workflowArtifactOrigin(registry, member)}, but ${centralFile} does not exist, so the ${noun} never runs. Register ${registry.registryName} in ${centralFile} (or run \`${makeCommand}\` to create it).`,
@@ -3846,6 +3985,7 @@ async function inspectWorkflowRegistrationDrift(
           severity: "warning",
           code: "BEIGNET_OUTBOX_EVENT_UNREGISTERED",
           file: config.paths.outbox,
+          subject: workflowArtifactSubject(registry, member),
           message: `${workflowArtifactOrigin(registry, member)} and listeners react to it, but it is not registered in the events list of defineOutboxRegistry({...}) in ${config.paths.outbox}, so outbox drain cannot deliver it. Import ${registry.registryName} and spread it into the events list.`,
         });
       }
@@ -3857,6 +3997,7 @@ async function inspectWorkflowRegistrationDrift(
           severity: "warning",
           code: "BEIGNET_OUTBOX_JOB_UNREGISTERED",
           file: config.paths.outbox,
+          subject: workflowArtifactSubject(registry, member),
           message: `${workflowArtifactOrigin(registry, member)}, but it is not registered in the jobs list of defineOutboxRegistry({...}) in ${config.paths.outbox}, so outbox drain cannot deliver it. Import ${registry.registryName} and spread it into the jobs list.`,
         });
       }
@@ -3878,6 +4019,7 @@ async function inspectWorkflowRegistrationDrift(
           drift.listeners.wiringFile ??
           drift.listeners.eventBusFile ??
           registry.indexFile,
+        subject: workflowArtifactSubject(registry, member),
         message: `${workflowArtifactOrigin(registry, member)}, but no registerListeners(...) call references it, so the listener never receives events. Register ${registry.registryName} with registerListeners(...) in ${listenerTarget}.`,
       });
     }
@@ -3983,6 +4125,16 @@ function workflowArtifactOrigin(
   return `${memberFile} declares ${member} (exported through ${registry.registryName} in ${registry.indexFile})`;
 }
 
+function workflowArtifactSubject(
+  registry: FeatureWorkflowRegistry,
+  member: string,
+): NonNullable<InspectDiagnostic["subject"]> {
+  return {
+    file: registry.memberFiles.get(member) ?? registry.indexFile,
+    exportName: member,
+  };
+}
+
 async function workflowRegistrationDrift(
   targetDir: string,
   files: string[],
@@ -5464,26 +5616,9 @@ function splitTopLevelArguments(source: string): string[] {
   const args: string[] = [];
   let start = 0;
   let depth = 0;
-  let inString: string | undefined;
-  let escaped = false;
 
-  for (let index = 0; index < source.length; index++) {
+  for (const index of codeCharacterIndexes(source)) {
     const char = source[index];
-    if (inString) {
-      if (escaped) {
-        escaped = false;
-      } else if (char === "\\") {
-        escaped = true;
-      } else if (char === inString) {
-        inString = undefined;
-      }
-      continue;
-    }
-
-    if (char === '"' || char === "'" || char === "`") {
-      inString = char;
-      continue;
-    }
     if (char === "(" || char === "{" || char === "[") {
       depth += 1;
       continue;
@@ -6020,8 +6155,7 @@ async function inspectPackageScripts(
       severity: "warning",
       code: "BEIGNET_PACKAGE_TEST_SCRIPT_MISSING",
       file: "package.json",
-      message:
-        'package.json does not define a test script. Add "test": "tsx lib/beignet-test-runner.ts" or run beignet doctor --fix.',
+      message: `package.json does not define a test script. Add "test": "${currentGeneratedPackageScripts.test}" or run beignet doctor --fix.`,
     });
   }
 
@@ -6033,7 +6167,7 @@ async function inspectPackageScripts(
       severity: "warning",
       code: "BEIGNET_PACKAGE_SCRIPT_LEGACY",
       file: "package.json",
-      message: `package.json still uses legacy generated Bun scripts for ${legacyScripts.join(", ")}. Run beignet doctor --fix to migrate them to package-manager-neutral tsx scripts.`,
+      message: `package.json still uses legacy generated scripts for ${legacyScripts.join(", ")}. Run beignet doctor --fix to migrate them to the current package-manager-neutral scripts.`,
     });
   }
 
@@ -6067,11 +6201,11 @@ async function inspectPackageScripts(
   return diagnostics;
 }
 
-async function fixPackageScripts(
+async function planPackageScripts(
   targetDir: string,
   files: string[],
   convention: InspectConvention,
-): Promise<InspectFix | undefined> {
+): Promise<PlannedDoctorFixOperation | undefined> {
   if (!convention.resourceGenerator || !files.includes("package.json")) {
     return undefined;
   }
@@ -6097,10 +6231,8 @@ async function fixPackageScripts(
   }
 
   if (!hasDirectBunTestImports) {
-    for (const [name, legacyCommand] of Object.entries(
-      legacyGeneratedPackageScripts,
-    )) {
-      if (packageJson.scripts[name] === legacyCommand) {
+    for (const name of Object.keys(legacyGeneratedPackageScripts)) {
+      if (isLegacyGeneratedPackageScript(name, packageJson.scripts[name])) {
         packageJson.scripts[name] = currentGeneratedPackageScripts[name];
         if (!updatedScripts.includes(name)) updatedScripts.push(name);
       }
@@ -6118,29 +6250,25 @@ async function fixPackageScripts(
   }
 
   const next = `${JSON.stringify(packageJson, null, "\t")}\n`;
-  const createdSupportFiles = await createMissingTestSupportFiles(
-    targetDir,
-    files,
-    packageJson.scripts.test === currentGeneratedPackageScripts.test,
-  );
+  const createdSupportFiles =
+    packageJson.scripts.test === currentGeneratedPackageScripts.test
+      ? missingTestSupportFiles(files)
+      : [];
 
   if (next === original && createdSupportFiles.length === 0) return undefined;
 
-  if (next !== original) await writeFile(filePath, next);
-
+  let fix: InspectFix | undefined;
   if (addedTestScript) {
-    return {
+    fix = {
       code: "BEIGNET_PACKAGE_TEST_SCRIPT_MISSING",
       file: "package.json",
       message:
         createdSupportFiles.length > 0
-          ? `Added "test": "tsx lib/beignet-test-runner.ts" and ${createdSupportFiles.join(", ")}.`
-          : 'Added "test": "tsx lib/beignet-test-runner.ts".',
+          ? `Added "test": "${currentGeneratedPackageScripts.test}" and ${createdSupportFiles.join(", ")}.`
+          : `Added "test": "${currentGeneratedPackageScripts.test}".`,
     };
-  }
-
-  if (updatedScripts.length > 0) {
-    return {
+  } else if (updatedScripts.length > 0) {
+    fix = {
       code: "BEIGNET_PACKAGE_SCRIPT_LEGACY",
       file: "package.json",
       message: packageScriptFixMessage(
@@ -6149,31 +6277,48 @@ async function fixPackageScripts(
         addedTsx,
       ),
     };
-  }
-
-  if (createdSupportFiles.length > 0) {
-    return {
+  } else if (createdSupportFiles.length > 0) {
+    fix = {
       code: "BEIGNET_PACKAGE_TEST_SUPPORT_MISSING",
       file: "package.json",
       message: `Restored ${createdSupportFiles.join(", ")}.`,
     };
-  }
-
-  if (addedTsx) {
-    return {
+  } else if (addedTsx) {
+    fix = {
       code: "BEIGNET_PACKAGE_TSX_DEPENDENCY_MISSING",
       file: "package.json",
       message: 'Added "tsx" to devDependencies.',
     };
   }
 
-  return undefined;
+  if (!fix) return undefined;
+
+  return {
+    id: "package.repair-generated-support",
+    fixes: [fix],
+    changes: [
+      ...(next === original
+        ? []
+        : [
+            planDoctorFixFileChange({
+              file: "package.json",
+              before: original,
+              after: next,
+            }),
+          ]),
+      ...testSupportTemplateFiles
+        .filter((file) => createdSupportFiles.includes(file.path))
+        .map((file) =>
+          planDoctorFixFileChange({ file: file.path, after: file.content }),
+        ),
+    ],
+  };
 }
 
 function legacyGeneratedScriptNames(scripts: Record<string, string>): string[] {
-  return Object.entries(legacyGeneratedPackageScripts)
-    .filter(([name, command]) => scripts[name] === command)
-    .map(([name]) => name);
+  return Object.keys(legacyGeneratedPackageScripts).filter((name) =>
+    isLegacyGeneratedPackageScript(name, scripts[name]),
+  );
 }
 
 async function appUsesDirectBunTestImports(
@@ -6194,7 +6339,8 @@ function hasCurrentGeneratedTsxScript(
 ): boolean {
   return Object.values(currentGeneratedPackageScripts).some(
     (command) =>
-      command.startsWith("tsx ") && Object.values(scripts).includes(command),
+      (command.startsWith("tsx ") || command.includes("--import tsx")) &&
+      Object.values(scripts).includes(command),
   );
 }
 
@@ -6204,23 +6350,6 @@ function missingTestSupportFiles(files: string[]): string[] {
     .filter((file) => !files.includes(file));
 }
 
-async function createMissingTestSupportFiles(
-  targetDir: string,
-  files: string[],
-  shouldCreate: boolean,
-): Promise<string[]> {
-  if (!shouldCreate) return [];
-  const createdSupportFiles: string[] = [];
-  for (const file of testSupportTemplateFiles) {
-    if (files.includes(file.path)) continue;
-    const destination = path.join(targetDir, file.path);
-    await mkdir(path.dirname(destination), { recursive: true });
-    await writeFile(destination, file.content);
-    createdSupportFiles.push(file.path);
-  }
-  return createdSupportFiles;
-}
-
 function packageScriptFixMessage(
   updatedScripts: string[],
   createdSupportFiles: string[],
@@ -6274,6 +6403,8 @@ function dedupeDiagnostics(
       diagnostic.code,
       diagnostic.file ?? "",
       diagnostic.contract ?? "",
+      diagnostic.subject?.file ?? "",
+      diagnostic.subject?.exportName ?? "",
       diagnostic.message,
     ].join(":");
     if (seen.has(key)) continue;
@@ -6463,6 +6594,10 @@ async function inspectFeatureRouteRegistration(
         code: "BEIGNET_ROUTE_GROUP_UNREGISTERED",
         file: config.paths.server,
         contract: routeGroupContract.exportName,
+        subject: {
+          file: routeGroup.file,
+          exportName: routeGroup.name,
+        },
         message: contract
           ? `${routeGroup.file} declares ${routeGroup.name} for ${contract.exportName} (${contract.method} ${contract.path}), but ${routeGroup.name} is not registered in defineRoutes([...]) in ${config.paths.server}. Import ${routeGroup.name} and add it to the central route list.`
           : `${routeGroup.file} declares ${routeGroup.name} for ${routeGroupContract.exportName}, but ${routeGroup.name} is not registered in defineRoutes([...]) in ${config.paths.server}. Import ${routeGroup.name} and add it to the central route list.`,
@@ -6584,44 +6719,8 @@ function balancedArraySource(
   startIndex: number,
 ): string | undefined {
   if (source[startIndex] !== "[") return undefined;
-
-  let depth = 0;
-  let quote: '"' | "'" | "`" | undefined;
-  let escaped = false;
-
-  for (let index = startIndex; index < source.length; index += 1) {
-    const char = source[index];
-
-    if (quote) {
-      if (escaped) {
-        escaped = false;
-        continue;
-      }
-      if (char === "\\") {
-        escaped = true;
-        continue;
-      }
-      if (char === quote) quote = undefined;
-      continue;
-    }
-
-    if (char === '"' || char === "'" || char === "`") {
-      quote = char;
-      continue;
-    }
-
-    if (char === "[") {
-      depth += 1;
-      continue;
-    }
-
-    if (char === "]") {
-      depth -= 1;
-      if (depth === 0) return source.slice(startIndex, index + 1);
-    }
-  }
-
-  return undefined;
+  const endIndex = matchingDelimiterIndex(source, startIndex, "[", "]");
+  return endIndex === -1 ? undefined : source.slice(startIndex, endIndex + 1);
 }
 
 function routeGroupContractRef(
@@ -6651,21 +6750,10 @@ function routeGroupContractRef(
 }
 
 function registeredRouteGroups(source: string): Set<string> {
-  const defineRoutesMatch = /defineRoutes(?:<[^>]+>)?\(\[/.exec(source);
-  if (!defineRoutesMatch) return new Set();
-
-  const defineRoutesSource = source.slice(defineRoutesMatch.index);
-  const defineRoutesEnd = defineRoutesSource.indexOf("]),");
-  const searchSource =
-    defineRoutesEnd === -1
-      ? defineRoutesSource
-      : defineRoutesSource.slice(0, defineRoutesEnd);
-
-  return new Set(
-    [...searchSource.matchAll(/\b([A-Za-z_$][\w$]*)\b/g)].map(
-      (match) => match[1],
-    ),
-  );
+  const routes = firstDefineRoutesArgInfo(source);
+  return routes?.text.startsWith("[")
+    ? identifiersFromArrayExpression(routes.text)
+    : new Set();
 }
 
 async function registeredRouteGroupsForServer(
@@ -6727,14 +6815,14 @@ function findRouteGroupContract(
   );
 }
 
-async function fixDirectOpenApiArrayDrift(
+async function planDirectOpenApiArrayDrift(
   targetDir: string,
   files: string[],
   config: ResolvedBeignetConfig,
   convention: InspectConvention,
   contracts: InspectedContract[],
   matchedRoutes: MatchedRoutesResult,
-): Promise<InspectFix | undefined> {
+): Promise<PlannedDoctorFixOperation | undefined> {
   const routePath = path.join(targetDir, config.paths.openapiRoute);
   let source: string;
   try {
@@ -6777,21 +6865,32 @@ async function fixDirectOpenApiArrayDrift(
   )}`;
   if (next === source) return undefined;
 
-  await writeFile(routePath, next);
   return {
-    code: "BEIGNET_OPENAPI_MISSING",
-    file: config.paths.openapiRoute,
-    message: `Added ${missingContracts
-      .map((contract) => contract.exportName)
-      .join(", ")} to the direct createOpenAPIHandler contract array.`,
+    id: "openapi.register-missing",
+    fixes: [
+      {
+        code: "BEIGNET_OPENAPI_MISSING",
+        file: config.paths.openapiRoute,
+        message: `Added ${missingContracts
+          .map((contract) => contract.exportName)
+          .join(", ")} to the direct createOpenAPIHandler contract array.`,
+      },
+    ],
+    changes: [
+      planDoctorFixFileChange({
+        file: config.paths.openapiRoute,
+        before: source,
+        after: next,
+      }),
+    ],
   };
 }
 
-async function fixUnregisteredRouteGroups(
+async function planUnregisteredRouteGroups(
   targetDir: string,
   files: string[],
   config: ResolvedBeignetConfig,
-): Promise<InspectFix | undefined> {
+): Promise<PlannedDoctorFixOperation | undefined> {
   if (!files.includes(config.paths.server)) return undefined;
 
   const routeGroups = await readFeatureRouteGroups(targetDir, files, config);
@@ -6862,25 +6961,36 @@ async function fixUnregisteredRouteGroups(
   )}`;
   if (next === original) return undefined;
 
-  await writeFile(targetPath, next);
   return {
-    code: "BEIGNET_ROUTE_GROUP_UNREGISTERED",
-    file: targetFile,
-    message: `Registered ${groupsToAppend
-      .map((routeGroup) => routeGroup.name)
-      .join(", ")} in the central route list.`,
+    id: "routes.register-missing",
+    fixes: [
+      {
+        code: "BEIGNET_ROUTE_GROUP_UNREGISTERED",
+        file: targetFile,
+        message: `Registered ${groupsToAppend
+          .map((routeGroup) => routeGroup.name)
+          .join(", ")} in the central route list.`,
+      },
+    ],
+    changes: [
+      planDoctorFixFileChange({
+        file: targetFile,
+        before: original,
+        after: next,
+      }),
+    ],
   };
 }
 
-async function fixUnregisteredSchedules(
+async function planUnregisteredSchedules(
   targetDir: string,
   files: string[],
   drift: WorkflowRegistrationDrift,
   config: ResolvedBeignetConfig,
-): Promise<InspectFix | undefined> {
+): Promise<PlannedDoctorFixOperation | undefined> {
   if (!drift.schedules.centralExists) return undefined;
 
-  return applyWorkflowRegistryFix({
+  return planWorkflowRegistryOperation("schedules.register-missing", {
     targetDir,
     files,
     centralFile: config.paths.schedules,
@@ -6893,15 +7003,15 @@ async function fixUnregisteredSchedules(
   });
 }
 
-async function fixUnregisteredTasks(
+async function planUnregisteredTasks(
   targetDir: string,
   files: string[],
   drift: WorkflowRegistrationDrift,
   config: ResolvedBeignetConfig,
-): Promise<InspectFix | undefined> {
+): Promise<PlannedDoctorFixOperation | undefined> {
   if (!drift.tasks.centralExists) return undefined;
 
-  return applyWorkflowRegistryFix({
+  return planWorkflowRegistryOperation("tasks.register-missing", {
     targetDir,
     files,
     centralFile: config.paths.tasks,
@@ -6915,6 +7025,84 @@ async function fixUnregisteredTasks(
   });
 }
 
+async function planCoLocatedScheduleAndTaskRegistries(
+  targetDir: string,
+  files: string[],
+  drift: WorkflowRegistrationDrift,
+  config: ResolvedBeignetConfig,
+): Promise<PlannedDoctorFixOperation | undefined> {
+  if (!drift.schedules.centralExists || !drift.tasks.centralExists) {
+    return undefined;
+  }
+
+  const centralFile = config.paths.schedules;
+  let original: string;
+  try {
+    original = await readFile(path.join(targetDir, centralFile), "utf8");
+  } catch {
+    return undefined;
+  }
+
+  let next = original;
+  const fixes: InspectFix[] = [];
+  const repairedKinds: Array<"schedules" | "tasks"> = [];
+
+  const scheduleEdit = planWorkflowRegistryEdit({
+    files,
+    centralFile,
+    source: next,
+    unregistered: drift.schedules.unregistered,
+    code: "BEIGNET_SCHEDULE_UNREGISTERED",
+    listName: "the schedules array",
+    importSpecifier: (indexFile) => `@/${modulePath(indexFile)}`,
+    append: (source, entry, importLine) =>
+      appendToNamedArray(source, "schedules", entry, importLine),
+  });
+  if (scheduleEdit) {
+    next = scheduleEdit.after;
+    fixes.push(scheduleEdit.fix);
+    repairedKinds.push("schedules");
+  }
+
+  const taskEdit = planWorkflowRegistryEdit({
+    files,
+    centralFile,
+    source: next,
+    unregistered: drift.tasks.unregistered,
+    code: "BEIGNET_TASK_UNREGISTERED",
+    listName: "defineTasks([...])",
+    importSpecifier: (indexFile) => relativeModule(centralFile, indexFile),
+    append: (source, entry, importLine) =>
+      appendToNamedArray(source, "tasks", entry, importLine),
+  });
+  if (taskEdit) {
+    next = taskEdit.after;
+    fixes.push(taskEdit.fix);
+    repairedKinds.push("tasks");
+  }
+
+  if (fixes.length === 0 || next === original) return undefined;
+
+  const id: DoctorFixOperationId =
+    repairedKinds.length === 2
+      ? "workflows.register-missing"
+      : repairedKinds[0] === "schedules"
+        ? "schedules.register-missing"
+        : "tasks.register-missing";
+
+  return {
+    id,
+    fixes,
+    changes: [
+      planDoctorFixFileChange({
+        file: centralFile,
+        before: original,
+        after: next,
+      }),
+    ],
+  };
+}
+
 /**
  * Wire fully unregistered feature listener registries into the central
  * listener registry and ensure the providers file registers that central
@@ -6926,12 +7114,12 @@ async function fixUnregisteredTasks(
  * register against, or when the registry name is already imported from another
  * file. The diagnostic stays in every bail case.
  */
-async function fixUnregisteredListeners(
+async function planUnregisteredListeners(
   targetDir: string,
   files: string[],
   drift: WorkflowRegistrationDrift,
   config: ResolvedBeignetConfig,
-): Promise<InspectFix | undefined> {
+): Promise<PlannedDoctorFixOperation | undefined> {
   const candidates = drift.listeners.unregistered.filter(
     (entry) => entry.fullyUnregistered,
   );
@@ -7028,32 +7216,61 @@ async function fixUnregisteredListeners(
     return undefined;
   }
 
-  await mkdir(path.dirname(listenersPath), { recursive: true });
-  await writeFile(listenersPath, nextListeners);
-  if (nextProviders !== originalProviders) {
-    await writeFile(providersPath, nextProviders);
-  }
   return {
-    code: "BEIGNET_LISTENER_UNREGISTERED",
-    file: listenersFile,
-    message: `Registered ${candidateNames.join(", ")} in ${listenersFile} and wired listeners with registerListeners(...) in ${providersFile}.`,
+    id: "listeners.register-missing",
+    fixes: [
+      {
+        code: "BEIGNET_LISTENER_UNREGISTERED",
+        file: listenersFile,
+        message: `Registered ${candidateNames.join(", ")} in ${listenersFile} and wired listeners with registerListeners(...) in ${providersFile}.`,
+      },
+    ],
+    changes: [
+      ...(nextListeners === originalListeners
+        ? []
+        : [
+            planDoctorFixFileChange({
+              file: listenersFile,
+              before: originalListeners,
+              after: nextListeners,
+            }),
+          ]),
+      ...(nextProviders === originalProviders
+        ? []
+        : [
+            planDoctorFixFileChange({
+              file: providersFile,
+              before: originalProviders,
+              after: nextProviders,
+            }),
+          ]),
+    ],
   };
 }
 
-async function fixUnregisteredOutboxEntries(
+async function planUnregisteredOutboxEntries(
   targetDir: string,
   files: string[],
   drift: WorkflowRegistrationDrift,
   config: ResolvedBeignetConfig,
-): Promise<InspectFix[]> {
-  if (!drift.outbox.exists) return [];
+): Promise<PlannedDoctorFixOperation | undefined> {
+  if (!drift.outbox.exists) return undefined;
+
+  const outboxPath = path.join(targetDir, config.paths.outbox);
+  let original: string;
+  try {
+    original = await readFile(outboxPath, "utf8");
+  } catch {
+    return undefined;
+  }
 
+  let next = original;
   const fixes: InspectFix[] = [];
 
-  const eventFix = await applyWorkflowRegistryFix({
-    targetDir,
+  const eventFix = planWorkflowRegistryEdit({
     files,
     centralFile: config.paths.outbox,
+    source: next,
     unregistered: drift.outbox.events,
     code: "BEIGNET_OUTBOX_EVENT_UNREGISTERED",
     listName: "the outbox events list",
@@ -7061,12 +7278,15 @@ async function fixUnregisteredOutboxEntries(
     append: (source, entry, importLine) =>
       appendToOutboxRegistryArray(source, "events", entry, importLine),
   });
-  if (eventFix) fixes.push(eventFix);
+  if (eventFix) {
+    next = eventFix.after;
+    fixes.push(eventFix.fix);
+  }
 
-  const jobFix = await applyWorkflowRegistryFix({
-    targetDir,
+  const jobFix = planWorkflowRegistryEdit({
     files,
     centralFile: config.paths.outbox,
+    source: next,
     unregistered: drift.outbox.jobs,
     code: "BEIGNET_OUTBOX_JOB_UNREGISTERED",
     listName: "the outbox jobs list",
@@ -7074,9 +7294,23 @@ async function fixUnregisteredOutboxEntries(
     append: (source, entry, importLine) =>
       appendToOutboxRegistryArray(source, "jobs", entry, importLine),
   });
-  if (jobFix) fixes.push(jobFix);
+  if (jobFix) {
+    next = jobFix.after;
+    fixes.push(jobFix.fix);
+  }
 
-  return fixes;
+  if (fixes.length === 0 || next === original) return undefined;
+  return {
+    id: "outbox.register-missing",
+    fixes,
+    changes: [
+      planDoctorFixFileChange({
+        file: config.paths.outbox,
+        before: original,
+        after: next,
+      }),
+    ],
+  };
 }
 
 /**
@@ -7088,7 +7322,7 @@ async function fixUnregisteredOutboxEntries(
  * some members are already individually registered (appending the registry
  * spread would run those members twice). The diagnostic stays in that case.
  */
-async function applyWorkflowRegistryFix(options: {
+type WorkflowRegistryPlanOptions = {
   targetDir: string;
   files: string[];
   centralFile: string;
@@ -7097,12 +7331,12 @@ async function applyWorkflowRegistryFix(options: {
   listName: string;
   importSpecifier: (indexFile: string) => string;
   append: (source: string, entry: string, importLine?: string) => AppendResult;
-}): Promise<InspectFix | undefined> {
-  const candidates = options.unregistered.filter(
-    (entry) => entry.fullyUnregistered,
-  );
-  if (candidates.length === 0) return undefined;
+};
 
+async function planWorkflowRegistryOperation(
+  id: DoctorFixOperationId,
+  options: WorkflowRegistryPlanOptions,
+): Promise<PlannedDoctorFixOperation | undefined> {
   const centralPath = path.join(options.targetDir, options.centralFile);
   let original: string;
   try {
@@ -7111,7 +7345,30 @@ async function applyWorkflowRegistryFix(options: {
     return undefined;
   }
 
-  let next = original;
+  const edit = planWorkflowRegistryEdit({ ...options, source: original });
+  if (!edit) return undefined;
+  return {
+    id,
+    fixes: [edit.fix],
+    changes: [
+      planDoctorFixFileChange({
+        file: options.centralFile,
+        before: original,
+        after: edit.after,
+      }),
+    ],
+  };
+}
+
+function planWorkflowRegistryEdit(
+  options: Omit<WorkflowRegistryPlanOptions, "targetDir"> & { source: string },
+): { after: string; fix: InspectFix } | undefined {
+  const candidates = options.unregistered.filter(
+    (entry) => entry.fullyUnregistered,
+  );
+  if (candidates.length === 0) return undefined;
+
+  let next = options.source;
   const registeredNames: string[] = [];
 
   for (const { registry } of candidates) {
@@ -7143,13 +7400,15 @@ async function applyWorkflowRegistryFix(options: {
     }
   }
 
-  if (next === original || registeredNames.length === 0) return undefined;
+  if (next === options.source || registeredNames.length === 0) return undefined;
 
-  await writeFile(centralPath, next);
   return {
-    code: options.code,
-    file: options.centralFile,
-    message: `Registered ${registeredNames.join(", ")} in ${options.listName}.`,
+    after: next,
+    fix: {
+      code: options.code,
+      file: options.centralFile,
+      message: `Registered ${registeredNames.join(", ")} in ${options.listName}.`,
+    },
   };
 }
 
@@ -7347,26 +7606,9 @@ function firstCallArgInfo(
   argStart: number,
 ): { text: string; start: number; end: number } | undefined {
   let depth = 0;
-  let inString: string | undefined;
-  let escaped = false;
 
-  for (let index = argStart; index < source.length; index++) {
+  for (const index of codeCharacterIndexes(source, argStart)) {
     const char = source[index];
-    if (inString) {
-      if (escaped) {
-        escaped = false;
-      } else if (char === "\\") {
-        escaped = true;
-      } else if (char === inString) {
-        inString = undefined;
-      }
-      continue;
-    }
-
-    if (char === '"' || char === "'" || char === "`") {
-      inString = char;
-      continue;
-    }
 
     if (char === "[" || char === "(" || char === "{") {
       depth++;