@jterrazz/typescript 9.3.0 → 10.1.0

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,56 @@
+import { fragment, off, on, scoped } from './_contract.js';
+import { ASSETS } 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: {
+        /*
+         * `never`, with two extensions that stay: an asset, which Vite resolves
+         * BY its extension, and `.astro` itself — Astro's `resolve.extensions`
+         * does not carry it, so a layout imported without it fails the build.
+         * An override's options REPLACE the base entry, so the whole list is
+         * restated here.
+         */
+        'import/extensions': on(['never', { ...ASSETS, astro: 'always' }]),
+        '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/bundler.js

@@ -0,0 +1,19 @@
+import { fragment } from './_contract.js';
+import { EXTENSIONS_NEVER } from './core/import.js';
+
+/*
+ * A bundled tree with no framework behind it — Vite, Remotion, a browser
+ * extension. oxlint has no plugin to load for one, so this fragment carries a
+ * single decision: the bundler resolves the specifier, so an import carries no
+ * extension.
+ *
+ * `rules/next.js`, `rules/astro.js` and `rules/react-native.js` each state the
+ * same decision inside their own framework fragment, where it sits beside that
+ * framework's plugin. A profile with no framework fragment states it here.
+ */
+export default fragment({
+    id: 'bundler',
+    rules: {
+        'import/extensions': EXTENSIONS_NEVER,
+    },
+});

package/rules/catalog.js

@@ -0,0 +1,166 @@
+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 -->',
+});
+
+/** The fence that bounds the list of fixers `fix` refuses to run. */
+export const FIXER_MARKERS = Object.freeze({
+    end: '<!-- /GENERATED:fixers -->',
+    start: '<!-- GENERATED:fixers -->',
+});
+
+/** 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(', ')}`;
+}
+
+/**
+ * Every rule whose own fixer changes meaning, with what the rewrite does.
+ * `check` reports them and a human answers them; `fix` runs with each one
+ * allowed, so the rewrite is never applied
+ * ([Quality checks](../docs/06-quality-checks.md)).
+ */
+export function unsafeFixers() {
+    const seen = new Map();
+    for (const entry of catalog()) {
+        if (entry.fixer === 'unsafe' && !seen.has(entry.rule)) {
+            seen.set(entry.rule, entry.fixerReason);
+        }
+    }
+
+    return [...seen.entries()]
+        .map(([rule, why]) => ({ rule, why }))
+        .toSorted((left, right) => left.rule.localeCompare(right.rule));
+}
+
+/** The same list as the markdown the chapter carries between its fixer markers. */
+export function renderFixers() {
+    return unsafeFixers()
+        .map(({ rule, why }) => `- \`${rule}\` — ${why}`)
+        .join('\n');
+}

package/rules/catalog.test.ts

@@ -0,0 +1,98 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { expect, test } from 'vitest';
+
+import {
+    catalog,
+    FIXER_MARKERS,
+    MARKERS,
+    render,
+    renderFixers,
+    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: {
+        markers: MARKERS,
+        page: resolve(import.meta.dirname, '../docs/07-lint-presets.md'),
+        render,
+    },
+    'fixer list': {
+        markers: FIXER_MARKERS,
+        page: resolve(import.meta.dirname, '../docs/07-lint-presets.md'),
+        render: renderFixers,
+    },
+    'skill reference': {
+        markers: MARKERS,
+        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, { markers, 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;
+}