@jterrazz/typescript 9.3.0 → 10.0.0

package/rules/_contract.js

@@ -0,0 +1,191 @@
+/*
+ * 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 {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 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 });

package/rules/architecture/layers.js

@@ -0,0 +1,75 @@
+import { fragment, on, scoped } from '../_contract.js';
+
+/*
+ * A layer map, compiled to `no-restricted-imports` overrides — one per layer,
+ * each carrying that layer's COMPLETE pattern list.
+ *
+ * Two oxlint semantics shape every line of this file, both verified against
+ * 1.83 and both permanent:
+ *
+ *   - An override's rule OPTIONS REPLACE the base entry; they never merge
+ *     (oxc#17527). So a layer's override states every pattern that layer is
+ *     bound by, and nothing about layering is left in the base config.
+ *   - The `regex` matcher is Rust regex, which has no lookahead. An exception
+ *     like "features may not import features, except common" is two `group`
+ *     globs — the deny glob, then the same glob negated with `!`.
+ *
+ * And one limit worth stating: `no-restricted-imports` matches the SPECIFIER
+ * STRING, never a resolved path. `../beta/thing.js` does not carry the layer
+ * name, so it passes. A layer map is a textual boundary, and a repository that
+ * needs a graph boundary declares a dependency-cruiser map beside it.
+ */
+
+/**
+ * Build a fragment from a layer map. Each layer is
+ * `{ name, files, deny, allow?, message }`: `files` are the globs that BELONG
+ * to the layer, `deny` the specifier globs it may not import, `allow` the
+ * exceptions carved out of them.
+ */
+export function layers({ id = 'layers', map }) {
+    assertDisjoint(id, map);
+
+    return fragment({
+        id,
+        overrides: map.map((layer) =>
+            scoped({
+                files: [...layer.files],
+                rules: {
+                    'no-restricted-imports': on([
+                        {
+                            patterns: [
+                                {
+                                    group: [
+                                        ...layer.deny,
+                                        ...(layer.allow ?? []).map((glob) => `!${glob}`),
+                                    ],
+                                    message: layer.message,
+                                },
+                            ],
+                        },
+                    ]),
+                },
+            }),
+        ),
+        rules: {},
+    });
+}
+
+/*
+ * One file belongs to one layer. Two layers sharing a `files` glob would each
+ * write an override for it, and the last one would silently erase the first —
+ * the replace semantics above. Refuse the map instead of shipping the hole.
+ */
+function assertDisjoint(id, map) {
+    const seen = new Map();
+    for (const layer of map) {
+        for (const glob of layer.files) {
+            if (seen.has(glob)) {
+                throw new TypeError(
+                    `${id}: "${glob}" belongs to both "${seen.get(glob)}" and "${layer.name}" — an override replaces, so one map entry would erase the other.`,
+                );
+            }
+            seen.set(glob, layer.name);
+        }
+    }
+}

package/rules/astro.js

@@ -0,0 +1,49 @@
+import { fragment, off, on, scoped } from './_contract.js';
+import { EXTENSIONS_NEVER } from './core/import.js';
+
+/*
+ * Astro. oxlint parses an `.astro` file's script body but not its frontmatter
+ * as a module, so the three decisions below are scoped to `*.astro` alone;
+ * everything else in an Astro tree is ordinary TypeScript under the core
+ * rulebook.
+ *
+ * The restricted imports are the boundary five checkouts hand-copied before
+ * this fragment existed: an Astro site is not a Next site, and reaching for
+ * Next's router or its intl package is the mistake that keeps being made.
+ */
+export default fragment({
+    id: 'astro',
+    ignorePatterns: ['.astro/**', 'assets/**', 'public/**'],
+    overrides: [
+        scoped({
+            files: ['**/*.astro'],
+            rules: {
+                'import/no-commonjs': on(),
+                'no-restricted-globals': on(['__dirname', '__filename']),
+                'unicorn/prefer-module': off({
+                    by: 'an .astro frontmatter block is not a module body, so the rule reads the file wrong',
+                    kind: 'convention',
+                }),
+            },
+        }),
+    ],
+    rules: {
+        'import/extensions': EXTENSIONS_NEVER,
+        'no-restricted-imports': on([
+            {
+                patterns: [
+                    {
+                        group: [
+                            'next',
+                            'next/*',
+                            'next-intl',
+                            'next-intl/*',
+                            '@jterrazz/manifest/next',
+                        ],
+                        message: 'this is an Astro site — the Next runtime is not on it',
+                    },
+                ],
+            },
+        ]),
+    },
+});

package/rules/catalog.js

