@hominis/fireforge 0.49.2 → 0.51.0

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

@@ -20,7 +20,8 @@ import { collectNewFileCreatorsByPath } from './patch-lint-creators.js';
 import { detectNewFilesInDiff, extractAddedLinesPerFile } from './patch-lint-diff.js';
 import { lintPatchQueueForwardRegistrations } from './patch-lint-forward-registration.js';
 import { lintPatchQueueModuleRegistrations } from './patch-lint-module-registration.js';
-import { describeRegistrationFailure, findStagedRegistrationFailure, isLaterOwner, quoteRegistrationLine, } from './patch-lint-staged-registration.js';
+import { describeRegistrationFailure, findStagedRegistrationFailure, isLaterOwner, quoteRegistrationLine, STAGED_DEPENDENCY_REASON_PLACEHOLDER, stagedDependencyUnusedFingerprint, } from './patch-lint-staged-registration.js';
+import { lintTokenScaleFloors } from './patch-lint-token-scale.js';
 import { loadPatchesManifest } from './patch-manifest-io.js';
 import { categoryRangeForOrder, categoryRangeLabel } from './patch-policy.js';
 import { extractNewFileContentsFromDiff } from './patch-transform.js';
@@ -88,6 +89,9 @@ export async function buildPatchQueueContext(patchesDir, config) {
         ...(config?.patchLint?.forwardRegistration !== undefined
             ? { forwardRegistration: config.patchLint.forwardRegistration }
             : {}),
+        ...(config?.patchLint?.tokenScales !== undefined
+            ? { tokenScales: config.patchLint.tokenScales }
+            : {}),
     };
 }
 // The creators map (split out of `lintPatchQueueDuplicateCreations` so
