@hominis/fireforge 0.54.0 → 0.60.0

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

@@ -1,180 +0,0 @@
-/**
- * Optional TypeScript `checkJs` pass for patch-owned `.sys.mjs` files.
- *
- * Loads the TypeScript compiler API via dynamic import so it is only
- * required when `patchLint.checkJs` is enabled in `fireforge.json`.
- * TypeScript remains a dev-dependency. If a user enables checkJs
- * without installing it, the pass emits a clear error explaining
- * how to fix it.
- *
- * Separated from `patch-lint.ts` to keep both files within the
- * project's per-file line budget. The shim itself and the suppressed
- * diagnostic code list live in `typecheck-shim.ts` and are shared
- * with the whole-project `fireforge typecheck` command, keeping a
- * single source of truth for the Firefox-globals coverage.
- * `patchLint.checkJsStrict` only tightens `strict` / `noImplicitAny`
- * and optional allowlisted `checkJsCompilerOptions`. It does not change
- * shim composition or suppressed diagnostic codes.
- *
- * Resolution scope vs reporting scope: the TS program is built over a
- * *resolution* set (every patch-owned `.sys.mjs` the run cares about, so
- * cross-patch `resource:///` imports resolve to their real sources), while
- * diagnostics are emitted only for files in the *report* scope. Splitting
- * the two lets per-patch lint build one queue-wide program and attribute
- * findings per patch, and lets export/re-export resolve cross-patch imports
- * while reporting only the patch under export.
- */
-import type { PatchLintIssue } from '../types/commands/index.js';
-import type { PatchLintCheckJsCompilerOptions, PatchLintConfig, PatchLintSeverityGate } from '../types/config.js';
-import { type CheckJsSourceFileCache } from './patch-lint-checkjs-cache.js';
-/** How a checkJs run controls reporting and resolution. See module docs. */
-export interface CheckJsMode {
-    strict: boolean;
-    compilerOptions?: PatchLintCheckJsCompilerOptions;
-    /**
-     * How to report undefined free identifiers (TS2304/TS2552). Default
-     * 'warning'. See `patchLint.undefinedIdentifiers`.
-     */
-    undefinedIdentifiers?: PatchLintSeverityGate;
-}
-/**
- * Result of {@link runCheckJsGrouped}: diagnostics attributed to the
- * patch-owned file they originate in (`byFile`, keyed by repo-relative
- * path), plus run-level errors that have no owning file (`global`, e.g.
- * TypeScript missing or an unreadable extra shim).
- */
-export interface GroupedCheckJsResult {
-    byFile: Map<string, PatchLintIssue[]>;
-    global: PatchLintIssue[];
-}
-/** Inputs for {@link runCheckJsGrouped}. */
-export interface RunCheckJsGroupedInput {
-    /** Absolute engine (repository) directory. */
-    repoDir: string;
-    /**
-     * Patch-owned `.sys.mjs` paths (relative to `repoDir`) the program should
-     * see and resolve against.
-     */
-    resolutionOwned: Set<string>;
-    /**
-     * Optional project-relative extra `.d.ts` appended to the built-in
-     * Firefox-globals shim (from `patchLint.checkJsExtraShim`).
-     */
-    extraShimPath?: string;
-    /** Absolute project root for resolving `extraShimPath`. */
-    projectRoot?: string;
-    /** Strictness preset plus allowlisted compiler-option overrides. */
-    mode?: CheckJsMode;
-    /** Optional shim text appended after the consumer shim. */
-    builtinShimSuffix?: string;
-    /**
-     * When set, only these repo-relative files become program roots.
-     * Resolution (and the host allowlist) still spans all of
-     * `resolutionOwned`, so a subset root's cross-patch imports type-check
-     * against the real owning sources while unrelated owned files are never
-     * parsed. `.mjs` files are module-scoped, so a root's diagnostics are
-     * identical whether other owned files are roots or mere resolution
-     * targets.
-     */
-    rootScope?: ReadonlySet<string>;
-    /**
-     * Parsed source files shared across several programs built with the same
-     * compiler options and shim in one run. See {@link runCheckJsTestFilesGrouped}.
-     */
-    sourceFileCache?: CheckJsSourceFileCache;
-    /** When set, diagnostics are collected only for these repo-relative files. */
-    reportOnly?: ReadonlySet<string>;
-}
-/**
- * Builds the checkJs program once over `resolutionOwned` and returns its
- * diagnostics grouped by originating file. Callers slice the result by their
- * own report scope: per-patch lint attributes each file to its owning patch,
- * export/re-export keeps only the patch under export. Resolution always spans
- * every file in `resolutionOwned`, so cross-patch `resource:///`/`chrome://`
- * imports resolve to real sources.
- *
- * @param input - Program inputs. See {@link RunCheckJsGroupedInput}
- * @returns Diagnostics grouped per owning file plus run-level errors
- */
-export declare function runCheckJsGrouped(input: RunCheckJsGroupedInput): Promise<GroupedCheckJsResult>;
-/**
- * Flattens a {@link runCheckJsGrouped} run into a single issue list. When
- * `reportScope` is supplied, only diagnostics from files in that set are
- * returned (resolution still spans every owned file). Omitting it reports
- * every owned file's diagnostics, the historical whole-set behaviour.
- *
- * @param repoDir - Absolute engine (repository) directory
- * @param patchOwnedFiles - Patch-owned `.sys.mjs` paths to resolve against
- * @param extraShimPath - Optional project-relative extra `.d.ts`
- * @param projectRoot - Absolute project root for resolving `extraShimPath`
- * @param mode - Strictness preset plus allowlisted compiler-option overrides
- * @param reportScope - When set, restrict reported diagnostics to these
- *   repo-relative files
- * @returns Array of lint issues from TS diagnostics
- */
-export declare function runCheckJs(repoDir: string, patchOwnedFiles: Set<string>, extraShimPath?: string, projectRoot?: string, mode?: CheckJsMode, reportScope?: ReadonlySet<string>): Promise<PatchLintIssue[]>;
-/**
- * Invokes {@link runCheckJs} for a `patchLint` block with `checkJs: true`.
- * `projectRoot` is the FireForge project root (`dirname(engine)`).
- *
- * @param repoDir - Absolute engine (repository) directory
- * @param patchOwnedFiles - Patch-owned `.sys.mjs` paths to resolve against
- * @param patchLint - The resolved `patchLint` config block
- * @param projectRoot - FireForge project root for shim resolution
- * @param reportScope - Optional repo-relative files to report on (export /
- *   re-export passes the patch under export so cross-patch resolution does
- *   not surface other patches' diagnostics)
- */
-export declare function invokePatchLintCheckJs(repoDir: string, patchOwnedFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string, reportScope?: ReadonlySet<string>): Promise<PatchLintIssue[]>;
-/**
- * Runs the checkJs pass over patch-owned test `.js` files (
- * `patchLint.checkJsTestFiles`). Each test file gets its own small
- * program, with roots = the test file plus any same-directory patch-owned
- * `head*.js`, checked against the built-in Firefox shim +
- * {@link TEST_HARNESS_SHIM} + the optional consumer `checkJsTestShim`.
- * Mochitest scripts share top-level scope only with their directory's
- * `head*.js` helpers, so one multi-script program would emit false
- * cross-file redeclaration errors. Only the target file's diagnostics are
- * reported per program (head helpers report from their own program), and
- * run-level errors are de-duplicated across programs.
- *
- * With `resolvableModules`, a test's `resource:///` and `chrome://`
- * imports also resolve to the modules it returns for that test (the
- * modules the queue creates up to the test's own patch), so a test that
- * imports an earlier patch's module is typed against its real source
- * instead of the shim's `any` wildcard. Those modules are resolution
- * targets only: never roots, and never reported on.
- *
- * @param repoDir - Absolute engine (repository) directory
- * @param testFiles - Patch-owned test-script paths (repo-relative)
- * @param patchLint - The resolved `patchLint` config block
- * @param projectRoot - FireForge project root for shim resolution
- */
-export declare function runCheckJsTestFilesGrouped(repoDir: string, testFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string, rootScope?: ReadonlySet<string>, resolvableModules?: (testFile: string) => ReadonlySet<string>): Promise<GroupedCheckJsResult>;
-/**
- * Grouped variant of {@link invokePatchLintCheckJs}: builds one queue-wide
- * checkJs program over `patchOwnedFiles` and returns its findings grouped by
- * owning file. The per-patch lint orchestrator calls this once per run
- * and attributes each file's findings to its owning patch, instead of
- * rebuilding the same program for every patch in the queue.
- *
- * @param repoDir - Absolute engine (repository) directory
- * @param patchOwnedFiles - Every patch-owned `.sys.mjs` in the queue
- * @param patchLint - The resolved `patchLint` config block
- * @param projectRoot - FireForge project root for shim resolution
- * @param rootScope - Optional subset of files to use as program roots
- * (`--patches`). Resolution still spans the whole queue
- */
-export declare function invokePatchLintCheckJsGrouped(repoDir: string, patchOwnedFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string, rootScope?: ReadonlySet<string>): Promise<GroupedCheckJsResult>;
-/**
- * Cheap probe reproducing the only run-level ("global") checkJs findings the
- * build path can produce: a missing `typescript` package and an unreadable
- * consumer shim (`checkJsExtraShim`, and `checkJsTestShim` when
- * `checkJsTestFiles` is on). The built program itself never contributes
- * globals (see {@link runCheckJsGrouped}), so a warm all-cache-hit run can
- * satisfy the "warm never reports less than cold" invariant with this probe
- * instead of building the whole TypeScript program. Issue objects are
- * byte-identical to the build path's, deduplicated by message like
- * {@link runCheckJsTestFilesGrouped}.
- */
-export declare function probeCheckJsGlobalIssues(patchLint: PatchLintConfig, projectRoot: string): Promise<PatchLintIssue[]>;