@hominis/fireforge 0.50.0 → 0.52.0

package/dist/src/index.js

@@ -22,8 +22,11 @@ export { applyAllComponents } from './core/furnace-apply.js';
 export { ensureFurnaceConfig, loadFurnaceConfig, loadFurnaceState, saveFurnaceState, validateFurnaceConfig, } from './core/furnace-config.js';
 export { validateAllComponents, validateComponent } from './core/furnace-validate.js';
 export { countNonBinaryDiffLines, filesMeasuredByFileTooLarge, getPatchSizeThresholds, isTestFile, resolvePatchSizeTier, } from './core/patch-lint.js';
-export { countCodeLines } from './core/patch-lint-code-lines.js';
+export { codeLineMask, countCodeLines } from './core/patch-lint-code-lines.js';
 export { resolveFileSizeThresholds } from './core/patch-lint-file-size.js';
+export { measurePatchSize } from './core/patch-lint-size.js';
+export { isPatchSizeRegistrationFile } from './core/patch-lint-size-thresholds.js';
+export { evaluatePatchPolicyContentForQueue } from './core/patch-policy-content.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';

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

@@ -1,6 +1,6 @@
 /**
  * Re-exports all command-related types from focused sub-modules.
  */
-export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceLockWaitable, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceRenameOptions, FurnaceSyncOptions, FurnaceValidateOptions, ImportOptions, LintCommandOptions, PackageOptions, PatchCompactOptions, PatchDeleteOptions, PatchLintIgnoreOptions, PatchMoveFilesOptions, PatchRenameOptions, PatchReorderOptions, PatchRetireOptions, PatchSplitOptions, PatchStagedDependencyOptions, PatchTierOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, SourceSetOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
-export type { ImportSummary, LintIgnoreCeiling, LintIgnoreEntry, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchLintStagedDeclaration, PatchMetadata, PatchResult, PatchRetiredSlot, PatchStagedDependencies, PatchStagedForwardImport, PatchStagedRegistration, } from './patches.js';
+export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceLockWaitable, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceRenameOptions, FurnaceSyncOptions, FurnaceValidateOptions, ImportOptions, LintCommandOptions, PackageOptions, PatchCompactOptions, PatchDeleteOptions, PatchLintIgnoreOptions, PatchMoveFilesOptions, PatchRenameOptions, PatchReorderOptions, PatchReserveOptions, PatchRetireOptions, PatchSplitOptions, PatchStagedDependencyOptions, PatchStageOptions, PatchTierOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, SourceSetOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
+export type { ImportSummary, LintIgnoreCeiling, LintIgnoreEntry, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchLintStagedDeclaration, PatchMetadata, PatchReservedSlot, PatchResult, PatchRetiredSlot, PatchSizeShare, PatchStagedDependencies, PatchStagedForwardImport, PatchStagedRegistration, } from './patches.js';
 export type { DoctorCheck, TokenCoverageFileEntry, TokenCoverageReport } from './project.js';

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

@@ -2,7 +2,7 @@
  * Command option types for CLI commands.
  */
 import type { FirefoxProduct, ProjectLicense } from '../config.js';
-import type { PatchCategory } from './patches.js';
+import type { PatchCategory, PatchSizeShare } from './patches.js';
 /**
  * `--dry-run`: print the planned change and exit without writing anything.
  *
@@ -334,8 +334,8 @@ export interface ReExportOptions extends EngineLockWaitable {
      * unmanaged files exist adjacent to the patch's ownership, instead of
      * warning. Gate-driven workflows use this so a freshly created file
      * beside a patch's owned files cannot be silently left out of the
-     * refreshed body. Only meaningful on the plain path, and mutually
-     * exclusive with `--scan` and `--files`, which set filesAffected
+     * refreshed body. Beside `--scan` it judges the neighbours the scan did
+     * not adopt. Mutually exclusive with `--files`, which sets filesAffected
      * explicitly.
      */
     refuseAdjacentUnmanaged?: boolean;
