@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/core/coverage-records.js

@@ -1,383 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Per-path packaging-coverage anchors for scoped `fireforge test --build`.
- *
- * Each staged request path carries its own anchor restricted to its own
- * staging inputs, and a claim is dropped only when one of those inputs
- * changed. One claim anchored to the whole engine would be replaced by any
- * edit outside the new scope (a peer's, on a shared engine, nearly always).
- *
- * The staging inputs of a request path are its manifest directory (the
- * nearest directory at or above it that holds a test manifest) plus every
- * path a manifest there names outside that directory (`support-files`,
- * `head`, `!/`-rooted shared fixtures). Without the full mozbuild graph
- * that is the closest sound boundary: an edit outside it cannot change
- * what the harness stages for that path.
- */
-import { readdir, readFile, stat } from 'node:fs/promises';
-import { join, posix } from 'node:path';
-import { getNodeErrorCode, toError } from '../utils/errors.js';
-import { sha256Hex } from '../utils/hash.js';
-import { verbose } from '../utils/logger.js';
-import { normalizePathSlashes } from '../utils/paths.js';
-import { DELETED_FILE_FINGERPRINT, } from './build-baseline-types.js';
-import { getHead, isMissingHeadError } from './git.js';
-import { git } from './git-base.js';
-import { getUntrackedFiles } from './git-status.js';
-/**
- * Basenames of the test manifests whose entries decide what a packaged test
- * runtime stages.
- */
-const TEST_MANIFEST_BASENAMES = new Set([
-    'xpcshell.toml',
-    'xpcshell.ini',
-    'browser.toml',
-    'browser.ini',
-    'mochitest.toml',
-    'mochitest.ini',
-    'chrome.toml',
-    'chrome.ini',
-    'a11y.toml',
-    'a11y.ini',
-]);
-/** Directory entries a directory request's manifest walk visits at most. */
-const MAX_WALK_ENTRIES = 5000;
-/**
- * Hex-encoded SHA-256 of an engine-relative file, matching the digest the
- * baseline writer produces. A missing file hashes to
- * {@link DELETED_FILE_FINGERPRINT}. `undefined` on any other IO error,
- * which every caller treats as "cannot prove unchanged".
- * @param engineDir - Path to the engine directory
- * @param relPath - Engine-relative POSIX path
- */
-export async function hashEngineFile(engineDir, relPath) {
-    try {
-        return sha256Hex(await readFile(join(engineDir, relPath)));
-    }
-    catch (error) {
-        if (getNodeErrorCode(error) === 'ENOENT')
-            return DELETED_FILE_FINGERPRINT;
-        verbose(`Coverage anchor: could not hash ${relPath} — ${toError(error).message}`);
-        return undefined;
-    }
-}
-/** True for a test manifest path (by basename). */
-export function isTestManifestPath(path) {
-    return TEST_MANIFEST_BASENAMES.has(posix.basename(path));
-}
-/** Normalizes a request path: forward slashes, no `./`, no trailing slash. */
-export function normalizeRequestPath(path) {
-    const normalized = posix.normalize(normalizePathSlashes(path.trim())).replace(/\/+$/, '');
-    return normalized === '.' ? '' : normalized;
-}
-/** True when `file` is `prefix` or sits beneath it. The empty prefix is the whole tree. */
-export function isUnderPath(file, prefix) {
-    return prefix === '' || file === prefix || file.startsWith(`${prefix}/`);
-}
-/**
- * Reads HEAD and the dirty set. Throws on a git failure other than an
- * unborn HEAD: callers treat that as "nothing can be proven unchanged".
- * @param engineDir - Path to the engine directory
- */
-export async function readEngineContentState(engineDir) {
-    let head;
-    try {
-        head = await getHead(engineDir);
-    }
-    catch (error) {
-        if (!isMissingHeadError(error))
-            throw error;
-    }
-    const dirty = new Set();
-    if (head !== undefined) {
-        for (const line of (await git(['diff', '--name-only', 'HEAD'], engineDir)).split('\n')) {
-            if (line.trim())
-                dirty.add(line.trim());
-        }
-    }
-    for (const file of await getUntrackedFiles(engineDir))
-        dirty.add(file);
-    return { engineDir, head, dirty, hashes: new Map(), diffs: new Map() };
-}
-function liveHash(state, path) {
-    let pending = state.hashes.get(path);
-    if (pending === undefined) {
-        pending = hashEngineFile(state.engineDir, path);
-        state.hashes.set(path, pending);
-    }
-    return pending;
-}
-/** Paths committed between `from` and HEAD, or undefined when `from` cannot be diffed. */
-function committedSince(state, from) {
-    let pending = state.diffs.get(from);
-    if (pending === undefined) {
-        pending = git(['diff', '--name-only', `${from}..HEAD`], state.engineDir).then((output) => new Set(output
-            .split('\n')
-            .map((line) => line.trim())
-            .filter(Boolean)), (error) => {
-            verbose(`Coverage anchor: cannot diff ${from}..HEAD — ${toError(error).message}`);
-            return undefined;
-        });
-        state.diffs.set(from, pending);
-    }
-    return pending;
-}
-/**
- * Paths whose content may differ from the anchor, restricted to `inputs`
- * (undefined: the whole tree) and excluding `rebuilt` paths. Undefined when
- * the anchor cannot be compared at all (no usable HEAD on either side).
- */
-async function candidatePaths(state, anchor, inputs, rebuilt) {
-    if (state.head === undefined || anchor.engineHeadSha === '')
-        return undefined;
-    const inScope = (file) => (inputs === undefined || inputs.some((input) => isUnderPath(file, input))) &&
-        !rebuilt.some((path) => isUnderPath(file, path));
-    const candidates = new Set();
-    if (state.head !== anchor.engineHeadSha) {
-        const committed = await committedSince(state, anchor.engineHeadSha);
-        if (committed === undefined)
-            return undefined;
-        for (const file of committed)
-            if (inScope(file))
-                candidates.add(file);
-    }
-    for (const file of state.dirty)
-        if (inScope(file))
-            candidates.add(file);
-    for (const file of Object.keys(anchor.fingerprints))
-        if (inScope(file))
-            candidates.add(file);
-    return candidates;
-}
-/**
- * Inputs whose live content differs from what the anchor staged, sorted.
- * Undefined when the anchor cannot be compared, which every caller treats as
- * "changed".
- *
- * @param state - Engine state from {@link readEngineContentState}
- * @param anchor - The claim's anchor
- * @param inputs - Staging inputs to compare, or undefined for the whole tree
- * @param rebuilt - Request paths the current build stages afresh
- */
-export async function findChangedInputs(state, anchor, inputs, rebuilt = []) {
-    const candidates = await candidatePaths(state, anchor, inputs, rebuilt);
-    if (candidates === undefined)
-        return undefined;
-    const changed = [];
-    for (const file of candidates) {
-        const recorded = anchor.fingerprints[file];
-        // Not recorded: the staged copy is the anchor HEAD's, and the file is
-        // a candidate only because it was committed or dirtied since.
-        if (recorded === undefined || (await liveHash(state, file)) !== recorded)
-            changed.push(file);
-    }
-    return changed.sort();
-}
-/**
- * The anchor after the current build restaged `rebuilt`: recorded content
- * for those paths becomes their live content. Undefined when that content
- * cannot be read or the anchor cannot be compared.
- */
-export async function refreshAnchor(state, anchor, rebuilt) {
-    const everything = await candidatePaths(state, anchor, undefined, []);
-    if (everything === undefined)
-        return undefined;
-    const restaged = (file) => rebuilt.some((path) => isUnderPath(file, path));
-    const fingerprints = {};
-    for (const [file, hash] of Object.entries(anchor.fingerprints)) {
-        if (!restaged(file))
-            fingerprints[file] = hash;
-    }
-    for (const file of everything) {
-        // A restaged file equal to the anchor HEAD's content needs no entry.
-        if (!restaged(file) || (state.head === anchor.engineHeadSha && !state.dirty.has(file))) {
-            continue;
-        }
-        const live = await liveHash(state, file);
-        if (live === undefined)
-            return undefined;
-        fingerprints[file] = live;
-    }
-    return { ...anchor, fingerprints };
-}
-/** Nearest directory at or above `dir` that holds a test manifest, or undefined. */
-async function findManifestDirectory(engineDir, dir) {
-    for (let current = dir;; current = posix.dirname(current)) {
-        const base = current === '.' ? '' : current;
-        try {
-            const entries = await readdir(join(engineDir, base));
-            if (entries.some((entry) => TEST_MANIFEST_BASENAMES.has(entry)))
-                return base;
-        }
-        catch {
-            // A missing directory has no manifest. Keep walking up.
-        }
-        if (base === '')
-            return undefined;
-    }
-}
-/**
- * The request paths a scoped build restages, widened by the test manifests
- * of every requested file: packaging one file of a manifest re-processes
- * the manifest itself, so a manifest that gained an entry for that file is
- * restaged too, and must not count as a changed input of the manifest's
- * other files afterwards.
- *
- * @param engineDir - Path to the engine directory
- * @param requested - Normalized request paths of the build
- */
-export async function widenWithRestagedManifests(engineDir, requested) {
-    const widened = new Set(requested);
-    for (const path of requested) {
-        if (!TEST_FILE_PATTERN.test(posix.basename(path)))
-            continue;
-        const dir = await findManifestDirectory(engineDir, posix.dirname(path));
-        if (dir === undefined)
-            continue;
-        let entries;
-        try {
-            entries = await readdir(join(engineDir, dir));
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            if (TEST_MANIFEST_BASENAMES.has(entry))
-                widened.add(dir === '' ? entry : `${dir}/${entry}`);
-        }
-    }
-    return [...widened];
-}
-/** A test implementation file (`browser_*.js`, `test_*.js`, …), not a directory. */
-const TEST_FILE_PATTERN = /^(?:browser|test)_.*\.m?js$/;
-/** Test manifests at or beneath `dir`, bounded by {@link MAX_WALK_ENTRIES}. */
-async function findManifestsBeneath(engineDir, dir) {
-    const manifests = [];
-    const pending = [dir];
-    let visited = 0;
-    while (pending.length > 0 && visited < MAX_WALK_ENTRIES) {
-        const current = pending.pop() ?? '';
-        let entries;
-        try {
-            entries = await readdir(join(engineDir, current), { withFileTypes: true });
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            visited += 1;
-            const path = current ? `${current}/${entry.name}` : entry.name;
-            if (entry.isDirectory())
-                pending.push(path);
-            else if (TEST_MANIFEST_BASENAMES.has(entry.name))
-                manifests.push(path);
-        }
-    }
-    return manifests;
-}
-/**
- * Engine-relative paths a manifest names outside its own directory. Bare
- * names stay inside it. `!/` and `/` prefixes are engine-root relative, as
- * in mozbuild manifests. A glob keeps the directory part before its first
- * wildcard segment.
- */
-export function manifestExternalReferences(manifestPath, text) {
-    const dir = posix.dirname(manifestPath);
-    const refs = [];
-    for (const token of text.match(/[\w.!~@+\-/*?{}]+/g) ?? []) {
-        if (!token.includes('/') || token.includes('//'))
-            continue;
-        const rooted = token.startsWith('!/')
-            ? token.slice(2)
-            : token.startsWith('/')
-                ? token.slice(1)
-                : undefined;
-        const resolved = rooted === undefined ? posix.join(dir, token) : posix.normalize(rooted);
-        const segments = resolved.split('/');
-        const wildcard = segments.findIndex((segment) => /[*?{}]/.test(segment));
-        const path = normalizeRequestPath(wildcard >= 0 ? segments.slice(0, wildcard).join('/') : resolved);
-        if (path === '' || path.startsWith('..') || isUnderPath(path, dir))
-            continue;
-        refs.push(path);
-    }
-    return refs;
-}
-/** Drops entries that sit beneath another entry, then sorts. */
-function collapsePaths(paths) {
-    const unique = [...new Set(paths)].sort();
-    return unique.filter((path) => !unique.some((other) => other !== path && isUnderPath(path, other)));
-}
-/**
- * Staging inputs of one request path. See the module comment.
- * @param engineDir - Path to the engine directory
- * @param requestPath - Engine-relative request path (file or directory)
- */
-export async function collectStagingInputs(engineDir, requestPath) {
-    const path = normalizeRequestPath(requestPath);
-    let isDirectory = false;
-    try {
-        isDirectory = (await stat(join(engineDir, path))).isDirectory();
-    }
-    catch {
-        // A missing request path is staged by nothing. Its directory still decides.
-    }
-    const start = isDirectory ? path : posix.dirname(path);
-    const base = await findManifestDirectory(engineDir, start === '.' ? '' : start);
-    const fallback = start === '.' || start === '' ? path : start;
-    const root = base === undefined || base === '' ? fallback : base;
-    const manifests = new Set();
-    for (const entry of await readdir(join(engineDir, root)).catch(() => [])) {
-        if (TEST_MANIFEST_BASENAMES.has(entry))
-            manifests.add(`${root}/${entry}`);
-    }
-    if (isDirectory) {
-        for (const manifest of await findManifestsBeneath(engineDir, path))
-            manifests.add(manifest);
-    }
-    const inputs = [root, path];
-    for (const manifest of manifests) {
-        try {
-            const text = await readFile(join(engineDir, manifest), 'utf8');
-            inputs.push(...manifestExternalReferences(manifest, text));
-        }
-        catch (error) {
-            verbose(`Coverage anchor: cannot read ${manifest} — ${toError(error).message}`);
-        }
-    }
-    return collapsePaths(inputs);
-}
-/**
- * Records the anchor of a request path this build staged. Undefined when
- * HEAD is unborn or an input's content cannot be read: the path is still
- * claimed, and later retention falls back to the baseline-wide anchor.
- *
- * @param state - Engine state after the build
- * @param requestPath - Engine-relative request path
- * @param mozconfigHash - Hash of the mozconfig the build configured with
- */
-export async function createCoverageRecord(state, requestPath, mozconfigHash) {
-    if (state.head === undefined)
-        return undefined;
-    const inputs = await collectStagingInputs(state.engineDir, requestPath);
-    return narrowAnchor(state, { engineHeadSha: state.head, mozconfigHash, fingerprints: {} }, inputs, [...state.dirty]);
-}
-/**
- * Restricts an anchor to `inputs`. `extraDirty` adds paths whose live content
- * becomes the recorded one (the dirty set of a record being created).
- */
-export async function narrowAnchor(state, anchor, inputs, extraDirty = []) {
-    const fingerprints = {};
-    for (const [file, hash] of Object.entries(anchor.fingerprints)) {
-        if (inputs.some((input) => isUnderPath(file, input)))
-            fingerprints[file] = hash;
-    }
-    for (const file of extraDirty) {
-        if (!inputs.some((input) => isUnderPath(file, input)))
-            continue;
-        const live = await liveHash(state, file);
-        if (live === undefined)
-            return undefined;
-        fingerprints[file] = live;
-    }
-    return { ...anchor, fingerprints, inputs };
-}

package/dist/src/core/destructive.d.ts

@@ -1,144 +0,0 @@
-/**
- * Shared destructive-operation contract: interactive confirmation, non-TTY
- * refusal, dry-run plumbing, hard-refusal on structural conflicts, and a
- * JSONL audit log.
- *
- * This exists because the repair primitives (`patch delete`, `patch reorder`,
- * `re-export --files`) and the new `export --dry-run`/`export --order` flags
- * all share the same dance: build a change summary, gate it behind a prompt,
- * accept a `--yes` bypass for CI, accept a `--dry-run` no-op, and refuse
- * outright when the change would introduce a structural conflict (e.g. a
- * forward-import that later-patch lint would then block). Without a single
- * helper, every new destructive command would re-implement this and drift.
- */
-/**
- * A structural conflict that must block the operation even under `--force`.
- *
- * Intended for cases like "reorder would introduce a forward-import" or
- * "delete would orphan a later patch's import", situations where the
- * operator almost certainly wants a different fix (re-export --files, etc.)
- * rather than a bypass. `--force-unsafe` is the escape hatch when the
- * operator genuinely accepts the risk.
- */
-export interface ConflictReport {
-    /** Short one-line reason the operation is refused. */
-    reason: string;
-    /** Specific conflicts (patch names, file paths, lint findings). */
-    details: string[];
-}
-/** Inputs to {@link confirmDestructive}. */
-export interface DestructiveOpInput {
-    /** Operation identifier, used in history entries (e.g. `patch-delete`). */
-    operation: string;
-    /** Short one-line title shown in the prompt. */
-    title: string;
-    /**
-     * Detailed change summary: every affected patch, file, or renumber row.
-     * Generic "proceed? [y/N]" is insufficient per the destructive-op
-     * contract. Callers must list every concrete change here.
-     */
-    summary: string[];
-    /** Whether the caller passed `--yes`. */
-    yes: boolean;
-    /** Whether the caller passed `--dry-run`. */
-    dryRun: boolean;
-    /** Whether the caller passed `--force-unsafe`. Only this flag bypasses conflicts. */
-    unsafeOverride?: boolean;
-    /** Structural conflicts that should block the operation unless `unsafeOverride`. */
-    conflicts?: ConflictReport | null;
-}
-/**
- * Outcome of the destructive-operation contract.
- *
- * `'declined'` means the operator answered "no", a successful run that
- * chose not to proceed, so callers return normally and the process exits 0.
- * An interrupt (Esc / Ctrl+C) is not represented here: it throws
- * {@link CancellationError} and exits 130. Collapsing the two would make an
- * interrupted prompt indistinguishable from a declined one.
- */
-export type DestructiveOpResult = 'proceed' | 'dry-run' | 'declined';
-/**
- * Inputs to {@link appendHistory}. Entries are appended as one JSON record
- * per line. Callers should only append after a mutation succeeds so
- * rolled-back failures never leave ghost entries.
- */
-export interface HistoryEntry {
-    /** Operation identifier matching the DestructiveOpInput. */
-    operation: string;
-    /** Serializable argument payload (flags, targets, renumber map, etc.). */
-    args: Record<string, unknown>;
-    /** True if `--yes` was used. */
-    yes?: boolean;
-    /** True if `--force-unsafe` was used. */
-    unsafeOverride?: boolean;
-    /** Result: `'ok'` on success. Other strings describe failure. */
-    result: string;
-}
-/**
- * True when both standard handles are real TTYs, i.e. an interactive prompt
- * can actually be answered.
- *
- * Named for the condition rather than for confirmation specifically: many
- * call sites gate a `text()` / `multiselect()` input prompt or a mode
- * switch, not a destructive confirmation.
- *
- * Node types `isTTY` as `boolean`, but at runtime it is `true | undefined`
- * (absent when the handle is not a TTY). Unusual harnesses (vitest stdio
- * capture, CI spawners, mocked pipes) can also leave it unset on only one
- * handle, so every falsy variant (false, undefined, a null-patched mock)
- * must route to the non-interactive path.
- */
-export declare function stdioIsInteractive(): boolean;
-/**
- * Up-front non-interactive refusal for a command that will end at
- * {@link confirmDestructive}.
- *
- * `confirmDestructive` already refuses a prompt-less run rather than
- * proceeding silently, but it does so at the end, after the command has
- * built diffs and run projected per-patch lint. On `patch move-files
- * --create` that is minutes of work before a scripted run learns it needed
- * `--yes`, and the failure reads as an obscure late error rather than a
- * usage problem. Calling this at command entry turns it into a usage
- * refusal that names the flag.
- *
- * A `--yes` or `--dry-run` run never prompts, so neither is refused.
- *
- * @param operation - Stable operation id, e.g. `patch-move-files-create`
- * @param options - The run's `--yes` / `--dry-run` state
- * @throws InvalidArgumentError when the run would prompt but cannot
- */
-export declare function assertConfirmationAvailable(operation: string, options: {
-    yes?: boolean | undefined;
-    dryRun?: boolean | undefined;
-}): void;
-/**
- * Executes the destructive-operation contract: summary → conflict refusal →
- * dry-run / force / prompt / non-TTY refusal.
- *
- * Returns the decision for the caller to act on. Callers must not execute
- * the mutation when the result is `'dry-run'` or `'declined'`, and must call
- * {@link appendHistory} only after the mutation succeeds (never on dry-run
- * or decline).
- *
- * @param input - Operation description, flags, and optional conflict report
- * @returns `'proceed'` to execute, `'dry-run'` to skip execution, or
- *   `'declined'` when the user declined the prompt
- */
-export declare function confirmDestructive(input: DestructiveOpInput): Promise<DestructiveOpResult>;
-/**
- * Appends a single JSONL record to the project's patch history log
- * (`.fireforge/history.jsonl` unless `fireforge.json#history.path` says
- * otherwise; a log found at `patches/.fireforge-history.jsonl` is moved
- * there first).
- *
- * Call order matters: append only after the mutation succeeds, never
- * pre-emptively, so rolled-back failures do not leave ghost entries. The log
- * is append-only and advisory: no code path reads it back. It exists so
- * operators have a post-hoc audit trail when something goes wrong. Every
- * record carries the writing invocation's id (and `FIREFORGE_SESSION_ID`
- * when set), so a session sharing the checkout can pick out its own lines.
- *
- * @param patchesDir - Path to the patches directory
- * @param entry - Serializable history record
- */
-export declare function appendHistory(patchesDir: string, entry: HistoryEntry): Promise<void>;