@hominis/fireforge 0.49.1 → 0.50.0

package/dist/src/commands/test.js

@@ -3,16 +3,16 @@ import { join } from 'node:path';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { assertEngineExists } from '../core/engine-precondition.js';
 import { assertEngineGenerationUnchanged, snapshotEngineGeneration, } from '../core/engine-session-lock.js';
-import { hasBuildArtifacts, hasRunnableBundle } from '../core/mach.js';
+import { hasBuildArtifacts } from '../core/mach.js';
 import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
 import { ensureLaunchableBrowserNotRunning } from '../core/marionette-port.js';
 import { waitForPreflight } from '../core/preflight-wait.js';
-import { closeActiveRunLog, openRunLog, setActiveRunLog, writeToActiveRunLog, } from '../core/run-log.js';
+import { closeActiveRunLog, keepRunLogCopy, openRunLog, setActiveRunLog, writeToActiveRunLog, } from '../core/run-log.js';
 import { createPostRebuildFailureContext } from '../core/test-harness-output.js';
 import { analyzeTestPathScopes, formatScopeNotice, } from '../core/test-path-scope.js';
 import { cleanupProfileFiles, stageProfileFiles, } from '../core/test-profile-files.js';
 import { assertObjdirMatchesTreeMarker } from '../core/tree-store.js';
-import { FireForgeError, GeneralError, PreflightRefusalError } from '../errors/base.js';
+import { FireForgeError, GeneralError, LockContentionError, PreflightRefusalError, } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
@@ -24,7 +24,10 @@ import { runTestBuildPhase } from './test-build-phase.js';
 import { diagnoseShardOutcome, finalizeSingleRunOutcome } from './test-diagnose.js';
 import { buildPerfSampleEnv, mergeHarnessEnv, resolveShuffleSeed, shuffleTestGroups, } from './test-harness-env.js';
 import { removePgidFile, setActivePgidFile } from './test-harness-teardown.js';
-import { assertPathlessTestMode, assertTestModeCombinations, canaryTimeoutSeconds, classifyBeforeDispatch, reportCanaryOutcome, resolveCanaryPath, } from './test-modes.js';
+import { assertPathlessTestMode, assertTestModeCombinations, canaryTimeoutSeconds, classifyBeforeDispatch, reportCanaryOutcome, resolveCanaryPath, restartBetweenTestsArgs, } from './test-modes.js';
+import { orchestrateTestRuns } from './test-orchestrate.js';
+import { perfGenerationTolerance } from './test-perf-scope.js';
+import { resolveLaunchablePathForTests, runTestPreLockPreflight, TEST_BUILD_PREFLIGHT, } from './test-prelock.js';
 import { DEFAULT_HARNESS_RETRIES, finalizeShardedOutcome, runShardedTests, runTestsWithRetries, } from './test-run.js';
 import { emitFailVerdict, resetVerdictEmission, verdictEmitted } from './test-verdict.js';
 async function assertTestPathsExist(engineDir, testPaths) {
@@ -77,20 +80,6 @@ function filterRedundantXpcshellFlavorArgs(machArgs, classification) {
     }
     return filtered;
 }