@@ -397,6 +397,23 @@ export interface ReExportOptions extends EngineLockWaitable {
      * back at HEAD.
      */
     expectRemoved?: string[];
+    /**
+     * Where a refused `--scan` adoption writes its one `--from`-ready
+     * declaration report (`--declarations-out`). Defaults to
+     * `.fireforge/declarations/`.
+     */
+    declarationsOut?: string;
+    /**
+     * `--hunks-from <diff>`: export each named file as the patch's current
+     * body plus only the hunks in this diff, leaving every other session's
+     * edits in the file out.
+     */
+    hunksFrom?: string;
+    /**
+     * `--exclude-hunks <diff>`: export each named file as the working tree
+     * minus the hunks in this diff.
+     */
+    excludeHunks?: string;
 }
 /**
  * Options for the `fireforge patch tier` subcommand. Sets or clears the
@@ -426,8 +443,15 @@ export interface PatchLintIgnoreOptions extends Confirmable, DryRunnable, PatchL
      * bare IDs. Only the measured size rules accept one. Requires `reason`.
      */
     max?: number;
-    /** Why the ceiling exists. Required with `max`. */
+    /** Why the ceiling exists. Required with `max` or a `<rule>=<max>` add. */
     reason?: string;
+    /** With a ceiling on `large-patch-lines`: the share it bounds. */
+    share?: PatchSizeShare;
+    /**
+     * Add every entry in a JSON file under one lock hold: an array of
+     * entries, or a lint report whose ceilings for the patch are rebaselined.
+     */
+    from?: string;
 }
 /**
  * Options for the `fireforge patch staged-dependency` subcommand. Modes are
@@ -490,6 +514,8 @@ export interface PatchSplitOptions extends Confirmable, PatchLockWaitable, Unsaf
     dryRun?: boolean;
     /** Skip per-patch lint of the projected bodies. */
     skipLint?: boolean;
+    /** Where a refusal writes its one `--from`-ready declaration report. */
+    declarationsOut?: string;
 }
 /**
  * Options for the `fireforge patch move-files` subcommand. Without
@@ -513,6 +539,8 @@ export interface PatchMoveFilesOptions extends Confirmable, PatchLockWaitable, U
     dryRun?: boolean;
     /** Skip per-patch lint of the projected bodies. */
     skipLint?: boolean;
+    /** Where a refusal writes its one `--from`-ready declaration report. */
+    declarationsOut?: string;
 }
 /**
  * Options for the rebase command.
@@ -650,11 +678,12 @@ export interface TestOptions extends EngineLockWaitable {
      */
     refuseUnexportedDrift?: boolean;
     /**
-     * `false` under `--no-furnace-apply`: the pre-test build skips the Furnace
-     * apply and packages engine/ as it stands. Valid only with
+     * Which components the pre-test build deploys: `all` (default), `reached`
+     * (only those a requested test reaches) or `none`. `false` is
+     * `--no-furnace-apply`, the same as `none`. Valid only with
      * `--build`/`--build-only`.
      */
-    furnaceApply?: boolean;
+    furnaceApply?: boolean | 'all' | 'reached' | 'none';
     /** Forward mach's pathless auto-selection mode. Valid only with no explicit paths. */
     auto?: boolean;
     /**
@@ -768,6 +797,17 @@ export interface TestOptions extends EngineLockWaitable {
      * engine harness's busy-port fallback. Same as `test.mochitestPorts: "auto"`.
      */
     autoPorts?: boolean;
+    /**
+     * Hold the engine session lock shared for a build-less run with auto
+     * ports, so peers' build-less runs overlap. Same as `test.lockMode: "shared"`.
+     */
+    sharedLock?: boolean;
+    /** Run shards on this many harness instances at once (requires auto ports). */
+    jobs?: number;
+    /** Dispatch n files per mach invocation, judged per file from the raw log. */
+    shardSize?: number;
+    /** Write per-file results (mozlog raw log) as JSON to this path. */
+    results?: string;
 }
 /**
  * Options for the furnace apply command.
@@ -984,6 +1024,8 @@ export interface RegisterOptions {
 export interface PatchDeleteOptions extends Confirmable, DryRunnable, PatchLockWaitable {
     /** Bypass the hard refusal when later patches depend on the target. */
     forceUnsafe?: boolean;
+    /** Also delete the engine files the patch creates that are still on disk. */
+    deleteCreated?: boolean;
 }
 /**
  * Options for the `fireforge patch retire` subcommand: `patch delete` that
@@ -993,6 +1035,25 @@ export interface PatchRetireOptions extends PatchDeleteOptions {
     /** Optional human-readable rationale stored on the retired slot. */
     reason?: string;
 }
