@jterrazz/typescript 9.3.0 → 10.1.0

package/rules/core/typescript.js

@@ -0,0 +1,223 @@
+import { allOn, fragment, off, on, scoped, typeAware, unsafeFix } from '../_contract.js';
+
+/*
+ * The `typescript` plugin, all 108 non-nursery rules decided by name. Fifty-one
+ * of them need type information: they run because every profile ships
+ * `options.typeAware`, which `oxlint-tsgolint` answers (it embeds its own
+ * TypeScript, so a consumer is not forced onto TypeScript 7 to get them).
+ */
+/*
+ * A JavaScript file has no parameter types. Every value flowing through one is
+ * `any` by construction, so the unsafe-any family reports the LANGUAGE, not a
+ * defect — measured on this package's own tree, 530 reports of which not one
+ * named a bug. The family stays armed everywhere TypeScript types the code.
+ */
+const UNTYPED_BY_CONSTRUCTION = {
+    by: 'TypeScript — a .js file has no parameter types, so every value in it is `any` and the rule reports the language, not a defect',
+    kind: 'covered',
+};
+
+const UNTYPED_IN_JAVASCRIPT = [
+    'no-unsafe-argument',
+    'no-unsafe-assignment',
+    'no-unsafe-call',
+    'no-unsafe-enum-comparison',
+    'no-unsafe-member-access',
+    'no-unsafe-return',
+    'no-unsafe-type-assertion',
+    'no-unsafe-unary-minus',
+    'strict-boolean-expressions',
+].map((rule) => [`typescript/${rule}`, off(UNTYPED_BY_CONSTRUCTION)]);
+
+export default fragment({
+    id: 'core/typescript',
+    plugins: ['typescript'],
+    overrides: [
+        scoped({
+            files: ['**/*.js', '**/*.cjs', '**/*.mjs'],
+            rules: Object.fromEntries(UNTYPED_IN_JAVASCRIPT),
+        }),
+    ],
+    rules: {
+        ...allOn(
+            [
+                'adjacent-overload-signatures',
+                'ban-tslint-comment',
+                'class-literal-property-style',
+                'consistent-generic-constructors',
+                'consistent-indexed-object-style',
+                'consistent-type-assertions',
+                'no-confusing-non-null-assertion',
+                'no-duplicate-enum-values',
+                'no-dynamic-delete',
+                'no-empty-object-type',
+                'no-explicit-any',
+                'no-extra-non-null-assertion',
+                'no-extraneous-class',
+                'no-inferrable-types',
+                'no-invalid-void-type',
+                'no-misused-new',
+                'no-namespace',
+                'no-non-null-asserted-nullish-coalescing',
+                'no-non-null-asserted-optional-chain',
+                'no-non-null-assertion',
+                'no-require-imports',
+                'no-restricted-types',
+                'no-this-alias',
+                'no-unnecessary-parameter-property-assignment',
+                'no-unnecessary-type-constraint',
+                'no-unsafe-declaration-merging',
+                'no-unsafe-function-type',
+                'no-useless-empty-export',
+                'no-wrapper-object-types',
+                'parameter-properties',
+                'prefer-as-const',
+                'prefer-enum-initializers',
+                'prefer-for-of',
+                'prefer-function-type',
+                'prefer-literal-enum-member',
+                'prefer-namespace-keyword',
+                'prefer-ts-expect-error',
+                'triple-slash-reference',
+                'unified-signatures',
+            ].map((rule) => `typescript/${rule}`),
+        ),
+
+        // -- On, and type-aware ----------------------------------------------
+        ...Object.fromEntries(
+            [
+                'await-thenable',
+                'consistent-return',
+                'consistent-type-exports',
+                'dot-notation',
+                'no-array-delete',
+                'no-base-to-string',
+                'no-deprecated',
+                'no-duplicate-type-constituents',
+                'no-floating-promises',
+                'no-for-in-array',
+                'no-implied-eval',
+                'no-meaningless-void-operator',
+                'no-misused-promises',
+                'no-misused-spread',
+                'no-mixed-enums',
+                'no-redundant-type-constituents',
+                'no-unnecessary-boolean-literal-compare',
+                'no-unnecessary-qualifier',
+                'no-unnecessary-template-expression',
+                'no-unnecessary-type-arguments',
+                'no-unnecessary-type-conversion',
+                'no-unnecessary-type-parameters',
+                'no-unsafe-argument',
+                'no-unsafe-assignment',
+                'no-unsafe-call',
+                'no-unsafe-enum-comparison',
+                'no-unsafe-member-access',
+                'no-unsafe-return',
+                'no-unsafe-type-assertion',
+                'no-unsafe-unary-minus',
+                'no-useless-default-assignment',
+                'only-throw-error',
+                'prefer-find',
+                'prefer-includes',
+                'prefer-promise-reject-errors',
+                'prefer-readonly',
+                'prefer-reduce-type-parameter',
+                'prefer-regexp-exec',
+                'prefer-return-this-type',
+                'prefer-string-starts-ends-with',
+                'promise-function-async',
+                'related-getter-setter-pairs',
+                'require-array-sort-compare',
+                'require-await',
+                'restrict-plus-operands',
+                'restrict-template-expressions',
+                'strict-boolean-expressions',
+                'strict-void-return',
+                'switch-exhaustiveness-check',
+                'unbound-method',
+                'use-unknown-in-catch-callback-variable',
+            ].map((rule) => [`typescript/${rule}`, typeAware()]),
+        ),
+
+        // -- On, at the strictest value the option carries ---------------------
+        'typescript/array-type': on([{ default: 'array' }]),
+        'typescript/ban-ts-comment': on([
+            {
+                'ts-check': false,
+                'ts-expect-error': 'allow-with-description',
+                'ts-ignore': true,
+                'ts-nocheck': true,
+            },
+        ]),
+        /* Three fixers that change meaning, so `fix` never applies them and
+         * `check` still reports them: one rewrites a `declare module`
+         * augmentation into an alias that no longer merges, one wraps a
+         * returned promise so nothing awaits it, one drops a cast a widened
+         * platform type needs. */
+        'typescript/consistent-type-definitions': unsafeFix(
+            on(['type']),
+            'rewrites a `declare module` augmentation into an alias, which no longer merges',
+        ),
+        'typescript/no-confusing-void-expression': unsafeFix(
+            typeAware(),
+            'wraps a returned promise, after which nothing awaits it',
+        ),
+        'typescript/no-unnecessary-type-assertion': unsafeFix(
+            typeAware(),
+            'drops a cast a widened platform type needs',
+        ),
+        /* `separate-type-imports`, for `import/consistent-type-specifier-style`'s
+         * reason: an inline type specifier survives `verbatimModuleSyntax` as an
+         * empty runtime import. */
+        'typescript/consistent-type-imports': on([
+            {
+                disallowTypeAnnotations: true,
+                fixStyle: 'separate-type-imports',
+                prefer: 'type-imports',
+            },
+        ]),
+        /* The guard for the emit above: an all-inline type import is the shape
+         * `verbatimModuleSyntax` turns into a side effect, and this names it. */
+        'typescript/no-import-type-side-effects': on(),
+        'typescript/explicit-member-accessibility': on([{ accessibility: 'no-public' }]),
+        /* Booleans excepted: `false ?? x` is `false` and `false || x` is `x`,
+         * so on a boolean the two operators mean different things and the
+         * rewrite the rule asks for is not the same expression. */
+        'typescript/prefer-nullish-coalescing': typeAware([
+            { ignorePrimitives: { boolean: true } },
+        ]),
+        'typescript/method-signature-style': on(['property']),
+        'typescript/return-await': typeAware(['always']),
+
+        // -- Off, each with its one reason -------------------------------------
+        'typescript/ban-types': off({
+            by: 'typescript/no-empty-object-type, no-unsafe-function-type, no-wrapper-object-types — its three successors',
+            kind: 'covered',
+        }),
+        'typescript/explicit-function-return-type': off({
+            by: 'presets/tsdown/bundle.js — isolatedDeclarations requires the annotation exactly where it is load-bearing, on a published export',
+            kind: 'covered',
+        }),
+        'typescript/explicit-module-boundary-types': off({
+            by: 'presets/tsdown/bundle.js — isolatedDeclarations requires the annotation exactly where it is load-bearing, on a published export',
+            kind: 'covered',
+        }),
+        'typescript/no-empty-interface': off({
+            by: 'typescript/no-empty-object-type — its upstream successor',
+            kind: 'covered',
+        }),
+        'typescript/non-nullable-type-assertion-style': off({
+            by: 'typescript/no-non-null-assertion — its fix is the `!` assertion that rule forbids, so no edit closes both',
+            kind: 'exclusive',
+        }),
+        'typescript/no-var-requires': off({
+            by: 'typescript/no-require-imports — its upstream successor',
+            kind: 'covered',
+        }),
+        'typescript/prefer-readonly-parameter-types': off({
+            by: 'no-param-reassign, typescript/prefer-readonly — the defect is mutation, and both name it',
+            kind: 'covered',
+        }),
+    },
+});

