@jterrazz/typescript 9.3.0 → 10.1.0

package/rules/core/eslint.js

@@ -0,0 +1,234 @@
+import { allOn, fragment, off, on } from '../_contract.js';
+
+/*
+ * The `eslint` plugin: oxlint's port of the ESLint core rules, all 183
+ * non-nursery ones decided by name. The offs below are the whole list, and
+ * each carries the one reason that justifies it.
+ */
+export default fragment({
+    id: 'core/eslint',
+    plugins: ['eslint'],
+    rules: {
+        ...allOn([
+            'accessor-pairs',
+            'array-callback-return',
+            'block-scoped-var',
+            'class-methods-use-this',
+            'constructor-super',
+            'curly',
+            'default-case',
+            'default-case-last',
+            'default-param-last',
+            'eqeqeq',
+            'for-direction',
+            'func-name-matching',
+            'func-names',
+            'getter-return',
+            'grouped-accessor-pairs',
+            'guard-for-in',
+            'id-denylist',
+            'id-match',
+            'logical-assignment-operators',
+            'max-classes-per-file',
+            'max-nested-callbacks',
+            'new-cap',
+            'no-alert',
+            'no-array-constructor',
+            'no-async-promise-executor',
+            'no-await-in-loop',
+            'no-bitwise',
+            'no-caller',
+            'no-case-declarations',
+            'no-class-assign',
+            'no-compare-neg-zero',
+            'no-cond-assign',
+            'no-console',
+            'no-const-assign',
+            'no-constant-binary-expression',
+            'no-constant-condition',
+            'no-constructor-return',
+            'no-control-regex',
+            'no-debugger',
+            'no-delete-var',
+            'no-div-regex',
+            'no-dupe-class-members',
+            'no-dupe-else-if',
+            'no-dupe-keys',
+            'no-duplicate-case',
+            'no-else-return',
+            'no-empty',
+            'no-empty-character-class',
+            'no-empty-function',
+            'no-empty-pattern',
+            'no-empty-static-block',
+            'no-eq-null',
+            'no-eval',
+            'no-ex-assign',
+            'no-extend-native',
+            'no-extra-bind',
+            'no-extra-boolean-cast',
+            'no-extra-label',
+            'no-fallthrough',
+            'no-func-assign',
+            'no-global-assign',
+            'no-implicit-coercion',
+            'no-implicit-globals',
+            'no-import-assign',
+            'no-inline-comments',
+            'no-inner-declarations',
+            'no-invalid-regexp',
+            'no-irregular-whitespace',
+            'no-iterator',
+            'no-label-var',
+            'no-labels',
+            'no-lone-blocks',
+            'no-loop-func',
+            'no-loss-of-precision',
+            'no-misleading-character-class',
+            'no-multi-assign',
+            'no-multi-str',
+            'no-new',
+            'no-new-func',
+            'no-new-native-nonconstructor',
+            'no-new-wrappers',
+            'no-nonoctal-decimal-escape',
+            'no-obj-calls',
+            'no-object-constructor',
+            'no-param-reassign',
+            'no-plusplus',
+            'no-promise-executor-return',
+            'no-proto',
+            'no-prototype-builtins',
+            'no-redeclare',
+            'no-regex-spaces',
+            'no-restricted-globals',
+            'no-restricted-imports',
+            'no-restricted-properties',
+            'no-return-assign',
+            'no-script-url',
+            'no-self-assign',
+            'no-self-compare',
+            'no-sequences',
+            'no-setter-return',
+            'no-shadow',
+            'no-shadow-restricted-names',
+            'no-sparse-arrays',
+            'no-template-curly-in-string',
+            'no-this-before-super',
+            'no-unassigned-vars',
+            'no-underscore-dangle',
+            'no-unexpected-multiline',
+            'no-unneeded-ternary',
+            'no-unreachable',
+            'no-unsafe-finally',
+            'no-unsafe-negation',
+            'no-unsafe-optional-chaining',
+            'no-unused-labels',
+            'no-unused-private-class-members',
+            'no-unused-vars',
+            'no-useless-backreference',
+            'no-useless-call',
+            'no-useless-catch',
+            'no-useless-computed-key',
+            'no-useless-concat',
+            'no-useless-constructor',
+            'no-useless-escape',
+            'no-useless-rename',
+            'no-useless-return',
+            'no-var',
+            'no-warning-comments',
+            'no-with',
+            'object-shorthand',
+            'operator-assignment',
+            'prefer-arrow-callback',
+            'prefer-const',
+            'prefer-exponentiation-operator',
+            'prefer-named-capture-group',
+            'prefer-numeric-literals',
+            'prefer-object-has-own',
+            'prefer-object-spread',
+            'prefer-regex-literals',
+            'prefer-rest-params',
+            'prefer-spread',
+            'prefer-template',
+            'preserve-caught-error',
+            'radix',
+            'require-unicode-regexp',
+            'require-yield',
+            'symbol-description',
+            'unicode-bom',
+            'use-isnan',
+            'valid-typeof',
+            'vars-on-top',
+            'yoda',
+        ]),
+
+        // -- On, at the strictest value the option carries --------------------
+        'arrow-body-style': on(['as-needed']),
+        complexity: on([12]),
+        'func-style': on(['declaration', { allowArrowFunctions: true }]),
+        'max-depth': on([4]),
+        'max-params': on([4]),
+        'no-duplicate-imports': on([{ allowSeparateTypeImports: true }]),
+        'no-unmodified-loop-condition': on([{ checkConditionalExpressions: true }]),
+        /* A hoisted function declaration has no temporal dead zone, and the
+         * estate writes the public function first and its helpers below it.
+         * The defect this rule names — reading a binding before it exists — is
+         * a `let`, a `const` or a `class`, and all three stay refused. */
+        'no-use-before-define': on([{ classes: true, functions: false, variables: true }]),
+        'no-unused-expressions': on([
+            { allowShortCircuit: true, allowTaggedTemplates: true, allowTernary: true },
+        ]),
+        'no-void': on([{ allowAsStatement: true }]),
+        /* The object form names what it takes; the array form past index 0
+         * counts commas, and `const [, , , operating] = SPINE` is not clearer
+         * than `SPINE[3]`. */
+        'prefer-destructuring': on([{ array: false, object: true }]),
+        /* `never`, not `always`. Both exist and both fix, but the `always` fixer
+         * FUSES adjacent declarations, and a comment standing between two of
+         * them is pulled inside the chain — which silently relocates the
+         * `// Given -` / `// Then -` narration @jterrazz/test requires. `never`
+         * splits chains and leaves every comment where it stands. */
+        'one-var': on(['never']),
+
+        // -- Off, each with its one reason ------------------------------------
+        'capitalized-comments': off({
+            by: 'jterrazz-design — 198 of 198 reports were false positives (quality study, 2026-09-15)',
+            kind: 'evidence',
+        }),
+        'id-length': off({
+            by: 'measured on this package — every report was a conventional short binding (k, v, x)',
+            kind: 'evidence',
+        }),
+        'init-declarations': off({ by: 'no-unassigned-vars, prefer-const', kind: 'covered' }),
+        'max-lines': off({ by: 'complexity (12)', kind: 'covered' }),
+        'max-lines-per-function': off({ by: 'complexity (12)', kind: 'covered' }),
+        'max-statements': off({ by: 'complexity (12)', kind: 'covered' }),
+        'no-continue': off({ by: 'max-depth (4)', kind: 'exclusive' }),
+        'no-implied-eval': off({ by: 'typescript/no-implied-eval', kind: 'covered' }),
+        'no-lonely-if': off({ by: 'unicorn/no-lonely-if', kind: 'covered' }),
+        'no-magic-numbers': off({
+            by: 'measured on this package — 125 reports, not one of them a defect',
+            kind: 'evidence',
+        }),
+        'no-negated-condition': off({ by: 'unicorn/no-negated-condition', kind: 'covered' }),
+        'no-nested-ternary': off({ by: 'unicorn/prefer-ternary', kind: 'exclusive' }),
+        'no-ternary': off({ by: 'unicorn/prefer-ternary', kind: 'exclusive' }),
+        'no-throw-literal': off({ by: 'typescript/only-throw-error', kind: 'covered' }),
+        'no-undefined': off({
+            by: 'no-shadow-restricted-names, no-global-assign — `undefined` cannot be rebound, which is the hazard this ES3-era rule was written for',
+            kind: 'covered',
+        }),
+        'prefer-promise-reject-errors': off({
+            by: 'typescript/prefer-promise-reject-errors',
+            kind: 'covered',
+        }),
+        'require-await': off({ by: 'typescript/require-await', kind: 'covered' }),
+        'sort-imports': off({ by: 'oxfmt sortImports', kind: 'covered' }),
+        'sort-keys': off({
+            by: 'docs/07-lint-presets.md — an object orders by meaning, and generic inference is order-sensitive',
+            kind: 'convention',
+        }),
+        'sort-vars': off({ by: 'one-var (never)', kind: 'covered' }),
+    },
+});