+/**
+ * Options for the `fireforge patch stage` subcommand: stage the named
+ * patches' files and only their `patches.json` rows in the project index.
+ */
+export type PatchStageOptions = DryRunnable & PatchLockWaitable;
+/**
+ * Options for the `fireforge patch reserve` subcommand: hold an order
+ * number for a patch not exported yet, or release the hold.
+ */
+export interface PatchReserveOptions extends DryRunnable, PatchLockWaitable {
+    /** Category the reserved patch will carry (required to reserve). */
+    category?: string;
+    /** Who holds the reservation (required to reserve). */
+    owner?: string;
+    /** Optional human-readable rationale stored on the reserved slot. */
+    reason?: string;
+    /** Release the reservation at the order instead of creating one. */
+    release?: boolean;
+}
 /**
  * Options for the `fireforge patch rename` subcommand. Updates the patch's
  * filename, manifest `name`, and (optionally) `description` atomically

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

@@ -65,7 +65,22 @@ export interface LintIgnoreCeiling {
     max: number;
     /** Why the waiver exists. Required so the ceiling is reviewable. */
     reason: string;
+    /**
+     * Which share of a split `large-patch-lines` measurement the ceiling
+     * bounds: `product` (non-test files) or `test` (test files, held to the
+     * test tier). Absent: every finding of the rule. Only valid on
+     * `large-patch-lines`, and a rule carries either one share-less ceiling
+     * or at most one ceiling per share.
+     */
+    share?: PatchSizeShare;
+    /**
+     * Free-form JSON object FireForge preserves and never reads: a place for
+     * a project's own waiver bookkeeping (kind, owner, exit condition).
+     */
+    meta?: Record<string, unknown>;
 }
+/** The two classes a split `addedCode` line measurement reports. */
+export type PatchSizeShare = 'test' | 'product';
 /** One `PatchMetadata.lintIgnore` entry: a bare check ID or a ceiling waiver. */
 export type LintIgnoreEntry = string | LintIgnoreCeiling;
 /**
@@ -227,6 +242,28 @@ export interface PatchesManifest {
      * slot, and the slot is dropped on that write.
      */
     retired?: PatchRetiredSlot[];
