@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/commands/re-export-bulk-scan.js

@@ -1,233 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { readdir, readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { isUnavailableGenerationToken, snapshotEngineGeneration, unavailableGenerationReason, } from '../core/engine-session-lock.js';
-import { createSiblingLockPath, withFileLock } from '../core/file-lock.js';
-import { formatPatchNotFoundError } from '../core/patch-identifier-suggest.js';
-import { resolvePatchIdentifier } from '../core/patch-manifest.js';
-import { GeneralError, InvalidArgumentError } from '../errors/base.js';
-import { mapWithConcurrency } from '../utils/concurrency.js';
-import { getNodeErrorCode, toError } from '../utils/errors.js';
-import { readText } from '../utils/fs.js';
-import { sha256Hex } from '../utils/hash.js';
-import { isObject } from '../utils/validation.js';
-import { describeForeignWriters, fingerprintScopedDryRunState, } from './re-export-purity-scope.js';
-import { normalizeEngineRelativeInput } from './re-export-scan.js';
-/** Concurrency bound for patch-body hashing (matches the classify/lint pools). */
-const PATCH_HASH_CONCURRENCY = 8;
-function parseScanFilesManifest(raw, manifestPath) {
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (error) {
-        throw new InvalidArgumentError(`--scan-files manifest is not valid JSON (${manifestPath}): ${toError(error).message}`, '--scan-files');
-    }
-    if (!isObject(parsed) || !Array.isArray(parsed['assignments'])) {
-        throw new InvalidArgumentError('--scan-files manifest must contain an assignments array.', '--scan-files');
-    }
-    const assignments = [];
-    for (const [index, assignment] of parsed['assignments'].entries()) {
-        if (!isObject(assignment)) {
-            throw new InvalidArgumentError(`--scan-files assignments[${index}] must be an object.`, '--scan-files');
-        }
-        const { patch, files } = assignment;
-        if (typeof patch !== 'string' || patch.trim().length === 0) {
-            throw new InvalidArgumentError(`--scan-files assignments[${index}].patch must be a non-empty string.`, '--scan-files');
-        }
-        if (!Array.isArray(files) ||
-            files.length === 0 ||
-            !files.every((file) => typeof file === 'string')) {
-            throw new InvalidArgumentError(`--scan-files assignments[${index}].files must be a non-empty string array.`, '--scan-files');
-        }
-        assignments.push({ patch, files });
-    }
-    if (assignments.length === 0) {
-        throw new InvalidArgumentError('--scan-files manifest must assign at least one file.', '--scan-files');
-    }
-    return { assignments };
-}
-/** Loads and validates a `re-export --scan-files` assignment manifest. */
-export async function loadScanFilesAssignments(manifestPath, manifest) {
-    const parsed = parseScanFilesManifest(await readText(manifestPath), manifestPath);
-    const filesByPatch = new Map();
-    const ownerByFile = new Map();
-    for (const assignment of parsed.assignments) {
-        const patch = resolvePatchIdentifier(assignment.patch, manifest.patches);
-        if (!patch) {
-            // Suggest close matches instead of dumping the whole queue.
-            throw new InvalidArgumentError(`--scan-files: ${formatPatchNotFoundError(assignment.patch, manifest.patches)}`, '--scan-files');
-        }
-        const patchFiles = filesByPatch.get(patch.filename) ?? new Set();
-        filesByPatch.set(patch.filename, patchFiles);
-        for (const rawFile of assignment.files) {
-            const file = normalizeEngineRelativeInput(rawFile, '--scan-files');
-            const previousOwner = ownerByFile.get(file);
-            if (previousOwner !== undefined && previousOwner !== patch.filename) {
-                throw new InvalidArgumentError(`--scan-files path is assigned to more than one patch: ${file} (${previousOwner}, ${patch.filename})`, '--scan-files');
-            }
-            ownerByFile.set(file, patch.filename);
-            patchFiles.add(file);
-        }
-    }
-    return new Map([...filesByPatch.entries()].map(([patchFilename, files]) => [patchFilename, [...files].sort()]));
-}
-/**
- * Fingerprints every piece of state a `re-export --dry-run` promises not to
- * disturb: the engine's commit + working-tree status (via the same
- * generation token `fireforge test` uses) and the byte content of every
- * regular file under `patches/`. That covers all of them, not just the
- * selected patches, because a dry-run of patch B can revert a just-written
- * export of patch A.
- *
- * A missing patches directory (ENOENT/ENOTDIR) fingerprints as empty, since
- * there is nothing there to protect. Any other listing failure (EACCES, EIO,
- * …) throws: an unreadable directory is not evidence it is empty, and
- * treating it as such lets the guard silently vouch for state it never saw.
- * The same rule covers an unmeasurable engine generation and an unreadable
- * individual patch file. A before-pass failure aborts the dry run before it
- * starts, since a guard that measured nothing cannot vouch for anything.
- */
-async function fingerprintDryRunState(engineDir, patchesDir) {
-    const fingerprint = new Map();
-    const generation = await snapshotEngineGeneration(engineDir);
-    if (isUnavailableGenerationToken(generation)) {
-        // A failed probe measured nothing. Hashing the failure token would let
-        // two identical failures compare "unchanged" (vouching for unmeasured
-        // state) and two differing messages report a spurious violation.
-        throw new GeneralError(`[dry-run] cannot fingerprint the engine working tree for the purity guard: ` +
-            unavailableGenerationReason(generation));
-    }
-    fingerprint.set('the engine working tree', sha256Hex(generation));
-    let names = [];
-    try {
-        const entries = await readdir(patchesDir, { withFileTypes: true });
-        names = entries
-            .filter((entry) => entry.isFile())
-            .map((entry) => entry.name)
-            .sort();
-    }
-    catch (error) {
-        // No patches directory, so nothing there to protect. The same condition
-        // on the post-run pass produces the same empty set, and a directory that
-        // appears mid-dry-run correctly reports as a violation. Any other failure
-        // must not read as "empty": the guard would be vouching for state it
-        // never saw.
-        const code = getNodeErrorCode(error);
-        if (code !== 'ENOENT' && code !== 'ENOTDIR') {
-            throw new GeneralError(`[dry-run] cannot fingerprint ${patchesDir} for the purity guard: ${toError(error).message}`, error);
-        }
-    }
-    const results = await mapWithConcurrency(names, PATCH_HASH_CONCURRENCY, async (name) => {
-        try {
-            return {
-                hash: sha256Hex(await readFile(join(patchesDir, name))),
-            };
-        }
-        catch (error) {
-            // A file that vanished between the listing and the read is omitted, so
-            // a dry run that deleted a patch artifact reports as the violation it
-            // is (key present before, absent after) instead of hiding behind a
-            // fingerprinting error. Every other failure fails closed: a constant
-            // placeholder would make unreadable-before equal unreadable-after even
-            // when the bytes changed underneath.
-            const code = getNodeErrorCode(error);
-            if (code === 'ENOENT' || code === 'ENOTDIR')
-                return { vanished: true };
-            return { error };
-        }
-    });
-    for (const [index, name] of names.entries()) {
-        const result = results[index];
-        if (result === undefined)
-            continue;
-        if ('error' in result) {
-            throw new GeneralError(`[dry-run] cannot fingerprint ${join(patchesDir, name)} for the purity guard: ${toError(result.error).message}`, result.error);
-        }
-        if ('vanished' in result)
-            continue;
-        fingerprint.set(`patches/${name}`, result.hash);
-    }
-    return fingerprint;
-}
-/**
- * Runtime enforcement of the dry-run purity contract: fingerprints the engine
- * tree and every patch artifact before and after `operation`, and throws when
- * a dry-run changed anything it promised only to inspect. That turns a
- * "dry-run reverted a just-written export" incident into a hard, named
- * failure instead of silent data loss discovered only when a later gate
- * fails. The post-fingerprint runs whether `operation` resolves or rejects,
- * because a dry-run that mutates state and then fails is exactly the case
- * where a rollback defect must not go unreported. A rejection with a purity
- * violation surfaces the violation with the original error as `cause`.
- * No-op outside dry-run.
- */
-export async function withDryRunPurityGuard(engineDir, patchesDir, isDryRun, operation, scope) {
-    if (!isDryRun)
-        return operation();
-    const fingerprint = () => scope === undefined
-        ? fingerprintDryRunState(engineDir, patchesDir)
-        : fingerprintScopedDryRunState(engineDir, patchesDir, scope);
-    const startedAt = Date.now();
-    const before = await fingerprint();
-    let result;
-    let operationError;
-    let failed = false;
-    try {
-        result = await operation();
-    }
-    catch (error) {
-        failed = true;
-        operationError = error;
-    }
-    let after;
-    try {
-        after = await fingerprint();
-    }
-    catch (fingerprintError) {
-        // The post-run fingerprint failing must not swallow the dry run's own
-        // failure: an operation that mutated state, broke it, and made it
-        // unreadable is exactly the case where both facts matter. The combined
-        // message carries both. The operation error stays the `cause`.
-        if (failed) {
-            throw new GeneralError(`[dry-run] this dry run failed (${toError(operationError).message}), and its purity could ` +
-                `not be verified afterwards: ${toError(fingerprintError).message}. Inspect engine/ and ` +
-                'your patches/ diff before trusting them.', operationError);
-        }
-        throw fingerprintError;
-    }
-    const touched = [...new Set([...before.keys(), ...after.keys()])]
-        .sort()
-        .filter((key) => before.get(key) !== after.get(key));
-    if (touched.length > 0) {
-        const also = failed ? ` The dry run also failed: ${toError(operationError).message}` : '';
-        const writers = await describeForeignWriters(patchesDir, startedAt);
-        if (writers.length > 0) {
-            throw new GeneralError(`[dry-run] ${touched.join(', ')} changed during this dry run, written by another ` +
-                `writer: ${writers.join('; ')}. The preview raced that write; rerun it once the ` +
-                `writer is done.${also}`, operationError);
-        }
-        throw new GeneralError(`[dry-run] invariant violated: ${touched.join(', ')} changed during this dry run. No ` +
-            'other FireForge command recorded a write in that window, so either another writer ' +
-            '(an editor, an agent or a git command in engine/) changed it, or this is a FireForge ' +
-            'bug. Rerun the dry run; if it repeats on a quiet tree, please report it, and inspect ' +
-            'the listed state (e.g. `git status` in engine/ and your patches/ diff) before ' +
-            'trusting it.' +
-            also, operationError);
-    }
-    if (failed)
-        throw operationError;
-    return result;
-}
-/** Serializes dry-run re-export git inspection against the same project tree. */
-export async function withDryRunReExportLock(fireforgeDir, isDryRun, operation) {
-    if (!isDryRun)
-        return operation();
-    const lockPath = createSiblingLockPath(join(fireforgeDir, 're-export-dry-run'), '.lock');
-    return withFileLock(lockPath, operation, {
-        timeoutMs: 24 * 60 * 60 * 1000,
-        onTimeoutMessage: `Timed out waiting for the FireForge re-export dry-run lock at ${lockPath}. ` +
-            'If no other `fireforge re-export --dry-run` is running, remove the lock directory and retry.',
-        onStaleLockMessage: (ageMs) => `Removing stale FireForge re-export dry-run lock (age: ${Math.round(ageMs / 1000)}s). A previous dry-run process may have crashed.`,
-    });
-}

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

@@ -1,110 +0,0 @@
-/**
- * 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 type { PatchMetadata } from '../types/commands/index.js';
-/** Why a patch was refused under `--refuse-foreign-drift`. */
-export type ForeignDriftRefusalReason = 'foreign-drift' | 'baseline-unreadable';
-/** Per-run context threaded through the re-export loop (mirrors). */
-export interface ForeignDriftContext {
-    refuseForeignDrift: boolean;
-    /**
-     * Engine-relative files whose drift is expected (`--expect`):
-     * drift confined to these files does not refuse. Files here that never
-     * drift are reported after the run as likely typos.
-     */
-    expectedDriftFiles: ReadonlySet<string>;
-    /** Expected files that actually drifted at least once this run. */
-    expectedSeen: Set<string>;
-    /** Number of patches whose old/new bodies reached the drift comparison. */
-    evaluationRuns: number;
-    refusals: {
-        patchFilename: string;
-        files: string[];
-        reason: ForeignDriftRefusalReason;
-    }[];
-}
-/**
- * One owned file's foreign drift between the old and refreshed body,
- * counted as edits to the engine file rather than as body payload, so a
- * deletion-only change is drift like any other.
- */
-export interface FileForeignDrift {
-    file: string;
-    /**
-     * Lines the engine file gained since the old body: `+` payload the new
-     * body carries that the old did not, plus `-` payload the old body carried
-     * that the new one dropped (an upstream line restored).
-     */
-    addedLines: number;
-    /**
-     * Lines the engine file lost since the old body: `-` payload the new body
-     * carries that the old did not, plus `+` payload the old body carried that
-     * the new one dropped (a line the patch added, now deleted).
-     */
-    removedLines: number;
-    /** `@@` headers of the hunks carrying those lines (capped). */
-    hunkSummaries: string[];
-    /** True when a binary section's recorded new-side blob hash changed. */
-    binaryChanged: boolean;
-}
-/**
- * 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 declare function computeForeignDrift(oldBody: string, newBody: string, previousFilesAffected: readonly string[]): FileForeignDrift[];
-/**
- * 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 declare function reportForeignDrift(args: {
-    patch: PatchMetadata;
-    patchesDir: string;
-    engineDir: string;
-    newDiffContent: string;
-    ctx: ForeignDriftContext;
-    /**
-     * The patch's files that the comparison covers. Defaults to its
-     * `filesAffected`; the caller narrows it by the `--expect-removed`
-     * retirements, which leave the body on purpose.
-     */
-    ownedFiles?: readonly string[];
-    /**
-     * Files a `--scan`/`--scan-file` adoption brings in this run. They sit
-     * outside the comparison (nothing to compare against) and count as
-     * expected, so naming one in `--expect` is not reported as unseen.
-     */
-    adoptedFiles?: readonly string[];
-}): Promise<boolean>;
-/**
- * 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 declare function warnUnseenExpectedDrift(driftCtx: ForeignDriftContext): void;