@hominis/fireforge 0.19.0 → 0.19.2

package/CHANGELOG.md

@@ -5,6 +5,11 @@
 ### Features
 
 - **`patchLint.checkJsStrict` and `patchLint.checkJsCompilerOptions`.** The patch-lint `checkJs` pass now defaults to the historical loose preset (`strict: false`, `noImplicitAny: false`). Set `"patchLint": { "checkJs": true, "checkJsStrict": true }` to enforce `strict` and `noImplicitAny` on patch-owned `.sys.mjs` so implicit-any parameters surface as `checkjs-type-error`, aligning with strict whole-project checkJs without changing module resolution (`noResolve` and `resource://` suppression unchanged). Optional `checkJsCompilerOptions` (requires `checkJsStrict`) merges allowlisted boolean compiler overrides — for example `{ "strictNullChecks": false }` — after the strict preset for gradual adoption. The Firefox globals shim and `SUPPRESSED_DIAGNOSTIC_CODES` remain shared with `fireforge typecheck` via `typecheck-shim.ts`.
+- **`checkJs` — ambient modules for Firefox URL imports.** The shared shim in `typecheck-shim.ts` now includes shorthand `declare module 'resource:*'` and `declare module 'chrome:*'`, matching typical `resource://…` / `chrome://…` specifiers without the broken `Record` + `export=` shape under `moduleResolution` Bundler (which typed dynamic imports as `{ default: … }` and broke `.namedExport` access). Bulk `fireforge re-export` with `patchLint.checkJs` no longer routinely needs `--skip-lint` for `.sys.mjs` queues that lazily URL-import storage and infra helpers.
+
+### Hardening
+
+- **`modified-file-missing-header` — standard Mozilla MPL-2.0 block headers with wrapped line breaks.** The upstream fallback scan required a contiguous `Mozilla Public License` substring in the first few lines, so files that follow Mozilla’s usual `/* … Mozilla Public` / ` * License, v. 2.0 … */` wrap (including after Emacs/vim directive blocks) were warned despite a valid notice. `containsUpstreamLicenseText` in `src/core/license-headers.ts` now normalizes common block-comment continuation prefixes before matching, so forks need not add SPDX solely to satisfy patch lint.
 
 ## 0.18.0
 

package/README.md