+    /**
+     * Order numbers `patch reserve` holds for a patch a session has agreed to
+     * export but has not exported yet. Like a retired slot, a reservation is
+     * read only by the `patchPolicy.allowGaps: false` gap check (as an
+     * occupied order) and by the earliest-legal-order search (as taken); the
+     * export that lands on the order fills it, and the slot is dropped on that
+     * write.
+     */
+    reserved?: PatchReservedSlot[];
+}
+/** One order held by `patch reserve` until its owner exports it. */
+export interface PatchReservedSlot {
+    /** The reserved order number. */
+    order: number;
+    /** Category the reserved patch will carry, so the slot stays in its range. */
+    category: PatchCategory;
+    /** Who holds the reservation: a session label or the planned filename. */
+    owner: string;
+    /** ISO timestamp of the reservation. */
+    reservedAt: string;
+    /** Optional human-readable rationale. */
+    reason?: string;
 }
 /** One placeholder left by `patch retire`. */
 export interface PatchRetiredSlot {
@@ -306,4 +343,10 @@ export interface PatchLintIssue {
      * ceiling compares against it, and `lint --report` carries it.
      */
     measurement?: number;
+    /**
+     * For a `large-patch-lines` finding under `patchSizeMetric: "addedCode"`
+     * on a general-tier patch: which share of the patch it measured. A
+     * share-scoped lintIgnore ceiling matches only findings of its share.
+     */
+    share?: PatchSizeShare;
 }

package/dist/src/types/config.d.ts

@@ -62,6 +62,21 @@ export interface TestConfig {
      * once. `--auto-ports` is the per-invocation equivalent.
      */
     mochitestPorts?: 'fixed' | 'auto';
+    /**
+     * `exclusive` (the default): every `fireforge test` holds the engine
+     * session lock alone. `shared`: a build-less run with auto ports holds it
+     * shared, so peers' build-less runs on the same objdir overlap while
+     * builds and re-exports still wait. `--shared-lock` is the per-invocation
+     * equivalent.
+     */
+    lockMode?: 'exclusive' | 'shared';
+    /**
+     * Which components `test --build` deploys before building: `all` (the
+     * default) every component with undeployed edits, `reached` only those a
+     * requested test reaches, `none` nothing. `--furnace-apply` is the
+     * per-invocation equivalent.
+     */
+    furnaceApply?: 'all' | 'reached' | 'none';
 }
 /** Patch history log settings stored in fireforge.json. */
 export interface HistoryConfig {
@@ -243,6 +258,11 @@ export interface CheckExtraStep {
     cwd?: string;
     /** Seconds before the step is killed and fails. Unbounded when unset. */
     timeout?: number;
+    /**
+     * Steps (built-in or extra) that must finish before this one starts,
+     * whatever their outcome: an ordering, not a success dependency.
+     */
+    after?: string[];
 }
 /** Configuration for `fireforge check`. Every field is optional. */
 export interface CheckConfig {
@@ -264,6 +284,23 @@ export interface CheckConfig {
     };
     /** Project commands run as further steps. */
     extraSteps?: CheckExtraStep[];
+    /** Seconds before a built-in step is killed and fails. Unbounded when unset. */
+    timeout?: number;
+    /** Per-step `timeout` overrides for built-in steps, in seconds. */
+    timeouts?: Partial<Record<CheckBuiltinStep, number>>;
+    /**
+     * Fail the verdict when a built-in step is skipped because it has nothing
+     * to run (no `typecheck` block, no furnace.json). A step named in `skip`
+     * is a decision, not a gap, and never fails it.
+     */
+    failOnSkipped?: boolean;
+    /**
+     * Project-relative path the lint step writes its `lint --per-patch
+     * --report` JSON to. Extra steps receive it as
+     * `FIREFORGE_CHECK_LINT_REPORT`, so an audit can read the run's lint
+     * report instead of linting the queue a second time.
+     */
+    lintReport?: string;
 }
 /**
  * Configuration for the `fireforge typecheck` command. Distinct from
@@ -308,6 +345,15 @@ export interface TypecheckConfig {
      * blocking. `'off'` suppresses them.
      */
     undefinedIdentifiers?: PatchLintSeverityGate;
+    /**
+     * Types Lit in the shim: `LitElement` and the template helpers of
+     * `chrome://global/content/vendor/lit.all.mjs`, and `MozLitElement` of
+     * `chrome://global/content/lit-utils.mjs`, with closed member lists, so a
+     * misspelt member of a widget host is an error. Default off: reactive
+     * properties declared only through `static properties` or
+     * `static queries` then need a JSDoc or constructor declaration.
+     */
+    litTypes?: boolean;
 }
 /**
  * Wire command configuration.
@@ -564,8 +610,12 @@ export interface PatchLintConfig {
 export interface PatchLintTokenScale {
     /** CSS properties governed (exact names, or a `*`-suffixed prefix such as `padding*`). */
     properties: string[];
-    /** Custom-property prefix of the scale's tokens, e.g. `--mybrowser-space-`. */
-    prefix: string;
+    /**
+     * Custom-property prefix of the scale's tokens, e.g. `--mybrowser-space-`,
+     * or a list of them for a scale whose steps are spelled more than one way
+     * (`["--mybrowser-space-", "--mybrowser-gap-"]`).
+     */
+    prefix: string | string[];
     /**
      * Literal value atoms accepted without a token (`0`, `auto`, `1px`).
      * `*` is a wildcard, so `*%` accepts any percentage. CSS-wide keywords
@@ -579,6 +629,28 @@ export interface PatchLintTokenScale {
      * tokens.
      */
     allow?: string[];
+    /**
+     * Literal atoms accepted only inside a math function (`calc()`, `min()`,
+     * `max()`, `clamp()`), with the `allowLiterals` wildcard syntax: a
+     * unitless multiplier (`calc(var(--x-space-2) * 2)`) without also
+     * accepting a bare `2`.
+     */
+    allowInCalc?: string[];
+    /**
+     * Largest total, in px, a declaration may subtract from this scale's
+     * tokens inside a math function (`calc(var(--x-space-4) - 1px)`), for a
+     * border or hairline inset. Summed over the declaration.
+     */
+    offsetCap?: number;
+    /** Engine-relative globs (`**`, `*`, `?`) of files this scale does not govern. */
+    exclude?: string[];
+    /**
+     * The fewest patch-created CSS files (outside `exclude`) that must carry a
+     * declaration of this scale's properties. A queue under it fails
+     * `token-scale-vacuous`, so a scale that matches nothing, or a scan set
+     * a move emptied, cannot pass by judging nothing.
+     */
+    minFiles?: number;
 }
 /**
  * Build modes for mach.

package/dist/src/types/furnace.d.ts

@@ -109,6 +109,19 @@ export interface FurnaceValidationException {
     component: string;
     /** The finding's check name, as `furnace validate` prints it in brackets. */
     check: string;
