@hominis/fireforge 0.50.0 → 0.52.0

package/dist/src/core/test-run-completeness.js

@@ -18,10 +18,14 @@
  * `FAIL reason=test-failures`, and a short start count is stamped on the
  * verdict line as `started=<n>/<m> first-unstarted=<path>`.
  *
- * The start-count check only runs when at least one start marker names a
- * requested file. The suite-specific xpcshell dispatch can prove execution
- * with a result-summary block alone and print no `TEST_START` line, and a
- * run that never names its files cannot be counted against them.
+ * From streamed or captured text, the start-count check only runs when at
+ * least one start marker names a requested file. The suite-specific xpcshell
+ * dispatch can prove execution with a result-summary block alone and print
+ * no `TEST_START` line, and a run that never names its files cannot be
+ * counted against them. The structured raw log names every test by its
+ * manifest id, so a raw log whose starts name none of the requested files
+ * ran something else: a `--jobs` instance that read another instance's test
+ * list once passed on that instance's file.
  */
 import { SHUTDOWN_REENTRY_PATTERN, START_MARKER_PATTERN, TEST_FILE_BASENAME_PATTERN, } from './test-harness-crash.js';
 /**
@@ -33,38 +37,70 @@ const SKIP_MARKER_PATTERN = /\bTEST[-_]SKIP(?:PED)?\b[:| ]*\s*(\S+)?/;
 function basenameOf(path) {
     return path.slice(path.lastIndexOf('/') + 1);
 }
+/** Collects the start and skip marker names in `output`, line by line. */
+function scanStartMarkers(output) {
+    const markers = { started: [], skipped: [] };
+    for (const line of output.split(/\r?\n/))
+        recordMarkerLine(line, markers);
+    return markers;
+}
+function recordMarkerLine(line, markers) {
+    const start = START_MARKER_PATTERN.exec(line)?.[1];
+    if (start !== undefined) {
+        markers.started.push(start);
+        return;
+    }
+    const skip = SKIP_MARKER_PATTERN.exec(line)?.[1];
+    if (skip !== undefined)
+        markers.skipped.push(skip);
+}
+/** Creates a {@link StartMarkerTracker}. */
+export function createStartMarkerTracker() {
+    const collected = { started: [], skipped: [] };
+    const pending = { stdout: '', stderr: '' };
+    return {
+        onChunk(stream, chunk) {
+            const lines = `${pending[stream]}${chunk}`.split(/\r?\n/);
+            pending[stream] = lines.pop() ?? '';
+            for (const line of lines)
+                recordMarkerLine(line, collected);
+        },
+        markers() {
+            const tail = { started: [], skipped: [] };
+            recordMarkerLine(pending.stdout, tail);
+            recordMarkerLine(pending.stderr, tail);
+            return {
+                started: [...collected.started, ...tail.started],
+                skipped: [...collected.skipped, ...tail.skipped],
+            };
+        },
+    };
+}
 /**
  * Counts the requested test files that produced a start or skip marker.
  * Returns undefined when nothing can be counted: no test-file-shaped
  * request, or no start line that names any requested file.
  *
- * @param output - Captured mach stdout and stderr
+ * @param evidence - Captured mach stdout and stderr, or the markers
+ *   collected from the complete stream
  * @param requestedPaths - Dispatched paths, in dispatch order
+ * @param authoritative - The markers come from the raw log, so a run whose
+ *   starts name no requested file is counted (as none started) instead of
+ *   being left uncounted
  */
