@hominis/fireforge 0.55.0 → 0.60.0

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

@@ -1,65 +0,0 @@
-/**
- * `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 (or
- * prefixes) 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. Inside them, `allowInCalc` names literals legal only
- * there (a unitless multiplier), and `offsetCap` lets a declaration
- * subtract a few px from a token (a border inset) without allowing the px
- * value anywhere else.
- *
- * Declarations inside descriptor at-rules (`@font-face`, `@counter-style`,
- * `@property`, `@page`, …) are not property declarations and are not
- * judged: `font-weight` in `@font-face` names a face, not a type step.
- *
- * 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 file a scale `exclude`s
- * is not judged against that scale. A line carrying
- * `fireforge-ignore: token-scale` is skipped, and so is a declaration the
- * scale's `allowValues` lists, in any file the scale governs. A scale with `minFiles` also
- * fails the queue (`token-scale-vacuous`) when fewer created files carry
- * its properties, so an emptied scan set cannot pass by judging nothing.
- */
-import type { PatchLintIssue } from '../types/commands/index.js';
-import type { PatchLintTokenScale } from '../types/config.js';
-/**
- * Exact name, or a `*`-suffixed prefix.
- *
- * @param name - Property or custom-property name
- * @param patterns - Names, or `*`-suffixed prefixes
- */
-export declare function matchesName(name: string, patterns: readonly string[]): boolean;
-/**
- * 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 and the `exclude` globs
- * @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[];
-/**
- * The `minFiles` floor of every scale over the queue's created stylesheets:
- * one `token-scale-vacuous` error per scale that fewer created CSS files
- * (outside its `exclude`) carry a declaration of.
- *
- * @param createdFiles - Every patch-created file's path and content
- * @param scales - `patchLint.tokenScales`
- */
-export declare function lintTokenScaleFloors(createdFiles: Iterable<readonly [string, string]>, scales: readonly PatchLintTokenScale[]): PatchLintIssue[];

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

