feat(eslint): exempt .d.ts from no-var/vars-on-top (ambient globalThis typing) — 0.1.1

Ambient `declare var X` is the only construct that augments `typeof globalThis`
(const/let don't merge; an interface Window augmentation types window.X not
globalThis.X, which unicorn/prefer-global-this steers toward). no-var/vars-on-top
therefore only ever false-positive on .d.ts; a new declarationFileOverrides() block
(appended last in every preset, before consumer overrides) turns them off for **/*.d.ts.

Consuming projects (e.g. fluxo) can drop their local .d.ts override. Tests 11/11,
self-lint + format clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: a-tokyo

README.md

@@ -29,7 +29,7 @@ Sonar issues before they reach CI. Five stack presets — **plain JS/TS**, **Rea
 Distributed via GitHub URL, pinned to a tag (no build step runs on install — raw ESM):
 
 ```bash
-npm i -D "github:zoldytech/javascript#v0.1.0"
+npm i -D "github:zoldytech/javascript#0.1.1"
 ```
 
 ## Usage

docs/react-native.md

@@ -49,6 +49,7 @@ with no extra ESLint config:
   **Native-only** projects (no web target) can drop the DOM lib to catch
   accidental DOM usage on native, by overriding `lib` in their own tsconfig:
   `"compilerOptions": { "lib": ["ES2022"] }`.
+
 - The bundler alias (`react-native$` → `react-native-web`) is a build-tool concern
   (webpack/Metro/Vite), out of scope for this package.
 
@@ -63,11 +64,11 @@ which this package requires (peer `eslint >=10.4`).
 
 **Verified against ESLint 10.7 (2026-07):**
 
-| Rule | Status on ESLint 10 |
-| --- | --- |
+| Rule                                                                       | Status on ESLint 10                                               |
+| -------------------------------------------------------------------------- | ----------------------------------------------------------------- |
 | `no-unused-styles`, `no-inline-styles`, `no-color-literals`, `sort-styles` | **crash** — call `context.getSourceCode()` (removed in ESLint 10) |
-| `split-platform-components` | **crash** — calls `context.getFilename()` (removed in ESLint 10) |
-| `no-raw-text`, `no-single-element-style-arrays` | load but are the least useful rules |
+| `split-platform-components`                                                | **crash** — calls `context.getFilename()` (removed in ESLint 10)  |
+| `no-raw-text`, `no-single-element-style-arrays`                            | load but are the least useful rules                               |
 
 `eslint-plugin-react-native@5.0.0` is the latest release and declares peer
 `eslint ^3 … ^9`. `@react-native/eslint-plugin` ships no style rules
@@ -114,6 +115,7 @@ When `eslint-plugin-react-native` publishes an ESLint-10-compatible release (dro
    ```
 
    (Omit `sort-styles` — pure ordering, Prettier's domain.)
+
 3. Add a `dirty.tsx` case to `test/fixtures/react-native/` that trips a couple of
    the style rules and extend the `presetSuite('react-native', …)` expected-rules
    list in `test/presets.test.js` accordingly.

eslint/_shared.js

@@ -140,3 +140,23 @@ export function sonarTestOff(testGlobs = DEFAULT_TEST_GLOBS) {
 export function antfuTypescript({ typeChecked = false, tsconfigPath = 'tsconfig.json' } = {}) {
   return typeChecked ? { tsconfigPath } : true;
 }
+
+/**
+ * Declaration-file (.d.ts) overrides. A `.d.ts` can only carry ambient `declare var` for
+ * `globalThis` augmentation — TypeScript does NOT merge `const`/`let` into `typeof globalThis`,
+ * and an `interface Window` augmentation types `window.X`, not `globalThis.X` (which
+ * unicorn/prefer-global-this steers code toward). So `no-var`/`vars-on-top` can only ever
+ * false-positive on ambient declarations; turn them off for `.d.ts`. Appended last in each
+ * preset so it wins over antfu/sonar, before the consumer's own `overrides`.
+ * @returns {import('eslint').Linter.Config} the `.d.ts` override block (no-var/vars-on-top off).
+ */
+export function declarationFileOverrides() {
+  return {
+    name: 'zoldytech/declaration-files',
+    files: ['**/*.d.ts'],
+    rules: {
+      'no-var': 'off',
+      'vars-on-top': 'off',
+    },
+  };
+}

