@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/core/negative-control-diff.js

@@ -1,204 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Parsing and strict application of a `fireforge test --negative-control`
- * diff.
- *
- * A control is a reviewed mutation, so the applier is deliberately strict:
- * every context and removed line must match exactly, the only tolerance is
- * a line offset (the same one `git apply` allows, never fuzz), and a hunk
- * that does not apply refuses the whole control before any file is
- * written. Only plain text modifications of existing files are accepted: a
- * created, deleted, renamed or binary file has no byte-exact restore story
- * that is worth its risk for a neuter.
- */
-import { GeneralError } from '../errors/base.js';
-import { isContainedRelativePath, normalizePathSlashes } from '../utils/paths.js';
-import { parseDiffSections } from './patch-parse.js';
-function refuse(message) {
-    throw new GeneralError(`Negative control diff refused: ${message}`);
-}
-/** A `---`/`+++` file name, without a trailing timestamp or git's `a/`/`b/`. */
-function plainDiffPath(raw) {
-    const name = raw.split('\t')[0]?.trim() ?? '';
-    return name.startsWith('a/') || name.startsWith('b/') ? name.slice(2) : name;
-}
-/**
- * Gives a plain unified diff (`diff -u`, no `diff --git` lines) the git
- * header the section parser keys on, one per `---`/`+++` pair. A diff that
- * already carries `diff --git` headers is returned unchanged.
- *
- * @param content - The diff file's text
- */
-function withGitHeaders(content) {
-    const lines = content.split('\n');
-    if (lines.some((line) => line.startsWith('diff --git ')))
-        return content;
-    const out = [];
-    for (let index = 0; index < lines.length; index += 1) {
-        const line = lines[index] ?? '';
-        const next = lines[index + 1] ?? '';
-        if (line.startsWith('--- ') && next.startsWith('+++ ')) {
-            const oldPath = plainDiffPath(line.slice(4));
-            const newPath = plainDiffPath(next.slice(4));
-            index += 1;
-            if (oldPath === '/dev/null' || newPath === '/dev/null') {
-                // Kept as a create/delete, which the parser below refuses by name.
-                const path = oldPath === '/dev/null' ? newPath : oldPath;
-                out.push(`diff --git a/${path} b/${path}`, oldPath === '/dev/null' ? 'new file mode 100644' : 'deleted file mode 100644', oldPath === '/dev/null' ? '--- /dev/null' : `--- a/${path}`, newPath === '/dev/null' ? '+++ /dev/null' : `+++ b/${path}`);
-                continue;
-            }
-            out.push(`diff --git a/${oldPath} b/${newPath}`, `--- a/${oldPath}`, `+++ b/${newPath}`);
-            continue;
-        }
-        out.push(line);
-    }
-    return out.join('\n');
-}
-/**
- * Parses a control diff. Accepts `git diff` output (a `diff --git` header
- * per file), which is what `git -C engine diff -- <file>` or a project-root
- * `git diff` writes, a plain unified diff (`diff -u`), and, through
- * `resolveRename`, a `git diff --no-index` against an edited copy.
- *
- * @param content - The diff file's text
- * @param options - See {@link ParseControlDiffOptions}
- * @returns One entry per file, in diff order
- */
-export function parseControlDiff(content, options = {}) {
-    const sections = parseDiffSections(withGitHeaders(content));
-    if (sections.length === 0) {
-        refuse('no diff sections found. Write the control with git, e.g. ' +
-            '`git -C engine diff -- <file> > control.diff` after making the edit, then revert the edit.');
-    }
-    const files = new Map();
-    for (const section of sections) {
-        let path = normalizePathSlashes(section.targetPath);
-        if (section.isBinary)
-            refuse(`${path} is a binary section.`);
-        if (section.isNewFile || section.isDeletedFile) {
-            refuse(`${path} creates or deletes a file; a control may only modify existing text files.`);
-        }
-        if (section.sourcePath !== section.targetPath) {
-            const resolved = options.resolveRename?.(section.sourcePath, section.targetPath);
-            if (resolved === undefined) {
-                refuse(`${section.sourcePath} -> ${path} is a rename; a control may only modify files.`);
-            }
-            path = normalizePathSlashes(resolved);
-        }
-        if (!isContainedRelativePath(path)) {
-            refuse(`${path} is not a contained relative path.`);
-        }
-        if (section.hunks.length === 0)
-            refuse(`${path} has no hunks.`);
-        const existing = files.get(path);
-        if (existing === undefined) {
-            files.set(path, { path, hunks: [...section.hunks], sections: 1 });
-        }
-        else {
-            existing.hunks.push(...section.hunks);
-            existing.sections += 1;
-        }
-    }
-    return [...files.values()].map(({ path, hunks, sections: count }) => ({
-        path,
-        hunks: count === 1 ? hunks : mergeSectionHunks(path, hunks),
-    }));
-}
-/**
- * Orders the hunks of a file that several sections name (a generator that
- * writes one section per edit) as one section's would be. Hunks that
- * overlap cannot be applied one after another, so they are refused.
- */
-function mergeSectionHunks(path, hunks) {
-    const ordered = [...hunks].sort((left, right) => left.oldStart - right.oldStart);
-    ordered.forEach((hunk, index) => {
-        const previous = ordered[index - 1];
-        if (previous !== undefined && previous.oldStart + previous.oldCount > hunk.oldStart) {
-            refuse(`${path} appears in more than one section, and hunks from them overlap ` +
-                `(@@ -${previous.oldStart},${previous.oldCount} @@ and @@ -${hunk.oldStart},${hunk.oldCount} @@). ` +
-                'Make every edit to the file, then write one section for it with `git -C engine diff -- <file>`.');
-        }
-    });
-    return ordered;
-}
-function hunkSides(hunk, label, index) {
-    const oldLines = [];
-    const newLines = [];
-    for (const line of hunk.lines) {
-        const body = line.slice(1);
-        if (line.startsWith(' ') || line.startsWith('-'))
-            oldLines.push(body);
-        if (line.startsWith(' ') || line.startsWith('+'))
-            newLines.push(body);
-    }
-    if (oldLines.length !== hunk.oldCount || newLines.length !== hunk.newCount) {
-        refuse(`hunk ${index + 1} of ${label} is malformed: its header counts ` +
-            `(-${hunk.oldCount} +${hunk.newCount}) do not match its body ` +
-            `(-${oldLines.length} +${newLines.length}).`);
-    }
-    return { oldLines, newLines };
-}
-function matchesAt(lines, block, position) {
-    if (position < 0 || position + block.length > lines.length)
-        return false;
-    return block.every((line, offset) => lines[position + offset] === line);
-}
-/**
- * The position nearest `anchor`, at or after `floor`, where `block`
- * matches, or -1.
- */
-function findBlock(lines, block, anchor, floor) {
-    const start = Math.max(anchor, floor);
-    for (let delta = 0; delta <= lines.length; delta += 1) {
-        if (matchesAt(lines, block, start + delta))
-            return start + delta;
-        const below = anchor - delta;
-        if (delta > 0 && below >= floor && matchesAt(lines, block, below))
-            return below;
-    }
-    return -1;
-}
-/**
- * Applies `hunks` to `original`, strictly.
- *
- * @param original - The file's current text
- * @param hunks - Hunks parsed from the control diff
- * @param label - File label for refusal messages
- * @returns The mutated text
- * @throws GeneralError when any hunk does not apply
- */
-export function applyControlHunks(original, hunks, label) {
-    const hasFinalNewline = original.endsWith('\n');
-    const lines = original === '' ? [] : (hasFinalNewline ? original.slice(0, -1) : original).split('\n');
-    const result = [];
-    let cursor = 0;
-    let finalNewline = hasFinalNewline;
-    hunks.forEach((hunk, index) => {
-        const { oldLines, newLines } = hunkSides(hunk, label, index);
-        const anchor = hunk.oldCount === 0 ? hunk.oldStart : hunk.oldStart - 1;
-        const position = oldLines.length === 0
-            ? anchor >= cursor && anchor <= lines.length
-                ? anchor
-                : -1
-            : findBlock(lines, oldLines, anchor, cursor);
-        const reachesEnd = position + oldLines.length === lines.length;
-        const endMatches = position >= 0 &&
-            (reachesEnd && oldLines.length > 0
-                ? hunk.noNewlineAtEndOld === !hasFinalNewline
-                : !hunk.noNewlineAtEndOld);
-        if (position < 0 || !endMatches) {
-            const alreadyApplied = newLines.length > 0 && findBlock(lines, newLines, Math.max(0, hunk.newStart - 1), 0) >= 0;
-            refuse(`hunk ${index + 1} of ${label} (@@ -${hunk.oldStart},${hunk.oldCount} ` +
-                `+${hunk.newStart},${hunk.newCount} @@) does not apply to the current file.` +
-                (alreadyApplied
-                    ? ' Its new side is already present: the mutation looks applied already (an earlier control that was not restored?).'
-                    : ' The file changed since the diff was written; regenerate the control against it.'));
-        }
-        result.push(...lines.slice(cursor, position), ...newLines);
-        cursor = position + oldLines.length;
-        if (reachesEnd)
-            finalNewline = !hunk.noNewlineAtEndNew;
-    });
-    result.push(...lines.slice(cursor));
-    return result.join('\n') + (finalNewline && result.length > 0 ? '\n' : '');
-}

