@fern-api/replay 0.15.1 → 0.16.0

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;
@@ -259,22 +257,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`.
+     *
+     * 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.
      *
-     * 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.
+     * `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).
      *
-     * Falls through to the legacy composite path when no common ancestor exists
-     * (truly disjoint history — orphan branches with no shared root).
+     * 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
@@ -308,9 +308,7 @@ declare class ReplayDetector {
      * within the current linear detection window, and are absent from
      * HEAD at the end of the window.
      *
-     * Rationale: on a merge commit, createMergeCompositePatch already diffs
-     * firstParent..mergeCommit so net-zero files never enter the composite. On
-     * linear history each commit becomes its own patch, so a file that was
+     * Rationale: each commit becomes its own patch, so a file that was
      * briefly added and later removed survives as a create+delete pair whose
      * cumulative diff is empty. We drop such patches before they reach the
      * lockfile.
@@ -341,13 +339,6 @@ declare class ReplayDetector {
      * more aggressively. On typical SDK repos this is a single sub-10ms call.
      */
     private listHeadFiles;
-    /**
-     * Create a single composite patch for a merge commit by diffing the merge
-     * commit against its first parent. This captures the net change of the
-     * entire merged branch as one patch, eliminating accumulator chaining and
-     * zero-net-change ghost conflicts.
-     */
-    private createMergeCompositePatch;
     /**
      * Detect patches via tree diff for non-linear history. Returns a composite patch.
      * Revert reconciliation is skipped here because tree-diff produces a single composite
@@ -377,6 +368,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;
 }
 
 /**
@@ -477,7 +475,6 @@ declare class ReplayApplicator {
 interface CommitOptions {
     cliVersion: string;
     generatorVersions: Record<string, string>;
-    baseBranchHead?: string;
 }
 declare class ReplayCommitter {
     private git;
@@ -596,12 +593,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 {
@@ -621,8 +616,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
@@ -637,8 +632,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;
 }
@@ -758,21 +751,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.

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;
@@ -259,22 +257,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`.
+     *
+     * 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.
      *
-     * 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.
+     * `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).
      *
-     * Falls through to the legacy composite path when no common ancestor exists
-     * (truly disjoint history — orphan branches with no shared root).
+     * 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
@@ -308,9 +308,7 @@ declare class ReplayDetector {
      * within the current linear detection window, and are absent from
      * HEAD at the end of the window.
      *
-     * Rationale: on a merge commit, createMergeCompositePatch already diffs
-     * firstParent..mergeCommit so net-zero files never enter the composite. On
-     * linear history each commit becomes its own patch, so a file that was
+     * Rationale: each commit becomes its own patch, so a file that was
      * briefly added and later removed survives as a create+delete pair whose
      * cumulative diff is empty. We drop such patches before they reach the
      * lockfile.
@@ -341,13 +339,6 @@ declare class ReplayDetector {
      * more aggressively. On typical SDK repos this is a single sub-10ms call.
      */
     private listHeadFiles;
-    /**
-     * Create a single composite patch for a merge commit by diffing the merge
-     * commit against its first parent. This captures the net change of the
-     * entire merged branch as one patch, eliminating accumulator chaining and
-     * zero-net-change ghost conflicts.
-     */
-    private createMergeCompositePatch;
     /**
      * Detect patches via tree diff for non-linear history. Returns a composite patch.
      * Revert reconciliation is skipped here because tree-diff produces a single composite
@@ -377,6 +368,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;
 }
 
 /**
@@ -477,7 +475,6 @@ declare class ReplayApplicator {
 interface CommitOptions {
     cliVersion: string;
     generatorVersions: Record<string, string>;
-    baseBranchHead?: string;
 }
 declare class ReplayCommitter {
     private git;
@@ -596,12 +593,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 {
@@ -621,8 +616,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
@@ -637,8 +632,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;
 }
@@ -758,21 +751,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.