@fern-api/replay 0.15.2 → 0.16.1

package/dist/index.d.cts

@@ -12,8 +12,6 @@ interface GenerationRecord {
     timestamp: string;
     cli_version: string;
     generator_versions: Record<string, string>;
-    /** SHA of the base branch HEAD before replay ran. Always on main's lineage. */
-    base_branch_head?: string;
 }
 interface StoredPatch {
     id: string;
@@ -216,8 +214,19 @@ declare class LockfileNotFoundError extends Error {
 declare class LockfileManager {
     private outputDir;
     private lock;
+    private fernignorePatterns;
     readonly warnings: string[];
     constructor(outputDir: string);
+    /**
+     * Inform the lockfile of the customer's `.fernignore` patterns so that
+     * `save()` can suppress its "Patch X removed from lockfile" warning when
+     * every file in the stripped patch is already `.fernignore`-protected.
+     * The strip itself still happens (credentials never persist); only the
+     * customer-visible warning is suppressed in that case, because the
+     * protected files survive the generator wipe regardless of whether the
+     * lockfile tracks them, so there's nothing for the customer to action.
+     */
+    setFernignorePatterns(patterns: string[]): void;
     get lockfilePath(): string;
     get customizationsPath(): string;
     exists(): boolean;
@@ -259,22 +268,24 @@ declare class ReplayDetector {
     private sdkOutputDir;
     readonly warnings: string[];
     constructor(git: GitClient, lockManager: LockfileManager, sdkOutputDir: string);
-    detectNewPatches(): Promise<DetectionResult>;
     /**
-     * Non-linear-history detection via `merge-base(prevGen, HEAD)`.
+     * Derive the previous-generation SHA from git history instead of trusting
+     * `lock.current_generation`.
      *
-     * After a squash-merge of a Fern-bot PR, `lastGen.commit_sha` (the previous
-     * `[fern-generated]`) is orphaned but still in git's object database. The
-     * merge-base is the commit on main from which the bot's branch was created —
-     * a reachable ancestor of HEAD. Walking that range and classifying each
-     * commit via `isGenerationCommit` mirrors the linear path and eliminates
-     * the bug class where pipeline-driven changes (autoversion, replay,
-     * generation) get bundled as customer customizations.
+     * Walks `git log HEAD --first-parent` and returns the SHA of the most recent
+     * commit that `isGenerationBoundary` classifies as a customization-baseline
+     * boundary, or null if no such commit is reachable from HEAD on the mainline.
      *
-     * Falls through to the legacy composite path when no common ancestor exists
-     * (truly disjoint history — orphan branches with no shared root).
+     * `isGenerationBoundary` is intentionally narrower than `isGenerationCommit`:
+     * it excludes `[fern-autoversion]` (lightweight bumps that don't reset the
+     * baseline) and the GitHub merge-commit subject for fern-bot regen PRs
+     * (which sits on first-parent but where the customer fix-up commits live
+     * on second-parent — stopping at the merge would hide them).
+     *
+     * See docs/adr/0001-derived-scan-boundary.md.
      */
-    private detectPatchesViaMergeBase;
+    findPreviousGenerationFromHistory(): Promise<string | null>;
+    detectNewPatches(): Promise<DetectionResult>;
     /**
      * Walk `${rangeStart}..HEAD`, classify each commit, emit one
      * `StoredPatch` per customer commit. Body shared by the linear path
@@ -368,6 +379,13 @@ declare class ReplayDetector {
     private resolveDiffBase;
     private parseGitLog;
     private getLastGeneration;
+    /**
+     * Build a transient `GenerationRecord` from a SHA derived by walking git
+     * history. Only `commit_sha` (and `tree_hash` when needed downstream) is
+     * load-bearing here; the rest are filled with defensible placeholders.
+     * This record is consumed by `detectPatchesInRange` and is never persisted.
+     */
+    private synthesizeGenerationRecord;
 }
 
 /**
@@ -468,7 +486,6 @@ declare class ReplayApplicator {
 interface CommitOptions {
     cliVersion: string;
     generatorVersions: Record<string, string>;
-    baseBranchHead?: string;
 }
 declare class ReplayCommitter {
     private git;
@@ -587,12 +604,10 @@ interface ReplayOptions {
     generatorVersions?: Record<string, string>;
     /** Commit generation + update lockfile, skip detection/application */
     skipApplication?: boolean;
-    /** SHA of the base branch HEAD before replay runs. Stored in lockfile for squash merge recovery. */
-    baseBranchHead?: string;
 }
 /**
  * Options honored by `applyPreparedReplay()`. `cliVersion`, `generatorVersions`,
- * `baseBranchHead`, `dryRun`, and `skipApplication` were all captured in phase 1
+ * `dryRun`, and `skipApplication` were all captured in phase 1
  * and re-supplying them here is meaningless.
  */
 interface ApplyOptions {
@@ -612,8 +627,8 @@ interface ApplyOptions {
  *   respected. `rebasePatches` uses `currentGenerationSha` (the pure `[fern-generated]`
  *   SHA), NOT HEAD — mid-phase commits do not retarget patches' `base_generation`.
  * - The service instance is single-use across the phase boundary: do not call
- *   other service methods (`syncFromDivergentMerge`, another `prepareReplay`, etc.)
- *   between phases. In-memory lockfile and warning state would be corrupted.
+ *   another `prepareReplay()` between phases. In-memory lockfile and warning
+ *   state would be corrupted.
  * - If the caller's mid-phase work throws or `applyPreparedReplay` is never called,
  *   the repo is left with the new `[fern-generated]` commit but a stale lockfile.
  *   Consumers MUST either (a) still call `applyPreparedReplay` so the lockfile
@@ -628,8 +643,6 @@ interface ReplayPreparation {
     previousGenerationSha: string | null;
     /** SHA of the new [fern-generated] commit created by prepareReplay (or HEAD for dry-run terminals) */
     currentGenerationSha: string;
-    /** options.baseBranchHead passed through */
-    baseBranchHead: string | null;
     /** @internal Opaque state consumed by applyPreparedReplay */
     readonly _prepared: InternalPreparationState;
 }
@@ -749,21 +762,6 @@ declare class ReplayService {
      * Behavior is byte-identical to the pre-split implementation for all existing callers.
      */
     runReplay(options?: ReplayOptions): Promise<ReplayReport>;
-    /**
-     * Sync the lockfile after a divergent PR was squash-merged.
-     * Call this BEFORE runReplay() when the CLI detects a merged divergent PR.
-     *
-     * After updating the generation record, re-detects customer patches via
-     * tree diff between the generation tag (pure generation tree) and HEAD
-     * (which includes customer customizations after squash merge). This ensures
-     * patches survive the squash merge → regenerate cycle even when the lockfile
-     * was restored from the base branch during conflict PR creation.
-     */
-    syncFromDivergentMerge(generationCommitSha: string, options?: {
-        cliVersion?: string;
-        generatorVersions?: Record<string, string>;
-        baseBranchHead?: string;
-    }): Promise<void>;
     private determineFlow;
     /**
      * Rebase cleanly applied patches so they are relative to the current generation.
@@ -887,7 +885,8 @@ declare class ReplayService {
      */
     /** @internal Used by Flow implementations in `src/flows/`. */
     cleanupStaleConflictMarkers(): Promise<void>;
-    private readFernignorePatterns;
+    /** @internal Used by Flow implementations in `src/flows/`. */
+    readFernignorePatterns(): string[];
     /** @internal Used by Flow implementations in `src/flows/`. */
     buildReport(flow: "first-generation" | "no-patches" | "normal-regeneration" | "skip-application", patches: StoredPatch[], results: ReplayResult[], options?: ReplayOptions, warnings?: string[], rebaseCounts?: {
         absorbed: number;

package/dist/index.d.ts

@@ -12,8 +12,6 @@ interface GenerationRecord {
     timestamp: string;
     cli_version: string;
     generator_versions: Record<string, string>;
-    /** SHA of the base branch HEAD before replay ran. Always on main's lineage. */
-    base_branch_head?: string;
 }
 interface StoredPatch {
     id: string;
@@ -216,8 +214,19 @@ declare class LockfileNotFoundError extends Error {
 declare class LockfileManager {
     private outputDir;
     private lock;
+    private fernignorePatterns;
     readonly warnings: string[];
     constructor(outputDir: string);
+    /**
+     * Inform the lockfile of the customer's `.fernignore` patterns so that
+     * `save()` can suppress its "Patch X removed from lockfile" warning when
+     * every file in the stripped patch is already `.fernignore`-protected.
+     * The strip itself still happens (credentials never persist); only the
+     * customer-visible warning is suppressed in that case, because the
+     * protected files survive the generator wipe regardless of whether the
+     * lockfile tracks them, so there's nothing for the customer to action.
+     */
+    setFernignorePatterns(patterns: string[]): void;
     get lockfilePath(): string;
     get customizationsPath(): string;
     exists(): boolean;
@@ -259,22 +268,24 @@ declare class ReplayDetector {
     private sdkOutputDir;
     readonly warnings: string[];
     constructor(git: GitClient, lockManager: LockfileManager, sdkOutputDir: string);
-    detectNewPatches(): Promise<DetectionResult>;
     /**
-     * Non-linear-history detection via `merge-base(prevGen, HEAD)`.
+     * Derive the previous-generation SHA from git history instead of trusting
+     * `lock.current_generation`.
      *
-     * After a squash-merge of a Fern-bot PR, `lastGen.commit_sha` (the previous
-     * `[fern-generated]`) is orphaned but still in git's object database. The
-     * merge-base is the commit on main from which the bot's branch was created —
-     * a reachable ancestor of HEAD. Walking that range and classifying each
-     * commit via `isGenerationCommit` mirrors the linear path and eliminates
-     * the bug class where pipeline-driven changes (autoversion, replay,
-     * generation) get bundled as customer customizations.
+     * Walks `git log HEAD --first-parent` and returns the SHA of the most recent
+     * commit that `isGenerationBoundary` classifies as a customization-baseline
+     * boundary, or null if no such commit is reachable from HEAD on the mainline.
      *
-     * Falls through to the legacy composite path when no common ancestor exists
-     * (truly disjoint history — orphan branches with no shared root).
+     * `isGenerationBoundary` is intentionally narrower than `isGenerationCommit`:
+     * it excludes `[fern-autoversion]` (lightweight bumps that don't reset the
+     * baseline) and the GitHub merge-commit subject for fern-bot regen PRs
+     * (which sits on first-parent but where the customer fix-up commits live
+     * on second-parent — stopping at the merge would hide them).
+     *
+     * See docs/adr/0001-derived-scan-boundary.md.
      */
-    private detectPatchesViaMergeBase;
+    findPreviousGenerationFromHistory(): Promise<string | null>;
+    detectNewPatches(): Promise<DetectionResult>;
     /**
      * Walk `${rangeStart}..HEAD`, classify each commit, emit one
      * `StoredPatch` per customer commit. Body shared by the linear path
@@ -368,6 +379,13 @@ declare class ReplayDetector {
     private resolveDiffBase;
     private parseGitLog;
     private getLastGeneration;
+    /**
+     * Build a transient `GenerationRecord` from a SHA derived by walking git
+     * history. Only `commit_sha` (and `tree_hash` when needed downstream) is
+     * load-bearing here; the rest are filled with defensible placeholders.
+     * This record is consumed by `detectPatchesInRange` and is never persisted.
+     */
+    private synthesizeGenerationRecord;
 }
 
 /**
@@ -468,7 +486,6 @@ declare class ReplayApplicator {
 interface CommitOptions {
     cliVersion: string;
     generatorVersions: Record<string, string>;
-    baseBranchHead?: string;
 }
 declare class ReplayCommitter {
     private git;
@@ -587,12 +604,10 @@ interface ReplayOptions {
     generatorVersions?: Record<string, string>;
     /** Commit generation + update lockfile, skip detection/application */
     skipApplication?: boolean;
-    /** SHA of the base branch HEAD before replay runs. Stored in lockfile for squash merge recovery. */
-    baseBranchHead?: string;
 }
 /**
  * Options honored by `applyPreparedReplay()`. `cliVersion`, `generatorVersions`,
- * `baseBranchHead`, `dryRun`, and `skipApplication` were all captured in phase 1
+ * `dryRun`, and `skipApplication` were all captured in phase 1
  * and re-supplying them here is meaningless.
  */
 interface ApplyOptions {
@@ -612,8 +627,8 @@ interface ApplyOptions {
  *   respected. `rebasePatches` uses `currentGenerationSha` (the pure `[fern-generated]`
  *   SHA), NOT HEAD — mid-phase commits do not retarget patches' `base_generation`.
  * - The service instance is single-use across the phase boundary: do not call
- *   other service methods (`syncFromDivergentMerge`, another `prepareReplay`, etc.)
- *   between phases. In-memory lockfile and warning state would be corrupted.
+ *   another `prepareReplay()` between phases. In-memory lockfile and warning
+ *   state would be corrupted.
  * - If the caller's mid-phase work throws or `applyPreparedReplay` is never called,
  *   the repo is left with the new `[fern-generated]` commit but a stale lockfile.
  *   Consumers MUST either (a) still call `applyPreparedReplay` so the lockfile
@@ -628,8 +643,6 @@ interface ReplayPreparation {
     previousGenerationSha: string | null;
     /** SHA of the new [fern-generated] commit created by prepareReplay (or HEAD for dry-run terminals) */
     currentGenerationSha: string;
-    /** options.baseBranchHead passed through */
-    baseBranchHead: string | null;
     /** @internal Opaque state consumed by applyPreparedReplay */
     readonly _prepared: InternalPreparationState;
 }
@@ -749,21 +762,6 @@ declare class ReplayService {
      * Behavior is byte-identical to the pre-split implementation for all existing callers.
      */
     runReplay(options?: ReplayOptions): Promise<ReplayReport>;
-    /**
-     * Sync the lockfile after a divergent PR was squash-merged.
-     * Call this BEFORE runReplay() when the CLI detects a merged divergent PR.
-     *
-     * After updating the generation record, re-detects customer patches via
-     * tree diff between the generation tag (pure generation tree) and HEAD
-     * (which includes customer customizations after squash merge). This ensures
-     * patches survive the squash merge → regenerate cycle even when the lockfile
-     * was restored from the base branch during conflict PR creation.
-     */
-    syncFromDivergentMerge(generationCommitSha: string, options?: {
-        cliVersion?: string;
-        generatorVersions?: Record<string, string>;
-        baseBranchHead?: string;
-    }): Promise<void>;
     private determineFlow;
     /**
      * Rebase cleanly applied patches so they are relative to the current generation.
@@ -887,7 +885,8 @@ declare class ReplayService {
      */
     /** @internal Used by Flow implementations in `src/flows/`. */
     cleanupStaleConflictMarkers(): Promise<void>;
-    private readFernignorePatterns;
+    /** @internal Used by Flow implementations in `src/flows/`. */
+    readFernignorePatterns(): string[];
     /** @internal Used by Flow implementations in `src/flows/`. */
     buildReport(flow: "first-generation" | "no-patches" | "normal-regeneration" | "skip-application", patches: StoredPatch[], results: ReplayResult[], options?: ReplayOptions, warnings?: string[], rebaseCounts?: {
         absorbed: number;