@jterrazz/typescript 9.3.0 → 10.1.0

package/lib/check-suppressions.js

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+
+/**
+ * Every place the project told a checker to look away.
+ *
+ * A suppression is a decision, and a decision the next reader cannot re-derive
+ * is a defect waiting to be re-introduced. Three rules hold the whole surface:
+ * it is spelled in the vocabulary of the tools this project actually runs, it
+ * carries the reason it was taken, and it names a rule that is still live.
+ *
+ * Usage: node check-suppressions.js [root] [--fix] [--oxlint <path>]
+ *        [--ignore-pattern <glob>]…
+ *
+ * `--fix` rewrites the two spellings a machine can settle: an
+ * `eslint-disable*` whose every named rule resolves becomes `oxlint-disable*`,
+ * and `@ts-ignore` becomes `@ts-expect-error`. It never invents a reason and it
+ * never deletes a directive — both of those are the author's judgement.
+ *
+ * One line per violation, `<rule>  <path>  <message>`. Exit code: 0 when every
+ * suppression is spelled, reasoned and live, 1 otherwise.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { argv, exit, stdout } from 'node:process';
+
+import { ignorePatternsOf, readText, trackedFiles } from './tracked-files.js';
+
+/** What a linter and a type-checker read — the files a directive can live in. */
+export const SOURCE = /\.(?:astro|[cm]?[jt]sx?|svelte|vue)$/u;
+
+/** The separator oxlint reads a directive's reason after. */
+const REASON = ' -- ';
+
+/**
+ * A directive is only a directive where a checker reads one: at the OPENING of
+ * a comment. Prose about a suppression, and a string carrying its spelling —
+ * this file is made of both — is not a suppression, and neither oxlint nor tsc
+ * would treat it as one.
+ */
+const COMMENT = String.raw`(?:\/\/|\/\*+|^\s*\*(?!\/))\s*`;
+
+/** A disable directive of either vocabulary, with its scope and its tail. */
+const DISABLE = new RegExp(
+    `${COMMENT}(?<tool>es|ox)lint-disable(?<scope>-next-line|-line)?(?<tail>[^\n*]*)`,
+    'gu',
+);
+
+/** The two TypeScript directives, with whatever description follows. */
+const TS_DIRECTIVE = new RegExp(`${COMMENT}@ts-(?<kind>expect-error|ignore)(?<tail>[^\n*]*)`, 'gu');
+
+/** Biome's, which no project of this toolchain runs. */
+const BIOME = new RegExp(`${COMMENT}biome-ignore\\b`, 'u');
+
+/** The rules a directive names: everything before the reason, comma-separated. */
+function rulesOf(tail) {
+    const named = tail.split(REASON)[0] ?? '';
+
+    return named
+        .replace(/\*\/\s*$/u, '')
+        .split(',')
+        .map((name) => name.trim())
+        .filter((name) => /^[\w-]+(?:\/[\w-]+)*$/u.test(name) && name !== '');
+}
+
+/** Whether the directive carries a reason after the separator oxlint reads. */
+const hasReason = (tail) => (tail.split(REASON)[1] ?? '').replace(/\*\/\s*$/u, '').trim() !== '';
+
+/**
+ * The rules oxlint resolved for this project, as `name -> level`, plus the
+ * plugin namespaces that map knows about. The map holds every rule the config
+ * DECIDED, which is not oxlint's whole catalogue: a rule missing from it is a
+ * rule this project does not run, which is the only question asked of it.
+ *
+ * A JS plugin's rules never appear in `--print-config`, so a directive naming
+ * one is unverifiable — and the gate says nothing rather than calling a live
+ * rule dead.
+ */
+function resolveConfig(root, oxlint) {
+    let printed;
+    try {
+        printed = execFileSync(oxlint, ['--print-config'], {
+            cwd: root,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+    } catch {
+        return null;
+    }
+
+    let rules;
+    try {
+        rules = JSON.parse(printed).rules ?? {};
+    } catch {
+        return null;
+    }
+
+    const namespaces = new Set();
+    for (const name of Object.keys(rules)) {
+        if (name.includes('/')) {
+            namespaces.add(name.split('/')[0]);
+        }
+    }
+
+    return { namespaces, rules };
+}
+
+/** Where a named rule stands for this project: `live`, `dead`, or `unverifiable`. */
+function standingOf(name, config) {
+    if (config === null) {
+        return 'unverifiable';
+    }
+
+    const namespace = name.includes('/') ? name.split('/')[0] : null;
+    if (namespace !== null && !config.namespaces.has(namespace)) {
+        /* A JS plugin's namespace: its rules are absent from --print-config. */
+        return 'unverifiable';
+    }
+
+    const bare = name.split('/').at(-1);
+    const level =
+        config.rules[name] ??
+        Object.entries(config.rules).find(([key]) => key.split('/').at(-1) === bare)?.[1];
+
+    return level === undefined || level === 'allow' ? 'dead' : 'live';
+}
+
+/** Every violation one line carries, and the line a `--fix` would leave behind. */
+function auditLine(line, number, config) {
+    const found = [];
+    let fixed = line;
+
+    for (const audit of [auditBiome, auditDisables, auditTypeScript]) {
+        const { fixed: rewritten, found: reported } = audit(fixed, number, config);
+        found.push(...reported);
+        fixed = rewritten;
+    }
+
+    return { fixed, found };
+}
+
+/** Biome's spelling, which no project of this toolchain runs and no fix rewrites. */
+function auditBiome(line, number) {
+    if (!BIOME.test(line)) {
+        return { fixed: line, found: [] };
+    }
+
+    return {
+        fixed: line,
+        found: [
+            {
+                message: `line ${number} spells a suppression for biome, which this toolchain never runs`,
+                rule: 'suppressions-spelling',
+            },
+        ],
+    };
+}
+
+/** The two linter vocabularies: the spelling, the reason, and the rules named. */
+function auditDisables(line, number, config) {
+    const found = [];
+    let fixed = line;
+
+    for (const match of line.matchAll(DISABLE)) {
+        const { scope = '', tail = '', tool } = match.groups;
+        const named = rulesOf(tail);
+
+        if (tool === 'es') {
+            /* A rewrite is only safe where the name it carries means something here. */
+            const settled = isRewritable(named, config);
+            if (settled) {
+                fixed = fixed.replace(`eslint-disable${scope}`, `oxlint-disable${scope}`);
+            }
+            found.push(eslintSpelling(number, named, settled));
+            continue;
+        }
+
+        found.push(...auditOxlintDirective(number, tail, named, config));
+    }
+
+    return { fixed, found };
+}
+
+/** Whether every rule an eslint directive names is one this project actually runs. */
+function isRewritable(named, config) {
+    return named.length > 0 && named.every((name) => standingOf(name, config) !== 'dead');
+}
+
+/** What an eslint spelling is told — which depends on whether a fix can settle it. */
+function eslintSpelling(number, named, settled) {
+    return {
+        message: settled
+            ? `line ${number} spells an eslint directive; this toolchain runs oxlint — 'typescript fix' rewrites it`
+            : `line ${number} spells an eslint directive naming ${named.join(', ') || 'no rule'}, which this project does not run — name an oxlint rule`,
+        rule: 'suppressions-spelling',
+    };
+}
+
+/** An oxlint directive: whether it carries its reason, and whether its rules are live. */
+function auditOxlintDirective(number, tail, named, config) {
+    const found = [];
+
+    if (!hasReason(tail)) {
+        found.push({
+            message: `line ${number} disables ${named.join(', ') || 'every rule'} with no '${REASON.trim()} reason' after it`,
+            rule: 'suppressions-reason',
+        });
+    }
+
+    for (const name of named) {
+        if (standingOf(name, config) === 'dead') {
+            found.push({
+                message: `line ${number} disables ${name}, which the resolved config does not have on`,
+                rule: 'suppressions-dead',
+            });
+        }
+    }
+
+    return found;
+}
+
+/** The two TypeScript directives: the spelling that stays silent, and the missing description. */
+function auditTypeScript(line, number) {
+    const found = [];
+    let fixed = line;
+
+    for (const match of line.matchAll(TS_DIRECTIVE)) {
+        const { kind, tail = '' } = match.groups;
+
+        if (kind === 'ignore') {
+            fixed = fixed.replace('@ts-ignore', '@ts-expect-error');
+            found.push({
+                message: `line ${number} spells @ts-ignore, which stays silent once the error is gone — @ts-expect-error does not`,
+                rule: 'suppressions-spelling',
+            });
+        }
+
+        if (tail.replace(/\*\/\s*$/u, '').trim() === '') {
+            found.push({
+                message: `line ${number} carries a TypeScript suppression with no description of what it is for`,
+                rule: 'suppressions-reason',
+            });
+        }
+    }
+
+    return { fixed, found };
+}
+
+/**
+ * One file read and audited: every violation it carries, each marked with
+ * whether a `--fix` settles that very line, and the text the rewrite would
+ * leave behind — null where nothing changed. A file with no directive spelling
+ * anywhere in it is skipped before a single line is parsed.
+ */
+function auditSource(root, path, configOf) {
+    const text = readText(root, path);
+    if (text === null || !/(?:es|ox)lint-disable|@ts-|biome-ignore/u.test(text)) {
+        return null;
+    }
+
+    const kept = [];
+    const violations = [];
+
+    for (const [index, line] of text.split('\n').entries()) {
+        const { fixed, found } = auditLine(line, index + 1, configOf());
+        kept.push(fixed);
+        for (const violation of found) {
+            violations.push({ ...violation, rewritable: fixed !== line });
+        }
+    }
+
+    const rewritten = kept.join('\n');
+
+    return { rewritten: rewritten === text ? null : rewritten, violations };
+}
+
+/**
+ * How many directives the tracked source carries — the number the drift report
+ * prints. It lives here because the shapes that count as a directive are this
+ * file's, and a second copy of them is a second definition of "suppression".
+ */
+export function countSuppressions(root, ignorePatterns = []) {
+    let found = 0;
+
+    for (const path of trackedFiles(root, { ignorePatterns }).filter((file) => SOURCE.test(file))) {
+        const text = readText(root, path);
+        if (text === null) {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            found +=
+                [...line.matchAll(DISABLE)].length +
+                [...line.matchAll(TS_DIRECTIVE)].length +
+                (BIOME.test(line) ? 1 : 0);
+        }
+    }
+
+    return found;
+}
+
+/* Imported for `countSuppressions`, run for the gate — never both at once. */
+if (import.meta.main) {
+    const isFix = argv.includes('--fix');
+    const oxlintAt = argv[argv.indexOf('--oxlint') + 1];
+    const oxlint = argv.includes('--oxlint') && oxlintAt !== undefined ? oxlintAt : 'oxlint';
+    const root = resolve(
+        argv.slice(2).find((argument, index) => {
+            const previous = argv[index + 1];
+
+            return (
+                !argument.startsWith('--') &&
+                previous !== '--oxlint' &&
+                previous !== '--ignore-pattern'
+            );
+        }) ?? '.',
+    );
+
+    const sources = trackedFiles(root, { ignorePatterns: ignorePatternsOf(argv) }).filter((path) =>
+        SOURCE.test(path),
+    );
+
+    /* The resolved config costs an oxlint run, so it is read only once a directive asks for it. */
+    let config;
+    const configOf = () => (config === undefined ? (config = resolveConfig(root, oxlint)) : config);
+
+    let failed = false;
+    const rewritten = [];
+
+    for (const path of sources) {
+        const audited = auditSource(root, path, configOf);
+        if (audited === null) {
+            continue;
+        }
+
+        for (const violation of audited.violations) {
+            if (isFix && violation.rewritable && violation.rule === 'suppressions-spelling') {
+                continue;
+            }
+            stdout.write(`${violation.rule}  ${path}  ${violation.message}\n`);
+            failed = true;
+        }
+
+        if (isFix && audited.rewritten !== null) {
+            writeFileSync(join(root, path), audited.rewritten);
+            rewritten.push(path);
+        }
+    }
+
+    for (const path of rewritten) {
+        stdout.write(`${path} rewritten — the directive now names the checker this project runs\n`);
+    }
+
+    exit(failed ? 1 : 0);
+}

package/lib/doctor.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+
+/**
+ * What the toolchain is actually running, against what it says it needs.
+ *
+ * Every version here is read from an INSTALLED package's own manifest rather
+ * than from a lockfile or a `--version` flag: a lockfile says what should have
+ * been installed, and two of these tools answer `--version` in a shape of their
+ * own or not at all. The declared ranges are this package's `package.json`, so
+ * the two halves of every row come from the two places that can disagree.
+ *
+ * Usage: node doctor.js
+ *
+ * One row per tool: what is installed, what is declared, and the verdict. Older
+ * than the range FAILS — a gate running an older linter is enforcing an older
+ * rulebook without saying so. Newer WARNS: a tool ahead of its range may be
+ * fine, and the toolchain is not the thing that gets to decide that.
+ *
+ * Exit code: 0 when nothing is old or absent, 1 otherwise.
+ */
+
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+import process, { exit, stdout } from 'node:process';
+
+const require = createRequire(import.meta.url);
+const PACKAGE_ROOT = resolve(import.meta.dirname, '..');
+
+/** A manifest off the disk. Every version this file reports is read this way. */
+function manifestAt(path) {
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+const manifest = manifestAt(resolve(PACKAGE_ROOT, 'package.json'));
+
+/** The per-platform package that carries the TypeScript 7 Go compiler here. */
+function goCompilerPackage() {
+    const os = { darwin: 'darwin', linux: 'linux', win32: 'win32' }[process.platform] ?? 'linux';
+    const arch = { arm: 'arm', arm64: 'arm64', x64: 'x64' }[process.arch] ?? 'x64';
+
+    return `@typescript/typescript-${os}-${arch}`;
+}
+
+/**
+ * An installed package's own version, or null when it is not there. A manifest
+ * is read through the resolver first and off the disk second: a package whose
+ * `exports` map does not publish `./package.json` — knip is one — is invisible
+ * to `require`, and the two directories below are the same two `find_binary`
+ * walks in `check.sh`.
+ */
+function installedVersion(name) {
+    for (const at of [
+        () => require.resolve(`${name}/package.json`),
+        () => resolve(PACKAGE_ROOT, 'node_modules', name, 'package.json'),
+        () => resolve(PACKAGE_ROOT, '../..', name, 'package.json'),
+    ]) {
+        try {
+            return manifestAt(at()).version;
+        } catch {
+            continue;
+        }
+    }
+
+    return null;
+}
+
+/** `1.83.0` as `[1, 83, 0]`, with anything after a `-` or `+` dropped. */
+function parts(version) {
+    return version
+        .split(/[+-]/u)[0]
+        .split('.')
+        .map((piece) => Number.parseInt(piece, 10) || 0);
+}
+
+/** Negative when left is older, positive when newer, zero when the same. */
+function compare(left, right) {
+    const [a, b] = [parts(left), parts(right)];
+    for (let index = 0; index < 3; index += 1) {
+        if ((a[index] ?? 0) !== (b[index] ?? 0)) {
+            return (a[index] ?? 0) - (b[index] ?? 0);
+        }
+    }
+
+    return 0;
+}
+
+/**
+ * The floor a range asks for, and the first version it refuses. `^` follows
+ * npm: below 1.0.0 a caret allows the patch line only, which is exactly why
+ * oxfmt's range moves on every minor.
+ */
+function boundsOf(range) {
+    const floor = range.replace(/^[\^>=~ ]+/u, '');
+    const [major = 0, minor = 0] = parts(floor);
+
+    if (range.startsWith('^')) {
+        return { ceiling: major === 0 ? `0.${minor + 1}.0` : `${major + 1}.0.0`, floor };
+    }
+    if (range.startsWith('>=') || range.startsWith('>')) {
+        return { ceiling: null, floor };
+    }
+    if (range.startsWith('~')) {
+        return { ceiling: `${major}.${minor + 1}.0`, floor };
+    }
+
+    return { ceiling: floor, exact: true, floor };
+}
+
+/** Where an installed version stands against a declared range. */
+function verdictOf(installed, range) {
+    if (installed === null) {
+        return 'absent';
+    }
+
+    const { ceiling, exact, floor } = boundsOf(range);
+    if (compare(installed, floor) < 0) {
+        return 'old';
+    }
+    if (exact === true) {
+        return compare(installed, floor) === 0 ? 'ok' : 'newer';
+    }
+
+    return ceiling !== null && compare(installed, ceiling) >= 0 ? 'newer' : 'ok';
+}
+
+const declared = {
+    ...manifest.dependencies,
+    ...manifest.optionalDependencies,
+};
+
+/**
+ * Every tool the toolchain runs, with what is installed, what is declared and
+ * where the two stand. The drift report reads the same rows and prints only the
+ * ones that deviate, so a version is answered for in one place.
+ */
+export function toolVersions() {
+    return [
+        ['node', process.version.replace(/^v/u, ''), manifest.engines?.node ?? '*'],
+        ['tsc (Go)', installedVersion(goCompilerPackage()), declared[goCompilerPackage()] ?? '*'],
+        ['typescript', installedVersion('typescript'), declared.typescript ?? '*'],
+        ['oxlint', installedVersion('oxlint'), declared.oxlint ?? '*'],
+        ['oxfmt', installedVersion('oxfmt'), declared.oxfmt ?? '*'],
+        [
+            'oxlint-tsgolint',
+            installedVersion('oxlint-tsgolint'),
+            declared['oxlint-tsgolint'] ?? '*',
+        ],
+        ['knip', installedVersion('knip'), declared.knip ?? '*'],
+    ].map(([name, installed, range]) => ({
+        installed,
+        name,
+        range,
+        verdict: verdictOf(installed, range),
+    }));
+}
+
+/* Imported for `toolVersions`, run for the report — never both at once. */
+if (import.meta.main) {
+    const rows = toolVersions();
+    const failed = rows.some(({ verdict }) => verdict === 'old' || verdict === 'absent');
+    const warned = rows.some(({ verdict }) => verdict === 'newer');
+
+    stdout.write('Toolchain versions\n\n');
+
+    for (const { installed, name, range, verdict } of rows) {
+        stdout.write(
+            `  ${name.padEnd(16)}${(installed ?? '—').padEnd(12)}${range.padEnd(12)}${verdict}\n`,
+        );
+    }
+
+    stdout.write('\n');
+
+    if (failed) {
+        stdout.write('A tool older than its range enforces an older rulebook without saying so.\n');
+    } else if (warned) {
+        stdout.write(
+            'A tool ahead of its range may be fine; the toolchain does not get to decide.\n',
+        );
+    } else {
+        stdout.write('Every tool is in range.\n');
+    }
+
+    exit(failed ? 1 : 0);
+}

package/lib/entry-points.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+/**
+ * The entries a build compiles, read off the consumer's own `exports` map.
+ *
+ * A package with several public subpaths — `./register`, `./testing`, `./oxlint`
+ * — used to need a `tsdown.config.ts` of its own to name them, which means
+ * declaring tsdown as a dependency, which is the one-devDependency contract
+ * broken ([Developing](../docs/02-developing.md)). The map already says what
+ * the package publishes, so the build reads it there.
+ *
+ * The rule: every subpath whose target is a file under `dist/` is compiled from
+ * the same path under `src/`, with a `.ts` extension. A subpath carrying a `*`
+ * is skipped — a pattern names a set the map does not enumerate — and so is a
+ * target the source tree has no file for, because a build cannot compile what
+ * nobody wrote.
+ *
+ * Prints one entry per line, sorted; prints NOTHING when the package has no
+ * exports map or no subpath resolves, and the caller then keeps the preset's
+ * single `src/index.ts`.
+ *
+ * Usage: node entry-points.js [project-root]
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { argv, stdout } from 'node:process';
+
+/**
+ * The file a subpath's condition tree points at, in the order Node resolves
+ * them. The empty string is "no target": a condition tree is data, and every
+ * answer here is a path.
+ */
+function targetOf(entry) {
+    if (typeof entry === 'string') {
+        return entry;
+    }
+    if (typeof entry !== 'object' || entry === null) {
+        return '';
+    }
+    for (const condition of ['import', 'default', 'require']) {
+        const nested = targetOf(entry[condition]);
+        if (nested !== '') {
+            return nested;
+        }
+    }
+    return '';
+}
+
+/** `./dist/register.js` -> `src/register.ts`, and the empty string otherwise. */
+function sourceOf(target) {
+    const match = /^\.\/dist\/(?<path>.+)\.(?:js|mjs|cjs)$/u.exec(target);
+    return match === null ? '' : `src/${match.groups.path}.ts`;
+}
+
+/** Every entry the map earns, in one order, each one a file that exists. */
+export function entryPoints(root) {
+    const manifest = join(root, 'package.json');
+    if (!existsSync(manifest)) {
+        return [];
+    }
+
+    let exported;
+    try {
+        exported = JSON.parse(readFileSync(manifest, 'utf8')).exports;
+    } catch {
+        return [];
+    }
+    if (typeof exported !== 'object' || exported === null) {
+        return [];
+    }
+
+    const entries = new Set();
+    for (const [subpath, entry] of Object.entries(exported)) {
+        if (subpath.includes('*')) {
+            continue;
+        }
+        const source = sourceOf(targetOf(entry));
+        if (source !== '' && existsSync(join(root, source))) {
+            entries.add(source);
+        }
+    }
+
+    return [...entries].toSorted((left, right) => left.localeCompare(right));
+}
+
+if (import.meta.main) {
+    for (const entry of entryPoints(resolve(argv[2] ?? '.'))) {
+        stdout.write(`${entry}\n`);
+    }
+}