@hominis/fireforge 0.15.5 → 0.15.7

package/dist/src/core/build-audit-platform.js

@@ -10,10 +10,23 @@
  * detection, the audit fires a "missing packaged artifact" warning for
  * every gated file on every off-platform build — pure noise.
  *
+ * Two gate sources are consulted, in order:
+ *   1. Python-style `if CONFIG[...]:` blocks in the owning `moz.build`.
+ *   2. Path-convention gates — certain directory fragments are packaged
+ *      by platform-specific Makefile.in / NSIS recipes that FireForge
+ *      does not parse, so a file living under `browser/installer/windows/`
+ *      or any `/stubinstaller/` subtree is Windows-only regardless of
+ *      what its nearest moz.build says. (The branding stubinstaller CSS
+ *      is the motivating case: referenced from
+ *      `browser/installer/windows/Makefile.in` / `nsis/stub.nsh` with no
+ *      `if CONFIG[…]:` in any moz.build ancestor.)
+ *
  * The detection is intentionally lightweight: we walk up from the
  * source file looking for the closest `moz.build`, scan it for an
  * occurrence of the source basename inside an `if CONFIG[...]:` block,
  * and check whether the gate expression matches the host platform.
+ * The path-convention pass kicks in only when no moz.build gate is
+ * found, so an explicit moz.build gate always wins.
  *
  * This is best-effort. False negatives (we miss a gate and warn anyway)
  * are tolerable — the audit is warn-only. False positives (we wrongly
@@ -128,9 +141,58 @@ export function findEnclosingGate(content, basename) {
     }
     return undefined;
 }
