@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/core/config.js

@@ -1,169 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Project configuration barrel module.
- *
- * Re-exports from focused sub-modules:
- *   config-paths.ts:    constants and project path derivation
- *   config-validate.ts: fireforge.json schema validation
- *   config-mutate.ts:   immutable config mutation
- *   config-state.ts:    state file management
- */
-import { basename } from 'node:path';
-import { ConfigError, ConfigNotFoundError } from '../errors/config.js';
-import { toError } from '../utils/errors.js';
-import * as fsUtils from '../utils/fs.js';
-import { isObject } from '../utils/validation.js';
-import { getProjectPaths } from './config-paths.js';
-import { validateConfig } from './config-validate.js';
-import { createSiblingLockPath, withFileLock } from './file-lock.js';
-import { rewriteJsonPreservingFormat } from './json-preserving-edit.js';
-// ---- re-exports ----
-export { mutateConfig } from './config-mutate.js';
-export { FIREFORGE_DIR, getProjectPaths, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
-export { loadState, updateState } from './config-state.js';
-export { validateConfig } from './config-validate.js';
-// ---- config I/O (stays here because it bridges paths + validation) ----
-/**
- * Checks if a fireforge.json exists in the given directory.
- * @param root - Root directory to check
- * @returns True if fireforge.json exists
- */
-export async function configExists(root) {
-    const paths = getProjectPaths(root);
-    // Strict probe: a permission error on `fireforge.json` must propagate
-    // rather than read as "no config here", which plain `pathExists` reports.
-    return fsUtils.pathExistsStrict(paths.config);
-}
-/**
- * Loads and validates the fireforge.json configuration.
- * @param root - Root directory of the project
- * @returns Validated FireForgeConfig
- * @throws Error if config doesn't exist or is invalid
- */
-export async function loadConfig(root) {
-    const paths = getProjectPaths(root);
-    // Strict probe: a permission error on `fireforge.json` must propagate
-    // rather than read as "no config here", which plain `pathExists` reports.
-    if (!(await fsUtils.pathExistsStrict(paths.config))) {
-        throw new ConfigNotFoundError(paths.config);
-    }
-    try {
-        const data = await fsUtils.readJson(paths.config);
-        return validateConfig(data);
-    }
-    catch (error) {
-        if (error instanceof ConfigError) {
-            throw error;
-        }
-        throw new ConfigError(`Invalid fireforge.json at ${paths.config}: ${toError(error).message}`);
-    }
-}
-/**
- * Reads the raw `fireforge.json` document without running it through
- * {@link validateConfig}. Returns every persisted key, including keys
- * written via `fireforge config <key> --force` that `validateConfig`
- * would strip from the typed result.
- *
- * Callers that need the validated, typed shape must still use
- * {@link loadConfig}. This helper exists specifically for the `config`
- * read path so `fireforge config <key>` can surface keys the write path
- * accepted under `--force`.
- *
- * @param root - Root directory of the project
- * @returns Raw config object as persisted on disk
- * @throws ConfigNotFoundError when fireforge.json is missing
- * @throws ConfigError when the file is not valid JSON
- */
-export async function loadRawConfigDocument(root) {
-    const paths = getProjectPaths(root);
-    // Strict probe: a permission error on `fireforge.json` must propagate
-    // rather than read as "no config here", which plain `pathExists` reports.
-    if (!(await fsUtils.pathExistsStrict(paths.config))) {
-        throw new ConfigNotFoundError(paths.config);
-    }
-    try {
-        const data = await fsUtils.readJson(paths.config);
-        if (!isObject(data)) {
-            throw new ConfigError(`Invalid fireforge.json at ${paths.config}: expected an object`);
-        }
-        // `data` came out of JSON.parse, which can only ever produce JSON
-        // values, so with the object check above the JsonObject contract holds.
-        return data;
-    }
-    catch (error) {
-        if (error instanceof ConfigError || error instanceof ConfigNotFoundError) {
-            throw error;
-        }
-        throw new ConfigError(`Invalid fireforge.json at ${paths.config}: ${toError(error).message}`);
-    }
-}
-/**
- * Writes a configuration to fireforge.json.
- * @param root - Root directory of the project
- * @param config - Configuration to write
- */
-export async function writeConfig(root, config) {
-    await writeConfigDocument(root, config);
-}
-/**
- * Writes a raw config document to fireforge.json.
- * This is used by CLI `config --force`, where callers may intentionally write
- * keys or value shapes outside the validated FireForgeConfig schema.
- *
- * An existing file is edited in place: only the values that differ from the
- * document on disk are rewritten, so a one-key change keeps the file's
- * formatting (compact objects and arrays, indentation, key order) and stays
- * a one-hunk diff. A missing or unparseable file is written in full.
- *
- * Individual writes are atomic via {@link writeJson} (temp file + rename),
- * but atomicity alone does not prevent lost updates across concurrent
- * writers: each writer reads an old copy, mutates its own in-memory view,
- * and writes it back, so the second writer's rename clobbers the first
- * writer's changes. Callers that do read → mutate → write must hold
- * {@link withConfigFileLock} for the full round-trip to serialise
- * against other writers.
- */
-export async function writeConfigDocument(root, config) {
-    const paths = getProjectPaths(root);
-    if (await fsUtils.pathExists(paths.config)) {
-        const current = await fsUtils.readText(paths.config);
-        // `FireForgeConfig` is plain parsed-config data, so it is a JSON object.
-        const edited = rewriteJsonPreservingFormat(current, config);
-        if (edited !== undefined) {
-            if (edited !== current)
-                await fsUtils.writeText(paths.config, edited);
-            return;
-        }
-    }
-    await fsUtils.writeJson(paths.config, config);
-}
-/**
- * Runs an operation while holding a sidecar lock on `fireforge.json`.
- *
- * Two concurrent `fireforge config <key> <value>` invocations each run
- * load → mutate → writeJson against the same document. Without this lock
- * the second rename lands after the first and silently drops the first
- * writer's key, with both commands exiting 0.
- *
- * Reads (`loadConfig`, `loadRawConfigDocument`) stay lock-free: writers
- * always use `writeJson`'s atomic temp-file + rename, so a reader observes
- * either the pre- or post-write document but never a torn file. The lock
- * only serialises writers against other writers.
- *
- * The lock is a sidecar directory `${config}.fireforge-config.lock`, and
- * `withFileLock` handles stale-lock recovery (PID-alive probe, age-based
- * fallback), so a crashed writer does not permanently block future writes.
- *
- * @param root - Root directory of the project
- * @param operation - Async function to run while holding the lock
- * @returns Whatever the operation returns
- */
-export async function withConfigFileLock(root, operation) {
-    const paths = getProjectPaths(root);
-    return withFileLock(createSiblingLockPath(paths.config, '.fireforge-config.lock'), operation, {
-        onTimeoutMessage: `Timed out waiting to update ${basename(paths.config)}. ` +
-            'If no other fireforge process is running, remove the stale lock directory and retry.',
-        onStaleLockMessage: (ageMs) => `Removing stale FireForge config lock for ${basename(paths.config)} ` +
-            `(age: ${Math.round(ageMs / 1000)}s). A previous fireforge process may have crashed.`,
-    });
-}

package/dist/src/core/coverage-dispatch.d.ts

@@ -1,24 +0,0 @@
-/**
- * Dispatch-time half of per-path coverage. A scoped build that followed a
- * full build carries the full build's anchor forward instead of collapsing
- * the claim to its own paths. A requested path outside the scoped list is
- * then still covered while its own staging inputs are unchanged against
- * that anchor, and a refusal names the inputs that did change.
- */
-import type { BuildBaseline } from './build-baseline-types.js';
-/** A requested path no recorded claim covers, with the inputs that explain it. */
-export interface UncoveredRequest {
-    path: string;
-    /** Staging inputs changed since the carried full build. Empty when unknown. */
-    changed: string[];
-}
-/**
- * Re-checks the paths the scoped list does not cover against the carried
- * full-build anchor. Returns the paths that stay uncovered.
- *
- * @param engineDir - Path to the engine directory
- * @param baseline - Last successful build's baseline
- * @param uncovered - Request paths outside the scoped list
- * @param fullSuite - The sentinel standing for a path-less (full-suite) request
- */
-export declare function filterByCarriedFullCoverage(engineDir: string, baseline: BuildBaseline | undefined, uncovered: readonly string[], fullSuite: string): Promise<UncoveredRequest[]>;

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

@@ -1,44 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Dispatch-time half of per-path coverage. A scoped build that followed a
- * full build carries the full build's anchor forward instead of collapsing
- * the claim to its own paths. A requested path outside the scoped list is
- * then still covered while its own staging inputs are unchanged against
- * that anchor, and a refusal names the inputs that did change.
- */
-import { toError } from '../utils/errors.js';
-import { verbose } from '../utils/logger.js';
-import { collectStagingInputs, findChangedInputs, hashEngineFile, readEngineContentState, } from './coverage-records.js';
-/**
- * Re-checks the paths the scoped list does not cover against the carried
- * full-build anchor. Returns the paths that stay uncovered.
- *
- * @param engineDir - Path to the engine directory
- * @param baseline - Last successful build's baseline
- * @param uncovered - Request paths outside the scoped list
- * @param fullSuite - The sentinel standing for a path-less (full-suite) request
- */
-export async function filterByCarriedFullCoverage(engineDir, baseline, uncovered, fullSuite) {
-    const unresolved = uncovered.map((path) => ({ path, changed: [] }));
-    const anchor = baseline?.fullCoverageAnchor;
-    if (anchor === undefined || uncovered.length === 0)
-        return unresolved;
-    if ((await hashEngineFile(engineDir, 'mozconfig')) !== anchor.mozconfigHash)
-        return unresolved;
-    let state;
-    try {
-        state = await readEngineContentState(engineDir);
-    }
-    catch (error) {
-        verbose(`Coverage check: engine state unreadable — ${toError(error).message}`);
-        return unresolved;
-    }
-    const remaining = [];
-    for (const path of uncovered) {
-        const inputs = path === fullSuite ? undefined : await collectStagingInputs(engineDir, path);
-        const changed = await findChangedInputs(state, anchor, inputs);
-        if (changed === undefined || changed.length > 0)
-            remaining.push({ path, changed: changed ?? [] });
-    }
-    return remaining;
-}

package/dist/src/core/coverage-extend.d.ts

@@ -1,89 +0,0 @@
-/**
- * Decides which earlier packaging claims a scoped `fireforge test --build`
- * keeps. Retention is per staged path (see `coverage-records.ts`): an
- * earlier path stays covered while its own staging inputs are unchanged,
- * whatever moved elsewhere in the engine, and a full claim narrows to
- * per-path checks once something outside the new scope changed instead of
- * collapsing to this build's paths. `--extend-coverage` turns any drop into
- * a refusal before the build.
- *
- * Fingerprints must be complete: a record of packageable inputs only cannot
- * prove that a test fixture or manifest still matches its staged copy.
- */
-import type { BuildBaseline, CoverageAnchor, CoverageRecord, TestPackagingCoverage } from './build-baseline-types.js';
-export { hashEngineFile } from './coverage-records.js';
-/** What a dropped full claim is called in notices and refusals. */
-export declare const FULL_CLAIM_LABEL = "full coverage";
-/** An earlier claim this build cannot keep, and why. */
-export interface DroppedClaim {
-    /** Request path, or {@link FULL_CLAIM_LABEL}. */
-    path: string;
-    /** Staging inputs whose content changed since the claim was staged. */
-    changed: string[];
-    /** Why the claim cannot be verified at all, when no input list explains it. */
-    reason?: string;
-}
-/** What a scoped build keeps of the recorded coverage. */
-export interface CoverageRetentionPlan {
-    /** The previous claim was full and nothing outside this build's scope moved. */
-    keepFull: boolean;
-    /** Earlier per-path records kept, refreshed for this build's paths. */
-    retained: Record<string, CoverageRecord>;
-    /** Full-build anchor carried for dispatch-time per-path checks. */
-    fullAnchor: CoverageAnchor | undefined;
-    /** Changed inputs that narrowed a full claim to per-path checks. */
-    narrowedBy: string[];
-    /** Earlier claims this build cannot keep. */
-    dropped: DroppedClaim[];
-}
-/** The baseline-wide anchor a baseline's own fields describe, when complete. */
-export declare function baselineAnchor(baseline: BuildBaseline): CoverageAnchor | undefined;
-/**
- * Plans which earlier claims a scoped build over `requested` keeps. Runs
- * before the build lock, so a refusal costs neither build time nor the
- * lock. The mozconfig half runs later, via {@link applyMozconfigAnchor}.
- *
- * @param engineDir - Path to the engine directory
- * @param previous - Baseline recorded by the previous build
- * @param requested - Normalized request paths this build packages
- */
-export declare function planCoverageRetention(engineDir: string, previous: BuildBaseline | undefined, requested: string[]): Promise<CoverageRetentionPlan>;
-/**
- * Applies the mozconfig half of the anchor: a claim staged under a different
- * `engine/mozconfig` is dropped. Runs after `prepareBuildEnvironment`
- * regenerated the file this build configures with, and before mach.
- *
- * @param engineDir - Path to the engine directory
- * @param plan - Plan from {@link planCoverageRetention}
- */
-export declare function applyMozconfigAnchor(engineDir: string, plan: CoverageRetentionPlan): Promise<CoverageRetentionPlan>;
-/** Fields a scoped build writes onto its baseline. */
-export interface RecordedCoverage {
-    testPackagingCoverage: TestPackagingCoverage;
-    testCoverageRecords?: Record<string, CoverageRecord>;
-    fullCoverageAnchor?: CoverageAnchor;
-}
-/**
- * The coverage a green scoped build records: `'full'` when the plan kept a
- * full claim, otherwise this build's paths with fresh records plus every
- * retained earlier path, and the carried full anchor.
- *
- * @param engineDir - Path to the engine directory
- * @param plan - Plan after {@link applyMozconfigAnchor}
- * @param requestedPaths - Request paths this build packaged. Normalized
- *   here (no trailing slash, no `./`): the baseline validator rejects the
- *   raw CLI shapes, and a baseline it rejects refuses every later run.
- */
-export declare function recordScopedCoverage(engineDir: string, plan: CoverageRetentionPlan, requestedPaths: string[]): Promise<RecordedCoverage>;
-/** Renders one dropped claim with its cause. */
-export declare function describeDroppedClaim(claim: DroppedClaim): string;
-/**
- * The notice a scoped build prints about earlier coverage, or undefined
- * when nothing was dropped or narrowed.
- */
-export declare function formatCoverageRetentionNotice(plan: CoverageRetentionPlan): string | undefined;
-/**
- * The `--extend-coverage` refusal: the flag asks that no earlier claim be
- * dropped, and the plan would drop some.
- */
-export declare function formatExtendCoverageRefusal(dropped: readonly DroppedClaim[]): string;

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

@@ -1,239 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Decides which earlier packaging claims a scoped `fireforge test --build`
- * keeps. Retention is per staged path (see `coverage-records.ts`): an
- * earlier path stays covered while its own staging inputs are unchanged,
- * whatever moved elsewhere in the engine, and a full claim narrows to
- * per-path checks once something outside the new scope changed instead of
- * collapsing to this build's paths. `--extend-coverage` turns any drop into
- * a refusal before the build.
- *
- * Fingerprints must be complete: a record of packageable inputs only cannot
- * prove that a test fixture or manifest still matches its staged copy.
- */
-import { toError } from '../utils/errors.js';
-import { verbose } from '../utils/logger.js';
-import { collectStagingInputs, createCoverageRecord, findChangedInputs, hashEngineFile, isUnderPath, narrowAnchor, normalizeRequestPath, readEngineContentState, refreshAnchor, widenWithRestagedManifests, } from './coverage-records.js';
-export { hashEngineFile } from './coverage-records.js';
-/** Filename of the generated mozconfig, relative to the engine directory. */
-const MOZCONFIG_FILENAME = 'mozconfig';
-/** How many paths a notice or refusal names before truncating. */
-const MAX_PATHS_REPORTED = 5;
-/** What a dropped full claim is called in notices and refusals. */
-export const FULL_CLAIM_LABEL = 'full coverage';
-const UNVERIFIABLE = 'engine HEAD or the recorded anchor cannot be compared';
-const NO_FINGERPRINTS = 'the record has no complete staging-input fingerprints';
-/** The baseline-wide anchor a baseline's own fields describe, when complete. */
-export function baselineAnchor(baseline) {
-    if (baseline.testInputFingerprints === undefined || baseline.mozconfigHash === undefined) {
-        return undefined;
-    }
-    return {
-        engineHeadSha: baseline.engineHeadSha,
-        mozconfigHash: baseline.mozconfigHash,
-        fingerprints: baseline.testInputFingerprints,
-    };
-}
-function emptyPlan() {
-    return { keepFull: false, retained: {}, fullAnchor: undefined, narrowedBy: [], dropped: [] };
-}
-/** True when a request path in `requested` stages `path` afresh. */
-function rebuiltBy(path, rebuilt) {
-    const normalized = normalizeRequestPath(path);
-    return rebuilt.some((request) => isUnderPath(normalized, request));
-}
-async function planFullClaim(state, previous, requested) {
-    const plan = emptyPlan();
-    const anchor = previous.fullCoverageAnchor ?? baselineAnchor(previous);
-    if (anchor === undefined) {
-        plan.dropped.push({ path: FULL_CLAIM_LABEL, changed: [], reason: NO_FINGERPRINTS });
-        return plan;
-    }
-    const changed = await findChangedInputs(state, anchor, undefined, requested);
-    const refreshed = changed === undefined ? undefined : await refreshAnchor(state, anchor, requested);
-    if (changed === undefined || refreshed === undefined) {
-        plan.dropped.push({ path: FULL_CLAIM_LABEL, changed: [], reason: UNVERIFIABLE });
-        return plan;
-    }
-    plan.keepFull = changed.length === 0;
-    plan.fullAnchor = refreshed;
-    plan.narrowedBy = changed;
-    return plan;
-}
-async function retainRecord(state, previous, path, requested) {
-    let record = previous.testCoverageRecords?.[path];
-    if (record === undefined) {
-        // A path recorded before per-path anchors existed: the baseline-wide
-        // anchor, restricted to the path's own inputs, says the same thing.
-        const anchor = baselineAnchor(previous);
-        if (anchor === undefined)
-            return { path, changed: [], reason: NO_FINGERPRINTS };
-        const inputs = await collectStagingInputs(state.engineDir, path);
-        record = await narrowAnchor(state, anchor, inputs);
-        if (record === undefined)
-            return { path, changed: [], reason: UNVERIFIABLE };
-    }
-    const changed = await findChangedInputs(state, record, record.inputs, requested);
-    if (changed === undefined)
-        return { path, changed: [], reason: UNVERIFIABLE };
-    if (changed.length > 0)
-        return { path, changed };
-    const refreshed = await refreshAnchor(state, record, requested);
-    return refreshed === undefined
-        ? { path, changed: [], reason: UNVERIFIABLE }
-        : { record: refreshed };
-}
-/**
- * Plans which earlier claims a scoped build over `requested` keeps. Runs
- * before the build lock, so a refusal costs neither build time nor the
- * lock. The mozconfig half runs later, via {@link applyMozconfigAnchor}.
- *
- * @param engineDir - Path to the engine directory
- * @param previous - Baseline recorded by the previous build
- * @param requested - Normalized request paths this build packages
- */
-export async function planCoverageRetention(engineDir, previous, requested) {
-    if (previous === undefined)
-        return emptyPlan();
-    const coverage = previous.testPackagingCoverage ?? 'full';
-    const rebuilt = await widenWithRestagedManifests(engineDir, requested.map(normalizeRequestPath).filter((path) => path !== ''));
-    let state;
-    try {
-        state = await readEngineContentState(engineDir);
-    }
-    catch (error) {
-        verbose(`Coverage retention: engine state unreadable — ${toError(error).message}`);
-        const paths = coverage === 'full' ? [FULL_CLAIM_LABEL] : coverage;
-        return {
-            ...emptyPlan(),
-            dropped: paths.map((path) => ({ path, changed: [], reason: UNVERIFIABLE })),
-        };
-    }
-    if (coverage === 'full')
-        return planFullClaim(state, previous, rebuilt);
-    const plan = emptyPlan();
-    if (previous.fullCoverageAnchor !== undefined) {
-        plan.fullAnchor = await refreshAnchor(state, previous.fullCoverageAnchor, rebuilt);
-        if (plan.fullAnchor === undefined) {
-            plan.dropped.push({ path: FULL_CLAIM_LABEL, changed: [], reason: UNVERIFIABLE });
-        }
-    }
-    for (const path of coverage) {
-        if (rebuiltBy(path, rebuilt))
-            continue;
-        const outcome = await retainRecord(state, previous, path, rebuilt);
-        if ('record' in outcome)
-            plan.retained[path] = outcome.record;
-        else
-            plan.dropped.push(outcome);
-    }
-    return plan;
-}
-/**
- * Applies the mozconfig half of the anchor: a claim staged under a different
- * `engine/mozconfig` is dropped. Runs after `prepareBuildEnvironment`
- * regenerated the file this build configures with, and before mach.
- *
- * @param engineDir - Path to the engine directory
- * @param plan - Plan from {@link planCoverageRetention}
- */
-export async function applyMozconfigAnchor(engineDir, plan) {
-    const live = await hashEngineFile(engineDir, MOZCONFIG_FILENAME);
-    const reason = 'engine/mozconfig differs from the build that staged it';
-    const next = { ...plan, retained: {}, dropped: [...plan.dropped] };
-    for (const [path, record] of Object.entries(plan.retained)) {
-        if (live !== undefined && record.mozconfigHash === live)
-            next.retained[path] = record;
-        else
-            next.dropped.push({ path, changed: [], reason });
-    }
-    if (plan.fullAnchor !== undefined &&
-        (live === undefined || plan.fullAnchor.mozconfigHash !== live)) {
-        next.fullAnchor = undefined;
-        next.keepFull = false;
-        next.narrowedBy = [];
-        next.dropped.push({ path: FULL_CLAIM_LABEL, changed: [], reason });
-    }
-    return next;
-}
-/**
- * The coverage a green scoped build records: `'full'` when the plan kept a
- * full claim, otherwise this build's paths with fresh records plus every
- * retained earlier path, and the carried full anchor.
- *
- * @param engineDir - Path to the engine directory
- * @param plan - Plan after {@link applyMozconfigAnchor}
- * @param requestedPaths - Request paths this build packaged. Normalized
- *   here (no trailing slash, no `./`): the baseline validator rejects the
- *   raw CLI shapes, and a baseline it rejects refuses every later run.
- */
-export async function recordScopedCoverage(engineDir, plan, requestedPaths) {
-    if (plan.keepFull)
-        return { testPackagingCoverage: 'full' };
-    const requested = [
-        ...new Set(requestedPaths.map(normalizeRequestPath).filter((path) => path.length > 0)),
-    ];
-    const records = { ...plan.retained };
-    try {
-        const state = await readEngineContentState(engineDir);
-        const mozconfigHash = await hashEngineFile(engineDir, MOZCONFIG_FILENAME);
-        for (const path of requested) {
-            const record = mozconfigHash === undefined
-                ? undefined
-                : await createCoverageRecord(state, path, mozconfigHash);
-            if (record !== undefined)
-                records[path] = record;
-        }
-    }
-    catch (error) {
-        verbose(`Coverage records: could not anchor this build's paths — ${toError(error).message}`);
-    }
-    const kept = Object.keys(plan.retained);
-    const coverage = kept.length === 0 ? [...requested] : [...new Set([...kept, ...requested])].sort();
-    return {
-        testPackagingCoverage: coverage,
-        ...(Object.keys(records).length > 0 ? { testCoverageRecords: records } : {}),
-        ...(plan.fullAnchor !== undefined ? { fullCoverageAnchor: plan.fullAnchor } : {}),
-    };
-}
-function capList(paths) {
-    const head = paths.slice(0, MAX_PATHS_REPORTED).join(', ');
-    const extra = paths.length - Math.min(paths.length, MAX_PATHS_REPORTED);
-    return extra > 0 ? `${head}, … (+${extra} more)` : head;
-}
-/** Renders one dropped claim with its cause. */
-export function describeDroppedClaim(claim) {
-    const cause = claim.changed.length > 0
-        ? `staging inputs changed: ${capList(claim.changed)}`
-        : (claim.reason ?? UNVERIFIABLE);
-    return `${claim.path} (${cause})`;
-}
-/**
- * The notice a scoped build prints about earlier coverage, or undefined
- * when nothing was dropped or narrowed.
- */
-export function formatCoverageRetentionNotice(plan) {
-    const lines = [];
-    if (plan.dropped.length > 0) {
-        const kept = Object.keys(plan.retained);
-        lines.push(`Scoped build drops previous packaging coverage for ${plan.dropped.map(describeDroppedClaim).join('; ')}.` +
-            (kept.length > 0 ? ` Kept: ${capList(kept)}.` : '') +
-            ' Rebuild a dropped path (alone or with this one) before running it without --build.');
-    }
-    if (!plan.keepFull && plan.fullAnchor !== undefined && plan.narrowedBy.length > 0) {
-        lines.push(`Full packaging coverage is now checked per path: ${capList(plan.narrowedBy)} changed outside ` +
-            "this build's scope, so a later run is refused only for paths whose own staging inputs include a changed file.");
-    }
-    return lines.length > 0 ? lines.join('\n') : undefined;
-}
-/**
- * The `--extend-coverage` refusal: the flag asks that no earlier claim be
- * dropped, and the plan would drop some.
- */
-export function formatExtendCoverageRefusal(dropped) {
-    return (`--extend-coverage refused: this build would drop earlier packaging coverage for ` +
-        `${dropped.length} claim(s): ${dropped.map(describeDroppedClaim).join('; ')}. ` +
-        'Extending would vouch for staging that obj-*/_tests/ no longer matches. Rebuild those paths ' +
-        'together with this one, or drop the flag: without it the dropped claims are named and the ' +
-        'rest of the coverage is kept.');
-}

package/dist/src/core/coverage-records.d.ts

@@ -1,107 +0,0 @@
-/**
- * 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 { type CoverageAnchor, type CoverageRecord } from './build-baseline-types.js';
-/**
- * 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 declare function hashEngineFile(engineDir: string, relPath: string): Promise<string | undefined>;
-/** True for a test manifest path (by basename). */
-export declare function isTestManifestPath(path: string): boolean;
-/** Normalizes a request path: forward slashes, no `./`, no trailing slash. */
-export declare function normalizeRequestPath(path: string): string;
-/** True when `file` is `prefix` or sits beneath it. The empty prefix is the whole tree. */
-export declare function isUnderPath(file: string, prefix: string): boolean;
-/**
- * Engine state one coverage decision reads. Shared across every anchor a
- * decision verifies, so the git probes run once and each file is hashed
- * once.
- */
-export interface EngineContentState {
-    engineDir: string;
-    /** Current engine HEAD, or undefined for an unborn branch. */
-    head: string | undefined;
-    /** Engine-relative paths dirty against HEAD (tracked and untracked). */
-    dirty: ReadonlySet<string>;
-    hashes: Map<string, Promise<string | undefined>>;
-    diffs: Map<string, Promise<ReadonlySet<string> | undefined>>;
-}
-/**
- * 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 declare function readEngineContentState(engineDir: string): Promise<EngineContentState>;
-/**
- * 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 declare function findChangedInputs(state: EngineContentState, anchor: CoverageAnchor, inputs: readonly string[] | undefined, rebuilt?: readonly string[]): Promise<string[] | undefined>;
-/**
- * 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 declare function refreshAnchor<T extends CoverageAnchor>(state: EngineContentState, anchor: T, rebuilt: readonly string[]): Promise<T | 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 declare function widenWithRestagedManifests(engineDir: string, requested: readonly string[]): Promise<string[]>;
-/**
- * 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 declare function manifestExternalReferences(manifestPath: string, text: string): string[];
-/**
- * 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 declare function collectStagingInputs(engineDir: string, requestPath: string): Promise<string[]>;
-/**
- * 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 declare function createCoverageRecord(state: EngineContentState, requestPath: string, mozconfigHash: string): Promise<CoverageRecord | undefined>;
-/**
- * Restricts an anchor to `inputs`. `extraDirty` adds paths whose live content
- * becomes the recorded one (the dirty set of a record being created).
- */
-export declare function narrowAnchor(state: EngineContentState, anchor: CoverageAnchor, inputs: string[], extraDirty?: readonly string[]): Promise<CoverageRecord | undefined>;