@ontrails/trails 1.0.0-beta.14 → 1.0.0-beta.16

package/src/trails/draft-promote.ts

@@ -1,24 +1,41 @@
-import { existsSync, renameSync, statSync } from 'node:fs';
-import { basename, dirname, join, relative } from 'node:path';
+import { existsSync, statSync } from 'node:fs';
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+} from 'node:path';
 
 import {
   Result,
   ValidationError,
-  analyzeDraftState,
+  deriveDraftReport,
   isDraftId,
   trail,
 } from '@ontrails/core';
+import type { Topo } from '@ontrails/core';
 import {
   DRAFT_FILE_PREFIX,
-  findStringLiterals,
   isDraftMarkedFile,
-  parse,
   stripDraftFileMarkers,
 } from '@ontrails/warden';
+import { findStringLiterals, parse } from '@ontrails/warden/ast';
 import { z } from 'zod';
 
-import { loadApp } from './load-app.js';
+import {
+  applyProjectOperations,
+  planProjectOperations,
+} from '../project-writes.js';
+import type {
+  PlannedProjectOperation,
+  ProjectWriteOperation,
+} from '../project-writes.js';
+import type { FreshAppLease } from './load-app.js';
+import { tryLoadFreshAppLease } from './load-app.js';
 import { findTopoPath } from './project.js';
+import { resolveTrailRootDir } from './root-dir.js';
 
 interface PromotionEdit {
   readonly end: number;
@@ -164,10 +181,8 @@ const replaceLiteralValue = (
   };
 };
 
-const collectOutputId = (
-  app: Awaited<ReturnType<typeof loadApp>>,
-  id: string
-) => app.get(id) ?? app.signals.get(id) ?? app.getProvision(id);
+const collectOutputId = (app: Topo, id: string) =>
+  app.get(id) ?? app.signals.get(id) ?? app.getResource(id);
 
 const toRelativeOutputPath = (rootDir: string, filePath: string): string =>
   relative(rootDir, filePath).replaceAll('\\', '/');
@@ -178,6 +193,7 @@ const toProjectModulePath = (sourceImport: string): string =>
     : sourceImport;
 
 interface PromotionRewriteState {
+  readonly plannedOperations: PlannedProjectOperation[];
   readonly renames: FileRename[];
   readonly updatedSourceFiles: Set<string>;
 }
