@hominis/fireforge 0.49.1 → 0.50.0

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

@@ -0,0 +1,117 @@
+/**
+ * Patch-size lint: the `large-patch-lines` and `large-patch-files` rules,
+ * the tier decision they share, and the measurement they read.
+ *
+ * Split out of `patch-lint.ts` (per-file line budget). `patch-lint.ts`
+ * re-exports this module's surface so callers keep importing from there.
+ */
+import type { PatchLintIssue } from '../types/commands/index.js';
+import type { FireForgeConfig, PatchLintPatchSizeMetric } from '../types/config.js';
+import { type PatchSizeThresholds, type PatchSizeTierName } from './patch-lint-size-thresholds.js';
+/**
+ * Returns true if the file path looks like a test file.
+ * Matches paths containing `/test/` or filenames starting with
+ * `browser_`, `test_`, or `xpcshell_` (all `.js`). This is the test class
+ * of both size rules: `file-too-large` picks the test thresholds with it,
+ * and the patch-size tier and the `addedCode` per-class split read it.
+ */
+export declare function isTestFile(file: string): boolean;
+/**
+ * Counts the total lines in a unified diff and the number of non-binary
+ * text lines, so binary hunks do not inflate patch size checks.
+ *
+ * Line counting agrees with `wc -l`: a trailing newline does not add a
+ * phantom empty line to either `total` or the binary-hunk accounting.
+ *
+ * @param diffContent - Raw unified diff string
+ * @returns Object with `total` line count and `textLines` (total minus binary hunk lines)
+ */
+export declare function countNonBinaryDiffLines(diffContent: string): {
+    total: number;
+    textLines: number;
+};
+/**
+ * Describes which tier `resolvePatchSizeTier` selected and why.
+ * Consumers that want to surface the tier choice to the operator
+ * (e.g. a one-line `info()` when branding thresholds kick in) read
+ * this alongside the issues array from `lintPatchSize`.
+ */
+export type PatchSizeTierDecision = {
+    tier: 'general';
+} | {
+    tier: 'test';
+} | {
+    tier: 'branding';
+    source: 'auto' | 'explicit';
+};
+/**
+ * Decides which patch-size threshold tier applies to a patch.
+ * Exported so `runPatchLint` and the per-patch `lint` command can
+ * surface the tier choice to the operator *without* depending on
+ * `lintPatchSize`'s internal return shape.
+ *
+ * Precedence: test > branding (explicit) > branding (auto) > general.
+ * The test tier beats branding because a table-driven regression test
+ * is legitimately large independent of whether the patch also claims
+ * branding shape, and the test-tier thresholds are already more
+ * permissive than branding, so "tests beat branding" is the
+ * defensive-for-tests choice.
+ */
+export declare function resolvePatchSizeTier(filesAffected: ReadonlyArray<string>, patchTier?: 'branding'): PatchSizeTierDecision;
+/**
+ * The size thresholds a tier enforces, with `patchLint.patchSizeThresholds`
+ * applied when `config` is passed. Public-API companion to
+ * {@link resolvePatchSizeTier} / {@link countNonBinaryDiffLines} so
+ * consumers can build waiver-freshness checks against the same numbers
+ * `large-patch-lines` / `large-patch-files` fire on instead of mirroring
+ * them. Without `config` it returns the built-in defaults.
+ *
+ * @param tier - The tier to read
+ * @param config - The project configuration, whose overrides apply
+ */
+export declare function getPatchSizeThresholds(tier: PatchSizeTierName, config?: Pick<FireForgeConfig, 'patchLint'>): PatchSizeThresholds;
+/** What a patch measures under the configured patch-size metric. */
+export interface PatchSizeMeasurement {
+    /** The metric `lines` is counted in. */
+    metric: PatchLintPatchSizeMetric;
+    /** Counted lines, registration files left out. */
+    lines: number;
+    /**
+     * Of `lines`, those in test files. Only `addedCode` attributes lines per
+     * file, so this is 0 under `diff`.
+     */
+    testLines: number;
+    /** Files `large-patch-files` counts: the patch's files minus registration files. */
+    files: number;
+    /** Files left out of both counts as registration files. */
+    registrationFiles: number;
+}
+/**
+ * Measures a patch under `patchLint.patchSizeMetric`.
+ *
+ * `diff` counts the non-binary lines of the unified diff, headers and
+ * context included. `addedCode` counts the added lines that carry code,
+ * judged on each file's post-image read from `repoDir` (a hunk can start
+ * inside a block comment, so the `+` lines alone cannot tell), and skips
+ * lines inside Furnace fragment expansions. Files matching
+ * `patchLint.patchSizeRegistrationFiles` count toward neither number.
+ *
+ * @param repoDir - Engine directory holding the post-images
+ * @param diffContent - The patch's unified diff
+ * @param filesAffected - The patch's files
+ * @param config - Project configuration
+ */
+export declare function measurePatchSize(repoDir: string, diffContent: string, filesAffected: readonly string[], config: Pick<FireForgeConfig, 'patchLint'>): Promise<PatchSizeMeasurement>;
+/**
+ * Checks patch size against the tier's thresholds.
+ *
+ * @param filesAffected - Files touched by the patch
+ * @param measured - The {@link measurePatchSize} result, or a bare
+ *   non-binary diff line count (the `diff` metric over every file)
+ * @param patchTier - Optional explicit tier override declared on
+ *   `PatchMetadata.tier`. When `"branding"`, forces the branding
+ *   thresholds regardless of `filesAffected`. Tests still win over
+ *   branding (precedence `test > branding > general`).
+ * @param config - Project configuration, for `patchLint.patchSizeThresholds`
+ */
+export declare function lintPatchSize(filesAffected: string[], measured: number | PatchSizeMeasurement, patchTier?: 'branding', config?: Pick<FireForgeConfig, 'patchLint'>): PatchLintIssue[];

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

