@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/commands/re-export-drift.js

@@ -1,358 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Foreign-drift preview + `--refuse-foreign-drift` gate for `re-export`.
- *
- * A scan-less re-export rebuilds each patch body as a whole-file
- * `git diff HEAD` over the owned files, so a concurrent session's
- * uncommitted lines inside a file the patch already owns are silently
- * absorbed into the refreshed body. The adjacency advisory
- * (`re-export-adjacent.ts`) warns about unmanaged neighbour files but is
- * structurally blind to drift inside owned files. This module compares
- * the old body against the refreshed body per file and reports the
- * payload lines that are about to enter or leave the body. Under
- * `--refuse-foreign-drift` the patch is skipped and the run exits
- * non-zero, mirroring `--refuse-adjacent-unmanaged`.
- *
- * "Foreign" is decided by content, not authorship: re-export's legitimate
- * job is capturing intentional engine edits, so the preview always prints
- * and the hard stop is an explicit opt-in for multi-session checkouts.
- * The comparison is offset-insensitive, using per-file multisets of `+`/`-`
- * payload lines, because a refresh legitimately shifts hunk offsets and
- * context without changing what the patch does.
- */
-import { stat } from 'node:fs/promises';
-import { join } from 'node:path';
-import { parseDiffSections } from '../core/patch-parse.js';
-import { toError } from '../utils/errors.js';
-import { pathExists, readText } from '../utils/fs.js';
-import { info, verbose, warn } from '../utils/logger.js';
-const MAX_HUNK_SUMMARIES_PER_FILE = 3;
-const MAX_FILES_REPORTED = 10;
-function collectPayloadByFile(body) {
-    const byFile = new Map();
-    for (const section of parseDiffSections(body)) {
-        const file = section.targetPath;
-        let payload = byFile.get(file);
-        if (!payload) {
-            payload = {
-                added: new Map(),
-                removed: new Map(),
-                binaryNewHash: undefined,
-                isBinary: false,
-                sections: [],
-            };
-            byFile.set(file, payload);
-        }
-        payload.sections.push(section);
-        if (section.isBinary) {
-            payload.isBinary = true;
-            payload.binaryNewHash = section.indexNewHash;
-            continue;
-        }
-        for (const hunk of section.hunks) {
-            for (const line of hunk.lines) {
-                if (line.startsWith('+')) {
-                    const text = line.slice(1);
-                    payload.added.set(text, (payload.added.get(text) ?? 0) + 1);
-                }
-                else if (line.startsWith('-')) {
-                    const text = line.slice(1);
-                    payload.removed.set(text, (payload.removed.get(text) ?? 0) + 1);
-                }
-            }
-        }
-    }
-    return byFile;
-}
-/** Multiset difference: occurrences of `next` not consumed by `previous`. */
-function multisetExcess(next, previous) {
-    const excess = new Map();
-    for (const [text, count] of next) {
-        const remaining = count - (previous.get(text) ?? 0);
-        if (remaining > 0)
-            excess.set(text, remaining);
-    }
-    return excess;
-}
-/**
- * Summarizes the hunks of `payload` that carry the budgeted `+`/`-` lines.
- * `describe` renders the per-hunk counts, so the old body's dropped lines
- * read in the same engine-edit direction as the new body's absorbed ones.
- */
-function summarizeForeignHunks(payload, foreignAdded, foreignRemoved, describe) {
-    const summaries = [];
-    if (payload === undefined)
-        return summaries;
-    const addedBudget = new Map(foreignAdded);
-    const removedBudget = new Map(foreignRemoved);
-    for (const section of payload.sections) {
-        for (const hunk of section.hunks) {
-            let added = 0;
-            let removed = 0;
-            for (const line of hunk.lines) {
-                if (line.startsWith('+')) {
-                    const text = line.slice(1);
-                    const budget = addedBudget.get(text) ?? 0;
-                    if (budget > 0) {
-                        addedBudget.set(text, budget - 1);
-                        added++;
-                    }
-                }
-                else if (line.startsWith('-')) {
-                    const text = line.slice(1);
-                    const budget = removedBudget.get(text) ?? 0;
-                    if (budget > 0) {
-                        removedBudget.set(text, budget - 1);
-                        removed++;
-                    }
-                }
-            }
-            if (added > 0 || removed > 0) {
-                summaries.push(`@@ -${hunk.oldStart},${hunk.oldCount} +${hunk.newStart},${hunk.newCount} @@ ${describe(added, removed)}`);
-            }
-        }
-    }
-    return summaries;
-}
-function countExcess(excess) {
-    let total = 0;
-    for (const count of excess.values())
-        total += count;
-    return total;
-}
-const EMPTY_PAYLOAD_LINES = new Map();
-/**
- * Pure comparison: per owned file, which `+`/`-` payload lines the
- * refreshed body carries that the old body did not, and which the old body
- * carried that the refreshed one dropped. Both directions are drift: a
- * concurrent session deleting a line the patch added changes the patch as
- * surely as one adding a line, and a belt that only saw absorbed lines let
- * such a deletion through silently. Files not in `previousFilesAffected`
- * are skipped, since those are intentional adoptions (`--scan`) or
- * retirements (`--expect-removed`) rather than drift.
- */
-export function computeForeignDrift(oldBody, newBody, previousFilesAffected) {
-    const owned = new Set(previousFilesAffected);
-    const oldByFile = collectPayloadByFile(oldBody);
-    const newByFile = collectPayloadByFile(newBody);
-    const drift = [];
-    // New-body order first, then files only the old body carried.
-    const files = new Set([...newByFile.keys(), ...oldByFile.keys()]);
-    for (const file of files) {
-        if (!owned.has(file))
-            continue;
-        const next = newByFile.get(file);
-        const previous = oldByFile.get(file);
-        if (next?.isBinary === true || previous?.isBinary === true) {
-            if (binaryContentChanged(next, previous)) {
-                drift.push({
-                    file,
-                    addedLines: 0,
-                    removedLines: 0,
-                    hunkSummaries: [],
-                    binaryChanged: true,
-                });
-            }
-            continue;
-        }
-        const absorbedAdded = multisetExcess(next?.added ?? EMPTY_PAYLOAD_LINES, previous?.added ?? EMPTY_PAYLOAD_LINES);
-        const absorbedRemoved = multisetExcess(next?.removed ?? EMPTY_PAYLOAD_LINES, previous?.removed ?? EMPTY_PAYLOAD_LINES);
-        const droppedAdded = multisetExcess(previous?.added ?? EMPTY_PAYLOAD_LINES, next?.added ?? EMPTY_PAYLOAD_LINES);
-        const droppedRemoved = multisetExcess(previous?.removed ?? EMPTY_PAYLOAD_LINES, next?.removed ?? EMPTY_PAYLOAD_LINES);
-        const addedLines = countExcess(absorbedAdded) + countExcess(droppedRemoved);
-        const removedLines = countExcess(absorbedRemoved) + countExcess(droppedAdded);
-        if (addedLines === 0 && removedLines === 0)
-            continue;
-        drift.push({
-            file,
-            addedLines,
-            removedLines,
-            hunkSummaries: [
-                ...summarizeForeignHunks(next, absorbedAdded, absorbedRemoved, (plus, minus) => `(+${plus}/-${minus})`),
-                // A dropped `+` line is one the engine lost; a dropped `-` line is an
-                // upstream line the engine has back.
-                ...summarizeForeignHunks(previous, droppedAdded, droppedRemoved, (plus, minus) => `in the old body, dropped (+${minus}/-${plus})`),
-            ].slice(0, MAX_HUNK_SUMMARIES_PER_FILE),
-            binaryChanged: false,
-        });
-    }
-    return drift;
-}
-/** True when a binary section appeared, vanished, or its new-side blob hash moved. */
-function binaryContentChanged(next, previous) {
-    if (next?.binaryNewHash === undefined || previous?.binaryNewHash === undefined)
-        return true;
-    return !(next.binaryNewHash.startsWith(previous.binaryNewHash) ||
-        previous.binaryNewHash.startsWith(next.binaryNewHash));
-}
-/**
- * Reads the old body, prints the always-on drift preview (including under
- * dry-run and `--scan`), and, when `ctx.refuseForeignDrift` is set,
- * records a refusal and returns `true` so the caller skips the write.
- */
-export async function reportForeignDrift(args) {
-    const { patch, patchesDir, engineDir, newDiffContent, ctx } = args;
-    for (const file of args.adoptedFiles ?? []) {
-        if (ctx.expectedDriftFiles.has(file))
-            ctx.expectedSeen.add(file);
-    }
-    const oldPath = join(patchesDir, patch.filename);
-    let oldBody;
-    try {
-        if (!(await pathExists(oldPath))) {
-            return refuseUnreadableBaseline(ctx, patch.filename, 'old patch body missing');
-        }
-        oldBody = await readText(oldPath);
-    }
-    catch (error) {
-        return refuseUnreadableBaseline(ctx, patch.filename, `old body unreadable (${toError(error).message})`);
-    }
-    const drift = computeForeignDrift(oldBody, newDiffContent, args.ownedFiles ?? patch.filesAffected);
-    ctx.evaluationRuns += 1;
-    if (drift.length === 0)
-        return false;
-    const unexpected = drift.filter((d) => !ctx.expectedDriftFiles.has(d.file));
-    for (const entry of drift) {
-        if (ctx.expectedDriftFiles.has(entry.file))
-            ctx.expectedSeen.add(entry.file);
-    }
-    const recentlyEdited = await findFilesEditedSinceLastExport(engineDir, oldPath, drift.map((d) => d.file));
-    const totalLines = drift.reduce((sum, d) => sum + d.addedLines + d.removedLines, 0);
-    const lineNoun = totalLines === 1 ? 'line' : 'lines';
-    warn(`${patch.filename}: refreshed body changes ${totalLines} ${lineNoun} against the old patch body (${drift.length} file(s)):`);
-    for (const entry of drift.slice(0, MAX_FILES_REPORTED)) {
-        const expectedTag = ctx.expectedDriftFiles.has(entry.file) ? ' (expected via --expect)' : '';
-        const authorshipTag = recentlyEdited.has(entry.file)
-            ? ' [edited since your last export]'
-            : ' [unchanged since your last export — another session may own it]';
-        if (entry.binaryChanged) {
-            info(`  ${entry.file}: binary content changed${expectedTag}${authorshipTag}`);
-            continue;
-        }
-        info(`  ${entry.file}: +${entry.addedLines} added / -${entry.removedLines} removed line(s)${expectedTag}${authorshipTag}`);
-        for (const summary of entry.hunkSummaries) {
-            info(`    ${summary}`);
-        }
-    }
-    if (drift.length > MAX_FILES_REPORTED) {
-        info(`  +${drift.length - MAX_FILES_REPORTED} more file(s)`);
-    }
-    if (ctx.refuseForeignDrift) {
-        if (unexpected.length === 0) {
-            info(`${patch.filename}: drift confined to --expect file(s); proceeding under --refuse-foreign-drift.`);
-            return false;
-        }
-        ctx.refusals.push({
-            patchFilename: patch.filename,
-            files: unexpected.map((d) => d.file),
-            reason: 'foreign-drift',
-        });
-        warn(`${patch.filename}: skipped (--refuse-foreign-drift).`);
-        return true;
-    }
-    warn('  If these are intentional engine edits, this is the normal re-export flow. ' +
-        "FireForge cannot PROVE authorship; the per-file tags above compare each file's " +
-        'modification time against this patch\'s last export, so "edited since your last ' +
-        'export" marks lines you most likely wrote yourself. If another session owns them, ' +
-        "re-run with --refuse-foreign-drift, or commit/stash that session's edits first.");
-    return false;
-}
-/**
- * Splits the drifting files into "you probably wrote this" and "this predates
- * your last export". `--refuse-foreign-drift` calls every absorbed line
- * "foreign", including the operator's own additions from the same session,
- * and "foreign" reads as "another session's", which is the case where
- * proceeding would be wrong. Authorship is unknowable, but recency is not:
- * a file whose mtime is newer than the patch body this run is refreshing
- * changed after the last export, which on a single-operator slice is the
- * operator's own edit. Returns the subset of `files` that qualifies. An
- * unstattable path is reported as not recently edited, so the cautious
- * wording is the fallback.
- */
-async function findFilesEditedSinceLastExport(engineDir, patchBodyPath, files) {
-    const recent = new Set();
-    let patchMtimeMs;
-    try {
-        patchMtimeMs = (await stat(patchBodyPath)).mtimeMs;
-    }
-    catch (error) {
-        verbose(`Could not stat ${patchBodyPath} for drift recency: ${toError(error).message}`);
-        return recent;
-    }
-    for (const file of files) {
-        try {
-            if ((await stat(join(engineDir, file))).mtimeMs > patchMtimeMs)
-                recent.add(file);
-        }
-        catch (error) {
-            verbose(`Could not stat ${file} for drift recency: ${toError(error).message}`);
-        }
-    }
-    return recent;
-}
-/**
- * Fail-closed baseline handling: a missing or unreadable old
- * patch body means the drift comparison cannot run, so under
- * `--refuse-foreign-drift` the patch is refused rather than written on the
- * strength of a check that never happened. Without the flag this stays the
- * historical advisory skip (the preview is best-effort there).
- */
-function refuseUnreadableBaseline(ctx, patchFilename, detail) {
-    if (!ctx.refuseForeignDrift) {
-        verbose(`Skipping foreign-drift preview for ${patchFilename}: ${detail}`);
-        return false;
-    }
-    ctx.refusals.push({ patchFilename, files: [], reason: 'baseline-unreadable' });
-    warn(`${patchFilename}: skipped (--refuse-foreign-drift) — ${detail}; the drift comparison cannot run, refusing fail-closed.`);
-    return true;
-}
-/**
- * States, verbatim in the notice, what the `--expect` whitelist is compared
- * against and when. This notice is the only feedback an operator gets that
- * the drift belt looked at the files they named, so it has to describe the
- * measurement exactly:
- *
- *  - Compared: for each file already in the patch's `filesAffected`, the
- *    `+`/`-` payload lines the refreshed body carries that the old patch
- *    body did not, and the ones the old body carried that the refreshed body
- *    dropped (`computeForeignDrift`). It is a content comparison in both
- *    directions, so a deletion-only edit is drift too.
- *  - When: per patch, on the body about to be written, before the write.
- *    Never against post-write state.
- *
- * An earlier copy compared one direction only, so a correctly captured
- * deletion read as an `--expect` that matched nothing, and a peer's
- * deletion in a file outside `--expect` passed the belt silently.
- */
-const EXPECT_MEASUREMENT_NOTE = '--expect is evaluated against CONTENT, before the write: for each file already in the ' +
-    "patch's filesAffected, the payload lines the refreshed body adds or drops against the old " +
-    'patch body. It never looks at post-write state.';
-/**
- * Names `--expect` paths that never drifted this run. A typo'd
- * `--expect` path silently degrades the flag back to refusing the slice it
- * was meant to admit, so surface the mismatch, but only as a warning: an
- * expected file legitimately shows no drift in several shapes, all named
- * below.
- */
-export function warnUnseenExpectedDrift(driftCtx) {
-    const unseen = [...driftCtx.expectedDriftFiles].filter((file) => !driftCtx.expectedSeen.has(file));
-    if (unseen.length === 0)
-        return;
-    if (driftCtx.evaluationRuns === 0) {
-        warn(`--expect path(s) were not evaluated because no selected patch reached the drift check (for example, an earlier refusal): ${unseen.join(', ')}`);
-        return;
-    }
-    warn('--expect path(s) showed no drift this run: ' +
-        `${unseen.join(', ')}.\n` +
-        `${EXPECT_MEASUREMENT_NOTE}\n` +
-        'Causes, in rough order of likelihood:\n' +
-        "  1. A typo in the path, or a path in none of the selected patches' filesAffected and " +
-        'not adopted by this run.\n' +
-        '  2. Adoption already captured it: a "re-export <p> --scan --scan-file <f>" run also ' +
-        "captures that patch's other drifted files, so a scan-less re-export afterwards " +
-        'legitimately sees nothing left to change. Informational — a chain that treats this ' +
-        'warning as an error will false-red on it.\n' +
-        '  3. The slice was already captured by an earlier export in this session.\n' +
-        '  4. The engine content already matches the patch body — a concurrent session may have ' +
-        'exported the same change, so the drift converged before this run looked.');
-}

