@hominis/fireforge 0.18.10 → 0.19.0

package/dist/src/core/typecheck.js

@@ -0,0 +1,302 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * 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 { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { pathExists } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
+import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES } from './typecheck-shim.js';
+/**
+ * Sentinel string surfaced as a `TypecheckIssue.message` when the
+ * project's jsconfig sets `checkJs: false`. Exported so tests can
+ * pin the contract — operators rely on it to spot opted-out projects
+ * in CI logs.
+ */
+export const CHECK_JS_DISABLED_NOTICE = 'Project sets "checkJs: false" — skipping (override the jsconfig to enable typecheck).';
+/**
+ * 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, not thrown — 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; collect semantic, syntactic, options, and
+ *      global diagnostics. The patchLint flow only reads semantic +
+ *      syntactic — 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 async function runTypecheck(projectRoot, cfg) {
+    // Dynamic import — typescript stays a dev dependency. Same pattern
+    // as `patch-lint-checkjs.ts`; the empty-projects-array case is
+    // already rejected by config-validate, so we don't gate the import
+    // on `cfg.projects.length`.
+    let ts;
+    try {
+        ts = await import('typescript');
+    }
+    catch {
+        return cfg.projects.map((project) => ({
+            project,
+            issues: [
+                {
+                    file: '(typecheck)',
+                    line: 1,
+                    column: 1,
+                    code: 0,
+                    category: 'error',
+                    message: 'fireforge typecheck requires the "typescript" package. Run "npm install typescript" to enable type checking.',
+                    project,
+                },
+            ],
+            filesChecked: 0,
+        }));
+    }
+    // Compose the shim once — extraShim is shared across all projects.
+    // A missing or unreadable shim is a project-wide failure, so we
+    // surface it as one issue per project rather than letting one
+    // project's read failure silently affect the others' results.
+    let shimSource;
+    try {
+        const composed = await composeShimSource(projectRoot, cfg.extraShim);
+        shimSource = composed.source;
+        if (composed.extraShimAppended) {
+            verbose(`typecheck: extra shim ${cfg.extraShim ?? ''} appended to Firefox globals shim`);
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return cfg.projects.map((project) => ({
+            project,
+            issues: [
+                {
+                    file: cfg.extraShim ?? '(typecheck)',
+                    line: 1,
+                    column: 1,
+                    code: 0,
+                    category: 'error',
+                    message,
+                    project,
+                },
+            ],
+            filesChecked: 0,
+        }));
+    }
+    const results = [];
+    for (const projectPath of cfg.projects) {
+        results.push(await runTypecheckForProject(ts, projectRoot, projectPath, shimSource));
+    }
+    return results;
+}
+/** Runs typecheck for a single jsconfig path, isolating its failures. */
+async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource) {
+    const absConfig = resolve(projectRoot, projectPath);
+    if (!(await pathExists(absConfig))) {
+        return {
+            project: projectPath,
+            issues: [
+                {
+                    file: projectPath,
+                    line: 1,
+                    column: 1,
+                    code: 0,
+                    category: 'error',
+                    message: `jsconfig.json not found: ${projectPath} (resolved to ${absConfig})`,
+                    project: projectPath,
+                },
+            ],
+            filesChecked: 0,
+        };
+    }
+    // 1) Read the JSON config. ts.readConfigFile reports JSON-shape
+    // errors via the returned diagnostic; missing files fall back to
+    // pathExists above, which gives a more directly actionable message.
+    const readResult = ts.readConfigFile(absConfig, (path) => ts.sys.readFile(path));
+    if (readResult.error) {
+        return {
+            project: projectPath,
+            issues: [diagnosticToIssue(ts, readResult.error, projectPath, projectPath)],
+            filesChecked: 0,
+        };
+    }
+    // 2) Parse the config content. This is what surfaces config-spec
+    // errors (unknown options, mismatched types in `compilerOptions`,
+    // bad `include` patterns, etc.) — TS5xxx codes. We surface them
+    // alongside semantic diagnostics so the operator sees the same
+    // output `tsc -p` would have produced.
+    const parsed = ts.parseJsonConfigFileContent(readResult.config, ts.sys, dirname(absConfig), 
+    /* existingOptions */ undefined, absConfig);
+    const issues = [];
+    for (const diag of parsed.errors) {
+        if (SUPPRESSED_DIAGNOSTIC_CODES.has(diag.code))
+            continue;
+        issues.push(diagnosticToIssue(ts, diag, absConfig, projectPath));
+    }
+    // 3) Honour explicit `checkJs: false`. The user has opted out for
+    // an IDE reason (likely "checkJs floods my workflow with non-actionable
+    // notes"); flipping it on here would surface ~hundreds of issues that
+    // the operator already evaluated and rejected. Surface a single
+    // notice so it is visible in CI logs rather than silently passing.
+    const rawConfig = readResult.config;
+    if (rawConfig?.compilerOptions?.['checkJs'] === false) {
+        issues.push({
+            file: projectPath,
+            line: 1,
+            column: 1,
+            code: 0,
+            category: 'warning',
+            message: CHECK_JS_DISABLED_NOTICE,
+            project: projectPath,
+        });
+        return { project: projectPath, issues, filesChecked: parsed.fileNames.length };
+    }
+    // 4) Compute final compiler options. `noEmit: true` is forced — we
+    // never write artifacts. `allowJs` / `checkJs` default to true
+    // *only* when unset (so a user can flip them off without us
+    // overriding); if the user set `allowJs: false` they're saying
+    // "don't even include JS in this typecheck", which is rare but
+    // legitimate (e.g. an isolated `.d.ts`-only project).
+    const options = {
+        ...parsed.options,
+        noEmit: true,
+        allowJs: parsed.options.allowJs ?? true,
+        checkJs: parsed.options.checkJs ?? true,
+        // skipLibCheck is not forced; the user owns it via their jsconfig.
+    };
+    // 5) The synthetic shim file. Use a project-rooted path with a
+    // hidden-style prefix so it is unlikely to collide with any real
+    // file — and never write it to disk. The CompilerHost below serves
+    // it from `shimSource` for `fileExists`/`readFile`/`getSourceFile`.
+    const projectDir = dirname(absConfig);
+    const shimPath = resolve(projectDir, `.fireforge-${SHIM_FILENAME}`);
+    const rootFiles = [...parsed.fileNames, shimPath];
+    const defaultHost = ts.createCompilerHost(options);
+    const host = {
+        ...defaultHost,
+        getSourceFile(fileName, languageVersion, onError, shouldCreate) {
+            if (fileName === shimPath) {
+                return ts.createSourceFile(fileName, shimSource, languageVersion, true);
+            }
+            return defaultHost.getSourceFile(fileName, languageVersion, onError, shouldCreate);
+        },
+        fileExists(fileName) {
+            if (fileName === shimPath)
+                return true;
+            return defaultHost.fileExists(fileName);
+        },
+        readFile(fileName) {
+            if (fileName === shimPath)
+                return shimSource;
+            return defaultHost.readFile(fileName);
+        },
+    };
+    const program = ts.createProgram(rootFiles, options, host);
+    // Collect the full diagnostic set. patchLint reads only semantic +
+    // syntactic — fine for hygiene, wrong for CI: a misconfigured
+    // `lib: ["es2015"]` or a missing `paths` target should fail
+    // typecheck loudly via getOptionsDiagnostics / getGlobalDiagnostics.
+    const allDiagnostics = [
+        ...program.getOptionsDiagnostics(),
+        ...program.getGlobalDiagnostics(),
+        ...program.getSyntacticDiagnostics(),
+        ...program.getSemanticDiagnostics(),
+    ];
+    for (const diag of allDiagnostics) {
+        if (SUPPRESSED_DIAGNOSTIC_CODES.has(diag.code))
+            continue;
+        // Drop diagnostics that originate in the synthetic shim — operators
+        // can't act on them and they would clutter CI logs.
+        if (diag.file?.fileName === shimPath)
+            continue;
+        issues.push(diagnosticToIssue(ts, diag, absConfig, projectPath));
+    }
+    verbose(`typecheck: ${projectPath} — analyzed ${String(parsed.fileNames.length)} file(s), found ${String(issues.length)} issue(s)`);
+    return {
+        project: projectPath,
+        issues,
+        filesChecked: parsed.fileNames.length,
+    };
+}
+/**
+ * Converts a TS Diagnostic to a TypecheckIssue. The `fallbackFile`
+ * is used when the diagnostic carries no source file (typical for
+ * options diagnostics) — typically the absolute jsconfig path or
+ * the project-relative form for surface-level errors. `project` is
+ * threaded through so the CLI can group issues by project without
+ * a second pass.
+ */
+function diagnosticToIssue(ts, diag, fallbackFile, project) {
+    let file = fallbackFile;
+    let line = 1;
+    let column = 1;
+    if (diag.file) {
+        file = diag.file.fileName;
+        if (typeof diag.start === 'number') {
+            const lc = diag.file.getLineAndCharacterOfPosition(diag.start);
+            line = lc.line + 1;
+            column = lc.character + 1;
+        }
+    }
+    const message = typeof diag.messageText === 'string'
+        ? diag.messageText
+        : ts.flattenDiagnosticMessageText(diag.messageText, '\n');
+    // Suggestion + Message categories collapse to 'warning'; only
+    // Error stays an error. This matches what the CLI then displays.
+    const category = diag.category === ts.DiagnosticCategory.Error ? 'error' : 'warning';
+    return {
+        file,
+        line,
+        column,
+        code: diag.code,
+        category,
+        message,
+        project,
+    };
+}
+/**
+ * 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 function relativeForDisplay(projectRoot, absoluteFile) {
+    if (!isAbsolute(absoluteFile))
+        return absoluteFile;
+    const rel = relative(projectRoot, absoluteFile);
+    if (rel === '' || rel.startsWith('..'))
+        return absoluteFile;
+    return rel;
+}
+//# sourceMappingURL=typecheck.js.map

package/dist/src/core/xpcshell-appdir.d.ts

@@ -8,8 +8,8 @@
  * The upstream xpcshell harness computes the manifest key for the appdir
  * override as `mozInfo["appname"] + "-appdir"`. On a stock Firefox build the
  * key is `firefox-appdir`, so the very common `firefox-appdir = "browser"`
- * directive is honoured. On a rebranded fork (appname=`hominis`,
- * `mybrowser`, …) the harness looks for `hominis-appdir` / `mybrowser-appdir`
+ * directive is honoured. On a rebranded fork (appname=`mybrowser`, …) the
+ * harness looks for `mybrowser-appdir`
  * — the literal `firefox-appdir` line is silently ignored, `appPath` falls
  * back to `xrePath`, and every `resource:///modules/…` import throws
  * `Failed to load resource:///modules/<name>.sys.mjs` because xpcshell now

package/dist/src/core/xpcshell-appdir.js

@@ -9,8 +9,8 @@
  * The upstream xpcshell harness computes the manifest key for the appdir
  * override as `mozInfo["appname"] + "-appdir"`. On a stock Firefox build the
  * key is `firefox-appdir`, so the very common `firefox-appdir = "browser"`
- * directive is honoured. On a rebranded fork (appname=`hominis`,
- * `mybrowser`, …) the harness looks for `hominis-appdir` / `mybrowser-appdir`
+ * directive is honoured. On a rebranded fork (appname=`mybrowser`, …) the
+ * harness looks for `mybrowser-appdir`
  * — the literal `firefox-appdir` line is silently ignored, `appPath` falls
  * back to `xrePath`, and every `resource:///modules/…` import throws
  * `Failed to load resource:///modules/<name>.sys.mjs` because xpcshell now

package/dist/src/types/commands/options.d.ts

@@ -440,7 +440,7 @@ export interface FurnaceCreateOptions {
     compose?: string[];
     /**
      * Participate in a pre-existing feature-scoped Fluent bundle at this
-     * path (as used by `insertFTLIfNeeded`, e.g. `browser/hominis-dock.ftl`)
+     * path (as used by `insertFTLIfNeeded`, e.g. `browser/mybrowser-dock.ftl`)
      * instead of scaffolding a per-component `.ftl`. Implies `localized`.
      * Persists onto the furnace.json entry so validation and apply skip the
      * per-component paths.

package/dist/src/types/config.d.ts

@@ -44,6 +44,8 @@ export interface FireForgeConfig {
     wire?: WireConfig;
     /** Patch lint configuration */
     patchLint?: PatchLintConfig;
