@fern-api/replay 0.12.0 → 0.14.0

package/dist/index.d.cts

@@ -69,6 +69,15 @@ interface FileResult {
     conflicts?: ConflictRegion[];
     conflictReason?: ConflictReason;
     conflictMetadata?: ConflictMetadata;
+    /**
+     * Lines that appeared as unchanged context in the customer's THEIRS (also
+     * present in BASE) but were absent from the merged output because OURS
+     * deleted them. diff3 sides with the deletion correctly, but the customer
+     * may not have realized those lines depended on the generator never
+     * removing them. Surfaced as a warning so the customer can re-add them
+     * if needed. Empty/undefined when no such lines exist.
+     */
+    droppedContextLines?: string[];
 }
 interface ConflictRegion {
     startLine: number;
@@ -80,6 +89,14 @@ interface MergeResult {
     content: string;
     hasConflicts: boolean;
     conflicts: ConflictRegion[];
+    /**
+     * Lines present in BOTH base and theirs but absent from the merged output.
+     * These are lines the customer's THEIRS treated as context; OURS deleted
+     * them; diff3 sided with the deletion. Empty when no such lines exist.
+     * Only populated when `hasConflicts` is false — when conflicts surface,
+     * the customer already knows something needs review.
+     */
+    droppedContextLines?: string[];
 }
 interface CommitInfo {
     sha: string;
@@ -210,6 +227,31 @@ declare class ReplayDetector {
     readonly warnings: string[];
     constructor(git: GitClient, lockManager: LockfileManager, sdkOutputDir: string);
     detectNewPatches(): Promise<DetectionResult>;
+    /**
+     * FER-10201 — Non-linear-history detection via `merge-base(prevGen, HEAD)`.
+     *
+     * 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.
+     *
+     * Falls through to the legacy composite path when no common ancestor exists
+     * (truly disjoint history — orphan branches with no shared root).
+     */
+    private detectPatchesViaMergeBase;
+    /**
+     * FER-10201 — Walk `${rangeStart}..HEAD`, classify each commit, emit one
+     * `StoredPatch` per customer commit. Body shared by the linear path
+     * (rangeStart = lastGen.commit_sha) and the merge-base path.
+     *
+     * Patch `base_generation` is always `lastGen.commit_sha` — the
+     * lockfile-tracked reference the applicator uses to fetch base file
+     * content, regardless of where the walk actually started.
+     */
+    private detectPatchesInRange;
     /**
      * Compute content hash for deduplication.
      *
@@ -321,6 +363,19 @@ declare class ReplayApplicator {
     private renameCache;
     private treeExistsCache;
     private fileTheirsAccumulator;
+    /**
+     * Apply mode for the current `applyPatches` invocation. Set at the start
+     * of `applyPatches`, read by `mergeFile` to decide:
+     *   - whether to skip the intra-loop marker strip (kept in `applyPatches`)
+     *   - whether to populate the accumulator after a conflicted merge
+     *     (resolve mode populates so subsequent patches on the same file
+     *     can use patch A's THEIRS as a structurally-correct merge base
+     *     when their diff was authored against post-A structure)
+     *   - whether to retry THEIRS reconstruction against the accumulator
+     *     when the BASE-relative reconstruction produced markers from a
+     *     cross-patch context mismatch
+     */
+    private currentApplyMode;
     constructor(git: GitClient, lockManager: LockfileManager, outputDir: string);
     /**
      * Resolve the GenerationRecord for a patch's base_generation.
@@ -344,9 +399,31 @@ declare class ReplayApplicator {
     /**
      * Apply all patches, returning results for each.
      * Skips patches that match exclude patterns in replay.yml
+     *
+     * `applyMode` controls the post-conflict marker strategy:
+     *   - `"replay"` (default): strip conflict markers from disk between
+     *     iterations whenever a later patch touches the same file. Lets the
+     *     follow-up patch's `git apply --3way` see clean OURS content,
+     *     which is what the silent-loss fix (PR #73) relies on. The replay
+     *     pipeline calls `revertConflictingFiles` after the loop to clean
+     *     any markers that survive.
+     *   - `"resolve"`: keep markers on disk. The resolve command needs the
+     *     customer to see them. Slow-path 3-way merge naturally preserves
+     *     A's markers and B's clean writes when their regions don't overlap;
+     *     when they do overlap, the customer gets nested markers and
+     *     resolves manually. Either way they aren't silently dropped.
+     */
+    applyPatches(patches: StoredPatch[], opts?: {
+        applyMode?: "replay" | "resolve";
+    }): Promise<ReplayResult[]>;
+    /**
+     * Populate accumulator after git apply succeeds, AND collect per-file
+     * results including any "dropped context lines" — lines that were
+     * present in BASE and THEIRS (unchanged context) but absent from the
+     * final on-disk state because OURS deleted them. This is the fast-path
+     * counterpart to ThreeWayMerge.computeDroppedContextLines used by the
+     * 3-way slow path; both must surface the same warning.
      */
-    applyPatches(patches: StoredPatch[]): Promise<ReplayResult[]>;
-    /** Populate accumulator after git apply succeeds. */
     private populateAccumulatorForPatch;
     private applyPatchWithFallback;
     private applyWithThreeWayMerge;
@@ -378,7 +455,13 @@ declare class ReplayCommitter {
     private outputDir;
     constructor(git: GitClient, outputDir: string);
     commitGeneration(message: string, options?: CommitOptions): Promise<string>;
-    commitReplay(_patchCount: number, patches?: StoredPatch[], message?: string): Promise<string>;
+    commitReplay(_patchCount: number, patches?: StoredPatch[], message?: string, options?: {
+        buckets?: {
+            applied: StoredPatch[];
+            unresolved: StoredPatch[];
+            absorbed: StoredPatch[];
+        };
+    }): Promise<string>;
     createGenerationRecord(options?: CommitOptions): Promise<GenerationRecord>;
     stageAll(): Promise<void>;
     hasStagedChanges(): Promise<boolean>;
@@ -643,6 +726,15 @@ declare class ReplayService {
      * Called BEFORE commitGeneration() while HEAD has customer code.
      */
     private preGenerationRebase;
+    /**
+     * After applyPatches(), surface a warning for each (patch × file) where
+     * diff3 silently dropped lines that were unchanged context in the
+     * customer's THEIRS. The deletion stays on disk (correct diff3 outcome),
+     * but the customer must learn so they can re-add the lines if they
+     * relied on them. This is the "surface or preserve, never silently drop"
+     * contract for legitimate-deletion cases.
+     */
+    private recordDroppedContextLineWarnings;
     /**
      * After applyPatches(), strip conflict markers from conflicting files
      * so only clean content is committed. Keeps the Generated (OURS) side.
@@ -814,6 +906,8 @@ interface ResolveResult {
     patchesApplied?: number;
     /** Number of patches resolved and committed (phase 2) */
     patchesResolved?: number;
+    /** Non-fatal diagnostic messages (e.g., per-patch fallbacks) */
+    warnings?: string[];
 }
 declare function resolve(outputDir: string, options?: ResolveOptions): Promise<ResolveResult>;
 

package/dist/index.d.ts

@@ -69,6 +69,15 @@ interface FileResult {
     conflicts?: ConflictRegion[];
     conflictReason?: ConflictReason;
     conflictMetadata?: ConflictMetadata;
+    /**
+     * Lines that appeared as unchanged context in the customer's THEIRS (also
+     * present in BASE) but were absent from the merged output because OURS
+     * deleted them. diff3 sides with the deletion correctly, but the customer
+     * may not have realized those lines depended on the generator never
+     * removing them. Surfaced as a warning so the customer can re-add them
+     * if needed. Empty/undefined when no such lines exist.
+     */
+    droppedContextLines?: string[];
 }
 interface ConflictRegion {
     startLine: number;
@@ -80,6 +89,14 @@ interface MergeResult {
     content: string;
     hasConflicts: boolean;
     conflicts: ConflictRegion[];
+    /**
+     * Lines present in BOTH base and theirs but absent from the merged output.
+     * These are lines the customer's THEIRS treated as context; OURS deleted
+     * them; diff3 sided with the deletion. Empty when no such lines exist.
+     * Only populated when `hasConflicts` is false — when conflicts surface,
+     * the customer already knows something needs review.
+     */
+    droppedContextLines?: string[];
 }
 interface CommitInfo {
     sha: string;
@@ -210,6 +227,31 @@ declare class ReplayDetector {
     readonly warnings: string[];
     constructor(git: GitClient, lockManager: LockfileManager, sdkOutputDir: string);
     detectNewPatches(): Promise<DetectionResult>;
+    /**
+     * FER-10201 — Non-linear-history detection via `merge-base(prevGen, HEAD)`.
+     *
+     * 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.
+     *
+     * Falls through to the legacy composite path when no common ancestor exists
+     * (truly disjoint history — orphan branches with no shared root).
+     */
+    private detectPatchesViaMergeBase;
+    /**
+     * FER-10201 — Walk `${rangeStart}..HEAD`, classify each commit, emit one
+     * `StoredPatch` per customer commit. Body shared by the linear path
+     * (rangeStart = lastGen.commit_sha) and the merge-base path.
+     *
+     * Patch `base_generation` is always `lastGen.commit_sha` — the
+     * lockfile-tracked reference the applicator uses to fetch base file
+     * content, regardless of where the walk actually started.
+     */
+    private detectPatchesInRange;
     /**
      * Compute content hash for deduplication.
      *
@@ -321,6 +363,19 @@ declare class ReplayApplicator {
     private renameCache;
     private treeExistsCache;
     private fileTheirsAccumulator;
+    /**
+     * Apply mode for the current `applyPatches` invocation. Set at the start
+     * of `applyPatches`, read by `mergeFile` to decide:
+     *   - whether to skip the intra-loop marker strip (kept in `applyPatches`)
+     *   - whether to populate the accumulator after a conflicted merge
+     *     (resolve mode populates so subsequent patches on the same file
+     *     can use patch A's THEIRS as a structurally-correct merge base
+     *     when their diff was authored against post-A structure)
+     *   - whether to retry THEIRS reconstruction against the accumulator
+     *     when the BASE-relative reconstruction produced markers from a
+     *     cross-patch context mismatch
+     */
+    private currentApplyMode;
     constructor(git: GitClient, lockManager: LockfileManager, outputDir: string);
     /**
      * Resolve the GenerationRecord for a patch's base_generation.
@@ -344,9 +399,31 @@ declare class ReplayApplicator {
     /**
      * Apply all patches, returning results for each.
      * Skips patches that match exclude patterns in replay.yml
+     *
+     * `applyMode` controls the post-conflict marker strategy:
+     *   - `"replay"` (default): strip conflict markers from disk between
+     *     iterations whenever a later patch touches the same file. Lets the
+     *     follow-up patch's `git apply --3way` see clean OURS content,
+     *     which is what the silent-loss fix (PR #73) relies on. The replay
+     *     pipeline calls `revertConflictingFiles` after the loop to clean
+     *     any markers that survive.
+     *   - `"resolve"`: keep markers on disk. The resolve command needs the
+     *     customer to see them. Slow-path 3-way merge naturally preserves
+     *     A's markers and B's clean writes when their regions don't overlap;
+     *     when they do overlap, the customer gets nested markers and
+     *     resolves manually. Either way they aren't silently dropped.
+     */
+    applyPatches(patches: StoredPatch[], opts?: {
+        applyMode?: "replay" | "resolve";
+    }): Promise<ReplayResult[]>;
+    /**
+     * Populate accumulator after git apply succeeds, AND collect per-file
+     * results including any "dropped context lines" — lines that were
+     * present in BASE and THEIRS (unchanged context) but absent from the
+     * final on-disk state because OURS deleted them. This is the fast-path
+     * counterpart to ThreeWayMerge.computeDroppedContextLines used by the
+     * 3-way slow path; both must surface the same warning.
      */
-    applyPatches(patches: StoredPatch[]): Promise<ReplayResult[]>;
-    /** Populate accumulator after git apply succeeds. */
     private populateAccumulatorForPatch;
     private applyPatchWithFallback;
     private applyWithThreeWayMerge;
@@ -378,7 +455,13 @@ declare class ReplayCommitter {
     private outputDir;
     constructor(git: GitClient, outputDir: string);
     commitGeneration(message: string, options?: CommitOptions): Promise<string>;
-    commitReplay(_patchCount: number, patches?: StoredPatch[], message?: string): Promise<string>;
+    commitReplay(_patchCount: number, patches?: StoredPatch[], message?: string, options?: {
+        buckets?: {
+            applied: StoredPatch[];
+            unresolved: StoredPatch[];
+            absorbed: StoredPatch[];
+        };
+    }): Promise<string>;
     createGenerationRecord(options?: CommitOptions): Promise<GenerationRecord>;
     stageAll(): Promise<void>;
     hasStagedChanges(): Promise<boolean>;
@@ -643,6 +726,15 @@ declare class ReplayService {
      * Called BEFORE commitGeneration() while HEAD has customer code.
      */
     private preGenerationRebase;
+    /**
+     * After applyPatches(), surface a warning for each (patch × file) where
+     * diff3 silently dropped lines that were unchanged context in the
+     * customer's THEIRS. The deletion stays on disk (correct diff3 outcome),
+     * but the customer must learn so they can re-add the lines if they
+     * relied on them. This is the "surface or preserve, never silently drop"
+     * contract for legitimate-deletion cases.
+     */
+    private recordDroppedContextLineWarnings;
     /**
      * After applyPatches(), strip conflict markers from conflicting files
      * so only clean content is committed. Keeps the Generated (OURS) side.
@@ -814,6 +906,8 @@ interface ResolveResult {
     patchesApplied?: number;
     /** Number of patches resolved and committed (phase 2) */
     patchesResolved?: number;
+    /** Non-fatal diagnostic messages (e.g., per-patch fallbacks) */
+    warnings?: string[];
 }
 declare function resolve(outputDir: string, options?: ResolveOptions): Promise<ResolveResult>;