@hominis/fireforge 0.21.3 → 0.22.0

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

@@ -7,7 +7,7 @@ import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/g
 import { measureTokenCoverage } from '../core/token-coverage.js';
 import { getTokensCssPath } from '../core/token-manager.js';
 import { GeneralError } from '../errors/base.js';
-import { pathExists } from '../utils/fs.js';
+import { pathExists, readText } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
 /**
  * Measures design token coverage across modified CSS files.
@@ -31,6 +31,9 @@ export async function tokenCoverageCommand(projectRoot) {
     // and the file-extension filter could not see the .css inside.
     const rawStatus = await getWorkingTreeStatus(paths.engine);
     const expandedStatus = await expandUntrackedDirectoryEntries(paths.engine, rawStatus);
+    const statusTokenCssFiles = expandedStatus
+        .filter((f) => f.file === tokensCssPath)
+        .map((f) => f.file);
     const statusCssFiles = expandedStatus
         .filter((f) => f.file.endsWith('.css') && f.file !== tokensCssPath)
         .map((f) => f.file);
@@ -44,11 +47,27 @@ export async function tokenCoverageCommand(projectRoot) {
     // De-dupe so a file that is both a custom deploy target AND modified is
     // scanned exactly once.
     const cssFiles = [...new Set([...statusCssFiles, ...furnaceCssFiles])];
-    if (cssFiles.length === 0) {
+    const tokenSourceFiles = [...new Set(statusTokenCssFiles)];
+    if (cssFiles.length === 0 && tokenSourceFiles.length === 0) {
         info('No modified CSS files');
         outro('Nothing to measure');
         return;
     }
+    const tokenPrefix = await resolveTokenPrefix(projectRoot, config.binaryName);
+    const tokenSourceResults = await validateTokenSourceFiles(paths.engine, tokenSourceFiles, tokenPrefix);
+    for (const result of tokenSourceResults) {
+        const detail = `${result.tokenDeclarations} token declaration${result.tokenDeclarations === 1 ? '' : 's'}`;
+        if (result.unknownDeclarations.length === 0) {
+            success(`${result.file}  token source valid (${detail})`);
+        }
+        else {
+            warn(`${result.file}  token source has ${result.unknownDeclarations.length} declaration${result.unknownDeclarations.length === 1 ? '' : 's'} outside prefix ${tokenPrefix}: ${result.unknownDeclarations.join(', ')}`);
+        }
+    }
+    if (cssFiles.length === 0) {
+        outro(`${tokenSourceResults.length} token source file${tokenSourceResults.length === 1 ? '' : 's'} validated`);
+        return;
+    }
     const report = await measureTokenCoverage(paths.engine, cssFiles);
     // Per-file breakdown
     for (const entry of report.files) {
@@ -73,6 +92,46 @@ export async function tokenCoverageCommand(projectRoot) {
     }
     outro(`${report.filesScanned} CSS file${report.filesScanned === 1 ? '' : 's'} scanned`);
 }
+async function resolveTokenPrefix(projectRoot, binaryName) {
+    try {
+        const furnaceConfig = await loadFurnaceConfig(projectRoot);
+        if (furnaceConfig.tokenPrefix) {
+            return furnaceConfig.tokenPrefix;
+        }
+    }
+    catch {
+        // Fall through to the convention used by furnace init. A broken
+        // furnace.json is already surfaced by collectFurnaceCustomCssFiles.
+    }
+    return `--${binaryName}-`;
+}
+async function validateTokenSourceFiles(engineDir, tokenSourceFiles, tokenPrefix) {
+    const results = [];
+    for (const file of tokenSourceFiles) {
+        const filePath = join(engineDir, file);
+        if (!(await pathExists(filePath)))
+            continue;
+        const css = (await readText(filePath)).replace(/\/\*[\s\S]*?\*\//g, '');
+        const declarations = new Set();
+        const declarationPattern = /(^|[;{\s])(--[\w-]+)\s*:/g;
+        let match;
+        while ((match = declarationPattern.exec(css)) !== null) {
+            const declaration = match[2];
+            if (declaration)
+                declarations.add(declaration);
+        }
+        const tokenDeclarations = [...declarations].filter((name) => name.startsWith(tokenPrefix));
+        const unknownDeclarations = [...declarations]
+            .filter((name) => !name.startsWith(tokenPrefix))
+            .sort();
+        results.push({
+            file,
+            tokenDeclarations: tokenDeclarations.length,
+            unknownDeclarations,
+        });
+    }
+    return results;
+}
 /**
  * Returns engine-relative `.css` paths deployed by every Furnace custom
  * component registered in `furnace.json`. Only files that actually exist

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

@@ -15,6 +15,24 @@
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../types/cli.js';
+interface VerifyIssueGroup {
+    title: string;
+    issues: string[];
+    errorCount: number;
+    warningCount: number;
+}
+export interface PatchQueueHealth {
+    hasPatchesDirectory: boolean;
+    groups: VerifyIssueGroup[];
+    errorCount: number;
+    warningCount: number;
+}
+/**
+ * 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.
+ */
+export declare function collectPatchQueueHealth(projectRoot: string): Promise<PatchQueueHealth>;
 /**
  * Runs the `verify` command: manifest consistency + cross-patch lint.
  * Read-only; exits non-zero on any error-severity finding.
@@ -29,3 +47,4 @@ export declare function verifyCommand(projectRoot: string): Promise<void>;
  * @param context - Shared CLI registration context
  */
 export declare function registerVerify(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;
+export {};

package/dist/src/commands/verify.js

@@ -101,100 +101,129 @@ function detectCrossPatchFileClaims(manifestPatches) {
     return results;
 }
 /**
- * Runs the `verify` command: manifest consistency + cross-patch lint.
- * Read-only; exits non-zero on any error-severity finding.
- *
- * @param projectRoot - Project root directory
+ * 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.
  */
-export async function verifyCommand(projectRoot) {
-    intro('FireForge Verify');
+export async function collectPatchQueueHealth(projectRoot) {
     const paths = getProjectPaths(projectRoot);
     const config = await loadConfig(projectRoot);
     if (!(await pathExists(paths.patches))) {
-        info('No patches directory. Nothing to verify.');
-        outro('Verify clean');
-        return;
+        return {
+            hasPatchesDirectory: false,
+            groups: [],
+            errorCount: 0,
+            warningCount: 0,
+        };
     }
+    const groups = [];
     let errorCount = 0;
     let warningCount = 0;
-    // 1. Manifest consistency: orphan patch files, missing entries,
-    // files-affected mismatch, duplicate entries, unparseable manifest.
     const consistencyIssues = await validatePatchesManifestConsistency(paths.patches);
     if (consistencyIssues.length > 0) {
-        warn(`Manifest consistency issues (${consistencyIssues.length}):`);
-        for (const issue of consistencyIssues) {
-            warn(`  [${issue.code}] ${issue.message}`);
-            errorCount += 1;
-        }
+        const issues = consistencyIssues.map((issue) => `[${issue.code}] ${issue.message}`);
+        groups.push({
+            title: `Manifest consistency issues (${consistencyIssues.length})`,
+            issues,
+            errorCount: consistencyIssues.length,
+            warningCount: 0,
+        });
+        errorCount += consistencyIssues.length;
     }
-    // 2. Cross-patch file claims: two or more manifest entries listing the
-    // same path in filesAffected. Not caught by per-patch consistency.
     const manifest = await loadPatchesManifest(paths.patches);
     if (manifest) {
         const policyIssues = evaluatePatchPolicy(config, manifest);
         if (policyIssues.length > 0) {
-            warn(`Patch policy issues (${policyIssues.length}):`);
-            for (const issue of policyIssues) {
-                const label = issue.severity === 'error' ? 'ERROR' : 'WARN';
-                warn(`  ${label} [${issue.code}] ${issue.filename}: ${issue.message}`);
-                if (issue.severity === 'error')
-                    errorCount += 1;
-                else
-                    warningCount += 1;
-            }
+            const policyErrors = policyIssues.filter((issue) => issue.severity === 'error').length;
+            const policyWarnings = policyIssues.length - policyErrors;
+            groups.push({
+                title: `Patch policy issues (${policyIssues.length})`,
+                issues: policyIssues.map((issue) => {
+                    const label = issue.severity === 'error' ? 'ERROR' : 'WARN';
+                    return `${label} [${issue.code}] ${issue.filename}: ${issue.message}`;
+                }),
+                errorCount: policyErrors,
+                warningCount: policyWarnings,
+            });
+            errorCount += policyErrors;
+            warningCount += policyWarnings;
         }
         const crossClaims = detectCrossPatchFileClaims(manifest.patches);
         if (crossClaims.length > 0) {
-            warn(`Cross-patch filesAffected conflicts (${crossClaims.length}):`);
-            for (const claim of crossClaims) {
-                warn(`  ${claim.path}  claimed by: ${claim.filenames.join(', ')}`);
-                errorCount += 1;
-            }
+            groups.push({
+                title: `Cross-patch filesAffected conflicts (${crossClaims.length})`,
+                issues: crossClaims.map((claim) => `${claim.path}  claimed by: ${claim.filenames.join(', ')}`),
+                errorCount: crossClaims.length,
+                warningCount: 0,
+            });
+            errorCount += crossClaims.length;
         }
     }
-    // 3. Cross-patch lint: duplicate /dev/null creation + forward imports.
     const ctx = await buildPatchQueueContext(paths.patches);
     const lintIssues = lintPatchQueue(ctx);
     if (lintIssues.length > 0) {
-        warn(`Cross-patch lint issues (${lintIssues.length}):`);
-        for (const issue of lintIssues) {
-            const label = issue.severity === 'error' ? 'ERROR' : issue.severity === 'warning' ? 'WARN' : 'NOTICE';
-            warn(`  ${label} [${issue.check}] ${issue.file}: ${issue.message}`);
-            if (issue.severity === 'error')
-                errorCount += 1;
-            else if (issue.severity === 'warning')
-                warningCount += 1;
-        }
+        const lintErrors = lintIssues.filter((issue) => issue.severity === 'error').length;
+        const lintWarnings = lintIssues.filter((issue) => issue.severity === 'warning').length;
+        groups.push({
+            title: `Cross-patch lint issues (${lintIssues.length})`,
+            issues: lintIssues.map((issue) => {
+                const label = issue.severity === 'error' ? 'ERROR' : issue.severity === 'warning' ? 'WARN' : 'NOTICE';
+                return `${label} [${issue.check}] ${issue.file}: ${issue.message}`;
+            }),
+            errorCount: lintErrors,
+            warningCount: lintWarnings,
+        });
+        errorCount += lintErrors;
+        warningCount += lintWarnings;
     }
-    // 4. Registration-consequence consistency: walk each patch body and
-    // confirm that every widget / locale registration it adds has a
-    // corresponding file body covered by the patch queue OR present in
-    // the engine working tree. 2026-04-24 eval Finding 1: a patch
-    // produced by `export-all --exclude-furnace` referenced
-    // `toolkit/content/widgets/moz-qa-panel/*.mjs` via jar.mn /
-    // customElements.js edits, but the source files themselves were
-    // excluded from the patch. `verify` used to report "clean"; it now
-    // flags each dangling reference as a `dangling-registration` error
-    // naming the specific patch and target path.
     if (manifest) {
         const registrationIssues = await detectDanglingRegistrations(paths.patches, paths.engine, manifest.patches);
         if (registrationIssues.length > 0) {
-            warn(`Dangling registration references (${registrationIssues.length}):`);
-            for (const issue of registrationIssues) {
-                warn(`  ${issue.patchFilename}: registers ${issue.targetPath} via ${issue.source}, but no patch body or engine file supplies it`);
-                errorCount += 1;
-            }
+            groups.push({
+                title: `Dangling registration references (${registrationIssues.length})`,
+                issues: registrationIssues.map((issue) => `${issue.patchFilename}: registers ${issue.targetPath} via ${issue.source}, but no patch body or engine file supplies it`),
+                errorCount: registrationIssues.length,
+                warningCount: 0,
+            });
+            errorCount += registrationIssues.length;
+        }
+    }
+    return {
+        hasPatchesDirectory: true,
+        groups,
+        errorCount,
+        warningCount,
+    };
+}
+/**
+ * Runs the `verify` command: manifest consistency + cross-patch lint.
+ * Read-only; exits non-zero on any error-severity finding.
+ *
+ * @param projectRoot - Project root directory
+ */
+export async function verifyCommand(projectRoot) {
+    intro('FireForge Verify');
+    const health = await collectPatchQueueHealth(projectRoot);
+    if (!health.hasPatchesDirectory) {
+        info('No patches directory. Nothing to verify.');
+        outro('Verify clean');
+        return;
+    }
+    for (const group of health.groups) {
+        warn(`${group.title}:`);
+        for (const issue of group.issues) {
+            warn(`  ${issue}`);
         }
     }
-    if (errorCount === 0 && warningCount === 0) {
+    if (health.errorCount === 0 && health.warningCount === 0) {
         success('Patch queue is consistent.');
         outro('Verify clean');
         return;
     }
-    info(`\nVerify: ${errorCount} error(s), ${warningCount} warning(s)`);
-    if (errorCount > 0) {
+    info(`\nVerify: ${health.errorCount} error(s), ${health.warningCount} warning(s)`);
+    if (health.errorCount > 0) {
         outro('Verify failed');
-        throw new GeneralError(`fireforge verify found ${errorCount} error(s). Fix these before running export/import/rebase.`);
+        throw new GeneralError(`fireforge verify found ${health.errorCount} error(s). Fix these before running export/import/rebase.`);
     }
     outro('Verify passed with warnings');
 }

package/dist/src/core/patch-policy.d.ts

@@ -11,7 +11,7 @@ import type { FireForgeConfig } from '../types/config.js';
 /** Default patch filename contract used when a policy omits `filenamePattern`. */
 export declare const DEFAULT_PATCH_POLICY_FILENAME_PATTERN = "^(?<order>\\d{3})-(?<category>[a-z][a-z0-9-]*)-(?<slug>[a-z0-9-]+)\\.patch$";
 /** Stable issue codes returned by patch policy evaluation. */
-export type PatchPolicyIssueCode = 'filename-pattern' | 'filename-captures' | 'filename-metadata-mismatch' | 'category-range' | 'reserved-range' | 'reserved-documentation' | 'reserved-files' | 'description-required' | 'numeric-gap';
+export type PatchPolicyIssueCode = 'filename-pattern' | 'filename-captures' | 'filename-metadata-mismatch' | 'order-collision' | 'category-range' | 'reserved-range' | 'reserved-documentation' | 'reserved-files' | 'description-required' | 'numeric-gap';
 /** A single patch policy validation finding. */
 export interface PatchPolicyIssue {
     code: PatchPolicyIssueCode;

package/dist/src/core/patch-policy.js

@@ -260,6 +260,28 @@ function evaluateGaps(cfg, patches, severity) {
     }
     return issues;
 }
+function evaluateOrderCollisions(patches, severity) {
+    const byOrder = new Map();
+    for (const patch of patches) {
+        const matches = byOrder.get(patch.order) ?? [];
+        matches.push(patch);
+        byOrder.set(patch.order, matches);
+    }
+    const issues = [];
+    for (const [order, matches] of [...byOrder.entries()].sort((a, b) => a[0] - b[0])) {
+        if (matches.length <= 1)
+            continue;
+        const filenames = matches.map((patch) => patch.filename).sort((a, b) => a.localeCompare(b));
+        issues.push({
+            code: 'order-collision',
+            filename: String(order).padStart(3, '0'),
+            severity,
+            message: `patchPolicy requires unique numeric orders; order ${String(order).padStart(3, '0')} ` +
+                `is used by: ${filenames.join(', ')}.`,
+        });
+    }
+    return issues;
+}
 /** Evaluates an entire patch manifest against the configured policy. */
 export function evaluatePatchPolicy(config, manifest) {
     const cfg = policy(config);
@@ -267,6 +289,7 @@ export function evaluatePatchPolicy(config, manifest) {
         return [];
     const severity = issueSeverity(config);
     const issues = manifest.patches.flatMap((patch) => evaluatePatchMetadata(cfg, patch, severity));
+    issues.push(...evaluateOrderCollisions(manifest.patches, severity));
     issues.push(...evaluateGaps(cfg, manifest.patches, severity));
     return issues;
 }

package/dist/src/types/commands/options.d.ts

@@ -70,7 +70,7 @@ export interface ExportOptions {
      * be superseded and which files caused the coverage.
      */
     dryRun?: boolean;
-    /** Place the new patch at a specific ordinal, shifting subsequent patches. */
+    /** Place the new patch at this exact unused order without renumbering existing patches. */
     order?: number;
     /** Place the new patch immediately before the named patch. */
     before?: string;
@@ -552,6 +552,8 @@ export interface PatchCompactOptions {
     yes?: boolean;
     /** Print what would happen without writing anything. */
     dryRun?: boolean;
+    /** Bypass force-mode patchPolicy refusals. */
+    forceUnsafe?: boolean;
 }
 /**
  * Options for the status command.
@@ -584,6 +586,12 @@ export interface TokenAddOptions {
  */
 export interface DoctorOptions {
     repairPatchesManifest?: boolean;
+    /**
+     * Clear a stale `pendingResolution` marker, but only after the same
+     * read-only queue health checks used by `fireforge verify` report no
+     * error-severity findings.
+     */
+    clearResolution?: boolean;
     /**
      * Opt-in repair path for furnace-specific checks. When true, doctor will:
      * - clear stale `.fireforge/furnace-state.json` entries whose component is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.21.3",
+  "version": "0.22.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",