+    /** Typecheck command configuration (CI-grade, whole-project) */
+    typecheck?: TypecheckConfig;
     /**
      * Project marker prefix appended to lines FireForge writes into
      * upstream Firefox source files (e.g. the `customElements.js` tag list).
@@ -52,6 +54,29 @@ export interface FireForgeConfig {
      */
     markerComment?: string;
 }
+/**
+ * Configuration for the `fireforge typecheck` command. Distinct from
+ * `patchLint.checkJs`: patch-lint runs every time `fireforge lint` runs
+ * and is scoped to patch-owned `.sys.mjs`; typecheck runs whole projects
+ * the operator points at via `projects` and is intended as a CI gate.
+ */
+export interface TypecheckConfig {
+    /**
+     * Project-relative paths to jsconfig.json (or tsconfig.json) files
+     * the typecheck command should run. Must be non-empty when the
+     * `typecheck` block is present — an empty array would silently turn
+     * the command into a no-op.
+     */
+    projects: string[];
+    /**
+     * Optional project-relative path to an additional `.d.ts` file whose
+     * contents are concatenated to the built-in `FIREFOX_GLOBALS_SHIM`.
+     * Lets projects declare component patterns like `MozLitElement` /
+     * `MozXULElement` once instead of per-file. Concat order is
+     * built-in shim first, extraShim second — augment, don't redeclare.
+     */
+    extraShim?: string;
+}
 /**
  * Wire command configuration.
  */
