@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/core/typecheck-explain.d.ts

@@ -1,93 +0,0 @@
-/**
- * `fireforge typecheck --explain <file>`: which of the two typecheck
- * programs see one file, and how, without checking anything.
- *
- * The project pass sees every root of a configured jsconfig project,
- * with that project's shim settings. A per-patch checkJs program sees much
- * less: a patch-created `.sys.mjs` module is checked in the queue-wide
- * module program, a patch-created test script in its own program with its
- * directory's patch-owned heads and the modules the queue creates up to
- * its patch, and nothing else is checked per patch at all. A URL import
- * that program cannot resolve types as `any` there. The explanation is
- * assembled from the same helpers the programs are built from, so it
- * cannot drift from them.
- */
-import type { FireForgeConfig, PatchLintSeverityGate, ProjectPaths, TypecheckConfig } from '../types/config.js';
-/** How one configured project relates to the file. */
-export interface ProjectExplanation {
-    /** The project's jsconfig path, as configured. */
-    project: string;
-    /**
-     * `root`: the jsconfig lists the file. `not-root`: it does not, so the
-     * project checks the file only when a root imports it. `skipped`: the
-     * project sets `checkJs: false`. `unreadable`: see `detail`.
-     */
-    membership: 'root' | 'not-root' | 'skipped' | 'unreadable';
-    /** Why the project could not be read. */
-    detail?: string;
-    /** `typecheck.litTypes`. */
-    litTypes: boolean;
-    /** The effective extra shim. */
-    extraShim?: string;
-    /** The `projectOverrides` key that applies to the project. */
-    overrideKey?: string;
-    /** `typecheck.undefinedIdentifiers`. */
-    undefinedIdentifiers: PatchLintSeverityGate;
-}
-/** One URL import and what the per-patch program resolves it to. */
-export interface ExplainedImport {
-    specifier: string;
-    /** `owned`: a module the program sees. `paths`: a reviewed mapping. */
-    resolution: 'owned' | 'paths' | 'any';
-    /** Engine-relative target, when resolved. */
-    target?: string;
-}
-/** How per-patch checkJs relates to the file. */
-export interface PerPatchExplanation {
-    /** `patchLint.checkJs`. */
-    enabled: boolean;
-    /** The file's path inside `engine/`, when it is there. */
-    engineFile?: string;
-    /** Patches that create the file, in queue order. */
-    creators: string[];
-    /** Patches that modify it without creating it, in queue order. */
-    modifiers: string[];
-    /**
-     * `module`: a root of the queue-wide `.sys.mjs` program. `test`: the root
-     * of its own test-script program. `none`: no per-patch program checks it.
-     */
-    program: 'module' | 'test' | 'none';
-    /** Why no per-patch program checks it. */
-    reason?: string;
-    /** For a `test`: the patch-owned heads its program loads beside it. */
-    heads: string[];
-    /** Modules the program resolves imports to (excluding the file). */
-    resolvable: string[];
-    /** The file's URL imports and how they resolve. */
-    imports: ExplainedImport[];
-    /** The consumer shim the program appends, if any. */
-    shim?: string;
-    litTypes: boolean;
-    strict: boolean;
-    undefinedIdentifiers: PatchLintSeverityGate;
-}
-/** The whole explanation. */
-export interface TypecheckExplanation {
-    /** The file, project-relative when inside the project. */
-    file: string;
-    /** False when the file does not exist. */
-    exists: boolean;
-    projects: ProjectExplanation[];
-    perPatch: PerPatchExplanation;
-}
-/**
- * Explains how `fireforge typecheck` sees one file. Read-only: nothing is
- * checked, generated or cached.
- *
- * @param paths - The project's paths
- * @param config - Loaded `fireforge.json`
- * @param typecheck - The typecheck block in force (`--project` applied), if any
- * @param file - The file, relative to the project root, relative to
- *   `engine/`, or absolute
- */
-export declare function explainTypecheckFile(paths: ProjectPaths, config: FireForgeConfig, typecheck: TypecheckConfig | undefined, file: string): Promise<TypecheckExplanation>;

