@hominis/fireforge 0.55.0 → 0.60.0

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

@@ -0,0 +1,249 @@
+import { toError } from '../../kernel/errors.js';
+import { lineAt, parseJs } from '../../syntax/index.js';
+function attachedJsDoc(comments, start, source) {
+    for (let i = comments.length - 1; i >= 0; i--) {
+        const comment = comments[i];
+        if (comment === undefined || comment.end > start)
+            continue;
+        if (comment.type !== 'Block' || !comment.value.startsWith('*'))
+            return undefined;
+        return /^\s*$/.test(source.slice(comment.end, start)) ? comment : undefined;
+    }
+    return undefined;
+}
+/** Skips a balanced `{ … }` type expression; quoted runs may hold braces. */
+function skipType(doc, start) {
+    let depth = 0;
+    let quote;
+    for (let i = start; i < doc.length; i++) {
+        const char = doc.charAt(i);
+        if (quote !== undefined) {
+            if (char === '\\')
+                i++;
+            else if (char === quote)
+                quote = undefined;
+        }
+        else if (char === '"' || char === "'" || char === '`')
+            quote = char;
+        else if (char === '{')
+            depth++;
+        else if (char === '}' && --depth === 0)
+            return i + 1;
+    }
+    return undefined;
+}
+/** The parameter names a JSDoc block documents; `opts.id` records `opts`. */
+export function documentedParams(doc) {
+    const names = [];
+    for (const tag of doc.matchAll(/@param\b/g)) {
+        let i = tag.index + tag[0].length;
+        while (/\s/.test(doc.charAt(i)))
+            i++;
+        if (doc.charAt(i) === '{') {
+            const after = skipType(doc, i);
+            if (after === undefined)
+                continue;
+            i = after;
+            while (/\s/.test(doc.charAt(i)))
+                i++;
+        }
+        if (doc.charAt(i) === '[')
+            i++;
+        const name = /^[A-Za-z_$][\w$]*/.exec(doc.slice(i))?.[0];
+        if (name !== undefined && !names.includes(name))
+            names.push(name);
+    }
+    return names;
+}
+function isNode(value) {
+    return typeof value === 'object' && value !== null && 'type' in value;
+}
+/** Whether a direct `return` (not one in a nested function) carries a value. */
+function returnsValue(node) {
+    if (node.type === 'ReturnStatement')
+        return node.argument != null;
+    if (node.type === 'FunctionDeclaration' ||
+        node.type === 'FunctionExpression' ||
+        node.type === 'ArrowFunctionExpression') {
+        return false;
+    }
+    for (const [key, value] of Object.entries(node)) {
+        if (key === 'type')
+            continue;
+        const children = Array.isArray(value) ? value : [value];
+        if (children.some((child) => isNode(child) && returnsValue(child)))
+            return true;
+    }
+    return false;
+}
+function checkSignature(walk, fn, doc, subject) {
+    const documented = documentedParams(doc.value);
+    for (const param of fn.params) {
+        if (param.type !== 'Identifier' || documented.includes(param.name))
+            continue;
+        walk.problems.push({
+            line: subject.line,
+            classMethod: subject.classMethod,
+            message: `${subject.label}: @param "${param.name}" is missing or misnamed in its JSDoc.`,
+        });
+    }
+    if (subject.skipReturns !== true && returnsValue(fn.body) && !/@returns?\b/.test(doc.value)) {
+        walk.problems.push({
+            line: subject.line,
+            classMethod: subject.classMethod,
+            message: `${subject.label} returns a value but its JSDoc has no @returns.`,
+        });
+    }
+}
+function checkFunction(walk, fn, start = fn.start) {
+    const line = lineAt(walk.source, start);
+    const label = `Function "${fn.id.name}" at line ${line}`;
+    const doc = attachedJsDoc(walk.comments, start, walk.source);
+    if (doc === undefined) {
+        walk.problems.push({ line, classMethod: false, message: `${label} has no JSDoc comment.` });
+        return;
+    }
+    checkSignature(walk, fn, doc, { label, line, classMethod: false });
+}
+function methodLabel(className, method, name) {
+    if (method.kind === 'constructor')
+        return `Constructor of class "${className}"`;
+    const kind = method.kind === 'get' ? 'Getter' : method.kind === 'set' ? 'Setter' : 'Method';
+    return `${method.static ? 'Static ' : ''}${kind} "${className}.${name}"`;
+}
+function checkMethods(walk, cls) {
+    const className = cls.id.name;
+    for (const member of cls.body.body) {
+        if (member.type !== 'MethodDefinition' || member.computed)
+            continue;
+        if (member.key.type !== 'Identifier')
+            continue;
+        const name = member.key.name;
+        if (member.kind !== 'constructor' && name.startsWith('_'))
+            continue;
+        if (member.kind === 'constructor' && member.value.params.length === 0)
+            continue;
+        const start = member.start;
+        const line = lineAt(walk.source, start);
+        const doc = attachedJsDoc(walk.comments, start, walk.source);
+        if (doc !== undefined && /@(?:private|internal)\b/.test(doc.value))
+            continue;
+        const label = `${methodLabel(className, member, name)} at line ${line}`;
+        if (doc === undefined) {
+            walk.problems.push({ line, classMethod: true, message: `${label} has no JSDoc comment.` });
+            continue;
+        }
+        if (member.kind === 'get')
+            continue;
+        checkSignature(walk, member.value, doc, {
+            label,
+            line,
+            classMethod: true,
+            skipReturns: member.kind === 'constructor' || member.kind === 'set',
+        });
+    }
+}
+function checkClass(walk, cls, start = cls.start) {
+    const line = lineAt(walk.source, start);
+    if (attachedJsDoc(walk.comments, start, walk.source) === undefined) {
+        walk.problems.push({
+            line,
+            classMethod: false,
+            message: `Class "${cls.id.name}" at line ${line} has no JSDoc comment.`,
+        });
+    }
+    checkMethods(walk, cls);
+}
+function checkVariable(walk, declaration, start = declaration.start) {
+    if (attachedJsDoc(walk.comments, start, walk.source) !== undefined)
+        return;
+    const line = lineAt(walk.source, start);
+    for (const declarator of declaration.declarations) {
+        const name = declarator.id.type === 'Identifier' ? declarator.id.name : '<destructured>';
+        walk.problems.push({
+            line,
+            classMethod: false,
+            message: `Constant "${name}" at line ${line} has no JSDoc comment.`,
+        });
+    }
+}
+function checkDeclaration(walk, declaration, start) {
+    if (declaration.type === 'FunctionDeclaration')
+        checkFunction(walk, declaration, start);
+    else if (declaration.type === 'ClassDeclaration')
+        checkClass(walk, declaration, start);
+    else
+        checkVariable(walk, declaration, start);
+}
+function localDeclaration(body, name) {
+    const found = body.find((statement) => ((statement.type === 'FunctionDeclaration' || statement.type === 'ClassDeclaration') &&
+        statement.id.name === name) ||
+        (statement.type === 'VariableDeclaration' &&
+            statement.declarations.some((d) => d.id.type === 'Identifier' && d.id.name === name)));
+    return found;
+}
+/**
+ * JSDoc problems on the exports of an ES module: inline exports, whose
+ * JSDoc attaches to `export`, and `export { a, B }` lists resolved to their
+ * local declarations. Source that does not parse is one problem.
+ *
+ * @param source - The module source
+ */
+export function moduleJsDocProblems(source) {
+    let parsed;
+    try {
+        parsed = parseJs(source, 'module');
+    }
+    catch (error) {
+        return [
+            {
+                line: 1,
+                classMethod: false,
+                message: `The module did not parse, so its JSDoc was not checked: ${toError(error).message}`,
+            },
+        ];
+    }
+    const walk = { source, comments: parsed.comments, problems: [] };
+    const body = parsed.program.body;
+    for (const node of body) {
+        if (node.type !== 'ExportNamedDeclaration')
+            continue;
+        if (node.declaration) {
+            checkDeclaration(walk, node.declaration, node.start);
+            continue;
+        }
+        if (node.source)
+            continue;
+        for (const specifier of node.specifiers) {
+            if (specifier.local.type !== 'Identifier')
+                continue;
+            const local = localDeclaration(body, specifier.local.name);
+            if (local !== undefined)
+                checkDeclaration(walk, local);
+        }
+    }
+    return walk.problems;
+}
+/**
+ * JSDoc problems on the top-level functions and classes of a chrome
+ * subscript.
+ *
+ * @param source - The script source
+ * @returns The problems, or undefined when the source does not parse as a script
+ */
+export function scriptJsDocProblems(source) {
+    let parsed;
+    try {
+        parsed = parseJs(source, 'script');
+    }
+    catch {
+        return undefined;
+    }
+    const walk = { source, comments: parsed.comments, problems: [] };
+    for (const node of parsed.program.body) {
+        if (node.type === 'FunctionDeclaration' || node.type === 'ClassDeclaration') {
+            checkDeclaration(walk, node);
+        }
+    }
+    return walk.problems;
+}

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

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * License-header rules: the acceptance policy for files the project creates
+ * (`missing-license-header`), and the check that an upstream file the
+ * project modifies still starts with a recognised header
+ * (`modified-file-missing-header`).
+ */
+import { hasLicenseHeader, hasUpstreamMplHeader, licenseHeader, mentionsLicense, } from '../../project/index.js';
+import { isJsFile } from '../rule.js';
+/**
+ * The comment style of a file kind that carries a header, or undefined.
+ *
+ * @param path - Engine-relative path
+ */
+function commentStyle(path) {
+    if (path.endsWith('.css'))
+        return 'css';
+    if (path.endsWith('.ftl'))
+        return 'hash';
+    return isJsFile(path) ? 'js' : undefined;
+}
+/**
+ * Whether a created file's header is acceptable: the project's own header;
+ * any recognised header under `browser/branding/` (copied from Firefox's
+ * branding template) or in an MPL-2.0 project; or, in a block-comment file
+ * kind, the verbatim upstream MPL block header of a file copied from
+ * Firefox.
+ *
+ * @param path - Engine-relative path
+ * @param content - File content
+ * @param license - The project license
+ */
+export function acceptsCreatedHeader(path, content, license) {
+    const style = commentStyle(path);
+    if (style === undefined)
+        return true;
+    if (content.startsWith(licenseHeader(license, style)))
+        return true;
+    if ((path.startsWith('browser/branding/') || license === 'MPL-2.0') &&
+        hasLicenseHeader(content, style)) {
+        return true;
+    }
+    return style !== 'hash' && hasUpstreamMplHeader(content);
+}
+const missingHeader = {
+    id: 'missing-license-header',
+    severity: 'error',
+    description: 'Files the project creates start with the project license header',
+    check(context) {
+        const license = context.config.license;
+        return context.owned
+            .all()
+            .filter((file) => file.created &&
+            file.text !== undefined &&
+            context.selected(file.path) &&
+            !acceptsCreatedHeader(file.path, file.text, license))
+            .map((file) => ({
+            path: file.path,
+            line: 1,
+            group: file.group,
+            message: `The file does not start with the ${license} license header.`,
+        }));
+    },
+};
+const modifiedHeader = {
+    id: 'modified-file-missing-header',
+    severity: 'warning',
+    description: 'Upstream files the project modifies still start with a recognised license header',
+    check(context) {
+        return context.owned.all().flatMap((file) => {
+            const style = commentStyle(file.path);
+            if (file.created || file.text === undefined || style === undefined)
+                return [];
+            if (!context.selected(file.path))
+                return [];
+            const text = file.text;
+            const recognised = ['js', 'css', 'hash'].some((candidate) => hasLicenseHeader(text, candidate)) ||
+                mentionsLicense(text);
+            if (recognised)
+                return [];
+            return [
+                {
+                    path: file.path,
+                    line: 1,
+                    group: file.group,
+                    message: 'This modified upstream file no longer starts with a recognised license header.',
+                },
+            ];
+        });
+    },
+};
+/** The license-header rules. */
+export const licenseRules = [missingHeader, modifiedHeader];

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