@@ -230,32 +230,32 @@ If the manifest drifts after an interrupted export or manual edits, `fireforge i
 
 By default, a standalone `fireforge lint` (no arguments) lints the **aggregate** `git diff HEAD` — i.e. every applied patch summed — with tool-managed branding paths (`browser/branding/<binaryName>/`) excluded. A fresh-setup workspace carries a large generated branding diff that operators did not author directly, and letting it through tripped the patch-size and license-header rules on content that matches the `branding` bucket in `fireforge status`. When the exclusion fires the command prints a one-line note naming the excluded count so the filter is visible. On a repo where `fireforge import` or `fireforge rebase` has just applied the full queue, the patch-size rules (`large-patch-lines`, `large-patch-files`) fire against the sum, which reads as "my queue is broken" when it is really an artefact of aggregation. Use `fireforge lint --per-patch` to rescope the diff to each patch's own `filesAffected`, honouring the patch's own `lintIgnore`. Cross-patch rules (`duplicate-new-file-creation`, `forward-import`) still run once over the whole queue either way. Pass explicit file paths to narrow the scope further — explicit-path mode does lint branding files (the operator's explicit request wins over the branding exclusion); the three modes (aggregate, file-scoped, per-patch) are mutually exclusive.
 
-| Check                                | Scope                                                                                            | Severity                 |
-| ------------------------------------ | ------------------------------------------------------------------------------------------------ | ------------------------ |
-| `missing-license-header`             | New files (JS/CSS/FTL)                                                                           | error                    |
-| `relative-import`                    | JS/MJS files                                                                                     | error                    |
-| `token-prefix-violation`             | CSS files (with furnace)                                                                         | error                    |
-| `raw-color-value`                    | Introduced CSS color values (allowlist via `patchLint.rawColorAllowlist`)                        | error                    |
-| `duplicate-new-file-creation`        | Same path created by multiple patches                                                            | error                    |
-| `forward-import`                     | Patch imports from a later-patch file                                                            | error                    |
-| `missing-jsdoc`                      | Exports in patch-owned `.sys.mjs`                                                                | error                    |
-| `jsdoc-param-mismatch`               | Exports in patch-owned `.sys.mjs`                                                                | error                    |
-| `jsdoc-missing-returns`              | Exports in patch-owned `.sys.mjs`                                                                | error                    |
-| `checkjs-type-error`                 | Patch-owned `.sys.mjs` (opt-in `patchLint.checkJs`)                                              | error                    |
-| `missing-jsdoc-class-method`         | Class-method exports in patch-owned `.sys.mjs` (opt-in)                                          | configurable             |
-| `jsdoc-class-method-param-mismatch`  | Class-method exports in patch-owned `.sys.mjs` (opt-in)                                          | configurable             |
-| `jsdoc-class-method-missing-returns` | Class-method exports in patch-owned `.sys.mjs` (opt-in)                                          | configurable             |
-| `test-needs-assertion`               | Patch-introduced `browser_*.js` test files (opt-in)                                              | configurable             |
-| `missing-modification-comment`       | Modified upstream JS/MJS                                                                         | warning                  |
-| `modified-file-missing-header`       | Modified upstream files (JS/CSS/FTL)                                                             | warning                  |
-| `file-too-large`                     | New files (tiered: 500/750/900 general, 1200/1400/1600 test)                                     | notice / warning / error |
-| `observer-topic-naming`              | Observer topics with binaryName                                                                  | warning                  |
-| `large-patch-files`                  | Patches affecting many files (tiered: >5 general, >5 test, >60 branding)                         | warning                  |
-| `large-patch-lines`                  | Patch line count (tiered: 800/1500/3000 general, 1500/3000/6000 test, 8000/18000/30000 branding) | notice / warning / error |
+| Check                                | Scope                                                                                                   | Severity                 |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------- | ------------------------ |
+| `missing-license-header`             | New files (JS/CSS/FTL)                                                                                  | error                    |
+| `relative-import`                    | JS/MJS files                                                                                            | error                    |
+| `token-prefix-violation`             | CSS files (with furnace)                                                                                | error                    |
+| `raw-color-value`                    | Introduced CSS color values (allowlist via `patchLint.rawColorAllowlist`)                               | error                    |
+| `duplicate-new-file-creation`        | Same path created by multiple patches                                                                   | error                    |
+| `forward-import`                     | Patch imports from a later-patch file                                                                   | error                    |
+| `missing-jsdoc`                      | Exports in patch-owned `.sys.mjs`                                                                       | error                    |
+| `jsdoc-param-mismatch`               | Exports in patch-owned `.sys.mjs`                                                                       | error                    |
+| `jsdoc-missing-returns`              | Exports in patch-owned `.sys.mjs`                                                                       | error                    |
+| `checkjs-type-error`                 | Patch-owned `.sys.mjs` (opt-in `patchLint.checkJs`)                                                     | error                    |
+| `missing-jsdoc-class-method`         | Class-method exports in patch-owned `.sys.mjs` (opt-in)                                                 | configurable             |
+| `jsdoc-class-method-param-mismatch`  | Class-method exports in patch-owned `.sys.mjs` (opt-in)                                                 | configurable             |
+| `jsdoc-class-method-missing-returns` | Class-method exports in patch-owned `.sys.mjs` (opt-in)                                                 | configurable             |
+| `test-needs-assertion`               | Patch-introduced `browser_*.js` test files (opt-in)                                                     | configurable             |
+| `missing-modification-comment`       | Modified upstream JS/MJS                                                                                | warning                  |
+| `modified-file-missing-header`       | Modified upstream files (JS/CSS/FTL); Mozilla MPL-2.0 `/* */` headers with wrapped lines are recognized | warning                  |
+| `file-too-large`                     | New files (tiered: 500/750/900 general, 1200/1400/1600 test)                                            | notice / warning / error |
+| `observer-topic-naming`              | Observer topics with binaryName                                                                         | warning                  |
+| `large-patch-files`                  | Patches affecting many files (tiered: >5 general, >5 test, >60 branding)                                | warning                  |
+| `large-patch-lines`                  | Patch line count (tiered: 800/1500/3000 general, 1500/3000/6000 test, 8000/18000/30000 branding)        | notice / warning / error |
 
 **JSDoc validation** uses AST-based analysis (Acorn) to validate exported APIs in patch-owned `.sys.mjs` files. A file is "patch-owned" if it was newly created by the current diff or by an existing patch in the queue. Functions must document every `@param` (names must match) and include `@returns` when the function returns a value. Exported constants and classes require a JSDoc block.
 
-**Optional `checkJs` pass.** Enable a TypeScript-esque bastardization of type checking for patch-owned `.sys.mjs` files by adding `"patchLint": { "checkJs": true }` to `fireforge.json`. This uses the TypeScript compiler API with `allowJs + checkJs + noEmit`, scoped only to patch-owned files. Firefox globals (`Services`, `ChromeUtils`, `lazy`, etc.) are shimmed automatically. Module-resolution errors from Firefox's `resource://` and `chrome://` URL schemes are suppressed since TypeScript cannot follow these. By default the pass uses a **loose** compiler preset (`strict: false`, `noImplicitAny: false`) so implicit `any` from untyped parameters does not flood the output. Set `"patchLint": { "checkJsStrict": true }` (requires `checkJs: true`) to enable `strict` and `noImplicitAny` for parity with strict whole-project checkJs — implicit-any parameters then surface as `checkjs-type-error`. Optional `"patchLint": { "checkJsCompilerOptions": { "strictNullChecks": false } }` (requires `checkJsStrict: true`) merges **allowlisted boolean** strict flags after that preset so forks can tighten `noImplicitAny` while relaxing e.g. null checks. The same built-in shim and the same eight suppressed diagnostic codes as `fireforge typecheck` apply; only explicit strictness differs. Projects that need to extend the built-in shim (e.g. for `MozLitElement`, `MozXULElement`, or fork-specific component bases) can point at an additional `.d.ts` via `"patchLint": { "checkJsExtraShim": "tools/types/<fork>-globals.d.ts" }`; the file is concatenated to the built-in shim — augment, don't redeclare.
+**Optional `checkJs` pass.** Enable a TypeScript-esque bastardization of type checking for patch-owned `.sys.mjs` files by adding `"patchLint": { "checkJs": true }` to `fireforge.json`. This uses the TypeScript compiler API with `allowJs + checkJs + noEmit`, scoped only to patch-owned files. Firefox globals (`Services`, `ChromeUtils`, `lazy`, etc.) are shimmed automatically. Module-resolution errors from Firefox's `resource://` and `chrome://` URL schemes are suppressed since TypeScript cannot follow these; the built-in shim also declares ambient `resource:*` and `chrome:*` modules so lazy `import("resource:-…")` / `import("chrome:-…")` stay loosely typed under `noResolve` instead of degrading into spurious `checkjs-type-error` cascades — refine further with `"patchLint": { "checkJsExtraShim": "..." }`. By default the pass uses a **loose** compiler preset (`strict: false`, `noImplicitAny: false`) so implicit `any` from untyped parameters does not flood the output. Set `"patchLint": { "checkJsStrict": true }` (requires `checkJs: true`) to enable `strict` and `noImplicitAny` for parity with strict whole-project checkJs — implicit-any parameters then surface as `checkjs-type-error`. Optional `"patchLint": { "checkJsCompilerOptions": { "strictNullChecks": false } }` (requires `checkJsStrict: true`) merges **allowlisted boolean** strict flags after that preset so forks can tighten `noImplicitAny` while relaxing e.g. null checks. The same built-in shim and the same eight suppressed diagnostic codes as `fireforge typecheck` apply; only explicit strictness differs. Projects that need to extend the built-in shim (e.g. for `MozLitElement`, `MozXULElement`, or fork-specific component bases) can point at an additional `.d.ts` via `"patchLint": { "checkJsExtraShim": "tools/types/<fork>-globals.d.ts" }`; the file is concatenated to the built-in shim — augment, don't redeclare.
 
 **Whole-project type checking — `fireforge typecheck`.** `patchLint.checkJs` is patch-hygiene: scoped to patch-owned `.sys.mjs`, suppresses module-resolution noise, and runs every time `fireforge lint` runs. With `checkJsStrict`, that pass can match a strict jsconfig's `noImplicitAny` behaviour without replacing full-project resolution. `fireforge typecheck` remains the CI-grade complement: it runs whole projects you point at via `typecheck.projects` in `fireforge.json`, honours each jsconfig's strictness/include/exclude/`paths`, and is intended as a CI gate. The two are complementary; the recommended setup is `fireforge lint` on every patch export and `fireforge typecheck` on CI for the project-level baseline.
 

