@fern-api/replay 0.6.0 → 0.6.2

package/dist/index.d.cts

@@ -0,0 +1,463 @@
+interface GenerationLock {
+    version: "1.0";
+    generations: GenerationRecord[];
+    current_generation: string;
+    patches: StoredPatch[];
+    replay_skipped_at?: string;
+}
+interface GenerationRecord {
+    commit_sha: string;
+    tree_hash: string;
+    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;
+    content_hash: string;
+    original_commit: string;
+    original_message: string;
+    original_author: string;
+    base_generation: string;
+    files: string[];
+    patch_content: string;
+}
+interface CustomizationsConfig {
+    exclude?: string[];
+    moves?: MoveDeclaration[];
+}
+interface MoveDeclaration {
+    from: string;
+    to: string;
+}
+type ConflictReason = "same-line-edit" | "new-file-both" | "base-generation-mismatch" | "patch-apply-failed";
+interface ReplayResult {
+    patch: StoredPatch;
+    status: "applied" | "conflict" | "skipped";
+    method: "git-am" | "3way-merge";
+    fileResults?: FileResult[];
+    conflictReason?: ConflictReason;
+    /** Maps original file path → resolved path for files that were renamed between generations. */
+    resolvedFiles?: Record<string, string>;
+}
+interface ConflictMetadata {
+    patchId: string;
+    patchMessage: string;
+    baseGeneration: string;
+    currentGeneration: string;
+}
+interface FileResult {
+    file: string;
+    status: "merged" | "conflict" | "skipped";
+    reason?: string;
+    conflicts?: ConflictRegion[];
+    conflictReason?: ConflictReason;
+    conflictMetadata?: ConflictMetadata;
+}
+interface ConflictRegion {
+    startLine: number;
+    endLine: number;
+    ours: string[];
+    theirs: string[];
+}
+interface MergeResult {
+    content: string;
+    hasConflicts: boolean;
+    conflicts: ConflictRegion[];
+}
+interface CommitInfo {
+    sha: string;
+    authorName: string;
+    authorEmail: string;
+    authorLogin?: string;
+    message: string;
+}
+interface ReplayConfig {
+    enabled: boolean;
+}
+
+declare class GitClient {
+    private git;
+    private repoPath;
+    constructor(repoPath: string);
+    exec(args: string[]): Promise<string>;
+    execWithInput(args: string[], input: string): Promise<string>;
+    formatPatch(commitSha: string): Promise<string>;
+    applyPatch(patchContent: string): Promise<void>;
+    getTreeHash(commitSha: string): Promise<string>;
+    showFile(treeish: string, filePath: string): Promise<string | null>;
+    getCommitInfo(commitSha: string): Promise<CommitInfo>;
+    getCommitParents(commitSha: string): Promise<string[]>;
+    detectRenames(fromTree: string, toTree: string): Promise<Array<{
+        from: string;
+        to: string;
+    }>>;
+    isAncestor(commit: string, descendant: string): Promise<boolean>;
+    commitExists(sha: string): Promise<boolean>;
+    getRepoPath(): string;
+}
+
+declare const FERN_BOT_NAME = "fern-api";
+declare const FERN_BOT_EMAIL = "115122769+fern-api[bot]@users.noreply.github.com";
+declare const FERN_BOT_LOGIN = "fern-api[bot]";
+declare function isGenerationCommit(commit: CommitInfo): boolean;
+declare function isReplayCommit(commit: CommitInfo): boolean;
+
+declare class LockfileManager {
+    private outputDir;
+    private lock;
+    constructor(outputDir: string);
+    get lockfilePath(): string;
+    get customizationsPath(): string;
+    exists(): boolean;
+    read(): GenerationLock;
+    initialize(firstGeneration: GenerationRecord): void;
+    /**
+     * Set up in-memory lock state without writing to disk.
+     * Useful for bootstrap dry-run where we need state for detection
+     * but don't want to persist anything.
+     */
+    initializeInMemory(firstGeneration: GenerationRecord): void;
+    save(): void;
+    addGeneration(record: GenerationRecord): void;
+    addPatch(patch: StoredPatch): void;
+    updatePatch(patchId: string, updates: Partial<Pick<StoredPatch, "base_generation" | "patch_content" | "content_hash" | "files">>): void;
+    removePatch(patchId: string): void;
+    clearPatches(): void;
+    getPatches(): StoredPatch[];
+    setReplaySkippedAt(timestamp: string): void;
+    clearReplaySkippedAt(): void;
+    isReplaySkipped(): boolean;
+    getGeneration(commitSha: string): GenerationRecord | undefined;
+    getCustomizationsConfig(): CustomizationsConfig;
+    private ensureLoaded;
+}
+
+declare class ReplayDetector {
+    private git;
+    private lockManager;
+    private sdkOutputDir;
+    readonly warnings: string[];
+    constructor(git: GitClient, lockManager: LockfileManager, sdkOutputDir: string);
+    detectNewPatches(): Promise<StoredPatch[]>;
+    /**
+     * Compute content hash for deduplication.
+     * Removes commit SHA line and index lines before hashing,
+     * so rebased commits with same content produce the same hash.
+     */
+    computeContentHash(patchContent: string): string;
+    /** Detect patches via tree diff for non-linear history. Returns a composite patch. */
+    private detectPatchesViaTreeDiff;
+    private parseGitLog;
+    private getLastGeneration;
+}
+
+/**
+ * Performs a 3-way merge using the diff3 algorithm.
+ *
+ * @param base - The common ancestor (pristine generated state user edited against)
+ * @param ours - The new generated version
+ * @param theirs - The user's customized version
+ * @returns MergeResult with content, conflict flag, and conflict regions
+ */
+declare function threeWayMerge(base: string, ours: string, theirs: string): MergeResult;
+
+declare class ReplayApplicator {
+    private git;
+    private lockManager;
+    private outputDir;
+    private renameCache;
+    private fileTheirsAccumulator;
+    constructor(git: GitClient, lockManager: LockfileManager, outputDir: string);
+    /** Reset inter-patch accumulator for a new cycle. */
+    private resetAccumulator;
+    /**
+     * Apply all patches, returning results for each.
+     * Skips patches that match exclude patterns in replay.yml
+     */
+    applyPatches(patches: StoredPatch[]): Promise<ReplayResult[]>;
+    /** Populate accumulator after git apply succeeds. */
+    private populateAccumulatorForPatch;
+    private applyPatchWithFallback;
+    private applyWithThreeWayMerge;
+    private mergeFile;
+    private isExcluded;
+    private resolveFilePath;
+    private applyPatchToContent;
+    private extractFileDiff;
+    private extractRenameSource;
+    private extractNewFileFromPatch;
+}
+
+interface CommitOptions {
+    cliVersion: string;
+    generatorVersions: Record<string, string>;
+    baseBranchHead?: string;
+}
+declare class ReplayCommitter {
+    private git;
+    private outputDir;
+    constructor(git: GitClient, outputDir: string);
+    commitGeneration(message: string, options?: CommitOptions): Promise<string>;
+    commitReplay(_patchCount: number, patches?: StoredPatch[]): Promise<string>;
+    createGenerationRecord(options?: CommitOptions): Promise<GenerationRecord>;
+    stageAll(): Promise<void>;
+    hasStagedChanges(): Promise<boolean>;
+    getTreeHash(commitSha: string): Promise<string>;
+}
+
+interface ConflictDetail {
+    patchId: string;
+    patchMessage: string;
+    reason?: string;
+    files: FileResult[];
+    /** Files that applied cleanly in a patch that also had conflicts. */
+    cleanFiles?: string[];
+}
+interface ReplayReport {
+    flow: "first-generation" | "no-patches" | "normal-regeneration" | "skip-application";
+    patchesDetected: number;
+    patchesApplied: number;
+    patchesWithConflicts: number;
+    patchesSkipped: number;
+    patchesAbsorbed?: number;
+    patchesRepointed?: number;
+    patchesContentRebased?: number;
+    patchesKeptAsUserOwned?: number;
+    patchesPartiallyApplied?: number;
+    patchesConflictResolved?: number;
+    patchesRefreshed?: number;
+    conflicts: FileResult[];
+    conflictDetails?: ConflictDetail[];
+    wouldApply?: StoredPatch[];
+    warnings?: string[];
+}
+interface ReplayOptions {
+    /** Log what would happen but don't modify anything */
+    dryRun?: boolean;
+    /** Write files and stage changes, but don't commit */
+    stageOnly?: boolean;
+    /** CLI version for commit metadata */
+    cliVersion?: string;
+    /** Generator versions for commit metadata */
+    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;
+}
+declare class ReplayService {
+    private git;
+    private detector;
+    private applicator;
+    private committer;
+    private lockManager;
+    private outputDir;
+    constructor(outputDir: string, _config: ReplayConfig);
+    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;
+    private handleFirstGeneration;
+    /**
+     * 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().
+     */
+    private handleSkipApplication;
+    private handleNoPatchesRegeneration;
+    private handleNormalRegeneration;
+    /**
+     * 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;
+    /**
+     * For conflict patches with mixed results (some files merged, some conflicted),
+     * check if the cleanly merged files were absorbed by the generator (empty diff).
+     * If so, remove them from patch.files so they don't pollute the pre-generation
+     * rebase conflict marker check (`git grep <<<<<<< -- ...patch.files`).
+     *
+     * Non-absorbed clean files stay in patch.files — removing them would lose
+     * the customization on the next generation.
+     */
+    private trimAbsorbedFiles;
+    /**
+     * Pre-generation rebase: update patches using the customer's current state.
+     * Called BEFORE commitGeneration() while HEAD has customer code.
+     */
+    private preGenerationRebase;
+    private readFernignorePatterns;
+    private buildReport;
+}
+
+interface MigrationAnalysis {
+    /** Files in .fernignore that have git commit history (can be tracked by Replay) */
+    trackedByBoth: Array<{
+        file: string;
+        commit: string;
+    }>;
+    /** Files in .fernignore but NO recent commit history found after last generation */
+    fernignoreOnly: string[];
+    /** Commits found that AREN'T in .fernignore (inline edits to generated files) */
+    commitsOnly: StoredPatch[];
+    /** Synthetic patches created for .fernignore files that differ from pristine generation */
+    syntheticPatches: StoredPatch[];
+}
+interface MigrationResult {
+    patchesCreated: number;
+    filesSkipped: string[];
+    warnings: string[];
+}
+declare class FernignoreMigrator {
+    private git;
+    private lockManager;
+    private outputDir;
+    constructor(git: GitClient, lockManager: LockfileManager, outputDir: string);
+    fernignoreExists(): boolean;
+    readFernignorePatterns(): string[];
+    /** Analyze .fernignore patterns vs git history. Creates synthetic patches for files differing from pristine generation. */
+    analyzeMigration(): Promise<MigrationAnalysis>;
+    private resolvePatterns;
+    private readFileContent;
+    private createNewFileDiff;
+    private createFileDiff;
+    migrate(): Promise<MigrationResult>;
+    movePatternsToReplayYml(patterns: string[]): void;
+}
+
+interface BootstrapOptions {
+    /** Log what would happen but don't modify anything */
+    dryRun?: boolean;
+    /** How to handle .fernignore: "migrate" moves patterns to replay.yml, "delete" removes it, "skip" leaves it */
+    fernignoreAction?: "migrate" | "delete" | "skip";
+    /** Maximum number of commits to scan for generation history (default: 500) */
+    maxCommitsToScan?: number;
+    /** Allow overwriting an existing lockfile */
+    force?: boolean;
+    /** When true, scan git history for existing patches. Default: false (clean start with 0 patches). */
+    importHistory?: boolean;
+}
+interface BootstrapResult {
+    /** The generation commit used as baseline, or null if none found */
+    generationCommit: CommitInfo | null;
+    /** Number of customization patches detected */
+    patchesDetected: number;
+    /** Number of patches written to lockfile */
+    patchesCreated: number;
+    /** The detected patches (for dry-run inspection) */
+    patches: StoredPatch[];
+    /** .fernignore patterns found, if any */
+    fernignorePatterns: string[];
+    /** .fernignore migration analysis, if .fernignore exists */
+    fernignoreAnalysis?: MigrationAnalysis;
+    /** Whether .fernignore was updated to protect replay files */
+    fernignoreUpdated: boolean;
+    /** Warnings about edge cases */
+    warnings: string[];
+    /** Number of older generation commits that were skipped (stale commits ignored) */
+    staleGenerationsSkipped: number;
+    /** The generation commit SHA used as cutoff for patch detection */
+    scannedSinceGeneration: string;
+}
+/**
+ * Bootstrap Replay for an existing SDK repository.
+ *
+ * Scans git history to find all generation commits, identifies
+ * user customization patches between them, and creates the initial replay.lock.
+ *
+ * This is a one-time migration step for SDKs that existed before Replay.
+ */
+declare function bootstrap(outputDir: string, options?: BootstrapOptions): Promise<BootstrapResult>;
+
+interface ForgetOptions {
+    /** Don't actually remove, just show what would be removed */
+    dryRun?: boolean;
+}
+interface ForgetResult {
+    /** Patches that were (or would be) removed */
+    removed: Array<{
+        id: string;
+        message: string;
+        files: string[];
+    }>;
+    /** True if no patches matched the pattern */
+    notFound: boolean;
+}
+declare function forget(outputDir: string, filePattern: string, options?: ForgetOptions): ForgetResult;
+
+interface ResetOptions {
+    /** Don't actually delete, just show what would happen */
+    dryRun?: boolean;
+}
+interface ResetResult {
+    /** Whether reset was successful (or would be) */
+    success: boolean;
+    /** Number of patches that were (or would be) removed */
+    patchesRemoved: number;
+    /** Whether the lockfile was (or would be) deleted */
+    lockfileDeleted: boolean;
+    /** True if there was nothing to reset */
+    nothingToReset: boolean;
+}
+declare function reset(outputDir: string, options?: ResetOptions): ResetResult;
+
+interface ResolveOptions {
+    /** Check for remaining conflict markers before committing. Default: true */
+    checkMarkers?: boolean;
+}
+interface ResolveResult {
+    /** Whether the resolve succeeded */
+    success: boolean;
+    /** Commit SHA of the [fern-replay] commit, if created */
+    commitSha?: string;
+    /** Reason for failure */
+    reason?: string;
+    /** Files that still have conflict markers */
+    unresolvedFiles?: string[];
+}
+declare function resolve(outputDir: string, options?: ResolveOptions): Promise<ResolveResult>;
+
+interface StatusResult {
+    /** Whether replay is initialized (lockfile exists) */
+    initialized: boolean;
+    /** Tracked customization patches */
+    patches: StatusPatch[];
+    /** Last generation info, if available */
+    lastGeneration: StatusGeneration | undefined;
+}
+interface StatusPatch {
+    /** Short SHA of the original commit */
+    sha: string;
+    /** Author name (without email) */
+    author: string;
+    /** Original commit message */
+    message: string;
+    /** Files touched by this patch */
+    files: string[];
+}
+interface StatusGeneration {
+    /** Full commit SHA */
+    sha: string;
+    /** Generation timestamp */
+    timestamp: string;
+}
+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, FERN_BOT_EMAIL, FERN_BOT_LOGIN, FERN_BOT_NAME, FernignoreMigrator, type FileResult, type ForgetOptions, type ForgetResult, type GenerationLock, type GenerationRecord, GitClient, LockfileManager, 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, bootstrap, forget, isGenerationCommit, isReplayCommit, reset, resolve, status, threeWayMerge };