@hominis/fireforge 0.50.0 → 0.52.0

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

@@ -24,6 +24,16 @@ export const LINT_IGNORE_CEILING_RULES = [
     'large-patch-lines',
     'large-patch-files',
 ];
+/** The only rule whose findings carry a {@link PatchSizeShare}. */
+const SHARE_RULE = 'large-patch-lines';
+const SHARES = ['product', 'test'];
+/**
+ * The key a ceiling is stored under: the rule, plus `#<share>` for a
+ * share-scoped ceiling, so one rule can carry a ceiling per share.
+ */
+function ceilingKey(rule, share) {
+    return share === undefined ? rule : `${rule}#${share}`;
+}
 /** Narrows an entry to the ceiling form. */
 export function isLintIgnoreCeiling(entry) {
     return typeof entry !== 'string';
@@ -32,9 +42,19 @@ export function isLintIgnoreCeiling(entry) {
 export function lintIgnoreRule(entry) {
     return isLintIgnoreCeiling(entry) ? entry.rule : entry;
 }
-/** One-word rendering for summaries and dry runs: `file-too-large<=1200`. */
+/**
+ * One-word rendering for summaries and dry runs: `file-too-large<=1200`,
+ * `large-patch-lines[test]<=900`.
+ */
 export function formatLintIgnoreEntry(entry) {
-    return isLintIgnoreCeiling(entry) ? `${entry.rule}<=${String(entry.max)}` : entry;
+    if (!isLintIgnoreCeiling(entry))
+        return entry;
+    const share = entry.share === undefined ? '' : `[${entry.share}]`;
+    return `${entry.rule}${share}<=${String(entry.max)}`;
+}
+/** The identity an entry is upserted and deduplicated by. */
+function entryKey(entry) {
+    return isLintIgnoreCeiling(entry) ? ceilingKey(entry.rule, entry.share) : entry;
 }
 /** Renders a list for messages, `(empty)` when there is nothing to show. */
 export function formatLintIgnoreList(entries) {
@@ -43,7 +63,11 @@ export function formatLintIgnoreList(entries) {
 function sameEntry(a, b) {
     if (!isLintIgnoreCeiling(a) || !isLintIgnoreCeiling(b))
         return a === b;
-    return a.rule === b.rule && a.max === b.max && a.reason === b.reason;
+    return (a.rule === b.rule &&
+        a.max === b.max &&
+        a.reason === b.reason &&
+        a.share === b.share &&
+        JSON.stringify(a.meta) === JSON.stringify(b.meta));
 }
 /**
  * Validates a raw `lintIgnore` value from `patches.json`.
@@ -53,6 +77,9 @@ function sameEntry(a, b) {
  * integer `max` and a non-empty `reason`, and must be the only entry for
  * its rule: a bare ID beside a ceiling for the same rule would make the
  * ceiling dead, and two ceilings would leave the effective one ambiguous.
+ * The one exception is `large-patch-lines`, which may carry one ceiling
+ * per `share` instead of a single share-less one. `meta` must be a JSON
+ * object and is kept verbatim.
  *
  * @param raw - The value under `lintIgnore`
  * @param label - Field label for error messages, e.g. `patches[3].lintIgnore`
@@ -73,13 +100,21 @@ export function parseLintIgnoreEntries(raw, label) {
         }
         entries.push(parseCeiling(item, itemLabel));
     }
+    const sharedRules = new Set();
     for (const entry of entries) {
         if (!isLintIgnoreCeiling(entry))
             continue;
-        if (ceilingRules.has(entry.rule) || entries.includes(entry.rule)) {
-            throw new Error(`${label} names "${entry.rule}" more than once; keep a single entry (bare or ceiling) per rule`);
+        const key = ceilingKey(entry.rule, entry.share);
+        const clash = ceilingRules.has(key) ||
+            entries.includes(entry.rule) ||
+            (entry.share === undefined ? sharedRules.has(entry.rule) : ceilingRules.has(entry.rule));
+        if (clash) {
+            throw new Error(`${label} names "${entry.rule}" more than once; keep a single entry (bare or ceiling) ` +
+                'per rule, or one ceiling per share');
         }
-        ceilingRules.add(entry.rule);
+        ceilingRules.add(key);
+        if (entry.share !== undefined)
+            sharedRules.add(entry.rule);
     }
     return entries;
 }
@@ -88,11 +123,11 @@ function parseCeiling(item, label) {
         throw new Error(`${label} must be a check ID string or a { rule, max, reason } object`);
     }
     const record = item;
-    const unknownKeys = Object.keys(record).filter((key) => key !== 'rule' && key !== 'max' && key !== 'reason');
+    const unknownKeys = Object.keys(record).filter((key) => !CEILING_KEYS.has(key));
     if (unknownKeys.length > 0) {
         throw new Error(`${label} has unknown field(s): ${unknownKeys.join(', ')}`);
     }
-    const { rule, max, reason } = record;
+    const { rule, max, reason, share, meta } = record;
     if (typeof rule !== 'string' || !LINT_IGNORE_CEILING_RULES.includes(rule)) {
         throw new Error(`${label}.rule must be one of the measured size rules: ${LINT_IGNORE_CEILING_RULES.join(', ')}`);
     }
@@ -102,8 +137,22 @@ function parseCeiling(item, label) {
     if (typeof reason !== 'string' || reason.trim() === '') {
         throw new Error(`${label}.reason must be a non-empty string`);
     }
-    return { rule, max, reason };
+    const ceiling = { rule, max, reason };
+    if (share !== undefined) {
+        if (rule !== SHARE_RULE || !SHARES.includes(share)) {
+            throw new Error(`${label}.share must be "product" or "test", and only on ${SHARE_RULE}`);
+        }
+        ceiling.share = share;
+    }
+    if (meta !== undefined) {
+        if (meta === null || typeof meta !== 'object' || Array.isArray(meta)) {
+            throw new Error(`${label}.meta must be a JSON object`);
+        }
+        ceiling.meta = meta;
+    }
+    return ceiling;
 }
+const CEILING_KEYS = new Set(['rule', 'max', 'reason', 'share', 'meta']);
 /**
  * Builds the waiver filter for a patch's entries.
  *
@@ -117,7 +166,7 @@ export function buildLintIgnoreChecks(entries) {
     const ceilings = new Map();
     for (const entry of entries) {
         if (isLintIgnoreCeiling(entry))
-            ceilings.set(entry.rule, entry);
+            ceilings.set(ceilingKey(entry.rule, entry.share), entry);
         else
             plain.add(entry);
     }
@@ -138,38 +187,52 @@ export function lintIgnoreCacheTokens(checks) {
  * semantics `export` / `re-export --lint-ignore` have always had. A bare ID
  * whose rule already has an entry (bare or ceiling) is a no-op: widening a
  * reviewed ceiling to an unbounded waiver is `patch lint-ignore`'s job, where
- * it is confirmed explicitly.
+ * it is confirmed explicitly. Ceilings deduplicate by rule and share, so a
+ * rule's per-share ceilings all survive.
  *
  * @returns The merged list, or undefined when it is empty
  */
 export function mergeLintIgnoreIds(existing, ids) {
     const merged = [];
+    const keys = new Set();
     const rules = new Set();
     for (const entry of [...(existing ?? []), ...(ids ?? [])]) {
-        const rule = lintIgnoreRule(entry);
-        if (rules.has(rule))
+        const blocked = isLintIgnoreCeiling(entry) ? keys.has(entryKey(entry)) : rules.has(entry);
+        if (blocked)
             continue;
-        rules.add(rule);
+        keys.add(entryKey(entry));
+        rules.add(lintIgnoreRule(entry));
         merged.push(entry);
     }
     return merged.length > 0 ? merged : undefined;
 }
 /**
- * Adds or replaces entries by rule, the `patch lint-ignore --add` semantics:
- * an explicit `--add <rule>` turns a ceiling into a bare waiver, and
- * `--add <rule> --max <n>` sets or moves the ceiling.
+ * Adds or replaces entries, the `patch lint-ignore --add` semantics: an
+ * explicit `--add <rule>` turns a rule's ceilings into a bare waiver,
+ * `--add <rule> --max <n>` sets or moves the rule's ceiling, and a
+ * share-scoped ceiling replaces only its own share (plus any bare or
+ * share-less entry for the rule, which it would contradict).
  *
  * @returns The new list, or undefined when it is empty
  */
 export function upsertLintIgnoreEntries(existing, additions) {
-    const next = [...existing];
+    let next = [...existing];
     for (const addition of additions) {
         const rule = lintIgnoreRule(addition);
-        const index = next.findIndex((entry) => lintIgnoreRule(entry) === rule);
-        if (index === -1)
-            next.push(addition);
-        else
-            next[index] = addition;
+        const scoped = isLintIgnoreCeiling(addition) && addition.share !== undefined;
+        const replaced = (entry) => lintIgnoreRule(entry) === rule &&
+            (!scoped ||
+                !isLintIgnoreCeiling(entry) ||
+                entry.share === undefined ||
+                entryKey(entry) === entryKey(addition));
+        const index = next.findIndex(replaced);
+        const kept = next.filter((entry) => !replaced(entry));
+        // The addition takes the first replaced entry's place, so a moved
+        // ceiling keeps its position in the list.
+        next =
+            index === -1
+                ? [...kept, addition]
+                : [...kept.slice(0, index), addition, ...kept.slice(index)];
     }
     return mergeLintIgnoreIds(next, undefined);
 }
@@ -200,7 +263,7 @@ export function partitionLintIgnoredIssues(issues, checks) {
             suppressed.push(issue);
             continue;
         }
-        const ceiling = checks?.ceilings?.get(issue.check);
+        const ceiling = ceilingFor(issue, checks);
         if (ceiling === undefined) {
             kept.push(issue);
             continue;
@@ -209,12 +272,31 @@ export function partitionLintIgnoredIssues(issues, checks) {
             suppressed.push(issue);
             continue;
         }
+        // A notice never gates, so a ceiling does not bound it: one past `max`
+        // surfaces as the plain notice it is, not as an exceeded waiver.
+        if (issue.severity === 'notice') {
+            kept.push(issue);
+            continue;
+        }
         kept.push({ ...issue, message: `${issue.message} ${describeExceededCeiling(ceiling)}` });
     }
     return { kept, suppressed };
 }
+/** The ceiling that governs `issue`: its share's, else the rule's share-less one. */
+function ceilingFor(issue, checks) {
+    const ceilings = checks?.ceilings;
+    if (ceilings === undefined)
+        return undefined;
+    if (issue.share !== undefined) {
+        const scoped = ceilings.get(ceilingKey(issue.check, issue.share));
+        if (scoped !== undefined)
+            return scoped;
+    }
+    return ceilings.get(issue.check);
+}
 function describeExceededCeiling(ceiling) {
-    return (`This exceeds the patch's lintIgnore ceiling for ${ceiling.rule} ` +
+    const share = ceiling.share === undefined ? '' : ` (${ceiling.share} share)`;
+    return (`This exceeds the patch's lintIgnore ceiling for ${ceiling.rule}${share} ` +
         `(max ${String(ceiling.max)}: ${ceiling.reason}).`);
 }
 /** True when `checks` waives `issue` (see {@link partitionLintIgnoredIssues}). */
@@ -242,6 +324,31 @@ export function filterLintIgnoredByOwners(issues, owners) {
         return issues;
     return issues.filter((issue) => !(byFile.get(issue.file) ?? []).some((checks) => isLintIgnored(issue, checks)));
 }
+function judgeWaiver(rule, max, share, issues, patchMeasurements) {
+    const findings = issues.filter((issue) => issue.check === rule && (share === undefined || issue.share === share));
+    const measured = findings
+        .map((issue) => issue.measurement)
+        .filter((value) => value !== undefined);
+    // A share-scoped ceiling has no patch-level fallback: the total counts
+    // both shares, which is not what it bounds.
+    const fallback = share !== undefined
+        ? null
+        : rule === 'large-patch-lines'
+            ? patchMeasurements.lines
+            : rule === 'large-patch-files'
+                ? patchMeasurements.files
+                : null;
+    const measurement = measured.length > 0 ? Math.max(...measured) : fallback;
+    const gating = findings.filter((issue) => issue.severity !== 'notice');
+    const exceeded = max !== null &&
+        gating.some((issue) => issue.measurement !== undefined && issue.measurement > max);
+    const state = exceeded
+        ? 'exceeded'
+        : gating.length > 0
+            ? 'within'
+            : 'removable';
+    return { measurement, state };
+}
 /**
  * Evaluates each ceiling on a patch against the findings its lint produced
  * (both surfaced and suppressed).
@@ -257,26 +364,48 @@ export function evaluateLintIgnoreCeilings(entries, issues, patchMeasurements) {
     for (const entry of entries ?? []) {
         if (!isLintIgnoreCeiling(entry))
             continue;
-        const findings = issues.filter((issue) => issue.check === entry.rule);
-        const measured = findings
-            .map((issue) => issue.measurement)
-            .filter((value) => value !== undefined);
-        const fallback = entry.rule === 'large-patch-lines'
-            ? patchMeasurements.lines
-            : entry.rule === 'large-patch-files'
-                ? patchMeasurements.files
-                : null;
-        const measurement = measured.length > 0 ? Math.max(...measured) : fallback;
-        const gating = findings.some((issue) => issue.severity !== 'notice');
-        const state = measured.some((value) => value > entry.max)
-            ? 'exceeded'
-            : gating
-                ? 'within'
-                : 'removable';
-        statuses.push({ rule: entry.rule, max: entry.max, reason: entry.reason, measurement, state });
+        statuses.push({
+            rule: entry.rule,
+            max: entry.max,
+            reason: entry.reason,
+            ...(entry.share !== undefined ? { share: entry.share } : {}),
+            ...(entry.meta !== undefined ? { meta: entry.meta } : {}),
+            ...judgeWaiver(entry.rule, entry.max, entry.share, issues, patchMeasurements),
+        });
     }
     return statuses;
 }
+/**
+ * Evaluates every waiver on a patch, bare IDs included, so a waiver audit
+ * reads each one's current measurement from the report instead of
+ * re-measuring bare waivers from `suppressedIssues`.
+ *
+ * @param entries - The patch's `lintIgnore`
+ * @param issues - Every finding of the patch's lint, surfaced and suppressed
+ * @param patchMeasurements - See {@link evaluateLintIgnoreCeilings}
+ */
+export function evaluateLintIgnoreWaivers(entries, issues, patchMeasurements) {
+    return (entries ?? []).map((entry) => {
+        if (!isLintIgnoreCeiling(entry)) {
+            return {
+                kind: 'bare',
+                rule: entry,
+                max: null,
+                reason: null,
+                ...judgeWaiver(entry, null, undefined, issues, patchMeasurements),
+            };
+        }
+        return {
+            kind: 'ceiling',
+            rule: entry.rule,
+            max: entry.max,
+            reason: entry.reason,
+            ...(entry.share !== undefined ? { share: entry.share } : {}),
+            ...(entry.meta !== undefined ? { meta: entry.meta } : {}),
+            ...judgeWaiver(entry.rule, entry.max, entry.share, issues, patchMeasurements),
+        };
+    });
+}
 /**
  * Notice-severity findings for ceilings that are no longer needed, so the
  * waiver's removal is prompted by the tool that enforces it rather than
@@ -287,10 +416,11 @@ export function removableCeilingIssues(patchFilename, statuses) {
         .filter((status) => status.state === 'removable')
         .map((status) => {
         const now = status.measurement === null ? 'below its notice band' : `at ${String(status.measurement)}`;
+        const share = status.share === undefined ? '' : `, ${status.share} share`;
         return {
             file: patchFilename,
             check: 'lint-ignore-removable',
-            message: `lintIgnore ceiling for ${status.rule} (max ${String(status.max)}) is no longer needed: ` +
+            message: `lintIgnore ceiling for ${status.rule} (max ${String(status.max)}${share}) is no longer needed: ` +
                 `the measurement is ${now}, under the rule's own warning threshold. ` +
                 `Remove it with "fireforge patch lint-ignore ${patchFilename} --remove ${status.rule}".`,
             severity: 'notice',

package/dist/src/core/patch-lint-ownership.d.ts

@@ -51,6 +51,16 @@ export declare function resolvePatchOwnedChromeScripts(currentNewFiles: Set<stri
  * `patch-lint-ownership.test.ts`.
  */
 export declare function isTestScriptFile(file: string): boolean;
+/**
+ * For each test script, the ES modules (`.mjs`, `.sys.mjs`) the queue
+ * creates up to and including the test's own patch: what its imports can
+ * resolve to in a per-test checkJs program. A test no patch touches sees
+ * every module the queue creates.
+ *
+ * @param patchQueueCtx - The queue, in apply order
+ * @returns Lookup from a test script path to its resolvable modules
+ */
+export declare function resolvableModulesForTests(patchQueueCtx: PatchQueueContext): (testFile: string) => ReadonlySet<string>;
 /**
  * Returns the set of patch-owned test `.js` files. Same
  * ownership semantics as {@link resolvePatchOwnedSysMjs}. Consumed by the

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

@@ -84,6 +84,32 @@ export function isTestScriptFile(file) {
     const basename = file.split('/').pop() ?? '';
     return /^(?:browser_|test_|xpcshell_).*\.js$/.test(basename);
 }
+/**
+ * For each test script, the ES modules (`.mjs`, `.sys.mjs`) the queue
+ * creates up to and including the test's own patch: what its imports can
+ * resolve to in a per-test checkJs program. A test no patch touches sees
+ * every module the queue creates.
+ *
+ * @param patchQueueCtx - The queue, in apply order
+ * @returns Lookup from a test script path to its resolvable modules
+ */
+export function resolvableModulesForTests(patchQueueCtx) {
+    const byTest = new Map();
+    const upTo = new Set();
+    for (const entry of patchQueueCtx.entries) {
+        for (const file of entry.newFiles.keys()) {
+            if (file.endsWith('.mjs') && !isTestScriptFile(file))
+                upTo.add(file);
+        }
+        const snapshot = new Set(upTo);
+        for (const file of [...entry.newFiles.keys(), ...entry.modifiedFileAdditions.keys()]) {
+            if (isTestScriptFile(file) && !byTest.has(file))
+                byTest.set(file, snapshot);
+        }
+    }
+    const all = upTo;
+    return (testFile) => byTest.get(testFile) ?? all;
+}
 /**
  * Returns the set of patch-owned test `.js` files. Same
  * ownership semantics as {@link resolvePatchOwnedSysMjs}. Consumed by the

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

@@ -248,19 +248,26 @@ function formatPatchSizeMessage(subject, band, thresholds) {
  */
 function lineChecks(measurement, tier, thresholds, config) {
     const perClass = measurement.metric === 'addedCode' && tier === 'general';
-    if (!perClass || measurement.testLines === 0) {
+    if (!perClass) {
         return [{ count: measurement.lines, thresholds: thresholds.lines, scope: '' }];
     }
+    if (measurement.testLines === 0) {
+        return [
+            { count: measurement.lines, thresholds: thresholds.lines, scope: '', share: 'product' },
+        ];
+    }
     return [
         {
             count: measurement.lines - measurement.testLines,
             thresholds: thresholds.lines,
             scope: ' in non-test files',
+            share: 'product',
         },
         {
             count: measurement.testLines,
             thresholds: getPatchSizeThresholds('test', config).lines,
             scope: ' in test files (test tier)',
+            share: 'test',
         },
     ];
 }
@@ -317,6 +324,7 @@ export function lintPatchSize(filesAffected, measured, patchTier, config) {
             message: formatPatchSizeMessage(subject, band, check.thresholds),
             severity: band,
             measurement: check.count,
+            ...(check.share !== undefined ? { share: check.share } : {}),
         });
     }
     return issues;

package/dist/src/core/patch-lint-token-scale.d.ts

@@ -6,20 +6,29 @@
  * or referencing foreign custom properties, but say nothing about
  * `gap: 7px`, `font-size: 13px` or `z-index: 9999`. Those are the values a
  * design scale exists to remove, and without a rule they drift back one
- * literal at a time. A scale names its properties, the token prefix that
- * defines its steps, and the literals that are not steps at all (`0`,
- * `auto`, a percentage).
+ * literal at a time. A scale names its properties, the token prefix (or
+ * prefixes) that defines its steps, and the literals that are not steps at
+ * all (`0`, `auto`, a percentage).
  *
  * Judged per value atom, after peeling `var()` innermost-first so a fallback
  * is held to the same scale as the token it backs: `var(--x-gap, 7px)` is a
  * literal in disguise. `calc()`, `min()`, `max()` and `clamp()` are
  * transparent, so a value built from tokens passes and one that adds a raw
- * length does not. Unitless multipliers inside them are literals too and
- * need an `allowLiterals` entry.
+ * length does not. Inside them, `allowInCalc` names literals legal only
+ * there (a unitless multiplier), and `offsetCap` lets a declaration
+ * subtract a few px from a token (a border inset) without allowing the px
+ * value anywhere else.
+ *
+ * Declarations inside descriptor at-rules (`@font-face`, `@counter-style`,
+ * `@property`, `@page`, …) are not property declarations and are not
+ * judged: `font-weight` in `@font-face` names a face, not a type step.
  *
  * Runs over CSS files the patch creates, not files it modifies: an upstream
- * stylesheet is not the fork's to put on a scale. A line carrying
- * `fireforge-ignore: token-scale` is skipped.
+ * stylesheet is not the fork's to put on a scale. A file a scale `exclude`s
+ * is not judged against that scale. A line carrying
+ * `fireforge-ignore: token-scale` is skipped. A scale with `minFiles` also
+ * fails the queue (`token-scale-vacuous`) when fewer created files carry
+ * its properties, so an emptied scan set cannot pass by judging nothing.
  */
 import type { PatchLintIssue } from '../types/commands/index.js';
 import type { PatchLintTokenScale } from '../types/config.js';
@@ -31,9 +40,18 @@ export declare function findOffScaleAtom(value: string, scale: PatchLintTokenSca
 /**
  * Lints one patch-created CSS file against the configured scales.
  *
- * @param file - Engine-relative path, for the issue
+ * @param file - Engine-relative path, for the issue and the `exclude` globs
  * @param css - The file's full content
  * @param scales - `patchLint.tokenScales`
  * @returns One `token-scale` error per off-scale declaration
  */
 export declare function lintTokenScales(file: string, css: string, scales: readonly PatchLintTokenScale[]): PatchLintIssue[];
+/**
+ * The `minFiles` floor of every scale over the queue's created stylesheets:
+ * one `token-scale-vacuous` error per scale that fewer created CSS files
+ * (outside its `exclude`) carry a declaration of.
+ *
+ * @param createdFiles - Every patch-created file's path and content
+ * @param scales - `patchLint.tokenScales`
+ */
+export declare function lintTokenScaleFloors(createdFiles: Iterable<readonly [string, string]>, scales: readonly PatchLintTokenScale[]): PatchLintIssue[];