@jterrazz/typescript 9.3.0 → 10.1.0

package/presets/tsconfig/expo.json

@@ -1,23 +1,33 @@
 {
     "display": "Expo",
     "include": ["${configDir}/**/*.ts", "${configDir}/**/*.tsx"],
-    "exclude": ["${configDir}/node_modules"],
-
+    "exclude": [
+        "${configDir}/node_modules",
+        "${configDir}/**/_fixtures",
+        "${configDir}/**/_expected"
+    ],
     "compilerOptions": {
         "allowJs": true,
-        "baseUrl": ".",
         "esModuleInterop": true,
+        "exactOptionalPropertyTypes": true,
         "incremental": true,
         "jsx": "react-native",
         "lib": ["DOM", "ESNext"],
-        "moduleResolution": "node",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
         "noEmit": true,
+        "noFallthroughCasesInSwitch": true,
+        "noImplicitOverride": true,
+        "noUncheckedIndexedAccess": true,
+        "noUncheckedSideEffectImports": true,
         "paths": {
-            "@/*": ["src/*"]
+            "@/*": ["${configDir}/src/*"]
         },
         "resolveJsonModule": true,
         "skipLibCheck": true,
+        "strict": true,
         "target": "ESNext",
-        "tsBuildInfoFile": "${configDir}/.artifacts/tsc/tsconfig.tsbuildinfo"
+        "tsBuildInfoFile": "${configDir}/.artifacts/tsc/tsconfig.tsbuildinfo",
+        "verbatimModuleSyntax": true
     }
 }

package/presets/tsconfig/library.json

@@ -0,0 +1,17 @@
+{
+    "display": "Library (ESM, declaration-emitting)",
+    "extends": "./node.json",
+    "compilerOptions": {
+        "allowJs": false,
+        "declaration": true,
+        "erasableSyntaxOnly": true
+    },
+    "include": ["${configDir}/**/*.ts"],
+    "exclude": [
+        "${configDir}/node_modules",
+        "${configDir}/dist",
+        "${configDir}/.artifacts",
+        "${configDir}/**/_fixtures",
+        "${configDir}/**/_expected"
+    ]
+}

package/presets/tsconfig/next.json

@@ -18,7 +18,13 @@
             {
                 "name": "next"
             }
-        ]
+        ],
+        "exactOptionalPropertyTypes": true,
+        "noFallthroughCasesInSwitch": true,
+        "noImplicitOverride": true,
+        "noUncheckedIndexedAccess": true,
+        "noUncheckedSideEffectImports": true,
+        "verbatimModuleSyntax": true
     },
     "include": [
         "${configDir}/next-env.d.ts",
@@ -27,5 +33,9 @@
         "${configDir}/**/*.ts",
         "${configDir}/**/*.tsx"
     ],
-    "exclude": ["${configDir}/node_modules"]
+    "exclude": [
+        "${configDir}/node_modules",
+        "${configDir}/**/_fixtures",
+        "${configDir}/**/_expected"
+    ]
 }

package/presets/tsconfig/node.json

@@ -1,19 +1,33 @@
 {
     "display": "Node ESM",
-    "include": ["${configDir}/**/*.ts"],
-    "exclude": ["${configDir}/node_modules"],
-
+    "include": ["${configDir}/**/*.ts", "${configDir}/**/*.js"],
+    "exclude": [
+        "${configDir}/node_modules",
+        "${configDir}/dist",
+        "${configDir}/.artifacts",
+        "${configDir}/**/_fixtures",
+        "${configDir}/**/_expected"
+    ],
     "compilerOptions": {
         "moduleResolution": "Bundler",
         "module": "ESNext",
         "target": "ESNext",
         "types": ["node"],
         "strict": true,
+        "exactOptionalPropertyTypes": true,
+        "noFallthroughCasesInSwitch": true,
+        "noImplicitOverride": true,
+        "noUncheckedIndexedAccess": true,
+        "noUncheckedSideEffectImports": true,
+        "verbatimModuleSyntax": true,
         "incremental": true,
         "tsBuildInfoFile": "${configDir}/.artifacts/tsc/tsconfig.tsbuildinfo",
         "experimentalDecorators": true,
         "esModuleInterop": true,
         "resolveJsonModule": true,
-        "skipLibCheck": true
+        "skipLibCheck": true,
+        "allowJs": true,
+        "checkJs": false,
+        "noEmit": true
     }
 }