package/dist/src/core/license-headers.js

@@ -129,6 +129,16 @@ export function hasAnyLicenseHeaderAnyStyle(content) {
     const styles = ['js', 'css', 'hash'];
     return styles.some((style) => hasAnyLicenseHeader(content, style));
 }
+/**
+ * Collapses block-comment continuation lines (`\n` + ` * ` prefixes) so
+ * substring markers like `Mozilla Public License` match Mozilla's wrapped
+ * MPL boilerplate.
+ */
+function normalizeLicenseHeadForScan(head) {
+    let s = head.replace(/\r\n?/g, '\n');
+    s = s.replace(/\n[ \t]*\*[ \t]*/g, ' ');
+    return s.replace(/\s+/g, ' ').trim();
+}
 /**
  * Returns true if the first few lines of `content` contain a recognized
  * upstream license identifier string.
@@ -138,6 +148,7 @@ export function hasAnyLicenseHeaderAnyStyle(content) {
  */
 export function containsUpstreamLicenseText(content, maxLines = 10) {
     const head = content.split('\n').slice(0, maxLines).join('\n');
+    const scanText = normalizeLicenseHeadForScan(head);
     const markers = [
         'Mozilla Public License',
         'SPDX-License-Identifier',
@@ -145,7 +156,7 @@ export function containsUpstreamLicenseText(content, maxLines = 10) {
         'MIT License',
         'GNU General Public License',
     ];
-    return markers.some((marker) => head.includes(marker));
+    return markers.some((marker) => scanText.includes(marker));
 }
 /**
  * Prepends the license header to a file on disk if it is not already present.

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

@@ -26,8 +26,12 @@ export declare const SHIM_FILENAME = "__fireforge_firefox_globals.d.ts";
  * - `Ci`, `Cc`, `Cr`, `Cu` are XPCOM component shortcuts.
  * - Browser chrome globals like `gBrowser`, `gURLBar` are common in
  *   content scripts wired via `browser.js`.
+ * - Dynamic `import("resource:-…")` / `import("chrome:-…")` under patch
+ *   checkJs: the compiler sees empty stubs (`noResolve`); without URL
+ *   ambient modules namespaces degrade to unusable typings. Wildcards
+ *   keep Firefox URL imports pragmatically loose, same posture as globals.
  */
-export declare const FIREFOX_GLOBALS_SHIM = "\ndeclare var Services: any;\ndeclare var ChromeUtils: {\n  defineESModuleGetters(target: any, modules: Record<string, string>): void;\n  importESModule(specifier: string): any;\n  import(specifier: string): any;\n  defineModuleGetter(target: any, name: string, specifier: string): void;\n  generateQI(interfaces: any[]): Function;\n  isClassInfo(obj: any): boolean;\n};\ndeclare var Cu: any;\ndeclare var Ci: any;\ndeclare var Cc: any;\ndeclare var Cr: any;\ndeclare var Components: any;\ndeclare var XPCOMUtils: any;\ndeclare var lazy: Record<string, any>;\ndeclare var PathUtils: any;\ndeclare var IOUtils: any;\ndeclare var FileUtils: any;\ndeclare var gBrowser: any;\ndeclare var gURLBar: any;\ndeclare var gNavigatorBundle: any;\ndeclare var AppConstants: any;\n";
+export declare const FIREFOX_GLOBALS_SHIM = "\ndeclare var Services: any;\ndeclare var ChromeUtils: {\n  defineESModuleGetters(target: any, modules: Record<string, string>): void;\n  importESModule(specifier: string): any;\n  import(specifier: string): any;\n  defineModuleGetter(target: any, name: string, specifier: string): void;\n  generateQI(interfaces: any[]): Function;\n  isClassInfo(obj: any): boolean;\n};\ndeclare var Cu: any;\ndeclare var Ci: any;\ndeclare var Cc: any;\ndeclare var Cr: any;\ndeclare var Components: any;\ndeclare var XPCOMUtils: any;\ndeclare var lazy: Record<string, any>;\ndeclare var PathUtils: any;\ndeclare var IOUtils: any;\ndeclare var FileUtils: any;\ndeclare var gBrowser: any;\ndeclare var gURLBar: any;\ndeclare var gNavigatorBundle: any;\ndeclare var AppConstants: any;\n\n// Shorthand ambient modules \u2014 exports from matching URL imports are loosely typed,\n// avoiding noResolve empty-graph namespaces. (Named member access broke when we tried\n// export= Record under moduleResolution Bundler.)\ndeclare module 'resource:*';\ndeclare module 'chrome:*';\n\n";
 /**
  * TS diagnostic codes suppressed by both the patch-lint checkJs pass
  * and the whole-project typecheck command. Each is a known false

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

@@ -29,6 +29,10 @@ export const SHIM_FILENAME = '__fireforge_firefox_globals.d.ts';
  * - `Ci`, `Cc`, `Cr`, `Cu` are XPCOM component shortcuts.
  * - Browser chrome globals like `gBrowser`, `gURLBar` are common in
  *   content scripts wired via `browser.js`.
+ * - Dynamic `import("resource:-…")` / `import("chrome:-…")` under patch
+ *   checkJs: the compiler sees empty stubs (`noResolve`); without URL
+ *   ambient modules namespaces degrade to unusable typings. Wildcards
+ *   keep Firefox URL imports pragmatically loose, same posture as globals.
  */
 export const FIREFOX_GLOBALS_SHIM = `
 declare var Services: any;
@@ -54,6 +58,13 @@ declare var gBrowser: any;
 declare var gURLBar: any;
 declare var gNavigatorBundle: any;
 declare var AppConstants: any;
+
+// 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:*';
+
 `;
 /**
  * TS diagnostic codes suppressed by both the patch-lint checkJs pass

package/package.json

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