@hominis/fireforge 0.30.1 → 0.32.0

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

@@ -1,17 +1,16 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { dirname, join } from 'node:path';
-import { toError } from '../utils/errors.js';
 import { pathExists, readText } from '../utils/fs.js';
-import { verbose } from '../utils/logger.js';
-import { hasRawCssColors, stripJsComments } from '../utils/regex.js';
-import { loadFurnaceConfig } from './furnace-config.js';
+import { stripJsComments } from '../utils/regex.js';
 import { containsUpstreamLicenseText, getLicenseHeader, hasAnyLicenseHeader, hasAnyLicenseHeaderAnyStyle, } from './license-headers.js';
 import { invokePatchLintCheckJs } from './patch-lint-checkjs.js';
 import { lintChromeScriptJsDocForFile } from './patch-lint-chrome-jsdoc.js';
+import { lintPatchedCss } from './patch-lint-css.js';
 import { detectNewFilesInDiff, extractAddedLinesPerFile } from './patch-lint-diff.js';
 import { AGGREGATE_PATCH_FILE } from './patch-lint-diff-tag.js';
 import { hasRelativeImport } from './patch-lint-imports.js';
 import { validateExportJsDoc } from './patch-lint-jsdoc.js';
+import { lintObserverTopics } from './patch-lint-observer.js';
 import { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs } from './patch-lint-ownership.js';
 // ---------------------------------------------------------------------------
 // Cross-patch lint re-exports
@@ -24,6 +23,10 @@ import { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs } from './patch
 // public surface from `patch-lint-reexports.ts` so callers continue to
 // import from a single module.
 export * from './patch-lint-reexports.js';
+// The CSS rule bodies live in `patch-lint-css.ts` (same per-file-budget
+// split as the other rule families); re-export the imported binding so
+// callers and tests keep importing `lintPatchedCss` from this module.
+export { lintPatchedCss };
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -205,139 +208,6 @@ export function commentStyleForFile(file) {
     return null;
 }
 // ---------------------------------------------------------------------------