@@ -1,304 +0,0 @@
-// 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 (or
- * prefixes) 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. Inside them, `allowInCalc` names literals legal only
- * there (a unitless multiplier), and `offsetCap` lets a declaration
- * subtract a few px from a token (a border inset) without allowing the px
- * value anywhere else.
- *
- * Declarations inside descriptor at-rules (`@font-face`, `@counter-style`,
- * `@property`, `@page`, …) are not property declarations and are not
- * judged: `font-weight` in `@font-face` names a face, not a type step.
- *
- * 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 file a scale `exclude`s
- * is not judged against that scale. A line carrying
- * `fireforge-ignore: token-scale` is skipped, and so is a declaration the
- * scale's `allowValues` lists, in any file the scale governs. A scale with `minFiles` also
- * fails the queue (`token-scale-vacuous`) when fewer created files carry
- * its properties, so an emptied scan set cannot pass by judging nothing.
- */
-import { matchesAnyGlob } from '../utils/path-glob.js';
-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';
-const MATH_FUNCTION = /^(?:calc|min|max|clamp)$/i;
-const OPERATORS = new Set(['+', '-', '*', '/']);
-/**
- * At-rules whose blocks hold descriptors, not property declarations. A
- * block nested in one (an `@page` margin box, a `@font-feature-values`
- * feature block) is a descriptor block too.
- */
-const DESCRIPTOR_AT_RULE = /^@(?:font-face|counter-style|property|font-feature-values|font-palette-values|page|view-transition)\b/i;
-/**
- * Exact name, or a `*`-suffixed prefix.
- *
- * @param name - Property or custom-property name
- * @param patterns - Names, or `*`-suffixed prefixes
- */
-export 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));
-}
-/** The scale's token prefixes, whether configured as one or a list. */
-function scalePrefixes(scale) {
-    return typeof scale.prefix === 'string' ? [scale.prefix] : scale.prefix;
-}
-/** The scale as a message names it: `--x-space-*`, or `--x-space-* / --x-gap-*`. */
-function scaleLabel(scale) {
-    return scalePrefixes(scale)
-        .map((prefix) => `${prefix}*`)
-        .join(' / ');
-}
-/**
- * Splits a value into atoms, keeping operators as atoms and noting which
- * atoms sit inside a math function. A math function's name is dropped; any
- * other function's name stays an atom, judged like a literal.
- */
-function valueAtoms(value) {
-    const atoms = [];
-    const mathStack = [];
-    let current = '';
-    const flush = () => {
-        if (current !== '')
-            atoms.push({ text: current, inMath: mathStack.includes(true) });
-        current = '';
-    };
-    for (const char of value) {
-        if (char === '(') {
-            const isMath = MATH_FUNCTION.test(current);
-            if (isMath)
-                current = '';
-            else
-                flush();
-            mathStack.push(isMath);
-        }
-        else if (char === ')') {
-            flush();
-            mathStack.pop();
-        }
-        else if (char === '*' || char === '/') {
-            flush();
-            atoms.push({ text: char, inMath: mathStack.includes(true) });
-        }
-        else if (char === ',' || /\s/.test(char)) {
-            flush();
-        }
-        else {
-            current += char;
-        }
-    }
-    flush();
-    return atoms;
-}
-const PX_LITERAL = /^(\d*\.?\d+)px$/;
-/**
- * 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 prefixes = scalePrefixes(scale);
-    const varPattern = /var\(\s*(--[\w-]+)\s*(?:,([^()]*))?\)/;
-    for (let match = varPattern.exec(rest); match !== null; match = varPattern.exec(rest)) {
-        const name = match[1] ?? '';
-        const onScale = prefixes.some((prefix) => name.startsWith(prefix));
-        if (!onScale && !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 = valueAtoms(rest);
-    // A px offset subtracted from a token (`token - 1px`, `token - 1px - 1px`)
-    // counts toward `offsetCap`, summed over the declaration.
-    let offsetTotal = 0;
-    let lastOffsetIndex = -1;
-    for (const [index, atom] of atoms.entries()) {
-        if (OPERATORS.has(atom.text) || atom.text === TOKEN_PLACEHOLDER)
-            continue;
-        if (CSS_WIDE_KEYWORDS.has(atom.text.toLowerCase()))
-            continue;
-        if (matchesLiteral(atom.text, scale.allowLiterals ?? []))
-            continue;
-        if (atom.inMath && matchesLiteral(atom.text, scale.allowInCalc ?? []))
-            continue;
-        const px = PX_LITERAL.exec(atom.text);
-        if (atom.inMath && px !== null && scale.offsetCap !== undefined) {
-            const subtrahendOf = atoms[index - 2]?.text;
-            const subtracted = atoms[index - 1]?.text === '-' &&
-                (subtrahendOf === TOKEN_PLACEHOLDER || lastOffsetIndex === index - 2);
-            if (subtracted) {
-                offsetTotal += Number(px[1]);
-                lastOffsetIndex = index;
-                if (offsetTotal <= scale.offsetCap)
-                    continue;
-            }
-        }
-        return atom.text;
-    }
-    return undefined;
-}
-/** Blanks block comments, keeping newlines so offsets map to lines. */
-function maskComments(css) {
-    return css.replace(/\/\*[\s\S]*?\*\//g, (comment) => comment.replace(/[^\n]/g, ' '));
-}
-/**
- * Blanks the contents of descriptor at-rule blocks (keeping braces and
- * newlines), so the declaration scan never sees their descriptors.
- */
-function maskDescriptorBlocks(css) {
-    const out = css.split('');
-    const stack = [];
-    let preludeStart = 0;
-    for (let i = 0; i < css.length; i++) {
-        const char = css.charAt(i);
-        const inDescriptor = stack[stack.length - 1] === true;
-        if (char === '{') {
-            const prelude = css.slice(preludeStart, i).trim();
-            stack.push(inDescriptor || DESCRIPTOR_AT_RULE.test(prelude));
-            preludeStart = i + 1;
-        }
-        else if (char === '}') {
-            stack.pop();
-            preludeStart = i + 1;
-        }
-        else if (char === ';') {
-            preludeStart = i + 1;
-        }
-        if (inDescriptor && char !== '\n' && char !== '{' && char !== '}')
-            out[i] = ' ';
-    }
-    return out.join('');
-}
-/** Every property declaration of a stylesheet, descriptors and comments left out. */
-function scanDeclarations(css) {
-    const masked = maskDescriptorBlocks(maskComments(css));
-    const declarations = [];
-    const pattern = /(^|[{;\s])([a-zA-Z][a-zA-Z-]*)\s*:\s*([^;{}]*)/g;
-    for (let match = pattern.exec(masked); match !== null; match = pattern.exec(masked)) {
-        const start = match.index + (match[1] ?? '').length;
-        declarations.push({
-            property: (match[2] ?? '').toLowerCase(),
-            value: (match[3] ?? '').trim(),
-            line: masked.slice(0, start).split('\n').length,
-        });
-    }
-    return declarations;
-}
-/** Collapses whitespace runs, so an allowed value matches however it is wrapped. */
-function normalizeDeclarationValue(value) {
-    return value.replace(/\s+/g, ' ').trim();
-}
-/** Whether the scale's `allowValues` lists this declaration. */
-function isAllowedValue(property, value, scale) {
-    const normalized = normalizeDeclarationValue(value);
-    return (scale.allowValues ?? []).some((entry) => entry.property.toLowerCase() === property &&
-        normalizeDeclarationValue(entry.value) === normalized);
-}
-/** The scales that govern `file`: those that do not `exclude` it. */
-function scalesFor(file, scales) {
-    return scales.filter((scale) => !matchesAnyGlob(file, scale.exclude ?? []));
-}
-/**
- * Lints one patch-created CSS file against the configured scales.
- *
- * @param file - Engine-relative path, for the issue and the `exclude` globs
- * @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) {
-    const governing = scalesFor(file, scales);
-    if (governing.length === 0)
-        return [];
-    const rawLines = css.split('\n');
-    const issues = [];
-    for (const { property, value, line } of scanDeclarations(css)) {
-        const scale = governing.find((candidate) => matchesName(property, candidate.properties));
-        if (scale === undefined || value === '')
-            continue;
-        if ((rawLines[line - 1] ?? '').includes(IGNORE_MARKER))
-            continue;
-        if (isAllowedValue(property, value, scale))
-            continue;
-        const atom = findOffScaleAtom(value, scale);
-        if (atom === undefined)
-            continue;
-        const label = scaleLabel(scale);
-        issues.push({
-            file,
-            check: 'token-scale',
-            fingerprint: `token-scale:${file}:${property}:${value}`,
-            message: `Line ${String(line)}: ${property}: ${value} is off the ${label} scale ` +
-                `("${atom}"). Use a ${label} token, or list a reviewed exception in ` +
-                `patchLint.tokenScales (allowLiterals / allowInCalc / allow / allowValues) or mark the line "${IGNORE_MARKER}".`,
-            severity: 'error',
-        });
-    }
-    return issues;
-}
-/**
- * The `minFiles` floor of every scale over the queue's created stylesheets:
- * one `token-scale-vacuous` error per scale that fewer created CSS files
- * (outside its `exclude`) carry a declaration of.
- *
- * @param createdFiles - Every patch-created file's path and content
- * @param scales - `patchLint.tokenScales`
- */
-export function lintTokenScaleFloors(createdFiles, scales) {
-    const floored = scales.filter((scale) => scale.minFiles !== undefined);
-    if (floored.length === 0)
-        return [];
-    const counts = new Map(floored.map((scale) => [scale, 0]));
-    for (const [file, content] of createdFiles) {
-        if (!file.endsWith('.css'))
-            continue;
-        const properties = new Set(scanDeclarations(content).map((entry) => entry.property));
-        for (const scale of scalesFor(file, floored)) {
-            if ([...properties].some((property) => matchesName(property, scale.properties))) {
-                counts.set(scale, (counts.get(scale) ?? 0) + 1);
-            }
-        }
-    }
-    const issues = [];
-    for (const [scale, count] of counts) {
-        const floor = scale.minFiles ?? 0;
-        if (count >= floor)
-            continue;
-        const label = scaleLabel(scale);
-        issues.push({
-            file: 'fireforge.json',
-            check: 'token-scale-vacuous',
-            fingerprint: `token-scale-vacuous:${label}`,
-            message: `The ${label} scale governs ${String(count)} patch-created stylesheet(s), under its ` +
-                `minFiles ${String(floor)}. A scale that judges nothing passes vacuously: check its ` +
-                'properties and exclude globs, or lower minFiles after a reviewed move.',
-            severity: 'error',
-        });
-    }
-    return issues;
-}

package/dist/src/core/patch-lint-unmanaged-companion.d.ts

@@ -1,106 +0,0 @@
-/**
- * Recognizes the one shape where the undefined-identifier hint sends the
- * operator at the wrong remedy, and where taking that remedy would mask a
- * real bug.
- *
- * The shape: helpers are hoisted out of duplicated test files into a new
- * `head_settings.js` that a managed `head.js` pulls in with
- * `loadSubScript`. Until that companion is exported it belongs to no patch,
- * so the per-patch checkJs program, which only ever loads patch-owned
- * roots, cannot see any of its declarations. Every use of every hoisted
- * helper is then reported as `Cannot find name`, and the generic hint
- * offers three remedies of which the shim is the easiest: adding the
- * globals to `extraShim` makes all of the warnings disappear and makes a
- * genuinely missing helper undetectable forever after.
- *
- * The warnings themselves are correct: they are the per-patch program's
- * honest view of a file that is in no patch. Only the advice is wrong.
- * FireForge already knows ownership, so when every undefined name in a file
- * is declared at the top level of an unmanaged file that a managed head
- * loads, it can name that file and the adoption command instead.
- *
- * Detection is conservative on both halves: a companion must
- * be reachable from an actual `loadSubScript` call, and every undefined
- * name must resolve inside it. One unresolved name means the file may
- * genuinely be missing a helper, and the generic hint stays.
- */
-import type { PatchLintIssue } from '../types/commands/index.js';
-/**
- * String literals passed anywhere inside a `loadSubScript(...)` call.
- *
- * The mochitest idiom is
- * `Services.scriptloader.loadSubScript(getRootDirectory(gTestPath) + "head_settings.js", this)`,
- * so the useful signal is the `.js` literal inside the call, not a
- * resolvable URL. The path half is computed at runtime.
- */
-export declare function findLoadSubScriptTargets(source: string): string[];
-/**
- * Top-level declaration names in a script-scope file.
- *
- * Regex rather than a TS program on purpose: this runs only to decide the
- * wording of a hint, the file is outside every program the
- * pass built, and a missed declaration degrades to the generic hint rather
- * than to a wrong answer. Matching is anchored at column zero so a nested
- * declaration inside a function body is not mistaken for a global.
- */
-export declare function collectTopLevelDeclarations(source: string): Set<string>;
-/** An unmanaged companion a managed head loads, plus what it declares. */
-export interface UnmanagedCompanion {
-    /** Repo-relative path of the companion. */
-    file: string;
-    /** Repo-relative path of the managed head that loads it. */
-    loadedBy: string;
-    /** Top-level names the companion declares. */
-    declarations: Set<string>;
-}
-/**
- * Resolves the unmanaged companions reachable from a set of managed head
- * files, given a reader for repo-relative file content.
- *
- * A candidate qualifies only when it is not in `ownedFiles` and its content
- * can be read. An unreadable or absent target is simply not a companion,
- * and the generic hint applies.
- *
- * @param heads - Repo-relative managed head files, with their sources
- * @param ownedFiles - Every patch-owned repo-relative path
- * @param readFile - Reads a repo-relative file, or returns undefined
- */
-export declare function resolveUnmanagedCompanions(heads: ReadonlyArray<{
-    file: string;
-    source: string;
-}>, ownedFiles: ReadonlySet<string>, readFile: (repoRelative: string) => Promise<string | undefined>): Promise<UnmanagedCompanion[]>;
-/**
- * The replacement hint, when every undefined name resolves in one
- * unmanaged companion.
- *
- * States the ownership fact first (the diagnosis), then the adoption
- * command, and explicitly rules the shim out. The shim is what an operator
- * reaches for by default here, and it is the one remedy that permanently
- * hides a genuinely missing helper.
- */
-export declare function formatUnmanagedCompanionHint(companion: UnmanagedCompanion): string;
-/**
- * Picks the companion that explains every undefined identifier in
- * `messages`, or undefined when none does.
- *
- * @param messages - Diagnostic messages reported for one file
- * @param companions - Candidates from {@link resolveUnmanagedCompanions}
- */
-export declare function explainUndefinedIdentifiers(messages: readonly string[], companions: readonly UnmanagedCompanion[]): UnmanagedCompanion | undefined;
-/**
- * Reads the head files in the owned test set and resolves the unmanaged
- * companions they pull in with `loadSubScript`. Hoisting shared helpers
- * into such a companion leaves it unowned until export, and every use of
- * every helper then reports `Cannot find name` from an honest per-patch
- * program. See `patch-lint-unmanaged-companion.ts` for why the generic
- * hint is actively harmful there.
- *
- * Best-effort: an unreadable head simply contributes no companions.
- */
-export declare function collectUnmanagedCompanions(repoDir: string, files: readonly string[], ownedFiles: ReadonlySet<string>): Promise<UnmanagedCompanion[]>;
-/**
- * Swaps the generic undefined-identifier hint for the ownership hint when
- * one unmanaged companion explains every undefined name in the file. Any
- * other issue in the list is returned untouched.
- */
-export declare function retargetUnmanagedCompanionHints(issues: readonly PatchLintIssue[], companions: readonly UnmanagedCompanion[]): PatchLintIssue[];