package/dist/src/commands/re-export-each.d.ts

@@ -1,46 +0,0 @@
-/**
- * The per-patch loop of `fireforge re-export`.
- *
- * Without `--refuse-foreign-drift` each selected patch is prepared and
- * committed in turn, so one patch's refusal or failure leaves the others
- * written. Under the flag every selected patch is prepared (scanned,
- * diffed and judged for drift, nothing written) before any is committed,
- * and a drift refusal anywhere writes none: a multi-patch export is the
- * unit the operator reviewed, and half of it written is a queue state
- * nobody asked for.
- */
-import type { PatchMetadata, ReExportOptions } from '../types/commands/index.js';
-import { type SpinnerHandle } from '../utils/logger.js';
-import { type ReExportSinglePatchArgs } from './re-export-single.js';
-/** Inputs of the per-patch loop. */
-export interface ReExportEachArgs {
-    /** The selected patches, in queue order. */
-    selectedPatches: readonly PatchMetadata[];
-    /** The run's options. */
-    options: ReExportOptions;
-    /** Per-patch scan-file assignments, when the run names any. */
-    scanAssignments: ReadonlyMap<string, string[]> | undefined;
-    /** The run's progress line. */
-    progress: SpinnerHandle;
-    /** When the run started, for the elapsed time in the progress line. */
-    startedAt: number;
-    /** The arguments every patch's refresh shares. */
-    shared: Omit<ReExportSinglePatchArgs, 'patch' | 'options'>;
-}
-/** What the loop did with each selected patch. */
-export interface ReExportEachOutcome {
-    /** Patches written (or, in a dry run, that would be). */
-    written: string[];
-    /** Patches whose refresh threw. */
-    failed: string[];
-    /** Patches prepared cleanly but not written because another was refused. */
-    heldBack: string[];
-}
-/**
- * Refreshes the selected patches, collecting which wrote, which failed and
- * which were held back.
- *
- * @param args - See {@link ReExportEachArgs}
- * @returns The outcome per patch
- */
-export declare function reExportEach(args: ReExportEachArgs): Promise<ReExportEachOutcome>;