package/dist/src/core/typecheck-explain.js

@@ -1,213 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * `fireforge typecheck --explain <file>`: which of the two typecheck
- * programs see one file, and how, without checking anything.
- *
- * The project pass sees every root of a configured jsconfig project,
- * with that project's shim settings. A per-patch checkJs program sees much
- * less: a patch-created `.sys.mjs` module is checked in the queue-wide
- * module program, a patch-created test script in its own program with its
- * directory's patch-owned heads and the modules the queue creates up to
- * its patch, and nothing else is checked per patch at all. A URL import
- * that program cannot resolve types as `any` there. The explanation is
- * assembled from the same helpers the programs are built from, so it
- * cannot drift from them.
- */
-import { readFile } from 'node:fs/promises';
-import { dirname, relative, resolve } from 'node:path';
-import { pathExists } from '../utils/fs.js';
-import { normalizePathSlashes } from '../utils/paths.js';
-import { buildPatchQueueContext, collectNewFileCreatorsByPath } from './patch-lint.js';
-import { createOwnedPathMatcher, pathsTargetCandidates } from './patch-lint-checkjs-resolve.js';
-import { isTestScriptFile, resolvableModulesForTests, resolvePatchOwnedSysMjs, resolvePatchOwnedTestScripts, } from './patch-lint-ownership.js';
-import { findProjectOverrideKey, resolveProjectExtraShim } from './typecheck.js';
-const HEAD_SCRIPT = /^head(?:_.*)?\.js$/;
-/** URL specifiers in static imports, `import()` calls and JSDoc `import("…")` types. */
-function findUrlImports(source) {
-    const found = new Set();
-    const patterns = [
-        /\bimport\s*\(\s*["'`]([^"'`]+)["'`]\s*\)/g,
-        /\bfrom\s*["']([^"']+)["']/g,
-        /^\s*import\s*["']([^"']+)["']/gm,
-    ];
-    for (const pattern of patterns) {
-        for (const match of source.matchAll(pattern)) {
-            const specifier = match[1];
-            if (specifier !== undefined && /^(?:resource|chrome):/.test(specifier)) {
-                found.add(specifier);
-            }
-        }
-    }
-    return [...found].sort();
-}
-async function explainProject(ts, projectRoot, cfg, project, absoluteFile) {
-    const extraShim = resolveProjectExtraShim(cfg, project, projectRoot);
-    const overrideKey = findProjectOverrideKey(cfg, project, projectRoot);
-    const base = {
-        project,
-        membership: 'unreadable',
-        litTypes: cfg.litTypes === true,
-        ...(extraShim !== undefined ? { extraShim } : {}),
-        ...(overrideKey !== undefined ? { overrideKey } : {}),
-        undefinedIdentifiers: cfg.undefinedIdentifiers ?? 'warning',
-    };
-    if (ts === undefined)
-        return { ...base, detail: 'the "typescript" package is not installed' };
-    const absConfig = resolve(projectRoot, project);
-    if (!(await pathExists(absConfig)))
-        return { ...base, detail: 'the jsconfig does not exist' };
-    const read = ts.readConfigFile(absConfig, (path) => ts.sys.readFile(path));
-    if (read.error) {
-        return { ...base, detail: ts.flattenDiagnosticMessageText(read.error.messageText, ' ') };
-    }
-    const raw = read.config;
-    if (raw?.compilerOptions?.['checkJs'] === false)
-        return { ...base, membership: 'skipped' };
-    const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, dirname(absConfig), undefined, absConfig);
-    const target = normalizePathSlashes(absoluteFile);
-    const isRoot = parsed.fileNames.some((name) => normalizePathSlashes(name) === target);
-    return { ...base, membership: isRoot ? 'root' : 'not-root' };
-}
-function noProgramReason(file, creators, modifiers, testFilesEnabled) {
-    if (creators.length === 0) {
-        return modifiers.length > 0
-            ? 'no patch creates it; per-patch checkJs checks only files a patch creates, so a ' +
-                'patch-modified upstream file is checked by the project pass alone'
-            : 'no patch creates or modifies it';
-    }
-    if (isTestScriptFile(file) && !testFilesEnabled) {
-        return 'patchLint.checkJsTestFiles is off, so test scripts are not checked per patch';
-    }
-    return ('per-patch checkJs roots only patch-created .sys.mjs modules and test scripts' +
-        (file.endsWith('.mjs')
-            ? '; this module is a resolution target for the test programs of its patch and later ones'
-            : ''));
-}
-async function explainImports(source, resolvable, engineDir, pathsMapping) {
-    const match = createOwnedPathMatcher(resolvable);
-    const imports = [];
-    for (const specifier of findUrlImports(source)) {
-        const owned = match(specifier);
-        if (owned !== undefined) {
-            imports.push({ specifier, resolution: 'owned', target: owned });
-            continue;
-        }
-        let viaPaths;
-        for (const target of pathsMapping ? pathsTargetCandidates(pathsMapping, specifier) : []) {
-            if (await pathExists(resolve(engineDir, target))) {
-                viaPaths = target;
-                break;
-            }
-        }
-        imports.push(viaPaths !== undefined
-            ? { specifier, resolution: 'paths', target: viaPaths }
-            : { specifier, resolution: 'any' });
-    }
-    return imports;
-}
-/** The files of `files` that exist under `engineDir`, sorted. */
-async function existing(engineDir, files) {
-    const kept = [];
-    for (const file of files) {
-        if (await pathExists(resolve(engineDir, file)))
-            kept.push(file);
-    }
-    return kept.sort();
-}
-async function explainPerPatch(paths, config, absoluteFile, ctx) {
-    const patchLint = config.patchLint ?? {};
-    const base = {
-        enabled: patchLint.checkJs === true,
-        creators: [],
-        modifiers: [],
-        program: 'none',
-        heads: [],
-        resolvable: [],
-        imports: [],
-        litTypes: patchLint.litTypes === true,
-        strict: patchLint.checkJsStrict === true,
-        undefinedIdentifiers: patchLint.undefinedIdentifiers ?? 'warning',
-    };
-    const rel = normalizePathSlashes(relative(paths.engine, absoluteFile));
-    if (rel.startsWith('..') || rel === '') {
-        return { ...base, reason: 'it is outside engine/, where every per-patch program lives' };
-    }
-    base.engineFile = rel;
-    if (!base.enabled)
-        return { ...base, reason: 'patchLint.checkJs is off' };
-    if (ctx === undefined)
-        return { ...base, reason: 'the project has no patch queue' };
-    const creators = collectNewFileCreatorsByPath(ctx).get(rel) ?? [];
-    const modifiers = ctx.entries
-        .filter((entry) => !creators.includes(entry.filename) && entry.modifiedFileAdditions.has(rel))
-        .map((entry) => entry.filename);
-    const known = { ...base, creators: [...creators], modifiers };
-    const testFilesEnabled = patchLint.checkJsTestFiles === true;
-    let program = 'none';
-    let heads = [];
-    let resolvable = [];
-    if (creators.length > 0 && rel.endsWith('.sys.mjs')) {
-        program = 'module';
-        resolvable = [...resolvePatchOwnedSysMjs(new Set(), ctx)].filter((f) => f !== rel);
-    }
-    else if (creators.length > 0 && testFilesEnabled && isTestScriptFile(rel)) {
-        program = 'test';
-        const dir = rel.slice(0, rel.lastIndexOf('/') + 1);
-        heads = [...resolvePatchOwnedTestScripts(new Set(), ctx)].filter((f) => f !== rel && f.startsWith(dir) && HEAD_SCRIPT.test(f.slice(f.lastIndexOf('/') + 1)));
-        resolvable = [...resolvableModulesForTests(ctx)(rel)];
-    }
-    if (program === 'none') {
-        return { ...known, reason: noProgramReason(rel, creators, modifiers, testFilesEnabled) };
-    }
-    const source = await readFile(absoluteFile, 'utf8').catch(() => '');
-    // What the program is built over: only files that exist are resolvable,
-    // and `paths` applies under `checkJsStrict`, as in the compiler host.
-    const programHeads = await existing(paths.engine, heads);
-    const programModules = await existing(paths.engine, resolvable);
-    const pathsMapping = patchLint.checkJsStrict === true ? patchLint.checkJsCompilerOptions?.paths : undefined;
-    const shim = program === 'test' ? patchLint.checkJsTestShim : patchLint.checkJsExtraShim;
-    return {
-        ...known,
-        program,
-        heads: programHeads,
-        resolvable: programModules,
-        imports: await explainImports(source, new Set([rel, ...programHeads, ...programModules]), paths.engine, pathsMapping),
-        ...(shim !== undefined ? { shim } : {}),
-    };
-}
-/**
- * Explains how `fireforge typecheck` sees one file. Read-only: nothing is
- * checked, generated or cached.
- *
- * @param paths - The project's paths
- * @param config - Loaded `fireforge.json`
- * @param typecheck - The typecheck block in force (`--project` applied), if any
- * @param file - The file, relative to the project root, relative to
- *   `engine/`, or absolute
- */
-export async function explainTypecheckFile(paths, config, typecheck, file) {
-    const fromRoot = resolve(paths.root, file);
-    const fromEngine = resolve(paths.engine, file);
-    const absoluteFile = !(await pathExists(fromRoot)) && (await pathExists(fromEngine)) ? fromEngine : fromRoot;
-    const display = normalizePathSlashes(relative(paths.root, absoluteFile));
-    let ts;
-    try {
-        ts = await import('typescript');
-    }
-    catch {
-        ts = undefined;
-    }
-    const projects = [];
-    for (const project of typecheck?.projects ?? []) {
-        projects.push(await explainProject(ts, paths.root, typecheck ?? { projects: [] }, project, absoluteFile));
-    }
-    const ctx = config.patchLint?.checkJs === true && (await pathExists(paths.patches))
-        ? await buildPatchQueueContext(paths.patches, config)
-        : undefined;
-    return {
-        file: display.startsWith('..') ? normalizePathSlashes(absoluteFile) : display,
-        exists: await pathExists(absoluteFile),
-        projects,
-        perPatch: await explainPerPatch(paths, config, absoluteFile, ctx),
-    };
-}

package/dist/src/core/typecheck-shim.d.ts

@@ -1,90 +0,0 @@
-/**
- * Shared TypeScript-checking constants used by both the patch-lint
- * `checkJs` pass (`patch-lint-checkjs.ts`) and the whole-project
- * `fireforge typecheck` command (`typecheck.ts`).
- *
- * Centralised so both flows agree on the same Firefox-globals shim
- * and the same set of suppressed diagnostic codes. Drift between the
- * two would mean a patch could lint clean under `fireforge lint` but
- * still fail `fireforge typecheck`, or vice versa, for reasons the
- * operator could not infer from the rule names.
- */
-/** Filename used for the synthetic Firefox-globals shim source file. */
-export declare const SHIM_FILENAME = "__fireforge_firefox_globals.d.ts";
-/**
- * Loose declarations for Firefox test-harness globals (mochitest
- * browser-chrome and xpcshell), appended after the composed
- * Firefox-globals + consumer shim when `patchLint.checkJsTestFiles`
- * extends the checkJs pass to patch-adopted test scripts.
- * These are `any`-typed, the same pragmatic posture as the main
- * shim. A consumer that wants typed harness members (so that, say, a call
- * to a method the harness does not declare fails at the patch boundary)
- * declares them in `patchLint.checkJsTestShim`. Because that shim
- * composes before this baseline and TypeScript resolves conflicting
- * `declare var` redeclarations to the first declaration, the typed
- * consumer declaration wins over the loose fallback here.
- */
-export declare const TEST_HARNESS_SHIM = "\n// \u2500\u2500 FireForge test-harness shim (loose baseline) \u2500\u2500\ndeclare var TestUtils: any;\ndeclare var BrowserTestUtils: any;\ndeclare var SpecialPowers: any;\ndeclare var EventUtils: any;\ndeclare var SimpleTest: any;\ndeclare var Assert: any;\ndeclare var gTestPath: string;\ndeclare var content: any;\ndeclare function add_task(task: (...args: any[]) => any): any;\ndeclare function add_setup(task: (...args: any[]) => any): any;\ndeclare function ok(condition: any, message?: string): void;\ndeclare function is(actual: any, expected: any, message?: string): void;\ndeclare function isnot(actual: any, expected: any, message?: string): void;\ndeclare function todo(condition: any, message?: string): void;\ndeclare function todo_is(actual: any, expected: any, message?: string): void;\ndeclare function todo_isnot(actual: any, expected: any, message?: string): void;\ndeclare function info(message: string): void;\ndeclare function registerCleanupFunction(callback: (...args: any[]) => any): void;\ndeclare function waitForExplicitFinish(): void;\ndeclare function finish(): void;\ndeclare function do_get_profile(): any;\ndeclare function run_test(): any;\n\n";
-/**
- * TS diagnostic codes suppressed by both the patch-lint checkJs pass
- * and the whole-project typecheck command. Each is a known false
- * positive that arises from checking Firefox JS outside Mozilla's own
- * build system: the resolver can't follow `resource://`/`chrome://`
- * URLs and the global shim is intentionally narrow.
- *
- * Widening this set should be deliberate and per-code: silently
- * suppressing more codes hides real type errors. The same set is used
- * by both flows so a patch can't pass one and fail the other for a
- * reason the operator couldn't infer from the docs.
- */
-export declare const SUPPRESSED_DIAGNOSTIC_CODES: ReadonlySet<number>;
-/**
- * Undefined-free-identifier codes, split out of
- * {@link SUPPRESSED_DIAGNOSTIC_CODES}. Suppressing them unconditionally lets
- * a module reference a name with no import or declaration anywhere and still
- * typecheck with 0 errors, so the failure surfaces as a runtime
- * `ReferenceError`. Both flows report these at a configurable severity
- * (default `'warning'`: visible without breaking gates, while genuine shim
- * gaps are silenced by adding the global to `extraShim`, or per-run via
- * `'off'`).
- */
-export declare const UNDEFINED_IDENTIFIER_CODES: ReadonlySet<number>;
-/** Hint appended to reported undefined-identifier diagnostics. */
-export declare const UNDEFINED_IDENTIFIER_HINT: string;
-/**
- * Result of {@link composeShimSource}: the source body to feed into
- * the TS host plus a flag indicating whether the user-supplied extra
- * shim was actually appended (used for verbose logging).
- */
-export interface ComposedShim {
-    source: string;
-    extraShimAppended: boolean;
-}
-/**
- * Composes the synthetic shim source by concatenating the built-in Firefox
- * globals shim with the contents of an optional user-supplied `.d.ts` file.
- * The user file is appended verbatim. The augment direction is intentional
- * (declarations later in concat order augment earlier ones), so a project
- * that wants to refine `Services` with a more specific type can do so in the
- * extra shim, and members can be added to the structured globals by merging
- * their interfaces (`interface ChromeUtilsShim { newMember(): any }`, see
- * the module doc comment). Any triple-slash `/// <reference path="…">`
- * directives inside the extra shim are inlined (resolved against the extra
- * shim's own directory) so they are not silently dropped at the synthetic
- * shim path.
- *
- * Missing extra-shim files raise a clear error rather than failing silently
- * with a confusing "type not found" downstream. This is the one
- * config-driven path where a user typo in `fireforge.json` produces a
- * runtime error, so it needs to be unmistakable.
- *
- * @param projectRoot - Absolute project root, used to resolve the relative
- *   shim path
- * @param extraShimPath - Optional project-relative path to an extra `.d.ts`
- * @param options - `litTypes` appends {@link LIT_TYPES_SHIM} after the
- *   built-in shim (before the extra shim, which can still merge into it),
- *   and {@link LOOSE_LIT_SHIM} otherwise
- */
-export declare function composeShimSource(projectRoot: string, extraShimPath: string | undefined, options?: {
-    litTypes?: boolean | undefined;
-}): Promise<ComposedShim>;