+    /**
+     * Narrows the exception to the findings on this element tag (a finding's
+     * `tags`): a `panel-item` menu row can be accepted without muting the
+     * check for every other element of the component.
+     */
+    tag?: string;
+    /**
+     * Narrows the exception to the findings in this module file of the
+     * component (a finding's `files`), by file name: a vendored bundle whose
+     * bytes are pinned can be accepted without muting the check for the
+     * authored modules beside it.
+     */
+    file?: string;
     /** Why the finding is accepted. Required: the entry is the review record. */
     reason: string;
 }
@@ -160,6 +173,12 @@ export interface FurnaceConfig {
      * `['browser/base/content/browser.xhtml']`, the upstream Firefox path.
      */
     tokenHostDocuments?: string[];
+    /**
+     * Stylesheets that load beside others in a document no queue link shows,
+     * for `token lint`: `{ "<glob>": ["<path or glob>", …] }`. A sheet the key
+     * matches may reference the tokens its partners declare.
+     */
+    tokenSiblingSheets?: Record<string, string[]>;
     /**
      * Override the default Fluent (.ftl) base path within the engine.
      * Defaults to `toolkit/locales/en-US/toolkit/global` when not set.
@@ -185,6 +204,12 @@ export interface FurnaceConfig {
      * entry that no longer matches anything as a stale-exception warning.
      */
     validationExceptions?: FurnaceValidationException[];
+    /**
+     * The fewest components a full `furnace validate` must judge. A run under
+     * it fails with `component-floor`, so a moved or emptied components tree
+     * cannot pass by validating nothing.
+     */
+    minComponents?: number;
     /**
      * Opt-in `furnace validate` checks (see {@link FURNACE_OPT_IN_CHECKS}).
      * Unset runs only the default checks.
@@ -359,6 +384,10 @@ export interface ValidationIssue {
     check: string;
     /** Human-readable description of the issue */
     message: string;
+    /** Element tags the finding is about, when it is about particular elements. */
+    tags?: string[];
+    /** Component module files the finding is in (`hardcoded-text`), by file name. */
+    files?: string[];
 }
 /** Resolved test-harness selection for a `furnace create` run. */
 export type ResolvedTestStyle = 'mochikit' | 'browser-chrome' | 'xpcshell' | 'none';

package/dist/src/types/index.d.ts

@@ -1,5 +1,5 @@
 /**
  * Re-exports all type definitions.
  */
-export type { BuildConfig, FireForgeConfig, FirefoxConfig, FirefoxProduct, PatchLintFileSizeThresholds, PatchLintFileSizeTier, ProjectLicense, ProjectPaths, WireConfig, } from './config.js';
+export type { BuildConfig, FireForgeConfig, FirefoxConfig, FirefoxProduct, PatchLintFileSizeThresholds, PatchLintFileSizeTier, PatchLintPatchSizeMetric, ProjectLicense, ProjectPaths, WireConfig, } from './config.js';
 export type { ApplyResult, ComponentType, CustomComponentConfig, DryRunAction, FurnaceConfig, FurnaceState, OverrideComponentConfig, OverrideType, StepError, ValidationIssue, } from './furnace.js';

package/dist/src/utils/options.d.ts

