@hominis/fireforge 0.30.1 → 0.32.0

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

@@ -0,0 +1,23 @@
+/**
+ * CSS patch-lint rules: introduced raw color values and non-tokenized
+ * custom-property references.
+ *
+ * Split out of `patch-lint.ts` so the per-patch and CSS rule bodies each
+ * stay within the project's per-file line budget — the same separation
+ * already applied to the JSDoc, observer, import, ownership, checkJs, and
+ * cross-patch rule families. `patch-lint.ts` re-exports `lintPatchedCss`
+ * so existing callers keep importing from the single module.
+ */
+import type { PatchLintIssue } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+/**
+ * Lints patched CSS files for introduced raw color values and non-tokenized
+ * custom properties.
+ *
+ * @param repoDir - Absolute path to the engine (repository) directory
+ * @param affectedFiles - File paths (relative to repoDir) affected by the patch
+ * @param diffContent - Optional unified diff used to scope raw color checks to introduced lines
+ * @param config - Project configuration
+ * @returns Array of lint issues found
+ */
+export declare function lintPatchedCss(repoDir: string, affectedFiles: string[], diffContent?: string, config?: FireForgeConfig): Promise<PatchLintIssue[]>;

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

@@ -0,0 +1,172 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * CSS patch-lint rules: introduced raw color values and non-tokenized
+ * custom-property references.
+ *
+ * Split out of `patch-lint.ts` so the per-patch and CSS rule bodies each
+ * stay within the project's per-file line budget — the same separation
+ * already applied to the JSDoc, observer, import, ownership, checkJs, and
+ * cross-patch rule families. `patch-lint.ts` re-exports `lintPatchedCss`
+ * so existing callers keep importing from the single module.
+ */
+import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
+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 { extractAddedLinesPerFile } from './patch-lint-diff.js';
+/**
+ * Loads the furnace token-prefix lint inputs gracefully — returns
+ * undefined (skipping the token-prefix check) when furnace.json cannot
+ * be loaded or no tokenPrefix is configured.
+ */
+async function loadCssTokenContext(repoDir) {
+    try {
+        const root = join(repoDir, '..');
+        const furnaceConfig = await loadFurnaceConfig(root);
+        if (furnaceConfig.tokenPrefix) {
+            return {
+                tokenPrefix: furnaceConfig.tokenPrefix,
+                tokenAllowlist: new Set(furnaceConfig.tokenAllowlist ?? []),
+                runtimeVariables: new Set(furnaceConfig.runtimeVariables ?? []),
+            };
+        }
+    }
+    catch (error) {
+        verbose(`Skipping furnace token-prefix lint hints because furnace.json could not be loaded: ${toError(error).message}`);
+    }
+    return undefined;
+}
+/**
+ * Raw-color check for one patched CSS file, scoped to introduced lines
+ * when diff context is available. Pushes onto `issues`.
+ */
+function checkRawColorValues(file, rawCss, addedLinesByFile, config, issues) {
+    // Check only introduced raw color values when diff context is available.
+    // Skip files on the raw-color allowlist (exact path or basename match) and
+    // auto-exempt files under `browser/branding/` — those are the fork's
+    // visual identity assets (app-about dialogs, installer pages, branded
+    // CSS copied from Firefox's `unofficial` template) and belong to the
+    // design-decision layer the design-token system does not govern.
+    // Without this auto-exemption, every first-time setup's copied CSS
+    // failed `raw-color-value` with no actionable fix other than manually
+    // listing each path in `rawColorAllowlist`.
+    const allowlist = config?.patchLint?.rawColorAllowlist;
+    const isAllowlisted = allowlist?.some((entry) => file === entry || file.endsWith('/' + entry));
+    const isBranding = file.startsWith('browser/branding/');
+    if (!isAllowlisted && !isBranding) {
+        // Strip lines with inline fireforge-ignore: raw-color-value suppression.
+        // Check against rawCss (before comment stripping) so the CSS comment marker is still present.
+        const sourceForSuppression = addedLinesByFile
+            ? (addedLinesByFile.get(file) ?? []).join('\n')
+            : rawCss;
+        const suppressedContent = sourceForSuppression
+            .split('\n')
+            .filter((line) => !line.includes('fireforge-ignore: raw-color-value'))
+            .join('\n')
+            .replace(/\/\*[\s\S]*?\*\//g, '');
+        if (hasRawCssColors(suppressedContent)) {
+            issues.push({
+                file,
+                check: 'raw-color-value',
+                message: 'Raw color value found. Use CSS custom properties (var(--...)) for design token consistency.',
+                severity: 'error',
+            });
+        }
+    }
+}
+/**
+ * Token-prefix check for one patched CSS file: flags `var(--x)` references
+ * that match neither the configured prefix, the allowlist, the runtime
+ * variables, nor a same-file declaration. Pushes onto `issues`.
+ */
+function checkTokenPrefixViolations(file, cssContent, addedLinesByFile, tokenContext, issues) {
+    // Check for non-tokenized custom properties. A variable that is both
+    // declared and consumed inside the same file is auto-exempted as a
+    // runtime state channel (see furnace.json → runtimeVariables).
+    //
+    // When diff context is available, scope the `var(...)` scan to
+    // added/modified lines only. `cssContent` (full-file) is still the
+    // source of `localDeclarations` so vars declared anywhere in the file
+    // are recognised as same-file refs regardless of where the consuming
+    // `var(...)` appears. Before this scoping change, a small edit to a
+    // Furnace override of a stock component (e.g. moz-card) produced a
+    // `token-prefix-violation` for every stock `var(--moz-card-*)` the
+    // upstream file already carried, because the scanner saw the full
+    // applied file and flagged each inherited reference as if the fork
+    // had introduced it.
+    if (tokenContext) {
+        const declarationPattern = /(?:^|[{;,\s])(--[\w-]+)\s*:/g;
+        const localDeclarations = new Set();
+        let declMatch;
+        while ((declMatch = declarationPattern.exec(cssContent)) !== null) {
+            const name = declMatch[1];
+            if (name)
+                localDeclarations.add(name);
+        }
+        const prefixScanSource = addedLinesByFile
+            ? (addedLinesByFile.get(file) ?? []).join('\n').replace(/\/\*[\s\S]*?\*\//g, '')
+            : cssContent;
+        if (prefixScanSource.length > 0) {
+            const varPattern = /var\(\s*(--[\w-]+)/g;
+            const flaggedProps = new Set();
+            let match;
+            while ((match = varPattern.exec(prefixScanSource)) !== null) {
+                const prop = match[1];
+                if (!prop)
+                    continue;
+                if (prop.startsWith(tokenContext.tokenPrefix))
+                    continue;
+                if (tokenContext.tokenAllowlist.has(prop))
+                    continue;
+                if (tokenContext.runtimeVariables.has(prop))
+                    continue;
+                if (localDeclarations.has(prop))
+                    continue;
+                // De-duplicate per (file, prop) pair so the same introduced var
+                // used five times in the added hunk doesn't produce five
+                // identical issue entries.
+                if (flaggedProps.has(prop))
+                    continue;
+                flaggedProps.add(prop);
+                issues.push({
+                    file,
+                    check: 'token-prefix-violation',
+                    message: `CSS references var(${prop}) which does not match the required token prefix "${tokenContext.tokenPrefix}". Use a design token, add to tokenAllowlist, or (for runtime state channels) list the variable in runtimeVariables.`,
+                    severity: 'error',
+                });
+            }
+        }
+    }
+}
+/**
+ * Lints patched CSS files for introduced raw color values and non-tokenized
+ * custom properties.
+ *
+ * @param repoDir - Absolute path to the engine (repository) directory
+ * @param affectedFiles - File paths (relative to repoDir) affected by the patch
+ * @param diffContent - Optional unified diff used to scope raw color checks to introduced lines
+ * @param config - Project configuration
+ * @returns Array of lint issues found
+ */
+export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config) {
+    const cssFiles = affectedFiles.filter((f) => f.endsWith('.css'));
+    if (cssFiles.length === 0)
+        return [];
+    const tokenContext = await loadCssTokenContext(repoDir);
+    const issues = [];
+    const addedLinesByFile = diffContent ? extractAddedLinesPerFile(diffContent) : undefined;
+    for (const file of cssFiles) {
+        const filePath = join(repoDir, file);
+        if (!(await pathExists(filePath)))
+            continue;
+        const rawCss = await readText(filePath);
+        // Strip block comments before scanning
+        const cssContent = rawCss.replace(/\/\*[\s\S]*?\*\//g, '');
+        checkRawColorValues(file, rawCss, addedLinesByFile, config, issues);
+        checkTokenPrefixViolations(file, cssContent, addedLinesByFile, tokenContext, issues);
+    }
+    return issues;
+}
+//# sourceMappingURL=patch-lint-css.js.map

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

@@ -37,13 +37,72 @@ function findAttachedJsDoc(comments, declStart, source) {
 // ---------------------------------------------------------------------------
 // JSDoc tag parsing
 // ---------------------------------------------------------------------------
+/**
+ * Skips a balanced `{ … }` JSDoc type expression starting at `start`
+ * (which must point at the opening brace). Braces nest in inline object
+ * types (`{{ id: string, args?: Record<string, boolean> }}`), so a flat
+ * "anything but `}`" regex truncates at the first inner close brace and
+ * loses the param name. String literal types may contain braces too, so
+ * quoted runs are skipped verbatim.
+ *
+ * @returns Index just past the matching close brace, or -1 when the type
+ *   expression never closes (malformed doc — caller skips the tag).
+ */
+function skipBalancedTypeBraces(jsDoc, start) {
+    let depth = 0;
+    let quote = null;
+    for (let i = start; i < jsDoc.length; i++) {
+        const ch = jsDoc[i];
+        if (quote !== null) {
+            if (ch === '\\')
+                i++;
+            else if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === "'" || ch === '"' || ch === '`') {
+            quote = ch;
+            continue;
+        }
+        if (ch === '{')
+            depth++;
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0)
+                return i + 1;
+        }
+    }
+    return -1;
+}
 function extractParamNames(jsDoc) {
     const names = [];
-    const paramPattern = /@param\s+(?:\{[^}]*\}\s+)?(\w+)/g;
+    const tagPattern = /@param\b/g;
     let m;
-    while ((m = paramPattern.exec(jsDoc)) !== null) {
-        if (m[1])
-            names.push(m[1]);
+    while ((m = tagPattern.exec(jsDoc)) !== null) {
+        let i = m.index + m[0].length;
+        while (i < jsDoc.length && /\s/.test(jsDoc[i] ?? ''))
+            i++;
+        // Optional `{type}` expression — depth-aware so nested braces inside
+        // inline object types or Record<…> generics don't truncate the scan.
+        if (jsDoc[i] === '{') {
+            const afterType = skipBalancedTypeBraces(jsDoc, i);
+            if (afterType === -1)
+                continue;
+            i = afterType;
+            while (i < jsDoc.length && /\s/.test(jsDoc[i] ?? ''))
+                i++;
+        }
+        // Name token: bare `name`, optional `[name]`, or defaulted `[name=x]`.
+        // Dotted property docs (`opts.id`) record the base object name once.
+        const optional = jsDoc[i] === '[';
+        if (optional)
+            i++;
+        const nameMatch = /^[A-Za-z_$][\w$]*/.exec(jsDoc.slice(i));
+        if (!nameMatch)
+            continue;
+        const name = nameMatch[0];
+        if (!names.includes(name))
+            names.push(name);
     }
     return names;
 }

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

@@ -0,0 +1,37 @@
+/**
+ * `observer-topic-naming` rule body, extracted from `patch-lint.ts`.
+ *
+ * The historical implementation captured the first string literal after
+ * the call's opening paren on a single line. That mis-attributed string
+ * literals in complex subject arguments and silently skipped multi-line
+ * call sites. This version scans the balanced argument list (across
+ * newlines, string-aware), takes the *topic* argument by position, and
+ * allowlists well-known Firefox-owned topics so tests that simulate
+ * upstream notifications are not pushed toward renaming real topics.
+ */
+import type { PatchLintIssue } from '../types/commands/index.js';
+/**
+ * Firefox-owned observer topics a fork legitimately observes or simulates.
+ * These must never be flagged for fork-prefix naming, even when a fork's
+ * binaryName happens to be a substring of one. `quit-application*` is
+ * handled as a prefix family in {@link isKnownFirefoxTopic}.
+ *
+ * The list is deliberately conservative: it only needs to cover topics
+ * whose text could plausibly contain a fork's binaryName, plus the
+ * high-traffic lifecycle topics seen in downstream test simulations.
+ */
+export declare const KNOWN_FIREFOX_OBSERVER_TOPICS: ReadonlySet<string>;
+/** True for allowlisted Firefox topics, including the quit-application family. */
+export declare function isKnownFirefoxTopic(topic: string): boolean;
+/**
+ * Lints observer-service call sites in `strippedContent` (comments already
+ * removed) for fork topic naming. Only topics that embed `binaryName` and
+ * do not follow the `<binary>-<noun>-<verb>` convention are flagged;
+ * allowlisted Firefox topics and constant-named topics are skipped.
+ *
+ * @param strippedContent - Source with comments stripped
+ * @param file - File path for issue attribution
+ * @param binaryName - Lowercased fork binary name
+ * @returns Observer-topic naming issues
+ */
+export declare function lintObserverTopics(strippedContent: string, file: string, binaryName: string): PatchLintIssue[];

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

@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `observer-topic-naming` rule body, extracted from `patch-lint.ts`.
+ *
+ * The historical implementation captured the first string literal after
+ * the call's opening paren on a single line. That mis-attributed string
+ * literals in complex subject arguments and silently skipped multi-line
+ * call sites. This version scans the balanced argument list (across
+ * newlines, string-aware), takes the *topic* argument by position, and
+ * allowlists well-known Firefox-owned topics so tests that simulate
+ * upstream notifications are not pushed toward renaming real topics.
+ */
+/**
+ * Firefox-owned observer topics a fork legitimately observes or simulates.
+ * These must never be flagged for fork-prefix naming, even when a fork's
+ * binaryName happens to be a substring of one. `quit-application*` is
+ * handled as a prefix family in {@link isKnownFirefoxTopic}.
+ *
+ * The list is deliberately conservative: it only needs to cover topics
+ * whose text could plausibly contain a fork's binaryName, plus the
+ * high-traffic lifecycle topics seen in downstream test simulations.
+ */
+export const KNOWN_FIREFOX_OBSERVER_TOPICS = new Set([
+    'idle-daily',
+    'profile-after-change',
+    'profile-before-change',
+    'xpcom-shutdown',
+    'xpcom-will-shutdown',
+    'final-ui-startup',
+    'browser-delayed-startup-finished',
+    'sessionstore-windows-restored',
+    'document-element-inserted',
+    'content-document-global-created',
+    'http-on-modify-request',
+    'http-on-examine-response',
+    'nsPref:changed',
+    'browser-window-before-show',
+    'domwindowopened',
+    'domwindowclosed',
+]);
+/** True for allowlisted Firefox topics, including the quit-application family. */
+export function isKnownFirefoxTopic(topic) {
+    return KNOWN_FIREFOX_OBSERVER_TOPICS.has(topic) || topic.startsWith('quit-application');
+}
+/**
+ * Scans a balanced `( … )` argument span starting at `openParen` (which
+ * must point at the opening paren) and splits it into top-level argument
+ * strings. Tracks paren/brace/bracket depth and skips quoted runs, so
+ * commas inside nested calls, object literals, or strings do not split.
+ *
+ * @returns The argument texts, or null when the span never closes within
+ *   `maxLength` characters (malformed or truncated source — caller skips).
+ */
+function extractCallArguments(content, openParen, maxLength = 2000) {
+    const args = [];
+    let current = '';
+    let depth = 0;
+    let quote = null;
+    const end = Math.min(content.length, openParen + maxLength);
+    for (let i = openParen; i < end; i++) {
+        const ch = content[i] ?? '';
+        if (quote !== null) {
+            current += ch;
+            if (ch === '\\') {
+                current += content[i + 1] ?? '';
+                i++;
+            }
+            else if (ch === quote) {
+                quote = null;
+            }
+            continue;
+        }
+        if (ch === "'" || ch === '"' || ch === '`') {
+            quote = ch;
+            current += ch;
+            continue;
+        }
+        if (ch === '(' || ch === '{' || ch === '[') {
+            depth++;
+            if (depth === 1 && ch === '(')
+                continue; // the call's own paren
+            current += ch;
+            continue;
+        }
+        if (ch === ')' || ch === '}' || ch === ']') {
+            depth--;
+            if (depth === 0 && ch === ')') {
+                args.push(current.trim());
+                return args;
+            }
+            current += ch;
+            continue;
+        }
+        if (ch === ',' && depth === 1) {
+            args.push(current.trim());
+            current = '';
+            continue;
+        }
+        current += ch;
+    }
+    return null;
+}
+/**
+ * Returns the literal string value when `arg` is exactly one plain string
+ * literal (no concatenation, no `${}` interpolation), otherwise null.
+ * Constant-named topics (identifiers, member expressions) intentionally
+ * return null — hoisting a literal into a named constant is a supported
+ * way to mark a topic as deliberate.
+ */
+function asStringLiteral(arg) {
+    const trimmed = arg.trim();
+    if (trimmed.length < 2)
+        return null;
+    const quoteChar = trimmed[0];
+    if (quoteChar !== "'" && quoteChar !== '"' && quoteChar !== '`')
+        return null;
+    if (trimmed[trimmed.length - 1] !== quoteChar)
+        return null;
+    const inner = trimmed.slice(1, -1);
+    if (inner.includes(quoteChar))
+        return null; // concatenation like "a" + "b"
+    if (quoteChar === '`' && inner.includes('${'))
+        return null;
+    return inner;
+}
+/**
+ * Lints observer-service call sites in `strippedContent` (comments already
+ * removed) for fork topic naming. Only topics that embed `binaryName` and
+ * do not follow the `<binary>-<noun>-<verb>` convention are flagged;
+ * allowlisted Firefox topics and constant-named topics are skipped.
+ *
+ * @param strippedContent - Source with comments stripped
+ * @param file - File path for issue attribution
+ * @param binaryName - Lowercased fork binary name
+ * @returns Observer-topic naming issues
+ */
+export function lintObserverTopics(strippedContent, file, binaryName) {
+    const issues = [];
+    const callPattern = /\b(?:addObserver|removeObserver|notifyObservers)\s*\(/g;
+    let callMatch;
+    while ((callMatch = callPattern.exec(strippedContent)) !== null) {
+        const openParen = callMatch.index + callMatch[0].length - 1;
+        const args = extractCallArguments(strippedContent, openParen);
+        if (!args)
+            continue;
+        // Topic is the second argument for all three observer-service methods:
+        // addObserver(observer, topic[, weak]), removeObserver(observer, topic),
+        // notifyObservers(subject, topic[, data]).
+        const topicArg = args[1];
+        if (topicArg === undefined)
+            continue;
+        const topic = asStringLiteral(topicArg);
+        if (topic === null)
+            continue;
+        if (isKnownFirefoxTopic(topic))
+            continue;
+        if (topic.toLowerCase().includes(binaryName) && !/^[\w]+-[a-z]+-[a-z]+/.test(topic)) {
+            issues.push({
+                file,
+                check: 'observer-topic-naming',
+                message: `Observer topic "${topic}" should follow "${binaryName}-<noun>-<verb>" naming convention.`,
+                severity: 'warning',
+            });
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=patch-lint-observer.js.map

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

@@ -1,7 +1,9 @@
 import type { PatchLintIssue } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
 import { type CommentStyle } from './license-headers.js';
+import { lintPatchedCss } from './patch-lint-css.js';
 export * from './patch-lint-reexports.js';
+export { lintPatchedCss };
 /**
  * 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.
@@ -23,16 +25,6 @@ export declare function isTestFile(file: string): boolean;
  * Detects comment style from file extension for license header checks.
  */
 export declare function commentStyleForFile(file: string): CommentStyle | null;
-/**
- * Lints patched CSS files for introduced raw color values and non-tokenized
- * custom properties.
- *
- * @param repoDir - Absolute path to the engine (repository) directory
- * @param affectedFiles - File paths (relative to repoDir) affected by the patch
- * @param diffContent - Optional unified diff used to scope raw color checks to introduced lines
- * @returns Array of lint issues found
- */
-export declare function lintPatchedCss(repoDir: string, affectedFiles: string[], diffContent?: string, config?: FireForgeConfig): Promise<PatchLintIssue[]>;
 /**
  * Checks new files for required license headers.
  *
@@ -121,6 +113,35 @@ export declare function lintPatchSize(filesAffected: string[], lineCount: number
  * @returns Warning-level lint issues for files missing any recognized header
  */
 export declare function lintModifiedFileHeaders(repoDir: string, affectedFiles: string[], newFiles: Set<string>): Promise<PatchLintIssue[]>;
+/**
+ * Optional behaviour switches for {@link lintExportedPatch}.
+ */
+export interface LintExportedPatchOptions {
+    /**
+     * Skip the patch-size rules (`large-patch-files` / `large-patch-lines`).
+     * The ad-hoc `fireforge lint <files>` path passes a cross-patch file
+     * list that does not correspond to a single patch, so it suppresses the
+     * synthetic combined-list size check here and re-evaluates the size
+     * rules per owning patch instead — never synthesising a phantom
+     * oversized patch from the operator's file selection.
+     */
+    skipPatchSize?: boolean;
+    /**
+     * Restrict checkJs diagnostics to these repo-relative files; module
+     * resolution still spans every owned file in `patchQueueCtx`. Export and
+     * re-export pass the patch under export so cross-patch `resource:///`
+     * imports resolve against the whole queue while only that patch's
+     * findings surface.
+     */
+    checkJsReportScope?: ReadonlySet<string>;
+    /**
+     * Pre-computed checkJs issues for this patch. When provided, the internal
+     * checkJs invocation is skipped and these are appended verbatim — the
+     * per-patch lint path builds one queue-wide checkJs program and
+     * attributes findings per patch instead of rebuilding per patch.
+     */
+    precomputedCheckJs?: readonly PatchLintIssue[];
+}
 /**
  * Runs all patch lint checks and returns combined issues.
  *
@@ -140,6 +161,8 @@ export declare function lintModifiedFileHeaders(repoDir: string, affectedFiles:
  *   per-patch manifest context (re-export, per-patch lint) should
  *   pass this; aggregate-mode callers without a specific patch
  *   context skip it and fall through to auto-detection.
+ * @param options - Optional behaviour switches; see
+ *   {@link LintExportedPatchOptions}.
  * @returns Array of all lint issues found
  */
-export declare function lintExportedPatch(repoDir: string, affectedFiles: string[], diffContent: string, config: FireForgeConfig, patchQueueCtx?: import('./patch-lint-cross.js').PatchQueueContext, ignoreChecks?: ReadonlySet<string>, patchTier?: 'branding'): Promise<PatchLintIssue[]>;
+export declare function lintExportedPatch(repoDir: string, affectedFiles: string[], diffContent: string, config: FireForgeConfig, patchQueueCtx?: import('./patch-lint-cross.js').PatchQueueContext, ignoreChecks?: ReadonlySet<string>, patchTier?: 'branding', options?: LintExportedPatchOptions): Promise<PatchLintIssue[]>;