package/rules/core/unicorn.js

@@ -0,0 +1,210 @@
+import { allOn, fragment, off, on, unsafeFix } from '../_contract.js';
+
+/*
+ * The `unicorn` plugin, all 137 non-nursery rules decided by name. Two of the
+ * offs are the formatter's: unicorn's fixer and oxfmt disagree about the same
+ * bytes, and the fixpoint suite is what proves it (specs/cli/preset).
+ */
+export default fragment({
+    id: 'core/unicorn',
+    plugins: ['unicorn'],
+    rules: {
+        ...allOn(
+            [
+                'catch-error-name',
+                'consistent-assert',
+                'consistent-date-clone',
+                'consistent-empty-array-spread',
+                'consistent-existence-index-check',
+                'consistent-function-scoping',
+                'consistent-template-literal-escape',
+                'custom-error-definition',
+                'empty-brace-spaces',
+                'error-message',
+                'escape-case',
+                'explicit-timer-delay',
+                'max-nested-calls',
+                'new-for-builtins',
+                'no-abusive-eslint-disable',
+                'no-accessor-recursion',
+                'no-anonymous-default-export',
+                'no-array-fill-with-reference-type',
+                'no-array-for-each',
+                'no-array-method-this-argument',
+                'no-array-reduce',
+                'no-array-reverse',
+                'no-array-sort',
+                'no-await-expression-member',
+                'no-await-in-promise-methods',
+                'no-confusing-array-with',
+                'no-console-spaces',
+                'no-document-cookie',
+                'no-empty-file',
+                'no-hex-escape',
+                'no-immediate-mutation',
+                'no-instanceof-builtins',
+                'no-invalid-fetch-options',
+                'no-invalid-remove-event-listener',
+                'no-length-as-slice-end',
+                'no-lonely-if',
+                'no-magic-array-flat-depth',
+                'no-negated-condition',
+                'no-negation-in-equality-check',
+                'no-new-array',
+                'no-new-buffer',
+                'no-object-as-default-parameter',
+                'no-process-exit',
+                'no-single-promise-in-promise-methods',
+                'no-static-only-class',
+                'no-thenable',
+                'no-this-assignment',
+                'no-typeof-undefined',
+                'no-unnecessary-array-flat-depth',
+                'no-unnecessary-array-splice-count',
+                'no-unnecessary-await',
+                'no-unnecessary-slice-end',
+                'no-unreadable-array-destructuring',
+                'no-unreadable-iife',
+                'no-useless-collection-argument',
+                'no-useless-error-capture-stack-trace',
+                'no-useless-fallback-in-spread',
+                'no-useless-length-check',
+                'no-useless-promise-resolve-reject',
+                'no-useless-spread',
+                'no-useless-switch-case',
+                'no-zero-fractions',
+                'numeric-separators-style',
+                'prefer-add-event-listener',
+                'prefer-array-find',
+                'prefer-array-flat',
+                'prefer-array-flat-map',
+                'prefer-array-index-of',
+                'prefer-array-some',
+                'prefer-at',
+                'prefer-bigint-literals',
+                'prefer-blob-reading-methods',
+                'prefer-class-fields',
+                'prefer-classlist-toggle',
+                'prefer-code-point',
+                'prefer-date-now',
+                'prefer-default-parameters',
+                'prefer-dom-node-append',
+                'prefer-dom-node-dataset',
+                'prefer-dom-node-remove',
+                'prefer-dom-node-text-content',
+                'prefer-event-target',
+                'prefer-export-from',
+                'prefer-global-this',
+                'prefer-keyboard-event-key',
+                'prefer-logical-operator-over-ternary',
+                'prefer-math-min-max',
+                'prefer-math-trunc',
+                'prefer-modern-dom-apis',
+                'prefer-modern-math-apis',
+                'prefer-module',
+                'prefer-native-coercion-functions',
+                'prefer-negative-index',
+                'prefer-node-protocol',
+                'prefer-number-properties',
+                'prefer-object-from-entries',
+                'prefer-optional-catch-binding',
+                'prefer-prototype-methods',
+                'prefer-query-selector',
+                'prefer-reflect-apply',
+                'prefer-regexp-test',
+                'prefer-response-static-json',
+                'prefer-set-has',
+                'prefer-set-size',
+                'prefer-single-call',
+                'prefer-spread',
+                'prefer-string-raw',
+                'prefer-string-replace-all',
+                'prefer-string-slice',
+                'prefer-string-trim-start-end',
+                'prefer-structured-clone',
+                'prefer-ternary',
+                'prefer-top-level-await',
+                'prefer-type-error',
+                'relative-url-style',
+                'require-array-join-separator',
+                'require-module-attributes',
+                'require-module-specifiers',
+                'require-number-to-fixed-digits-argument',
+                'require-post-message-target-origin',
+                'switch-case-braces',
+                'switch-case-break-position',
+                'throw-new-error',
+            ].map((rule) => `unicorn/${rule}`),
+        ),
+
+        // -- On, at the strictest value the option carries ---------------------
+        'unicorn/filename-case': on([{ case: 'kebabCase' }]),
+        /* The estate imports a Node builtin by name — `import { resolve } from
+         * 'node:path'` — because that is what the type-aware rules read and what
+         * `verbatimModuleSyntax` keeps. The rule's default asks for the default
+         * import on exactly these three. */
+        'unicorn/import-style': on([
+            {
+                styles: {
+                    'node:path': { named: true },
+                    'node:util': { named: true },
+                    path: { named: true },
+                    util: { named: true },
+                },
+            },
+        ]),
+        /* No `withDash`: the estate writes `'utf8'`, which is the rule's own
+         * default preference, and `'utf-8'` is the same encoding spelled longer. */
+        'unicorn/text-encoding-identifier-case': on(),
+
+        /* Both fixers change meaning, so `fix` never applies them and `check`
+         * still reports them: one strips a REQUIRED argument, the other drops
+         * the trailing slash `new URL('.', import.meta.url)` carries. */
+        'unicorn/no-useless-undefined': unsafeFix(
+            on(),
+            'strips a REQUIRED argument, `mockReturnValue(undefined)` included (TS2554)',
+        ),
+        'unicorn/prefer-import-meta-properties': unsafeFix(
+            on(),
+            "rewrites `fileURLToPath(new URL('.', import.meta.url))` into `import.meta.dirname`, which carries no trailing slash",
+        ),
+
+        // -- Off, each with its one reason -------------------------------------
+        'unicorn/explicit-length-check': off({
+            by: 'typescript/strict-boolean-expressions — it already refuses a length used as a condition',
+            kind: 'covered',
+        }),
+        'unicorn/no-array-callback-reference': off({
+            by: 'measured on this package — every report was a correct point-free callback',
+            kind: 'evidence',
+        }),
+        'unicorn/no-instanceof-array': off({
+            by: 'unicorn/no-instanceof-builtins — its upstream successor',
+            kind: 'covered',
+        }),
+        'unicorn/no-nested-ternary': off({
+            by: 'oxfmt — its fixer parenthesises the inner ternary and the formatter strips the parentheses, so every fix round ping-pongs',
+            kind: 'formatter',
+        }),
+        'unicorn/no-null': off({
+            by: 'docs/07-lint-presets.md — null is what the platform and JSON APIs return, and a codebase that refuses it grows a translation layer at every boundary',
+            kind: 'convention',
+        }),
+        'unicorn/prefer-number-coercion': off({
+            by: 'measured on this package — it rewrites `Number.parseInt("01-architecture.md", 10)`, which is 1, into `Math.trunc(Number(...))`, which is NaN; the rule assumes the string holds nothing but digits',
+            kind: 'evidence',
+        }),
+        'unicorn/number-literal-case': off({
+            by: 'oxfmt — oxc#21949: the two disagree on the case of a hex literal and rewrite each other',
+            kind: 'formatter',
+        }),
+        'unicorn/prefer-includes': off({
+            by: 'typescript/prefer-includes — the type-aware rule of the same name',
+            kind: 'covered',
+        }),
+        'unicorn/prefer-string-starts-ends-with': off({
+            by: 'typescript/prefer-string-starts-ends-with — the type-aware rule of the same name',
+            kind: 'covered',
+        }),
+    },
+});