-// CSS lint
-// ---------------------------------------------------------------------------
-/**
- * Lints patched CSS files for introduced raw color values and non-tokenized
- * custom properties.
- *
- * @param repoDir - Absolute path to the engine (repository) directory
- * @param affectedFiles - File paths (relative to repoDir) affected by the patch
- * @param diffContent - Optional unified diff used to scope raw color checks to introduced lines
- * @returns Array of lint issues found
- */
-export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config) {
-    const cssFiles = affectedFiles.filter((f) => f.endsWith('.css'));
-    if (cssFiles.length === 0)
-        return [];
-    // Load furnace config gracefully — skip token-prefix check if unavailable
-    let tokenPrefix;
-    let tokenAllowlist;
-    let runtimeVariables;
-    try {
-        const root = join(repoDir, '..');
-        const furnaceConfig = await loadFurnaceConfig(root);
-        if (furnaceConfig.tokenPrefix) {
-            tokenPrefix = furnaceConfig.tokenPrefix;
-            tokenAllowlist = new Set(furnaceConfig.tokenAllowlist ?? []);
-            runtimeVariables = new Set(furnaceConfig.runtimeVariables ?? []);
-        }
-    }
-    catch (error) {
-        verbose(`Skipping furnace token-prefix lint hints because furnace.json could not be loaded: ${toError(error).message}`);
-    }
-    const issues = [];
-    const addedLinesByFile = diffContent ? extractAddedLinesPerFile(diffContent) : undefined;
-    for (const file of cssFiles) {
-        const filePath = join(repoDir, file);
-        if (!(await pathExists(filePath)))
-            continue;
-        const rawCss = await readText(filePath);
-        // Strip block comments before scanning
-        const cssContent = rawCss.replace(/\/\*[\s\S]*?\*\//g, '');
-        // Check only introduced raw color values when diff context is available.
-        // Skip files on the raw-color allowlist (exact path or basename match) and
-        // auto-exempt files under `browser/branding/` — those are the fork's
-        // visual identity assets (app-about dialogs, installer pages, branded
-        // CSS copied from Firefox's `unofficial` template) and belong to the
-        // design-decision layer the design-token system does not govern.
-        // Without this auto-exemption, every first-time setup's copied CSS
-        // failed `raw-color-value` with no actionable fix other than manually
-        // listing each path in `rawColorAllowlist`.
-        const allowlist = config?.patchLint?.rawColorAllowlist;
-        const isAllowlisted = allowlist?.some((entry) => file === entry || file.endsWith('/' + entry));
-        const isBranding = file.startsWith('browser/branding/');
-        if (!isAllowlisted && !isBranding) {
-            // Strip lines with inline fireforge-ignore: raw-color-value suppression.
-            // Check against rawCss (before comment stripping) so the CSS comment marker is still present.
-            const sourceForSuppression = addedLinesByFile
-                ? (addedLinesByFile.get(file) ?? []).join('\n')
-                : rawCss;
-            const suppressedContent = sourceForSuppression
-                .split('\n')
-                .filter((line) => !line.includes('fireforge-ignore: raw-color-value'))
-                .join('\n')
-                .replace(/\/\*[\s\S]*?\*\//g, '');
-            if (hasRawCssColors(suppressedContent)) {
-                issues.push({
-                    file,
-                    check: 'raw-color-value',
-                    message: 'Raw color value found. Use CSS custom properties (var(--...)) for design token consistency.',
-                    severity: 'error',
-                });
-            }
-        }
-        // Check for non-tokenized custom properties. A variable that is both
-        // declared and consumed inside the same file is auto-exempted as a
-        // runtime state channel (see furnace.json → runtimeVariables).
-        //
-        // When diff context is available, scope the `var(...)` scan to
-        // added/modified lines only. `cssContent` (full-file) is still the
-        // source of `localDeclarations` so vars declared anywhere in the file
-        // are recognised as same-file refs regardless of where the consuming
-        // `var(...)` appears. Before this scoping change, a small edit to a
-        // Furnace override of a stock component (e.g. moz-card) produced a
-        // `token-prefix-violation` for every stock `var(--moz-card-*)` the
-        // upstream file already carried, because the scanner saw the full
-        // applied file and flagged each inherited reference as if the fork
-        // had introduced it.
-        if (tokenPrefix) {
-            const declarationPattern = /(?:^|[{;,\s])(--[\w-]+)\s*:/g;
-            const localDeclarations = new Set();
-            let declMatch;
-            while ((declMatch = declarationPattern.exec(cssContent)) !== null) {
-                const name = declMatch[1];
-                if (name)
-                    localDeclarations.add(name);
-            }
-            const prefixScanSource = addedLinesByFile
-                ? (addedLinesByFile.get(file) ?? []).join('\n').replace(/\/\*[\s\S]*?\*\//g, '')
-                : cssContent;
-            if (prefixScanSource.length > 0) {
-                const varPattern = /var\(\s*(--[\w-]+)/g;
-                const flaggedProps = new Set();
-                let match;
-                while ((match = varPattern.exec(prefixScanSource)) !== null) {
-                    const prop = match[1];
-                    if (!prop)
-                        continue;
-                    if (prop.startsWith(tokenPrefix))
-                        continue;
-                    if (tokenAllowlist?.has(prop))
-                        continue;
-                    if (runtimeVariables?.has(prop))
-                        continue;
-                    if (localDeclarations.has(prop))
-                        continue;
-                    // De-duplicate per (file, prop) pair so the same introduced var
-                    // used five times in the added hunk doesn't produce five
-                    // identical issue entries.
-                    if (flaggedProps.has(prop))
-                        continue;
-                    flaggedProps.add(prop);
-                    issues.push({
-                        file,
-                        check: 'token-prefix-violation',
-                        message: `CSS references var(${prop}) which does not match the required token prefix "${tokenPrefix}". Use a design token, add to tokenAllowlist, or (for runtime state channels) list the variable in runtimeVariables.`,
-                        severity: 'error',
-                    });
-                }
-            }
-        }
-    }
-    return issues;
-}
-// ---------------------------------------------------------------------------
 // License header lint
 // ---------------------------------------------------------------------------
 /**
@@ -503,23 +373,10 @@ export async function lintPatchedJs(repoDir, affectedFiles, newFiles, config, pa
                 });
             }
         }
-        // 4. Observer topic naming
-        const topicPattern = /(?:addObserver|removeObserver|notifyObservers)\s*\([^)\n]*["']([^"']+)["']/g;
-        let topicMatch;
-        while ((topicMatch = topicPattern.exec(strippedContent)) !== null) {
-            const topic = topicMatch[1];
-            if (!topic)
-                continue;
-            // Only flag topics that contain the binaryName but don't follow convention
-            if (topic.toLowerCase().includes(binaryName) && !/^[\w]+-[a-z]+-[a-z]+/.test(topic)) {
-                issues.push({
-                    file,
-                    check: 'observer-topic-naming',
-                    message: `Observer topic "${topic}" should follow "${binaryName}-<noun>-<verb>" naming convention.`,
-                    severity: 'warning',
-                });
-            }
-        }
+        // 4. Observer topic naming. Rule body lives in `patch-lint-observer.ts`:
+        // argument-position-aware, multi-line-safe, and allowlists Firefox-owned
+        // topics so simulated upstream notifications are not flagged.
+        issues.push(...lintObserverTopics(strippedContent, file, binaryName));
     }
     return issues;
 }
@@ -688,9 +545,6 @@ export async function lintModifiedFileHeaders(repoDir, affectedFiles, newFiles)
     }
     return issues;
 }
-// ---------------------------------------------------------------------------
-// Orchestrator
-// ---------------------------------------------------------------------------
 /**
  * Runs all patch lint checks and returns combined issues.
  *
@@ -710,9 +564,11 @@ export async function lintModifiedFileHeaders(repoDir, affectedFiles, newFiles)
  *   per-patch manifest context (re-export, per-patch lint) should
  *   pass this; aggregate-mode callers without a specific patch
  *   context skip it and fall through to auto-detection.
+ * @param options - Optional behaviour switches; see
+ *   {@link LintExportedPatchOptions}.
  * @returns Array of all lint issues found
  */
-export async function lintExportedPatch(repoDir, affectedFiles, diffContent, config, patchQueueCtx, ignoreChecks, patchTier) {
+export async function lintExportedPatch(repoDir, affectedFiles, diffContent, config, patchQueueCtx, ignoreChecks, patchTier, options) {
     const newFiles = detectNewFilesInDiff(diffContent);
     const { textLines: lineCount } = countNonBinaryDiffLines(diffContent);
     const patchOwnedFiles = resolvePatchOwnedSysMjs(newFiles, patchQueueCtx);
@@ -724,7 +580,9 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
         lintModifiedFileHeaders(repoDir, affectedFiles, newFiles),
     ]);
     const modCommentIssues = lintModificationComments(diffContent, config);
-    const sizeIssues = lintPatchSize(affectedFiles, lineCount, patchTier);
+    const sizeIssues = options?.skipPatchSize
+        ? []
+        : lintPatchSize(affectedFiles, lineCount, patchTier);
     const issues = [
         ...sizeIssues,
         ...cssIssues,
@@ -733,8 +591,13 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
         ...jsIssues,
         ...modCommentIssues,
     ];
-    if (config.patchLint?.checkJs) {
-        issues.push(...(await invokePatchLintCheckJs(repoDir, patchOwnedFiles, config.patchLint, dirname(repoDir))));
+    if (options?.precomputedCheckJs) {
+        // Per-patch lint built one queue-wide program and already attributed
+        // this patch's findings — append them instead of rebuilding the program.
+        issues.push(...options.precomputedCheckJs);
+    }
+    else if (config.patchLint?.checkJs) {
+        issues.push(...(await invokePatchLintCheckJs(repoDir, patchOwnedFiles, config.patchLint, dirname(repoDir), options?.checkJsReportScope)));
     }
     // Filter out ignored checks last so every rule still runs (keeps the
     // implementation uniform) but suppressed rules do not surface. We do not

package/dist/src/core/patch-manifest-io.d.ts

@@ -85,6 +85,22 @@ export interface PatchRenameEntry {
     /** New numeric order — must match the prefix of `newFilename`. */
     newOrder: number;
 }
+/**
+ * Rewrites `stagedDependencies.forwardImports[].owner` references on one
+ * patch through a rename lookup. Owners embed exact patch filenames, so any
+ * renumber (compact, reorder, placement export, rename) that does not remap
+ * them leaves dangling references that surface as false forward-import
+ * errors on the next lint.
+ *
+ * Pure and allocation-conservative: returns the input object unchanged when
+ * no owner matches the lookup, so callers can map whole manifests cheaply.
+ *
+ * @param patch - Manifest row to rewrite
+ * @param renameLookup - Maps an old patch filename to its new filename, or
+ *   undefined when the filename is not being renamed
+ * @returns The same row, or a copy with remapped owners
+ */
+export declare function rewriteStagedDependencyOwners(patch: PatchMetadata, renameLookup: (oldFilename: string) => string | undefined): PatchMetadata;
 /**
  * Renames patch files on disk and rewrites the corresponding manifest rows
  * atomically-ish: file renames use a two-phase staging strategy (rename each

package/dist/src/core/patch-manifest-io.js

@@ -167,6 +167,44 @@ export async function removePatchFromManifest(patchesDir, filename) {
     await savePatchesManifest(patchesDir, manifest);
     return true;
 }
+/**
+ * Rewrites `stagedDependencies.forwardImports[].owner` references on one
+ * patch through a rename lookup. Owners embed exact patch filenames, so any
+ * renumber (compact, reorder, placement export, rename) that does not remap
+ * them leaves dangling references that surface as false forward-import
+ * errors on the next lint.
+ *
+ * Pure and allocation-conservative: returns the input object unchanged when
+ * no owner matches the lookup, so callers can map whole manifests cheaply.
+ *
+ * @param patch - Manifest row to rewrite
+ * @param renameLookup - Maps an old patch filename to its new filename, or
+ *   undefined when the filename is not being renamed
+ * @returns The same row, or a copy with remapped owners
+ */
+export function rewriteStagedDependencyOwners(patch, renameLookup) {
+    const forwardImports = patch.stagedDependencies?.forwardImports;
+    if (!forwardImports || forwardImports.length === 0)
+        return patch;
+    const rewritten = forwardImports.map((fi) => {
+        if (!fi.owner)
+            return fi;
+        const newOwner = renameLookup(fi.owner);
+        if (newOwner === undefined || newOwner === fi.owner)
+            return fi;
+        return { ...fi, owner: newOwner };
+    });
+    const changed = rewritten.some((fi, index) => fi !== forwardImports[index]);
+    if (!changed)
+        return patch;
+    return {
+        ...patch,
+        stagedDependencies: {
+            ...patch.stagedDependencies,
+            forwardImports: rewritten,
+        },
+    };
+}
 /**
  * Renames patch files on disk and rewrites the corresponding manifest rows
  * atomically-ish: file renames use a two-phase staging strategy (rename each
@@ -300,12 +338,16 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
     for (const [oldFilename, entry] of renameMap) {
         filenameUpdates.set(oldFilename, entry);
     }
+    // Owner references live on *other* patches than the renamed ones, so every
+    // row is passed through the staged-dependency rewrite, not just renamed rows.
+    const ownerLookup = (oldFilename) => filenameUpdates.get(oldFilename)?.newFilename;
     const updatedPatches = manifest.patches.map((p) => {
         const update = filenameUpdates.get(p.filename);
+        const withOwners = rewriteStagedDependencyOwners(p, ownerLookup);
         if (!update)
-            return p;
+            return withOwners;
         return {
-            ...p,
+            ...withOwners,
             filename: update.newFilename,
             order: update.newOrder,
         };

package/dist/src/core/patch-manifest-validate.d.ts

@@ -1,14 +1,7 @@
 /**
  * Schema validation for patches.json manifest data.
  */
-import type { PatchCategory, PatchesManifest, PatchMetadata } from '../types/commands/index.js';
-/**
- * Validates a single patch metadata entry from raw data.
- * @param data - Raw data to validate
- * @param index - Array index for error messages
- * @returns Validated PatchMetadata
- */
-export declare function validatePatchMetadata(data: unknown, index: number): PatchMetadata;
+import type { PatchCategory, PatchesManifest } from '../types/commands/index.js';
 /** Validates raw patches.json data and returns the typed manifest shape. */
 export declare function validatePatchesManifest(data: unknown): PatchesManifest;
 /**

package/dist/src/core/patch-manifest-validate.js

@@ -39,7 +39,7 @@ function parseStagedDependencies(data, label) {
  * @param index - Array index for error messages
  * @returns Validated PatchMetadata
  */
-export function validatePatchMetadata(data, index) {
+function validatePatchMetadata(data, index) {
     const rec = parseObject(data, `patches[${index}]`);
     const filename = rec.string('filename');
     const name = rec.string('name');

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

@@ -5,7 +5,7 @@
  * is an implementation detail.
  */
 export { rebuildPatchesManifest, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';
-export { addPatchToManifest, loadPatchesManifest, mutatePatchRowsInManifest, PATCHES_MANIFEST, type PatchManifestRowMutation, type PatchManifestRowMutationResult, type PatchRenameEntry, removePatchFileAndManifest, renumberPatchesInManifest, savePatchesManifest, } from './patch-manifest-io.js';
+export { addPatchToManifest, loadPatchesManifest, mutatePatchRowsInManifest, PATCHES_MANIFEST, type PatchManifestRowMutation, type PatchManifestRowMutationResult, type PatchRenameEntry, removePatchFileAndManifest, renumberPatchesInManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from './patch-manifest-io.js';
 export { checkVersionCompatibility, findPatchesAffectingFile, getClaimedFiles, stampPatchVersions, validatePatchIntegrity, } from './patch-manifest-query.js';
 export { resolvePatchIdentifier } from './patch-manifest-resolve.js';
 export { validatePatchesManifest } from './patch-manifest-validate.js';

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

@@ -6,7 +6,7 @@
  * is an implementation detail.
  */
 export { rebuildPatchesManifest, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';
-export { addPatchToManifest, loadPatchesManifest, mutatePatchRowsInManifest, PATCHES_MANIFEST, removePatchFileAndManifest, renumberPatchesInManifest, savePatchesManifest, } from './patch-manifest-io.js';
+export { addPatchToManifest, loadPatchesManifest, mutatePatchRowsInManifest, PATCHES_MANIFEST, removePatchFileAndManifest, renumberPatchesInManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from './patch-manifest-io.js';
 export { checkVersionCompatibility, findPatchesAffectingFile, getClaimedFiles, stampPatchVersions, validatePatchIntegrity, } from './patch-manifest-query.js';
 export { resolvePatchIdentifier } from './patch-manifest-resolve.js';
 export { validatePatchesManifest } from './patch-manifest-validate.js';

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

@@ -8,8 +8,6 @@
  */
 import type { PatchesManifest, PatchMetadata } from '../types/commands/index.js';
 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' | 'order-collision' | 'category-range' | 'reserved-range' | 'reserved-documentation' | 'reserved-files' | 'description-required' | 'numeric-gap';
 /** A single patch policy validation finding. */
@@ -26,8 +24,6 @@ export interface PatchPolicyEnforcementInput {
     command: string;
     forceUnsafe?: boolean;
 }
-/** Returns true when the loaded config includes an opt-in patch policy. */
-export declare function hasPatchPolicy(config: FireForgeConfig): boolean;
 /** Returns valid categories for prompts and CLI validation under the config. */
 export declare function getPatchPolicyCategories(config: FireForgeConfig): string[];
 /** Checks whether a category is accepted by legacy defaults or the policy ranges. */

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

@@ -10,8 +10,9 @@
 import { InvalidArgumentError } from '../errors/base.js';
 import { warn } from '../utils/logger.js';
 import { PATCH_CATEGORIES } from '../utils/validation.js';
+import { rewriteStagedDependencyOwners } from './patch-manifest-io.js';
 /** Default patch filename contract used when a policy omits `filenamePattern`. */
-export const DEFAULT_PATCH_POLICY_FILENAME_PATTERN = '^(?<order>\\d{3})-(?<category>[a-z][a-z0-9-]*)-(?<slug>[a-z0-9-]+)\\.patch$';
+const DEFAULT_PATCH_POLICY_FILENAME_PATTERN = '^(?<order>\\d{3})-(?<category>[a-z][a-z0-9-]*)-(?<slug>[a-z0-9-]+)\\.patch$';
 function policy(config) {
     return config.patchPolicy;
 }
@@ -22,7 +23,7 @@ function issueSeverity(config) {
     return mutationMode(config) === 'warn' ? 'warning' : 'error';
 }
 /** Returns true when the loaded config includes an opt-in patch policy. */
-export function hasPatchPolicy(config) {
+function hasPatchPolicy(config) {
     return policy(config) !== undefined;
 }
 /** Returns valid categories for prompts and CLI validation under the config. */
@@ -305,12 +306,17 @@ export function buildProjectedManifest(current, patches) {
 }
 /** Applies a filename/order rename projection to a manifest without mutating it. */
 export function applyRenameMapToManifest(manifest, renameMap) {
+    const ownerLookup = (oldFilename) => renameMap.get(oldFilename)?.newFilename;
     return buildProjectedManifest(manifest, manifest.patches.map((patch) => {
+        // Staged-dependency owners reference other patches' filenames, so the
+        // projection rewrites them on every row to mirror what
+        // renumberPatchesInManifest persists.
+        const withOwners = rewriteStagedDependencyOwners(patch, ownerLookup);
         const rename = renameMap.get(patch.filename);
         if (!rename)
-            return patch;
+            return withOwners;
         return {
-            ...patch,
+            ...withOwners,
             filename: rename.newFilename,
             order: rename.newOrder,
         };

package/dist/src/core/register-browser-content.d.ts

@@ -1,7 +1,7 @@
 /**
  * JS/content registration in browser/base/jar.mn.
  */
-import type { RegisterResult } from './manifest-register.js';
+import type { RegisterResult } from './register-result.js';
 /**
  * Registers a JS/content file in browser/base/jar.mn.
  *

package/dist/src/core/register-module.d.ts

@@ -1,7 +1,7 @@
 /**
  * Module registration in browser/modules/{binaryName}/moz.build.
  */
-import type { RegisterResult } from './manifest-register.js';
+import type { RegisterResult } from './register-result.js';
 /**
  * Registers a module in browser/modules/{binaryName}/moz.build.
  *

package/dist/src/core/register-result.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared result shape for manifest registration operations, split out of
+ * the `manifest-register.ts` barrel so the `register-*` leaf modules can
+ * import it without importing the barrel that re-exports them — that
+ * type-only back-edge made the registration dependency graph cyclic.
+ */
+/**
+ * Result of a manifest registration operation.
+ */
+export interface RegisterResult {
+    /** The manifest file that was modified */
+    manifest: string;
+    /** The entry that was inserted */
+    entry: string;
+    /** The entry after which the new entry was inserted (for user display) */
+    previousEntry?: string | undefined;
+    /** Whether the entry already existed (skipped) */
+    skipped: boolean;
+    /** Whether --after target was not found and fell back to alphabetical */
+    afterFallback?: boolean | undefined;
+}

package/dist/src/core/register-result.js

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Shared result shape for manifest registration operations, split out of
+ * the `manifest-register.ts` barrel so the `register-*` leaf modules can
+ * import it without importing the barrel that re-exports them — that
+ * type-only back-edge made the registration dependency graph cyclic.
+ */
+export {};
+//# sourceMappingURL=register-result.js.map

package/dist/src/core/register-shared-css.d.ts

@@ -1,7 +1,7 @@
 /**
  * CSS registration in browser/themes/shared/jar.inc.mn.
  */
-import type { RegisterResult } from './manifest-register.js';
+import type { RegisterResult } from './register-result.js';
 /**
  * Measures the column at which the `(source)` parenthesis opens in
  * adjacent `skin/classic/browser/<x>.css (...)` entries inside an

package/dist/src/core/register-test-manifest.d.ts

@@ -1,7 +1,7 @@
 /**
  * Test manifest registration in browser/base/moz.build.
  */
-import type { RegisterResult } from './manifest-register.js';
+import type { RegisterResult } from './register-result.js';
 /**
  * Registers a test manifest (browser.toml) in browser/base/moz.build.
  *

package/dist/src/core/test-harness-crash.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Harness-crash classification for `fireforge test` (field reports C1/C2).
+ *
+ * The wrapped mach harness exhibits flaky non-test failures that an exit
+ * code (or a "did it print a summary" grep) cannot distinguish from real
+ * test results:
+ *
+ *  - startup crashes from the mozlog resource monitor on macOS
+ *    (`AttributeError: 'SystemResourceMonitor' object has no attribute
+ *    'poll_interval'`, `host_statistics64(HOST_VM_INFO64) syscall failed`,
+ *    `(ipc/mig) array not large enough` — a psutil/macOS mismatch) which
+ *    abort the run before any test executes;
+ *  - hangs after browser startup that die at the no-output timeout yet
+ *    still emit a `Passed: 0` summary;
+ *  - post-green shutdown re-entry, where a fully green run stalls on
+ *    "must wait for focus" and records "Application shut down (without
+ *    crashing) in the middle of a test!" as the only unexpected failure.
+ *
+ * Classification therefore keys on `TEST-START` presence — summary lines
+ * never count as proof that tests ran — and recognizes the crash shapes
+ * above so the command layer can retry them with a bounded budget instead
+ * of reporting phantom test failures (or phantom passes).
+ */
+/** How a completed harness run should be interpreted. */
+export type HarnessRunClassification = 'tests-ran-ok' | 'test-failures' | 'harness-crash' | 'no-tests';
+/** A recognized harness-crash shape with its evidence line. */
+export interface HarnessCrashSignature {
+    reason: string;
+    line: string;
+}
+/** Result of {@link classifyHarnessRun}. */
+export interface HarnessRunVerdict {
+    kind: HarnessRunClassification;
+    signature?: HarnessCrashSignature;
+}
+/**
+ * Detects the known harness-crash shapes in captured mach output.
+ * Returns undefined for anything that looks like a genuine test result.
+ */
+export declare function detectHarnessCrashSignature(output: string): HarnessCrashSignature | undefined;
+/**
+ * Classifies a completed harness run. The decision tree, in order:
+ *
+ * 1. A recognized crash signature wins regardless of exit code (the
+ *    shutdown re-entry shape exits non-zero on an otherwise green run;
+ *    the hang shape can even exit zero with a `Passed: 0` summary).
+ * 2. No `TEST-START` with explicit paths requested means no test ran —
+ *    `no-tests`, even when the exit code is zero. Summary lines are not
+ *    trusted as evidence of execution.
+ * 3. Exit code zero with tests started is a pass; anything else is a
+ *    test failure for the regular diagnosis chain.
+ */
+export declare function classifyHarnessRun(exitCode: number, output: string, requestedPaths: readonly string[]): HarnessRunVerdict;
+/** Builds the operator-facing failure message after retries are exhausted. */
+export declare function buildHarnessCrashMessage(signature: HarnessCrashSignature, attempts: number): string;
+/**
+ * Builds the message for a run that produced no `TEST-START` despite
+ * requesting paths — including exit-code-zero runs whose `Passed: 0`
+ * summary would otherwise read as a silent false green.
+ */
+export declare function buildNoTestsRanMessage(exitCode: number, requestedPaths: readonly string[]): string;