package/rules/core/import.js

@@ -0,0 +1,117 @@
+import { allOn, fragment, off, on } from '../_contract.js';
+
+/*
+ * The `import` plugin, all 31 non-nursery rules decided by name.
+ *
+ * `import/extensions` is the one rule two platforms answer differently: Node
+ * ESM resolves a specifier literally and needs the `.js`, a bundler resolves it
+ * and refuses one. Core states the Node answer; `rules/next.js`,
+ * `rules/astro.js`, `rules/react-native.js` and `rules/bundler.js` re-decide it
+ * for their platform, at `error` either way — a profile changes the convention,
+ * never the level.
+ *
+ * `import/no-cycle` rides here for +0.05s. Mind what it does NOT see: oxlint's
+ * implementation ignores type-only imports, so a value import one way and an
+ * `import type` back is invisible to it (oxc#20551).
+ */
+
+/** Asset specifiers keep their extension on every platform — a bundler resolves them by it. */
+export const ASSETS = {
+    avif: 'always',
+    css: 'always',
+    gif: 'always',
+    jpeg: 'always',
+    jpg: 'always',
+    json: 'always',
+    less: 'always',
+    png: 'always',
+    sass: 'always',
+    scss: 'always',
+    svg: 'always',
+    webp: 'always',
+};
+
+export const EXTENSIONS_ALWAYS = on(['always', { ignorePackages: true, ...ASSETS }]);
+export const EXTENSIONS_NEVER = on(['never', ASSETS]);
+
+export default fragment({
+    id: 'core/import',
+    plugins: ['import'],
+    rules: {
+        ...allOn(
+            [
+                'default',
+                'first',
+                'namespace',
+                'newline-after-import',
+                'no-absolute-path',
+                'no-amd',
+                'no-commonjs',
+                'no-cycle',
+                'no-duplicates',
+                'no-dynamic-require',
+                'no-empty-named-blocks',
+                'no-mutable-exports',
+                'no-named-as-default',
+                'no-named-as-default-member',
+                'no-named-default',
+                'no-namespace',
+                'no-self-import',
+                'no-unassigned-import',
+                'no-webpack-loader-syntax',
+            ].map((rule) => `import/${rule}`),
+        ),
+
+        // -- On, at the strictest value the option carries ---------------------
+        /*
+         * Top level, not inline, and `verbatimModuleSyntax` is why: under it
+         * `import { type X } from 'leaflet'` is emitted as
+         * `import {} from 'leaflet'` — a runtime side-effect import of a module
+         * that may only exist in a browser. signews-web served a 500 from it.
+         */
+        'import/consistent-type-specifier-style': on(['prefer-top-level']),
+        'import/extensions': EXTENSIONS_ALWAYS,
+
+        // -- Off, each with its one reason -------------------------------------
+        'import/exports-last': off({
+            by: 'docs/07-lint-presets.md — an export sits with the declaration it exports; three repositories had refused this rule locally before the decision moved here',
+            kind: 'convention',
+        }),
+        'import/group-exports': off({
+            by: 'docs/07-lint-presets.md — an export sits with the declaration it exports',
+            kind: 'convention',
+        }),
+        'import/max-dependencies': off({
+            by: 'oxc/no-barrel-file — the defect a dependency count stands in for is the barrel, and that rule names it',
+            kind: 'covered',
+        }),
+        'import/no-anonymous-default-export': off({
+            by: 'unicorn/no-anonymous-default-export',
+            kind: 'covered',
+        }),
+        'import/no-default-export': off({
+            by: 'docs/07-lint-presets.md — every framework config file and every preset of this package is a default export',
+            kind: 'convention',
+        }),
+        'import/no-named-export': off({
+            by: 'docs/07-lint-presets.md — a module exports what it owns by name',
+            kind: 'convention',
+        }),
+        'import/no-nodejs-modules': off({
+            by: 'docs/07-lint-presets.md — the estate ships Node services, and a browser boundary is the profile that states it',
+            kind: 'convention',
+        }),
+        'import/no-relative-parent-imports': off({
+            by: 'docs/07-lint-presets.md — a relative parent import is how a package reaches its own sibling module; layer boundaries are the layer map, not the path shape',
+            kind: 'convention',
+        }),
+        'import/prefer-default-export': off({
+            by: 'docs/07-lint-presets.md — a module exports what it owns by name',
+            kind: 'convention',
+        }),
+        'import/unambiguous': off({
+            by: 'TypeScript — `verbatimModuleSyntax` and a package\'s `"type": "module"` already make every file a module, and what the rule reports beyond that is a file with nothing to export: an entry script, an Astro `is:inline` block',
+            kind: 'covered',
+        }),
+    },
+});