@@ -49,13 +49,14 @@ export declare function commanderArgParser<T>(parse: (raw: string) => T): (raw:
 export declare function stringListOption(): [(value: string, previous: string[]) => string[], string[]];
 /** Environment variable naming a standing wait budget for the whole session. */
 export declare const WAIT_LOCK_ENV_VAR = "FIREFORGE_WAIT_LOCK";
+export declare const MAX_WAIT_LOCK_SECONDS = 86400;
 /**
  * Resolves the parsed `--wait-lock [seconds]` option value into a wait budget
  * in seconds for `withEngineSessionLock`:
  * - absent (`undefined`) → {@link WAIT_LOCK_ENV_VAR} if set, else `undefined`
  *   (the ~1 s fail-fast),
  * - bare flag (`true`) → {@link DEFAULT_WAIT_LOCK_SECONDS},
- * - explicit value → integer validated into 1..3600.
+ * - explicit value → integer validated into 1..86400.
  *
  * The flag always wins over the environment: the environment expresses a
  * default for a session, and an invocation that names a budget has said
@@ -125,7 +126,7 @@ export declare function isPathShapedArgument(token: string): boolean;
  *
  * Commander binds the next non-dash token to an optional value, so
  * `fireforge test --build --wait-lock browser_x.js` failed with
- * "--wait-lock must be an integer in 1..3600 (got "browser_x.js")": the
+ * "--wait-lock must be an integer in 1..86400 (got "browser_x.js")": the
  * help says the value is optional, and the obvious spelling refused. The
  * released flag moves to the end of the option section (before any `--`),
  * where nothing follows it, so commander reads it bare. Operands keep their

package/dist/src/utils/options.js

@@ -68,9 +68,14 @@ export function stringListOption() {
 const DEFAULT_WAIT_LOCK_SECONDS = 60;
 /** Environment variable naming a standing wait budget for the whole session. */
 export const WAIT_LOCK_ENV_VAR = 'FIREFORGE_WAIT_LOCK';
-/** Bounds shared by the flag and the environment variable. */
+/**
+ * Bounds shared by the flag and the environment variable. The ceiling is a
+ * day: on a shared engine a re-export or `test --build` queued behind a
+ * peer's long series can need more than the hour the cap used to be, and a
+ * longer wait then had to be a requeue after exit 15.
+ */
 const MIN_WAIT_LOCK_SECONDS = 1;
-const MAX_WAIT_LOCK_SECONDS = 3600;
+export const MAX_WAIT_LOCK_SECONDS = 86_400;
 /**
  * Parses a wait budget from text, or undefined when it is not an integer in
  * range. Shared by the flag and {@link WAIT_LOCK_ENV_VAR} so the two cannot
@@ -115,7 +120,7 @@ function waitLockSecondsFromEnv() {
  * - absent (`undefined`) → {@link WAIT_LOCK_ENV_VAR} if set, else `undefined`
  *   (the ~1 s fail-fast),
  * - bare flag (`true`) → {@link DEFAULT_WAIT_LOCK_SECONDS},
- * - explicit value → integer validated into 1..3600.
+ * - explicit value → integer validated into 1..86400.
  *
  * The flag always wins over the environment: the environment expresses a
  * default for a session, and an invocation that names a budget has said
@@ -237,7 +242,7 @@ export function isPathShapedArgument(token) {
  *
  * Commander binds the next non-dash token to an optional value, so
  * `fireforge test --build --wait-lock browser_x.js` failed with
- * "--wait-lock must be an integer in 1..3600 (got "browser_x.js")": the
+ * "--wait-lock must be an integer in 1..86400 (got "browser_x.js")": the
  * help says the value is optional, and the obvious spelling refused. The
  * released flag moves to the end of the option section (before any `--`),
  * where nothing follows it, so commander reads it bare. Operands keep their

package/docs/configuration.md

@@ -253,10 +253,34 @@ lint instead of throwing at runtime (since 0.50.0). The same shim backs
   is a wildcard), or a CSS-wide keyword (`inherit`, `initial`, `unset`,
   `revert`, `revert-layer`). A `var()` fallback is held to the same scale,
   so `var(--mybrowser-gap, 7px)` fails on `7px`. `calc()`, `min()`, `max()`
-  and `clamp()` are transparent, so a unitless multiplier inside one needs
-  an `allowLiterals` entry. Files the patch modifies rather than creates are
-  not checked, and a line carrying `fireforge-ignore: token-scale` is
-  skipped.
+  and `clamp()` are transparent. Files the patch modifies rather than
+  creates are not checked, and a line carrying
+  `fireforge-ignore: token-scale` is skipped. Declarations inside
+  descriptor at-rules (`@font-face`, `@counter-style`, `@property`,
+  `@font-feature-values`, `@font-palette-values`, `@page` and its margin
+  boxes) are descriptors, not properties, and are not judged.
+
+  Since 0.51.0 a scale also takes:
+
+  - `prefix` as a list (`["--mybrowser-space-", "--mybrowser-gap-"]`) for a
+    scale whose steps are spelled more than one way.
+  - `allowInCalc`: literals legal only inside a math function, such as the
+    unitless multiplier in `calc(var(--mybrowser-space-2) * 2)`, without
+    also passing a bare `2`. Same wildcard syntax as `allowLiterals`.
+  - `offsetCap`: the px a declaration may subtract from the scale's tokens
+    inside a math function (`calc(var(--mybrowser-space-4) - 1px)`), summed
+    over the declaration. A px value anywhere else still fails.
+  - `exclude`: engine-relative globs of files the scale does not govern,
+    such as a vendored minified sheet, so its patch needs no patch-wide
+    waiver.
+  - `minFiles`: the fewest patch-created stylesheets (outside `exclude`)
+    that must declare one of the scale's properties. Under it the queue
+    fails `token-scale-vacuous` (an error on `fireforge.json` in
+    `lint --per-patch`), so a scale that matches nothing, or a scan set a
+    move emptied, cannot pass by judging nothing. A `--patches` run does
+    not judge the floor.
+
+  An unknown key in a scale is refused.
 
 ## `typecheck`
 
@@ -275,6 +299,42 @@ program: prior incremental diagnostic state is never restored. Cached and
 also disables build-info writes. A jsconfig's own `incremental` and
 `tsBuildInfoFile` remain ignored.
 
+`typecheck.litTypes: true` (since 0.51.0, default off) types Lit in the
+shim: `LitElement` and the helpers of
+`chrome://global/content/vendor/lit.all.mjs`, and `MozLitElement` of
+`chrome://global/content/lit-utils.mjs`. The element classes carry closed
+member lists, as `Cu` does, so a misspelt member of a widget host is an
+error rather than `any`. Template helpers and directives stay loose. It is
+off by default because a reactive property declared only in
+`static properties` or `static queries` then needs a declaration to be
+known. Since 0.52.0 the shim declares the global type
+`MozLitElementWith<Extra>`: a widget casts its base to it, and its
+instances carry `Extra` beside MozLitElement's members. A query getter
+cannot be declared any other way: a class field redefines the getter
+MozLitElement installs and throws, and a constructor declaration reads it
+before `renderRoot` exists.
+
+```js
+const Base = /** @type {MozLitElementWith<{ input: HTMLInputElement }>} */ (MozLitElement);
+export class MozSearch extends Base {
+  static queries = { input: 'input' };
+}
+```
+
+Without `litTypes` (and under per-patch checkJs, which does not type Lit)
+`MozLitElementWith<Extra>` is `any`, as the base is, so the same source
+checks in both. A project shim can add members by merging
+`interface LitElementShimMembers`; a jsconfig `paths` entry that maps these
+URLs to real sources takes precedence.
+
+Per-patch checkJs gives each test script its own program. Since 0.51.0 a
+test's `resource:///` and `chrome://` imports (including a
+`typeof import("…")` cast) resolve to the modules the queue creates up to
+the test's own patch, so a test of an earlier patch's module is checked
+against its real types. A module a later patch creates, an upstream module
+and a basename two patches create still type as `any`, and an implicit-any
+finding on such an import names it.
+
 Both project and per-patch checkJs provide Gecko DOM constructor
 `isInstance(value)` predicates with instance narrowing, plus
 `MouseEvent.MOZ_SOURCE_PEN`. These declarations retain normal DOM member