@@ -185,7 +201,6 @@ interface PromotionRewriteState {
 interface PromotionLoadState {
   readonly appModule: string | null;
   readonly loadError: string | null;
-  readonly loadedApp: Awaited<ReturnType<typeof loadApp>> | undefined;
 }
 
 const validatePromotionInput = (input: {
@@ -242,7 +257,22 @@ const resolveValidatedPromotionRoot = (
     return validation;
   }
 
-  const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+  let rootDir: string;
+  if (input.rootDir === undefined) {
+    const cwdResult = resolveTrailRootDir(undefined, ctx.cwd);
+    if (cwdResult.isErr()) {
+      return cwdResult;
+    }
+    rootDir = resolve(cwdResult.value);
+  } else if (isAbsolute(input.rootDir)) {
+    rootDir = resolve(input.rootDir);
+  } else {
+    const cwdResult = resolveTrailRootDir(undefined, ctx.cwd);
+    if (cwdResult.isErr()) {
+      return cwdResult;
+    }
+    rootDir = resolve(cwdResult.value, input.rootDir);
+  }
   const rootValidation = validatePromotionRoot(rootDir);
   if (rootValidation.isErr()) {
     return rootValidation;
@@ -251,27 +281,83 @@ const resolveValidatedPromotionRoot = (
   return Result.ok(rootDir);
 };
 
-const rewritePromotedSourceFiles = async (
+type SourceFileMap = Map<string, string>;
+type WriteProjectOperation = Extract<
+  ProjectWriteOperation,
+  { readonly kind: 'write' }
+>;
+
+const pushWriteOperation = (
+  operations: ProjectWriteOperation[],
+  operation: WriteProjectOperation
+): void => {
+  for (let index = operations.length - 1; index >= 0; index -= 1) {
+    const existing = operations[index];
+    if (
+      existing?.kind === 'rename' &&
+      (existing.from === operation.path || existing.to === operation.path)
+    ) {
+      break;
+    }
+    if (existing?.kind === 'write' && existing.path === operation.path) {
+      operations[index] = operation;
+      return;
+    }
+  }
+
+  operations.push(operation);
+};
+
+const readSourceFiles = async (
+  filePaths: readonly string[]
+): Promise<Result<SourceFileMap, Error>> => {
+  const sources = new Map<string, string>();
+  for (const filePath of filePaths) {
+    try {
+      sources.set(filePath, await Bun.file(filePath).text());
+    } catch (error) {
+      return Result.err(
+        new ValidationError(
+          `Cannot read source file "${filePath}"`,
+          error instanceof Error ? { cause: error } : undefined
+        )
+      );
+    }
+  }
+  return Result.ok(sources);
+};
+
+const planPromotedSourceFiles = (
   filePaths: readonly string[],
+  sources: SourceFileMap,
   fromId: string,
   toId: string,
-  updatedSourceFiles: Set<string>
-): Promise<void> => {
+  updatedSourceFiles: Set<string>,
+  operations: ProjectWriteOperation[]
+): Result<void, Error> => {
   for (const filePath of filePaths) {
-    const sourceCode = await Bun.file(filePath).text();
+    const sourceCode = sources.get(filePath);
+    if (sourceCode === undefined) {
+      return Result.err(
+        new ValidationError(`Cannot read source file "${filePath}"`)
+      );
+    }
+
     const replaced = replaceIdLiterals(sourceCode, filePath, fromId, toId);
     if (!replaced.changed) {
       continue;
     }
 
-    await Bun.write(filePath, replaced.nextSource);
+    sources.set(filePath, replaced.nextSource);
+    pushWriteOperation(operations, {
+      content: replaced.nextSource,
+      kind: 'write',
+      path: filePath,
+    });
     updatedSourceFiles.add(filePath);
   }
-};
 
-const hasDraftIdsInFile = async (filePath: string): Promise<boolean> => {
-  const sourceCode = await Bun.file(filePath).text();
-  return hasDraftIds(sourceCode, filePath);
+  return Result.ok();
 };
 
 const buildPromotableFileRename = (
@@ -295,9 +381,10 @@ const buildPromotableFileRename = (
   return Result.ok({ from: filePath, to: nextPath });
 };
 
-const collectPromotableFileRename = async (
-  filePath: string
-): Promise<Result<FileRename | null, Error>> => {
+const collectPromotableFileRename = (
+  filePath: string,
+  sourceCode: string
+): Result<FileRename | null, Error> => {
   if (!isDraftMarkedFile(filePath)) {
     return Result.ok(null);
   }
@@ -307,7 +394,7 @@ const collectPromotableFileRename = async (
     return Result.ok(null);
   }
 
-  if (await hasDraftIdsInFile(filePath)) {
+  if (hasDraftIds(sourceCode, filePath)) {
     return Result.ok(null);
   }
 
@@ -339,12 +426,19 @@ const validateRenameTargets = (
   return Result.ok();
 };
 
-const collectFileRenames = async (
-  filePaths: readonly string[]
-): Promise<Result<FileRename[], Error>> => {
+const collectFileRenames = (
+  filePaths: readonly string[],
+  sources: SourceFileMap
+): Result<FileRename[], Error> => {
   const renames: FileRename[] = [];
   for (const filePath of filePaths) {
-    const renameResult = await collectPromotableFileRename(filePath);
+    const sourceCode = sources.get(filePath);
+    if (sourceCode === undefined) {
+      return Result.err(
+        new ValidationError(`Cannot read source file "${filePath}"`)
+      );
+    }
+    const renameResult = collectPromotableFileRename(filePath, sourceCode);
     if (renameResult.isErr()) {
       return renameResult;
     }
@@ -355,26 +449,6 @@ const collectFileRenames = async (
   return Result.ok(renames);
 };
 
-const collectAndApplyFileRenames = async (
-  filePaths: readonly string[]
-): Promise<Result<FileRename[], Error>> => {
-  const collected = await collectFileRenames(filePaths);
-  if (collected.isErr()) {
-    return collected;
-  }
-
-  const renames = collected.value;
-  const valid = validateRenameTargets(renames);
-  if (valid.isErr()) {
-    return valid;
-  }
-
-  for (const r of renames) {
-    renameSync(r.from, r.to);
-  }
-  return Result.ok(renames);
-};
-
 const applyRenameEffects = (
   updatedSourceFiles: Set<string>,
   renames: readonly FileRename[]
@@ -386,6 +460,30 @@ const applyRenameEffects = (
   }
 };
 
+const applySourceRenameEffects = (
+  sources: SourceFileMap,
+  renames: readonly FileRename[]
+): void => {
+  for (const rename of renames) {
+    const sourceCode = sources.get(rename.from);
+    if (sourceCode === undefined) {
+      continue;
+    }
+    sources.delete(rename.from);
+    sources.set(rename.to, sourceCode);
+  }
+};
+
+const applyFilePathRenames = (
+  filePaths: readonly string[],
+  renames: readonly FileRename[]
+): string[] => {
+  const renamedBySource = new Map(
+    renames.map((rename) => [rename.from, rename.to])
+  );
+  return filePaths.map((filePath) => renamedBySource.get(filePath) ?? filePath);
+};
+
 const applyRelativeImportRename = (
   sourceCode: string,
   filePath: string,
@@ -431,69 +529,128 @@ const rewriteRelativeImportsForFile = (
   return { changed, sourceCode: nextSourceCode };
 };
 
-const updateRelativeImportsForFile = async (
+const planRelativeImportsForFile = (
   filePath: string,
-  renames: readonly FileRename[]
-): Promise<boolean> => {
-  const sourceCode = await Bun.file(filePath).text();
+  renames: readonly FileRename[],
+  sources: SourceFileMap,
+  operations: ProjectWriteOperation[]
+): Result<boolean, Error> => {
+  const sourceCode = sources.get(filePath);
+  if (sourceCode === undefined) {
+    return Result.err(
+      new ValidationError(`Cannot read source file "${filePath}"`)
+    );
+  }
+
   const updated = rewriteRelativeImportsForFile(filePath, renames, sourceCode);
   if (updated.changed) {
-    await Bun.write(filePath, updated.sourceCode);
-    return true;
+    sources.set(filePath, updated.sourceCode);
+    pushWriteOperation(operations, {
+      content: updated.sourceCode,
+      kind: 'write',
+      path: filePath,
+    });
+    return Result.ok(true);
   }
 
-  return false;
+  return Result.ok(false);
 };
 
-const updateRelativeImports = async (
+const planRelativeImports = (
   filePaths: readonly string[],
-  renames: readonly FileRename[]
-): Promise<string[]> => {
-  const updatedFiles = new Set<string>();
-
+  renames: readonly FileRename[],
+  sources: SourceFileMap,
+  updatedSourceFiles: Set<string>,
+  operations: ProjectWriteOperation[]
+): Result<void, Error> => {
   for (const filePath of filePaths) {
-    const changed = await updateRelativeImportsForFile(filePath, renames);
-    if (changed) {
-      updatedFiles.add(filePath);
+    const changed = planRelativeImportsForFile(
+      filePath,
+      renames,
+      sources,
+      operations
+    );
+    if (changed.isErr()) {
+      return Result.err(changed.error);
+    }
+    if (changed.value) {
+      updatedSourceFiles.add(filePath);
     }
   }
 
-  return [...updatedFiles].toSorted();
+  return Result.ok();
 };
 
 const rewritePromotionState = async (
   rootDir: string,
   input: {
+    readonly dryRun?: boolean | undefined;
     readonly fromId: string;
     readonly renameFiles: boolean;
     readonly toId: string;
   }
 ): Promise<Result<PromotionRewriteState, Error>> => {
   const initialFiles = collectTsFiles(rootDir);
+  const sourcesResult = await readSourceFiles(initialFiles);
+  if (sourcesResult.isErr()) {
+    return Result.err(sourcesResult.error);
+  }
+  const sources = sourcesResult.value;
+  const operations: ProjectWriteOperation[] = [];
   const updatedSourceFiles = new Set<string>();
 
-  await rewritePromotedSourceFiles(
+  const rewritten = planPromotedSourceFiles(
     initialFiles,
+    sources,
     input.fromId,
     input.toId,
-    updatedSourceFiles
+    updatedSourceFiles,
+    operations
   );
+  if (rewritten.isErr()) {
+    return Result.err(rewritten.error);
+  }
 
   const renamesResult = input.renameFiles
-    ? await collectAndApplyFileRenames(initialFiles)
+    ? collectFileRenames(initialFiles, sources)
     : Result.ok([] as FileRename[]);
   if (renamesResult.isErr()) {
     return Result.err(renamesResult.error);
   }
 
+  const valid = validateRenameTargets(renamesResult.value);
+  if (valid.isErr()) {
+    return valid;
+  }
+
+  for (const rename of renamesResult.value) {
+    operations.push({ from: rename.from, kind: 'rename', to: rename.to });
+  }
+
   applyRenameEffects(updatedSourceFiles, renamesResult.value);
-  for (const f of await updateRelativeImports(
-    collectTsFiles(rootDir),
-    renamesResult.value
-  )) {
-    updatedSourceFiles.add(f);
+  applySourceRenameEffects(sources, renamesResult.value);
+  const importUpdates = planRelativeImports(
+    applyFilePathRenames(initialFiles, renamesResult.value),
+    renamesResult.value,
+    sources,
+    updatedSourceFiles,
+    operations
+  );
+  if (importUpdates.isErr()) {
+    return Result.err(importUpdates.error);
   }
-  return Result.ok({ renames: renamesResult.value, updatedSourceFiles });
+
+  const plannedOperations = input.dryRun
+    ? planProjectOperations(rootDir, operations)
+    : await applyProjectOperations(rootDir, operations);
+  if (plannedOperations.isErr()) {
+    return Result.err(plannedOperations.error);
+  }
+  return Result.ok({
+    plannedOperations: plannedOperations.value,
+    renames: renamesResult.value,
+    updatedSourceFiles,
+  });
 };
 
 const resolvePromotionAppModule = async (
@@ -511,23 +668,55 @@ const resolvePromotionAppModule = async (
   );
 };
 
-const loadVerifiedApp = async (
-  appModule: string | null,
+/**
+ * Run `consume` while holding a fresh-load lease on `appModule`.
+ *
+ * @remarks
+ * The lease deletes its on-disk mirror on release. Any Topo consumption that
+ * may trigger deferred filesystem imports (for example inside a trail's
+ * `blaze` or a lazy relative `import()`) must run before the lease is
+ * released, otherwise those resolutions race the mirror teardown. Collapsing
+ * consumption into the leased critical section keeps that contract
+ * structural rather than relying on the caller to discover it.
+ */
+type LeaseAttempt =
+  | {
+      readonly ok: true;
+      readonly lease: FreshAppLease;
+    }
+  | { readonly ok: false; readonly loadError: string };
+
+const tryAcquireLease = async (
+  appModule: string,
   rootDir: string
-): Promise<PromotionLoadState> => {
+): Promise<LeaseAttempt> => {
+  const loaded = await tryLoadFreshAppLease(appModule, rootDir);
+  if (loaded.isErr()) {
+    return { loadError: loaded.error.message, ok: false };
+  }
+  return { lease: loaded.value, ok: true };
+};
+
+const withVerifiedApp = async <T>(
+  appModule: string | null,
+  rootDir: string,
+  consume: (app: Topo) => T | Promise<T>
+): Promise<{ readonly load: PromotionLoadState; readonly value: T | null }> => {
   if (appModule === null) {
-    return { appModule, loadError: null, loadedApp: undefined };
+    return { load: { appModule, loadError: null }, value: null };
   }
 
-  let loadError: string | null = null;
-  const loadedApp = await loadApp(appModule, rootDir, { fresh: true }).catch(
-    (error: unknown): undefined => {
-      loadError = error instanceof Error ? error.message : String(error);
-      return undefined;
-    }
-  );
+  const attempt = await tryAcquireLease(appModule, rootDir);
+  if (!attempt.ok) {
+    return { load: { appModule, loadError: attempt.loadError }, value: null };
+  }
 
-  return { appModule, loadError, loadedApp };
+  try {
+    const value = await consume(attempt.lease.app);
+    return { load: { appModule, loadError: null }, value };
+  } finally {
+    attempt.lease.release();
+  }
 };
 
 const toRenamedFiles = (rootDir: string, renames: readonly FileRename[]) =>
@@ -541,19 +730,33 @@ const toUpdatedFiles = (rootDir: string, updatedSourceFiles: Set<string>) =>
     .toSorted()
     .map((filePath) => toRelativeOutputPath(rootDir, filePath));
 
+const buildUnverifiedPromotionMessage = (
+  loadError: string | null,
+  dryRun: boolean
+): string => {
+  if (dryRun) {
+    return 'Promotion plan is valid. Re-run without dryRun to apply it.';
+  }
+
+  return loadError === null
+    ? 'Promotion rewrote source files, but no topo entrypoint could be loaded for verification.'
+    : `Promotion rewrote source files, but verification failed: ${loadError}`;
+};
+
 const buildUnverifiedPromotionResult = (
   rootDir: string,
   loadError: string | null,
   renames: readonly FileRename[],
   updatedSourceFiles: Set<string>,
-  appModule: string | null
+  appModule: string | null,
+  plannedOperations: readonly PlannedProjectOperation[],
+  dryRun: boolean
 ) =>
   Result.ok({
     appModule,
-    message:
-      loadError === null
-        ? 'Promotion rewrote source files, but no topo entrypoint could be loaded for verification.'
-        : `Promotion rewrote source files, but verification failed: ${loadError}`,
+    dryRun,
+    message: buildUnverifiedPromotionMessage(loadError, dryRun),
+    plannedOperations,
     promotedEstablished: false,
     remainingDraftIds: [],
     renamedFiles: toRenamedFiles(rootDir, renames),
@@ -562,11 +765,12 @@ const buildUnverifiedPromotionResult = (
 
 const buildVerifiedPromotionResult = (
   rootDir: string,
-  analysis: ReturnType<typeof analyzeDraftState>,
+  analysis: ReturnType<typeof deriveDraftReport>,
   promotedEstablished: boolean,
   renames: readonly FileRename[],
   updatedSourceFiles: Set<string>,
   appModule: string | null,
+  plannedOperations: readonly PlannedProjectOperation[],
   toId: string
 ) => {
   const blockingFinding = analysis.findings.find(
@@ -575,11 +779,13 @@ const buildVerifiedPromotionResult = (
 
   return Result.ok({
     appModule,
+    dryRun: false,
     message:
       blockingFinding?.message ??
       (promotedEstablished
         ? `Promoted "${toId}" is now established.`
         : `Promoted "${toId}" could not be verified as established.`),
+    plannedOperations,
     promotedEstablished,
     remainingDraftIds: [...analysis.declaredDraftIds].toSorted(),
     renamedFiles: toRenamedFiles(rootDir, renames),
@@ -589,13 +795,14 @@ const buildVerifiedPromotionResult = (
 
 const buildVerifiedPromotionResultFromApp = (
   rootDir: string,
-  loadedApp: Awaited<ReturnType<typeof loadApp>>,
+  loadedApp: Topo,
   renames: readonly FileRename[],
   updatedSourceFiles: Set<string>,
   appModule: string | null,
+  plannedOperations: readonly PlannedProjectOperation[],
   toId: string
 ) => {
-  const analysis = analyzeDraftState(loadedApp);
+  const analysis = deriveDraftReport(loadedApp);
   const promotedNode = collectOutputId(loadedApp, toId);
   const promotedEstablished =
     promotedNode !== undefined && !analysis.contaminatedIds.has(toId);
@@ -607,6 +814,7 @@ const buildVerifiedPromotionResultFromApp = (
     renames,
     updatedSourceFiles,
     appModule,
+    plannedOperations,
     toId
   );
 };
@@ -614,6 +822,7 @@ const buildVerifiedPromotionResultFromApp = (
 const promoteDraftState = async (
   input: {
     readonly appModule?: string | undefined;
+    readonly dryRun?: boolean | undefined;
     readonly fromId: string;
     readonly renameFiles: boolean;
     readonly rootDir?: string | undefined;
@@ -633,27 +842,45 @@ const promoteDraftState = async (
 
   const { renames, updatedSourceFiles } = rewriteResult.value;
   const appModule = await resolvePromotionAppModule(input, rootDirResult.value);
-  const { loadError, loadedApp } = await loadVerifiedApp(
-    appModule,
-    rootDirResult.value
-  );
+  if (input.dryRun === true) {
+    return buildUnverifiedPromotionResult(
+      rootDirResult.value,
+      null,
+      renames,
+      updatedSourceFiles,
+      appModule,
+      rewriteResult.value.plannedOperations,
+      true
+    );
+  }
 
-  return loadedApp
-    ? buildVerifiedPromotionResultFromApp(
+  const { load, value } = await withVerifiedApp(
+    appModule,
+    rootDirResult.value,
+    (loadedApp) =>
+      buildVerifiedPromotionResultFromApp(
         rootDirResult.value,
         loadedApp,
         renames,
         updatedSourceFiles,
         appModule,
+        rewriteResult.value.plannedOperations,
         input.toId
       )
-    : buildUnverifiedPromotionResult(
-        rootDirResult.value,
-        loadError,
-        renames,
-        updatedSourceFiles,
-        appModule
-      );
+  );
+
+  return (
+    value ??
+    buildUnverifiedPromotionResult(
+      rootDirResult.value,
+      load.loadError,
+      renames,
+      updatedSourceFiles,
+      appModule,
+      rewriteResult.value.plannedOperations,
+      false
+    )
+  );
 };
 
 export const draftPromoteTrail = trail('draft.promote', {
@@ -664,6 +891,7 @@ export const draftPromoteTrail = trail('draft.promote', {
     {
       error: 'ValidationError',
       input: {
+        // warden-ignore-next-line
         fromId: '_draft.entity.prepare',
         renameFiles: true,
         rootDir: './__does_not_exist__/draft-promote-example',
@@ -677,6 +905,10 @@ export const draftPromoteTrail = trail('draft.promote', {
       .string()
       .optional()
       .describe('Optional app module to verify after promotion'),
+    dryRun: z
+      .boolean()
+      .default(false)
+      .describe('Plan promotion rewrites without touching source files'),
     fromId: z.string().describe('Draft id to promote'),
     renameFiles: z
       .boolean()
@@ -690,7 +922,19 @@ export const draftPromoteTrail = trail('draft.promote', {
   intent: 'write',
   output: z.object({
     appModule: z.string().nullable(),
+    dryRun: z.boolean(),
     message: z.string(),
+    plannedOperations: z.array(
+      z.discriminatedUnion('kind', [
+        z.object({ kind: z.literal('mkdir'), path: z.string() }),
+        z.object({
+          from: z.string(),
+          kind: z.literal('rename'),
+          to: z.string(),
+        }),
+        z.object({ kind: z.literal('write'), path: z.string() }),
+      ])
+    ),
     promotedEstablished: z.boolean(),
     remainingDraftIds: z.array(z.string()),
     renamedFiles: z.array(