@jterrazz/typescript 9.3.0 → 10.0.0

package/rules/catalog.test.ts

@@ -0,0 +1,84 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { expect, test } from 'vitest';
+
+import { catalog, MARKERS, render, renderReference } from './catalog.js';
+
+/*
+ * The catalogue has two readers and one source. `docs/07-lint-presets.md` is
+ * the human's, with the reason and the version behind every decision; the
+ * skill reference is an agent's, trimmed to what it needs to answer "may I
+ * write this". Both carry a table between two markers, both are PROJECTIONS of
+ * `rules/`, and this suite fails either one that has drifted. Regenerate with
+ * `TEST_UPDATE=1 npm test`, the gesture every other golden here takes.
+ *
+ * It is the @jterrazz/test pattern — one manifest, every roster derived from
+ * it, freshness meta-tested — so a decision is never recorded in two places
+ * that can disagree.
+ */
+
+const PROJECTIONS = {
+    chapter: {
+        page: resolve(import.meta.dirname, '../docs/07-lint-presets.md'),
+        render,
+    },
+    'skill reference': {
+        page: resolve(import.meta.dirname, '../skills/jterrazz-typescript/references/rules.md'),
+        render: renderReference,
+    },
+};
+
+/** A markdown table as its cells, with the alignment padding taken out. */
+function cells(table: string): string[] {
+    return table
+        .trim()
+        .split('\n')
+        .map((row) =>
+            row
+                .split('|')
+                .map((cell) => cell.trim().replaceAll(/^-+$/gu, '---'))
+                .join(' | '),
+        );
+}
+
+test('every decision carries the version it was taken in', () => {
+    // Given - the whole catalogue
+    const entries = catalog();
+    expect(entries.length).toBeGreaterThan(500);
+
+    // Then - each one names a semver, which is what replaces a changelog here
+    for (const entry of entries) {
+        expect.soft(entry.since, `${entry.rule} has no since`).toMatch(/^\d+\.\d+\.\d+$/u);
+    }
+});
+
+test.each(Object.entries(PROJECTIONS))(
+    'the %s carries the catalogue the manifest renders',
+    (_name, { page, render: project }) => {
+        // Given - the generated section of the projection
+        const before = readFileSync(page, 'utf8');
+        const start = before.indexOf(MARKERS.start);
+        const end = before.indexOf(MARKERS.end);
+        expect(start, 'the page has lost its GENERATED marker').toBeGreaterThan(-1);
+        expect(end, 'the page has lost its /GENERATED marker').toBeGreaterThan(start);
+
+        // Then - it is exactly what the manifest renders today
+        const table = project();
+        if (process.env.TEST_UPDATE === '1') {
+            const head = before.slice(0, start + MARKERS.start.length);
+            writeFileSync(page, `${head}\n\n${table}\n\n${before.slice(end)}`);
+        }
+
+        /*
+         * The comparison is column-insensitive on purpose: oxfmt owns markdown
+         * and it aligns a table's pipes. What a projection must carry is the
+         * DECISIONS.
+         */
+        const fresh = readFileSync(page, 'utf8');
+        const carried = fresh.slice(
+            fresh.indexOf(MARKERS.start) + MARKERS.start.length,
+            fresh.indexOf(MARKERS.end),
+        );
+        expect(cells(carried)).toStrictEqual(cells(table));
+    },
+);

package/rules/compile.js

