@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/lint/rules/css.js

@@ -0,0 +1,308 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Stylesheet rules: no raw colours on the lines owned changes add, custom
+ * properties from the design tokens, and token scales over the stylesheets
+ * the project creates.
+ *
+ * A scale names CSS properties, the token prefixes that are its steps, and
+ * the literals that are no step at all (`0`, `auto`, a percentage). A value
+ * is judged per atom after peeling `var()` innermost-first, so a fallback is
+ * held to the same scale as the token it backs. `calc()`, `min()`, `max()`
+ * and `clamp()` are transparent; inside them `allowInCalc` literals are
+ * legal and `offsetCap` px may be subtracted from a token. Declarations in
+ * descriptor at-rules (`@font-face`, `@property`, `@page`, ...) are not
+ * property declarations and are not judged.
+ */
+import { matchesPropertyName } from '../../config/index.js';
+import { matchesAnyGlob } from '../../kernel/glob.js';
+import { escapeRegExp } from '../../kernel/text.js';
+import { foreignVariables, parseCss, rawColors } from '../../syntax/index.js';
+function cssFiles(context, accept) {
+    return context.owned
+        .all()
+        .filter((file) => file.path.endsWith('.css') &&
+        file.text !== undefined &&
+        context.selected(file.path) &&
+        accept(file));
+}
+/**
+ * The 1-based lines of a stylesheet the content rules judge: every line of
+ * a created file, the added lines of a modified one. The file is parsed
+ * whole, so a comment opened on an unchanged line still hides what it covers.
+ */
+async function scannedLines(context, file) {
+    if (file.created)
+        return () => true;
+    const added = new Set((await context.owned.added(file.change)).map((entry) => entry.line));
+    return (line) => added.has(line);
+}
+const rawColor = {
+    id: 'raw-color-value',
+    severity: 'error',
+    description: 'Owned stylesheet lines use custom properties instead of raw colours',
+    async check(context) {
+        const allowlist = context.config.patchLint.rawColorAllowlist ?? [];
+        const drafts = [];
+        const exempt = (path) => path.startsWith('browser/branding/') ||
+            allowlist.some((entry) => path === entry || path.endsWith(`/${entry}`));
+        const judged = (candidate) => !exempt(candidate.path) && !context.component(candidate.path);
+        for (const file of cssFiles(context, judged)) {
+            const scanned = await scannedLines(context, file);
+            const hit = rawColors(parseCss(file.text ?? '')).find((color) => scanned(color.line + 1));
+            if (hit === undefined)
+                continue;
+            drafts.push({
+                path: file.path,
+                line: hit.line + 1,
+                group: file.group,
+                message: 'Raw colour value. Use a CSS custom property (var(--...)) from the design tokens.',
+            });
+        }
+        return drafts;
+    },
+};
+const tokenPrefix = {
+    id: 'token-prefix-violation',
+    severity: 'error',
+    description: 'Custom properties an owned stylesheet references are design tokens',
+    async check(context) {
+        const tokens = context.tokens;
+        if (tokens === undefined)
+            return [];
+        const accepted = new Set([...tokens.allowlist, ...tokens.runtimeVariables]);
+        const drafts = [];
+        for (const file of cssFiles(context, (candidate) => !context.component(candidate.path))) {
+            const scanned = await scannedLines(context, file);
+            const flagged = new Set();
+            for (const { name, line } of foreignVariables(parseCss(file.text ?? ''), tokens.prefix, accepted)) {
+                if (!scanned(line + 1) || flagged.has(name))
+                    continue;
+                flagged.add(name);
+                drafts.push({
+                    path: file.path,
+                    line: line + 1,
+                    group: file.group,
+                    message: `var(${name}) does not have the token prefix "${tokens.prefix}". Use a design token, ` +
+                        'add it to tokenAllowlist, or list a runtime state channel in runtimeVariables.',
+                });
+            }
+        }
+        return drafts;
+    },
+};
+const CSS_WIDE_KEYWORDS = new Set(['inherit', 'initial', 'unset', 'revert', 'revert-layer']);
+const TOKEN = '\u0000token\u0000';
+const MATH_FUNCTION = /^(?:calc|min|max|clamp)$/i;
+const OPERATORS = new Set(['+', '-', '*', '/']);
+const PX_LITERAL = /^(\d*\.?\d+)px$/;
+const DESCRIPTOR_AT_RULE = /^@(?:font-face|counter-style|property|font-feature-values|font-palette-values|page|view-transition)\b/i;
+function prefixesOf(scale) {
+    return typeof scale.prefix === 'string' ? [scale.prefix] : scale.prefix;
+}
+function scaleLabel(scale) {
+    return prefixesOf(scale)
+        .map((prefix) => `${prefix}*`)
+        .join(' / ');
+}
+function matchesLiteral(atom, patterns) {
+    return patterns.some((pattern) => new RegExp(`^${pattern.split('*').map(escapeRegExp).join('.*')}$`).test(atom));
+}
+/** A value split into atoms (operators kept), each marked when inside a math function. */
+function valueAtoms(value) {
+    const atoms = [];
+    const math = [];
+    let current = '';
+    const flush = () => {
+        if (current !== '')
+            atoms.push({ text: current, inMath: math.includes(true) });
+        current = '';
+    };
+    for (const char of value) {
+        if (char === '(') {
+            const isMath = MATH_FUNCTION.test(current);
+            if (isMath)
+                current = '';
+            else
+                flush();
+            math.push(isMath);
+        }
+        else if (char === ')') {
+            flush();
+            math.pop();
+        }
+        else if (char === '*' || char === '/') {
+            flush();
+            atoms.push({ text: char, inMath: math.includes(true) });
+        }
+        else if (char === ',' || /\s/.test(char)) {
+            flush();
+        }
+        else {
+            current += char;
+        }
+    }
+    flush();
+    return atoms;
+}
+/**
+ * The first atom of a value that is off a scale, or undefined when every
+ * atom resolves to it.
+ *
+ * @param value - The declaration value
+ * @param scale - The scale
+ */
+export function offScaleAtom(value, scale) {
+    let rest = value.replace(/!\s*important\s*$/i, '');
+    const prefixes = prefixesOf(scale);
+    const variable = /var\(\s*(--[\w-]+)\s*(?:,([^()]*))?\)/;
+    for (let match = variable.exec(rest); match !== null; match = variable.exec(rest)) {
+        const name = match[1] ?? '';
+        const onScale = prefixes.some((prefix) => name.startsWith(prefix));
+        if (!onScale && !matchesPropertyName(name, scale.allow ?? []))
+            return `var(${name})`;
+        const fallback = match[2]?.trim() ?? '';
+        const offending = fallback === '' ? undefined : offScaleAtom(fallback, scale);
+        if (offending !== undefined)
+            return offending;
+        rest = `${rest.slice(0, match.index)} ${TOKEN} ${rest.slice(match.index + match[0].length)}`;
+    }
+    return offScaleLiteral(valueAtoms(rest), scale);
+}
+/**
+ * The first atom (tokens already replaced) no scale rule accepts. A px
+ * offset subtracted from a token, or chained after such an offset, counts
+ * toward `offsetCap`, summed over the declaration.
+ */
+function offScaleLiteral(atoms, scale) {
+    let offsetTotal = 0;
+    let lastOffset = -1;
+    for (const [index, atom] of atoms.entries()) {
+        if (OPERATORS.has(atom.text) || atom.text === TOKEN)
+            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 = atom.inMath && scale.offsetCap !== undefined ? PX_LITERAL.exec(atom.text) : null;
+        const subtracted = px !== null &&
+            atoms[index - 1]?.text === '-' &&
+            (atoms[index - 2]?.text === TOKEN || lastOffset === index - 2);
+        if (subtracted) {
+            offsetTotal += Number(px[1]);
+            lastOffset = index;
+            if (offsetTotal <= (scale.offsetCap ?? 0))
+                continue;
+        }
+        return atom.text;
+    }
+    return undefined;
+}
+function inDescriptor(block) {
+    for (let at = block; at !== undefined; at = at.parent) {
+        if (DESCRIPTOR_AT_RULE.test(at.selector))
+            return true;
+    }
+    return false;
+}
+/**
+ * Every property declaration of a stylesheet outside descriptor blocks,
+ * the property lower-cased, with its 1-based line. Custom properties are
+ * not properties a scale governs.
+ *
+ * @param css - Stylesheet text
+ */
+export function cssDeclarations(css) {
+    return parseCss(css)
+        .declarations.filter((declaration) => !declaration.name.startsWith('--') && !inDescriptor(declaration.block))
+        .map((declaration) => ({
+        property: declaration.name.toLowerCase(),
+        value: declaration.value,
+        line: declaration.line + 1,
+    }));
+}
+const collapse = (value) => value.replace(/\s+/g, ' ').trim();
+function scalesFor(path, scales) {
+    return scales.filter((scale) => !matchesAnyGlob(path, scale.exclude ?? []));
+}
+const tokenScale = {
+    id: 'token-scale',
+    severity: 'error',
+    description: 'Governed properties in created stylesheets resolve to their token scale',
+    check(context) {
+        const scales = context.config.patchLint.tokenScales ?? [];
+        if (scales.length === 0)
+            return [];
+        return cssFiles(context, (file) => file.created).flatMap((file) => {
+            const governing = scalesFor(file.path, scales);
+            return cssDeclarations(file.text ?? '').flatMap(({ property, value, line }) => {
+                const scale = governing.find((candidate) => matchesPropertyName(property, candidate.properties));
+                if (scale === undefined || value === '')
+                    return [];
+                const allowed = (scale.allowValues ?? []).some((entry) => entry.property.toLowerCase() === property && collapse(entry.value) === collapse(value));
+                const atom = allowed ? undefined : offScaleAtom(value, scale);
+                if (atom === undefined)
+                    return [];
+                const label = scaleLabel(scale);
+                return [
+                    {
+                        path: file.path,
+                        line,
+                        group: file.group,
+                        message: `${property}: ${value} is off the ${label} scale ("${atom}"). Use a ${label} token, ` +
+                            'or list a reviewed exception in patchLint.tokenScales (allowLiterals, allowInCalc, ' +
+                            'allow, allowValues).',
+                    },
+                ];
+            });
+        });
+    },
+};
+const vacuousScale = {
+    id: 'token-scale-vacuous',
+    severity: 'error',
+    description: 'A scale with minFiles governs at least that many created stylesheets',
+    check(context) {
+        const floored = (context.config.patchLint.tokenScales ?? []).filter((scale) => scale.minFiles !== undefined);
+        const counts = new Map(floored.map((scale) => [scale, 0]));
+        for (const file of context.owned.all()) {
+            if (!file.created || !file.path.endsWith('.css') || file.text === undefined)
+                continue;
+            const properties = cssDeclarations(file.text).map((entry) => entry.property);
+            for (const scale of scalesFor(file.path, floored)) {
+                if (properties.some((property) => matchesPropertyName(property, scale.properties))) {
+                    counts.set(scale, (counts.get(scale) ?? 0) + 1);
+                }
+            }
+        }
+        return [...counts]
+            .filter(([scale, count]) => count < (scale.minFiles ?? 0))
+            .map(([scale, count]) => ({
+            message: `The ${scaleLabel(scale)} scale governs ${count} created stylesheet(s), under its ` +
+                `minFiles ${scale.minFiles ?? 0}. A scale that judges nothing passes vacuously: check ` +
+                'its properties and exclude globs, or lower minFiles after a reviewed move.',
+        }));
+    },
+};
+const staleExclude = {
+    id: 'stale-token-scale-exclude',
+    severity: 'warning',
+    description: 'Every token-scale exclude names an owned path',
+    check(context) {
+        const owned = context.changes.net().map((change) => change.path);
+        return (context.config.patchLint.tokenScales ?? []).flatMap((scale, index) => (scale.exclude ?? [])
+            .filter((glob) => !owned.some((path) => matchesAnyGlob(path, [glob])))
+            .map((glob) => ({
+            message: `Token scale ${index + 1} excludes ${glob}, which matches no owned path. Remove the retired exception.`,
+        })));
+    },
+};
+/** The stylesheet rules. */
+export const cssRules = [
+    rawColor,
+    tokenPrefix,
+    tokenScale,
+    vacuousScale,
+    staleExclude,
+];