eslint/base.js

@@ -4,7 +4,7 @@
 
 import antfu from '@antfu/eslint-config';
 import prettier from 'eslint-config-prettier/flat';
-import { antfuTypescript, sonarLayer, sonarTestOff } from './_shared.js';
+import { antfuTypescript, declarationFileOverrides, sonarLayer, sonarTestOff } from './_shared.js';
 
 /**
  * @typedef {object} BaseOptions
@@ -47,6 +47,7 @@ export function base(options = {}) {
     ...sonarLayer({ tsdoc }),
     sonarTestOff(testGlobs),
     prettier,
+    declarationFileOverrides(),
     ...overrides
   );
 }

eslint/nest.js

@@ -4,7 +4,13 @@
 
 import antfu from '@antfu/eslint-config';
 import prettier from 'eslint-config-prettier/flat';
-import { antfuTypescript, sonarLayer, sonarTestOff, TS_GLOBS } from './_shared.js';
+import {
+  antfuTypescript,
+  declarationFileOverrides,
+  sonarLayer,
+  sonarTestOff,
+  TS_GLOBS,
+} from './_shared.js';
 
 /**
  * @typedef {object} NestOptions
@@ -69,6 +75,7 @@ export function nest(options = {}) {
     ...nestRules,
     sonarTestOff(testGlobs),
     prettier,
+    declarationFileOverrides(),
     ...overrides
   );
 }

eslint/next.js

@@ -6,7 +6,13 @@
 import antfu from '@antfu/eslint-config';
 import nextPlugin from '@next/eslint-plugin-next';
 import prettier from 'eslint-config-prettier/flat';
-import { antfuTypescript, sonarLayer, sonarReactRules, sonarTestOff } from './_shared.js';
+import {
+  antfuTypescript,
+  declarationFileOverrides,
+  sonarLayer,
+  sonarReactRules,
+  sonarTestOff,
+} from './_shared.js';
 
 /**
  * Flat-config block registering @next/eslint-plugin-next with its core-web-vitals
@@ -61,6 +67,7 @@ export function next(options = {}) {
     sonarReactRules(),
     sonarTestOff(testGlobs),
     prettier,
+    declarationFileOverrides(),
     ...overrides
   );
 }

eslint/react-native.js

@@ -15,7 +15,13 @@
 
 import antfu from '@antfu/eslint-config';
 import prettier from 'eslint-config-prettier/flat';
-import { antfuTypescript, sonarLayer, sonarReactRules, sonarTestOff } from './_shared.js';
+import {
+  antfuTypescript,
+  declarationFileOverrides,
+  sonarLayer,
+  sonarReactRules,
+  sonarTestOff,
+} from './_shared.js';
 
 /**
  * RN runtime globals that antfu's browser+node globals don't already cover.
@@ -74,6 +80,7 @@ export function reactNative(options = {}) {
     sonarReactRules(),
     sonarTestOff(testGlobs),
     prettier,
+    declarationFileOverrides(),
     ...overrides
   );
 }

eslint/react.js

@@ -4,7 +4,13 @@
 
 import antfu from '@antfu/eslint-config';
 import prettier from 'eslint-config-prettier/flat';
-import { antfuTypescript, sonarLayer, sonarReactRules, sonarTestOff } from './_shared.js';
+import {
+  antfuTypescript,
+  declarationFileOverrides,
+  sonarLayer,
+  sonarReactRules,
+  sonarTestOff,
+} from './_shared.js';
 
 /**
  * @typedef {object} ReactOptions
@@ -45,6 +51,7 @@ export function react(options = {}) {
     sonarReactRules(),
     sonarTestOff(testGlobs),
     prettier,
+    declarationFileOverrides(),
     ...overrides
   );
 }

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zoldytech/javascript",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": true,
   "description": "Zoldytech's JavaScript/TypeScript standards: SonarQube-compatible ESLint presets (Next.js, NestJS, React+Vite, plain JS/TS) plus shared Prettier and tsconfig configs.",
   "license": "MIT",