-export function countStartedFiles(output, requestedPaths) {
+export function countStartedFiles(evidence, requestedPaths, authoritative = false) {
     const requested = requestedPaths.filter((path) => TEST_FILE_BASENAME_PATTERN.test(basenameOf(path)));
     if (requested.length === 0)
         return undefined;
-    const started = [];
-    const skipped = [];
-    for (const line of output.split(/\r?\n/)) {
-        const start = START_MARKER_PATTERN.exec(line)?.[1];
-        if (start !== undefined) {
-            started.push(start);
-            continue;
-        }
-        const skip = SKIP_MARKER_PATTERN.exec(line)?.[1];
-        if (skip !== undefined)
-            skipped.push(skip);
-    }
+    const { started, skipped } = typeof evidence === 'string' ? scanStartMarkers(evidence) : evidence;
     const names = (path, list) => {
         const base = basenameOf(path);
         return list.some((name) => name.includes(base));
     };
     // Counting needs a dialect that names the requested files on its start
     // lines. When no start line names any of them, the output cannot be
-    // counted against the request at all.
-    if (!requested.some((path) => names(path, started)))
+    // counted against the request at all, unless it is the raw log.
+    if (!authoritative && !requested.some((path) => names(path, started)))
         return undefined;
     const unstarted = requested.filter((path) => !names(path, started) && !names(path, skipped));
     const firstUnstarted = unstarted[0];
@@ -82,15 +118,21 @@ export function countStartedFiles(output, requestedPaths) {
  * @param verdict - The classifier's verdict
  * @param output - Captured mach stdout and stderr
  * @param requestedPaths - Dispatched paths, in dispatch order
+ * @param tracked - Start markers collected from the complete stream (or
+ *   the structured raw log); without them the capped capture is scanned
  */
-export function vetoIncompletePass(verdict, output, requestedPaths) {
+export function vetoIncompletePass(verdict, output, requestedPaths, tracked) {
     if (verdict.kind !== 'tests-ran-ok')
         return verdict;
     const shutdownLine = output
         .split(/\r?\n/)
         .find((line) => SHUTDOWN_REENTRY_PATTERN.test(line))
         ?.trim();
-    const counted = countStartedFiles(output, requestedPaths);
+    // Tracked markers win whenever they saw a start line at all. An empty
+    // tracker means nothing was streamed through it, and the capture is then
+    // the only evidence there is.
+    const useTracked = tracked !== undefined && tracked.markers.started.length > 0;
+    const counted = countStartedFiles(useTracked ? tracked.markers : output, requestedPaths, useTracked && tracked.source === 'raw');
     const unexpected = verdict.unexpected ?? 0;
     const truncated = counted?.firstUnstarted !== undefined;
     if (unexpected === 0 && shutdownLine === undefined && !truncated)
@@ -98,7 +140,12 @@ export function vetoIncompletePass(verdict, output, requestedPaths) {
     const evidence = {
         started: counted?.started ?? 0,
         requested: counted?.requested ?? 0,
-        ...(counted?.firstUnstarted !== undefined ? { firstUnstarted: counted.firstUnstarted } : {}),
+        ...(counted?.firstUnstarted !== undefined
+            ? {
+                firstUnstarted: counted.firstUnstarted,
+                startedSource: useTracked ? tracked.source : 'capture',
+            }
+            : {}),
         ...(shutdownLine !== undefined ? { shutdownLine } : {}),
         ...(unexpected > 0 ? { unexpected } : {}),
     };

package/dist/src/core/test-stale-check.d.ts

@@ -1,4 +1,4 @@
-import type { BuildBaseline, TestPackagingCoverage } from './build-baseline-types.js';
+import type { BaselineRecorder, BuildBaseline, TestPackagingCoverage } from './build-baseline-types.js';
 import { type StaleExemption } from './test-stale-exempt.js';
 /** Result of the stale-build preflight probe. */
 export interface StaleBuildResult {
@@ -97,6 +97,15 @@ export interface CoverageRefusalDetail {
     changedInputs?: Readonly<Record<string, readonly string[]>>;
     /** The record carries a full build's anchor forward for unchanged paths. */
     carriesFullAnchor?: boolean;
+    /**
+     * Who wrote the record and when, so a run whose coverage a peer's scoped
+     * build replaced can tell whose build that was.
+     */
+    recordedBy?: string | undefined;
+    builtAt?: string | undefined;
+    recorder?: BaselineRecorder | undefined;
+    /** Whether the recorder's process is still running (it may still be using the packaging). */
+    recorderAlive?: boolean | undefined;
 }
 /**
  * Formats the refusal shown when a non-`--build` run requests paths the

package/dist/src/core/test-stale-check.js

@@ -163,6 +163,20 @@ export async function findChangedTestManifestsForPaths(engineDir, baseline, unco
     });
     return hits.slice(0, STALE_PATHS_LIMIT);
 }
+/** The refusal's sentence naming who wrote the coverage record. */
+function formatCoverageHolder(detail) {
+    if (detail.recorder === undefined && detail.recordedBy === undefined)
+        return '';
+    const what = detail.recordedBy !== undefined ? `"${detail.recordedBy}"` : 'a build';
+    const when = detail.builtAt !== undefined ? ` at ${detail.builtAt}` : '';
+    const recorder = detail.recorder;
+    const who = recorder === undefined
+        ? ''
+        : ` (pid ${recorder.pid}${detail.recorderAlive === true ? ', still running' : ''}` +
+            (recorder.sessionId !== undefined ? `, session ${recorder.sessionId}` : '') +
+            `, invocation ${recorder.invocationId})`;
+    return ` The current record was written by ${what}${when}${who}.`;
+}
 /**
  * Formats the refusal shown when a non-`--build` run requests paths the
  * packaged runtime's scoped `test --build` coverage does not include. It is
@@ -210,7 +224,7 @@ export function formatTestCoverageRefusal(uncovered, coverage, changedManifests
     return (`The packaged test runtime was produced by a scoped "fireforge test --build" covering only: ${scope}.\n` +
         `The requested run needs ${cap(uncovered)}, which that packaging does not cover — support ` +
         'fixtures for those manifests may be missing from obj-*/_tests/, and the run can hang ' +
-        `rather than fail.${affectedLine}${manifestLine} ${rebuildHint} ` +
+        `rather than fail.${formatCoverageHolder(detail)}${affectedLine}${manifestLine} ${rebuildHint} ` +
         '(--allow-stale-build does not bypass this check — it accepts stale content, not missing coverage.)');
 }
 /**

package/dist/src/core/test-xpcshell-retry.d.ts

@@ -22,6 +22,8 @@ export interface XpcshellRetryOptions {
     kind?: MachTestSuiteKind | undefined;
     /** Whether the run was started with full harness output. */
     fullOutput?: boolean | undefined;
+    /** Per-chunk feed for the retried run's output (start-marker tracking). */
+    onOutputChunk?: ((stream: 'stdout' | 'stderr', chunk: string) => void) | undefined;
 }
 /**
  * Removes a stale xpcshell install symlink and retries the focused mach test

package/dist/src/core/test-xpcshell-retry.js

@@ -9,7 +9,7 @@ import { tryRepairStaleXpcshellTestSymlink } from './test-stale-symlink.js';
  * generic command.
  */
 export async function retryAfterXpcshellSymlinkRepair(options) {
-    const { engineDir, objDir, result, classification, normalizedPaths, extraArgs, env, kind = 'test', fullOutput, } = options;
+    const { engineDir, objDir, result, classification, normalizedPaths, extraArgs, env, kind = 'test', fullOutput, onOutputChunk, } = options;
     if (result.exitCode !== 0 &&
         classification.xpcshell.length > 0 &&
         classification.nonXpcshell.length === 0) {
@@ -23,6 +23,7 @@ export async function retryAfterXpcshellSymlinkRepair(options) {
                 args: extraArgs,
                 env,
                 fullOutput,
+                ...(onOutputChunk === undefined ? {} : { teardown: { onOutputChunk } }),
             });
         }
     }

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

@@ -7,9 +7,12 @@
  *   every other theme resolves it to nothing.
  * - `token-undeclared`: a `var(--<prefix>…)` reference in the tokens CSS or
  *   in a CSS file the patch queue touches names a token no block of the
- *   tokens CSS declares. Same-file declarations, `furnace.json`
+ *   tokens CSS declares. Same-file declarations, declarations of a sheet
+ *   that loads beside it (see `token-sibling-sheets.ts`), `furnace.json`
  *   `tokenAllowlist` and `runtimeVariables` are exempt, matching the
- *   `token-prefix-violation` rule's notion of a runtime channel.
+ *   `token-prefix-violation` rule's notion of a runtime channel. A
+ *   reference with a fallback (`var(--x, 0)`) is optional by construction
+ *   (a host hook, a channel set from JS) and is not reported.
  *
  * Built on `token-category.ts`'s base-block and comment-mask primitives, so
  * this report and `token add` agree on which block is the base.

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

@@ -8,9 +8,12 @@
  *   every other theme resolves it to nothing.
  * - `token-undeclared`: a `var(--<prefix>…)` reference in the tokens CSS or
  *   in a CSS file the patch queue touches names a token no block of the
- *   tokens CSS declares. Same-file declarations, `furnace.json`
+ *   tokens CSS declares. Same-file declarations, declarations of a sheet
+ *   that loads beside it (see `token-sibling-sheets.ts`), `furnace.json`
  *   `tokenAllowlist` and `runtimeVariables` are exempt, matching the
- *   `token-prefix-violation` rule's notion of a runtime channel.
+ *   `token-prefix-violation` rule's notion of a runtime channel. A
+ *   reference with a fallback (`var(--x, 0)`) is optional by construction
+ *   (a host hook, a channel set from JS) and is not reported.
  *
  * Built on `token-category.ts`'s base-block and comment-mask primitives, so
  * this report and `token add` agree on which block is the base.
@@ -104,8 +107,10 @@ export function lintUndeclaredTokenReferences(file, css, tokenPrefix, declared,
     const findings = [];
     const seen = new Set();
     for (const [index, line] of maskCommentLines(lines).entries()) {
-        for (const match of line.matchAll(/var\(\s*(--[A-Za-z0-9_-]+)/g)) {
+        for (const match of line.matchAll(/var\(\s*(--[A-Za-z0-9_-]+)\s*(,)?/g)) {
             const name = match[1] ?? '';
+            if (match[2] !== undefined)
+                continue;
             if (!name.startsWith(tokenPrefix) || declared.has(name) || local.has(name))
                 continue;
             if (exempt.has(name) || seen.has(name))

package/dist/src/core/token-sibling-sheets.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Which stylesheets load together, so `token lint` can resolve a token one
+ * sheet references against the declarations of the sheets beside it.
+ *
+ * A widget sheet may read a token its host document's other sheet
+ * declares; judged alone it looks undeclared. Two sources say which sheets
+ * share a document:
+ *
+ * - links the queue's documents make: `<link rel="stylesheet">` (and
+ *   `<html:link>`) and `<?xml-stylesheet?>` in markup and Lit templates,
+ *   and CSS `@import`. A `chrome://` URL resolves through the jar.mn lines
+ *   the queue adds; a relative URL resolves beside the document, and only
+ *   to a sheet the queue touches.
+ * - `furnace.json#tokenSiblingSheets`: `{ "<glob>": ["<path or glob>"] }`,
+ *   for pairings no link in the queue shows (an upstream host document).
+ *
+ * Sheets linked from one document are siblings of each other; an
+ * `@import` makes the importing and the imported sheet siblings.
+ */
+/** The stylesheet URLs one document or sheet loads, in order. */
+export declare function collectStylesheetUrls(file: string, content: string): string[];
+/**
+ * Resolves a stylesheet URL to an engine-relative path, or undefined.
+ *
+ * @param url - The URL as written
+ * @param from - Engine-relative path of the document or sheet holding it
+ * @param jarTargets - jar target (`content/<pkg>/<path>`) → packaged source
+ * @param knownSheets - Sheets a relative URL may resolve to
+ */
+export declare function resolveStylesheetUrl(url: string, from: string, jarTargets: ReadonlyMap<string, string>, knownSheets: ReadonlySet<string>): string | undefined;
+/** Inputs of {@link buildSiblingSheetMap}. */
+export interface SiblingSheetInputs {
+    /** Documents and sheets to read links from: engine-relative path and content. */
+    documents: Iterable<readonly [string, string]>;
+    /** jar target → packaged source, from the queue's jar.mn lines. */
+    jarTargets: ReadonlyMap<string, string>;
+    /** The sheets `token lint` judges. */
+    sheets: readonly string[];
+    /** `furnace.json#tokenSiblingSheets`. */
+    explicit?: Readonly<Record<string, readonly string[]>> | undefined;
+}
+/**
+ * Maps each sheet to the other sheets that load beside it. A sheet with no
+ * siblings is absent.
+ */
+export declare function buildSiblingSheetMap(inputs: SiblingSheetInputs): Map<string, Set<string>>;

package/dist/src/core/token-sibling-sheets.js

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Which stylesheets load together, so `token lint` can resolve a token one
+ * sheet references against the declarations of the sheets beside it.
+ *
+ * A widget sheet may read a token its host document's other sheet
+ * declares; judged alone it looks undeclared. Two sources say which sheets
+ * share a document:
+ *
+ * - links the queue's documents make: `<link rel="stylesheet">` (and
+ *   `<html:link>`) and `<?xml-stylesheet?>` in markup and Lit templates,
+ *   and CSS `@import`. A `chrome://` URL resolves through the jar.mn lines
+ *   the queue adds; a relative URL resolves beside the document, and only
+ *   to a sheet the queue touches.
+ * - `furnace.json#tokenSiblingSheets`: `{ "<glob>": ["<path or glob>"] }`,
+ *   for pairings no link in the queue shows (an upstream host document).
+ *
+ * Sheets linked from one document are siblings of each other; an
+ * `@import` makes the importing and the imported sheet siblings.
+ */
+import { dirname, posix } from 'node:path';
+import { matchesAnyGlob } from '../utils/path-glob.js';
+import { normalizePathSlashes } from '../utils/paths.js';
+const LINK_TAG = /<(?:html:)?link\b[^>]*>/gi;
+const STYLESHEET_PI = /<\?xml-stylesheet\b[^?]*?href\s*=\s*["']([^"']+)["']/gi;
+const CSS_IMPORT = /@import\s+(?:url\(\s*)?["']([^"']+)["']/gi;
+/** The stylesheet URLs one document or sheet loads, in order. */
+export function collectStylesheetUrls(file, content) {
+    const urls = [];
+    if (file.endsWith('.css')) {
+        for (const match of content.matchAll(CSS_IMPORT))
+            urls.push(match[1] ?? '');
+        return urls.filter((url) => url !== '');
+    }
+    for (const match of content.matchAll(LINK_TAG)) {
+        const tag = match[0];
+        if (!/\brel\s*=\s*["']stylesheet["']/i.test(tag))
+            continue;
+        const href = /\bhref\s*=\s*["']([^"'$]+)["']/i.exec(tag)?.[1];
+        if (href !== undefined)
+            urls.push(href);
+    }
+    for (const match of content.matchAll(STYLESHEET_PI))
+        urls.push(match[1] ?? '');
+    return urls.filter((url) => url.endsWith('.css'));
+}
+/**
+ * Resolves a stylesheet URL to an engine-relative path, or undefined.
+ *
+ * @param url - The URL as written
+ * @param from - Engine-relative path of the document or sheet holding it
+ * @param jarTargets - jar target (`content/<pkg>/<path>`) → packaged source
+ * @param knownSheets - Sheets a relative URL may resolve to
+ */
+export function resolveStylesheetUrl(url, from, jarTargets, knownSheets) {
+    const chrome = /^chrome:\/\/([\w.-]+)\/(content|skin|locale)\/(.+)$/.exec(url);
+    if (chrome !== null) {
+        const [, pkg = '', kind = '', path = ''] = chrome;
+        const candidates = kind === 'skin'
+            ? [`skin/classic/${pkg}/${path}`, `skin/${pkg}/${path}`]
+            : [`${kind}/${pkg}/${path}`];
+        for (const target of candidates) {
+            const source = jarTargets.get(target);
+            if (source !== undefined)
+                return source;
+        }
+        return undefined;
+    }
+    if (/^[a-z][\w+.-]*:/i.test(url))
+        return undefined;
+    const base = normalizePathSlashes(dirname(from));
+    const resolved = posix.normalize(posix.join(base === '.' ? '' : base, url));
+    return knownSheets.has(resolved) ? resolved : undefined;
+}
+/**
+ * Maps each sheet to the other sheets that load beside it. A sheet with no
+ * siblings is absent.
+ */
+export function buildSiblingSheetMap(inputs) {
+    const known = new Set(inputs.sheets);
+    const siblings = new Map();
+    const link = (group) => {
+        for (const sheet of group) {
+            const set = siblings.get(sheet) ?? new Set();
+            for (const other of group)
+                if (other !== sheet)
+                    set.add(other);
+            if (set.size > 0)
+                siblings.set(sheet, set);
+        }
+    };
+    for (const [file, content] of inputs.documents) {
+        const linked = collectStylesheetUrls(file, content)
+            .map((url) => resolveStylesheetUrl(url, file, inputs.jarTargets, known))
+            .filter((sheet) => sheet !== undefined);
+        // An @import pairs the importing sheet with what it imports.
+        link(file.endsWith('.css') ? [file, ...linked] : linked);
+    }
+    for (const [pattern, partners] of Object.entries(inputs.explicit ?? {})) {
+        const owners = inputs.sheets.filter((sheet) => matchesAnyGlob(sheet, [pattern]));
+        for (const owner of owners) {
+            const set = siblings.get(owner) ?? new Set();
+            for (const partner of partners) {
+                if (/[*?]/.test(partner)) {
+                    for (const sheet of inputs.sheets) {
+                        if (sheet !== owner && matchesAnyGlob(sheet, [partner]))
+                            set.add(sheet);
+                    }
+                }
+                else if (partner !== owner) {
+                    set.add(partner);
+                }
+            }
+            if (set.size > 0)
+                siblings.set(owner, set);
+        }
+    }
+    return siblings;
+}

package/dist/src/core/tree-guard.js

@@ -36,6 +36,8 @@ export const TREE_COMMAND_VERDICTS = {
     export: 'conditional',
     'export-all': 'conditional',
     're-export': 'conditional',
+    // Parks live in the primary tree's .fireforge/ and rewrite engine files.
+    park: 'refused',
     patch: 'refused',
     rebase: 'refused',
     package: 'refused',

package/dist/src/core/typecheck-shim.d.ts

@@ -81,5 +81,10 @@ export interface ComposedShim {
  * @param projectRoot - Absolute project root, used to resolve the relative
  *   shim path
  * @param extraShimPath - Optional project-relative path to an extra `.d.ts`
+ * @param options - `litTypes` appends {@link LIT_TYPES_SHIM} after the
+ *   built-in shim (before the extra shim, which can still merge into it),
+ *   and {@link LOOSE_LIT_SHIM} otherwise
  */
-export declare function composeShimSource(projectRoot: string, extraShimPath: string | undefined): Promise<ComposedShim>;
+export declare function composeShimSource(projectRoot: string, extraShimPath: string | undefined, options?: {
+    litTypes?: boolean | undefined;
+}): Promise<ComposedShim>;

package/dist/src/core/typecheck-shim.js

@@ -289,6 +289,140 @@ export const UNDEFINED_IDENTIFIER_CODES = new Set([
     2304, // Cannot find name '{0}'.
     2552, // Cannot find name '{0}'. Did you mean '{1}'?
 ]);
+/**
+ * Typed Lit, opt-in through `typecheck.litTypes`. Declares the two chrome
+ * modules widgets import Lit from, so they no longer fall to the
+ * `chrome:*` wildcard as `any`: `LitElement` (with `ReactiveElement`'s
+ * lifecycle) and `MozLitElement` carry closed member lists, so a misspelt
+ * member of a widget host is TS2339, as `Cu` is in the built-in shim.
+ * Template helpers and directives stay loose. The global
+ * `MozLitElementWith<Extra>` types a widget's query getters and
+ * `static properties` members: the widget casts its `MozLitElement` import
+ * to it before extending ({@link LOOSE_LIT_SHIM} keeps it `any` without
+ * typed Lit). A project
+ * shim can merge members into `LitElementShimMembers`; a project whose
+ * jsconfig `paths`
+ * maps these URLs to the real sources gets those instead, since a resolved
+ * file wins over an ambient module.
+ */
+const LIT_TYPES_SHIM = `
+// ── FireForge typed Lit (typecheck.litTypes) ──
+interface LitPropertyDeclarationShim {
+  type?: unknown;
+  attribute?: boolean | string;
+  reflect?: boolean;
+  state?: boolean;
+  noAccessor?: boolean;
+  converter?: unknown;
+  hasChanged?(value: unknown, oldValue: unknown): boolean;
+  fluent?: boolean;
+}
+interface LitElementShimMembers {
+  readonly renderRoot: HTMLElement | DocumentFragment;
+  readonly isUpdatePending: boolean;
+  readonly hasUpdated: boolean;
+  readonly updateComplete: Promise<boolean>;
+  renderOptions: any;
+  requestUpdate(name?: PropertyKey, oldValue?: unknown, options?: LitPropertyDeclarationShim): void;
+  addController(controller: any): void;
+  removeController(controller: any): void;
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  attributeChangedCallback(name: string, oldValue: string | null, value: string | null): void;
+  createRenderRoot(): HTMLElement | DocumentFragment;
+  enableUpdating(requestedUpdate: boolean): void;
+  scheduleUpdate(): void | Promise<unknown>;
+  performUpdate(): void;
+  getUpdateComplete(): Promise<boolean>;
+  shouldUpdate(changedProperties: Map<PropertyKey, unknown>): boolean;
+  willUpdate(changedProperties: Map<PropertyKey, unknown>): void;
+  update(changedProperties: Map<PropertyKey, unknown>): void;
+  render(): unknown;
+  firstUpdated(changedProperties: Map<PropertyKey, unknown>): void;
+  updated(changedProperties: Map<PropertyKey, unknown>): void;
+}
+declare module 'chrome://global/content/vendor/lit.all.mjs' {
+  export class ReactiveElement extends HTMLElement {
+    static properties: Record<string, LitPropertyDeclarationShim>;
+    static styles: any;
+    static shadowRootOptions: ShadowRootInit;
+    static readonly observedAttributes: string[];
+    static createProperty(name: PropertyKey, options?: LitPropertyDeclarationShim): void;
+    static addInitializer(initializer: (element: ReactiveElement) => void): void;
+  }
+  export interface ReactiveElement extends LitElementShimMembers {}
+  export class LitElement extends ReactiveElement {}
+  export const html: (strings: TemplateStringsArray, ...values: unknown[]) => any;
+  export const svg: (strings: TemplateStringsArray, ...values: unknown[]) => any;
+  export const css: (strings: TemplateStringsArray, ...values: unknown[]) => any;
+  export const nothing: any;
+  export const noChange: any;
+  export const render: any;
+  export const unsafeCSS: any;
+  export const classMap: any;
+  export const styleMap: any;
+  export const ifDefined: any;
+  export const repeat: any;
+  export const when: any;
+  export const map: any;
+  export const live: any;
+  export const ref: any;
+  export const createRef: any;
+  export const until: any;
+  export const guard: any;
+  export const choose: any;
+  export const keyed: any;
+  export const cache: any;
+  export const join: any;
+  export const range: any;
+  export const unsafeHTML: any;
+  export const unsafeSVG: any;
+  export const literal: any;
+  export const unsafeStatic: any;
+  export const staticHtml: any;
+  export const staticSvg: any;
+  export const directive: any;
+  export const Directive: any;
+  export const AsyncDirective: any;
+  export const PartType: any;
+  export const defaultConverter: any;
+  export const notEqual: any;
+  export const adoptStyles: any;
+  export const supportsAdoptingStyleSheets: boolean;
+  export const CSSResult: any;
+  export const isServer: boolean;
+}
+declare module 'chrome://global/content/lit-utils.mjs' {
+  import { LitElement } from 'chrome://global/content/vendor/lit.all.mjs';
+  export class MozLitElement extends LitElement {
+    static queries: Record<string, string | Record<string, unknown>>;
+    static fragment: unknown;
+    dispatchOnUpdateComplete(event: Event): Promise<void>;
+  }
+  export const MozBaseInputElement: any;
+  export const MozBoolInputElement: any;
+  export const SelectControlBaseElement: any;
+  export const SelectControlItemMixin: any;
+}
+// MozLitElement with instance members Extra: what a widget casts its base
+// to for the getters static queries installs (and properties it declares
+// only in static properties). A class field would redefine a query getter
+// and throw, and a constructor declaration reads it before renderRoot.
+type MozLitElementWith<Extra> = Pick<
+  typeof import('chrome://global/content/lit-utils.mjs').MozLitElement,
+  keyof typeof import('chrome://global/content/lit-utils.mjs').MozLitElement
+> &
+  (new () => import('chrome://global/content/lit-utils.mjs').MozLitElement & Extra);
+`;
+/**
+ * Without typed Lit, `MozLitElementWith<Extra>` is `any`, as the base it
+ * casts is: the same widget source checks under per-patch checkJs and a
+ * project typecheck that leaves `litTypes` off.
+ */
+const LOOSE_LIT_SHIM = `
+// FireForge loose Lit (typecheck.litTypes off): see typecheck-shim.ts.
+type MozLitElementWith<Extra> = any;
+`;
 /** Hint appended to reported undefined-identifier diagnostics. */
 export const UNDEFINED_IDENTIFIER_HINT = '(undefined identifier — import or declare it, add the global to the extra shim, ' +
     'or tune the "undefinedIdentifiers" setting)';
@@ -350,9 +484,12 @@ async function inlineTripleSlashReferences(source, baseDir, seen) {
  * @param projectRoot - Absolute project root, used to resolve the relative
  *   shim path
  * @param extraShimPath - Optional project-relative path to an extra `.d.ts`
+ * @param options - `litTypes` appends {@link LIT_TYPES_SHIM} after the
+ *   built-in shim (before the extra shim, which can still merge into it),
+ *   and {@link LOOSE_LIT_SHIM} otherwise
  */
-export async function composeShimSource(projectRoot, extraShimPath) {
-    const base = FIREFOX_GLOBALS_SHIM;
+export async function composeShimSource(projectRoot, extraShimPath, options = {}) {
+    const base = `${FIREFOX_GLOBALS_SHIM}\n${options.litTypes === true ? LIT_TYPES_SHIM : LOOSE_LIT_SHIM}`;
     if (!extraShimPath) {
         return { source: base, extraShimAppended: false };
     }

package/dist/src/core/typecheck.js

@@ -102,7 +102,9 @@ export async function runTypecheck(projectRoot, cfg, runOptions = {}) {
         const cached = shimCache.get(key);
         if (cached !== undefined)
             return cached;
-        const composed = await composeShimSource(projectRoot, extraShim);
+        const composed = await composeShimSource(projectRoot, extraShim, {
+            litTypes: cfg.litTypes,
+        });
         if (composed.extraShimAppended) {
             verbose(`typecheck: extra shim ${extraShim ?? ''} appended to Firefox globals shim`);
         }

package/dist/src/index.d.ts

@@ -24,13 +24,19 @@ export { ensureFurnaceConfig, loadFurnaceConfig, loadFurnaceState, saveFurnaceSt
 export { validateAllComponents, validateComponent } from './core/furnace-validate.js';
 export type { PatchSizeThresholds, PatchSizeTierDecision } from './core/patch-lint.js';
 export { countNonBinaryDiffLines, filesMeasuredByFileTooLarge, getPatchSizeThresholds, isTestFile, resolvePatchSizeTier, } from './core/patch-lint.js';
-export type { CodeLineCount } from './core/patch-lint-code-lines.js';
-export { countCodeLines } from './core/patch-lint-code-lines.js';
+export type { CodeLineCount, CodeLineMask } from './core/patch-lint-code-lines.js';
+export { codeLineMask, countCodeLines } from './core/patch-lint-code-lines.js';
 export type { ResolvedFileSizeTier } from './core/patch-lint-file-size.js';
 export { resolveFileSizeThresholds } from './core/patch-lint-file-size.js';
+export type { PatchSizeMeasurement } from './core/patch-lint-size.js';
+export { measurePatchSize } from './core/patch-lint-size.js';
 export type { ResolvedPatchFilesTier } from './core/patch-lint-size-thresholds.js';
+export { isPatchSizeRegistrationFile } from './core/patch-lint-size-thresholds.js';
+export type { PatchPolicyIssue, PatchPolicyIssueCode } from './core/patch-policy.js';
+export { evaluatePatchPolicyContentForQueue } from './core/patch-policy-content.js';
 export type { AddTokenOptions, AddTokenResult, TokenMode } from './core/token-manager.js';
 export { addToken, getTokensCssPath, validateTokenAdd } from './core/token-manager.js';
 export { CancellationError, CommandError, FireForgeError, GeneralError, InvalidArgumentError, ResolutionError, } from './errors/base.js';
 export { ExitCode } from './errors/codes.js';
-export type { ApplyResult, BuildConfig, ComponentType, CustomComponentConfig, DryRunAction, FireForgeConfig, FirefoxConfig, FirefoxProduct, FurnaceConfig, FurnaceState, OverrideComponentConfig, OverrideType, PatchLintFileSizeThresholds, PatchLintFileSizeTier, ProjectLicense, StepError, ValidationIssue, WireConfig, } from './types/index.js';
+export type { PatchesManifest, PatchMetadata } from './types/commands/index.js';
+export type { ApplyResult, BuildConfig, ComponentType, CustomComponentConfig, DryRunAction, FireForgeConfig, FirefoxConfig, FirefoxProduct, FurnaceConfig, FurnaceState, OverrideComponentConfig, OverrideType, PatchLintFileSizeThresholds, PatchLintFileSizeTier, PatchLintPatchSizeMetric, ProjectLicense, StepError, ValidationIssue, WireConfig, } from './types/index.js';