package/rules/next.js

@@ -0,0 +1,53 @@
+import { allOn, fragment, off, scoped } from './_contract.js';
+import { EXTENSIONS_NEVER } from './core/import.js';
+
+/*
+ * The `nextjs` plugin, all 21 rules on, plus the two decisions Next's own
+ * resolution forces: a bundler resolves an import, so a specifier carries no
+ * extension, and `next-env.d.ts` is a side-effect import Next writes itself.
+ */
+export default fragment({
+    id: 'next',
+    plugins: ['nextjs'],
+    ignorePatterns: ['.next/**', 'next-env.d.ts', 'assets/**', 'public/**'],
+    overrides: [
+        scoped({
+            files: ['**/next-env.d.ts'],
+            rules: {
+                'import/no-unassigned-import': off({
+                    by: 'Next writes this file, and its whole body is a triple-slash reference',
+                    kind: 'convention',
+                }),
+            },
+        }),
+    ],
+    rules: {
+        ...allOn(
+            [
+                'google-font-display',
+                'google-font-preconnect',
+                'inline-script-id',
+                'next-script-for-ga',
+                'no-assign-module-variable',
+                'no-async-client-component',
+                'no-before-interactive-script-outside-document',
+                'no-css-tags',
+                'no-document-import-in-page',
+                'no-duplicate-head',
+                'no-head-element',
+                'no-head-import-in-document',
+                'no-html-link-for-pages',
+                'no-img-element',
+                'no-page-custom-font',
+                'no-script-component-in-head',
+                'no-styled-jsx-in-document',
+                'no-sync-scripts',
+                'no-title-in-document-head',
+                'no-typos',
+                'no-unwanted-polyfillio',
+            ].map((rule) => `nextjs/${rule}`),
+        ),
+
+        'import/extensions': EXTENSIONS_NEVER,
+    },
+});

