@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/core/patch-lint-unmanaged-companion.js

@@ -1,214 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Recognizes the one shape where the undefined-identifier hint sends the
- * operator at the wrong remedy, and where taking that remedy would mask a
- * real bug.
- *
- * The shape: helpers are hoisted out of duplicated test files into a new
- * `head_settings.js` that a managed `head.js` pulls in with
- * `loadSubScript`. Until that companion is exported it belongs to no patch,
- * so the per-patch checkJs program, which only ever loads patch-owned
- * roots, cannot see any of its declarations. Every use of every hoisted
- * helper is then reported as `Cannot find name`, and the generic hint
- * offers three remedies of which the shim is the easiest: adding the
- * globals to `extraShim` makes all of the warnings disappear and makes a
- * genuinely missing helper undetectable forever after.
- *
- * The warnings themselves are correct: they are the per-patch program's
- * honest view of a file that is in no patch. Only the advice is wrong.
- * FireForge already knows ownership, so when every undefined name in a file
- * is declared at the top level of an unmanaged file that a managed head
- * loads, it can name that file and the adoption command instead.
- *
- * Detection is conservative on both halves: a companion must
- * be reachable from an actual `loadSubScript` call, and every undefined
- * name must resolve inside it. One unresolved name means the file may
- * genuinely be missing a helper, and the generic hint stays.
- */
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { UNDEFINED_IDENTIFIER_HINT } from './typecheck-shim.js';
-/**
- * String literals passed anywhere inside a `loadSubScript(...)` call.
- *
- * The mochitest idiom is
- * `Services.scriptloader.loadSubScript(getRootDirectory(gTestPath) + "head_settings.js", this)`,
- * so the useful signal is the `.js` literal inside the call, not a
- * resolvable URL. The path half is computed at runtime.
- */
-export function findLoadSubScriptTargets(source) {
-    const targets = [];
-    // Scanned to the statement terminator rather than to a closing paren:
-    // the idiomatic argument is itself a call (`getRootDirectory(gTestPath) +
-    // "head_settings.js"`), so a non-greedy `\)` stops on the inner paren and
-    // never reaches the literal.
-    for (const call of source.matchAll(/loadSubScript\s*\(/g)) {
-        const from = call.index + call[0].length;
-        const semicolon = source.indexOf(';', from);
-        const to = semicolon === -1 ? from + CALL_SCAN_LIMIT : Math.min(semicolon, from + CALL_SCAN_LIMIT);
-        for (const literal of source.slice(from, to).matchAll(/["'`]([^"'`]*\.js)["'`]/g)) {
-            const value = literal[1];
-            if (value !== undefined && value.length > 0)
-                targets.push(value);
-        }
-    }
-    return targets;
-}
-/** How far past a `loadSubScript(` the argument scan looks. */
-const CALL_SCAN_LIMIT = 400;
-/**
- * Top-level declaration names in a script-scope file.
- *
- * Regex rather than a TS program on purpose: this runs only to decide the
- * wording of a hint, the file is outside every program the
- * pass built, and a missed declaration degrades to the generic hint rather
- * than to a wrong answer. Matching is anchored at column zero so a nested
- * declaration inside a function body is not mistaken for a global.
- */
-export function collectTopLevelDeclarations(source) {
-    const names = new Set();
-    const patterns = [
-        /^(?:async\s+)?function\s*\*?\s*([A-Za-z_$][\w$]*)/gm,
-        /^(?:const|let|var)\s+([A-Za-z_$][\w$]*)/gm,
-        /^class\s+([A-Za-z_$][\w$]*)/gm,
-    ];
-    for (const pattern of patterns) {
-        for (const match of source.matchAll(pattern)) {
-            const name = match[1];
-            if (name !== undefined)
-                names.add(name);
-        }
-    }
-    return names;
-}
-/**
- * Extracts the identifier from a `Cannot find name 'X'` diagnostic message,
- * or undefined when the message is not one.
- */
-function extractUndefinedIdentifier(message) {
-    const match = /Cannot find name '([^']+)'/.exec(message);
-    return match?.[1];
-}
-/**
- * Resolves the unmanaged companions reachable from a set of managed head
- * files, given a reader for repo-relative file content.
- *
- * A candidate qualifies only when it is not in `ownedFiles` and its content
- * can be read. An unreadable or absent target is simply not a companion,
- * and the generic hint applies.
- *
- * @param heads - Repo-relative managed head files, with their sources
- * @param ownedFiles - Every patch-owned repo-relative path
- * @param readFile - Reads a repo-relative file, or returns undefined
- */
-export async function resolveUnmanagedCompanions(heads, ownedFiles, readFile) {
-    const companions = [];
-    const seen = new Set();
-    for (const head of heads) {
-        const dir = head.file.slice(0, head.file.lastIndexOf('/') + 1);
-        for (const target of findLoadSubScriptTargets(head.source)) {
-            // Only same-directory targets: the runtime path is computed from the
-            // test's own directory, and a bare basename is what that idiom yields.
-            const candidate = `${dir}${target.slice(target.lastIndexOf('/') + 1)}`;
-            if (candidate === head.file || ownedFiles.has(candidate) || seen.has(candidate))
-                continue;
-            seen.add(candidate);
-            const source = await readFile(candidate);
-            if (source === undefined)
-                continue;
-            companions.push({
-                file: candidate,
-                loadedBy: head.file,
-                declarations: collectTopLevelDeclarations(source),
-            });
-        }
-    }
-    return companions;
-}
-/**
- * The replacement hint, when every undefined name resolves in one
- * unmanaged companion.
- *
- * States the ownership fact first (the diagnosis), then the adoption
- * command, and explicitly rules the shim out. The shim is what an operator
- * reaches for by default here, and it is the one remedy that permanently
- * hides a genuinely missing helper.
- */
-export function formatUnmanagedCompanionHint(companion) {
-    return (`(undefined identifier — every one of them is declared in ${companion.file}, which ` +
-        `${companion.loadedBy} loads via loadSubScript but which NO patch owns yet, so the ` +
-        `per-patch program cannot see it. Adopt it with ` +
-        `"fireforge re-export <patch> --scan --scan-file ${companion.file}". Do NOT add these ` +
-        `globals to the extra shim: that silences these warnings and every future genuinely ` +
-        `missing helper with them.)`);
-}
-/**
- * Picks the companion that explains every undefined identifier in
- * `messages`, or undefined when none does.
- *
- * @param messages - Diagnostic messages reported for one file
- * @param companions - Candidates from {@link resolveUnmanagedCompanions}
- */
-export function explainUndefinedIdentifiers(messages, companions) {
-    const names = messages
-        .map((message) => extractUndefinedIdentifier(message))
-        .filter((name) => name !== undefined);
-    if (names.length === 0)
-        return undefined;
-    // Only the undefined-identifier diagnostics are explained here. A file
-    // carrying other type errors still gets those reported untouched.
-    return companions.find((companion) => names.every((name) => companion.declarations.has(name)));
-}
-/**
- * Reads the head files in the owned test set and resolves the unmanaged
- * companions they pull in with `loadSubScript`. Hoisting shared helpers
- * into such a companion leaves it unowned until export, and every use of
- * every helper then reports `Cannot find name` from an honest per-patch
- * program. See `patch-lint-unmanaged-companion.ts` for why the generic
- * hint is actively harmful there.
- *
- * Best-effort: an unreadable head simply contributes no companions.
- */
-export async function collectUnmanagedCompanions(repoDir, files, ownedFiles) {
-    const heads = [];
-    for (const file of files) {
-        const base = file.split('/').pop() ?? '';
-        if (!/^head(?:_.*)?\.js$/.test(base))
-            continue;
-        try {
-            heads.push({ file, source: await readFile(join(repoDir, file), 'utf8') });
-        }
-        catch {
-            continue;
-        }
-    }
-    if (heads.length === 0)
-        return [];
-    return resolveUnmanagedCompanions(heads, ownedFiles, async (rel) => {
-        try {
-            return await readFile(join(repoDir, rel), 'utf8');
-        }
-        catch {
-            return undefined;
-        }
-    });
-}
-/**
- * Swaps the generic undefined-identifier hint for the ownership hint when
- * one unmanaged companion explains every undefined name in the file. Any
- * other issue in the list is returned untouched.
- */
-export function retargetUnmanagedCompanionHints(issues, companions) {
-    if (companions.length === 0)
-        return [...issues];
-    const undefinedIssues = issues.filter((issue) => issue.message.includes(UNDEFINED_IDENTIFIER_HINT));
-    if (undefinedIssues.length === 0)
-        return [...issues];
-    const companion = explainUndefinedIdentifiers(undefinedIssues.map((issue) => issue.message), companions);
-    if (!companion)
-        return [...issues];
-    const hint = formatUnmanagedCompanionHint(companion);
-    return issues.map((issue) => issue.message.includes(UNDEFINED_IDENTIFIER_HINT)
-        ? { ...issue, message: issue.message.replace(UNDEFINED_IDENTIFIER_HINT, hint) }
-        : issue);
-}

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

@@ -1,206 +0,0 @@
-import type { PatchLintIssue } from '../types/commands/index.js';
-import type { FireForgeConfig, ProjectLicense } from '../types/config.js';
-import { type CommentStyle } from './license-headers.js';
-import { lintPatchedCss } from './patch-lint-css.js';
-import { type LintIgnoreChecks } from './patch-lint-ignore.js';
-import { type PatchSizeMeasurement } from './patch-lint-size.js';
-export * from './patch-lint-cross.js';
-export { buildModifiedFileAdditionsFromDiff, detectNewFilesInDiff } from './patch-lint-diff.js';
-export { lintPatchedCss };
-export { countNonBinaryDiffLines, getPatchSizeThresholds, isTestFile, lintPatchSize, measurePatchSize, type PatchSizeMeasurement, type PatchSizeTierDecision, resolvePatchSizeTier, } from './patch-lint-size.js';
-export type { PatchSizeThresholds } from './patch-lint-size-thresholds.js';
-/**
- * Canonical `[check] file: message` rendering of a patch-lint issue. It is
- * the one string shape every reporter and refusal message uses, so operators
- * can grep one format across lint output and refusal details.
- */
-export declare function formatPatchLintIssue(issue: Pick<PatchLintIssue, 'check' | 'file' | 'message'>): string;
-/**
- * The files the `file-too-large` rule measures for a patch: the JS files
- * (`.js`, `.mjs`, `.sys.mjs`, …) the patch creates. A modified file is
- * never measured, and neither is a new file of another kind (CSS, FTL,
- * markup), however long. This is the rule's own predicate, not a mirror
- * of it: the rule selects its files through the same function.
- *
- * @param patchText - Unified-diff body of one patch
- * @returns Engine-relative paths the rule would size-check
- */
-export declare function filesMeasuredByFileTooLarge(patchText: string): Set<string>;
-/** True when `strippedContent` contains at least one assertion call. */
-export declare function hasBrowserChromeAssertion(strippedContent: string): boolean;
-/**
- * Detects comment style from file extension for license header checks.
- */
-export declare function commentStyleForFile(file: string): CommentStyle | null;
-/**
- * Decides whether a new file's leading header satisfies the
- * `missing-license-header` rule. It is the single owner of the acceptance
- * policy: `lintNewFileHeaders` (the rule) and `autoFixLicenseHeaders` (the
- * interactive export fixer) must agree, or the fixer offers to stack a
- * second header onto a file the lint already accepts.
- *
- * Accepted shapes, in order:
- *  - the project's own header for the file's comment style.
- *  - under `browser/branding/`, any recognised license header in the
- *    matching style: the setup-generated branding directory is copied from
- *    Firefox's `unofficial` template and arrives with Mozilla MPL-2.0
- *    headers, legitimate for copyright purposes (the assets are Mozilla's)
- *    even when the fork's own code is 0BSD / EUPL-1.2 / GPL-2.0-or-later.
- *  - on an MPL-2.0 project, any recognised header in the matching style.
- *  - the verbatim upstream MPL-2.0 block header (`/* … *\/`, optionally
- *    behind a leading editor-directive comment) regardless of the project
- *    license, on any file whose comment syntax is the block form (JS and
- *    CSS): a file copied from the Firefox tree legitimately keeps Mozilla's
- *    header for provenance in an EUPL/GPL/0BSD project too. Only the block
- *    form is accepted, because the `// `-style MPL header is
- *    FireForge-generated rather than upstream provenance, and `hash`-style
- *    files (FTL) stay excluded
- *    because `/* … *\/` is not a comment there.
- *
- * @param file - Engine-relative path of the new file
- * @param content - File content
- * @param style - Comment style resolved for the file
- * @param license - The project license
- */
-export declare function isAcceptableNewFileHeader(file: string, content: string, style: CommentStyle, license: ProjectLicense): boolean;
-/**
- * Checks new files for required license headers (acceptance policy in
- * {@link isAcceptableNewFileHeader}).
- *
- * @param repoDir - Absolute path to the engine directory
- * @param newFiles - New file paths (relative to repoDir)
- * @param config - Project configuration
- * @returns Array of lint issues
- */
-export declare function lintNewFileHeaders(repoDir: string, newFiles: string[], config: FireForgeConfig): Promise<PatchLintIssue[]>;
-/** Optional ownership and diff context for {@link lintPatchedJs}. */
-export interface LintPatchedJsScope {
-    /** Patch-owned `.sys.mjs` paths for scoped JSDoc enforcement. */
-    patchOwnedFiles?: Set<string>;
-    /**
-     * Patch-owned chrome subscripts (`.js` non-`.sys.mjs`) for scoped
-     * chrome-script JSDoc enforcement. Built by
-     * {@link resolvePatchOwnedChromeScripts}. Kept apart from
-     * `patchOwnedFiles` so the `runCheckJs` consumer (which only accepts
-     * `.sys.mjs`) is not silently broadened.
-     */
-    patchOwnedChromeScripts?: Set<string>;
-    /**
-     * Unified diff of the patch. When given, `relative-import` judges a
-     * modified upstream file on the lines the patch adds only, so upstream's
-     * own relative imports do not count against it. A file the patch creates
-     * is judged whole either way.
-     */
-    diffContent?: string;
-}
-/**
- * Lints patched JS/MJS files for import conventions, file size, JSDoc, and
- * observer topic naming.
- *
- * @param repoDir - Absolute path to the engine directory
- * @param affectedFiles - File paths (relative to repoDir)
- * @param newFiles - Set of files that are newly created in this patch
- * @param config - Project configuration
- * @param scope - Optional ownership sets and patch diff; see {@link LintPatchedJsScope}
- * @returns Array of lint issues
- */
-export declare function lintPatchedJs(repoDir: string, affectedFiles: string[], newFiles: Set<string>, config: FireForgeConfig, scope?: LintPatchedJsScope): Promise<PatchLintIssue[]>;
-/**
- * Checks that modifications to existing (non-new) JS/MJS files include at
- * least one `// BINARYNAME:` comment in the added lines.
- *
- * @param diffContent - Raw unified diff string
- * @param config - Project configuration
- * @returns Array of lint issues
- */
-export declare function lintModificationComments(diffContent: string, config: FireForgeConfig): PatchLintIssue[];
-/**
- * Checks that modified (non-new) files with a supported extension still
- * start with a recognized license header.
- *
- * @param repoDir - Engine root directory
- * @param affectedFiles - All files affected by the patch
- * @param newFiles - Set of newly created files (excluded from this check)
- * @returns Warning-level lint issues for files missing any recognized header
- */
-export declare function lintModifiedFileHeaders(repoDir: string, affectedFiles: string[], newFiles: Set<string>): Promise<PatchLintIssue[]>;
-/**
- * Optional behaviour switches for {@link lintExportedPatch}.
- */
-export interface LintExportedPatchOptions {
-    /**
-     * Cross-patch context for ownership resolution. Present whenever the
-     * caller has a loaded patch queue. Absent for the ad-hoc single-diff
-     * paths that have no queue to resolve against.
-     */
-    patchQueueCtx?: import('./patch-lint-cross.js').PatchQueueContext;
-    /**
-     * Per-patch `check` IDs to drop from the returned issues. Threaded from
-     * `PatchMetadata.lintIgnore` so a patch that is advisory-noisy by nature
-     * (a cohesive branding bundle, auto-generated manifest, etc.) can opt out
-     * of a specific rule without reaching for the blunt `--skip-lint` hammer.
-     * Not mutated.
-     */
-    ignoreChecks?: LintIgnoreChecks;
-    /**
-     * Explicit tier override, threaded from `PatchMetadata.tier`. When
-     * `"branding"` forces the branding thresholds on the
-     * `large-patch-lines` rule. Callers with a per-patch manifest context
-     * (re-export, per-patch lint) should pass this. Aggregate-mode callers
-     * without a specific patch context omit it and fall through to
-     * auto-detection.
-     */
-    patchTier?: 'branding';
-    /**
-     * Skip the patch-size rules (`large-patch-files` / `large-patch-lines`).
-     * The ad-hoc `fireforge lint <files>` path passes a cross-patch file
-     * list that does not correspond to a single patch, so it suppresses the
-     * synthetic combined-list size check here and re-evaluates the size
-     * rules per owning patch instead, never synthesising a phantom
-     * oversized patch from the operator's file selection.
-     */
-    skipPatchSize?: boolean;
-    /**
-     * Restrict checkJs diagnostics to these repo-relative files. Module
-     * resolution still spans every owned file in `patchQueueCtx`. Export and
-     * re-export pass the patch under export so cross-patch `resource:///`
-     * imports resolve against the whole queue while only that patch's
-     * findings surface.
-     */
-    checkJsReportScope?: ReadonlySet<string>;
-    /**
-     * Pre-computed checkJs issues for this patch. When provided, the internal
-     * checkJs invocation is skipped and these are appended verbatim: the
-     * per-patch lint path builds one queue-wide checkJs program and
-     * attributes findings per patch instead of rebuilding per patch.
-     */
-    precomputedCheckJs?: readonly PatchLintIssue[];
-    /**
-     * Invoked with the issues dropped by the `ignoreChecks` waiver filter,
-     * when any were. Suppression semantics are unchanged (the returned issue
-     * list still excludes them), but the caller can report
-     * the measurement a waived size finding carried (per-patch NOTICE lines
-     * and the `--report` JSON) instead of losing it entirely.
-     */
-    onSuppressed?: (suppressed: PatchLintIssue[]) => void;
-    /**
-     * The patch's {@link measurePatchSize} result, when the caller already
-     * measured it for its own report or cache row. Absent, the size rules
-     * measure the diff themselves.
-     */
-    patchSizeMeasurement?: PatchSizeMeasurement;
-}
-/**
- * Runs all patch lint checks and returns combined issues.
- *
- * @param repoDir - Absolute path to the engine directory
- * @param affectedFiles - File paths (relative to repoDir) affected by the patch
- * @param diffContent - Raw unified diff string
- * @param config - Project configuration
- * @param options - Optional context and behaviour switches. See
- *   {@link LintExportedPatchOptions}. Every optional input lives here
- *   rather than in a positional tail: four of the five call sites had to
- *   pass `undefined` placeholders to reach the one member they wanted.
- * @returns Array of all lint issues found
- */
-export declare function lintExportedPatch(repoDir: string, affectedFiles: string[], diffContent: string, config: FireForgeConfig, options?: LintExportedPatchOptions): Promise<PatchLintIssue[]>;