@@ -288,8 +348,10 @@ gaps does not move a patch out of the band its category owns.
 With `patchPolicy.allowGaps: false`, orders are contiguous within a range:
 a new patch must fill an existing gap or take the number right after the
 range's last patch. A patch that has to leave the queue without opening a
-gap is removed with `patch retire`, which keeps its order as a retired slot
-(see [`patch-workflow.md`](patch-workflow.md#queue-maintenance)).
+gap is removed with `patch retire`, which keeps its order as a retired slot.
+An order a peer has claimed but not exported yet is held with `patch
+reserve`, so a later order can be exported without a gap in between (see
+[`patch-workflow.md`](patch-workflow.md#queue-maintenance)).
 
 ### Registration-only rules
 
@@ -356,6 +418,18 @@ harness's own busy-port fallback, so sibling checkouts can run browser suites
 at once. `--auto-ports` does the same for one invocation. See
 [`testing.md`](testing.md#shared-browsers-ports-and-host-state).
 
+`test.lockMode` is `"exclusive"` (default) or `"shared"`. `"shared"` lets a
+build-less run that applies no negative control and uses auto ports hold the
+engine-session lock shared, so peers' build-less runs on the same objdir
+overlap while builds, re-exports and every other writer still hold it alone.
+`--shared-lock` does the same for one invocation. See
+[`testing.md`](testing.md#concurrency).
+
+`test.furnaceApply` is `"all"` (default), `"reached"` or `"none"`: which
+components a `test --build` deploys before building. `--furnace-apply` does
+the same for one invocation. See
+[`testing.md`](testing.md#furnace-components-in-a-pre-test-build).
+
 ## `history`
 
 `history.path` is where FireForge appends its patch history log, relative to
@@ -457,6 +531,24 @@ one that dismissed four unregistered sources.
   `/bin/sh -c` (`cmd.exe /c` on Windows) from the project root, or from the
   project-relative `cwd`. `timeout` is in seconds: past it the step's whole
   process tree is killed and the step fails. A step passes when it exits 0.
+  `after` lists steps, built-in or extra, that must finish before it starts
+  (whatever their outcome); a name that is not a step, or an ordering cycle,
+  is refused.
+- `timeout` bounds every built-in step, in seconds, and `timeouts` sets it
+  per step (`{ "typecheck": 600 }`). A step past its budget is killed and
+  fails. Unset, built-in steps are unbounded.
+- `failOnSkipped: true` fails the check (`reason=skipped-steps`) when a
+  built-in step is skipped because the project has nothing for it to run
+  (no `typecheck` block, no `furnace.json`). A step named in `skip` is a
+  decision and never fails it.
+- `lintReport` is a project-relative path the lint step writes its
+  `lint --per-patch --report` JSON to. Every extra step receives the
+  absolute path as `FIREFORGE_CHECK_LINT_REPORT`, so an audit that runs
+  `after: ["lint"]` can read the run's lint report instead of linting the
+  queue a second time.
+
+The verdict line names the skipped steps with an additive
+`skipped-steps=<a,b>` key beside `skipped=<n>`.
 
 ## Design tokens
 
@@ -519,7 +611,16 @@ The dark and variant blocks mirror it and appear in `token show`.
 - `token-undeclared`: a `var(--<prefix>…)` in the tokens CSS, or in any CSS
   file a patch in the queue touches, names a token no block of the tokens
   CSS declares. A property declared in the same file, and the `furnace.json`
-  `tokenAllowlist` and `runtimeVariables` names, are exempt.
+  `tokenAllowlist` and `runtimeVariables` names, are exempt. Since 0.51.0 a
+  reference with a fallback (`var(--x, 0)`) is optional and not reported,
+  and a token a sibling sheet declares counts as declared. Sheets are
+  siblings when one queue document links both (`<link rel="stylesheet">`,
+  `<html:link>` or `<?xml-stylesheet?>`, in markup or a Lit template; a
+  `chrome://` URL resolves through the queue's jar.mn lines, a relative
+  one beside the document), when one `@import`s the other, or when
+  `furnace.json` `tokenSiblingSheets` pairs them:
+  `{ "browser/themes/**/panel*.css": ["browser/base/content/host.css"] }`
+  (a partner is a path or a glob over the queue's sheets).
 
 The prefix is `furnace.json` `tokenPrefix`, else `--<binaryName>-`.
 
@@ -585,7 +686,7 @@ Every FireForge command that mutates the engine takes the engine-session
 lock, and some take a second subsystem lock as well. Contention fails fast
 after about a second by default.
 
-`--wait-lock [seconds]` (bare flag means 60, valid range 1 to 3600) replaces
+`--wait-lock [seconds]` (bare flag means 60, valid range 1 to 86400, a day) replaces
 that with a bounded wait, and the budget covers every lock the command takes.
 For `furnace apply`, `deploy` and `sync` that means the furnace lock as well
 as the engine-session lock. The furnace leaves that take only the furnace lock
@@ -614,7 +715,7 @@ instead of blocking it.
 
 | Variable                             | Effect                                                                                                                                  |
 | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `FIREFORGE_WAIT_LOCK`                | Session-wide lock wait budget in seconds (1 to 3600). See above.                                                                        |
+| `FIREFORGE_WAIT_LOCK`                | Session-wide lock wait budget in seconds (1 to 86400). See above.                                                                       |
 | `FIREFORGE_SESSION_ID`               | Recorded as `sessionId` on every patch history log record this process writes. See `history` above.                                     |
 | `FIREFORGE_LOG_KEEP`                 | Also write every `test`/`build` run log here, outside retention (a directory collects one file per run). See `run-logs.md`.             |
 | `FIREFORGE_MAX_UNTRACKED_FILES`      | Per-directory cap when expanding collapsed untracked directories in `status` (default 5000). A non-positive value warns and is ignored. |