package/rules/profiles.js

@@ -0,0 +1,95 @@
+import a11y from './a11y.js';
+import astro from './astro.js';
+import bundler from './bundler.js';
+import eslint from './core/eslint.js';
+import importPlugin from './core/import.js';
+import jsdoc from './core/jsdoc.js';
+import node from './core/node.js';
+import oxc from './core/oxc.js';
+import promise from './core/promise.js';
+import typescript from './core/typescript.js';
+import unicorn from './core/unicorn.js';
+import next from './next.js';
+import reactNative from './react-native.js';
+import react from './react.js';
+import sorted from './sorted.js';
+import vitest from './vitest.js';
+
+/*
+ * Which fragments each profile carries. A profile ADDS a framework's plugins
+ * and its ignore patterns to the core rulebook; it never subtracts from it, and
+ * no profile sets a core rule to `off`
+ * ([Lint presets](../docs/07-lint-presets.md)).
+ *
+ * `presets/oxlint/profiles/<name>.js` is this table compiled; nothing else
+ * decides what a profile holds.
+ */
+
+/** The rulebook every profile carries, whatever it is written in. */
+export const CORE = Object.freeze([
+    eslint,
+    typescript,
+    unicorn,
+    oxc,
+    importPlugin,
+    promise,
+    node,
+    jsdoc,
+    sorted,
+    vitest,
+]);
+
+/*
+ * Trees no profile lints. `.artifacts/` is deliberately absent: it is
+ * gitignored and oxlint reads `.gitignore` on its own, so naming it here too
+ * would make it unlintable even where a caller asks for it by name.
+ */
+const IGNORED = Object.freeze([
+    'dist/**',
+    'node_modules/**',
+    // What a spec stands on and what it is measured against are @jterrazz/test
+    // 14's underscored trees: an input is deliberately broken and a golden is
+    // Byte-for-byte, so neither is source and neither is linted.
+    '**/_fixtures/**',
+    '**/_expected/**',
+]);
+
+/** Every profile, by the name a consumer imports. */
+export const PROFILES = Object.freeze({
+    astro: {
+        env: { astro: true, browser: true, builtin: true, node: true },
+        fragments: [...CORE, react, a11y, astro],
+        ignorePatterns: [...IGNORED],
+    },
+    bun: {
+        env: { builtin: true, node: true },
+        fragments: [...CORE],
+        globals: { Bun: 'readonly' },
+        ignorePatterns: [...IGNORED],
+    },
+    expo: {
+        env: { browser: true, builtin: true, node: true },
+        fragments: [...CORE, react, a11y, reactNative],
+        ignorePatterns: [...IGNORED],
+    },
+    library: {
+        env: { builtin: true, node: true },
+        fragments: [...CORE],
+        ignorePatterns: [...IGNORED, 'docs/reference/**'],
+    },
+    next: {
+        env: { browser: true, builtin: true, node: true },
+        fragments: [...CORE, react, a11y, next],
+        ignorePatterns: [...IGNORED],
+    },
+    node: {
+        env: { builtin: true, node: true },
+        fragments: [...CORE],
+        ignorePatterns: [...IGNORED],
+    },
+    react: {
+        env: { browser: true, builtin: true, node: true },
+        fragments: [...CORE, react, a11y, bundler],
+        ignorePatterns: [...IGNORED],
+    },
+});