@@ -0,0 +1,134 @@
+import { PROFILES } from './profiles.js';
+
+/**
+ * @typedef {object} Entry One decision, with the profiles that carry it.
+ * @property {string} rule The oxlint rule id.
+ * @property {'error' | 'off'} level What the rulebook says about it.
+ * @property {unknown} [options] The rule's options, at their decided value.
+ * @property {{ by: string, kind: string }} [reason] Why it is off.
+ * @property {boolean} [typeAware] Whether it needs type information.
+ * @property {readonly string[]} [scoped] The globs it applies to, when not all of them.
+ * @property {string} fragment The fragment that took the decision.
+ * @property {string} since The version the decision was taken in.
+ * @property {string[]} profiles The profiles that carry it.
+ */
+
+/*
+ * The catalogue: every decision of every profile, with the profiles that carry
+ * it. It is the one place the rulebook is readable as a list, and the GENERATED
+ * section of [Lint presets](../docs/07-lint-presets.md) is its projection —
+ * `rules/catalog.test.ts` fails a chapter that has drifted from it.
+ *
+ * Composition is last-wins per rule, so the catalogue resolves each profile
+ * first and groups after: `import/extensions` is `always` under node and
+ * `never` under the bundler profiles, and a reader is owed both lines, each
+ * naming only the profiles it is true for.
+ */
+
+/** The fence that bounds the generated section of the chapter. */
+export const MARKERS = Object.freeze({
+    end: '<!-- /GENERATED -->',
+    start: '<!-- GENERATED -->',
+});
+
+/** Every profile there is, so a decision carried by all of them says `all`. */
+const EVERY_PROFILE = Object.keys(PROFILES).length;
+
+/** Every decision, in rule order, one entry per distinct decision. */
+export function catalog() {
+    /** @type {Map<string, Entry>} */
+    const grouped = new Map();
+
+    for (const [name, definition] of Object.entries(PROFILES)) {
+        for (const [key, decision] of resolve(definition).entries()) {
+            const identity = `${key} @ ${decision.level} @ ${JSON.stringify(decision.options ?? null)}`;
+            const existing = grouped.get(identity);
+
+            if (existing === undefined) {
+                grouped.set(identity, { ...decision, profiles: [name] });
+            } else {
+                existing.profiles.push(name);
+            }
+        }
+    }
+
+    return [...grouped.values()].toSorted(
+        (left, right) =>
+            left.rule.localeCompare(right.rule) || left.fragment.localeCompare(right.fragment),
+    );
+}
+
+/** The catalogue as the markdown table the chapter carries between its markers. */
+export function render() {
+    const rows = catalog().map((entry) => {
+        const state = entry.level === 'off' ? 'off' : 'on';
+        const why =
+            entry.level === 'off' ? `${entry.reason.kind} — ${entry.reason.by}` : scopeOf(entry);
+        return `| \`${entry.rule}\` | ${entry.profiles.join(', ')} | ${state} | ${why} | ${entry.since} |`;
+    });
+
+    return [
+        '| Rule | Profiles | State | Reason | Since |',
+        '| --- | --- | --- | --- | --- |',
+        ...rows,
+    ].join('\n');
+}
+
+/**
+ * The same catalogue, trimmed for an agent: what the rule is, whether it runs,
+ * the reason in one clause, and where. No `since` column — an agent is reading
+ * to answer "may I write this", not "when was this decided", and the chapter
+ * carries that half.
+ */
+export function renderReference() {
+    const rows = catalog().map((entry) => {
+        const state = entry.level === 'off' ? 'off' : 'on';
+        const why = entry.level === 'off' ? reasonClause(entry.reason) : scopeOf(entry);
+        const where = entry.profiles.length === EVERY_PROFILE ? 'all' : entry.profiles.join(', ');
+
+        return `| \`${entry.rule}\` | ${state} | ${why} | ${where} |`;
+    });
+
+    return ['| Rule | State | Why | Profiles |', '| --- | --- | --- | --- |', ...rows].join('\n');
+}
+
+/** An `off` in one clause: its kind, and the first thing its reason names. */
+function reasonClause({ by, kind }) {
+    return `${kind}: ${by.split(' — ')[0]}`;
+}
+
+/** One profile's decisions, its fragments applied left to right, last wins per rule and scope. */
+function resolve(definition) {
+    /** @type {Map<string, Entry>} */
+    const decisions = new Map();
+
+    for (const fragment of definition.fragments) {
+        absorb(decisions, fragment, fragment.decisions);
+        for (const override of fragment.overrides) {
+            absorb(decisions, fragment, override.decisions, override.files);
+        }
+    }
+
+    return decisions;
+}
+
+function absorb(decisions, fragment, entries, scoped) {
+    const scope = scoped === undefined ? '' : scoped.join(',');
+
+    for (const [rule, decision] of Object.entries(entries)) {
+        decisions.set(`${rule} @ ${scope}`, {
+            ...decision,
+            fragment: fragment.id,
+            rule,
+            scoped,
+        });
+    }
+}
+
+/** What an `on` entry has to say for itself: where it applies, when that is not everywhere. */
+function scopeOf(entry) {
+    if (entry.scoped === undefined) {
+        return entry.typeAware === true ? 'type-aware' : '—';
+    }
+    return `scoped to ${entry.scoped.map((glob) => `\`${glob}\``).join(', ')}`;
+}