package/rules/core/jsdoc.js

@@ -0,0 +1,52 @@
+import { allOn, fragment, off } from '../_contract.js';
+
+/*
+ * The `jsdoc` plugin, all 23 rules decided by name. JSDoc is never REQUIRED —
+ * TypeScript carries the types and `typescript docs` derives the reference from
+ * them — but a block that is written must be well formed.
+ */
+const BY_TYPESCRIPT = {
+    by: 'TypeScript — the signature carries the type, and `typescript docs` reads it from there',
+    kind: 'covered',
+};
+
+export default fragment({
+    id: 'core/jsdoc',
+    plugins: ['jsdoc'],
+    rules: {
+        ...allOn(
+            [
+                'check-access',
+                'check-property-names',
+                'check-tag-names',
+                'empty-tags',
+                'implements-on-classes',
+                'no-blank-blocks',
+                'no-defaults',
+                'require-param-description',
+                'require-param-name',
+                'require-property',
+                'require-property-description',
+                'require-property-name',
+                'require-returns-description',
+                'require-throws-description',
+                'require-yields',
+                'require-yields-description',
+            ].map((rule) => `jsdoc/${rule}`),
+        ),
+
+        'jsdoc/require-param': off({
+            by: 'TypeScript — a parameter is documented by its type, and a description is optional prose',
+            kind: 'covered',
+        }),
+        'jsdoc/require-param-type': off(BY_TYPESCRIPT),
+        'jsdoc/require-property-type': off(BY_TYPESCRIPT),
+        'jsdoc/require-returns': off({
+            by: 'TypeScript — a return is documented by its type, and a description is optional prose',
+            kind: 'covered',
+        }),
+        'jsdoc/require-returns-type': off(BY_TYPESCRIPT),
+        'jsdoc/require-throws-type': off(BY_TYPESCRIPT),
+        'jsdoc/require-yields-type': off(BY_TYPESCRIPT),
+    },
+});