@@ -493,13 +497,21 @@ export function lintPatchQueueForwardImports(ctx) {
         const stagedCommands = laterOwners
             .map((o) => `fireforge patch staged-dependency ${entry.filename} --add ` +
             `--file ${sitePath} --specifier "${specifier}" ` +
-            `--creates ${o.fullPath} --owner ${o.filename}`)
+            `--creates ${o.fullPath} --owner ${o.filename} ${STAGED_DEPENDENCY_REASON_PLACEHOLDER}`)
             .join('; ');
         issues.push({
             file: sitePath,
             check: 'forward-import',
             patches: [entry.filename],
             fingerprint: `forward-import|${sitePath}|${cleaned}|${fingerprintOwners}`,
+            stagedDeclarations: laterOwners.map((o) => ({
+                patch: entry.filename,
+                kind: 'import',
+                file: sitePath,
+                specifier,
+                creates: o.fullPath,
+                owner: o.filename,
+            })),
             message: `${sitePath} in ${entry.filename} imports "${specifier}", ` +
                 `but the matching new file is created by a later patch: ${ownersSummary}. ` +
                 'Reorder the patches so the dependency is created first, move the import ' +
@@ -518,7 +530,7 @@ export function lintPatchQueueForwardImports(ctx) {
                 file: dependency.file,
                 check: 'staged-dependency-unused',
                 patches: [entry.filename],
-                fingerprint: `staged-dependency-unused|${entry.filename}|${dependency.file}|${dependency.specifier}|${dependency.creates}|${dependency.owner ?? ''}`,
+                fingerprint: stagedDependencyUnusedFingerprint(entry.filename, dependency),
                 message: `${entry.filename} declares a staged forward import from ${dependency.file} ` +
                     `to "${dependency.specifier}" / ${dependency.creates}, but that exact forward dependency was not found. ` +
                     'Remove the stale declaration with "fireforge patch staged-dependency --remove" or update it to match the current queue.',
@@ -541,7 +553,7 @@ export function lintPatchQueueForwardImports(ctx) {
                 file: registration.file,
                 check: 'staged-dependency-unused',
                 patches: [entry.filename],
-                fingerprint: `staged-dependency-unused|${entry.filename}|${registration.file}|reg:${registration.line}|${registration.creates}|${registration.owner ?? ''}`,
+                fingerprint: stagedDependencyUnusedFingerprint(entry.filename, registration),
                 message: `${entry.filename} declares a staged registration in ${registration.file} ` +
                     `("${registration.line}") for ${registration.creates}, but ${describeRegistrationFailure(failure)} ` +
                     'Remove the stale declaration with: ' +
@@ -573,5 +585,6 @@ export function lintPatchQueue(ctx) {
         ...lintPatchQueueModuleRegistrations(ctx),
         ...lintPatchQueueForwardRegistrations(ctx),
         ...lintPatchQueueBinaryBodies(ctx),
+        ...lintTokenScaleFloors(ctx.entries.flatMap((entry) => [...entry.newFiles]), ctx.tokenScales ?? []),
     ];
 }

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

@@ -1,6 +1,6 @@
 /**
- * CSS patch-lint rules: introduced raw color values and non-tokenized
- * custom-property references.
+ * CSS patch-lint rules: introduced raw color values, non-tokenized
+ * custom-property references, and (opt-in) token scales over created CSS.
  *
  * Split out of `patch-lint.ts` so each rule family stays within the
  * per-file line budget. `patch-lint.ts` re-exports `lintPatchedCss` so
@@ -8,6 +8,12 @@
  */
 import type { PatchLintIssue } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
+/**
+ * Masks CSS block comments with spaces, preserving newlines so line
+ * numbers stay stable. An unclosed trailing `/*` is masked to EOF,
+ * matching how a CSS parser treats it.
+ */
+export declare function maskCssComments(source: string): string;
 /**
  * Lints patched CSS files for introduced raw color values and non-tokenized
  * custom properties.

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

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * CSS patch-lint rules: introduced raw color values and non-tokenized
- * custom-property references.
+ * CSS patch-lint rules: introduced raw color values, non-tokenized
+ * custom-property references, and (opt-in) token scales over created CSS.
  *
  * Split out of `patch-lint.ts` so each rule family stays within the
  * per-file line budget. `patch-lint.ts` re-exports `lintPatchedCss` so
@@ -13,7 +13,8 @@ import { pathExists, readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { hasRawCssColors } from '../utils/regex.js';
 import { loadFurnaceConfig } from './furnace-config.js';
-import { extractAddedLineNumbersPerFile, extractAddedLinesPerFile } from './patch-lint-diff.js';
+import { detectNewFilesInDiff, extractAddedLineNumbersPerFile, extractAddedLinesPerFile, } from './patch-lint-diff.js';
+import { lintTokenScales } from './patch-lint-token-scale.js';
 /**
  * Loads the furnace token-prefix lint inputs gracefully. Returns
  * undefined (skipping the token-prefix check) when furnace.json cannot
@@ -41,17 +42,21 @@ async function loadCssTokenContext(repoDir) {
  * numbers stay stable. An unclosed trailing `/*` is masked to EOF,
  * matching how a CSS parser treats it.
  */
-function maskCssComments(source) {
-    const masked = source.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
-    const openerIndex = masked.indexOf('/*');
-    if (openerIndex === -1)
-        return masked;
-    return (masked.slice(0, openerIndex) +
-        masked
-            .slice(openerIndex)
-            .split('\n')
-            .map((line) => ' '.repeat(line.length))
-            .join('\n'));
+export function maskCssComments(source) {
+    // Linear indexOf scan rather than a lazy `/\*[\s\S]*?\*\/` regex: with
+    // many openers and no closer, the regex retries from every `/*` to EOF
+    // (quadratic in file size).
+    let masked = '';
+    let cursor = 0;
+    for (;;) {
+        const open = source.indexOf('/*', cursor);
+        if (open === -1)
+            return masked + source.slice(cursor);
+        const close = source.indexOf('*/', open + 2);
+        const end = close === -1 ? source.length : close + 2;
+        masked += source.slice(cursor, open) + source.slice(open, end).replace(/[^\n]/g, ' ');
+        cursor = end;
+    }
 }
 const RAW_COLOR_IGNORE_MARKER = 'fireforge-ignore: raw-color-value';
 /**
@@ -197,6 +202,9 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
     const addedLineNumbersByFile = diffContent
         ? extractAddedLineNumbersPerFile(diffContent)
         : undefined;
+    // `patchLint.tokenScales` governs only CSS the patch creates.
+    const tokenScales = config?.patchLint?.tokenScales ?? [];
+    const createdFiles = diffContent && tokenScales.length > 0 ? detectNewFilesInDiff(diffContent) : new Set();
     for (const file of cssFiles) {
         const filePath = join(repoDir, file);
         if (!(await pathExists(filePath)))
@@ -213,6 +221,8 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
             issues,
         });
         checkTokenPrefixViolations(file, cssContent, addedLinesByFile, tokenContext, issues);
+        if (createdFiles.has(file))
+            issues.push(...lintTokenScales(file, rawCss, tokenScales));
     }
     return issues;
 }

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

@@ -13,7 +13,9 @@
  * lines failed a gate with a message calling 750 soft. The message below
  * says what the band is (a warning) and what a zero-warning gate does with
  * it, and the thresholds are now tunable, so a project whose file-size
- * policy differs has a dial instead of an argument.
+ * policy differs has a dial instead of an argument. The notice band is the
+ * design target: advisory, and its message says so rather than borrowing
+ * the warning band's gate sentence.
  */
 import type { PatchLintFileSizeThresholds } from '../types/config.js';
 /** A fully resolved threshold triple. */
@@ -38,14 +40,19 @@ export declare function resolveFileSizeThresholds(overrides: PatchLintFileSizeTh
 /**
  * Renders the `file-too-large` message for a given band.
  *
- * The `warning` and `notice` bands name the gate consequence explicitly:
- * the number is advisory to patch-lint and blocking to a `--max-warnings 0`
- * gate, and an operator deciding whether to decompose a file needs to know
- * which of those they are looking at.
+ * Each band says what it means for a gate. A notice is over the design
+ * target and advisory: it never fails `--max-warnings 0`, and saying it
+ * did once got a test suite split for nothing. A warning is what a
+ * zero-warning gate fails on, so it names that and the dial. Only the
+ * error band suggests splitting, because a test-file split pushes against
+ * one suite per subject and should not be the default advice below it.
+ * Every band names the unit, which matters once `fileSizeMetric` makes
+ * code lines a choice.
  */
 export declare function formatFileTooLargeMessage(args: {
     label: string;
     lineCount: number;
+    unit: 'lines' | 'code lines';
     thresholds: ResolvedFileSizeTier;
     band: 'notice' | 'warning' | 'error';
     verb: string;

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

@@ -14,7 +14,9 @@
  * lines failed a gate with a message calling 750 soft. The message below
  * says what the band is (a warning) and what a zero-warning gate does with
  * it, and the thresholds are now tunable, so a project whose file-size
- * policy differs has a dial instead of an argument.
+ * policy differs has a dial instead of an argument. The notice band is the
+ * design target: advisory, and its message says so rather than borrowing
+ * the warning band's gate sentence.
  */
 /** Built-in defaults, per file class. */
 export const DEFAULT_FILE_SIZE_THRESHOLDS = {
@@ -36,18 +38,27 @@ export function resolveFileSizeThresholds(overrides, isTest) {
 /**
  * Renders the `file-too-large` message for a given band.
  *
- * The `warning` and `notice` bands name the gate consequence explicitly:
- * the number is advisory to patch-lint and blocking to a `--max-warnings 0`
- * gate, and an operator deciding whether to decompose a file needs to know
- * which of those they are looking at.
+ * Each band says what it means for a gate. A notice is over the design
+ * target and advisory: it never fails `--max-warnings 0`, and saying it
+ * did once got a test suite split for nothing. A warning is what a
+ * zero-warning gate fails on, so it names that and the dial. Only the
+ * error band suggests splitting, because a test-file split pushes against
+ * one suite per subject and should not be the default advice below it.
+ * Every band names the unit, which matters once `fileSizeMetric` makes
+ * code lines a choice.
  */
 export function formatFileTooLargeMessage(args) {
-    const { label, lineCount, thresholds, band, verb } = args;
+    const { label, lineCount, unit, thresholds, band, verb } = args;
+    const measured = `${label} has ${lineCount} ${unit}`;
     if (band === 'error') {
-        return `${label} has ${lineCount} lines (error threshold: ${thresholds.error}). Consider ${verb}.`;
+        return `${measured} (error threshold: ${thresholds.error}). Consider ${verb}.`;
     }
-    return (`${label} has ${lineCount} lines (warning threshold: ${thresholds.warning}, ` +
-        `error threshold: ${thresholds.error}). Consider ${verb}. ` +
-        `Reported as a ${band}, which a gate running --max-warnings 0 treats as a failure; ` +
-        `tune "patchLint.fileSizeThresholds" if these limits are wrong for this project.`);
+    const limits = `(warning threshold: ${thresholds.warning}, error threshold: ${thresholds.error})`;
+    if (band === 'notice') {
+        return (`${measured}, over the design target of ${thresholds.notice} ${limits}. ` +
+            'Advisory; does not fail --max-warnings 0.');
+    }
+    return (`${measured} ${limits}. ` +
+        'Reported as a warning, which a gate running --max-warnings 0 treats as a failure; ' +
+        'tune "patchLint.fileSizeThresholds" if these limits are wrong for this project.');
 }

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

@@ -24,6 +24,29 @@ export interface ForwardRegistration {
     /** Paste-and-run declaration that records the stage as intentional. */
     command: string;
 }
+/**
+ * jar target → packaged source, over every jar.mn line the queue adds. Only
+ * exact (wildcard-free) sources can back a chrome URL lookup.
+ */
+export declare function buildJarTargetIndex(entries: readonly PatchQueueForwardRegistrationEntry[]): Map<string, string>;
+/** True for a jar.mn, moz.build or test manifest, the carriers {@link resolveCarrierReferences} reads. */
+export declare function isRegistrationCarrier(file: string): boolean;
+/**
+ * The engine paths named by the lines of one jar.mn, moz.build or test
+ * manifest, resolved the way this rule resolves them. Exported for a caller
+ * outside the queue lint (re-export's adjacency belt asks which files a
+ * patch's added registration lines name). A `customElements.js` chrome URL
+ * resolves only through the queue's jar.mn index, so it is not covered.
+ *
+ * @param rawPath - Engine-relative path of the carrier
+ * @param content - The carrier lines to read (typically the added ones)
+ * @returns One entry per resolvable token. `exact` is set when it has no wildcard.
+ */
+export declare function resolveCarrierReferences(rawPath: string, content: string): {
+    line: string;
+    exact?: string;
+    matches: (candidate: string) => boolean;
+}[];
 /** The discharge command, in the exact shape the support-files arm prints. */
 export declare function formatRegistrationDeclaration(patch: string, file: string, line: string, creates: string, owner: string): string;
 /**

package/dist/src/core/patch-lint-forward-registration-extended.js

@@ -28,7 +28,7 @@ import { basename, dirname, posix } from 'node:path';
 import { normalizePathSlashes } from '../utils/paths.js';
 import { escapeRegex } from '../utils/regex.js';
 import { parseJarMnEntry } from './build-audit-registration.js';
-import { isLaterOwner, quoteRegistrationLine } from './patch-lint-staged-registration.js';
+import { isLaterOwner, quoteRegistrationLine, STAGED_DEPENDENCY_REASON_PLACEHOLDER, } from './patch-lint-staged-registration.js';
 const TEST_MANIFEST_BASENAMES = new Set([
     'xpcshell.toml',
     'xpcshell.ini',
@@ -116,7 +116,7 @@ function testManifestReferences(file, content) {
  * jar target → packaged source, over every jar.mn line the queue adds. Only
  * exact (wildcard-free) sources can back a chrome URL lookup.
  */
-function buildJarTargetIndex(entries) {
+export function buildJarTargetIndex(entries) {
     const index = new Map();
     for (const entry of entries) {
         for (const [file, content] of [...entry.newFiles, ...entry.modifiedFileAdditions]) {
@@ -153,20 +153,45 @@ function customElementsReferences(file, content, jarTargets) {
     }
     return refs;
 }
+/** True for a jar.mn, moz.build or test manifest, the carriers {@link resolveCarrierReferences} reads. */
+export function isRegistrationCarrier(file) {
+    const name = basename(normalizePathSlashes(file));
+    return name === 'jar.mn' || name === 'moz.build' || TEST_MANIFEST_BASENAMES.has(name);
+}
+function carrierReferences(file, content) {
+    const name = basename(file);
+    if (name === 'jar.mn')
+        return jarMnReferences(file, content);
+    if (name === 'moz.build')
+        return mozBuildReferences(file, content);
+    if (TEST_MANIFEST_BASENAMES.has(name))
+        return testManifestReferences(file, content);
+    return [];
+}
+/**
+ * The engine paths named by the lines of one jar.mn, moz.build or test
+ * manifest, resolved the way this rule resolves them. Exported for a caller
+ * outside the queue lint (re-export's adjacency belt asks which files a
+ * patch's added registration lines name). A `customElements.js` chrome URL
+ * resolves only through the queue's jar.mn index, so it is not covered.
+ *
+ * @param rawPath - Engine-relative path of the carrier
+ * @param content - The carrier lines to read (typically the added ones)
+ * @returns One entry per resolvable token. `exact` is set when it has no wildcard.
+ */
+export function resolveCarrierReferences(rawPath, content) {
+    return carrierReferences(normalizePathSlashes(rawPath), content);
+}
 function referencesFor(entry, jarTargets) {
     const refs = [];
     for (const [rawPath, content] of [...entry.newFiles, ...entry.modifiedFileAdditions]) {
         const file = normalizePathSlashes(rawPath);
-        const name = basename(file);
-        if (name === 'jar.mn')
-            refs.push(...jarMnReferences(file, content));
-        else if (name === 'moz.build')
-            refs.push(...mozBuildReferences(file, content));
-        else if (TEST_MANIFEST_BASENAMES.has(name))
-            refs.push(...testManifestReferences(file, content));
-        else if (name === 'customElements.js') {
+        if (basename(file) === 'customElements.js') {
             refs.push(...customElementsReferences(file, content, jarTargets));
         }
+        else {
+            refs.push(...carrierReferences(file, content));
+        }
     }
     return refs;
 }
@@ -178,7 +203,7 @@ function isDeclared(entry, file, created) {
 export function formatRegistrationDeclaration(patch, file, line, creates, owner) {
     return (`fireforge patch staged-dependency ${patch} --add --kind registration ` +
         `--file ${file} --line "${quoteRegistrationLine(line)}" ` +
-        `--creates ${creates} --owner ${owner}`);
+        `--creates ${creates} --owner ${owner} ${STAGED_DEPENDENCY_REASON_PLACEHOLDER}`);
 }
 /**
  * Finds every undeclared forward registration in the extended carriers:

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

@@ -243,6 +243,16 @@ export function lintPatchQueueForwardRegistrations(ctx) {
             check: 'forward-registration',
             patches: [found.patch],
             fingerprint: `forward-registration|${found.patch}|${found.file}|${found.token}|${found.creates}|${found.owner}`,
+            stagedDeclarations: [
+                {
+                    patch: found.patch,
+                    kind: 'registration',
+                    file: found.file,
+                    line: found.line,
+                    creates: found.creates,
+                    owner: found.owner,
+                },
+            ],
             message: `${found.file} in ${found.patch} registers "${found.token}" ${KIND_PHRASES[found.kind]}, ` +
                 `but ${found.creates} is created by the later patch ${found.owner}. ` +
                 'Applying the queue up to this patch leaves the registration dangling. ' +

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

@@ -0,0 +1,196 @@
+/**
+ * `PatchMetadata.lintIgnore` entries and the waiver filter they drive.
+ *
+ * An entry is either a bare check ID, which suppresses that rule at any
+ * size, or a ceiling `{ rule, max, reason }`, which suppresses a size rule
+ * only while its measurement is at or below `max`. The bare form let a
+ * waived file grow without bound: nothing re-examined the waiver once it
+ * was written, so a 950-line file waived at review time was still waived at
+ * 2,000 lines. The ceiling makes growth past the reviewed size fire again,
+ * and lets a gate say when the waiver is no longer needed at all.
+ *
+ * Its own module so every caller that turns a manifest list into a filter
+ * (export, re-export, per-patch and aggregate lint, split, move-files)
+ * shares one reading of an entry, and so `patch-lint.ts` only calls into it.
+ */
+import type { LintIgnoreCeiling, LintIgnoreEntry, PatchLintIssue, PatchSizeShare } from '../types/commands/index.js';
+/**
+ * The size rules whose findings carry a `measurement`, and therefore the
+ * only rules a ceiling can bound. A ceiling on any other rule could never
+ * suppress anything, so the manifest validator refuses it.
+ */
+export declare const LINT_IGNORE_CEILING_RULES: readonly string[];
+/**
+ * A waiver filter: the bare check IDs as a set (so a plain `Set<string>`
+ * still satisfies the type), plus the ceilings keyed by {@link ceilingKey}.
+ *
+ * Bare IDs and ceilings are kept apart on purpose. A caller that only knows
+ * `has()` treats a ceiling-waived rule as not waived, which fails closed.
+ */
+export type LintIgnoreChecks = ReadonlySet<string> & {
+    readonly ceilings?: ReadonlyMap<string, LintIgnoreCeiling>;
+};
+/** Narrows an entry to the ceiling form. */
+export declare function isLintIgnoreCeiling(entry: LintIgnoreEntry): entry is LintIgnoreCeiling;
+/** The check ID an entry names, whatever its form. */
+export declare function lintIgnoreRule(entry: LintIgnoreEntry): string;
+/**
+ * One-word rendering for summaries and dry runs: `file-too-large<=1200`,
+ * `large-patch-lines[test]<=900`.
+ */
+export declare function formatLintIgnoreEntry(entry: LintIgnoreEntry): string;
+/** Renders a list for messages, `(empty)` when there is nothing to show. */
+export declare function formatLintIgnoreList(entries: readonly LintIgnoreEntry[]): string;
+/**
+ * Validates a raw `lintIgnore` value from `patches.json`.
+ *
+ * Bare strings keep their historical leniency (any ID, duplicates collapse
+ * later). A ceiling must name a measured size rule, carry a positive
+ * integer `max` and a non-empty `reason`, and must be the only entry for
+ * its rule: a bare ID beside a ceiling for the same rule would make the
+ * ceiling dead, and two ceilings would leave the effective one ambiguous.
+ * The one exception is `large-patch-lines`, which may carry one ceiling
+ * per `share` instead of a single share-less one. `meta` must be a JSON
+ * object and is kept verbatim.
+ *
+ * @param raw - The value under `lintIgnore`
+ * @param label - Field label for error messages, e.g. `patches[3].lintIgnore`
+ * @returns The validated entries
+ * @throws Error naming the offending element
+ */
+export declare function parseLintIgnoreEntries(raw: unknown, label: string): LintIgnoreEntry[];
+/**
+ * Builds the waiver filter for a patch's entries.
+ *
+ * @param entries - `PatchMetadata.lintIgnore`, possibly merged with CLI flags
+ * @returns The filter, or undefined when there is nothing to waive
+ */
+export declare function buildLintIgnoreChecks(entries: readonly LintIgnoreEntry[] | undefined): LintIgnoreChecks | undefined;
+/**
+ * Canonical string form of a filter for the per-patch lint cache's waiver
+ * comparison: bare IDs as themselves, ceilings as `rule<=max`.
+ */
+export declare function lintIgnoreCacheTokens(checks: LintIgnoreChecks | undefined): string[];
+/**
+ * Unions CLI-flag check IDs into an existing list, the append-only
+ * semantics `export` / `re-export --lint-ignore` have always had. A bare ID
+ * whose rule already has an entry (bare or ceiling) is a no-op: widening a
+ * reviewed ceiling to an unbounded waiver is `patch lint-ignore`'s job, where
+ * it is confirmed explicitly. Ceilings deduplicate by rule and share, so a
+ * rule's per-share ceilings all survive.
+ *
+ * @returns The merged list, or undefined when it is empty
+ */
+export declare function mergeLintIgnoreIds(existing: readonly LintIgnoreEntry[] | undefined, ids: readonly string[] | undefined): LintIgnoreEntry[] | undefined;
+/**
+ * Adds or replaces entries, the `patch lint-ignore --add` semantics: an
+ * explicit `--add <rule>` turns a rule's ceilings into a bare waiver,
+ * `--add <rule> --max <n>` sets or moves the rule's ceiling, and a
+ * share-scoped ceiling replaces only its own share (plus any bare or
+ * share-less entry for the rule, which it would contradict).
+ *
+ * @returns The new list, or undefined when it is empty
+ */
+export declare function upsertLintIgnoreEntries(existing: readonly LintIgnoreEntry[], additions: readonly LintIgnoreEntry[]): LintIgnoreEntry[] | undefined;
+/** Removes every entry naming one of `rules`. Undefined when nothing is left. */
+export declare function removeLintIgnoreRules(existing: readonly LintIgnoreEntry[], rules: readonly string[]): LintIgnoreEntry[] | undefined;
+/** Entries present in `after` but not (identically) in `before`. */
+export declare function addedLintIgnoreEntries(before: readonly LintIgnoreEntry[], after: readonly LintIgnoreEntry[]): LintIgnoreEntry[];
+/**
+ * Splits issues into the ones that still surface and the ones a waiver
+ * drops.
+ *
+ * A bare ID drops every finding of its rule. A ceiling drops a finding only
+ * when it carries a measurement at or below `max`. Past the ceiling the
+ * finding surfaces at its own severity with the ceiling named, and a
+ * finding with no measurement surfaces too (fail closed).
+ */
+export declare function partitionLintIgnoredIssues(issues: readonly PatchLintIssue[], checks: LintIgnoreChecks | undefined): {
+    kept: PatchLintIssue[];
+    suppressed: PatchLintIssue[];
+};
+/** True when `checks` waives `issue` (see {@link partitionLintIgnoredIssues}). */
+export declare function isLintIgnored(issue: PatchLintIssue, checks: LintIgnoreChecks | undefined): boolean;
+/**
+ * Drops issues that a patch owning `issue.file` (via `filesAffected`)
+ * waives. Used where findings carry no patch scope of their own (aggregate
+ * `lint`). Each owner keeps its own filter, so a ceiling stays bounded by
+ * the patch that declared it instead of merging into a file-wide union; an
+ * issue is dropped when any owner waives it.
+ */
+export declare function filterLintIgnoredByOwners(issues: PatchLintIssue[], owners: ReadonlyArray<{
+    lintIgnore?: LintIgnoreEntry[];
+    filesAffected: readonly string[];
+} | null | undefined>): PatchLintIssue[];
+/** Where a ceiling stands against the patch's current measurements. */
+export type LintIgnoreCeilingState = 'within' | 'exceeded' | 'removable';
+/** One ceiling's standing, as `lint --per-patch --report` records it. */
+export interface LintIgnoreCeilingStatus {
+    rule: string;
+    max: number;
+    reason: string;
+    /** The share the ceiling bounds, when it is share-scoped. */
+    share?: PatchSizeShare;
+    /** The ceiling's `meta`, verbatim, when it has one. */
+    meta?: Record<string, unknown>;
+    /** Largest current measurement for the rule, null when none was taken. */
+    measurement: number | null;
+    /**
+     * `exceeded`: a warning- or error-band finding measured past `max` and
+     * surfaced. A notice never exceeds a ceiling: it gates nothing.
+     * `removable`: the rule no longer reaches its own warning band, so the
+     * waiver changes no gate and can be dropped.
+     * `within`: the waiver is doing its job.
+     */
+    state: LintIgnoreCeilingState;
+}
+/**
+ * One waiver's standing, bare or ceiling, as the report's
+ * `lintIgnoreWaivers` records it. A bare waiver has `max: null`; its
+ * `state` is `within` while the rule still finds something to suppress at
+ * warning band or above, and `removable` otherwise (informational: a bare
+ * waiver of a rule this lint does not run reads as removable too).
+ */
+export interface LintIgnoreWaiverStatus {
+    kind: 'bare' | 'ceiling';
+    rule: string;
+    max: number | null;
+    reason: string | null;
+    share?: PatchSizeShare;
+    meta?: Record<string, unknown>;
+    measurement: number | null;
+    state: LintIgnoreCeilingState;
+}
+/** Patch-level measurements a size rule falls back to when it did not fire. */
+interface PatchMeasurements {
+    lines: number;
+    files: number;
+}
+/**
+ * Evaluates each ceiling on a patch against the findings its lint produced
+ * (both surfaced and suppressed).
+ *
+ * @param entries - The patch's `lintIgnore`
+ * @param issues - Every finding of the patch's lint, surfaced and suppressed
+ * @param patchMeasurements - Patch-level measurements used when a
+ *   patch-size rule did not fire at all, so the report still shows the
+ *   current number
+ */
+export declare function evaluateLintIgnoreCeilings(entries: readonly LintIgnoreEntry[] | undefined, issues: readonly PatchLintIssue[], patchMeasurements: PatchMeasurements): LintIgnoreCeilingStatus[];
+/**
+ * Evaluates every waiver on a patch, bare IDs included, so a waiver audit
+ * reads each one's current measurement from the report instead of
+ * re-measuring bare waivers from `suppressedIssues`.
+ *
+ * @param entries - The patch's `lintIgnore`
+ * @param issues - Every finding of the patch's lint, surfaced and suppressed
+ * @param patchMeasurements - See {@link evaluateLintIgnoreCeilings}
+ */
+export declare function evaluateLintIgnoreWaivers(entries: readonly LintIgnoreEntry[] | undefined, issues: readonly PatchLintIssue[], patchMeasurements: PatchMeasurements): LintIgnoreWaiverStatus[];
+/**
+ * Notice-severity findings for ceilings that are no longer needed, so the
+ * waiver's removal is prompted by the tool that enforces it rather than
+ * discovered by hand.
+ */
+export declare function removableCeilingIssues(patchFilename: string, statuses: readonly LintIgnoreCeilingStatus[]): PatchLintIssue[];
+export {};