package/presets/tsconfig/react.json

@@ -0,0 +1,33 @@
+{
+    "display": "React (bundled, no framework)",
+    "include": ["${configDir}/**/*.ts", "${configDir}/**/*.tsx"],
+    "exclude": [
+        "${configDir}/node_modules",
+        "${configDir}/dist",
+        "${configDir}/.artifacts",
+        "${configDir}/**/_fixtures",
+        "${configDir}/**/_expected"
+    ],
+    "compilerOptions": {
+        "allowJs": true,
+        "esModuleInterop": true,
+        "exactOptionalPropertyTypes": true,
+        "incremental": true,
+        "isolatedModules": true,
+        "jsx": "react-jsx",
+        "lib": ["DOM", "DOM.Iterable", "ESNext"],
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "noEmit": true,
+        "noFallthroughCasesInSwitch": true,
+        "noImplicitOverride": true,
+        "noUncheckedIndexedAccess": true,
+        "noUncheckedSideEffectImports": true,
+        "resolveJsonModule": true,
+        "skipLibCheck": true,
+        "strict": true,
+        "target": "ESNext",
+        "tsBuildInfoFile": "${configDir}/.artifacts/tsc/tsconfig.tsbuildinfo",
+        "verbatimModuleSyntax": true
+    }
+}

package/presets/tsdown/build.d.ts

@@ -0,0 +1,13 @@
+/*
+ * The shape of a bundler config is tsdown's own fact, so this declaration does
+ * not restate it: `UserConfig` is re-exported from the tool, for a consumer
+ * that annotates its own config ([Developing](../../docs/02-developing.md)).
+ */
+
+import type { UserConfig } from 'tsdown';
+
+/** An application build: one ESM output with declarations and source maps. */
+declare const build: UserConfig;
+
+export { type UserConfig } from 'tsdown';
+export default build;

package/presets/tsdown/bundle.d.ts

@@ -0,0 +1,13 @@
+/*
+ * The shape of a bundler config is tsdown's own fact, so this declaration does
+ * not restate it: `UserConfig` is re-exported from the tool, for a consumer
+ * that annotates its own config ([Developing](../../docs/02-developing.md)).
+ */
+
+import type { UserConfig } from 'tsdown';
+
+/** A library bundle: ESM and CJS outputs with declarations and source maps. */
+declare const bundle: UserConfig;
+
+export { type UserConfig } from 'tsdown';
+export default bundle;

package/presets/tsdown/bundle.js

