@hominis/fireforge 0.54.0 → 0.60.0

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

@@ -1,67 +0,0 @@
-import { stripJsComments } from '../utils/regex.js';
-import { parseModule, parseScript, walkAST } from './ast-utils.js';
-const RELATIVE_IMPORT_FALLBACK_PATTERN = /(?:\bimport\s*(?:\(\s*)?(?:[\s\S]*?\bfrom\s*)?|\bexport\s+(?:[\s\S]*?\bfrom\s*)?|(?:ChromeUtils\.import(?:ESModule)?|Cu\.import)\s*\(\s*)["'](?:\.\.?\/)/m;
-function literalString(node) {
-    if (!node || node.type !== 'Literal')
-        return undefined;
-    return typeof node.value === 'string' ? node.value : undefined;
-}
-function isRelativeSpecifier(value) {
-    return value !== undefined && (value.startsWith('./') || value.startsWith('../'));
-}
-function isChromeImportCall(node) {
-    const callee = node.callee;
-    if (callee.type !== 'MemberExpression' || callee.computed)
-        return false;
-    if (callee.object.type !== 'Identifier' || callee.property.type !== 'Identifier')
-        return false;
-    if (callee.object.name === 'Cu') {
-        return callee.property.name === 'import';
-    }
-    return (callee.object.name === 'ChromeUtils' &&
-        (callee.property.name === 'import' || callee.property.name === 'importESModule'));
-}
-function astHasRelativeImport(content, sourceType) {
-    const ast = sourceType === 'module' ? parseModule(content) : parseScript(content);
-    let found = false;
-    walkAST(ast, {
-        enter(node) {
-            if (found) {
-                this.skip();
-                return;
-            }
-            if (node.type === 'ImportDeclaration') {
-                found = isRelativeSpecifier(literalString(node.source));
-            }
-            else if (node.type === 'ImportExpression') {
-                found = isRelativeSpecifier(literalString(node.source));
-            }
-            else if (node.type === 'ExportNamedDeclaration' || node.type === 'ExportAllDeclaration') {
-                found = isRelativeSpecifier(literalString(node.source));
-            }
-            else if (node.type === 'CallExpression' && isChromeImportCall(node)) {
-                found = isRelativeSpecifier(literalString(node.arguments[0]));
-            }
-        },
-    });
-    return found;
-}
-/**
- * Detects relative JS imports while avoiding comment/template false positives.
- * Falls back to stripped-text matching for legacy chrome scripts Acorn cannot parse.
- */
-export function hasRelativeImport(content) {
-    try {
-        return astHasRelativeImport(content, 'module');
-    }
-    catch {
-        // Not parseable as an ES module; try classic-script mode next.
-    }
-    try {
-        return astHasRelativeImport(content, 'script');
-    }
-    catch {
-        // Not parseable at all; fall back to stripped-text matching below.
-    }
-    return RELATIVE_IMPORT_FALLBACK_PATTERN.test(stripJsComments(content));
-}

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

@@ -1,67 +0,0 @@
-/**
- * AST-based JSDoc validation for exported declarations in `.sys.mjs`
- * modules. Uses Acorn (already a runtime dependency) to parse the
- * module and inspects JSDoc comments via the `onComment` callback.
- *
- * Separated from `patch-lint.ts` to keep both files within the
- * project's per-file line budget.
- */
-import type * as acorn from 'acorn';
-import type { ClassDeclaration, FunctionDeclaration } from 'estree';
-import type { AcornESTreeNode } from './ast-utils.js';
-export type JsDocCheck = 
-/** The source could not be parsed, so no JSDoc rule could run on it. */
-'jsdoc-unparseable-source' | 'missing-jsdoc' | 'jsdoc-param-mismatch' | 'jsdoc-missing-returns' | 'missing-jsdoc-class-method' | 'jsdoc-class-method-param-mismatch' | 'jsdoc-class-method-missing-returns';
-export interface JsDocIssue {
-    line: number;
-    check: JsDocCheck;
-    message: string;
-    /** Optional severity hint. When undefined, callers default to 'error'. */
-    severity?: 'error' | 'warning';
-}
-export type ClassMethodMode = 'off' | 'warning' | 'error';
-export interface ValidateExportJsDocOptions {
-    /** Gate for class-method JSDoc enforcement. Default 'off' (no walking). */
-    classMethodMode?: ClassMethodMode;
-}
-/**
- * Validates a top-level function declaration: requires an attached JSDoc
- * comment, then checks @param name matching and @returns presence. Exported
- * so the chrome-subscript validator (`patch-lint-chrome-jsdoc.ts`) can reuse
- * it on `parseScript`-produced declarations. The rule shape is identical
- * between ES-module exports and chrome-subscript top-level declarations.
- *
- * @param fn - FunctionDeclaration AST node
- * @param comments - All Acorn comments collected from the source
- * @param source - Original source text (for line-number resolution)
- * @param lookupStart - Optional offset to use when locating the attached
- *   JSDoc (defaults to `fn.start`). Used by the export-walker so the JSDoc
- *   is found relative to the `export` keyword rather than the inner decl.
- */
-export declare function validateFunctionDecl(fn: AcornESTreeNode<FunctionDeclaration>, comments: acorn.Comment[], source: string, lookupStart?: number): JsDocIssue[];
-/**
- * Validates a top-level class declaration: requires an attached JSDoc
- * comment on the class itself. Method-level checks live in
- * {@link validateClassMethods}. Exported for reuse in the chrome-subscript
- * validator.
- */
-export declare function validateClassDecl(cls: AcornESTreeNode<ClassDeclaration>, comments: acorn.Comment[], source: string, lookupStart?: number): JsDocIssue[];
-/**
- * Walks an exported class body and emits class-method JSDoc issues per the
- * configured severity. Skip rules (in evaluation order):
- *   1. private syntax (`#foo`) and underscore-prefixed names
- *   2. zero-parameter constructors
- *   3. methods whose JSDoc carries `@private` or `@internal`
- *
- * A pure-override skip (`super.method(...args)`-only bodies bypassing the
- * return-tag check) is deliberately not implemented. The rule stays simple.
- */
-export declare function validateClassMethods(cls: AcornESTreeNode<ClassDeclaration>, comments: acorn.Comment[], source: string, severity: 'warning' | 'error'): JsDocIssue[];
-/**
- * Validates JSDoc on exported declarations in a `.sys.mjs` source file.
- *
- * @param source - File content
- * @param options - Optional gates for opt-in checks (e.g. class-method JSDoc)
- * @returns Array of JSDoc issues found
- */
-export declare function validateExportJsDoc(source: string, options?: ValidateExportJsDocOptions): JsDocIssue[];

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

@@ -1,471 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * AST-based JSDoc validation for exported declarations in `.sys.mjs`
- * modules. Uses Acorn (already a runtime dependency) to parse the
- * module and inspects JSDoc comments via the `onComment` callback.
- *
- * Separated from `patch-lint.ts` to keep both files within the
- * project's per-file line budget.
- */
-import { toError } from '../utils/errors.js';
-import { asEstree, parseModule } from './ast-utils.js';
-// ---------------------------------------------------------------------------
-// JSDoc comment helpers
-// ---------------------------------------------------------------------------
-function isJsDocComment(comment) {
-    return comment.type === 'Block' && comment.value.startsWith('*');
-}
-/**
- * Finds the JSDoc comment immediately preceding `declStart` in the
- * source. "Immediately" means only whitespace and newlines may appear
- * between the comment's closing delimiter and the declaration.
- */
-function findAttachedJsDoc(comments, declStart, source) {
-    for (let i = comments.length - 1; i >= 0; i--) {
-        const c = comments[i];
-        if (!c || !isJsDocComment(c))
-            continue;
-        const commentEnd = c.end;
-        if (commentEnd > declStart)
-            continue;
-        const between = source.slice(commentEnd, declStart);
-        if (/^\s*$/.test(between))
-            return c;
-        break;
-    }
-    return undefined;
-}
-// ---------------------------------------------------------------------------
-// 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 undefined 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 undefined;
-}
-function extractParamNames(jsDoc) {
-    const names = [];
-    const tagPattern = /@param\b/g;
-    let m;
-    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 === undefined)
-                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;
-}
-function hasReturnsTag(jsDoc) {
-    return /@returns?\b/.test(jsDoc);
-}
-function hasPrivateOrInternalTag(jsDoc) {
-    return /@(?:private|internal)\b/.test(jsDoc);
-}
-// ---------------------------------------------------------------------------
-// Return-statement detection
-// ---------------------------------------------------------------------------
-/**
- * Returns true if any direct `ReturnStatement` in the function body
- * has a non-null argument. Does not recurse into nested functions or
- * arrow expressions which have their own return semantics.
- */
-function functionReturnsValue(node) {
-    return walkForReturn(node.body);
-}
-/**
- * Narrows an arbitrary child value reached by walking a node's own
- * properties to an ESTree node. Acorn's AST holds nodes, arrays of nodes,
- * and plain scalars in the same property positions, so the discriminating
- * `type` string is the only structural signal available.
- */
-function isEstreeNode(value) {
-    if (typeof value !== 'object' || value === null || !('type' in value))
-        return false;
-    return typeof value.type === 'string';
-}
-function walkForReturn(node) {
-    if (node.type === 'ReturnStatement') {
-        return node.argument != null;
-    }
-    if (node.type === 'FunctionDeclaration' ||
-        node.type === 'FunctionExpression' ||
-        node.type === 'ArrowFunctionExpression') {
-        return false;
-    }
-    // `entries` erases the node's static shape without asserting a new one.
-    // The `any` from `Object.entries`' fallback overload widens to `unknown`.
-    const entries = Object.entries(node);
-    for (const [key, val] of entries) {
-        if (key === 'type')
-            continue;
-        if (Array.isArray(val)) {
-            const children = val;
-            for (const child of children) {
-                if (isEstreeNode(child) && walkForReturn(child))
-                    return true;
-            }
-        }
-        else if (isEstreeNode(val) && walkForReturn(val)) {
-            return true;
-        }
-    }
-    return false;
-}
-function findLocalDeclaration(body, name) {
-    for (const stmt of body) {
-        if (stmt.type === 'FunctionDeclaration') {
-            const fn = stmt;
-            if (fn.id.name === name)
-                return stmt;
-        }
-        else if (stmt.type === 'ClassDeclaration') {
-            const cls = stmt;
-            if (cls.id.name === name)
-                return stmt;
-        }
-        else if (stmt.type === 'VariableDeclaration') {
-            const varDecl = stmt;
-            for (const d of varDecl.declarations) {
-                if (d.id.type === 'Identifier' && d.id.name === name) {
-                    return varDecl;
-                }
-            }
-        }
-    }
-    return undefined;
-}
-// ---------------------------------------------------------------------------
-// Line number helpers
-// ---------------------------------------------------------------------------
-function lineAt(source, offset) {
-    return source.slice(0, offset).split('\n').length;
-}
-/**
- * Validates @param name matching and @returns presence on a function-like
- * node that already has an attached JSDoc comment. Destructured, default-
- * valued, and rest params are silently skipped to match historical behavior
- * of the top-level export check.
- */
-function validateParamsAndReturns(fnNode, jsDoc, issues, ctx) {
-    const docText = jsDoc.value;
-    const actualParams = fnNode.params
-        .map((p) => (p.type === 'Identifier' ? p.name : null))
-        .filter((n) => n !== null);
-    if (actualParams.length > 0) {
-        const docParams = extractParamNames(docText);
-        for (const param of actualParams) {
-            if (!docParams.includes(param)) {
-                issues.push({
-                    line: ctx.line,
-                    check: ctx.paramCheck,
-                    message: `Exported ${ctx.label} at line ${ctx.line}: @param "${param}" is missing or misnamed in JSDoc.`,
-                    ...(ctx.severity ? { severity: ctx.severity } : {}),
-                });
-            }
-        }
-    }
-    if (!ctx.skipReturns && functionReturnsValue(fnNode) && !hasReturnsTag(docText)) {
-        issues.push({
-            line: ctx.line,
-            check: ctx.returnsCheck,
-            message: `Exported ${ctx.label} at line ${ctx.line} returns a value but JSDoc is missing @returns.`,
-            ...(ctx.severity ? { severity: ctx.severity } : {}),
-        });
-    }
-}
-// ---------------------------------------------------------------------------
-// Top-level export validation
-// ---------------------------------------------------------------------------
-/**
- * Validates a top-level function declaration: requires an attached JSDoc
- * comment, then checks @param name matching and @returns presence. Exported
- * so the chrome-subscript validator (`patch-lint-chrome-jsdoc.ts`) can reuse
- * it on `parseScript`-produced declarations. The rule shape is identical
- * between ES-module exports and chrome-subscript top-level declarations.
- *
- * @param fn - FunctionDeclaration AST node
- * @param comments - All Acorn comments collected from the source
- * @param source - Original source text (for line-number resolution)
- * @param lookupStart - Optional offset to use when locating the attached
- *   JSDoc (defaults to `fn.start`). Used by the export-walker so the JSDoc
- *   is found relative to the `export` keyword rather than the inner decl.
- */
-export function validateFunctionDecl(fn, comments, source, lookupStart) {
-    const issues = [];
-    const name = fn.id.name;
-    const start = lookupStart !== undefined ? lookupStart : fn.start;
-    const line = lineAt(source, start);
-    const jsDoc = findAttachedJsDoc(comments, start, source);
-    if (!jsDoc) {
-        issues.push({
-            line,
-            check: 'missing-jsdoc',
-            message: `Exported function "${name}" at line ${line} is missing a JSDoc comment.`,
-        });
-        return issues;
-    }
-    validateParamsAndReturns(fn, jsDoc, issues, {
-        label: `function "${name}"`,
-        line,
-        paramCheck: 'jsdoc-param-mismatch',
-        returnsCheck: 'jsdoc-missing-returns',
-    });
-    return issues;
-}
-/**
- * Validates a top-level class declaration: requires an attached JSDoc
- * comment on the class itself. Method-level checks live in
- * {@link validateClassMethods}. Exported for reuse in the chrome-subscript
- * validator.
- */
-export function validateClassDecl(cls, comments, source, lookupStart) {
-    const issues = [];
-    const name = cls.id.name;
-    const start = lookupStart !== undefined ? lookupStart : cls.start;
-    const line = lineAt(source, start);
-    const jsDoc = findAttachedJsDoc(comments, start, source);
-    if (!jsDoc) {
-        issues.push({
-            line,
-            check: 'missing-jsdoc',
-            message: `Exported class "${name}" at line ${line} is missing a JSDoc comment.`,
-        });
-    }
-    return issues;
-}
-function validateVariableDecl(varDecl, comments, source, lookupStart) {
-    const issues = [];
-    const start = lookupStart !== undefined ? lookupStart : varDecl.start;
-    const jsDoc = findAttachedJsDoc(comments, start, source);
-    if (jsDoc)
-        return issues; // has a JSDoc block, sufficient for constants
-    for (const decl of varDecl.declarations) {
-        const name = decl.id.type === 'Identifier' ? decl.id.name : '<destructured>';
-        const line = lineAt(source, start);
-        issues.push({
-            line,
-            check: 'missing-jsdoc',
-            message: `Exported constant "${name}" at line ${line} is missing a JSDoc comment.`,
-        });
-    }
-    return issues;
-}
-// ---------------------------------------------------------------------------
-// Class-method validation (opt-in via classMethodMode)
-// ---------------------------------------------------------------------------
-/**
- * Returns the method's identifier name when statically resolvable, or
- * undefined for computed keys (e.g. `[Symbol.iterator]()`). Private fields
- * (`#name`) are treated as private-by-syntax and surface as undefined here
- * so the walker skips them up front.
- */
-function staticMethodName(method) {
-    if (method.computed)
-        return undefined;
-    const key = method.key;
-    if (key.type !== 'Identifier')
-        return undefined;
-    return key.name;
-}
-function isPrivateMethodKey(method) {
-    return method.key.type === 'PrivateIdentifier';
-}
-function classMethodLabel(className, method, name) {
-    if (method.kind === 'constructor')
-        return `constructor of class "${className}"`;
-    const prefix = method.static ? 'static ' : '';
-    if (method.kind === 'get')
-        return `${prefix}getter "${className}.${name}"`;
-    if (method.kind === 'set')
-        return `${prefix}setter "${className}.${name}"`;
-    return `${prefix}method "${className}.${name}"`;
-}
-/**
- * Walks an exported class body and emits class-method JSDoc issues per the
- * configured severity. Skip rules (in evaluation order):
- *   1. private syntax (`#foo`) and underscore-prefixed names
- *   2. zero-parameter constructors
- *   3. methods whose JSDoc carries `@private` or `@internal`
- *
- * A pure-override skip (`super.method(...args)`-only bodies bypassing the
- * return-tag check) is deliberately not implemented. The rule stays simple.
- */
-export function validateClassMethods(cls, comments, source, severity) {
-    const issues = [];
-    const className = cls.id.name;
-    for (const member of cls.body.body) {
-        if (member.type !== 'MethodDefinition')
-            continue;
-        const method = asEstree(member);
-        if (isPrivateMethodKey(method))
-            continue;
-        const name = staticMethodName(method);
-        if (name === undefined)
-            continue;
-        if (method.kind !== 'constructor' && name.startsWith('_'))
-            continue;
-        if (method.kind === 'constructor' && method.value.params.length === 0)
-            continue;
-        const methodStart = method.start;
-        const line = lineAt(source, methodStart);
-        const jsDoc = findAttachedJsDoc(comments, methodStart, source);
-        if (jsDoc && hasPrivateOrInternalTag(jsDoc.value))
-            continue;
-        const label = classMethodLabel(className, method, name);
-        if (!jsDoc) {
-            issues.push({
-                line,
-                check: 'missing-jsdoc-class-method',
-                message: `Exported ${label} at line ${line} is missing a JSDoc comment.`,
-                severity,
-            });
-            continue;
-        }
-        if (method.kind === 'get') {
-            // Presence already verified. The getter expression is the contract.
-            continue;
-        }
-        const skipReturns = method.kind === 'constructor' || method.kind === 'set';
-        validateParamsAndReturns(asEstree(method.value), jsDoc, issues, {
-            label,
-            line,
-            paramCheck: 'jsdoc-class-method-param-mismatch',
-            returnsCheck: 'jsdoc-class-method-missing-returns',
-            severity,
-            skipReturns,
-        });
-    }
-    return issues;
-}
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Validates JSDoc on exported declarations in a `.sys.mjs` source file.
- *
- * @param source - File content
- * @param options - Optional gates for opt-in checks (e.g. class-method JSDoc)
- * @returns Array of JSDoc issues found
- */
-export function validateExportJsDoc(source, options) {
-    const classMethodMode = options?.classMethodMode ?? 'off';
-    const comments = [];
-    let ast;
-    try {
-        ast = parseModule(source, comments);
-    }
-    catch (error) {
-        // An unparseable source is not a clean file. Returning `[]` here was the
-        // same value as "fully documented", so a syntax error silently cleared
-        // every rule this module enforces. Report it instead.
-        return [
-            {
-                line: 1,
-                check: 'jsdoc-unparseable-source',
-                message: `Source could not be parsed for JSDoc analysis: ${toError(error).message}`,
-            },
-        ];
-    }
-    const issues = [];
-    const body = ast.body;
-    for (const node of body) {
-        if (node.type !== 'ExportNamedDeclaration')
-            continue;
-        const exportNode = node;
-        // Case 1: inline export declaration, JSDoc attaches to `export`
-        if (exportNode.declaration) {
-            const decl = exportNode.declaration;
-            const exportStart = exportNode.start;
-            if (decl.type === 'FunctionDeclaration') {
-                issues.push(...validateFunctionDecl(decl, comments, source, exportStart));
-            }
-            else if (decl.type === 'ClassDeclaration') {
-                issues.push(...validateClassDecl(decl, comments, source, exportStart));
-                if (classMethodMode !== 'off') {
-                    issues.push(...validateClassMethods(decl, comments, source, classMethodMode));
-                }
-            }
-            else if (decl.type === 'VariableDeclaration') {
-                issues.push(...validateVariableDecl(decl, comments, source, exportStart));
-            }
-            continue;
-        }
-        // Case 2: `export { foo, Bar }`, resolve back to local declarations
-        if (exportNode.specifiers.length > 0 && !exportNode.source) {
-            for (const spec of exportNode.specifiers) {
-                const local = spec.local;
-                if (local.type !== 'Identifier')
-                    continue;
-                const localName = local.name;
-                const localDecl = findLocalDeclaration(body, localName);
-                if (!localDecl)
-                    continue;
-                if (localDecl.type === 'FunctionDeclaration') {
-                    issues.push(...validateFunctionDecl(localDecl, comments, source));
-                }
-                else if (localDecl.type === 'ClassDeclaration') {
-                    issues.push(...validateClassDecl(localDecl, comments, source));
-                    if (classMethodMode !== 'off') {
-                        issues.push(...validateClassMethods(localDecl, comments, source, classMethodMode));
-                    }
-                }
-                else {
-                    issues.push(...validateVariableDecl(localDecl, comments, source));
-                }
-            }
-        }
-    }
-    return issues;
-}

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

@@ -1,22 +0,0 @@
-import type { PatchLintIssue } from '../types/commands/index.js';
-import type { PatchQueueRegistrationEntry, PatchQueueView } from './patch-lint-queue-types.js';
-type ModuleRegistrationQueueContext = PatchQueueView<PatchQueueRegistrationEntry>;
-/**
- * Maps Firefox's common system-module resource URLs to their source
- * suffix. Exported alongside {@link extractResourceModuleSpecifiers} so
- * the resolution preflight resolves specifiers identically.
- */
-export declare function moduleSourceSuffix(specifier: string): string | undefined;
-/**
- * Resource-module strings in actual code (comments removed), de-duplicated.
- * Exported for the engine-aware resolution preflight, which must recognise
- * exactly the same specifier shapes this queue-level rule does. Two
- * extractors would drift.
- */
-export declare function extractResourceModuleSpecifiers(content: string): string[];
-/**
- * Flags a new `.sys.mjs` imported through a Firefox resource URL when the
- * projected queue never adds it to a moz.build list.
- */
-export declare function lintPatchQueueModuleRegistrations(ctx: ModuleRegistrationQueueContext): PatchLintIssue[];
-export {};