package/rules/core/node.js

@@ -0,0 +1,36 @@
+import { allOn, fragment, off } from '../_contract.js';
+
+/*
+ * The `node` plugin, all 11 rules decided by name.
+ */
+export default fragment({
+    id: 'core/node',
+    plugins: ['node'],
+    rules: {
+        ...allOn(
+            [
+                'callback-return',
+                'exports-style',
+                'global-require',
+                'handle-callback-err',
+                'no-exports-assign',
+                'no-mixed-requires',
+                'no-new-require',
+                'no-path-concat',
+            ].map((rule) => `node/${rule}`),
+        ),
+
+        'node/no-process-env': off({
+            by: 'docs/07-lint-presets.md — the estate reads configuration from the environment at the edge and has no config-module to funnel it through',
+            kind: 'convention',
+        }),
+        'node/no-sync': off({
+            by: 'docs/07-lint-presets.md — a one-shot CLI script has no event loop to protect, and the toolchain gates are exactly that',
+            kind: 'convention',
+        }),
+        'node/no-top-level-await': off({
+            by: 'unicorn/prefer-top-level-await — one rule demands it, the other forbids it',
+            kind: 'exclusive',
+        }),
+    },
+});

package/rules/core/oxc.js

@@ -0,0 +1,54 @@
+import { allOn, fragment, off } from '../_contract.js';
+
+/*
+ * The `oxc` plugin, all 27 rules decided by name. Three of them are
+ * downlevel-syntax restrictions — they exist for a target older than the one
+ * the estate compiles to — and they are the only three that are off.
+ */
+export default fragment({
+    id: 'core/oxc',
+    plugins: ['oxc'],
+    rules: {
+        ...allOn(
+            [
+                'approx-constant',
+                'bad-array-method-on-arguments',
+                'bad-bitwise-operator',
+                'bad-char-at-comparison',
+                'bad-comparison-sequence',
+                'bad-match-all-arg',
+                'bad-min-max-func',
+                'bad-object-literal-comparison',
+                'bad-replace-all-arg',
+                'branches-sharing-code',
+                'const-comparisons',
+                'double-comparisons',
+                'erasing-op',
+                'misrefactored-assign-op',
+                'missing-throw',
+                'no-accumulating-spread',
+                'no-async-endpoint-handlers',
+                'no-barrel-file',
+                'no-const-enum',
+                'no-map-spread',
+                'no-this-in-exported-function',
+                'number-arg-out-of-range',
+                'only-used-in-recursion',
+                'uninvoked-array-callback',
+            ].map((rule) => `oxc/${rule}`),
+        ),
+
+        'oxc/no-async-await': off({
+            by: 'promise/prefer-await-to-then — one rule demands await, the other forbids it',
+            kind: 'exclusive',
+        }),
+        'oxc/no-optional-chaining': off({
+            by: 'docs/07-lint-presets.md — the estate compiles to ESNext on Node 24, where optional chaining is native syntax',
+            kind: 'convention',
+        }),
+        'oxc/no-rest-spread-properties': off({
+            by: 'docs/07-lint-presets.md — the estate compiles to ESNext on Node 24, where object rest and spread are native syntax',
+            kind: 'convention',
+        }),
+    },
+});