@@ -3,7 +3,16 @@ import { defineConfig } from 'tsdown';
 export default defineConfig({
     entry: ['src/index.ts'],
     format: ['esm', 'cjs'],
-    dts: true,
+    /*
+     * `isolatedDeclarations` lives here, not in the `library` tsconfig preset:
+     * what it buys is a declaration emitted without a type-checker, which is a
+     * property of the PUBLISHED artefact and of nothing else. In the tsconfig
+     * it also reached every spec file, where it refused the destructured
+     * export a specification hands back ([Developing](../../docs/02-developing.md)).
+     * `bundle` is the library command, so the guarantee sits exactly where the
+     * tsconfig preset used to put it — and nowhere wider.
+     */
+    dts: { compilerOptions: { isolatedDeclarations: true } },
     sourcemap: true,
     clean: true,
     hash: false,

package/rules/README.md

@@ -0,0 +1,23 @@
+# `rules/` — the manifest
+
+One nature lives here: a DECISION about a lint rule. Never a config object, never a path, never a tool invocation — those are `presets/`'s and `bin/`'s. What the decisions mean, and the four laws they answer to, is [Lint presets](../docs/07-lint-presets.md); this page only says where each thing is.
+
+| File                                                                               | Holds                                                                                                                                                                                                      |
+| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `_contract.js`                                                                     | `fragment()`, `on()`, `typeAware()`, `off()`, `unsafeFix()`, `scoped()` — and the load-time refusal of a level that is not `error`/`off`, of an `off` with no reason and of an unsafe fixer with no reason |
+| `compile.js`                                                                       | fragment → plain oxlint config, and the deterministic merge behind `compose()`. It never emits `categories`                                                                                                |
+| `profiles.js`                                                                      | which fragments each of the seven profiles carries, and what none of them lints                                                                                                                            |
+| `catalog.js`                                                                       | every decision as one list, and the markdown the chapter carries between its `GENERATED` markers                                                                                                           |
+| `core/`                                                                            | one file per plugin of the rulebook every profile holds: `eslint`, `typescript`, `unicorn`, `oxc`, `import`, `promise`, `node`, `jsdoc`                                                                    |
+| `react.js` · `a11y.js` · `next.js` · `react-native.js` · `astro.js` · `bundler.js` | what a framework profile adds to that rulebook, and what a bundled tree with no framework still owes                                                                                                       |
+| `vitest.js`                                                                        | the test-file rules, as an `overrides` block — they read a test and say nothing about anything else                                                                                                        |
+| `sorted.js`                                                                        | perfectionist: only what oxfmt does not sort                                                                                                                                                               |
+| `architecture/`                                                                    | `layers.js` turns a declared layer map into `no-restricted-imports` overrides; `hexagonal.js` is the map this package ships                                                                                |
+
+A fragment is loaded, not read: importing one runs its contract, so a decision that breaks an invariant fails at import time rather than at review time.
+
+## What proves it
+
+- `_contract.test.ts` — the invariants, and the compile of a fragment.
+- `catalog.test.ts` — the chapter is the manifest's projection, and nothing else.
+- `specs/cli/preset/` — the resolved rule set, the plugin coverage, the fixpoint against the formatter, the behaviour of each decision, and the exclusive pairs.

package/rules/_contract.js

@@ -0,0 +1,207 @@
+/*
+ * The rulebook's contract: a FRAGMENT is a set of decisions, one per rule of
+ * one plugin, and nothing else. `compile.js` turns a fragment into the oxlint
+ * config object a profile ships.
+ *
+ *     import { fragment, off, on } from '../_contract.js';
+ *
+ *     export default fragment({
+ *         id: 'core/promise',
+ *         plugins: ['promise'],
+ *         since: '10.0.0',
+ *         rules: {
+ *             'promise/no-nesting': on(),
+ *             'promise/always-return': off({ kind: 'exclusive', by: 'promise/prefer-await-to-then' }),
+ *         },
+ *     });
+ *
+ * Two invariants the whole package rests on: a decision is `error` or `off`,
+ * never `warn`; and an `off` carries exactly one recorded reason.
+ */
+
+/**
+ * @typedef {object} Reason Why a rule is off.
+ * @property {string} kind One of `REASON_KINDS`.
+ * @property {string} by The rule, page or measurement that carries it.
+ *
+ * @typedef {object} Decision What the rulebook says about one rule.
+ * @property {string} rule The oxlint rule id.
+ * @property {'error' | 'off'} level There is no third level.
+ * @property {unknown} [options] The rule's options, at their decided value.
+ * @property {Reason} [reason] Present on every `off`, absent on every `on`.
+ * @property {boolean} [typeAware] Whether the rule needs type information.
+ * @property {'unsafe'} [fixer] Present when the rule's own fixer changes meaning.
+ * @property {string} [fixerReason] What that rewrite changes — measured, one clause.
+ * @property {string} since The version the decision was taken in.
+ *
+ * @typedef {object} Scoped An `overrides` block, stated in decisions.
+ * @property {readonly string[]} files The globs it applies to.
+ * @property {Readonly<Record<string, Decision>>} decisions What it says there.
+ */
+
+/** The version this rulebook was born in — the default `since` of every decision. */
+export const SINCE = '10.0.0';
+
+/** The five reasons an `off` may carry. Anything else is refused at load time. */
+export const REASON_KINDS = Object.freeze([
+    /** Fights oxfmt — proved by the fixpoint suite. */
+    'formatter',
+    /** Mutually exclusive with a rule that is on — the rule is named. */
+    'exclusive',
+    /** Refuses a convention the estate holds — the page is named. */
+    'convention',
+    /** Measured false-positive rate on real estate code — the measurement is cited. */
+    'evidence',
+    /** Covered by TypeScript itself, or by a stronger rule that is on — it is named. */
+    'covered',
+]);
+
+/**
+ * A rule that is on. Every rule of the rulebook is on at `error`; the optional
+ * argument is the rule's options, at their strictest sensible value.
+ */
+export function on(options) {
+    return Object.freeze({ level: 'error', options });
+}
+
+/**
+ * Every named rule, on at `error` with its default options — the bulk of a
+ * fragment, where the rule id IS the whole decision.
+ */
+export function allOn(rules) {
+    return Object.fromEntries(rules.map((rule) => [rule, on()]));
+}
+
+/**
+ * A rule that is off, and why. `reason` is `{ kind, by }` where `kind` is one
+ * of `REASON_KINDS` and `by` names the rule, page or measurement that carries
+ * the decision. "Too strict" is not a reason.
+ */
+export function off(reason, since) {
+    assertReason(reason);
+    return Object.freeze({ level: 'off', reason: Object.freeze({ ...reason }), since });
+}
+
+/**
+ * A decision whose FIXER changes meaning. The rule stays on — `check` reports
+ * it and a human answers it — but `fix` never applies the rewrite: the eight
+ * marked here have each been measured turning working code into code that
+ * does not compile, or into code that claims something else
+ * ([Lint presets](../docs/07-lint-presets.md)).
+ */
+export function unsafeFix(decision, why) {
+    if (typeof why !== 'string' || why.length === 0) {
+        throw new TypeError('An unsafe fixer must say what its rewrite changes.');
+    }
+    return Object.freeze({ ...decision, fixer: 'unsafe', fixerReason: why });
+}
+
+/**
+ * A rule that is on and needs type information — `oxlint --type-aware`, which
+ * every profile of this package turns on. The mark is what the catalogue reads.
+ */
+export function typeAware(options) {
+    return Object.freeze({ level: 'error', options, typeAware: true });
+}
+
+/**
+ * Declare a fragment: one plugin's decisions, or one framework's. `rules` maps
+ * an oxlint rule id to an `on()` / `typeAware()` / `off()` decision, and every
+ * decision inherits the fragment's `since` unless it carries its own.
+ */
+export function fragment(definition) {
+    const {
+        id,
+        plugins = [],
+        jsPlugins = [],
+        rules = {},
+        overrides = [],
+        settings,
+        options,
+        ignorePatterns = [],
+        env,
+        globals,
+        since = SINCE,
+    } = definition;
+
+    if (typeof id !== 'string' || id.length === 0) {
+        throw new TypeError('A fragment needs an id.');
+    }
+
+    /** @type {Record<string, Decision>} */
+    const decisions = {};
+    for (const [rule, decision] of Object.entries(rules)) {
+        decisions[rule] = normalise(id, rule, decision, since);
+    }
+
+    return Object.freeze({
+        decisions: Object.freeze(decisions),
+        env,
+        globals,
+        id,
+        ignorePatterns: Object.freeze([...ignorePatterns]),
+        jsPlugins: Object.freeze([...jsPlugins]),
+        options,
+        overrides: Object.freeze([...overrides]),
+        plugins: Object.freeze([...plugins]),
+        settings,
+        since,
+    });
+}
+
+/** Every decision of every fragment, keyed by rule id, fragments merged left to right. */
+export function decisionsOf(...fragments) {
+    const merged = {};
+    for (const one of fragments) {
+        for (const [rule, decision] of Object.entries(one.decisions)) {
+            merged[rule] = { ...decision, fragment: one.id };
+        }
+        for (const override of one.overrides) {
+            for (const [rule, decision] of Object.entries(override.decisions ?? {})) {
+                merged[rule] = { ...decision, fragment: one.id, scoped: override.files };
+            }
+        }
+    }
+    return merged;
+}
+
+/**
+ * An `overrides` block, stated in decisions like a fragment's own body. Its
+ * rule options REPLACE the base entry — they never merge — so a block states
+ * the complete option list for every rule it names.
+ */
+export function scoped({ files, rules, since = SINCE }) {
+    /** @type {Record<string, Decision>} */
+    const decisions = {};
+    for (const [rule, decision] of Object.entries(rules)) {
+        decisions[rule] = normalise(files.join(','), rule, decision, since);
+    }
+    return Object.freeze({ decisions: Object.freeze(decisions), files: Object.freeze([...files]) });
+}
+
+function assertReason(reason) {
+    if (!reason || typeof reason !== 'object') {
+        throw new TypeError('An off decision needs a reason.');
+    }
+    if (!REASON_KINDS.includes(reason.kind)) {
+        throw new TypeError(`Unknown reason kind "${reason.kind}".`);
+    }
+    if (typeof reason.by !== 'string' || reason.by.length === 0) {
+        throw new TypeError(`A "${reason.kind}" reason must name what carries it.`);
+    }
+}
+
+function normalise(owner, rule, decision, since) {
+    if (!decision || typeof decision !== 'object' || typeof decision.level !== 'string') {
+        throw new TypeError(
+            `${owner}: "${rule}" is not a decision — use on(), typeAware() or off().`,
+        );
+    }
+    if (decision.level !== 'error' && decision.level !== 'off') {
+        throw new TypeError(`${owner}: "${rule}" is "${decision.level}" — a rule is error or off.`);
+    }
+    if (decision.level === 'off') {
+        assertReason(decision.reason);
+    }
+    return Object.freeze({ ...decision, rule, since: decision.since ?? since });
+}

package/rules/_contract.test.ts

@@ -0,0 +1,81 @@
+import { expect, test } from 'vitest';
+
+import { fragment, off, on, REASON_KINDS, typeAware } from './_contract.js';
+import { compile } from './compile.js';
+
+/*
+ * The two invariants every fragment of the rulebook rests on: a decision is
+ * `error` or `off` and never `warn`, and an `off` carries exactly one of the
+ * five recorded reasons. Both are enforced at LOAD time, so a fragment that
+ * breaks one cannot be imported at all.
+ */
+
+const REASON = { by: 'oxfmt sortImports', kind: 'covered' } as const;
+
+test('refuses an off with no reason', () => {
+    // Given - a decision turned off on nobody's authority
+    // Then - the contract refuses it before any config is built
+    expect(() => off()).toThrow(/needs a reason/u);
+});
+
+test('refuses a reason whose kind is not one of the five', () => {
+    // Given - a reason invented on the spot
+    // Then - the contract names the five and refuses the sixth
+    expect(() => off({ by: 'taste', kind: 'too-strict' })).toThrow(/Unknown reason kind/u);
+    expect(REASON_KINDS).toHaveLength(5);
+});
+
+test('refuses a reason that names nothing', () => {
+    // Given - a kind with no rule, page or measurement behind it
+    // Then - "covered" has to say by what
+    expect(() => off({ by: '', kind: 'covered' })).toThrow(/must name what carries it/u);
+});
+
+/** A fragment reaching for the warning tier this rulebook does not have. */
+function buildWarningFragment() {
+    return fragment({ id: 'probe', rules: { curly: { level: 'warn' } } });
+}
+
+test('refuses a level that is neither error nor off', () => {
+    // Given - a fragment reaching for a warning tier
+    // Then - there is no warn in this rulebook
+    expect(buildWarningFragment).toThrow(/a rule is error or off/u);
+});
+
+test('gives every decision the fragment version, unless it carries its own', () => {
+    // Given - a fragment born in one version with one decision taken later
+    const probe = fragment({
+        id: 'probe',
+        rules: { curly: on(), 'no-var': off(REASON, '10.2.0') },
+        since: '10.0.0',
+    });
+
+    // Then - each decision states when it was taken
+    expect(probe.decisions.curly?.since).toBe('10.0.0');
+    expect(probe.decisions['no-var']?.since).toBe('10.2.0');
+});
+
+test('compiles a fragment to a plain oxlint config, and never to a category', () => {
+    // Given - a fragment with an option, a type-aware rule and an off
+    const probe = fragment({
+        id: 'probe',
+        plugins: ['typescript'],
+        rules: {
+            curly: on(),
+            'max-depth': on([4]),
+            'no-var': off(REASON),
+            'typescript/await-thenable': typeAware(),
+        },
+    });
+
+    // Then - the config states every level by name
+    expect(compile(probe)).toStrictEqual({
+        plugins: ['typescript'],
+        rules: {
+            curly: 'error',
+            'max-depth': ['error', 4],
+            'no-var': 'off',
+            'typescript/await-thenable': 'error',
+        },
+    });
+});

package/rules/a11y.js

@@ -0,0 +1,51 @@
+import { allOn, fragment } from './_contract.js';
+
+/*
+ * The `jsx-a11y` plugin, all 36 rules on. There is no off here and no reason
+ * to record: an accessibility rule describes what a person using the product
+ * can reach, and the estate has no profile that may decide otherwise.
+ */
+export default fragment({
+    id: 'a11y',
+    plugins: ['jsx-a11y'],
+    rules: allOn(
+        [
+            'alt-text',
+            'anchor-ambiguous-text',
+            'anchor-has-content',
+            'anchor-is-valid',
+            'aria-activedescendant-has-tabindex',
+            'aria-props',
+            'aria-proptypes',
+            'aria-role',
+            'aria-unsupported-elements',
+            'autocomplete-valid',
+            'click-events-have-key-events',
+            'control-has-associated-label',
+            'heading-has-content',
+            'html-has-lang',
+            'iframe-has-title',
+            'img-redundant-alt',
+            'interactive-supports-focus',
+            'label-has-associated-control',
+            'lang',
+            'media-has-caption',
+            'mouse-events-have-key-events',
+            'no-access-key',
+            'no-aria-hidden-on-focusable',
+            'no-autofocus',
+            'no-distracting-elements',
+            'no-interactive-element-to-noninteractive-role',
+            'no-noninteractive-element-interactions',
+            'no-noninteractive-element-to-interactive-role',
+            'no-noninteractive-tabindex',
+            'no-redundant-roles',
+            'no-static-element-interactions',
+            'prefer-tag-over-role',
+            'role-has-required-aria-props',
+            'role-supports-aria-props',
+            'scope',
+            'tabindex-no-positive',
+        ].map((rule) => `jsx-a11y/${rule}`),
+    ),
+});

package/rules/architecture/hexagonal.js

@@ -0,0 +1,56 @@
+import { layers } from './layers.js';
+
+/*
+ * The hexagonal map: the six boundaries this package has enforced since v6,
+ * restated as a layer map. The dependency arrow points inward — the domain
+ * knows nothing, the application knows the domain, everything else knows the
+ * application.
+ */
+export const HEXAGONAL_MAP = Object.freeze([
+    {
+        deny: [
+            '**/application/**',
+            '**/infrastructure/**',
+            '**/presentation/**',
+            '**/di/**',
+            '**/config/**',
+            '**/generated/**',
+        ],
+        files: ['**/domain/**'],
+        message: 'the domain layer is pure — it imports no other layer',
+        name: 'domain',
+    },
+    {
+        deny: ['**/infrastructure/**', '**/presentation/**', '**/di/**'],
+        files: ['**/application/use-cases/**'],
+        message: 'a use case depends on the domain and on ports, never on an implementation',
+        name: 'application/use-cases',
+    },
+    {
+        deny: ['**/infrastructure/**', '**/presentation/**', '**/di/**'],
+        files: ['**/application/ports/**'],
+        message: 'a port is an interface — it cannot depend on what implements it',
+        name: 'application/ports',
+    },
+    {
+        deny: ['**/infrastructure/outbound/**'],
+        files: ['**/infrastructure/inbound/**'],
+        message: 'an inbound adapter reaches an outbound one through injection, not by import',
+        name: 'infrastructure/inbound',
+    },
+    {
+        deny: ['**/navigation/**'],
+        files: ['**/presentation/ui/atoms/**', '**/presentation/ui/molecules/**'],
+        message: 'an atom and a molecule are pure — navigation is a feature concern',
+        name: 'presentation/ui',
+    },
+    {
+        allow: ['**/presentation/features/common/**'],
+        deny: ['**/presentation/features/**'],
+        files: ['**/presentation/features/**'],
+        message: 'a feature is independent — shared code lives in features/common',
+        name: 'presentation/features',
+    },
+]);
+
+export default layers({ id: 'architecture/hexagonal', map: HEXAGONAL_MAP });