package/dist/src/core/negative-control.d.ts

@@ -1,150 +0,0 @@
-/**
- * `fireforge test --negative-control <diff>`: apply a reviewed mutation to
- * engine sources for exactly one harness dispatch, then put every byte back.
- *
- * Safety model (also stated in docs/testing.md):
- *
- *  - The control is applied and restored only while the caller holds the
- *    engine-session lock, after the pre-test build has packaged and before
- *    the harness spawns, so no peer build or test can observe it and a
- *    Furnace deploy cannot overwrite it.
- *  - Before the first mutated byte is written, the original bytes of every
- *    target go to `.fireforge/negative-control/` together with a journal
- *    recording each file's original and mutated SHA-256, mode and
- *    timestamps. A killed FireForge therefore leaves enough on disk to undo
- *    the control, and the next `fireforge test` does so before anything else.
- *  - Restore writes the original bytes back atomically, re-applies the
- *    original mode and timestamps, and reads the file back to prove the
- *    bytes match. It only overwrites a file that still holds exactly the
- *    bytes the control wrote: anything else means someone edited the file
- *    while the control ran, and that edit is kept, never clobbered, with the
- *    original left in the journal directory and the conflict reported.
- *  - A SIGINT or SIGTERM restores through {@link restoreActiveNegativeControlsForSignal},
- *    which the entry point runs after the harness has shut down and before
- *    it releases the held locks.
- */
-import type { ParsedHunk } from './patch-parse.js';
-/** One file a control mutates. */
-export interface NegativeControlTarget {
-    /** The path as the diff names it. */
-    diffPath: string;
-    /** The engine-relative file the control mutates. */
-    enginePath: string;
-    /** Hunks to apply to the engine file. */
-    hunks: ParsedHunk[];
-    /** True when the diff named a `components/` source mapped to its deployed copy. */
-    fromComponents: boolean;
-}
-/** A parsed, resolved control, ready to apply. */
-export interface NegativeControlPlan {
-    /** The diff file, as the operator passed it. */
-    diffFile: string;
-    targets: NegativeControlTarget[];
-    /**
-     * Engine-relative targets only a build delivers (compiled sources). A
-     * control with any must be applied before the pre-test build, and is
-     * restored with a fresh mtime. See `negative-control-compiled.ts`.
-     */
-    compiled?: string[];
-}
-/** Locations a control works against. */
-export interface NegativeControlPaths {
-    engineDir: string;
-    /** The project's `.fireforge/` directory. */
-    fireforgeDir: string;
-}
-interface JournalEntry {
-    enginePath: string;
-    backup: string;
-    originalSha256: string;
-    mutatedSha256: string;
-    mode: number;
-    atimeMs: number;
-    mtimeMs: number;
-    /**
-     * Restore with the current time as mtime, not the original: a compiled
-     * source restored with its old mtime is skipped by the incremental build,
-     * which would leave the mutated code in the binary.
-     */
-    freshMtime?: boolean;
-}
-interface Journal {
-    version: 1;
-    diffFile: string;
-    appliedAt: string;
-    entries: JournalEntry[];
-}
-/** A control currently applied to the engine. */
-export interface ActiveNegativeControl {
-    paths: NegativeControlPaths;
-    journal: Journal;
-    /**
-     * The one restore in flight, set synchronously by whichever path (the
-     * run's own `finally`, or the signal handler) gets there first, so the
-     * other awaits the same restore instead of racing or skipping it.
-     */
-    restoring?: Promise<NegativeControlRestoreResult>;
-}
-/**
- * Reads, parses and resolves a control diff, and (unless `deferApplyCheck`)
- * proves every hunk applies to the current engine file, so a broken control
- * is refused before any build time is spent.
- *
- * `deferApplyCheck` is for a run that builds first: Furnace redeploys a
- * component's engine copy during the build, so a `components/` control can
- * only be checked against what the build left behind.
- *
- * @param projectRoot - Project root; the diff path resolves against it
- * @param engineDir - Absolute engine directory
- * @param diffFile - The `--negative-control` argument
- * @param options - `deferApplyCheck` skips the up-front apply check for
- *   `components/` targets
- */
-export declare function planNegativeControl(projectRoot: string, engineDir: string, diffFile: string, options?: {
-    deferApplyCheck?: boolean;
-}): Promise<NegativeControlPlan>;
-/**
- * Applies the control: every target is computed first (a hunk that does
- * not apply refuses with nothing written), the originals and the journal
- * are persisted, then the mutated bytes are written. Runs as a signal
- * critical section, so a Ctrl+C mid-apply waits for the apply to finish
- * and the signal path then restores a complete journal.
- *
- * @returns The handle {@link restoreNegativeControl} takes
- */
-export declare function applyNegativeControl(paths: NegativeControlPaths, plan: NegativeControlPlan): Promise<ActiveNegativeControl>;
-/** What happened to each file of a restored control. */
-export interface NegativeControlRestoreResult {
-    /** Engine-relative files put back to their original bytes. */
-    restored: string[];
-    /** Engine-relative files that held neither the control's bytes nor the original. */
-    conflicts: string[];
-}
-/**
- * Restores a control applied by {@link applyNegativeControl}. Idempotent:
- * a second caller (the signal handler racing the run's own `finally`)
- * receives the restore already in flight.
- *
- * @throws GeneralError when a file changed under the control (the edit is
- *   kept and the original stays in the journal directory) or did not read
- *   back byte-exact
- */
-export declare function restoreNegativeControl(control: ActiveNegativeControl): Promise<NegativeControlRestoreResult>;
-/**
- * Restores every applied control on the way out of a SIGINT/SIGTERM. Called
- * by the entry point after child shutdown and before the held locks are
- * force-released. Never throws: a failure is reported on stderr and the
- * journal stays for the next run's recovery.
- */
-export declare function restoreActiveNegativeControlsForSignal(): Promise<void>;
-/**
- * Undoes a control a killed FireForge left applied. Called at the start of
- * every `fireforge test`, under the engine-session lock. A file that still
- * holds the control's bytes is restored; a file somebody changed since is
- * refused rather than overwritten.
- *
- * @throws PreflightRefusalError (`note=negative-control-pending`) when a
- *   journal entry cannot be restored safely
- */
-export declare function recoverPendingNegativeControl(paths: NegativeControlPaths): Promise<void>;
-export {};