@@ -0,0 +1,125 @@
+/*
+ * Fragment -> oxlint config. The compiler is the only place a rule level is
+ * spelled, and it never emits `categories`: a category switch arms rules of
+ * plugins the config never names, inert until a framework config activates the
+ * plugin and then firing unannounced. Every rule of this package is decided by
+ * name ([Lint presets](../docs/07-lint-presets.md)).
+ */
+
+/** The linter options every profile ships: type information on, dead directives refused. */
+export const OPTIONS = Object.freeze({
+    reportUnusedDisableDirectives: 'error',
+    typeAware: true,
+});
+
+/** Config keys concatenated across configs, duplicates dropped (===). */
+const CONCAT_DEDUPE = new Set(['extends', 'ignorePatterns', 'jsPlugins', 'plugins']);
+/** Config keys concatenated verbatim — order matters, no dedupe. */
+const CONCAT = new Set(['overrides']);
+/** Config keys shallow-merged as objects — the LAST config wins per key. */
+const SHALLOW_MERGE = new Set(['env', 'globals', 'options', 'rules', 'settings']);
+
+/** One fragment as the plain oxlint config object oxlint itself reads. */
+export function compile(fragment) {
+    const config = { rules: rulesOf(fragment.decisions) };
+
+    if (fragment.plugins.length > 0) {
+        config.plugins = [...fragment.plugins];
+    }
+    if (fragment.jsPlugins.length > 0) {
+        config.jsPlugins = [...fragment.jsPlugins];
+    }
+    if (fragment.ignorePatterns.length > 0) {
+        config.ignorePatterns = [...fragment.ignorePatterns];
+    }
+    if (fragment.overrides.length > 0) {
+        config.overrides = fragment.overrides.map((override) => ({
+            files: [...override.files],
+            rules: rulesOf(override.decisions),
+        }));
+    }
+    if (fragment.settings) {
+        config.settings = fragment.settings;
+    }
+    if (fragment.options) {
+        config.options = fragment.options;
+    }
+    if (fragment.env) {
+        config.env = fragment.env;
+    }
+    if (fragment.globals) {
+        config.globals = fragment.globals;
+    }
+
+    return config;
+}
+
+/**
+ * Deterministic merge of oxlint config objects, left to right:
+ * `jsPlugins` / `plugins` / `ignorePatterns` / `extends` concatenated and
+ * deduped, `rules` / `env` / `globals` / `options` / `settings` shallow-merged
+ * with last-wins per key, `overrides` concatenated, any other key taken from
+ * the last config that sets it.
+ */
+export function merge(...configs) {
+    const merged = {};
+    for (const config of configs) {
+        if (!config || typeof config !== 'object') {
+            continue;
+        }
+        for (const [key, value] of Object.entries(config)) {
+            if (value !== undefined) {
+                merged[key] = mergeKey(key, merged[key], value);
+            }
+        }
+    }
+    return merged;
+}
+
+/** How one key merges: the three tables above, then last-wins. */
+function mergeKey(key, previous, value) {
+    if (CONCAT_DEDUPE.has(key)) {
+        const combined = [...asArray(previous), ...asArray(value)];
+        return combined.filter((entry, index) => combined.indexOf(entry) === index);
+    }
+    if (CONCAT.has(key)) {
+        return [...asArray(previous), ...asArray(value)];
+    }
+    if (SHALLOW_MERGE.has(key)) {
+        return { ...previous, ...value };
+    }
+    return value;
+}
+
+function asArray(value) {
+    if (value === undefined) {
+        return [];
+    }
+    return Array.isArray(value) ? value : [value];
+}
+
+/** A profile: fragments compiled, merged, and given the linter options. */
+export function profile({ fragments, env, globals, ignorePatterns = [] }) {
+    return merge(...fragments.map((one) => compile(one)), {
+        env,
+        globals,
+        ignorePatterns,
+        options: { ...OPTIONS },
+    });
+}
+
+function rulesOf(decisions) {
+    const rules = {};
+    for (const [rule, decision] of Object.entries(decisions)) {
+        if (decision.level === 'off') {
+            rules[rule] = 'off';
+        } else if (decision.options === undefined) {
+            rules[rule] = 'error';
+        } else if (Array.isArray(decision.options)) {
+            rules[rule] = ['error', ...decision.options];
+        } else {
+            rules[rule] = ['error', decision.options];
+        }
+    }
+    return rules;
+}

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,107 @@
+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` and `rules/react-native.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. */
+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',
+                'unambiguous',
+            ].map((rule) => `import/${rule}`),
+        ),
+
+        // -- On, at the strictest value the option carries ---------------------
+        'import/consistent-type-specifier-style': on(['prefer-inline']),
+        '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',
+        }),
+    },
+});

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',
+        }),
+    },
+});