@@ -0,0 +1,323 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Patch-size lint: the `large-patch-lines` and `large-patch-files` rules,
+ * the tier decision they share, and the measurement they read.
+ *
+ * Split out of `patch-lint.ts` (per-file line budget). `patch-lint.ts`
+ * re-exports this module's surface so callers keep importing from there.
+ */
+import { join } from 'node:path';
+import { pathExists, readText } from '../utils/fs.js';
+import { codeLineMask } from './patch-lint-code-lines.js';
+import { AGGREGATE_PATCH_FILE } from './patch-lint-diff-tag.js';
+import { isPatchSizeRegistrationFile, resolvePatchSizeThresholds, } from './patch-lint-size-thresholds.js';
+import { parseDiffGitHeader, parseDiffSections } from './patch-parse.js';
+/**
+ * Shared remedy sentence for the over-budget findings. Every place an
+ * operator stands when a patch outgrows its budget must name the
+ * sanctioned one-transaction way out, or they reach for the wrong tools
+ * first. One constant, so the wording cannot drift.
+ */
+const SPLIT_HINT = 'Consider splitting into smaller, focused patches — ' +
+    '"fireforge patch move-files <from> <to> --file <path> --create --order <n>" ' +
+    'moves files into a new patch in one transaction.';
+/**
+ * Fixed allowlist of non-branding sibling paths that real-world Firefox
+ * branding patches legitimately need to touch to register the new branding
+ * flavor with the top-level configure. A predicate requiring every file to
+ * live under `browser/branding/` drops a branding patch that also touches
+ * `browser/moz.configure` (the canonical registration point) into the
+ * general lint tier.
+ *
+ * Narrow on purpose: add entries only when a genuine branding patch
+ * cannot be expressed without a specific registration sibling. Pinned
+ * against ESR 140.x conventions at time of writing.
+ */
+const BRANDING_REGISTRATION_FILES = new Set([
+    'browser/moz.configure',
+    'browser/confvars.sh',
+]);
+/**
+ * Returns true when a patch qualifies for the branding threshold tier:
+ * every file lives either under `browser/branding/` or in the narrow
+ * registration allowlist, and the patch contains at least one file
+ * under `browser/branding/` (guard against a config-only patch
+ * accidentally qualifying as branding).
+ */
+function isBrandingOnlyPatch(files) {
+    if (files.length === 0)
+        return false;
+    let hasBrandingFile = false;
+    for (const file of files) {
+        if (file.startsWith('browser/branding/')) {
+            hasBrandingFile = true;
+            continue;
+        }
+        if (BRANDING_REGISTRATION_FILES.has(file))
+            continue;
+        return false;
+    }
+    return hasBrandingFile;
+}
+/**
+ * Returns true if the file path looks like a test file.
+ * Matches paths containing `/test/` or filenames starting with
+ * `browser_`, `test_`, or `xpcshell_` (all `.js`). This is the test class
+ * of both size rules: `file-too-large` picks the test thresholds with it,
+ * and the patch-size tier and the `addedCode` per-class split read it.
+ */
+export function isTestFile(file) {
+    if (file.includes('/test/'))
+        return true;
+    const basename = file.split('/').pop() ?? '';
+    return /^(?:browser_|test_|xpcshell_).*\.js$/.test(basename);
+}
+/**
+ * Counts the total lines in a unified diff and the number of non-binary
+ * text lines, so binary hunks do not inflate patch size checks.
+ *
+ * Line counting agrees with `wc -l`: a trailing newline does not add a
+ * phantom empty line to either `total` or the binary-hunk accounting.
+ *
+ * @param diffContent - Raw unified diff string
+ * @returns Object with `total` line count and `textLines` (total minus binary hunk lines)
+ */
+export function countNonBinaryDiffLines(diffContent) {
+    return countDiffLines(diffContent, () => false);
+}
+/**
+ * {@link countNonBinaryDiffLines} with whole file sections left out of
+ * `textLines` when `isExcluded` names their path (registration files).
+ */
+function countDiffLines(diffContent, isExcluded) {
+    const lines = diffContent.split('\n');
+    if (lines[lines.length - 1] === '')
+        lines.pop();
+    const total = lines.length;
+    let uncounted = 0;
+    let inBinaryHunk = false;
+    let inExcluded = false;
+    for (const line of lines) {
+        if (line.startsWith('GIT binary patch')) {
+            inBinaryHunk = true;
+        }
+        else if (line.startsWith('diff --git ')) {
+            inBinaryHunk = false;
+            const header = parseDiffGitHeader(line);
+            inExcluded = header !== null && isExcluded(header.targetPath);
+        }
+        if (inBinaryHunk || inExcluded) {
+            uncounted++;
+        }
+    }
+    return { total, textLines: total - uncounted };
+}
+/**
+ * Decides which patch-size threshold tier applies to a patch.
+ * Exported so `runPatchLint` and the per-patch `lint` command can
+ * surface the tier choice to the operator *without* depending on
+ * `lintPatchSize`'s internal return shape.
+ *
+ * Precedence: test > branding (explicit) > branding (auto) > general.
+ * The test tier beats branding because a table-driven regression test
+ * is legitimately large independent of whether the patch also claims
+ * branding shape, and the test-tier thresholds are already more
+ * permissive than branding, so "tests beat branding" is the
+ * defensive-for-tests choice.
+ */
+export function resolvePatchSizeTier(filesAffected, patchTier) {
+    const allTests = filesAffected.length > 0 && filesAffected.every(isTestFile);
+    if (allTests)
+        return { tier: 'test' };
+    if (patchTier === 'branding')
+        return { tier: 'branding', source: 'explicit' };
+    if (isBrandingOnlyPatch(filesAffected))
+        return { tier: 'branding', source: 'auto' };
+    return { tier: 'general' };
+}
+/**
+ * The size thresholds a tier enforces, with `patchLint.patchSizeThresholds`
+ * applied when `config` is passed. Public-API companion to
+ * {@link resolvePatchSizeTier} / {@link countNonBinaryDiffLines} so
+ * consumers can build waiver-freshness checks against the same numbers
+ * `large-patch-lines` / `large-patch-files` fire on instead of mirroring
+ * them. Without `config` it returns the built-in defaults.
+ *
+ * @param tier - The tier to read
+ * @param config - The project configuration, whose overrides apply
+ */
+export function getPatchSizeThresholds(tier, config) {
+    return resolvePatchSizeThresholds(tier, config?.patchLint?.patchSizeThresholds);
+}
+/**
+ * Measures a patch under `patchLint.patchSizeMetric`.
+ *
+ * `diff` counts the non-binary lines of the unified diff, headers and
+ * context included. `addedCode` counts the added lines that carry code,
+ * judged on each file's post-image read from `repoDir` (a hunk can start
+ * inside a block comment, so the `+` lines alone cannot tell), and skips
+ * lines inside Furnace fragment expansions. Files matching
+ * `patchLint.patchSizeRegistrationFiles` count toward neither number.
+ *
+ * @param repoDir - Engine directory holding the post-images
+ * @param diffContent - The patch's unified diff
+ * @param filesAffected - The patch's files
+ * @param config - Project configuration
+ */
+export async function measurePatchSize(repoDir, diffContent, filesAffected, config) {
+    const globs = config.patchLint?.patchSizeRegistrationFiles ?? [];
+    const isRegistration = (file) => isPatchSizeRegistrationFile(file, globs);
+    const registrationFiles = filesAffected.filter(isRegistration).length;
+    const files = filesAffected.length - registrationFiles;
+    if (config.patchLint?.patchSizeMetric !== 'addedCode') {
+        const lines = countDiffLines(diffContent, isRegistration).textLines;
+        return { metric: 'diff', lines, testLines: 0, files, registrationFiles };
+    }
+    let lines = 0;
+    let testLines = 0;
+    for (const section of parseDiffSections(diffContent)) {
+        if (section.isBinary || isRegistration(section.targetPath))
+            continue;
+        const counted = await countAddedCodeLines(repoDir, section);
+        lines += counted;
+        if (isTestFile(section.targetPath))
+            testLines += counted;
+    }
+    return { metric: 'addedCode', lines, testLines, files, registrationFiles };
+}
+/**
+ * Counts one section's added lines that carry code in the post-image.
+ * Without a readable post-image, every non-blank added line counts: the
+ * upper bound, so a missing file never shrinks the measurement.
+ */
+async function countAddedCodeLines(repoDir, section) {
+    const path = join(repoDir, section.targetPath);
+    const mask = (await pathExists(path))
+        ? codeLineMask(section.targetPath, await readText(path)).code
+        : undefined;
+    let count = 0;
+    for (const hunk of section.hunks) {
+        let newLine = hunk.newStart;
+        for (const line of hunk.lines) {
+            if (line.startsWith('\\') || line.startsWith('-'))
+                continue;
+            if (line.startsWith('+')) {
+                const isCode = mask ? mask[newLine - 1] === true : line.slice(1).trim() !== '';
+                if (isCode)
+                    count++;
+            }
+            newLine++;
+        }
+    }
+    return count;
+}
+function bandFor(count, thresholds) {
+    if (thresholds.error !== null && count > thresholds.error)
+        return 'error';
+    if (count > thresholds.warning)
+        return 'warning';
+    if (count > thresholds.notice)
+        return 'notice';
+    return undefined;
+}
+/**
+ * Renders a patch-size finding. The notice band is advisory and says so;
+ * the warning band names what a `--max-warnings 0` gate does with it and
+ * where to tune it; the split hint rides on the bands that can fail a gate.
+ */
+function formatPatchSizeMessage(subject, band, thresholds) {
+    const errorPart = thresholds.error === null ? '' : `, error threshold: ${thresholds.error}`;
+    if (band === 'error') {
+        return `${subject} (error threshold: ${thresholds.error}). ${SPLIT_HINT}`;
+    }
+    if (band === 'notice') {
+        return (`${subject}, over the design target of ${thresholds.notice} ` +
+            `(warning threshold: ${thresholds.warning}${errorPart}). ` +
+            'Advisory; does not fail --max-warnings 0.');
+    }
+    return (`${subject} (warning threshold: ${thresholds.warning}${errorPart}). ` +
+        'Reported as a warning, which a gate running --max-warnings 0 treats as a failure; ' +
+        'tune "patchLint.patchSizeThresholds" if these limits are wrong for this project. ' +
+        SPLIT_HINT);
+}
+/**
+ * The line-count comparisons for a patch. Under `addedCode` a general-tier
+ * patch splits per class: test files against the test tier's lines,
+ * everything else against the general tier's, so a test riding with its
+ * subject is held to the same budget as a test-only patch.
+ */
+function lineChecks(measurement, tier, thresholds, config) {
+    const perClass = measurement.metric === 'addedCode' && tier === 'general';
+    if (!perClass || measurement.testLines === 0) {
+        return [{ count: measurement.lines, thresholds: thresholds.lines, scope: '' }];
+    }
+    return [
+        {
+            count: measurement.lines - measurement.testLines,
+            thresholds: thresholds.lines,
+            scope: ' in non-test files',
+        },
+        {
+            count: measurement.testLines,
+            thresholds: getPatchSizeThresholds('test', config).lines,
+            scope: ' in test files (test tier)',
+        },
+    ];
+}
+/**
+ * Checks patch size against the tier's thresholds.
+ *
+ * @param filesAffected - Files touched by the patch
+ * @param measured - The {@link measurePatchSize} result, or a bare
+ *   non-binary diff line count (the `diff` metric over every file)
+ * @param patchTier - Optional explicit tier override declared on
+ *   `PatchMetadata.tier`. When `"branding"`, forces the branding
+ *   thresholds regardless of `filesAffected`. Tests still win over
+ *   branding (precedence `test > branding > general`).
+ * @param config - Project configuration, for `patchLint.patchSizeThresholds`
+ */
+export function lintPatchSize(filesAffected, measured, patchTier, config) {
+    const measurement = typeof measured === 'number'
+        ? {
+            metric: 'diff',
+            lines: measured,
+            testLines: 0,
+            files: filesAffected.length,
+            registrationFiles: 0,
+        }
+        : measured;
+    const issues = [];
+    // Both rules read off the same decision so the file-count and line-count
+    // rules cannot disagree about which tier applies.
+    const decision = resolvePatchSizeTier(filesAffected, patchTier);
+    const thresholds = getPatchSizeThresholds(decision.tier, config);
+    const filesBand = bandFor(measurement.files, thresholds.files);
+    if (filesBand !== undefined) {
+        const registration = measurement.registrationFiles > 0
+            ? ` (not counting ${measurement.registrationFiles} registration file(s))`
+            : '';
+        issues.push({
+            file: AGGREGATE_PATCH_FILE,
+            check: 'large-patch-files',
+            message: formatPatchSizeMessage(`Patch affects ${measurement.files} files${registration}`, filesBand, thresholds.files),
+            severity: filesBand,
+            measurement: measurement.files,
+        });
+    }
+    for (const check of lineChecks(measurement, decision.tier, thresholds, config)) {
+        const band = bandFor(check.count, check.thresholds);
+        if (band === undefined)
+            continue;
+        const subject = measurement.metric === 'addedCode'
+            ? `Patch adds ${check.count} code lines${check.scope}`
+            : `Patch is ${check.count} lines`;
+        issues.push({
+            file: AGGREGATE_PATCH_FILE,
+            check: 'large-patch-lines',
+            message: formatPatchSizeMessage(subject, band, check.thresholds),
+            severity: band,
+            measurement: check.count,
+        });
+    }
+    return issues;
+}