package/dist/src/commands/re-export-each.js

@@ -1,110 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * The per-patch loop of `fireforge re-export`.
- *
- * Without `--refuse-foreign-drift` each selected patch is prepared and
- * committed in turn, so one patch's refusal or failure leaves the others
- * written. Under the flag every selected patch is prepared (scanned,
- * diffed and judged for drift, nothing written) before any is committed,
- * and a drift refusal anywhere writes none: a multi-patch export is the
- * unit the operator reviewed, and half of it written is a queue state
- * nobody asked for.
- */
-import { elapsedSince } from '../utils/elapsed.js';
-import { toError } from '../utils/errors.js';
-import { warn } from '../utils/logger.js';
-import { scanOptionsForPatch } from './re-export-scan-owner.js';
-import { commitPreparedPatchWithIndexLockRetry, prepareSinglePatchWithIndexLockRetry, reExportSinglePatchWithIndexLockRetry, } from './re-export-single.js';
-function progressLine(verb, args, position, patch) {
-    return (`${verb} ${position}: ${patch.filename} ` +
-        `(${patch.filesAffected.length} file(s), ${elapsedSince(args.startedAt)} elapsed)...`);
-}
-function reportFailure(patch, error, failed) {
-    failed.push(patch.filename);
-    warn(`Failed to re-export ${patch.filename}`);
-    warn(toError(error).message);
-}
-/**
- * Refreshes the selected patches, collecting which wrote, which failed and
- * which were held back.
- *
- * @param args - See {@link ReExportEachArgs}
- * @returns The outcome per patch
- */
-export async function reExportEach(args) {
-    if (args.shared.driftCtx.refuseForeignDrift)
-        return reExportJudgedFirst(args);
-    const { selectedPatches, options, scanAssignments, progress, shared } = args;
-    const written = [];
-    const failed = [];
-    for (const [index, patch] of selectedPatches.entries()) {
-        const patchOptions = scanOptionsForPatch(options, patch.filename, scanAssignments);
-        progress.message(progressLine('Re-exporting', args, `${index + 1}/${selectedPatches.length}`, patch));
-        try {
-            if (await reExportSinglePatchWithIndexLockRetry({ ...shared, patch, options: patchOptions })) {
-                written.push(patch.filename);
-            }
-        }
-        catch (error) {
-            reportFailure(patch, error, failed);
-        }
-    }
-    return { written, failed, heldBack: [] };
-}
-/**
- * The `--refuse-foreign-drift` loop: prepares every patch, then commits
- * them in queue order only when no patch was refused for drift.
- *
- * A patch's prepare reads the manifest's ownership (which files a scan may
- * adopt, which neighbours are unmanaged), and in the per-patch loop an
- * earlier patch's commit has already moved its row by then. The prepares
- * here run against a copy of the manifest that takes each prepared row's
- * `filesAffected` the way that commit would, so every patch is judged
- * against the ownership it would meet in the per-patch loop. A dry run
- * leaves the manifest alone in either loop, so the copy is left alone too.
- */
-async function reExportJudgedFirst(args) {
-    const { selectedPatches, options, scanAssignments, progress, shared } = args;
-    const judged = { ...shared.manifest, patches: [...shared.manifest.patches] };
-    const failed = [];
-    const prepared = [];
-    for (const [index, patch] of selectedPatches.entries()) {
-        const patchArgs = {
-            ...shared,
-            patch,
-            options: scanOptionsForPatch(options, patch.filename, scanAssignments),
-        };
-        progress.message(progressLine('Judging', args, `${index + 1}/${selectedPatches.length}`, patch));
-        try {
-            const ready = await prepareSinglePatchWithIndexLockRetry({ ...patchArgs, manifest: judged });
-            if (ready === undefined)
-                continue;
-            prepared.push({ args: patchArgs, ready });
-            if (!shared.isDryRun) {
-                judged.patches = judged.patches.map((entry) => entry.filename === patch.filename
-                    ? { ...entry, filesAffected: ready.currentFilesAffected }
-                    : entry);
-            }
-        }
-        catch (error) {
-            reportFailure(patch, error, failed);
-        }
-    }
-    if (shared.driftCtx.refusals.length > 0) {
-        return { written: [], failed, heldBack: prepared.map((entry) => entry.args.patch.filename) };
-    }
-    const written = [];
-    for (const [index, entry] of prepared.entries()) {
-        const { patch } = entry.args;
-        progress.message(progressLine('Re-exporting', args, `${index + 1}/${prepared.length}`, patch));
-        try {
-            if (await commitPreparedPatchWithIndexLockRetry(entry.args, entry.ready)) {
-                written.push(patch.filename);
-            }
-        }
-        catch (error) {
-            reportFailure(patch, error, failed);
-        }
-    }
-    return { written, failed, heldBack: [] };
-}

package/dist/src/commands/re-export-files.d.ts

@@ -1,15 +0,0 @@
-import type { PatchMetadata, ReExportOptions } from '../types/commands/index.js';
-import type { FireForgeConfig, ProjectPaths } from '../types/config.js';
-/**
- * Handles `re-export --files` end-to-end: computes the projected diff, runs
- * the per-patch and cross-patch lint against a context in which the target
- * patch has been replaced with the projected state, gates on
- * confirmDestructive, and writes atomically.
- *
- * Lives outside reExportSinglePatch because the --files path has strictly
- * different semantics (authoritative file list, destructive shrink
- * confirmation, cross-patch projection lint). Shoehorning it through the
- * generic single-patch helper is what makes the projection lint run against
- * the current (unchanged) queue instead of the projected state.
- */
-export declare function reExportFilesInPlace(paths: ProjectPaths, selectedPatches: PatchMetadata[], options: ReExportOptions, config: FireForgeConfig): Promise<void>;