@hominis/fireforge 0.55.0 → 0.60.0

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

@@ -1,117 +0,0 @@
-/**
- * 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

@@ -1,331 +0,0 @@
-// 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) {
-        return [{ count: measurement.lines, thresholds: thresholds.lines, scope: '' }];
-    }
-    if (measurement.testLines === 0) {
-        return [
-            { count: measurement.lines, thresholds: thresholds.lines, scope: '', share: 'product' },
-        ];
-    }
-    return [
-        {
-            count: measurement.lines - measurement.testLines,
-            thresholds: thresholds.lines,
-            scope: ' in non-test files',
-            share: 'product',
-        },
-        {
-            count: measurement.testLines,
-            thresholds: getPatchSizeThresholds('test', config).lines,
-            scope: ' in test files (test tier)',
-            share: 'test',
-        },
-    ];
-}
-/**
- * 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,
-            ...(check.share !== undefined ? { share: check.share } : {}),
-        });
-    }
-    return issues;
-}

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

@@ -1,98 +0,0 @@
-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;
-    order: number;
-    fullPath: string;
-}
-/** The ordering fields `isLaterOwner` compares an owner against. */
-export interface QueuePosition {
-    filename: string;
-    order: number;
-}
-/**
- * Later-in-apply-order predicate shared by the forward-import scan, the
- * forward-registration rule and the registration validation: strictly
- * higher ordinal, or same ordinal with a lexicographically later filename
- * (the apply loop's tiebreak).
- *
- * @param owner - The creating patch
- * @param entry - The referencing patch
- * @returns True when `owner` applies after `entry`
- */
-export declare function isLaterOwner(owner: QueuePosition, entry: QueuePosition): boolean;
-/** The slice of a queue entry the registration validation reads. */
-export interface StagedRegistrationEntry extends QueuePosition {
-    newFiles: ReadonlyMap<string, string>;
-    modifiedFileAdditions: ReadonlyMap<string, string>;
-}
-/** Why a staged registration declaration failed validation. */
-export type StagedRegistrationFailure = {
-    kind: 'line-absent';
-} | {
-    kind: 'creates-unresolved';
-} | {
-    kind: 'owner-mismatch';
-    creators: readonly NewFileOwner[];
-};
-/**
- * Validates one registration-kind declaration against the patch content
- * and the queue, mirroring {@link findMatchingStagedDependency}: the
- * declared line must be added by this patch, `creates` must exactly match
- * a file a later-ordered patch creates (an earlier-only creator means the
- * dependency is already satisfied and the declaration is stale), and
- * `owner`, when set, must name one of those creating patches. Returns
- * undefined when valid.
- */
-export declare function findStagedRegistrationFailure(entry: StagedRegistrationEntry, registration: PatchStagedRegistration, createdFileIndex: Map<string, NewFileOwner[]>): StagedRegistrationFailure | undefined;
-/** Message tail for each {@link StagedRegistrationFailure} shape. */
-export declare function describeRegistrationFailure(failure: StagedRegistrationFailure): string;
-/**
- * Collapses whitespace runs and trims, so registration lines compare
- * whitespace-insensitively: a jar.mn line aligned with two spaces before its
- * `(source)` matches a declaration typed with one.
- *
- * @param line - Registration line as declared or as the patch adds it
- */
-export declare function normalizeRegistrationLine(line: string): string;
-/**
- * True when `line` (whitespace-insensitively, see
- * {@link normalizeRegistrationLine}) is among the lines the patch
- * introduces in `file`, either as a newly-created file's content or as
- * added lines to an existing file (where jar.mn / customElements.js /
- * actor-registration edits land).
- *
- * @param entry - The declaring patch's projected additions
- * @param file - Engine-relative path of the declaring file
- * @param line - The registration line
- */
-export declare function patchAddsRegistrationLine(entry: Pick<StagedRegistrationEntry, 'newFiles' | 'modifiedFileAdditions'>, file: string, line: string): boolean;
-/**
- * Renders `line` for the `--line "…"` argument of a paste-and-run
- * `patch staged-dependency` command.
- *
- * A registration line is quoted for the shell in the messages that print
- * the command, and a `support-files` element carries its own quotes
- * (`"file_tiles_find.html",` is what a multi-line TOML array adds). Without
- * escaping, the shell would eat them and the declaration would be written
- * with a line the patch never adds, the exact mismatch that made the
- * 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

@@ -1,128 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Validation of `--kind registration` staged-dependency declarations.
- *
- * Split out of `patch-lint-cross.ts` to keep that file inside the per-file
- * line budget, and because the forward-registration rule needs the same
- * apply-order predicate: two spellings of "later in the queue" would let the
- * rule that flags an undeclared registration and the rule that validates a
- * declared one disagree about the very same pair of patches.
- *
- * Exports helpers consumed by `patch-lint-cross.ts`,
- * `patch-lint-forward-registration.ts` and `patch staged-dependency`, 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
- * higher ordinal, or same ordinal with a lexicographically later filename
- * (the apply loop's tiebreak).
- *
- * @param owner - The creating patch
- * @param entry - The referencing patch
- * @returns True when `owner` applies after `entry`
- */
-export function isLaterOwner(owner, entry) {
-    return (owner.order > entry.order || (owner.order === entry.order && owner.filename > entry.filename));
-}
-/**
- * Validates one registration-kind declaration against the patch content
- * and the queue, mirroring {@link findMatchingStagedDependency}: the
- * declared line must be added by this patch, `creates` must exactly match
- * a file a later-ordered patch creates (an earlier-only creator means the
- * dependency is already satisfied and the declaration is stale), and
- * `owner`, when set, must name one of those creating patches. Returns
- * undefined when valid.
- */
-export function findStagedRegistrationFailure(entry, registration, createdFileIndex) {
-    if (!isRegistrationLinePresent(entry, registration))
-        return { kind: 'line-absent' };
-    const creators = (createdFileIndex.get(basename(registration.creates)) ?? []).filter((owner) => owner.fullPath === registration.creates && isLaterOwner(owner, entry));
-    if (creators.length === 0)
-        return { kind: 'creates-unresolved' };
-    if (registration.owner !== undefined &&
-        !creators.some((owner) => owner.filename === registration.owner)) {
-        return { kind: 'owner-mismatch', creators };
-    }
-    return undefined;
-}
-/** Message tail for each {@link StagedRegistrationFailure} shape. */
-export function describeRegistrationFailure(failure) {
-    switch (failure.kind) {
-        case 'line-absent':
-            return 'the patch does not add that line.';
-        case 'creates-unresolved':
-            return ('no later-ordered patch creates that file — the declaration is stale, ' +
-                'or the queue order no longer stages it.');
-        case 'owner-mismatch':
-            return `that file is created by ${failure.creators.map((o) => o.filename).join(', ')}, not the declared owner.`;
-    }
-}
-/**
- * Collapses whitespace runs and trims, so registration lines compare
- * whitespace-insensitively: a jar.mn line aligned with two spaces before its
- * `(source)` matches a declaration typed with one.
- *
- * @param line - Registration line as declared or as the patch adds it
- */
-export function normalizeRegistrationLine(line) {
-    return line.trim().replace(/\s+/g, ' ');
-}
-/**
- * True when `line` (whitespace-insensitively, see
- * {@link normalizeRegistrationLine}) is among the lines the patch
- * introduces in `file`, either as a newly-created file's content or as
- * added lines to an existing file (where jar.mn / customElements.js /
- * actor-registration edits land).
- *
- * @param entry - The declaring patch's projected additions
- * @param file - Engine-relative path of the declaring file
- * @param line - The registration line
- */
-export function patchAddsRegistrationLine(entry, file, line) {
-    const declared = normalizeRegistrationLine(line);
-    if (declared.length === 0)
-        return false;
-    const introduced = [entry.newFiles.get(file), entry.modifiedFileAdditions.get(file)];
-    return introduced.some((content) => content !== undefined &&
-        content.split('\n').some((added) => normalizeRegistrationLine(added) === declared));
-}
-/** True when the declared registration line is among the lines the patch adds to its file. */
-function isRegistrationLinePresent(entry, registration) {
-    return patchAddsRegistrationLine(entry, registration.file, registration.line);
-}
-/**
- * Renders `line` for the `--line "…"` argument of a paste-and-run
- * `patch staged-dependency` command.
- *
- * A registration line is quoted for the shell in the messages that print
- * the command, and a `support-files` element carries its own quotes
- * (`"file_tiles_find.html",` is what a multi-line TOML array adds). Without
- * escaping, the shell would eat them and the declaration would be written
- * with a line the patch never adds, the exact mismatch that made the
- * forward-registration remedy leave the declaring patch red.
- */
-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 ?? ''}`;
-}