package/rules/core/promise.js

@@ -0,0 +1,39 @@
+import { allOn, fragment, off } from '../_contract.js';
+
+/*
+ * The `promise` plugin, all 15 non-nursery rules decided by name. The estate
+ * writes `await`, so the two rules that describe a well-behaved `.then()`
+ * chain are the ones that cannot hold beside `prefer-await-to-then`.
+ */
+export default fragment({
+    id: 'core/promise',
+    plugins: ['promise'],
+    rules: {
+        ...allOn(
+            [
+                'avoid-new',
+                'no-callback-in-promise',
+                'no-multiple-resolved',
+                'no-nesting',
+                'no-new-statics',
+                'no-promise-in-callback',
+                'no-return-wrap',
+                'param-names',
+                'prefer-await-to-callbacks',
+                'prefer-await-to-then',
+                'prefer-catch',
+                'spec-only',
+                'valid-params',
+            ].map((rule) => `promise/${rule}`),
+        ),
+
+        'promise/always-return': off({
+            by: 'promise/prefer-await-to-then — it describes a .then() chain the estate does not write',
+            kind: 'exclusive',
+        }),
+        'promise/catch-or-return': off({
+            by: 'promise/prefer-await-to-then — it describes a .then() chain the estate does not write',
+            kind: 'exclusive',
+        }),
+    },
+});