@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `patchPolicy` over the owned changes: which upstream files a group may
+ * change and how, which files a class of group may touch, and that the
+ * documents behind reviewed exceptions exist.
+ *
+ * A path is upstream when its first owned step is not a create. A group
+ * named by a `reservedRanges[].allowed` entry is an exception: it may
+ * change the upstream files the entry lists (any, when it lists none)
+ * outside `upstreamAllowlist`, and its list must not name an upstream file
+ * it no longer changes. Every other group may change an upstream file only
+ * when an allowlist glob matches it; under an `addOnly` entry it may only
+ * add lines, each carrying the marker, and remove lines that name one of
+ * the entry's `retiredPaths`.
+ */
+import { join } from 'node:path';
+import { exists } from '../../kernel/fs.js';
+import { matchesAnyGlob } from '../../kernel/glob.js';
+function severityOf(policy) {
+    return policy.mutationMode === 'warn' ? 'warning' : 'error';
+}
+function exceptionFor(policy, group) {
+    if (group === undefined)
+        return undefined;
+    return (policy.reservedRanges ?? [])
+        .flatMap((range) => range.allowed)
+        .find((entry) => entry.filename === group);
+}
+/** The steps that change upstream paths, by group (`''` for ungrouped steps). */
+function upstreamSteps(context) {
+    const byGroup = new Map();
+    for (const step of context.changes.changes) {
+        if (context.changes.at(step.path)[0]?.kind === 'create')
+            continue;
+        const key = step.group ?? '';
+        byGroup.set(key, [...(byGroup.get(key) ?? []), step]);
+    }
+    return byGroup;
+}
+const label = (group) => (group === '' ? 'Ungrouped changes' : group);
+async function addOnlyViolation(context, step, marker, retired) {
+    if (step.kind === 'delete')
+        return 'deletes the file';
+    if (step.binary)
+        return 'changes it as binary';
+    const removed = (await context.owned.removed(step)).filter((line) => line.trim() !== '' && !retired.some((path) => line.includes(path)));
+    if (removed.length > 0) {
+        return `removes ${removed.length} line(s), first: ${JSON.stringify(removed[0])}`;
+    }
+    const unmarked = (await context.owned.added(step)).filter((entry) => entry.text.trim() !== '' && !entry.text.toLowerCase().includes(marker.toLowerCase()));
+    const [first] = unmarked;
+    if (first === undefined)
+        return undefined;
+    return `adds ${unmarked.length} line(s) without the "${marker}" marker, first: ${JSON.stringify(first.text)}`;
+}
+function exceptionDrafts(context, group, steps, exception) {
+    if (exception.files === undefined)
+        return [];
+    const listed = new Set(exception.files);
+    const changed = new Set(steps.map((step) => step.path));
+    const outside = [...changed].filter((path) => !listed.has(path)).sort();
+    const stale = exception.files.filter((path) => !changed.has(path) && context.changes.at(path)[0]?.kind !== 'create');
+    const drafts = [];
+    if (outside.length > 0) {
+        drafts.push({
+            group,
+            message: `${group} is a reviewed exception, but changes upstream file(s) its entry does not list: ${outside.join(', ')}.`,
+        });
+    }
+    if (stale.length > 0) {
+        drafts.push({
+            group,
+            message: `${group}'s exception lists upstream file(s) it no longer changes: ${stale.join(', ')}. Update the entry.`,
+        });
+    }
+    return drafts;
+}
+const upstreamAllowlist = {
+    id: 'upstream-allowlist',
+    severity: 'error',
+    description: 'Upstream files change only where patchPolicy allows it',
+    check(context) {
+        const policy = context.config.patchPolicy;
+        if (policy === undefined)
+            return [];
+        const severity = severityOf(policy);
+        const globs = (policy.upstreamAllowlist ?? []).map((entry) => typeof entry === 'string' ? entry : entry.path);
+        const drafts = [];
+        for (const [group, steps] of upstreamSteps(context)) {
+            const exception = exceptionFor(policy, group);
+            if (exception !== undefined) {
+                drafts.push(...exceptionDrafts(context, group, steps, exception).map((d) => ({ ...d, severity })));
+                continue;
+            }
+            if (policy.upstreamAllowlist === undefined)
+                continue;
+            const outside = [...new Set(steps.map((step) => step.path))]
+                .filter((path) => !matchesAnyGlob(path, globs))
+                .sort();
+            if (outside.length === 0)
+                continue;
+            drafts.push({
+                ...(group === '' ? {} : { group }),
+                severity,
+                message: `${label(group)} change(s) upstream file(s) outside patchPolicy.upstreamAllowlist: ` +
+                    `${outside.join(', ')}. Move the change into a project-owned file, or add a reviewed allowlist entry.`,
+            });
+        }
+        return drafts;
+    },
+};
+const addOnly = {
+    id: 'add-only',
+    severity: 'error',
+    description: 'Add-only upstream files only gain lines carrying the marker',
+    async check(context) {
+        const policy = context.config.patchPolicy;
+        const entries = (policy?.upstreamAllowlist ?? []).filter((entry) => typeof entry !== 'string' && entry.addOnly === true);
+        if (policy === undefined || entries.length === 0)
+            return [];
+        const drafts = [];
+        for (const [group, steps] of upstreamSteps(context)) {
+            if (exceptionFor(policy, group) !== undefined)
+                continue;
+            for (const step of steps) {
+                const matching = entries.filter((entry) => matchesAnyGlob(step.path, [entry.path]));
+                const [first] = matching;
+                if (first === undefined)
+                    continue;
+                const marker = first.marker ?? policy.addOnlyMarker ?? '';
+                const retired = matching.flatMap((entry) => entry.retiredPaths ?? []);
+                const violation = await addOnlyViolation(context, step, marker, retired);
+                if (violation === undefined)
+                    continue;
+                drafts.push({
+                    path: step.path,
+                    ...(group === '' ? {} : { group }),
+                    severity: severityOf(policy),
+                    message: `${label(group)} edits this add-only upstream file (added lines carry "${marker}"), but ${violation}.`,
+                });
+            }
+        }
+        return drafts;
+    },
+};
+const scope = {
+    id: 'scope',
+    severity: 'error',
+    description: 'Groups a scope rule selects touch only the files it names',
+    check(context) {
+        const policy = context.config.patchPolicy;
+        if (policy === undefined)
+            return [];
+        return (policy.scopeRules ?? []).flatMap((rule, index) => context.changes.groups
+            .filter((group) => new RegExp(rule.group).test(group.id))
+            .flatMap((group) => {
+            const outside = context.changes
+                .inGroup(group.id)
+                .map((step) => step.path)
+                .filter((path) => !matchesAnyGlob(path, rule.files));
+            if (outside.length === 0)
+                return [];
+            return [
+                {
+                    group: group.id,
+                    severity: severityOf(policy),
+                    message: `${group.id} is scoped by patchPolicy.scopeRules[${index}] to ${rule.files.join(', ')}, ` +
+                        `but touches: ${outside.join(', ')}. Move those files to a group of the class that owns them.`,
+                },
+            ];
+        }));
+    },
+};
+const documents = {
+    id: 'policy-document-missing',
+    severity: 'error',
+    description: 'The decision records and documents of reviewed exceptions exist',
+    async check(context) {
+        const policy = context.config.patchPolicy;
+        if (policy?.verifyDocumentPaths !== true)
+            return [];
+        const drafts = [];
+        for (const entry of (policy.reservedRanges ?? []).flatMap((range) => range.allowed)) {
+            for (const [field, path] of [
+                ['adr', entry.adr],
+                ['documentation', entry.documentation],
+            ]) {
+                if (path === undefined || (await exists(join(context.projectRoot, path))))
+                    continue;
+                drafts.push({
+                    group: entry.filename,
+                    severity: severityOf(policy),
+                    message: `${entry.filename}'s exception names ${field} "${path}", which does not exist. Restore it or correct the path.`,
+                });
+            }
+        }
+        return drafts;
+    },
+};
+/** The policy rules. */
+export const policyRules = [upstreamAllowlist, addOnly, scope, documents];