@hominis/fireforge 0.30.0 → 0.31.0

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

@@ -17,13 +17,51 @@
  * and optional allowlisted `checkJsCompilerOptions`; it does not change
  * shim composition or suppressed diagnostic codes.
  */
-import { resolve } from 'node:path';
+import { basename, resolve } from 'node:path';
 import { pathExists } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES } from './typecheck-shim.js';
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
+/**
+ * Builds the host-side module resolver for the checkJs pass: maps an import
+ * specifier to a patch-owned absolute path when the specifier's final
+ * segment uniquely matches an owned file. URL specifiers
+ * (chrome://browser/content/Foo.sys.mjs, resource:///modules/Foo.sys.mjs)
+ * are matched by basename, with a `.mjs` → `.sys.mjs` fallback for deployed
+ * widget URLs. Ambiguous or unknown basenames stay unresolved — loose
+ * wildcard typing beats guessing the wrong module — and relative specifiers
+ * are left to fail resolution (the relative-import lint rule bans them).
+ */
+function createOwnedSpecifierResolver(ts, ownedAbsolute) {
+    const ownedByBasename = new Map();
+    for (const abs of ownedAbsolute) {
+        const base = basename(abs);
+        const list = ownedByBasename.get(base) ?? [];
+        list.push(abs);
+        ownedByBasename.set(base, list);
+    }
+    return (specifier) => {
+        if (specifier.startsWith('.'))
+            return undefined;
+        const cleaned = specifier.split(/[?#]/)[0] ?? specifier;
+        const segment = cleaned.slice(cleaned.lastIndexOf('/') + 1);
+        if (!segment)
+            return undefined;
+        const candidates = [...(ownedByBasename.get(segment) ?? [])];
+        if (segment.endsWith('.mjs') && !segment.endsWith('.sys.mjs')) {
+            candidates.push(...(ownedByBasename.get(segment.replace(/\.mjs$/, '.sys.mjs')) ?? []));
+        }
+        if (candidates.length !== 1)
+            return undefined;
+        return {
+            resolvedFileName: candidates[0],
+            extension: ts.Extension.Mjs,
+            isExternalLibraryImport: false,
+        };
+    };
+}
 /**
  * Runs TypeScript's checkJs pass on patch-owned `.sys.mjs` files.
  *
@@ -126,15 +164,18 @@ export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projec
         module: ts.ModuleKind.ESNext,
         moduleResolution: ts.ModuleResolutionKind.Bundler,
         skipLibCheck: true,
-        // Do not follow import/reference directives into the Firefox tree.
-        // We only want to check the patch-owned files themselves.
-        // Without this, TS would try (and fail) to resolve every
-        // resource:// and chrome:// import, flooding the output with
-        // "Cannot find module" errors for upstream Firefox modules.
-        noResolve: true,
+        // Module resolution is host-controlled (see resolveOwnedSpecifier
+        // below): imports that match a patch-owned file resolve to the real
+        // source so JSDoc type-guard predicates and @template generics
+        // survive the module boundary; everything else deliberately fails
+        // resolution, falling back to the chrome:*/resource:* ambient
+        // wildcards plus the suppressed "cannot find module" codes. The
+        // host resolver is authoritative — TS never crawls the Firefox
+        // tree looking for upstream modules.
         ...strictness,
         ...overrides,
     };
+    const resolveOwnedSpecifier = createOwnedSpecifierResolver(ts, ownedAbsolute);
     // Custom compiler host: reads patch-owned files from disk, returns
     // the shim for the shim path, and returns empty content for
     // anything else to avoid reading the full Firefox tree.
@@ -169,6 +210,11 @@ export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projec
                 return shimSource;
             return defaultHost.readFile(fileName);
         },
+        resolveModuleNameLiterals(moduleLiterals) {
+            return moduleLiterals.map((literal) => ({
+                resolvedModule: resolveOwnedSpecifier(literal.text),
+            }));
+        },
     };
     const program = ts.createProgram(rootFiles, options, host);
     const allDiagnostics = [

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.js

@@ -12,6 +12,7 @@ import { detectNewFilesInDiff, extractAddedLinesPerFile } from './patch-lint-dif
 import { AGGREGATE_PATCH_FILE } from './patch-lint-diff-tag.js';
 import { hasRelativeImport } from './patch-lint-imports.js';
 import { validateExportJsDoc } from './patch-lint-jsdoc.js';
+import { lintObserverTopics } from './patch-lint-observer.js';
 import { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs } from './patch-lint-ownership.js';
 // ---------------------------------------------------------------------------
 // Cross-patch lint re-exports
@@ -204,9 +205,130 @@ export function commentStyleForFile(file) {
         return 'js';
     return null;
 }
-// ---------------------------------------------------------------------------
-// CSS lint
-// ---------------------------------------------------------------------------
+/**
+ * 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.
@@ -220,22 +342,7 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
     const cssFiles = affectedFiles.filter((f) => f.endsWith('.css'));
     if (cssFiles.length === 0)
         return [];
-    // Load furnace config gracefully — skip token-prefix check if unavailable
-    let tokenPrefix;
-    let tokenAllowlist;
-    let runtimeVariables;
-    try {
-        const root = join(repoDir, '..');
-        const furnaceConfig = await loadFurnaceConfig(root);
-        if (furnaceConfig.tokenPrefix) {
-            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}`);
-    }
+    const tokenContext = await loadCssTokenContext(repoDir);
     const issues = [];
     const addedLinesByFile = diffContent ? extractAddedLinesPerFile(diffContent) : undefined;
     for (const file of cssFiles) {
@@ -245,95 +352,8 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
         const rawCss = await readText(filePath);
         // Strip block comments before scanning
         const cssContent = rawCss.replace(/\/\*[\s\S]*?\*\//g, '');
-        // 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',
-                });
-            }
-        }
-        // 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 (tokenPrefix) {
-            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(tokenPrefix))
-                        continue;
-                    if (tokenAllowlist?.has(prop))
-                        continue;
-                    if (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 "${tokenPrefix}". Use a design token, add to tokenAllowlist, or (for runtime state channels) list the variable in runtimeVariables.`,
-                        severity: 'error',
-                    });
-                }
-            }
-        }
+        checkRawColorValues(file, rawCss, addedLinesByFile, config, issues);
+        checkTokenPrefixViolations(file, cssContent, addedLinesByFile, tokenContext, issues);
     }
     return issues;
 }
@@ -503,23 +523,10 @@ export async function lintPatchedJs(repoDir, affectedFiles, newFiles, config, pa
                 });
             }
         }
-        // 4. Observer topic naming
-        const topicPattern = /(?:addObserver|removeObserver|notifyObservers)\s*\([^)\n]*["']([^"']+)["']/g;
-        let topicMatch;
-        while ((topicMatch = topicPattern.exec(strippedContent)) !== null) {
-            const topic = topicMatch[1];
-            if (!topic)
-                continue;
-            // Only flag topics that contain the binaryName but don't follow convention
-            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',
-                });
-            }
-        }
+        // 4. Observer topic naming. Rule body lives in `patch-lint-observer.ts`:
+        // argument-position-aware, multi-line-safe, and allowlists Firefox-owned
+        // topics so simulated upstream notifications are not flagged.
+        issues.push(...lintObserverTopics(strippedContent, file, binaryName));
     }
     return issues;
 }