@hominis/fireforge 0.49.2 → 0.51.0

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

@@ -54,6 +54,37 @@ export interface TestConfig {
      * verdict line. `--reap-orphans` is the per-invocation equivalent.
      */
     reapOrphans?: 'report' | 'reap';
+    /**
+     * `fixed` (the default) refuses a browser run while the mochitest server
+     * or Marionette port is held. `auto` lets a run proceed when the holder is
+     * not this checkout's own and the engine's mochitest harness can fall back
+     * to a free port itself, so sibling checkouts can run browser suites at
+     * 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 {
+    /**
+     * Project-relative path of the append-only patch history log. Defaults to
+     * `.fireforge/history.jsonl`, outside the tracked patch queue.
+     */
+    path?: string;
 }
 /** A single external executable required by a project-specific toolchain. */
 export interface ExternalToolRequirement {
@@ -104,6 +135,35 @@ export interface PatchPolicyReservedRange {
     /** Exact patch exceptions allowed in this reserved range. */
     allowed: PatchPolicyReservedAllowedPatch[];
 }
+/**
+ * One `patchPolicy.upstreamAllowlist` entry in object form. The string form
+ * is shorthand for `{ path }`.
+ */
+export interface PatchPolicyUpstreamAllowEntry {
+    /** Engine-relative path glob (`*` within a segment, `**` across segments). */
+    path: string;
+    /**
+     * Registration-only mode: a patch may only add lines to a matching file
+     * (no removals, no deletion), and every non-blank added line must carry
+     * `marker` (or `patchPolicy.addOnlyMarker`), case-insensitively.
+     */
+    addOnly?: boolean;
+    /** Marker an added line must contain. Overrides `patchPolicy.addOnlyMarker`. */
+    marker?: string;
+}
+/**
+ * Limits the files a class of patch may touch, e.g. a `-tests` patch to test
+ * directories and test manifests. A rule applies to a patch when every
+ * selector it sets matches. At least one selector is required.
+ */
+export interface PatchPolicyScopeRule {
+    /** Applies to patches in this category. */
+    category?: string;
+    /** Applies to patches whose filename matches this regular expression. */
+    filenamePattern?: string;
+    /** Engine-relative path globs every file the patch touches must match. */
+    files: string[];
+}
 /**
  * Optional project-specific patch queue policy. When absent, FireForge keeps
  * its historical broad category + numeric ordering behaviour.
@@ -121,6 +181,21 @@ export interface PatchPolicyConfig {
     ranges: PatchPolicyRange[];
     /** Reserved exception ranges. */
     reservedRanges?: PatchPolicyReservedRange[];
+    /**
+     * Globs naming the upstream files a non-reserved patch may modify. A file
+     * counts as upstream when no patch in the queue creates it. Unset: no
+     * restriction.
+     */
+    upstreamAllowlist?: Array<string | PatchPolicyUpstreamAllowEntry>;
+    /** Default marker for `addOnly` allowlist entries that set none. */
+    addOnlyMarker?: string;
+    /** File-scope rules per patch class (category and/or filename pattern). */
+    scopeRules?: PatchPolicyScopeRule[];
+    /**
+     * Require every reserved allowlist entry's `adr` and `documentation` path
+     * to exist under the project root. Default false.
+     */
+    verifyDocumentPaths?: boolean;
 }
 /**
  * Main fireforge.json configuration schema.
@@ -142,6 +217,8 @@ export interface FireForgeConfig {
     buildAudit?: BuildAuditConfig;
     /** Test command defaults */
     test?: TestConfig;
+    /** Patch history log settings */
+    history?: HistoryConfig;
     /** Optional project-specific external toolchains checked by doctor. */
     externalToolchains?: ExternalToolchainConfig[];
     /** Project license SPDX identifier */
@@ -154,6 +231,8 @@ export interface FireForgeConfig {
     patchPolicy?: PatchPolicyConfig;
     /** Typecheck command configuration (CI-grade, whole-project) */
     typecheck?: TypecheckConfig;
+    /** `fireforge check`: the composed static gate's policy and project steps */
+    check?: CheckConfig;
     /**
      * Project marker prefix appended to lines FireForge writes into
      * upstream Firefox source files (e.g. the `customElements.js` tag list).
@@ -162,6 +241,67 @@ export interface FireForgeConfig {
      */
     markerComment?: string;
 }