package/dist/src/core/patch-lint-staged-registration.d.ts

@@ -1,4 +1,11 @@
-import type { PatchStagedRegistration } from '../types/commands/index.js';
+import type { PatchStagedForwardImport, PatchStagedRegistration } from '../types/commands/index.js';
+/**
+ * The `--reason` argument every printed `patch staged-dependency --add`
+ * remedy ends with. A declaration without a reason reads as unreviewed
+ * residue to a queue audit, so the paste-and-run command asks for one
+ * rather than inviting the operator to leave it out.
+ */
+export declare const STAGED_DEPENDENCY_REASON_PLACEHOLDER = "--reason '<why this patch references a file the owner creates later>'";
 /** A patch that creates a given path, with its position in the queue. */
 export interface NewFileOwner {
     filename: string;
@@ -59,3 +66,13 @@ export declare function describeRegistrationFailure(failure: StagedRegistrationF
  * forward-registration remedy leave the declaring patch red.
  */
 export declare function quoteRegistrationLine(line: string): string;
+/**
+ * The `staged-dependency-unused` fingerprint for one declaration on
+ * `holder`, the one spelling both the rule and the callers that need to
+ * recognise its findings (`patch split`/`move-files --create` deciding which
+ * declarations a move made unused) build it with.
+ *
+ * @param holder - Filename of the patch carrying the declaration
+ * @param declaration - Either declaration kind
+ */
+export declare function stagedDependencyUnusedFingerprint(holder: string, declaration: PatchStagedForwardImport | PatchStagedRegistration): string;

package/dist/src/core/patch-lint-staged-registration.js

@@ -12,6 +12,13 @@
  * `patch-lint-forward-registration.ts`, with no registrar or rule of its own.
  */
 import { basename } from 'node:path';
+/**
+ * The `--reason` argument every printed `patch staged-dependency --add`
+ * remedy ends with. A declaration without a reason reads as unreviewed
+ * residue to a queue audit, so the paste-and-run command asks for one
+ * rather than inviting the operator to leave it out.
+ */
+export const STAGED_DEPENDENCY_REASON_PLACEHOLDER = "--reason '<why this patch references a file the owner creates later>'";
 /**
  * Later-in-apply-order predicate shared by the forward-import scan, the
  * forward-registration rule and the registration validation: strictly
@@ -88,3 +95,16 @@ function isRegistrationLinePresent(entry, registration) {
 export function quoteRegistrationLine(line) {
     return line.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
 }
+/**
+ * The `staged-dependency-unused` fingerprint for one declaration on
+ * `holder`, the one spelling both the rule and the callers that need to
+ * recognise its findings (`patch split`/`move-files --create` deciding which
+ * declarations a move made unused) build it with.
+ *
+ * @param holder - Filename of the patch carrying the declaration
+ * @param declaration - Either declaration kind
+ */
+export function stagedDependencyUnusedFingerprint(holder, declaration) {
+    const matcher = 'specifier' in declaration ? declaration.specifier : `reg:${declaration.line}`;
+    return `staged-dependency-unused|${holder}|${declaration.file}|${matcher}|${declaration.creates}|${declaration.owner ?? ''}`;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * `token-scale`: values of governed CSS properties must resolve to a token
+ * on the property's scale (`patchLint.tokenScales`).
+ *
+ * The raw-colour and token-prefix rules stop a patch from inventing colours
+ * or referencing foreign custom properties, but say nothing about
+ * `gap: 7px`, `font-size: 13px` or `z-index: 9999`. Those are the values a
+ * design scale exists to remove, and without a rule they drift back one
+ * literal at a time. A scale names its properties, the token prefix that
+ * defines its steps, and the literals that are not steps at all (`0`,
+ * `auto`, a percentage).
+ *
+ * Judged per value atom, after peeling `var()` innermost-first so a fallback
+ * is held to the same scale as the token it backs: `var(--x-gap, 7px)` is a
+ * literal in disguise. `calc()`, `min()`, `max()` and `clamp()` are
+ * transparent, so a value built from tokens passes and one that adds a raw
+ * length does not. Unitless multipliers inside them are literals too and
+ * need an `allowLiterals` entry.
+ *
+ * Runs over CSS files the patch creates, not files it modifies: an upstream
+ * stylesheet is not the fork's to put on a scale. A line carrying
+ * `fireforge-ignore: token-scale` is skipped.
+ */
+import type { PatchLintIssue } from '../types/commands/index.js';
+import type { PatchLintTokenScale } from '../types/config.js';
+/**
+ * Returns the first atom of `value` that is off `scale`, or undefined when
+ * every atom resolves to the scale.
+ */
+export declare function findOffScaleAtom(value: string, scale: PatchLintTokenScale): string | undefined;
+/**
+ * Lints one patch-created CSS file against the configured scales.
+ *
+ * @param file - Engine-relative path, for the issue
+ * @param css - The file's full content
+ * @param scales - `patchLint.tokenScales`
+ * @returns One `token-scale` error per off-scale declaration
+ */
+export declare function lintTokenScales(file: string, css: string, scales: readonly PatchLintTokenScale[]): PatchLintIssue[];

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

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `token-scale`: values of governed CSS properties must resolve to a token
+ * on the property's scale (`patchLint.tokenScales`).
+ *
+ * The raw-colour and token-prefix rules stop a patch from inventing colours
+ * or referencing foreign custom properties, but say nothing about
+ * `gap: 7px`, `font-size: 13px` or `z-index: 9999`. Those are the values a
+ * design scale exists to remove, and without a rule they drift back one
+ * literal at a time. A scale names its properties, the token prefix that
+ * defines its steps, and the literals that are not steps at all (`0`,
+ * `auto`, a percentage).
+ *
+ * Judged per value atom, after peeling `var()` innermost-first so a fallback
+ * is held to the same scale as the token it backs: `var(--x-gap, 7px)` is a
+ * literal in disguise. `calc()`, `min()`, `max()` and `clamp()` are
+ * transparent, so a value built from tokens passes and one that adds a raw
+ * length does not. Unitless multipliers inside them are literals too and
+ * need an `allowLiterals` entry.
+ *
+ * Runs over CSS files the patch creates, not files it modifies: an upstream
+ * stylesheet is not the fork's to put on a scale. A line carrying
+ * `fireforge-ignore: token-scale` is skipped.
+ */
+import { escapeRegex } from '../utils/regex.js';
+const IGNORE_MARKER = 'fireforge-ignore: token-scale';
+/** CSS-wide keywords: never a step on any scale, always legal. */
+const CSS_WIDE_KEYWORDS = new Set(['inherit', 'initial', 'unset', 'revert', 'revert-layer']);
+const TOKEN_PLACEHOLDER = '\u0000token\u0000';
+/** Exact name, or a `*`-suffixed prefix. */
+function matchesName(name, patterns) {
+    return patterns.some((pattern) => pattern.endsWith('*') ? name.startsWith(pattern.slice(0, -1)) : name === pattern);
+}
+function matchesLiteral(atom, patterns) {
+    return patterns.some((pattern) => new RegExp(`^${pattern.split('*').map(escapeRegex).join('.*')}$`).test(atom));
+}
+/**
+ * Returns the first atom of `value` that is off `scale`, or undefined when
+ * every atom resolves to the scale.
+ */
+export function findOffScaleAtom(value, scale) {
+    let rest = value.replace(/!\s*important\s*$/i, '');
+    const varPattern = /var\(\s*(--[\w-]+)\s*(?:,([^()]*))?\)/;
+    for (let match = varPattern.exec(rest); match !== null; match = varPattern.exec(rest)) {
+        const name = match[1] ?? '';
+        if (!name.startsWith(scale.prefix) && !matchesName(name, scale.allow ?? [])) {
+            return `var(${name})`;
+        }
+        const fallback = match[2];
+        if (fallback !== undefined && fallback.trim() !== '') {
+            const offending = findOffScaleAtom(fallback, scale);
+            if (offending !== undefined)
+                return offending;
+        }
+        rest = `${rest.slice(0, match.index)} ${TOKEN_PLACEHOLDER} ${rest.slice(match.index + match[0].length)}`;
+    }
+    const atoms = rest
+        .replace(/\b(?:calc|min|max|clamp)\(/gi, ' ')
+        .replace(/[(),]/g, ' ')
+        .split(/\s+/)
+        .filter((atom) => atom !== '' && !['+', '-', '*', '/'].includes(atom));
+    return atoms.find((atom) => atom !== TOKEN_PLACEHOLDER &&
+        !CSS_WIDE_KEYWORDS.has(atom.toLowerCase()) &&
+        !matchesLiteral(atom, scale.allowLiterals ?? []));
+}
+/** Blanks block comments, keeping newlines so offsets map to lines. */
+function maskComments(css) {
+    return css.replace(/\/\*[\s\S]*?\*\//g, (comment) => comment.replace(/[^\n]/g, ' '));
+}
+/**
+ * Lints one patch-created CSS file against the configured scales.
+ *
+ * @param file - Engine-relative path, for the issue
+ * @param css - The file's full content
+ * @param scales - `patchLint.tokenScales`
+ * @returns One `token-scale` error per off-scale declaration
+ */
+export function lintTokenScales(file, css, scales) {
+    if (scales.length === 0)
+        return [];
+    const rawLines = css.split('\n');
+    const masked = maskComments(css);
+    const issues = [];
+    const declaration = /(^|[{;\s])([a-zA-Z][a-zA-Z-]*)\s*:\s*([^;{}]*)/g;
+    for (let match = declaration.exec(masked); match !== null; match = declaration.exec(masked)) {
+        const property = (match[2] ?? '').toLowerCase();
+        const value = (match[3] ?? '').trim();
+        const scale = scales.find((candidate) => matchesName(property, candidate.properties));
+        if (scale === undefined || value === '')
+            continue;
+        const start = match.index + (match[1] ?? '').length;
+        const line = masked.slice(0, start).split('\n').length;
+        if ((rawLines[line - 1] ?? '').includes(IGNORE_MARKER))
+            continue;
+        const atom = findOffScaleAtom(value, scale);
+        if (atom === undefined)
+            continue;
+        issues.push({
+            file,
+            check: 'token-scale',
+            fingerprint: `token-scale:${file}:${property}:${value}`,
+            message: `Line ${String(line)}: ${property}: ${value} is off the ${scale.prefix}* scale ` +
+                `("${atom}"). Use a ${scale.prefix}* token, or list a reviewed exception in ` +
+                `patchLint.tokenScales (allowLiterals / allow) or mark the line "${IGNORE_MARKER}".`,
+            severity: 'error',
+        });
+    }
+    return issues;
+}