package/dist/src/lint/rules/javascript.js

@@ -0,0 +1,299 @@
+import { markerComment } from '../../config/index.js';
+import { blankJsComments, isStringLiteral, lineAt, parseEither, relativeImportLines, walkJs, } from '../../syntax/index.js';
+import { basename, isJsFile } from '../rule.js';
+import { moduleJsDocProblems, scriptJsDocProblems } from './jsdoc.js';
+function jsFiles(context, accept) {
+    return context.owned
+        .all()
+        .filter((file) => file.text !== undefined &&
+        isJsFile(file.path) &&
+        context.selected(file.path) &&
+        accept(file));
+}
+function text(file) {
+    return file.text ?? '';
+}
+const BARE_ASSERTIONS = new Set(['ok', 'is', 'isnot', 'isDeeply']);
+const NAMESPACED_ASSERTIONS = new Set([
+    ...BARE_ASSERTIONS,
+    'equal',
+    'notEqual',
+    'deepEqual',
+    'notDeepEqual',
+    'strictEqual',
+    'notStrictEqual',
+    'greater',
+    'greaterOrEqual',
+    'less',
+    'lessOrEqual',
+    'stringMatches',
+    'stringContains',
+    'throws',
+    'rejects',
+    'todo',
+    'todo_is',
+    'todo_isnot',
+]);
+const TEXTUAL_ASSERTION = new RegExp(`(?<![\\w.#$-])(?:(?:Assert|SimpleTest)\\.(?:${[...NAMESPACED_ASSERTIONS].join('|')})\\s*\\(|(?:window\\.|[\\w$]+\\?\\.)?(?:${[...BARE_ASSERTIONS].join('|')})\\s*\\()`);
+function isAssertionCall(call, local) {
+    const callee = call.callee;
+    if (callee.type === 'Identifier')
+        return BARE_ASSERTIONS.has(callee.name) && !local.has(callee.name);
+    if (callee.type !== 'MemberExpression' || callee.computed)
+        return false;
+    if (callee.property.type !== 'Identifier')
+        return false;
+    const member = callee.property.name;
+    if (callee.optional && BARE_ASSERTIONS.has(member))
+        return true;
+    if (callee.object.type !== 'Identifier')
+        return false;
+    if (callee.object.name === 'window')
+        return BARE_ASSERTIONS.has(member);
+    return ((callee.object.name === 'Assert' || callee.object.name === 'SimpleTest') &&
+        NAMESPACED_ASSERTIONS.has(member));
+}
+/**
+ * Whether a browser test makes at least one assertion: a bare `ok`, `is`,
+ * `isnot` or `isDeeply` call (also `window.`-qualified or optional-chained)
+ * that the file does not declare itself, or an `Assert.*` / `SimpleTest.*`
+ * assertion. Strings and comments that spell a call do not count. Source
+ * acorn cannot parse is matched as text at a call boundary.
+ *
+ * @param source - The test source
+ */
+export function hasAssertion(source) {
+    const parsed = parseEither(source);
+    if (parsed === undefined)
+        return TEXTUAL_ASSERTION.test(blankJsComments(source));
+    const local = new Set();
+    walkJs(parsed.program, (node) => {
+        if (node.type === 'FunctionDeclaration')
+            local.add(node.id.name);
+        if (node.type === 'VariableDeclarator' && node.id.type === 'Identifier')
+            local.add(node.id.name);
+    });
+    let found = false;
+    walkJs(parsed.program, (node) => {
+        if (found || (node.type === 'CallExpression' && isAssertionCall(node, local)))
+            found = true;
+        return !found;
+    });
+    return found;
+}
+function isBrowserTest(path) {
+    const name = basename(path);
+    return (path.endsWith('.js') &&
+        /\/tests?\//.test(path) &&
+        name.startsWith('browser_') &&
+        name !== 'head.js' &&
+        !/^head_.*\.js$/.test(name));
+}
+/** Firefox's own topics, which owned code may observe or simulate under any name. */
+const FIREFOX_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',
+]);
+const OBSERVER_METHODS = new Set([
+    'addObserver',
+    'removeObserver',
+    'notifyObservers',
+]);
+const OBSERVER_CALL_TEXT = /\b(?:addObserver|removeObserver|notifyObservers)\s*\([^,()]*,\s*(["'`])([^"'`$\\]*)\1/g;
+/** The topic argument of an observer-service call, when it is a plain string. */
+function observerTopic(node) {
+    if (node.type !== 'CallExpression')
+        return undefined;
+    const callee = node.callee;
+    const method = callee.type === 'Identifier'
+        ? callee.name
+        : callee.type === 'MemberExpression' && callee.property.type === 'Identifier'
+            ? callee.property.name
+            : undefined;
+    if (method === undefined || !OBSERVER_METHODS.has(method))
+        return undefined;
+    const topic = node.arguments[1];
+    if (isStringLiteral(topic))
+        return topic.value;
+    if (topic?.type === 'TemplateLiteral' && topic.expressions.length === 0) {
+        return topic.quasis[0]?.value.cooked ?? undefined;
+    }
+    return undefined;
+}
+/**
+ * Observer topics a source names that carry the binary name but not the
+ * `<name>-<noun>-<verb>` shape: the second argument of `addObserver`,
+ * `removeObserver` and `notifyObservers`, when a plain string. Source acorn
+ * cannot parse is matched as comment-blanked text.
+ *
+ * @param source - JavaScript source
+ * @param binaryName - The project's binary name, lower case
+ */
+export function misnamedObserverTopics(source, binaryName) {
+    const calls = [];
+    const parsed = parseEither(source);
+    if (parsed === undefined) {
+        for (const match of blankJsComments(source).matchAll(OBSERVER_CALL_TEXT)) {
+            calls.push({ topic: match[2] ?? '', offset: match.index });
+        }
+    }
+    else {
+        walkJs(parsed.program, (node) => {
+            const topic = observerTopic(node);
+            if (topic !== undefined)
+                calls.push({ topic, offset: node.start });
+        });
+    }
+    return calls
+        .filter(({ topic }) => !FIREFOX_TOPICS.has(topic) &&
+        !topic.startsWith('quit-application') &&
+        topic.toLowerCase().includes(binaryName) &&
+        !/^\w+-[a-z]+-[a-z]+/.test(topic))
+        .map(({ topic, offset }) => ({ topic, line: lineAt(source, offset) }));
+}
+const relativeImport = {
+    id: 'relative-import',
+    severity: 'error',
+    description: 'Owned JavaScript imports through resource:// or chrome:// URLs, not relative paths',
+    async check(context) {
+        const drafts = [];
+        const binary = context.config.binaryName;
+        for (const file of jsFiles(context, (candidate) => !context.component(candidate.path))) {
+            let lines = relativeImportLines(text(file));
+            if (!file.created) {
+                const added = new Set((await context.owned.added(file.change)).map((entry) => entry.line));
+                lines = lines.filter((line) => added.has(line));
+            }
+            const [line] = lines;
+            if (line === undefined)
+                continue;
+            drafts.push({
+                path: file.path,
+                line,
+                group: file.group,
+                message: `Relative imports are not allowed. Use "resource:///modules/${binary}/" for modules or "chrome://browser/content/" for subscripts.`,
+            });
+        }
+        return drafts;
+    },
+};
+const modificationComment = {
+    id: 'missing-modification-comment',
+    severity: 'warning',
+    description: 'An edit to upstream JavaScript carries the `// MARKER:` comment',
+    async check(context) {
+        const marker = `// ${markerComment(context.config).toUpperCase()}:`;
+        const drafts = [];
+        for (const file of jsFiles(context, (candidate) => !candidate.created)) {
+            const added = await context.owned.added(file.change);
+            if (added.length === 0)
+                continue;
+            if (added.some((entry) => entry.text.toUpperCase().includes(marker)))
+                continue;
+            drafts.push({
+                path: file.path,
+                group: file.group,
+                message: `This upstream file's changes carry no "${marker}" comment marking them.`,
+            });
+        }
+        return drafts;
+    },
+};
+function jsdocRule(id, classMethods) {
+    return {
+        id,
+        severity: classMethods ? 'off' : 'error',
+        description: classMethods
+            ? 'Methods of exported classes of owned modules carry JSDoc'
+            : 'Exports of owned modules carry JSDoc naming their parameters and return',
+        check(context) {
+            return jsFiles(context, (file) => file.created && file.path.endsWith('.sys.mjs')).flatMap((file) => moduleJsDocProblems(text(file))
+                .filter((problem) => problem.classMethod === classMethods)
+                .map((problem) => ({
+                path: file.path,
+                line: problem.line,
+                group: file.group,
+                message: problem.message,
+            })));
+        },
+    };
+}
+const chromeScriptJsDoc = {
+    id: 'chrome-script-jsdoc',
+    severity: 'off',
+    description: 'Top-level functions and classes of owned chrome scripts carry JSDoc',
+    check(context) {
+        return jsFiles(context, (file) => file.created && file.path.endsWith('.js') && !file.path.endsWith('.sys.mjs')).flatMap((file) => {
+            const problems = scriptJsDocProblems(text(file));
+            if (problems === undefined) {
+                return [
+                    {
+                        path: file.path,
+                        group: file.group,
+                        severity: 'notice',
+                        message: 'The file did not parse as a script, so its JSDoc was not checked.',
+                    },
+                ];
+            }
+            return problems.map((problem) => ({
+                path: file.path,
+                line: problem.line,
+                group: file.group,
+                message: problem.message,
+            }));
+        });
+    },
+};
+const testAssertion = {
+    id: 'test-needs-assertion',
+    severity: 'off',
+    description: 'Every owned or modified browser test makes at least one assertion',
+    check(context) {
+        return jsFiles(context, (file) => isBrowserTest(file.path))
+            .filter((file) => !hasAssertion(text(file)))
+            .map((file) => ({
+            path: file.path,
+            group: file.group,
+            message: 'The test makes no assertion (Assert.*, ok(), is(), isnot(), isDeeply()). Add one that ' +
+                'pins user-visible behaviour, or remove the test.',
+        }));
+    },
+};
+const observerTopics = {
+    id: 'observer-topic-naming',
+    severity: 'warning',
+    description: 'Observer topics carrying the binary name follow `<name>-<noun>-<verb>`',
+    check(context) {
+        const name = context.config.binaryName.toLowerCase();
+        return jsFiles(context, () => true).flatMap((file) => misnamedObserverTopics(text(file), name).map(({ topic, line }) => ({
+            path: file.path,
+            line,
+            group: file.group,
+            message: `Observer topic "${topic}" should follow the "${name}-<noun>-<verb>" naming convention.`,
+        })));
+    },
+};
+/** The JavaScript content rules. */
+export const javascriptRules = [
+    relativeImport,
+    modificationComment,
+    jsdocRule('jsdoc', false),
+    jsdocRule('jsdoc-class-method', true),
+    chromeScriptJsDoc,
+    testAssertion,
+    observerTopics,
+];