@@ -64,12 +89,48 @@ export interface WireConfig {
  * `'warning'` and `'error'` emit issues at the matching severity.
  */
 export type PatchLintSeverityGate = 'off' | 'warning' | 'error';
+/**
+ * Allowlisted TypeScript `compilerOptions` overrides for the patch
+ * `checkJs` pass when {@link PatchLintConfig.checkJsStrict} is true.
+ * Merged after the strict preset; only boolean flags — no `paths`,
+ * `rootDir`, or other options that would fight the synthetic program.
+ */
+export interface PatchLintCheckJsCompilerOptions {
+    strictNullChecks?: boolean;
+    strictFunctionTypes?: boolean;
+    strictBindCallApply?: boolean;
+    noImplicitThis?: boolean;
+    useUnknownInCatchVariables?: boolean;
+    strictPropertyInitialization?: boolean;
+    noUnusedLocals?: boolean;
+    noUnusedParameters?: boolean;
+}
 /**
  * Configuration for patch lint rules.
  */
 export interface PatchLintConfig {
     /** Enable TypeScript checkJs pass on patch-owned .sys.mjs files */
     checkJs?: boolean;
+    /**
+     * When true with `checkJs: true`, run checkJs with `strict` and
+     * `noImplicitAny` enabled (CI-style). Default false preserves the
+     * historical loose preset. Optional {@link checkJsCompilerOptions}
+     * can relax individual strict flags (e.g. `strictNullChecks: false`).
+     */
+    checkJsStrict?: boolean;
+    /**
+     * Boolean overrides merged after the strict preset; only valid when
+     * `checkJsStrict` is true. Requires `checkJs: true`.
+     */
+    checkJsCompilerOptions?: PatchLintCheckJsCompilerOptions;
+    /**
+     * Project-relative path to an additional `.d.ts` file whose contents
+     * are concatenated to the built-in `FIREFOX_GLOBALS_SHIM` for the
+     * `patchLint.checkJs` pass. Same semantics as `typecheck.extraShim`
+     * but scoped to the patch-hygiene flow. Default unset = current
+     * behaviour (built-in shim only).
+     */
+    checkJsExtraShim?: string;
     /** File paths exempt from the raw-color-value check (exact or basename match) */
     rawColorAllowlist?: string[];
     /** Enforce JSDoc on class-method exports in patch-owned .sys.mjs files. Default: 'off'. */

package/dist/src/types/furnace.d.ts

@@ -70,7 +70,7 @@ export interface CustomComponentConfig {
     /**
      * Path of a pre-existing feature-scoped Fluent bundle this component
      * participates in, in the same form used by `insertFTLIfNeeded` (for
-     * example `browser/hominis-dock.ftl`). When set:
+     * example `browser/mybrowser-dock.ftl`). When set:
      *
      *   - `furnace create --localized` does NOT scaffold a per-component
      *     `.ftl` stub — the component shares the feature bundle.

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

@@ -0,0 +1,51 @@
+/**
+ * Types for the `fireforge typecheck` command.
+ *
+ * Kept separate from `PatchLintIssue` because the two flows model
+ * different things: patch-lint issues are keyed on a stable `check`
+ * rule ID (consumed by `lintIgnore`, severity gates, and the
+ * cross-patch tagger), while typecheck issues carry a raw TypeScript
+ * diagnostic code that should never enter the patch-lint vocabulary.
+ * Conflating them would let `lintIgnore` accidentally suppress TS
+ * errors and would force `PatchLintIssue` to grow line / column /
+ * code fields that have no meaning for patch-hygiene rules.
+ */
+/**
+ * A single diagnostic produced by `runTypecheck` for one source file.
+ */
+export interface TypecheckIssue {
+    /** Absolute path to the source file the diagnostic originated in. */
+    file: string;
+    /** 1-based line number. */
+    line: number;
+    /** 1-based column number. */
+    column: number;
+    /** Raw TypeScript diagnostic code (e.g. 2322 for a type mismatch). */
+    code: number;
+    /**
+     * Severity bucket — TS reports `Suggestion` and `Message` categories
+     * too, but `runTypecheck` collapses both into `'warning'` so the CLI
+     * has only two visible levels.
+     */
+    category: 'error' | 'warning';
+    /** Human-readable message text (already flattened from chains). */
+    message: string;
+    /**
+     * Project-relative path of the originating jsconfig.json. Useful
+     * when typecheck.projects names multiple projects and the operator
+     * needs to know which one fired.
+     */
+    project: string;
+}
+/**
+ * Per-project typecheck output. One entry per `typecheck.projects`
+ * jsconfig path, in the order the projects were declared.
+ */
+export interface TypecheckProjectResult {
+    /** Project-relative path of the jsconfig.json. */
+    project: string;
+    /** All issues from this project (errors + warnings). */
+    issues: TypecheckIssue[];
+    /** How many root files the program was built against (excludes the synthetic shim). */
+    filesChecked: number;
+}

package/dist/src/types/typecheck.js

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Types for the `fireforge typecheck` command.
+ *
+ * Kept separate from `PatchLintIssue` because the two flows model
+ * different things: patch-lint issues are keyed on a stable `check`
+ * rule ID (consumed by `lintIgnore`, severity gates, and the
+ * cross-patch tagger), while typecheck issues carry a raw TypeScript
+ * diagnostic code that should never enter the patch-lint vocabulary.
+ * Conflating them would let `lintIgnore` accidentally suppress TS
+ * errors and would force `PatchLintIssue` to grow line / column /
+ * code fields that have no meaning for patch-hygiene rules.
+ */
+export {};
+//# sourceMappingURL=typecheck.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.18.10",
+  "version": "0.19.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",