+/**
+ * Path-convention gates: directories whose files are packaged by
+ * platform-specific build recipes (NSIS stub installer, DMG creation,
+ * Linux installer scripts) that live outside the moz.build graph. A
+ * file under any of these fragments is platform-restricted regardless
+ * of what its nearest `moz.build` says.
+ *
+ * `stubinstaller/` is the Windows NSIS stub installer asset tree. It
+ * is referenced from `browser/installer/windows/Makefile.in` (via
+ * `FILES` / `_WIDGET_FILES` lists) and `nsis/stub.nsh`, never through
+ * an `if CONFIG[…]:` block an ancestor moz.build exposes. Without
+ * this path-level gate, the audit warns on every touched branding
+ * stubinstaller CSS on every non-Windows build.
+ */
+const PATH_GATES = [
+    { fragment: '/stubinstaller/', platform: 'win32', label: 'path convention: /stubinstaller/' },
+    {
+        fragment: '/browser/installer/windows/',
+        platform: 'win32',
+        label: 'path convention: browser/installer/windows/',
+    },
+    {
+        fragment: '/browser/installer/macosx/',
+        platform: 'darwin',
+        label: 'path convention: browser/installer/macosx/',
+    },
+    {
+        fragment: '/browser/installer/linux/',
+        platform: 'linux',
+        label: 'path convention: browser/installer/linux/',
+    },
+];
+/**
+ * Returns a path-convention gate for `sourcePath` when one applies.
+ * Leading slash added so `startsWith`-style prefix traps
+ * (`browser/installer/windows/…`) match whether or not the input
+ * starts with a separator.
+ */
+function findPathConventionGate(sourcePath) {
+    const normalised = `/${sourcePath}`.replace(/\/+/g, '/');
+    for (const entry of PATH_GATES) {
+        if (normalised.includes(entry.fragment)) {
+            return { platform: entry.platform, label: entry.label };
+        }
+    }
+    return undefined;
+}
 /**
  * Determines whether the given source file is gated off on the current
- * host by an enclosing `if CONFIG[...]:` block in its owning moz.build.
+ * host by an enclosing `if CONFIG[...]:` block in its owning moz.build,
+ * OR by a path-convention rule for installer-tree subdirectories that
+ * are packaged via Makefile.in recipes the audit does not parse.
  * Returns `gatedOff: false` and no expression when no gate is found —
  * the file is not platform-restricted, so the caller should audit it
  * normally.
@@ -140,31 +202,36 @@ export function findEnclosingGate(content, basename) {
  * @returns Detection result
  */
 export async function detectPlatformGate(engineDir, sourcePath) {
-    const sourceDir = dirname(join(engineDir, sourcePath));
-    const mozBuild = await findOwningMozBuild(engineDir, sourceDir);
-    if (!mozBuild)
-        return { gatedOff: false };
-    let content;
-    try {
-        content = await readText(mozBuild);
-    }
-    catch {
-        return { gatedOff: false };
-    }
-    const sourceBasename = sourcePath.split('/').pop() ?? '';
-    const expression = findEnclosingGate(content, sourceBasename);
-    if (!expression)
-        return { gatedOff: false };
     let host;
     try {
         host = getPlatform();
     }
     catch {
-        return { gatedOff: false };
+        host = undefined;
+    }
+    const sourceDir = dirname(join(engineDir, sourcePath));
+    const mozBuild = await findOwningMozBuild(engineDir, sourceDir);
+    if (mozBuild) {
+        let content;
+        try {
+            content = await readText(mozBuild);
+        }
+        catch {
+            content = '';
+        }
+        const sourceBasename = sourcePath.split('/').pop() ?? '';
+        const expression = findEnclosingGate(content, sourceBasename);
+        if (expression) {
+            if (host && isGateOffHost(expression, host)) {
+                return { gatedOff: true, gateExpression: expression };
+            }
+            return { gatedOff: false, gateExpression: expression };
+        }
     }
-    if (isGateOffHost(expression, host)) {
-        return { gatedOff: true, gateExpression: expression };
+    const pathGate = findPathConventionGate(sourcePath);
+    if (pathGate && host && host !== pathGate.platform) {
+        return { gatedOff: true, gateExpression: pathGate.label };
     }
-    return { gatedOff: false, gateExpression: expression };
+    return { gatedOff: false };
 }
 //# sourceMappingURL=build-audit-platform.js.map

package/dist/src/core/build-audit-registration.d.ts

@@ -0,0 +1,80 @@
+/** Parsed jar.mn registration anchored to a specific engine source path. */
+export interface RegistrationHit {
+    /** Target path extracted from the entry (POSIX). */
+    target: string;
+    /** Source path from the entry (POSIX, relative to the jar.mn directory). */
+    source: string;
+    /** Absolute path of the jar.mn that owns the registration. */
+    jarManifest: string;
+}
+/** Result of a registration-aware dist probe. */
+export interface RegistrationProbeResult {
+    /** Absolute path of the packaged artifact matching the registration target. */
+    artifact: string;
+    /** The registration entry that anchored the match. */
+    hit: RegistrationHit;
+}
+/**
+ * Parses a single jar.mn line into `{ target, source }` when the line is a
+ * content entry with an explicit `(source)` reference. Returns undefined
+ * for comments, headers (`browser.jar:`), `%` manifest directives, blank
+ * lines, and entries without a source reference.
+ *
+ * Accepted entry shapes:
+ *   `        content/browser/foo.js     (content/foo.js)`   bare
+ *   `*       content/browser/foo.js     (content/foo.js)`   `*` = preprocessed
+ *   `en-US.jar:        content/foo.js  (content/foo.js)`    locale-prefixed
+ */
+export declare function parseJarMnEntry(line: string): {
+    target: string;
+    source: string;
+} | undefined;
+/**
+ * Scans a jar.mn file's contents for an entry whose source reference
+ * matches `relativeSource` (POSIX, relative to the jar.mn directory).
+ * Returns the first match; jar.mn enforces uniqueness of `(source)` in
+ * practice, so a first-match wins behaviour is adequate.
+ */
+export declare function findJarMnEntryForSource(content: string, relativeSource: string): {
+    target: string;
+    source: string;
+} | undefined;
+/**
+ * Walks from the source's directory upward to the engine root, returning
+ * the first jar.mn entry that registers the given source. Returns undefined
+ * when no ancestor jar.mn claims the source.
+ *
+ * @param engineDir Absolute engine root; walk halts here.
+ * @param source Engine-relative POSIX source path.
+ */
+export declare function findRegisteredTarget(engineDir: string, source: string): Promise<RegistrationHit | undefined>;
+/**
+ * Probes the dist tree for the artifact registered against the given
+ * source. Returns the matched candidate and the registration hit that
+ * anchored it; undefined when the source has no owning jar.mn or when
+ * no same-basename candidate under the search roots ends with the
+ * registered target path.
+ *
+ * Suffix-matching against the target path is intentional: jar.mn targets
+ * are relative to the jar root (`browser.jar:`, `toolkit.jar:`), but the
+ * dist tree prefixes every entry with a jar-specific directory
+ * (`.../chrome/browser/content/browser/…`). The source basename plus the
+ * target suffix are unambiguous across every packaging convention we
+ * care about.
+ *
+ * @param engineDir Absolute engine root.
+ * @param source Engine-relative POSIX source path.
+ * @param searchRoots Absolute roots to probe (dist/, _tests/).
+ */
+export declare function resolveArtifactByRegistration(engineDir: string, source: string, searchRoots: readonly string[]): Promise<RegistrationProbeResult | undefined>;
+/**
+ * Returns the absolute paths of every same-basename candidate under the
+ * given search roots. Used by the audit to enumerate ALL false-match
+ * candidates when the heuristic fallback downgrades to "missing" — the
+ * operator needs to see the full set, not just the scorer's pick, to
+ * distinguish a registration bug from a genuine packaging drop.
+ *
+ * @param source Engine-relative POSIX source path.
+ * @param searchRoots Absolute roots to scan.
+ */
+export declare function collectSameBasenameCandidates(source: string, searchRoots: readonly string[]): Promise<string[]>;

package/dist/src/core/build-audit-registration.js

@@ -0,0 +1,187 @@
+// SPDX-License-Identifier: EUPL-1.2
+/*
+ * Registration-aware artifact resolution for the post-build dist-tree audit.
+ *
+ * The basename-plus-similarity heuristic in `build-audit-resolve.ts` cannot
+ * distinguish two unrelated files that share a source basename. Motivating
+ * case: one fork registers `content/mybrowser.js` in `browser/base/jar.mn`
+ * (packaged under `chrome/browser/content/browser/mybrowser.js`) while an
+ * unrelated patch registers a `mybrowser.js` pref file under
+ * `browser/defaults/preferences/`. The basename walker surfaces both
+ * candidates, `scoreCandidate` awards them an equal trailing-overlap score
+ * (basename only, no meaningful mid-path match), and whichever the
+ * directory walk hits first wins — frequently the wrong one.
+ *
+ * This module anchors resolution to the `(source)` reference inside
+ * `jar.mn`. For a source under audit we walk its ancestor directories for
+ * an owning `jar.mn`, find the entry whose `(source)` resolves to our
+ * path, and expose both the target path recorded in the entry and the
+ * manifest that owns it. Callers in `build-audit.ts` prefer candidates
+ * whose absolute dist-tree path ends with the registered target, and
+ * report an unambiguous "registered but not packaged" miss when no such
+ * candidate exists — rather than falling through to the heuristic which
+ * would pick an unrelated same-basename file.
+ *
+ * Fallback semantics: when no jar.mn registration is found, the caller
+ * is expected to use the similarity heuristic. Registration wins when it
+ * exists; the heuristic fills the gap for sources registered through
+ * moz.build (`FINAL_TARGET_FILES`, `JS_PREFERENCE_FILES`, etc.) or
+ * `package-manifest.in` entries, which this module intentionally does
+ * not parse — supporting every Firefox registration surface would bloat
+ * the audit, and the heuristic's remaining weak case (unrelated same-
+ * basename hits) is surfaced to the operator in the warning copy.
+ */
+import { basename, dirname, join, relative, sep } from 'node:path';
+import { pathExists, readText } from '../utils/fs.js';
+import { findAllByBasename } from './build-audit-resolve.js';
+/** Ceiling on ancestor-directory hops when searching for an owning jar.mn. */
+const MAX_JAR_MN_SCAN_DEPTH = 8;
+/**
+ * Parses a single jar.mn line into `{ target, source }` when the line is a
+ * content entry with an explicit `(source)` reference. Returns undefined
+ * for comments, headers (`browser.jar:`), `%` manifest directives, blank
+ * lines, and entries without a source reference.
+ *
+ * Accepted entry shapes:
+ *   `        content/browser/foo.js     (content/foo.js)`   bare
+ *   `*       content/browser/foo.js     (content/foo.js)`   `*` = preprocessed
+ *   `en-US.jar:        content/foo.js  (content/foo.js)`    locale-prefixed
+ */
+export function parseJarMnEntry(line) {
+    if (!line)
+        return undefined;
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('#') || trimmed.startsWith('%'))
+        return undefined;
+    // Leading `*` (preprocessed) and optional `locale.jar:` prefix are dropped
+    // before matching the target/(source) pair. Both are whitespace-separated
+    // from the target entry.
+    const stripped = trimmed.replace(/^\*\s+/, '').replace(/^[A-Za-z0-9.\-_]+\.jar:\s+/, '');
+    const match = /^(\S+)\s+\(([^)]+)\)\s*$/.exec(stripped);
+    if (!match)
+        return undefined;
+    const target = (match[1] ?? '').trim();
+    const source = (match[2] ?? '').trim();
+    if (!target || !source)
+        return undefined;
+    return { target, source };
+}
+/**
+ * Scans a jar.mn file's contents for an entry whose source reference
+ * matches `relativeSource` (POSIX, relative to the jar.mn directory).
+ * Returns the first match; jar.mn enforces uniqueness of `(source)` in
+ * practice, so a first-match wins behaviour is adequate.
+ */
+export function findJarMnEntryForSource(content, relativeSource) {
+    const normalized = relativeSource.replace(/\\/g, '/');
+    for (const line of content.split('\n')) {
+        const parsed = parseJarMnEntry(line);
+        if (!parsed)
+            continue;
+        if (parsed.source === normalized)
+            return parsed;
+    }
+    return undefined;
+}
+/**
+ * Walks from the source's directory upward to the engine root, returning
+ * the first jar.mn entry that registers the given source. Returns undefined
+ * when no ancestor jar.mn claims the source.
+ *
+ * @param engineDir Absolute engine root; walk halts here.
+ * @param source Engine-relative POSIX source path.
+ */
+export async function findRegisteredTarget(engineDir, source) {
+    const sourceAbs = join(engineDir, source);
+    const root = engineDir.replace(/[/\\]+$/, '');
+    let current = dirname(sourceAbs);
+    let depth = 0;
+    while (depth <= MAX_JAR_MN_SCAN_DEPTH &&
+        (current === root || current.startsWith(`${root}/`) || current.startsWith(`${root}\\`))) {
+        const jarMn = join(current, 'jar.mn');
+        if (await pathExists(jarMn)) {
+            let content;
+            try {
+                content = await readText(jarMn);
+            }
+            catch {
+                content = '';
+            }
+            const rel = relative(current, sourceAbs).split(sep).join('/');
+            const entry = findJarMnEntryForSource(content, rel);
+            if (entry) {
+                return { target: entry.target, source: entry.source, jarManifest: jarMn };
+            }
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+        depth += 1;
+    }
+    return undefined;
+}
+/**
+ * Normalises an absolute filesystem path to POSIX separators so the
+ * suffix comparison against a jar.mn target (always POSIX) is platform-
+ * independent.
+ */
+function toPosix(path) {
+    return path.split(sep).join('/');
+}
+/**
+ * Probes the dist tree for the artifact registered against the given
+ * source. Returns the matched candidate and the registration hit that
+ * anchored it; undefined when the source has no owning jar.mn or when
+ * no same-basename candidate under the search roots ends with the
+ * registered target path.
+ *
+ * Suffix-matching against the target path is intentional: jar.mn targets
+ * are relative to the jar root (`browser.jar:`, `toolkit.jar:`), but the
+ * dist tree prefixes every entry with a jar-specific directory
+ * (`.../chrome/browser/content/browser/…`). The source basename plus the
+ * target suffix are unambiguous across every packaging convention we
+ * care about.
+ *
+ * @param engineDir Absolute engine root.
+ * @param source Engine-relative POSIX source path.
+ * @param searchRoots Absolute roots to probe (dist/, _tests/).
+ */
+export async function resolveArtifactByRegistration(engineDir, source, searchRoots) {
+    const hit = await findRegisteredTarget(engineDir, source);
+    if (!hit)
+        return undefined;
+    const name = basename(source);
+    const targetSuffix = `/${hit.target.replace(/^\/+/, '')}`;
+    const candidates = [];
+    for (const root of searchRoots) {
+        const found = await findAllByBasename(root, name);
+        candidates.push(...found);
+    }
+    for (const candidate of candidates) {
+        if (toPosix(candidate).endsWith(targetSuffix)) {
+            return { artifact: candidate, hit };
+        }
+    }
+    return undefined;
+}
+/**
+ * Returns the absolute paths of every same-basename candidate under the
+ * given search roots. Used by the audit to enumerate ALL false-match
+ * candidates when the heuristic fallback downgrades to "missing" — the
+ * operator needs to see the full set, not just the scorer's pick, to
+ * distinguish a registration bug from a genuine packaging drop.
+ *
+ * @param source Engine-relative POSIX source path.
+ * @param searchRoots Absolute roots to scan.
+ */
+export async function collectSameBasenameCandidates(source, searchRoots) {
+    const name = basename(source);
+    const out = [];
+    for (const root of searchRoots) {
+        const found = await findAllByBasename(root, name);
+        out.push(...found);
+    }
+    return out;
+}
+//# sourceMappingURL=build-audit-registration.js.map

package/dist/src/core/build-audit-transforms.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Returns the expected chrome-tree suffix for an engine-relative POSIX
+ * source path when the path falls under a known transform prefix;
+ * undefined otherwise.
+ *
+ * @param source Engine-relative POSIX source path.
+ */
+export declare function expectedChromeSuffix(source: string): string | undefined;
+/**
+ * Probes the dist tree for the artifact implied by a known
+ * source→chrome transform. Returns the first absolute candidate whose
+ * POSIX path ends with the expected chrome suffix, or undefined when
+ * no transform applies or no candidate matches.
+ *
+ * The transform check is treated as high-confidence by `build-audit.ts`
+ * (callers pass `{ registered: true }` to `evaluateArtifactMtime`), so
+ * a match bypasses the structural-relation check that rejects generic
+ * basename collisions.
+ *
+ * @param source Engine-relative POSIX source path.
+ * @param searchRoots Absolute roots to probe (dist/, _tests/).
+ */
+export declare function resolveArtifactByKnownTransform(source: string, searchRoots: readonly string[]): Promise<string | undefined>;

package/dist/src/core/build-audit-transforms.js

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: EUPL-1.2
+/*
+ * Known source→packaging path transforms for the post-build dist-tree audit.
+ *
+ * Motivating case: a source at `engine/browser/base/content/foo.js` ships
+ * under `chrome/browser/content/browser/foo.js`. If an unrelated patch
+ * registers a different `foo.js` elsewhere in the tree (e.g. a pref file
+ * under `browser/defaults/preferences/foo.js`), the basename walker
+ * surfaces both candidates, `scoreCandidate` awards them an identical
+ * trailing-overlap score (basename only; every intermediate segment is
+ * in the generic list), and whichever the directory walk hits first wins.
+ * The heuristic then declares the chosen candidate "not structurally
+ * related" and reports the correctly-packaged chrome resource as missing.
+ *
+ * The transforms below anchor resolution to the well-known subtree→chrome
+ * conventions used by upstream mozilla-central jar.mn. When a source
+ * matches one of these prefixes, a candidate whose absolute path ends
+ * with the implied chrome suffix is treated as a confident match — the
+ * scorer never runs and the structural-relation check is bypassed.
+ *
+ * Scope is intentionally narrow: only subtrees whose packaging target is
+ * stable across every fork we know about. A fork that reroutes a known
+ * subtree can still win by adding `(source)` annotations in its own
+ * `jar.mn`, which `resolveArtifactByRegistration` consults first.
+ */
+import { basename, sep } from 'node:path';
+import { findAllByBasename } from './build-audit-resolve.js';
+/**
+ * Table of `prefix → chrome-suffix` transforms. Each rule names an
+ * engine-relative subtree prefix and produces the expected dist-tree
+ * suffix for a file under it. Rules are evaluated in array order and
+ * the first-matching prefix wins, so `toolkit/content/widgets/` must
+ * precede the looser `toolkit/content/`.
+ */
+const KNOWN_TRANSFORMS = [
+    {
+        prefix: 'browser/base/content/',
+        build: (rest) => `chrome/browser/content/browser/${rest}`,
+    },
+    {
+        prefix: 'toolkit/content/widgets/',
+        build: (rest) => `chrome/toolkit/content/global/elements/${rest}`,
+    },
+    {
+        prefix: 'toolkit/content/',
+        build: (rest) => `chrome/toolkit/content/global/${rest}`,
+    },
+];
+/**
+ * Returns the expected chrome-tree suffix for an engine-relative POSIX
+ * source path when the path falls under a known transform prefix;
+ * undefined otherwise.
+ *
+ * @param source Engine-relative POSIX source path.
+ */
+export function expectedChromeSuffix(source) {
+    for (const rule of KNOWN_TRANSFORMS) {
+        if (source.startsWith(rule.prefix)) {
+            return rule.build(source.slice(rule.prefix.length));
+        }
+    }
+    return undefined;
+}
+/**
+ * Probes the dist tree for the artifact implied by a known
+ * source→chrome transform. Returns the first absolute candidate whose
+ * POSIX path ends with the expected chrome suffix, or undefined when
+ * no transform applies or no candidate matches.
+ *
+ * The transform check is treated as high-confidence by `build-audit.ts`
+ * (callers pass `{ registered: true }` to `evaluateArtifactMtime`), so
+ * a match bypasses the structural-relation check that rejects generic
+ * basename collisions.
+ *
+ * @param source Engine-relative POSIX source path.
+ * @param searchRoots Absolute roots to probe (dist/, _tests/).
+ */
+export async function resolveArtifactByKnownTransform(source, searchRoots) {
+    const suffix = expectedChromeSuffix(source);
+    if (!suffix)
+        return undefined;
+    const name = basename(source);
+    const suffixWithSlash = `/${suffix}`;
+    for (const root of searchRoots) {
+        const candidates = await findAllByBasename(root, name);
+        for (const candidate of candidates) {
+            if (candidate.split(sep).join('/').endsWith(suffixWithSlash)) {
+                return candidate;
+            }
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=build-audit-transforms.js.map