@fern-api/replay 0.10.4 → 0.12.0

package/dist/index.d.ts

@@ -28,6 +28,15 @@ interface StoredPatch {
      *  When "resolving", the resolve command has applied patches to the working tree
      *  and is waiting for the customer to resolve conflicts and run resolve again. */
     status?: "unresolved" | "resolving";
+    /**
+     * True when the patch introduces files that the generator has never produced
+     * (new-file creations). User-owned patches are immune to absorption checks in
+     * `rebasePatches`, `trimAbsorbedFiles`, and `preGenerationRebase`. Set at
+     * detection time by observing `--- /dev/null` headers in patch_content, or at
+     * rebase time by the reachability-aware helper. Once true, never cleared —
+     * the generator will not start producing a file it never produced before.
+     */
+    user_owned?: boolean;
 }
 interface CustomizationsConfig {
     exclude?: string[];
@@ -83,6 +92,29 @@ interface ReplayConfig {
     enabled: boolean;
 }
 
+/**
+ * Credential detection patterns for the replay pipeline.
+ *
+ * Two-layer defense against credential leaks in .fern/replay.lock:
+ *   Layer 1 — file-level: SENSITIVE_FILE_PATTERNS blocks entire files (.env, .pem, etc.)
+ *   Layer 2 — content-level: CREDENTIAL_PATTERNS catches inline secrets in any file
+ *
+ * These patterns mirror the invariant assertions in __tests__/invariants/i4-credential-containment.ts.
+ * If they diverge, the invariant tests independently catch real leaks.
+ *
+ * @security FER-9807
+ */
+interface CredentialPattern {
+    name: string;
+    re: RegExp;
+}
+declare const CREDENTIAL_PATTERNS: ReadonlyArray<CredentialPattern>;
+declare const SENSITIVE_FILE_PATTERNS: ReadonlyArray<RegExp>;
+/** Check if a file path matches any sensitive file pattern. */
+declare function isSensitiveFile(filePath: string): boolean;
+/** Scan content for credential patterns. Returns matched pattern names. */
+declare function scanForCredentials(content: string): string[];
+
 declare class GitClient {
     private git;
     private repoPath;
@@ -95,6 +127,16 @@ declare class GitClient {
     showFile(treeish: string, filePath: string): Promise<string | null>;
     getCommitInfo(commitSha: string): Promise<CommitInfo>;
     getCommitParents(commitSha: string): Promise<string[]>;
+    /**
+     * Detects renames and copies between two trees.
+     *
+     * Both `R` (rename) and `C` (copy) entries are returned as `{from, to}` pairs.
+     * Copies are treated as rename-equivalent because the generator may produce the
+     * new path while the old path remains in the tree (e.g., imperfect cleanup,
+     * customer edits at the old path, or test helpers that only write new files).
+     * Callers that care about "is the source still present" should verify via
+     * `showFile(toTree, from)`.
+     */
     detectRenames(fromTree: string, toTree: string): Promise<Array<{
         from: string;
         to: string;
@@ -124,6 +166,7 @@ declare class LockfileNotFoundError extends Error {
 declare class LockfileManager {
     private outputDir;
     private lock;
+    readonly warnings: string[];
     constructor(outputDir: string);
     get lockfilePath(): string;
     get customizationsPath(): string;
@@ -139,7 +182,7 @@ declare class LockfileManager {
     save(): void;
     addGeneration(record: GenerationRecord): void;
     addPatch(patch: StoredPatch): void;
-    updatePatch(patchId: string, updates: Partial<Pick<StoredPatch, "base_generation" | "patch_content" | "content_hash" | "files" | "status">>): void;
+    updatePatch(patchId: string, updates: Partial<Pick<StoredPatch, "base_generation" | "patch_content" | "content_hash" | "files" | "status" | "user_owned">>): void;
     removePatch(patchId: string): void;
     clearPatches(): void;
     addForgottenHash(hash: string): void;
@@ -169,10 +212,60 @@ declare class ReplayDetector {
     detectNewPatches(): Promise<DetectionResult>;
     /**
      * Compute content hash for deduplication.
-     * Removes commit SHA line and index lines before hashing,
-     * so rebased commits with same content produce the same hash.
+     *
+     * Produces a format-agnostic hash so both `git format-patch` output
+     * (email-wrapped) and plain `git diff` output hash to the same value
+     * when the underlying diff hunks are identical.
+     *
+     * Normalization:
+     *   1. Strip email wrapper: everything before the first `diff --git` line
+     *      (From:, Subject:, Date:, diffstat, blank separators).
+     *   2. Strip `index` lines (blob SHA pairs change across rebases).
+     *   3. Strip trailing git version marker (`-- \n<version>`).
+     *
+     * This ensures content hashes match across the no-patches and normal-
+     * regeneration flows, which store formatPatch and git-diff formats
+     * respectively (FER-9850, D5-D9).
      */
     computeContentHash(patchContent: string): string;
+    /**
+     * FER-9805 — Drop patches whose files were transiently created and then
+     * deleted 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
+     * 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.
+     *
+     * A file is "transient" when:
+     *   1. some patch in the window sets `new file mode` for it (a creation), AND
+     *   2. some patch in the window sets `deleted file mode` for it (a deletion), AND
+     *   3. it is absent from HEAD's tree.
+     *
+     * The HEAD guard (#3) prevents false positives when a file is deleted
+     * and then recreated with different content — the cumulative diff of
+     * such a pair is non-empty and must be preserved.
+     *
+     * This only drops patches whose `files` are a subset of the transient
+     * set. A partial-transient patch (one that touches a transient file
+     * alongside a persistent one) is left unmodified; surgical stripping of
+     * single files from a multi-file patch would require a follow-up that
+     * regenerates the patch content via `git format-patch -- <files>`. No
+     * current failing test exercises this, and leaving the patch intact
+     * preserves today's behaviour. TODO(FER-9805): revisit if a future
+     * adversarial test demands per-file stripping.
+     */
+    private collapseNetZeroFiles;
+    /**
+     * List every tracked path at HEAD (one `git ls-tree -r` invocation).
+     * Returns an empty Set if HEAD is unborn or the invocation fails — the
+     * caller then treats every candidate as "not in HEAD" and may collapse
+     * 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
@@ -237,6 +330,17 @@ declare class ReplayApplicator {
     private resolveBaseGeneration;
     /** Reset inter-patch accumulator for a new cycle. */
     private resetAccumulator;
+    /**
+     * @internal Test-only.
+     * Returns a defensive copy of the inter-patch accumulator. Used by the
+     * adversarial test suite (FER-9791) to assert invariant I2: after every
+     * applied patch, the accumulator has an entry for each file the patch
+     * touched, and the entry's content matches on-disk.
+     */
+    getAccumulatorSnapshot(): ReadonlyMap<string, {
+        content: string;
+        baseGeneration: string;
+    }>;
     /**
      * Apply all patches, returning results for each.
      * Skips patches that match exclude patterns in replay.yml
@@ -251,6 +355,14 @@ declare class ReplayApplicator {
     private isExcluded;
     private resolveFilePath;
     private applyPatchToContent;
+    /**
+     * Detects whether a patch's additions are already present in `content`.
+     * Uses `git apply --reverse --check` — if the reverse patch applies cleanly,
+     * the forward patch is effectively a no-op (its +lines are already there and
+     * its -lines are already gone). Used to distinguish "patch already applied"
+     * from "patch base mismatch" after a forward-apply fails.
+     */
+    private isPatchAlreadyApplied;
     private extractFileDiff;
     private extractRenameSource;
     private extractNewFileFromPatch;
@@ -322,6 +434,72 @@ interface ReplayOptions {
     /** 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
+ * and re-supplying them here is meaningless.
+ */
+interface ApplyOptions {
+    /** Write files and stage changes, but don't commit */
+    stageOnly?: boolean;
+}
+/**
+ * Opaque handle returned by `prepareReplay()`. Consumed by `applyPreparedReplay()`
+ * to complete the run.
+ *
+ * Contract for consumers (e.g., generator-cli pipeline inserting AutoVersionStep):
+ *
+ * - Between `prepareReplay` and `applyPreparedReplay`, HEAD is at the new
+ *   `[fern-generated]` commit (unless `_prepared.terminal === true`, e.g. dry-run).
+ * - Consumers MAY land additional commits on HEAD between phases. `applyPatches`
+ *   runs against current HEAD at phase-2 call time, so mid-phase commits are
+ *   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.
+ * - 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
+ *   advances, or (b) reset HEAD to `previousGenerationSha` and surface the failure.
+ *
+ * To decide whether to run autoversion between phases, use:
+ *     prep.previousGenerationSha != null && prep.flow !== "skip-application"
+ */
+interface ReplayPreparation {
+    flow: "first-generation" | "no-patches" | "normal-regeneration" | "skip-application";
+    /** lockfile.current_generation from BEFORE this run; null iff no prior generation exists */
+    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;
+}
+/** @internal */
+interface InternalPreparationState {
+    flow: "first-generation" | "no-patches" | "normal-regeneration" | "skip-application";
+    /** true → applyPreparedReplay returns preparedReport without disk/git work (dry-run path) */
+    terminal: boolean;
+    preparedReport?: ReplayReport;
+    /** post-preGenRebase, post-detection, post-absorption (references, not copies) */
+    patchesToApply: StoredPatch[];
+    /** subset of patchesToApply that were freshly detected this cycle (vs already in the lockfile) */
+    newPatchIds: Set<string>;
+    preRebaseCounts?: {
+        conflictResolved: number;
+        conflictAbsorbed: number;
+        contentRefreshed: number;
+    };
+    /** detector warnings snapshotted at end of phase 1 */
+    detectorWarnings: string[];
+    revertedCount: number;
+    /** [fern-generated] SHA; passed to rebasePatches as currentGenSha */
+    genSha: string;
+    /** cached phase-1 options for constructing the final ReplayReport in phase 2 */
+    optionsSnapshot?: ReplayOptions;
+}
 declare class ReplayService {
     private git;
     private detector;
@@ -329,7 +507,57 @@ declare class ReplayService {
     private committer;
     private lockManager;
     private outputDir;
+    /** @internal Test-only. Captures the last ReplayResult[] returned from applicator.applyPatches(). */
+    private _lastApplyResults;
+    /**
+     * Service-level warnings accumulated during a single runReplay() call.
+     * Merged with `detector.warnings` into `ReplayReport.warnings` by each flow handler.
+     * Populated by `isFileUserOwned` when a patch's base generation tree is unreachable
+     * (shallow clone / aggressive `git gc --prune`) and we fall back to a conservative
+     * heuristic. Cleared at the top of `runReplay()`.
+     */
+    private warnings;
+    /**
+     * @internal Test-only accessor.
+     * Returns the ReplayApplicator instance used for the last run. Tests use this
+     * to inspect the inter-patch accumulator after runReplay() completes (FER-9791, I2).
+     */
+    get applicatorRef(): ReplayApplicator;
+    /**
+     * @internal Test-only accessor.
+     * Returns the ReplayResult[] from the most recent applyPatches() call. Tests use
+     * this to filter applied-vs-conflicted-vs-absorbed patches for invariant assertions
+     * (FER-9791). Returns an empty array if no patches have been applied yet.
+     */
+    getLastResults(): ReadonlyArray<ReplayResult>;
     constructor(outputDir: string, _config: ReplayConfig);
+    /**
+     * Phase 1 of the two-phase replay flow. Runs preGenerationRebase (when applicable),
+     * detects new patches, and creates the `[fern-generated]` commit. Leaves HEAD at
+     * the generation commit (or unchanged for dry-run).
+     *
+     * Does NOT apply patches — the returned handle must be passed to
+     * `applyPreparedReplay()` to complete the run. No disk writes to the lockfile
+     * happen here; lockfile persistence is deferred to phase 2.
+     *
+     * Callers may land additional commits on HEAD between `prepareReplay` and
+     * `applyPreparedReplay` (e.g., `[fern-autoversion]`).
+     */
+    prepareReplay(options?: ReplayOptions): Promise<ReplayPreparation>;
+    /**
+     * Phase 2 of the two-phase replay flow. Applies patches, rebases them against
+     * the generation, saves the lockfile, and commits `[fern-replay]` (or stages
+     * under `stageOnly`). Operates on HEAD at call time — mid-phase commits are
+     * respected.
+     *
+     * For terminal handles (dry-run, first-gen has no patch work, skip-app does
+     * its own post-commit logic), this returns the precomputed report.
+     */
+    applyPreparedReplay(prep: ReplayPreparation, options?: ApplyOptions): Promise<ReplayReport>;
+    /**
+     * Backwards-compatible atomic entry point. Composes `prepareReplay` + `applyPreparedReplay`.
+     * 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.
@@ -347,21 +575,59 @@ declare class ReplayService {
         baseBranchHead?: string;
     }): Promise<void>;
     private determineFlow;
-    private handleFirstGeneration;
+    private firstGenerationReport;
+    private _prepareFirstGeneration;
+    private _applyFirstGeneration;
     /**
-     * Skip-application mode: commit the generation and update the lockfile
-     * but don't detect or apply patches. Sets a marker so the next normal
-     * run skips revert detection in preGenerationRebase().
+     * Skip-application mode phase 1: commit the generation and update the
+     * in-memory lockfile, but don't detect or apply patches. Sets a marker
+     * so the next normal run skips revert detection in preGenerationRebase().
+     *
+     * Disk save is deferred to `_applySkipApplication`.
      */
-    private handleSkipApplication;
-    private handleNoPatchesRegeneration;
-    private handleNormalRegeneration;
+    private _prepareSkipApplication;
+    private _applySkipApplication;
+    private _prepareNoPatchesRegeneration;
+    private _applyNoPatchesRegeneration;
+    private _prepareNormalRegeneration;
+    private _applyNormalRegeneration;
     /**
      * Rebase cleanly applied patches so they are relative to the current generation.
      * This prevents recurring conflicts on subsequent regenerations.
      * Returns the number of patches rebased.
      */
     private rebasePatches;
+    /**
+     * Determine whether `file` is user-owned (never produced by the generator).
+     *
+     * Resolution order (first match wins):
+     *  1. `patch.user_owned === true` — authoritative, persisted across cycles.
+     *  2. `.fernignore` itself, or file matches a .fernignore pattern.
+     *  3. Legacy-safe signal: `patch_content` shows this file as a `--- /dev/null`
+     *     creation. Works for patches that predate the `user_owned` field or
+     *     whose flag was lost. Immune to rename tricks — relies on raw patch text.
+     *  4. Tree-based check against `patch.base_generation` when it is reachable
+     *     AND distinct from `currentGenSha`. If the base tree is unreachable
+     *     (shallow clone / aggressive `git gc --prune`), emit a one-time
+     *     customer-actionable warning (deduplicated via warnedGens) and
+     *     conservatively treat as user-owned — strictly safer than silent
+     *     absorption (FER-9809).
+     *  5. Final fallback — check `currentGenSha` when there is no usable base
+     *     (legacy one-gen lockfile). Preserves pre-fix behavior for that edge.
+     *
+     * `originalFileName` is the pre-rename path when the generator moved the
+     * file between the patch's base and the current generation. Tree lookups
+     * at ancestor generations use the original path — that's where the
+     * generator produced the content.
+     */
+    private isFileUserOwned;
+    /**
+     * Returns true if `file`'s diff section in `patchContent` starts with
+     * `--- /dev/null`, meaning this file was introduced by the patch (user
+     * creation). Used as a legacy-safe fallback when `patch.user_owned` is
+     * absent or cleared.
+     */
+    private fileIsCreationInPatchContent;
     /**
      * For conflict patches with mixed results (some files merged, some conflicted),
      * check if the cleanly merged files were absorbed by the generator (empty diff).
@@ -595,4 +861,4 @@ interface StatusGeneration {
 }
 declare function status(outputDir: string): StatusResult;
 
-export { type BootstrapOptions, type BootstrapResult, type CommitInfo, type CommitOptions, type ConflictDetail, type ConflictMetadata, type ConflictReason, type ConflictRegion, type CustomizationsConfig, type DetectionResult, type DiffStat, FERN_BOT_EMAIL, FERN_BOT_LOGIN, FERN_BOT_NAME, FernignoreMigrator, type FileResult, type ForgetOptions, type ForgetResult, type GenerationLock, type GenerationRecord, GitClient, LockfileManager, LockfileNotFoundError, type MatchedPatch, type MergeResult, type MigrationAnalysis, type MigrationResult, type MoveDeclaration, ReplayApplicator, ReplayCommitter, type ReplayConfig, ReplayDetector, type ReplayOptions, type ReplayReport, type ReplayResult, ReplayService, type ResetOptions, type ResetResult, type ResolveOptions, type ResolveResult, type StatusGeneration, type StatusPatch, type StatusResult, type StoredPatch, type UnresolvedPatchInfo, bootstrap, forget, isGenerationCommit, isReplayCommit, isRevertCommit, parseRevertedMessage, parseRevertedSha, reset, resolve, status, threeWayMerge };
+export { type ApplyOptions, type BootstrapOptions, type BootstrapResult, CREDENTIAL_PATTERNS, type CommitInfo, type CommitOptions, type ConflictDetail, type ConflictMetadata, type ConflictReason, type ConflictRegion, type CredentialPattern, type CustomizationsConfig, type DetectionResult, type DiffStat, FERN_BOT_EMAIL, FERN_BOT_LOGIN, FERN_BOT_NAME, FernignoreMigrator, type FileResult, type ForgetOptions, type ForgetResult, type GenerationLock, type GenerationRecord, GitClient, LockfileManager, LockfileNotFoundError, type MatchedPatch, type MergeResult, type MigrationAnalysis, type MigrationResult, type MoveDeclaration, ReplayApplicator, ReplayCommitter, type ReplayConfig, ReplayDetector, type ReplayOptions, type ReplayPreparation, type ReplayReport, type ReplayResult, ReplayService, type ResetOptions, type ResetResult, type ResolveOptions, type ResolveResult, SENSITIVE_FILE_PATTERNS, type StatusGeneration, type StatusPatch, type StatusResult, type StoredPatch, type UnresolvedPatchInfo, bootstrap, forget, isGenerationCommit, isReplayCommit, isRevertCommit, isSensitiveFile, parseRevertedMessage, parseRevertedSha, reset, resolve, scanForCredentials, status, threeWayMerge };