package/rules/react-native.js

@@ -0,0 +1,48 @@
+import { fragment, on } from './_contract.js';
+import { EXTENSIONS_NEVER } from './core/import.js';
+
+/*
+ * React Native. oxlint 1.83 ships no `react-native` plugin, so this fragment
+ * is not a plugin roster: it is the three decisions the platform forces, plus
+ * the globals its runtime defines.
+ *
+ * Metro resolves an import, so a specifier carries no extension — except an
+ * asset, which Metro resolves BY its extension, and `require()` is how an
+ * asset is named in a React Native tree.
+ */
+export default fragment({
+    id: 'react-native',
+    globals: {
+        __DEV__: 'readonly',
+        ErrorUtils: 'readonly',
+        FormData: 'readonly',
+        XMLHttpRequest: 'readonly',
+        fetch: 'readonly',
+        requestAnimationFrame: 'readonly',
+    },
+    ignorePatterns: ['.expo/**', 'assets/**', 'ios/**', 'android/**'],
+    rules: {
+        'import/extensions': EXTENSIONS_NEVER,
+        'no-restricted-imports': on([
+            {
+                patterns: [
+                    {
+                        group: ['react-dom', 'react-dom/*', 'next', 'next/*'],
+                        message: 'this is a React Native tree — the DOM and Next are not on it',
+                    },
+                ],
+            },
+        ]),
+        'typescript/no-require-imports': on([
+            {
+                allow: [
+                    String.raw`\.gif$`,
+                    String.raw`\.jpeg$`,
+                    String.raw`\.jpg$`,
+                    String.raw`\.png$`,
+                    String.raw`\.webp$`,
+                ],
+            },
+        ]),
+    },
+});