-async function resolveLaunchablePathForTests(engineDir, binaryName, objDir) {
-    if (!objDir)
-        return undefined;
-    const bundleCheck = await hasRunnableBundle(engineDir, binaryName, objDir);
-    if (!bundleCheck.runnable) {
-        const expectedSuffix = bundleCheck.expectedPath
-            ? ` (expected at engine/${bundleCheck.expectedPath})`
-            : '';
-        throw new GeneralError(`Tests require a complete launchable build${expectedSuffix}. ` +
-            'The obj-*/dist/ tree exists but the launchable binary is missing — typically the result of an interrupted or partially failed `fireforge build`.\n\n' +
-            'Run "fireforge build" again and let it finish before retrying "fireforge test".');
-    }
-    return bundleCheck.expectedPath;
-}
 function logTestSelection(scopes) {
     if (scopes.length > 0) {
         const labels = scopes.map((scope) => scope.isDirectory && scope.testFileCount > 0
@@ -103,13 +92,6 @@ function logTestSelection(scopes) {
     }
     info('');
 }
-/** Build-artifact preflight wording for `fireforge test`. */
-const TEST_BUILD_PREFLIGHT = {
-    label: 'Tests',
-    requirement: 'Tests require a completed build.',
-    remediation: "Run 'fireforge build' first, then run 'fireforge test'.",
-    requireExisting: true,
-};
 /**
  * Runs the test command to execute mach tests.
  *
@@ -121,17 +103,22 @@ const TEST_BUILD_PREFLIGHT = {
  * since no harness classification exists for such a run. Writers closer to
  * the harness (doctor, canary, single, sharded, the engine-generation
  * guard) emit first and win.
+ * The lock-free checks (launchable binary, named-file checkJs, the
+ * `--wait-browser`/`--wait-port` budgets) run first, outside `underLock`,
+ * so a run that would be refused or would only wait never holds a place in
+ * the engine lock queue. See `test-prelock.ts`.
  * @param projectRoot - Root directory of the project
  * @param testPaths - Test file or directory paths
  * @param options - Test options
+ * @param underLock - Runs the rest of the command under the engine session lock
  */
-export async function testCommand(projectRoot, testPaths, options = {}) {
+export async function testCommand(projectRoot, testPaths, options = {}, underLock = (body) => body()) {
     intro('FireForge Test');
     resetVerdictEmission();
     // Opened before any work so a preflight refusal is logged too. Those are
     // exactly the runs whose only output a `tail` throws away. Closed in
     // `finally`, after the verdict line has already read the path.
-    setActiveRunLog(await openRunLog(projectRoot, 'test'));
+    setActiveRunLog(await keepRunLogCopy(await openRunLog(projectRoot, 'test'), options.keepLog, 'test'));
     setActivePgidFile(options.pgidFile);
     let staged;
     try {
@@ -139,12 +126,22 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
             staged = await stageProfileFiles(projectRoot, options.profileFile);
             options = { ...options, machArg: [...(options.machArg ?? []), ...staged.args] };
         }
-        await runTestCommandBody(projectRoot, testPaths, options, staged?.env);
+        const lockedOptions = await runTestPreLockPreflight(projectRoot, testPaths, options);
+        const profileEnv = staged?.env;
+        await underLock(() => orchestrateTestRuns(projectRoot, testPaths, lockedOptions, (paths, runOptions, hooks) => runTestCommandBody(projectRoot, paths, runOptions, profileEnv, hooks), (error) => {
+            renderPreflightRefusal(error);
+            emitFailVerdict('preflight', refusalNote(error));
+        }));
     }
     catch (error) {
         if (!verdictEmitted()) {
-            renderPreflightRefusal(error);
-            emitFailVerdict('preflight', refusalNote(error));
+            if (error instanceof LockContentionError) {
+                emitFailVerdict('lock-timeout');
+            }
+            else {
+                renderPreflightRefusal(error);
+                emitFailVerdict('preflight', refusalNote(error));
+            }
         }
         throw error;
     }
@@ -208,9 +205,11 @@ function renderPreflightRefusal(error) {
  * misdescribe a run whose harness already executed). It is emitted here so the
  * guard's throw can never leave a stale or missing verdict line behind.
  */
-async function verifyEngineGenerationOrEmitInconclusive(engineDir, before, powerChanged = false) {
+async function verifyEngineGenerationOrEmitInconclusive(engineDir, before, powerChanged = false, perfSamples) {
     try {
-        await assertEngineGenerationUnchanged(engineDir, before);
+        await (perfSamples === undefined
+            ? assertEngineGenerationUnchanged(engineDir, before)
+            : assertEngineGenerationUnchanged(engineDir, before, perfGenerationTolerance(engineDir)));
         if (powerChanged)
             throw new GeneralError('Perf power source changed during the run; repeat this sitting on a stable power source.');
     }
@@ -255,9 +254,35 @@ function prepareDispatchArguments(classification, options, canaryPath, projectCo
         ? filterRedundantXpcshellFlavorArgs(options.machArg, classification)
         : [];
     const extraArgs = prepareExtraMachArgs(options, shuffleSeed, canaryPath, projectConfig, forwardedMachArgs);
+    extraArgs.push(...restartBetweenTestsArgs(options, suite, forwardedMachArgs));
     return { suite, shuffleSeed, extraArgs };
 }
-async function runTestCommandBody(projectRoot, testPaths, options = {}, profileEnv) {
+/**
+ * Directory arguments mean exactly that directory: mozbuild's test resolver
+ * matches paths by string prefix, so a bare directory arg silently sweeps in
+ * prefix-named siblings, with `…/test/hominis` also running
+ * `…/test/hominis-tiles`, with no indication the scope widened. Each
+ * directory argument therefore dispatches as its enumerated explicit
+ * test-file list, which cannot prefix-match a sibling. A trailing-`/`
+ * normalization does not work, as mach still sweeps the sibling in. Any
+ * prefix-siblings are echoed so the narrowed scope is visible.
+ *
+ * xpcshell appdir auto-injection happens per harness invocation inside
+ * `runTestsWithRetries` (src/commands/test-run.ts) so sharded runs probe the
+ * manifest for each file individually. See src/core/xpcshell-appdir.ts for
+ * the full motivation.
+ */
+async function resolveDispatchGroups(engineDir, normalizedPaths) {
+    const scopes = await analyzeTestPathScopes(engineDir, normalizedPaths);
+    for (const scope of scopes) {
+        const notice = formatScopeNotice(scope);
+        if (notice)
+            info(notice);
+    }
+    logTestSelection(scopes);
+    return scopes.map((scope) => ({ label: scope.requestedPath, paths: scope.dispatchPaths }));
+}
+async function runTestCommandBody(projectRoot, testPaths, options = {}, profileEnv, hooks = {}) {
     const paths = getProjectPaths(projectRoot);
     // Check if engine exists
     await assertEngineExists(paths.engine);
@@ -281,7 +306,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}, profileE
     // against an incomplete build surface the missing-bundle path instead of a
     // cryptic `Browser process exited during spawn (exit code 1, signal none).
     // stderr tail: (empty)`.
-    const launchablePath = await resolveLaunchablePathForTests(paths.engine, projectConfig.binaryName, buildCheck.objDir);
+    const launchablePath = await resolveLaunchablePathForTests(projectRoot, paths.engine, projectConfig.binaryName, buildCheck.objDir);
     const harnessRetries = options.harnessRetries ?? DEFAULT_HARNESS_RETRIES;
     // Normalized engine-relative request paths, hoisted above the build/stale
     // gate: the pre-test build records them as the packaging-coverage claim,
@@ -304,7 +329,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}, profileE
     // mach.
     if (await runTestBuildPhase(projectRoot, paths, projectConfig, harnessRetries, options, {
         classification,
-        normalizedPaths,
+        normalizedPaths: hooks.coveragePaths ?? normalizedPaths,
     })) {
         return;
     }
@@ -324,31 +349,9 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}, profileE
     await assertTestPathsExist(paths.engine, normalizedPaths);
     const { suite, shuffleSeed, extraArgs } = prepareDispatchArguments(classification, options, canaryPath, projectConfig);
     appendMarionetteForwardingArgs(extraArgs, options, forwardedPort, xpcshellOnly);
-    // Directory arguments mean exactly that directory: mozbuild's test
-    // resolver matches paths by string prefix, so a bare directory arg
-    // silently sweeps in prefix-named siblings, with `…/test/hominis` also
-    // running `…/test/hominis-tiles`, with no indication the scope widened. Each
-    // directory argument therefore dispatches as its enumerated explicit
-    // test-file list, which cannot prefix-match a sibling. A trailing-`/`
-    // normalization does not work, as mach still sweeps the sibling in. Any
-    // prefix-siblings are echoed so the narrowed scope is visible.
     // Classification above intentionally used the raw argument forms. Only the
     // mach dispatch needs the exact-match shape.
-    const scopes = await analyzeTestPathScopes(paths.engine, normalizedPaths);
-    const dispatchGroups = scopes.map((scope) => ({
-        label: scope.requestedPath,
-        paths: scope.dispatchPaths,
-    }));
-    for (const scope of scopes) {
-        const notice = formatScopeNotice(scope);
-        if (notice)
-            info(notice);
-    }
-    // xpcshell appdir auto-injection happens per harness invocation inside
-    // `runTestsWithRetries` (src/commands/test-run.ts) so sharded runs probe
-    // the manifest for each file individually. See src/core/xpcshell-appdir.ts
-    // for the full motivation.
-    logTestSelection(scopes);
+    const dispatchGroups = await resolveDispatchGroups(paths.engine, normalizedPaths);
     const harnessEnv = mergeHarnessEnv(buildPerfSampleEnv(projectRoot, projectConfig.binaryName, options.perfSamples), profileEnv, shuffleSeed === undefined ? undefined : { FIREFORGE_SHUFFLE_SEED: String(shuffleSeed) });
     const runCtx = {
         engineDir: paths.engine,
@@ -365,6 +368,9 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}, profileE
     const postRebuildContext = options.build
         ? createPostRebuildFailureContext('fireforge test --build', normalizedPaths)
         : undefined;
+    // A negative control goes in here: after every gate and the build, so
+    // packaging cannot overwrite it and stale-build cannot refuse it.
+    await hooks.beforeDispatch?.();
     // Multi-argument requests shard into sequential harness runs by default:
     // one shared mochitest profile across files bleeds pref/media-query state
     // into later files. Sharding is per path argument: a directory argument
@@ -390,7 +396,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}, profileE
             // `FAIL reason=inconclusive` and throws, so an invalidated run can
             // never print `PASS shards=N/N` first. (A throw here masks an
             // in-flight shard error, as the plain assert always did.)
-            await verifyEngineGenerationOrEmitInconclusive(paths.engine, generationBefore, runCtx.powerChanged);
+            await verifyEngineGenerationOrEmitInconclusive(paths.engine, generationBefore, runCtx.powerChanged, options.perfSamples);
         }
         finalizeShardedOutcome(summary);
         return;
@@ -405,7 +411,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}, profileE
         throw new BuildError('Test process failed to start', 'mach test', error instanceof Error ? error : undefined);
     }
     finally {
-        await verifyEngineGenerationOrEmitInconclusive(paths.engine, generationBefore, runCtx.powerChanged);
+        await verifyEngineGenerationOrEmitInconclusive(paths.engine, generationBefore, runCtx.powerChanged, options.perfSamples);
     }
     if (canaryPath !== undefined) {
         reportCanaryOutcome(outcome);

package/dist/src/commands/token-lint.d.ts

@@ -0,0 +1,14 @@
+/** Options accepted by {@link tokenLintCommand}. */
+export interface TokenLintOptions {
+    /** Emit the machine-readable envelope instead of the human report. */
+    json?: boolean;
+}
+/**
+ * Runs `token lint`. Exits non-zero (GeneralError) when any finding is
+ * reported; with `--json` the report is written first, as `status --check
+ * --json` does.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param options - Output-mode options
+ */
+export declare function tokenLintCommand(projectRoot: string, options?: TokenLintOptions): Promise<void>;

package/dist/src/commands/token-lint.js

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge token lint`: themed-block lockstep and undeclared token
+ * references (see `core/token-lint.ts` for the rules).
+ *
+ * Helper module: no registrar, called from `token.ts`.
+ */
+import { join } from 'node:path';
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { furnaceConfigExists, loadFurnaceConfig } from '../core/furnace-config.js';
+import { loadPatchesManifest } from '../core/patch-manifest.js';
+import { collectDeclaredTokenNames, lintTokenLockstep, lintUndeclaredTokenReferences, } from '../core/token-lint.js';
+import { getTokensCssPath } from '../core/token-manager.js';
+import { GeneralError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
+import { pathExists, readText } from '../utils/fs.js';
+import { info, intro, outro, setMachineOutputMode, setStdoutSealed, success, warn, } from '../utils/logger.js';
+import { emitMachineError, MACHINE_OUTPUT_SCHEMA_VERSION } from '../utils/machine-output.js';
+/** Token prefix and exempt names from furnace.json, with the init default. */
+async function loadTokenSettings(projectRoot, binaryName) {
+    const fallback = { tokenPrefix: `--${binaryName}-`, exempt: new Set() };
+    if (!(await furnaceConfigExists(projectRoot)))
+        return fallback;
+    try {
+        const furnace = await loadFurnaceConfig(projectRoot);
+        return {
+            tokenPrefix: furnace.tokenPrefix ?? fallback.tokenPrefix,
+            exempt: new Set([...(furnace.tokenAllowlist ?? []), ...(furnace.runtimeVariables ?? [])]),
+        };
+    }
+    catch (error) {
+        warn(`Could not load furnace.json; using the default token prefix (${toError(error).message})`);
+        return fallback;
+    }
+}
+async function collectTokenLint(projectRoot) {
+    const paths = getProjectPaths(projectRoot);
+    const config = await loadConfig(projectRoot);
+    const tokensCssPath = getTokensCssPath(config.binaryName);
+    const tokensFile = join(paths.engine, tokensCssPath);
+    if (!(await pathExists(tokensFile))) {
+        throw new GeneralError(`Token CSS file not found: ${tokensCssPath}. Run "fireforge furnace init" to seed it.`);
+    }
+    const { tokenPrefix, exempt } = await loadTokenSettings(projectRoot, config.binaryName);
+    const tokensCss = await readText(tokensFile);
+    const lines = tokensCss.split('\n');
+    const declared = collectDeclaredTokenNames(lines);
+    const findings = [
+        ...lintTokenLockstep(lines, tokensCssPath, tokenPrefix),
+        ...lintUndeclaredTokenReferences(tokensCssPath, tokensCss, tokenPrefix, declared, exempt),
+    ];
+    // Every CSS file the patch queue touches: the fork's own stylesheets and
+    // the upstream ones it edits.
+    const manifest = await loadPatchesManifest(paths.patches);
+    const cssFiles = [
+        ...new Set((manifest?.patches ?? []).flatMap((patch) => patch.filesAffected.filter((file) => file.endsWith('.css') && file !== tokensCssPath))),
+    ].sort();
+    let filesScanned = 1;
+    for (const file of cssFiles) {
+        const absolute = join(paths.engine, file);
+        if (!(await pathExists(absolute)))
+            continue;
+        filesScanned++;
+        findings.push(...lintUndeclaredTokenReferences(file, await readText(absolute), tokenPrefix, declared, exempt));
+    }
+    return { tokensCssPath, tokenPrefix, filesScanned, findings };
+}
+function failureMessage(count) {
+    return `token lint found ${String(count)} finding(s).`;
+}
+/**
+ * Runs `token lint`. Exits non-zero (GeneralError) when any finding is
+ * reported; with `--json` the report is written first, as `status --check
+ * --json` does.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param options - Output-mode options
+ */
+export async function tokenLintCommand(projectRoot, options = {}) {
+    if (options.json === true) {
+        setMachineOutputMode(true);
+        let findings = 0;
+        try {
+            const report = await collectTokenLint(projectRoot);
+            findings = report.findings.length;
+            process.stdout.write(`${JSON.stringify({ schemaVersion: MACHINE_OUTPUT_SCHEMA_VERSION, ...report }, null, 2)}\n`);
+            setStdoutSealed(true);
+        }
+        catch (error) {
+            emitMachineError('token-lint-failed', toError(error).message);
+        }
+        finally {
+            setMachineOutputMode(false);
+        }
+        if (findings > 0)
+            throw new GeneralError(failureMessage(findings));
+        return;
+    }
+    intro('Token Lint');
+    const report = await collectTokenLint(projectRoot);
+    for (const finding of report.findings) {
+        warn(`${finding.file}:${String(finding.line)} [${finding.check}] ${finding.message}`);
+    }
+    info(`${String(report.filesScanned)} CSS file(s) scanned for ${report.tokenPrefix}* tokens`);
+    if (report.findings.length > 0) {
+        outro('Token lint failed');
+        throw new GeneralError(failureMessage(report.findings.length));
+    }
+    success('Themed blocks are in lockstep with the base block; every token reference resolves');
+    outro('Token lint passed');
+}

package/dist/src/commands/token.js

@@ -10,6 +10,7 @@ import { info, intro, outro, success, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 import { normalizeTokenName } from '../utils/validation.js';
 import { tokenCoverageCommand } from './token-coverage.js';
+import { tokenLintCommand } from './token-lint.js';
 import { tokenListCommand, tokenShowCommand } from './token-list.js';
 async function normalizeTokenNameForProject(projectRoot, rawTokenName) {
     if (rawTokenName.startsWith('--')) {
@@ -217,6 +218,15 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
         .action(withErrorHandling(async (tokenName, options) => {
         await tokenShowCommand(getProjectRoot(), tokenName, pickDefined({ json: options.json }));
     }));
+    token
+        .command('lint')
+        .description('Check the token system: themed override blocks declare only tokens the base :root ' +
+        'declares, and every var(--<prefix>…) in the tokens CSS or a patch-touched CSS file ' +
+        'names a declared token. Exits non-zero on any finding')
+        .option('--json', 'Emit the machine-readable envelope on stdout (see docs/machine-output.md)')
+        .action(withErrorHandling(async (options) => {
+        await tokenLintCommand(getProjectRoot(), pickDefined({ json: options.json }));
+    }));
     token
         .command('coverage')
         .description('Measure design token usage across modified CSS files')

package/dist/src/commands/verify-scope.d.ts

@@ -0,0 +1,28 @@
+import type { PatchLintIssue, PatchMetadata } from '../types/commands/index.js';
+/** The resolved scope: manifest filenames, and every path they claim. */
+export interface VerifyScope {
+    patches: ReadonlySet<string>;
+    files: ReadonlySet<string>;
+}
+/**
+ * Resolves raw `--patches` values against the manifest. Returns undefined
+ * when the flag was not given and refuses a name that matches no patch.
+ *
+ * @param patchesDir - Absolute path to the patches directory
+ * @param requested - Raw `--patches` values (each may be a comma list)
+ */
+export declare function resolveVerifyScope(patchesDir: string, requested: readonly string[] | undefined): Promise<VerifyScope | undefined>;
+/**
+ * True when a filename-keyed finding (manifest consistency, policy) is in
+ * scope: it names a scoped patch, or it names no patch at all.
+ */
+export declare function isFilenameInScope(scope: VerifyScope | undefined, filename: string): boolean;
+/** True when any of the implicated patches is in scope. */
+export declare function anyPatchInScope(scope: VerifyScope | undefined, filenames: readonly string[]): boolean;
+/**
+ * Keeps the lint issues that implicate a scoped patch. An issue without a
+ * `patches` list is attributed through its file instead.
+ */
+export declare function scopeLintIssues(issues: PatchLintIssue[], scope: VerifyScope | undefined): PatchLintIssue[];
+/** Keeps the manifest rows in scope. No scope keeps all. */
+export declare function scopePatches<T extends Pick<PatchMetadata, 'filename'>>(patches: readonly T[], scope: VerifyScope | undefined): T[];

package/dist/src/commands/verify-scope.js

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `verify --patches <list>`: judges only the named patches' findings. Split
+ * out of verify.ts so the per-group attribution rules sit in one place.
+ *
+ * A finding is in scope when it names a scoped patch: a manifest or policy
+ * issue by its filename, a cross-patch claim or lint issue by any patch it
+ * implicates, a drifted file by its owning patch, a dangling registration
+ * by the patch that registers it. Findings about the queue as a whole (a
+ * manifest that does not parse) are kept, because no patch can be judged
+ * past them. Unowned worktree changes belong to no patch and drop out.
+ */
+import { loadPatchesManifest } from '../core/patch-manifest.js';
+import { selectPatchSubset } from '../core/patch-subset.js';
+import { GeneralError } from '../errors/base.js';
+/**
+ * Resolves raw `--patches` values against the manifest. Returns undefined
+ * when the flag was not given and refuses a name that matches no patch.
+ *
+ * @param patchesDir - Absolute path to the patches directory
+ * @param requested - Raw `--patches` values (each may be a comma list)
+ */
+export async function resolveVerifyScope(patchesDir, requested) {
+    if (requested === undefined || requested.length === 0)
+        return undefined;
+    const manifest = await loadPatchesManifest(patchesDir);
+    if (!manifest || manifest.patches.length === 0) {
+        throw new GeneralError('--patches needs a patch queue, but patches.json lists no patches.');
+    }
+    const subset = selectPatchSubset(manifest, requested, '--patches selects patches (filename, stem, order number, manifest name, or slug).');
+    return {
+        patches: new Set(subset.map((patch) => patch.filename)),
+        files: new Set(subset.flatMap((patch) => patch.filesAffected)),
+    };
+}
+/**
+ * True when a filename-keyed finding (manifest consistency, policy) is in
+ * scope: it names a scoped patch, or it names no patch at all.
+ */
+export function isFilenameInScope(scope, filename) {
+    if (scope === undefined)
+        return true;
+    return scope.patches.has(filename) || !filename.endsWith('.patch');
+}
+/** True when any of the implicated patches is in scope. */
+export function anyPatchInScope(scope, filenames) {
+    if (scope === undefined)
+        return true;
+    return filenames.some((filename) => scope.patches.has(filename));
+}
+/**
+ * Keeps the lint issues that implicate a scoped patch. An issue without a
+ * `patches` list is attributed through its file instead.
+ */
+export function scopeLintIssues(issues, scope) {
+    if (scope === undefined)
+        return issues;
+    return issues.filter((issue) => issue.patches !== undefined && issue.patches.length > 0
+        ? anyPatchInScope(scope, issue.patches)
+        : scope.files.has(issue.file));
+}
+/** Keeps the manifest rows in scope. No scope keeps all. */
+export function scopePatches(patches, scope) {
+    if (scope === undefined)
+        return [...patches];
+    return patches.filter((patch) => scope.patches.has(patch.filename));
+}

package/dist/src/commands/verify.d.ts

@@ -15,6 +15,7 @@
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../types/cli.js';
+import { type VerifyScope } from './verify-scope.js';
 interface VerifyIssueGroup {
     title: string;
     issues: string[];
@@ -31,15 +32,22 @@ export interface PatchQueueHealth {
  * Collects the same queue-health findings reported by `fireforge verify`
  * without printing. Used by doctor recovery paths that need a read-only
  * "is this queue healthy?" decision before clearing stale state.
+ *
+ * @param projectRoot - Project root directory
+ * @param scope - `verify --patches`: keep only the findings that name these
+ *   patches (see verify-scope.ts). Omitted, every finding counts.
  */
-export declare function collectPatchQueueHealth(projectRoot: string): Promise<PatchQueueHealth>;
+export declare function collectPatchQueueHealth(projectRoot: string, scope?: VerifyScope): Promise<PatchQueueHealth>;
 /**
  * Runs the `verify` command: manifest consistency + cross-patch lint.
  * Read-only. Exits non-zero on any error-severity finding.
  *
  * @param projectRoot - Project root directory
+ * @param options - `patches`: the raw `--patches` values
  */
-export declare function verifyCommand(projectRoot: string): Promise<void>;
+export declare function verifyCommand(projectRoot: string, options?: {
+    patches?: string[];
+}): Promise<void>;
 /**
  * Registers the `verify` command on the CLI program.
  *