+/** The built-in steps of `fireforge check`, in table order. */
+export declare const CHECK_BUILTIN_STEPS: readonly ["status", "verify", "lint", "typecheck", "furnace-validate", "token-coverage"];
+/** One built-in `fireforge check` step name. */
+export type CheckBuiltinStep = (typeof CHECK_BUILTIN_STEPS)[number];
+/**
+ * A project command `fireforge check` runs beside its built-in steps
+ * (`check.extraSteps[]`): an audit FireForge does not ship.
+ */
+export interface CheckExtraStep {
+    /** Unique step name shown in the table (lowercase, digits and dashes). */
+    name: string;
+    /** Shell command line, run with `/bin/sh -c` (`cmd.exe /c` on Windows). */
+    command: string;
+    /** Project-relative working directory. Defaults to the project root. */
+    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 {
+    /** Built-in steps this project never runs. */
+    skip?: CheckBuiltinStep[];
+    /**
+     * The status step's `--check` policy: `--fail-on`, `--allow` and
+     * `--fail-on-unknown`. Unset runs the default `status --check` policy.
+     */
+    status?: {
+        failOn?: string[];
+        allow?: string[];
+        failOnUnknown?: boolean;
+    };
+    /** `--max-warnings` for the lint and furnace-validate steps. */
+    maxWarnings?: {
+        lint?: number;
+        furnace?: number;
+    };
+    /** 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
  * `patchLint.checkJs`: patch-lint runs every time `fireforge lint` runs
@@ -205,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.
@@ -297,6 +446,37 @@ export interface PatchLintFileSizeThresholds {
     /** Test files. Defaults: notice 1200, warning 1400, error 1600. */
     test?: PatchLintFileSizeTier;
 }
+/** What `file-too-large` counts: every line, or only lines that carry code. */
+export type PatchLintFileSizeMetric = 'raw' | 'code';
+/**
+ * What `large-patch-lines` counts: every non-binary line of the unified
+ * diff, or only the added lines that carry code.
+ */
+export type PatchLintPatchSizeMetric = 'diff' | 'addedCode';
+/**
+ * Overrides for one patch-size tier. `lines` drives `large-patch-lines`,
+ * `files` drives `large-patch-files`. Each is a `notice`/`warning`/`error`
+ * triple shaped like {@link PatchLintFileSizeTier}, merged over the
+ * defaults and validated `notice <= warning <= error`.
+ */
+export interface PatchLintPatchSizeTier {
+    lines?: PatchLintFileSizeTier;
+    files?: PatchLintFileSizeTier;
+}
+/**
+ * Overrides for the patch-size thresholds, per tier.
+ *
+ * Module constants until 0.50.0. The defaults are the old constants: lines
+ * general 800/1500/3000, test 1500/3000/6000, branding 8000/18000/30000;
+ * files warn above 5 (general, test) or 60 (branding). The files triple has
+ * no notice or error band by default: an unset `files.notice` follows the
+ * effective `files.warning`, and an unset `files.error` never fires.
+ */
+export interface PatchLintPatchSizeThresholds {
+    general?: PatchLintPatchSizeTier;
+    test?: PatchLintPatchSizeTier;
+    branding?: PatchLintPatchSizeTier;
+}
 /**
  * Configuration for patch lint rules.
  */
@@ -348,6 +528,34 @@ export interface PatchLintConfig {
      * Unset fields keep the built-in defaults.
      */
     fileSizeThresholds?: PatchLintFileSizeThresholds;
+    /**
+     * What `file-too-large` counts. `'raw'` (the default) counts every line
+     * the way `wc -l` does. `'code'` counts the lines left non-blank once
+     * comments are blanked, so JSDoc and blank lines stop counting.
+     */
+    fileSizeMetric?: PatchLintFileSizeMetric;
+    /**
+     * Per-tier overrides for `large-patch-lines` and `large-patch-files`.
+     * Unset fields keep the built-in defaults.
+     */
+    patchSizeThresholds?: PatchLintPatchSizeThresholds;
+    /**
+     * What `large-patch-lines` counts. `'diff'` (the default) counts every
+     * non-binary line of the unified diff. `'addedCode'` counts added lines
+     * that are neither blank nor comment, judged on each file's post-image,
+     * skips lines inside Furnace `@fireforge-include` spans, and counts test
+     * files against the test tier and everything else against the general
+     * tier inside a mixed patch.
+     */
+    patchSizeMetric?: PatchLintPatchSizeMetric;
+    /**
+     * Globs naming registration files (`jar.mn`, `moz.build`, manifests)
+     * that count toward neither `large-patch-lines` nor `large-patch-files`.
+     * A glob without a `/` matches the basename, one with a `/` matches the
+     * engine-relative path. `*` stays within a path segment, `**` crosses
+     * segments. Default: none.
+     */
+    patchSizeRegistrationFiles?: string[];
     /**
      * Run the project's Prettier over patch-owned `.sys.mjs` modules, from
      * inside `engine/` so the engine's own `.prettierrc*`/`.prettierignore`
@@ -387,6 +595,62 @@ export interface PatchLintConfig {
      * and fail the other. Default: 'warning'.
      */
     undefinedIdentifiers?: PatchLintSeverityGate;
+    /**
+     * Token scales enforced over CSS files a patch creates (`token-scale`).
+     * Each scale names properties whose values must resolve to its tokens.
+     * Default unset: no scale is enforced.
+     */
+    tokenScales?: PatchLintTokenScale[];
+}
+/**
+ * One `patchLint.tokenScales[]` entry: a property family (spacing, type,
+ * radius, opacity, z-index, …) whose declared values must be tokens on one
+ * scale.
+ */
+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-`,
+     * 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
+     * (`inherit`, `initial`, `unset`, `revert`, `revert-layer`) are always
+     * accepted.
+     */
+    allowLiterals?: string[];
+    /**
+     * Further custom properties accepted besides `prefix` (exact names, or a
+     * `*`-suffixed prefix such as `--moz-*`), for reviewed upstream or recipe
+     * 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/config.js

@@ -1,3 +1,12 @@
+/** The built-in steps of `fireforge check`, in table order. */
+export const CHECK_BUILTIN_STEPS = [
+    'status',
+    'verify',
+    'lint',
+    'typecheck',
+    'furnace-validate',
+    'token-coverage',
+];
 /**
  * Build modes for mach.
  *

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

@@ -103,6 +103,30 @@ export interface CustomComponentConfig {
      */
     sharedFtl?: string;
 }
+/** A reviewed `furnace validate` finding (`furnace.json#validationExceptions[]`). */
+export interface FurnaceValidationException {
+    /** Component tag name the finding is reported on. */
+    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;
+    /** Why the finding is accepted. Required: the entry is the review record. */
+    reason: string;
+}
+/**
+ * `furnace validate` checks that run only when `furnace.json#optInChecks`
+ * names them. `icon-button-label`: an icon-only `<moz-button>` (an
+ * `iconsrc` or an `icon` type, no `label` and no text content) carries
+ * neither `data-l10n-id` nor `aria-label`.
+ */
+export declare const FURNACE_OPT_IN_CHECKS: readonly ["icon-button-label"];
+/** One opt-in check name. */
+export type FurnaceOptInCheck = (typeof FURNACE_OPT_IN_CHECKS)[number];
 /**
  * The furnace.json schema.
  */
@@ -142,6 +166,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.
@@ -161,6 +191,23 @@ export interface FurnaceConfig {
      * Unset disables jsconfig maintenance.
      */
     typecheckJsconfig?: string;
+    /**
+     * Reviewed `furnace validate` findings. Each entry suppresses every
+     * finding of `check` on `component`, and `furnace validate` reports an
+     * 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.
+     */
+    optInChecks?: FurnaceOptInCheck[];
     /** Stock components tracked for preview */
     stock: string[];
     /** Override components */
@@ -234,6 +281,15 @@ export interface StepError {
      */
     advisory?: boolean;
 }
+/**
+ * Why `applyAllComponents` skipped a component, so a summary can say more
+ * than "skipped". `already-current`: the source is unchanged since the last
+ * recorded apply and the engine copy still matches it (fragment expansions
+ * included), so there was nothing to write. The apply state is shared by
+ * every session on the checkout, so the recorded apply may be another
+ * session's, e.g. a peer's `test --build`.
+ */
+export type ApplySkipKind = 'already-current';
 /**
  * Result of applying all components to the engine source tree.
  */
@@ -246,10 +302,14 @@ export interface ApplyResult {
         /** Non-fatal registration step errors */
         stepErrors?: StepError[];
     }>;
-    /** Components that were skipped (e.g., no changes) */
+    /**
+     * Components that were skipped (e.g., no changes). `kind` names the
+     * reason for summaries; `reason` is the stable free-text form.
+     */
     skipped: Array<{
         name: string;
         reason: string;
+        kind?: ApplySkipKind;
     }>;
     /** Components that failed to apply */
     errors: Array<{
@@ -317,6 +377,8 @@ 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[];
 }
 /** Resolved test-harness selection for a `furnace create` run. */
 export type ResolvedTestStyle = 'mochikit' | 'browser-chrome' | 'xpcshell' | 'none';

package/dist/src/types/furnace.js

@@ -1,3 +1,10 @@
+/**
+ * `furnace validate` checks that run only when `furnace.json#optInChecks`
+ * names them. `icon-button-label`: an icon-only `<moz-button>` (an
+ * `iconsrc` or an `icon` type, no `label` and no text content) carries
+ * neither `data-l10n-id` nor `aria-label`.
+ */
+export const FURNACE_OPT_IN_CHECKS = ['icon-button-label'];
 /**
  * Operations that can leave a pending-repair marker when they fail to roll
  * back cleanly. The marker is consumed by `fireforge doctor`, which either

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

@@ -1,5 +1,5 @@
 /**
  * Re-exports all type definitions.
  */
-export type { BuildConfig, FireForgeConfig, FirefoxConfig, FirefoxProduct, 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

@@ -13,7 +13,9 @@ import type { Command } from 'commander';
  * @param obj - Object to filter
  * @returns The same object with every `undefined`-valued key removed
  */
-export declare function pickDefined<T extends object>(obj: T): {
+export declare function pickDefined<T extends object>(obj: T): DefinedProps<T>;
+/** `T` with every property optional and `undefined` removed: what {@link pickDefined} returns. */
+export type DefinedProps<T> = {
     [K in keyof T]+?: Exclude<T[K], undefined>;
 };
 /**
@@ -47,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
@@ -74,11 +77,11 @@ export declare function resolveWaitLockSeconds(value: string | number | boolean
  * `--wait-lock` flag was threaded to. A furnace mutation takes the engine
  * session lock and then `.fireforge/furnace.lock`. Only the first had a
  * budget, so a contended deploy died on the file lock's fixed 30 s while
- * its operator believed a much larger budget was in force. Threading the
- * flag reaches the three furnace commands that declare it. This reaches
- * the twelve that do not (`create`, `remove`, `rename`, `refresh`, `scan`,
- * `override`, `chrome-doc`, …), which have no flag to thread but are just
- * as contended.
+ * its operator believed a much larger budget was in force. Every furnace
+ * leaf that takes the furnace lock threads its own `--wait-lock` into it;
+ * this is the fallback when the flag is absent, and the only budget for
+ * callers that do not thread one (doctor's furnace repair, the
+ * pre-build apply).
  *
  * Env-only: a flag belongs to one invocation and is passed
  * explicitly where it applies, while the environment is exactly the place a
@@ -109,6 +112,32 @@ export declare function addAcceptedWaitLockOption(command: Command): Command;
  * one everywhere else.
  */
 export declare function ensureWaitLockOptionEverywhere(command: Command): void;
+/**
+ * True for a token that reads as a path rather than a number: it has a
+ * path separator or a file extension, or is `.`/`..`. A bare word such as
+ * `nonsense` is not path-shaped, so `--wait-lock nonsense` stays the usage
+ * error it always was.
+ */
+export declare function isPathShapedArgument(token: string): boolean;
+/**
+ * Rewrites a command's option tokens so a path-shaped argument after a
+ * numeric optional-value flag is an operand, and the flag takes its
+ * default.
+ *
+ * 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..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
+ * relative order. The value of a required-value option (`--mach-arg
+ * --wait-lock`) is never mistaken for a flag.
+ *
+ * @param argv - The tokens commander passes to `parseOptions`
+ * @param requiredValueFlags - This command's flags that always take a value
+ * @returns The rewritten tokens
+ */
+export declare function releasePathShapedValues(argv: readonly string[], requiredValueFlags: ReadonlySet<string>): string[];
 /**
  * Registers the shared `--wait-lock [seconds]` flag on a lock-taking
  * command (the engine session lock for engine-mutating commands, the patch