@hominis/fireforge 0.55.0 → 0.60.0

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

@@ -1,508 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * 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.
- */
-import { dirname, resolve } from 'node:path';
-import { pathExists, readText } from '../utils/fs.js';
-/** Filename used for the synthetic Firefox-globals shim source file. */
-export const SHIM_FILENAME = '__fireforge_firefox_globals.d.ts';
-/**
- * Minimal `.d.ts` shim for Firefox privileged-scope globals.
- *
- * Firefox source is plain JS, with no TypeScript allowed. The shim lets
- * TS-driven type checking run without reporting "cannot find name"
- * for the most common Mozilla APIs. Types are intentionally loose
- * (`any`) because full Firefox type coverage is out of scope.
- *
- * Structured globals (`ChromeUtils`, `Localization`) are declared via
- * named global interfaces (`ChromeUtilsShim`, `LocalizationShim`, …)
- * rather than closed object-literal types, so a project's extra shim
- * (`patchLint.checkJsExtraShim` / `typecheck.extraShim`) can add members
- * through TypeScript interface merging:
- *
- *   // my-extra-shim.d.ts
- *   interface ChromeUtilsShim {
- *     someNewApi(arg: string): unknown;
- *   }
- *
- * (A second `declare var ChromeUtils` in the extra shim remains a
- * duplicate-identifier error by design. Merge the interface instead.)
- * The member lists track upstream WebIDL additions per Firefox release
- * (`dom/chrome-webidl/ChromeUtils.webidl` for ChromeUtils). When a new
- * release adds a commonly-patched member, add a loose signature here.
- *
- * Notable patterns that require shimming:
- * - `const lazy = {};` + `ChromeUtils.defineESModuleGetters(lazy, { ... })`
- *   populates `lazy` at runtime, so we declare it as `Record<string, any>`.
- * - `Services.obs`, `Services.prefs`, etc. are XPCOM service accessors.
- * - `Ci`, `Cc`, `Cr`, `Cu` are XPCOM component shortcuts. `Cu` alone is
- *   typed (`CuShim`, the members of `nsIXPCComponents_Utils`), so an
- *   unknown `Cu.*` member is an error rather than a runtime TypeError.
- * - Browser chrome globals like `gBrowser`, `gURLBar` are common in
- *   content scripts wired via `browser.js`.
- * - Dynamic `import("resource:-…")` / `import("chrome:-…")` under patch
- *   checkJs: imports of *patch-owned* modules resolve to their real
- *   sources (see `patch-lint-checkjs.ts`). Everything else fails host
- *   resolution and lands on these URL ambient wildcards, keeping
- *   upstream Firefox imports pragmatically loose, same posture as globals.
- */
-const FIREFOX_GLOBALS_SHIM = `
-declare var Services: any;
-// Extensible via interface merging from a project extra shim; see the
-// module doc comment in typecheck-shim.ts.
-interface ChromeUtilsShim {
-  defineESModuleGetters(target: any, modules: Record<string, string>): void;
-  importESModule(specifier: string): any;
-  import(specifier: string): any;
-  registerWindowActor(name: string, options: Record<string, any>): void;
-  defineModuleGetter(target: any, name: string, specifier: string): void;
-  defineLazyGetter(target: any, name: string, getter: () => any): void;
-  generateQI(interfaces: any[]): Function;
-  getClassName(obj: any, unwrap?: boolean): string;
-  isClassInfo(obj: any): boolean;
-  // Firefox 153, dom/chrome-webidl/ChromeUtils.webidl: two overloads
-  // (URI string / nsIURI) with a PredictRemoteTypeOptions dictionary,
-  // collapsed into one loose signature per the shim's pragmatic posture.
-  predictRemoteTypeForURI(uri: string | object | null, options?: object): string | null;
-}
-declare var ChromeUtils: ChromeUtilsShim;
-// Components.utils (js/xpconnect/idl/xpccomponents.idl, nsIXPCComponents_Utils,
-// Firefox 153). Every member is listed with loose (any) jsval parameters and
-// results, so Xray-waived and cloned objects keep their expandos, but the
-// member set is closed: a call to a member Cu does not have (Cu.now() is
-// ChromeUtils.now()) is a typecheck error instead of a runtime TypeError.
-// Extensible via interface merging, same as ChromeUtilsShim.
-interface CuShim {
-  QueryInterface(iid: any): any;
-  printStderr(message: string): void;
-  reportError(error: any, stack?: any): void;
-  readonly Sandbox: { new (principal: any, options?: any): any; (principal: any, options?: any): any };
-  evalInSandbox(
-    source: string,
-    sandbox: any,
-    version?: any,
-    filename?: string,
-    lineNo?: number,
-    enforceFilenameRestrictions?: boolean
-  ): any;
-  getUAWidgetScope(principal: any): any;
-  getSandboxMetadata(sandbox: any): any;
-  setSandboxMetadata(sandbox: any, metadata: any): void;
-  setSandboxLocaleOverride(sandbox: any, locale: string): void;
-  setSandboxTimezoneOverride(sandbox: any, timezone: string): void;
-  isESModuleLoaded(resourceURI: string): boolean;
-  importGlobalProperties(propertyList: any): void;
-  getWeakReference(obj: any): { get(): any };
-  forceGC(): void;
-  forceCC(listener?: any): void;
-  createCCLogger(): any;
-  finishCC(): void;
-  ccSlice(budget: number): void;
-  getMaxCCSliceTimeSinceClear(): number;
-  clearMaxCCTime(): void;
-  forceShrinkingGC(): void;
-  schedulePreciseGC(callback: any): void;
-  schedulePreciseShrinkingGC(callback: any): void;
-  unlinkGhostWindows(): void;
-  intentionallyLeak(): void;
-  getJSTestingFunctions(): any;
-  getFunctionSourceLocation(func: any): any;
-  callFunctionWithAsyncStack(func: any, stack: any, asyncCause: string): any;
-  getGlobalForObject(obj: any): any;
-  isProxy(obj: any): boolean;
-  exportFunction(func: any, scope: any, options?: any): any;
-  createObjectIn(scope: any, options?: any): any;
-  makeObjectPropsNormal(obj: any): void;
-  isDeadWrapper(obj: any): boolean;
-  isRemoteProxy(val: any): boolean;
-  recomputeWrappers(obj?: any): void;
-  setWantXrays(scope: any): void;
-  dispatch(runnable: any, scope?: any): void;
-  readonly isInAutomation: boolean;
-  exitIfInAutomation(): void;
-  crashIfNotInAutomation(): void;
-  setGCZeal(zeal: number): void;
-  nukeSandbox(obj: any): void;
-  blockScriptForGlobal(global: any): void;
-  unblockScriptForGlobal(global: any): void;
-  isOpaqueWrapper(obj: any): boolean;
-  isXrayWrapper(obj: any): boolean;
-  waiveXrays(val: any): any;
-  unwaiveXrays(val: any): any;
-  getClassName(obj: any, unwrap: boolean): string;
-  getIncumbentGlobal(callback?: any): any;
-  getDebugName(obj: any): string;
-  getWatchdogTimestamp(category: string): number;
-  getJSEngineTelemetryValue(): any;
-  cloneInto(value: any, scope: any, options?: any): any;
-  getWebIDLCallerPrincipal(): any;
-  getObjectPrincipal(obj: any): any;
-  getRealmLocation(obj: any): string;
-  readUTF8File(file: any): string;
-  readUTF8URI(url: any): string;
-  createSpellChecker(): any;
-  createCommandLine(args: string[], workingDir: any, state: number): any;
-  createCommandParams(): any;
-  createLoadContext(): any;
-  createPrivateLoadContext(): any;
-  createPersistentProperties(): any;
-  createDocumentEncoder(contentType: string): any;
-  createHTMLCopyEncoder(): any;
-  readonly loadedESModules: string[];
-  getModuleImportStack(location: string): string;
-}
-declare var Cu: CuShim;
-declare var Ci: any;
-declare var Cc: any;
-declare var Cr: any;
-declare var Components: any;
-declare var XPCOMUtils: any;
-declare var lazy: Record<string, any>;
-declare var PathUtils: any;
-declare var IOUtils: any;
-declare var FileUtils: any;
-declare var gBrowser: any;
-declare var gURLBar: any;
-declare var gNavigatorBundle: any;
-declare var AppConstants: any;
-declare class JSWindowActorChild {
-  readonly browsingContext: any;
-  readonly contentWindow: any;
-  readonly document: any;
-  sendAsyncMessage(name: string, data?: any, transfers?: any[]): void;
-  sendQuery(name: string, data?: any, transfers?: any[]): Promise<any>;
-}
-declare class JSWindowActorParent {
-  readonly browsingContext: any;
-  sendAsyncMessage(name: string, data?: any, transfers?: any[]): void;
-  sendQuery(name: string, data?: any, transfers?: any[]): Promise<any>;
-}
-// Fluent localization, a stable chrome global. Members stay loose (any),
-// but the constructor shape is declared so "new Localization([...])" and
-// "new Localization([...], true)" typecheck without a local cast. Both
-// interfaces are extensible via interface merging from a project extra
-// shim, same as ChromeUtilsShim.
-interface LocalizationInstanceShim {
-  formatValue(id: string, args?: Record<string, unknown>): any;
-  formatValues(keys: any[]): any;
-  formatMessages(keys: any[]): any;
-  formatValueSync(id: string, args?: Record<string, unknown>): any;
-  formatValuesSync(keys: any[]): any;
-  formatMessagesSync(keys: any[]): any;
-  addResourceIds(ids: Array<string | { path: string; optional?: boolean }>): void;
-  removeResourceIds(ids: string[]): number;
-  setAsync(): void;
-}
-interface LocalizationShim {
-  new (
-    resourceIds: Array<string | { path: string; optional?: boolean }>,
-    sync?: boolean
-  ): LocalizationInstanceShim;
-}
-declare var Localization: LocalizationShim;
-
-// Shorthand ambient modules: exports from matching URL imports are loosely typed,
-// avoiding noResolve empty-graph namespaces. (Named member access broke when we tried
-// export= Record under moduleResolution Bundler.)
-declare module 'resource:*';
-declare module 'chrome:*';
-
-`;
-/**
- * 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 const TEST_HARNESS_SHIM = `
-// ── FireForge test-harness shim (loose baseline) ──
-declare var TestUtils: any;
-declare var BrowserTestUtils: any;
-declare var SpecialPowers: any;
-declare var EventUtils: any;
-declare var SimpleTest: any;
-declare var Assert: any;
-declare var gTestPath: string;
-declare var content: any;
-declare function add_task(task: (...args: any[]) => any): any;
-declare function add_setup(task: (...args: any[]) => any): any;
-declare function ok(condition: any, message?: string): void;
-declare function is(actual: any, expected: any, message?: string): void;
-declare function isnot(actual: any, expected: any, message?: string): void;
-declare function todo(condition: any, message?: string): void;
-declare function todo_is(actual: any, expected: any, message?: string): void;
-declare function todo_isnot(actual: any, expected: any, message?: string): void;
-declare function info(message: string): void;
-declare function registerCleanupFunction(callback: (...args: any[]) => any): void;
-declare function waitForExplicitFinish(): void;
-declare function finish(): void;
-declare function do_get_profile(): any;
-declare function run_test(): any;
-
-`;
-/**
- * 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 const SUPPRESSED_DIAGNOSTIC_CODES = new Set([
-    2307, // Cannot find module '{0}' or its corresponding type declarations.
-    2306, // File '{0}' is not a module.
-    2305, // Module '{0}' has no exported member '{1}'.
-    2792, // Cannot find module '{0}'. Did you mean to set the 'moduleResolution' option...
-    2580, // Cannot find name '{0}'. Do you need to install type definitions...
-    7016, // Could not find a declaration file for module '{0}'.
-]);
-/**
- * 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 const UNDEFINED_IDENTIFIER_CODES = new Set([
-    2304, // Cannot find name '{0}'.
-    2552, // Cannot find name '{0}'. Did you mean '{1}'?
-]);
-/**
- * Typed Lit, opt-in through `typecheck.litTypes` for the project pass and
- * `patchLint.litTypes` for the per-patch checkJs programs. Declares the two chrome
- * modules widgets import Lit from, so they do not fall to the
- * `chrome:*` wildcard as `any`: `LitElement` (with `ReactiveElement`'s
- * lifecycle) and `MozLitElement` carry closed member lists, so a misspelt
- * member of a widget host is TS2339, as `Cu` is in the built-in shim.
- * Template helpers and directives stay loose. The global
- * `MozLitElementWith<Extra>` types a widget's query getters and
- * `static properties` members: the widget casts its `MozLitElement` import
- * to it before extending ({@link LOOSE_LIT_SHIM} keeps it `any` without
- * typed Lit). A project
- * shim can merge members into `LitElementShimMembers`; a project whose
- * jsconfig `paths`
- * maps these URLs to the real sources gets those instead, since a resolved
- * file wins over an ambient module.
- */
-const LIT_TYPES_SHIM = `
-// ── FireForge typed Lit (litTypes) ──
-interface LitPropertyDeclarationShim {
-  type?: unknown;
-  attribute?: boolean | string;
-  reflect?: boolean;
-  state?: boolean;
-  noAccessor?: boolean;
-  converter?: unknown;
-  hasChanged?(value: unknown, oldValue: unknown): boolean;
-  fluent?: boolean;
-}
-interface LitElementShimMembers {
-  readonly renderRoot: HTMLElement | DocumentFragment;
-  readonly isUpdatePending: boolean;
-  readonly hasUpdated: boolean;
-  readonly updateComplete: Promise<boolean>;
-  renderOptions: any;
-  requestUpdate(name?: PropertyKey, oldValue?: unknown, options?: LitPropertyDeclarationShim): void;
-  addController(controller: any): void;
-  removeController(controller: any): void;
-  connectedCallback(): void;
-  disconnectedCallback(): void;
-  attributeChangedCallback(name: string, oldValue: string | null, value: string | null): void;
-  createRenderRoot(): HTMLElement | DocumentFragment;
-  enableUpdating(requestedUpdate: boolean): void;
-  scheduleUpdate(): void | Promise<unknown>;
-  performUpdate(): void;
-  getUpdateComplete(): Promise<boolean>;
-  shouldUpdate(changedProperties: Map<PropertyKey, unknown>): boolean;
-  willUpdate(changedProperties: Map<PropertyKey, unknown>): void;
-  update(changedProperties: Map<PropertyKey, unknown>): void;
-  render(): unknown;
-  firstUpdated(changedProperties: Map<PropertyKey, unknown>): void;
-  updated(changedProperties: Map<PropertyKey, unknown>): void;
-}
-declare module 'chrome://global/content/vendor/lit.all.mjs' {
-  export class ReactiveElement extends HTMLElement {
-    static properties: Record<string, LitPropertyDeclarationShim>;
-    static styles: any;
-    static shadowRootOptions: ShadowRootInit;
-    static readonly observedAttributes: string[];
-    static createProperty(name: PropertyKey, options?: LitPropertyDeclarationShim): void;
-    static addInitializer(initializer: (element: ReactiveElement) => void): void;
-  }
-  export interface ReactiveElement extends LitElementShimMembers {}
-  export class LitElement extends ReactiveElement {}
-  export const html: (strings: TemplateStringsArray, ...values: unknown[]) => any;
-  export const svg: (strings: TemplateStringsArray, ...values: unknown[]) => any;
-  export const css: (strings: TemplateStringsArray, ...values: unknown[]) => any;
-  export const nothing: any;
-  export const noChange: any;
-  export const render: any;
-  export const unsafeCSS: any;
-  export const classMap: any;
-  export const styleMap: any;
-  export const ifDefined: any;
-  export const repeat: any;
-  export const when: any;
-  export const map: any;
-  export const live: any;
-  export const ref: any;
-  export const createRef: any;
-  export const until: any;
-  export const guard: any;
-  export const choose: any;
-  export const keyed: any;
-  export const cache: any;
-  export const join: any;
-  export const range: any;
-  export const unsafeHTML: any;
-  export const unsafeSVG: any;
-  export const literal: any;
-  export const unsafeStatic: any;
-  export const staticHtml: any;
-  export const staticSvg: any;
-  export const directive: any;
-  export const Directive: any;
-  export const AsyncDirective: any;
-  export const PartType: any;
-  export const defaultConverter: any;
-  export const notEqual: any;
-  export const adoptStyles: any;
-  export const supportsAdoptingStyleSheets: boolean;
-  export const CSSResult: any;
-  export const isServer: boolean;
-}
-declare module 'chrome://global/content/lit-utils.mjs' {
-  import { LitElement } from 'chrome://global/content/vendor/lit.all.mjs';
-  export class MozLitElement extends LitElement {
-    static queries: Record<string, string | Record<string, unknown>>;
-    static fragment: unknown;
-    dispatchOnUpdateComplete(event: Event): Promise<void>;
-  }
-  export const MozBaseInputElement: any;
-  export const MozBoolInputElement: any;
-  export const SelectControlBaseElement: any;
-  export const SelectControlItemMixin: any;
-}
-// MozLitElement with instance members Extra: what a widget casts its base
-// to for the getters static queries installs (and properties it declares
-// only in static properties). A class field would redefine a query getter
-// and throw, and a constructor declaration reads it before renderRoot.
-type MozLitElementWith<Extra> = Pick<
-  typeof import('chrome://global/content/lit-utils.mjs').MozLitElement,
-  keyof typeof import('chrome://global/content/lit-utils.mjs').MozLitElement
-> &
-  (new () => import('chrome://global/content/lit-utils.mjs').MozLitElement & Extra);
-`;
-/**
- * Without typed Lit, `MozLitElementWith<Extra>` is `any`, as the base it
- * casts is: the same widget source checks in every program that leaves
- * `litTypes` off.
- */
-const LOOSE_LIT_SHIM = `
-// FireForge loose Lit (litTypes off): see typecheck-shim.ts.
-type MozLitElementWith<Extra> = any;
-`;
-/** Hint appended to reported undefined-identifier diagnostics. */
-export const UNDEFINED_IDENTIFIER_HINT = '(undefined identifier — import or declare it, add the global to the extra shim, ' +
-    'or tune the "undefinedIdentifiers" setting)';
-/** Matches a lone triple-slash `/// <reference path="…" />` directive line. */
-const TRIPLE_SLASH_REFERENCE = /^\s*\/\/\/\s*<reference\s+path\s*=\s*["']([^"']+)["']\s*\/?>\s*$/;
-/**
- * Inlines triple-slash `/// <reference path="…">` directives in shim source.
- *
- * Both shim consumers feed the text to the compiler at a *synthetic* path
- * (an in-memory source file, not the extra shim's real location), so TS
- * resolves a relative `/// <reference>` against that synthetic directory and
- * silently drops it. Inlining the referenced file's contents (recursively,
- * resolved against the *referencing* file's directory, deduped by absolute
- * path) makes the directives self-contained so their declarations survive.
- *
- * @param source - Shim source possibly containing reference directives
- * @param baseDir - Directory the directives' relative paths resolve against
- * @param seen - Absolute paths already inlined (cycle / duplicate guard)
- */
-async function inlineTripleSlashReferences(source, baseDir, seen) {
-    const out = [];
-    for (const line of source.split('\n')) {
-        const match = TRIPLE_SLASH_REFERENCE.exec(line);
-        if (!match?.[1]) {
-            out.push(line);
-            continue;
-        }
-        const absolute = resolve(baseDir, match[1]);
-        if (seen.has(absolute))
-            continue;
-        seen.add(absolute);
-        if (!(await pathExists(absolute))) {
-            out.push(`// (fireforge: unresolved /// <reference path="${match[1]}">)`);
-            continue;
-        }
-        const referenced = await readText(absolute);
-        out.push(await inlineTripleSlashReferences(referenced, dirname(absolute), seen));
-    }
-    return out.join('\n');
-}
-/**
- * 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 async function composeShimSource(projectRoot, extraShimPath, options = {}) {
-    const base = `${FIREFOX_GLOBALS_SHIM}\n${options.litTypes === true ? LIT_TYPES_SHIM : LOOSE_LIT_SHIM}`;
-    if (!extraShimPath) {
-        return { source: base, extraShimAppended: false };
-    }
-    const absoluteShim = resolve(projectRoot, extraShimPath);
-    if (!(await pathExists(absoluteShim))) {
-        throw new Error(`Extra TypeScript shim not found: ${extraShimPath} (resolved to ${absoluteShim}). ` +
-            'Check the path in fireforge.json or create the file.');
-    }
-    const extra = await readText(absoluteShim);
-    const inlinedExtra = await inlineTripleSlashReferences(extra, dirname(absoluteShim), new Set([absoluteShim]));
-    return {
-        source: `${base}\n// ── extraShim: ${extraShimPath} ──\n${inlinedExtra}`,
-        extraShimAppended: true,
-    };
-}

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

@@ -1,97 +0,0 @@
-/**
- * Whole-project TypeScript type checking driven by user-supplied
- * `jsconfig.json` paths. The engine behind the `fireforge typecheck`
- * command.
- *
- * Distinct from `patch-lint-checkjs.ts` (patch-hygiene): patchLint is
- * scoped, fireforge-controlled, and runs as part of `fireforge lint`.
- * This command runs whole projects with user-controlled compiler
- * options and is intended as a CI gate. The two share the Firefox
- * globals shim and suppressed-code list (via `typecheck-shim.ts`) so
- * a file that lints clean cannot fail typecheck for a reason the
- * operator could not have inferred from the docs.
- *
- * Loads the TypeScript compiler API via dynamic import so it is only
- * required when `typecheck.projects` is configured. TypeScript
- * remains a dev-dependency. If a user invokes `fireforge typecheck`
- * without installing it, the function returns a clear error pointing
- * at `npm install typescript`.
- */
-import type { TypecheckConfig } from '../types/config.js';
-import type { TypecheckProjectResult } from '../types/typecheck.js';
-/**
- * Sentinel string surfaced as a `TypecheckIssue.message` when the
- * project's jsconfig sets `checkJs: false`. Exported so tests can
- * pin the contract, since operators rely on it to spot opted-out projects
- * in CI logs.
- */
-export declare const CHECK_JS_DISABLED_NOTICE = "Project sets \"checkJs: false\" \u2014 skipping (override the jsconfig to enable typecheck).";
-/** Run-level options for {@link runTypecheck}. */
-export interface RunTypecheckOptions {
-    /**
-     * Directory for the per-project incremental build info. Defaults to
-     * `<projectRoot>/.fireforge/typecheck`.
-     */
-    cacheDir?: string;
-    /** Build every project from scratch and write no build info. */
-    noCache?: boolean;
-}
-/**
- * Runs `fireforge typecheck` against every project listed in `cfg.projects`.
- *
- * Per-project flow:
- *   1. Read the jsconfig via the TS API. JSON parse / config-spec
- *      errors are surfaced as issues rather than thrown, because a single
- *      broken project must not abort the rest of the run.
- *   2. Compute final compiler options from the user's options. We
- *      only force `noEmit: true` (this is a typecheck, not a build).
- *      We honour `strict`, `target`, `lib`, `module`, `paths`,
- *      `include`, `exclude`. `allowJs` and `checkJs` default to
- *      `true` only when the user has not set them. If the user set
- *      `checkJs: false` we treat that as an explicit opt-out and
- *      skip the project with a single notice (see {@link CHECK_JS_DISABLED_NOTICE}).
- *   3. Inject the synthetic shim (built-in + optional extraShim) as
- *      a virtual root file that the custom CompilerHost serves.
- *   4. Build the program and collect semantic, syntactic, options,
- *      and global diagnostics. The patchLint flow only reads semantic +
- *      syntactic, which is fine for hygiene, but a CI gate needs the full
- *      set so misconfigured `lib`/`paths` entries fail loudly.
- *   5. Drop diagnostics whose code is in `SUPPRESSED_DIAGNOSTIC_CODES`
- *      and any diagnostic originating in the synthetic shim itself.
- *
- * @param projectRoot - Absolute project root. All paths in `cfg` are resolved against it.
- * @param cfg - Validated `typecheck` block from `fireforge.json`.
- * @returns One {@link TypecheckProjectResult} per entry in `cfg.projects`,
- *   in declared order. The CLI is responsible for printing the issues
- *   and computing the exit code.
- */
-export declare function runTypecheck(projectRoot: string, cfg: TypecheckConfig, runOptions?: RunTypecheckOptions): Promise<TypecheckProjectResult[]>;
-/**
- * The `projectOverrides` key that names `projectPath`, matched by the path
- * it resolves to, so `./a/jsconfig.json` or an absolute path finds the
- * `a/jsconfig.json` entry. An exact key wins over another spelling of the
- * same file.
- *
- * @param cfg - The `typecheck` block
- * @param projectPath - A project path as configured or passed to `--project`
- * @param projectRoot - Absolute project root both paths resolve against
- * @returns The matching key, or undefined when no override names the project
- */
-export declare function findProjectOverrideKey(cfg: TypecheckConfig, projectPath: string, projectRoot: string): string | undefined;
-/**
- * Resolves the effective extra shim for a single project: a `projectOverrides`
- * entry wins (a string path overrides, `null` opts out → `undefined`), else
- * the shared top-level `extraShim` applies.
- *
- * @param cfg - The `typecheck` block
- * @param projectPath - The project's jsconfig path
- * @param projectRoot - Absolute project root, for matching override keys
- */
-export declare function resolveProjectExtraShim(cfg: TypecheckConfig, projectPath: string, projectRoot: string): string | undefined;
-/**
- * Converts an absolute path to a path relative to the project root,
- * for display in CLI output. Falls back to the absolute path when
- * the path lies outside the root (e.g. a `node_modules` symlinked
- * from elsewhere). Exposed for tests and the CLI.
- */
-export declare function relativeForDisplay(projectRoot: string, absoluteFile: string): string;