@jterrazz/typescript 9.2.1 → 10.0.0

package/bin/typescript.sh

@@ -41,6 +41,21 @@ find_binary() {
 
 TSDOWN=$(find_binary tsdown)
 
+# oxlint's type-aware rules run in `tsgolint`, a separate binary it looks up on
+# PATH — and a consumer's PATH has no reason to carry this package's bin dir. It
+# is a dependency here, so the lookup is made to succeed by putting the
+# directory that holds it in front, for this process and its children only.
+add_tsgolint_to_path() {
+    local tsgolint
+    tsgolint=$(find_binary tsgolint)
+    case "$tsgolint" in
+        */*)
+            PATH="$(cd -P "$(dirname "$tsgolint")" && pwd):$PATH"
+            export PATH
+            ;;
+    esac
+}
+
 # Parse command
 COMMAND="$1"
 shift 2>/dev/null || true
@@ -168,6 +183,42 @@ case "$COMMAND" in
         exec node "$PACKAGE_ROOT/lib/check-docs.js" "${1:-$PROJECT_ROOT}"
         ;;
 
+    doctor)
+        # Cheap, and read-only: what the toolchain is actually running against
+        # what it says it needs. No binary is spawned — every version is read
+        # off an installed package's own manifest, which is the one place that
+        # cannot disagree with what node will load.
+        printf "${CYAN_BG}${BRIGHT_WHITE} TYPESCRIPT ${NC} Checking the toolchain...\n\n"
+
+        exec node "$PACKAGE_ROOT/lib/doctor.js"
+        ;;
+
+    baseline)
+        # The ratchet, recorded. A command of its own because it neither checks
+        # nor repairs: it writes down where the project actually stands, so the
+        # oxlint pass can refuse to let that number rise. `fix --baseline` would
+        # bury a rewrite of a tracked file inside the everyday gesture.
+        cd "$PROJECT_ROOT"
+
+        add_tsgolint_to_path
+
+        OXLINT=$(find_binary oxlint)
+        BASELINE_REPORT=$(mktemp)
+        trap 'rm -f "$BASELINE_REPORT"' EXIT
+
+        printf "${CYAN_BG}${BRIGHT_WHITE} TYPESCRIPT ${NC} Recording the oxlint baseline...\n\n"
+
+        # A non-zero exit is the whole point of the recording, not a failure.
+        "$OXLINT" --type-aware --format json "$@" > "$BASELINE_REPORT" 2>/dev/null || true
+
+        node "$PACKAGE_ROOT/lib/check-baseline.js" "$BASELINE_REPORT" . --write
+
+        # The file is tracked, so it is the formatter's like every other tracked
+        # file — written here, shaped by the project's own oxfmt, never both.
+        OXFMT=$(find_binary oxfmt)
+        "$OXFMT" oxlint.baseline.json > /dev/null 2>&1 || true
+        ;;
+
     check|fix)
         exec bash "$SCRIPT_DIR/commands/check.sh" "$COMMAND" "$@"
         ;;
@@ -182,6 +233,8 @@ case "$COMMAND" in
         printf "  dev          Build, run, and rebuild on changes\n"
         printf "  docs         Generate the committed docs/reference tree; --check verifies sync\n"
         printf "  docs-layout  Check a repository's docs/ against the manual spine\n"
+        printf "  doctor       Report the installed tool versions against the declared ranges\n"
+        printf "  baseline     Record the oxlint baseline this project may not exceed\n"
         printf "  check        Check types, lint, formatting, and unused code\n"
         printf "  fix          Auto-fix lint and formatting issues\n"
         printf "  clean        Remove .artifacts/ — dist/ stays, it is the build's product\n\n"
@@ -193,6 +246,8 @@ case "$COMMAND" in
         printf "  typescript docs\n"
         printf "  typescript docs --check\n"
         printf "  typescript docs-layout .\n"
+        printf "  typescript doctor\n"
+        printf "  typescript baseline\n"
         printf "  typescript check\n"
         printf "  typescript fix\n"
         printf "  typescript clean\n"

package/lib/check-architecture.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+/**
+ * The layer map a project declared, checked against the graph it actually has.
+ *
+ * oxlint's `no-restricted-imports` reads a path and a pattern; dependency-
+ * cruiser resolves the module graph, which is the only way to see a cycle that
+ * runs through three files or an edge that hides behind a barrel. Where a
+ * project declares a map — `.dependency-cruiser.cjs`, `.js` or `.mjs` at its
+ * root — this gate is the one that reads it.
+ *
+ * The rule ids are the config's own `name`s. That is deliberate and it is the
+ * only gate of this toolchain whose vocabulary the consumer writes: a layer map
+ * is a project's own architecture, and naming its rules for it is the point.
+ *
+ * Usage: node check-architecture.js [root] [--depcruise <path>]
+ *
+ * dependency-cruiser's `err-long` report, verbatim, when the graph breaks the
+ * map. Exit code: 0 when it holds, 1 otherwise. No `--fix`: moving a module
+ * across a layer is a design decision.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { argv, exit, stdout } from 'node:process';
+
+/** The three spellings dependency-cruiser answers to at a project root. */
+const CONFIGS = ['.dependency-cruiser.cjs', '.dependency-cruiser.js', '.dependency-cruiser.mjs'];
+
+/**
+ * What a cruise starts from. `src/` is the whole answer wherever there is one;
+ * a workspace that keeps its code in `apps/` and `packages/` is cruised from
+ * those instead, so a map never has to restate the tree's shape.
+ */
+const ROOTS = ['apps', 'lib', 'packages'];
+
+const flagged = (name, fallback) => {
+    const at = argv.indexOf(name);
+
+    return at === -1 || argv[at + 1] === undefined ? fallback : argv[at + 1];
+};
+
+const root = resolve(
+    argv
+        .slice(2)
+        .find(
+            (argument, index) => !argument.startsWith('--') && argv[index + 1] !== '--depcruise',
+        ) ?? '.',
+);
+
+const config = CONFIGS.find((name) => existsSync(join(root, name)));
+if (config === undefined) {
+    exit(0);
+}
+
+const cruised = existsSync(join(root, 'src'))
+    ? ['src']
+    : ROOTS.filter((name) => existsSync(join(root, name)));
+
+if (cruised.length === 0) {
+    stdout.write(
+        `${config} declares a layer map, but there is no src/, apps/, packages/ or lib/ to cruise\n`,
+    );
+    exit(1);
+}
+
+/* An empty root is a cruise of nothing, and dependency-cruiser refuses one. */
+const populated = cruised.filter((name) => readdirSync(join(root, name)).length > 0);
+if (populated.length === 0) {
+    exit(0);
+}
+
+const run = spawnSync(
+    flagged('--depcruise', 'depcruise'),
+    ['--config', config, '--output-type', 'err-long', ...populated],
+    { cwd: root, encoding: 'utf8' },
+);
+
+if (run.error) {
+    stdout.write(`depcruise could not be run: ${run.error.message}\n`);
+    exit(1);
+}
+
+if (run.status !== 0) {
+    stdout.write(`${run.stdout ?? ''}${run.stderr ?? ''}`);
+}
+
+exit(run.status === 0 ? 0 : 1);

package/lib/check-baseline.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+/**
+ * The migration ratchet: a count per rule that may fall and never rise.
+ *
+ * A project adopting a stricter rulebook has two honest options — burn every
+ * diagnostic down before the first green run, or record where it stands and
+ * refuse to go backwards. `oxlint.baseline.json` is the second: `{ "<rule>":
+ * <count> }`, tracked, and read by the oxlint pass instead of the raw exit
+ * code. Without the file a single diagnostic fails, exactly as before.
+ *
+ * Three things fail a run that has one:
+ *
+ * - a rule whose count EXCEEDS its entry — the debt grew;
+ * - a rule with diagnostics and NO entry — a rule nobody recorded owing;
+ * - an entry whose count is now zero — the ratchet moved, so the entry goes.
+ *
+ * The third is what makes the file shrink. Without it a baseline records a debt
+ * that was paid years ago and nothing ever says so.
+ *
+ * Usage: node check-baseline.js <oxlint-json> [root] [--write]
+ *
+ * `--write` rewrites the file from the current counts — that is `typescript
+ * baseline`, a command of its own because it RECORDS rather than checks or
+ * repairs. Exit code: 0 when the ratchet holds, 1 otherwise.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { argv, exit, stdout } from 'node:process';
+
+/** The file, at the project root, tracked beside the config it ratchets. */
+export const BASELINE = 'oxlint.baseline.json';
+
+/** `eslint(no-debugger)` is how oxlint's JSON spells `eslint/no-debugger`. */
+function ruleOf(code) {
+    const match = /^(?<plugin>[\w-]+)\((?<rule>[^)]+)\)$/u.exec(code ?? '');
+
+    return match === null ? (code ?? 'unknown') : `${match.groups.plugin}/${match.groups.rule}`;
+}
+
+/** How many diagnostics each rule accounts for, in oxlint's JSON report. */
+export function countsOf(report) {
+    const counts = {};
+    for (const diagnostic of report.diagnostics ?? []) {
+        const rule = ruleOf(diagnostic.code);
+        counts[rule] = (counts[rule] ?? 0) + 1;
+    }
+
+    return counts;
+}
+
+/** The recorded counts, or null when the project does not keep a baseline. */
+export function readBaseline(root) {
+    const path = join(root, BASELINE);
+    if (!existsSync(path)) {
+        return null;
+    }
+
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    } catch {
+        return {};
+    }
+}
+
+/** Every way the counts break the ratchet, in the order a reader wants them. */
+export function judge(counts, baseline) {
+    const broken = [];
+
+    for (const [rule, count] of Object.entries(counts).toSorted(([left], [right]) =>
+        left < right ? -1 : 1,
+    )) {
+        const allowed = baseline[rule];
+        if (allowed === undefined) {
+            broken.push(`${rule} has ${count} diagnostic(s) and no entry — it is new debt`);
+        } else if (count > allowed) {
+            broken.push(`${rule} is at ${count}, above its baseline of ${allowed}`);
+        }
+    }
+
+    for (const rule of Object.keys(baseline).toSorted()) {
+        if ((counts[rule] ?? 0) === 0) {
+            broken.push(`${rule} is at zero — the ratchet moved, delete its entry`);
+        }
+    }
+
+    return broken;
+}
+
+/** The file's text: sorted, two-space, so a diff reads as a burn-down. */
+function serialise(counts) {
+    const sorted = Object.fromEntries(
+        Object.entries(counts).toSorted(([left], [right]) => (left < right ? -1 : 1)),
+    );
+
+    return `${JSON.stringify(sorted, null, 2)}\n`;
+}
+
+/* Imported for the ratchet's reading, run for the gate — never both at once. */
+if (import.meta.main) {
+    const isWrite = argv.includes('--write');
+    const positional = argv.slice(2).filter((argument) => !argument.startsWith('--'));
+    const reportPath = positional[0];
+    const root = resolve(positional[1] ?? '.');
+
+    let report;
+    try {
+        report = JSON.parse(readFileSync(reportPath, 'utf8'));
+    } catch {
+        stdout.write(
+            `oxlint wrote no JSON report at ${reportPath} — the baseline cannot be read\n`,
+        );
+        exit(1);
+    }
+
+    const counts = countsOf(report);
+
+    if (isWrite) {
+        const total = Object.values(counts).reduce((sum, count) => sum + count, 0);
+        writeFileSync(join(root, BASELINE), serialise(counts));
+        stdout.write(
+            `${BASELINE} written — ${total} diagnostic(s) across ${Object.keys(counts).length} rule(s)\n`,
+        );
+        exit(0);
+    }
+
+    const baseline = readBaseline(root);
+
+    if (baseline === null) {
+        exit(Object.keys(counts).length > 0 ? 1 : 0);
+    }
+
+    const broken = judge(counts, baseline);
+
+    for (const reason of broken) {
+        stdout.write(`baseline-ratchet  ${BASELINE}  ${reason}\n`);
+    }
+    if (broken.length > 0) {
+        stdout.write("Run 'typescript baseline' to record where the project actually stands.\n");
+    }
+
+    exit(broken.length > 0 ? 1 : 0);
+}

package/lib/check-docs.js

@@ -22,7 +22,8 @@
  * place the workspace shows through is the `04-operating.md` presence test,
  * whose Dockerfile and `.infrastructure/` clauses are read at the root AND at
  * every workspace member's root — a monorepo deploys from a member as readily
- * as from its root (ADR-007, the toolchain's unit is the workspace package).
+ * as from its root ([Architecture](../docs/01-architecture.md), "The unit is the
+ * workspace package").
  * The publishable clause stays on the ROOT manifest: a private root that holds
  * a publishable member is a question for its owner, not a verdict for a gate.
  */
@@ -35,7 +36,7 @@ import { auditDocs, HEAD_LINES } from '../src/docs.js';
 import { workspaceMembers } from './workspace-members.js';
 
 /** Every markdown link target of a page, in the order the page carries them. */
-const LINK = /!?\[[^\]]*]\(\s*(?<target>[^\s)]+)/g;
+const LINK = /!?\[[^\]]*\]\(\s*(?<target>[^\s)]+)/gu;
 
 /** Where a repository declares a deployment it owns. */
 const INFRASTRUCTURE = '.infrastructure';
@@ -53,7 +54,7 @@ function listDocs(root) {
         paths.push(`${relativePath}/`);
 
         const entries = readdirSync(join(root, relativePath), { withFileTypes: true });
-        for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+        for (const entry of entries.toSorted((a, b) => (a.name < b.name ? -1 : 1))) {
             const child = `${relativePath}/${entry.name}`;
             if (entry.isDirectory()) {
                 walk(child);

package/lib/check-drift.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+
+/**
+ * How far this project stands from the profile it says it extends.
+ *
+ * Four numbers, printed at the end of every `check`, because the alternative is
+ * what the estate had: twenty-eight repositories each quietly a little further
+ * from the shared rulebook, and nobody able to say by how much without opening
+ * twenty-eight config files. A rule turned off, a suppression written, a
+ * baseline entry recorded and a tool left behind are the four ways a project
+ * drifts, and each of them is a number here.
+ *
+ * One of the four is also a GATE. A rule the profile has on may be turned off —
+ * a project knows things the profile does not — but not silently: the line that
+ * turns it off carries a `// reason:` comment, or the run fails on
+ * `drift-unreasoned`. The other three only ever report.
+ *
+ * Usage: node check-drift.js [root] [--oxlint <path>] [--json]
+ *        [--ignore-pattern <glob>]…
+ *
+ * Exit code: 0 unless a rule is turned off with no reason beside it.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { argv, exit, stdout } from 'node:process';
+
+import { PROFILES } from '../rules/profiles.js';
+import { readBaseline } from './check-baseline.js';
+import { countSuppressions } from './check-suppressions.js';
+import { toolVersions } from './doctor.js';
+import { ignorePatternsOf } from './tracked-files.js';
+
+const PACKAGE_ROOT = resolve(import.meta.dirname, '..');
+
+/** Where a consumer declares its rules, in the order oxlint looks. */
+const CONFIGS = [
+    'oxlint.config.ts',
+    'oxlint.config.mjs',
+    'oxlint.config.js',
+    'oxlint.config.cjs',
+    '.oxlintrc.json',
+];
+
+/** The profiles this package ships, read off the manifest that defines them. */
+const PROFILE_NAMES = new Set(Object.keys(PROFILES));
+
+/** The comment that makes a rule turned off a decision rather than a drift. */
+const REASON = /\/\/\s*reason:/iu;
+
+/** A resolved rule set, as `name -> level`, or null when oxlint refused. */
+function resolvedRules(root, oxlint, configPath) {
+    try {
+        const printed = execFileSync(
+            oxlint,
+            configPath === null ? ['--print-config'] : ['-c', configPath, '--print-config'],
+            { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+        );
+
+        return JSON.parse(printed).rules ?? {};
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * The profile a consumer config extends, read off the config's own source, or
+ * null when it extends none of ours.
+ *
+ * The SOURCE is the evidence, and it is the only evidence available: oxlint's
+ * config schema is closed — an unknown top-level key makes it print `Failed to
+ * parse oxlint configuration file` — so a compiled profile cannot carry its own
+ * name through to `--print-config`. A config that imports `node` from this
+ * package's oxlint entry is a `node` project, and that import is what this
+ * reads.
+ *
+ * Null matters: a project that extends no profile of ours is not DRIFTING from
+ * one, it never joined it, and reporting two hundred "rules off" would say
+ * nothing about anything.
+ */
+function profileOf(source) {
+    const imported =
+        /import\s*\{(?<names>[^}]*)\}\s*from\s*['"]@jterrazz\/typescript\/oxlint['"]/u.exec(
+            source ?? '',
+        );
+    const named = (imported?.groups.names ?? '').split(',').map((name) => name.trim());
+
+    return named.find((name) => PROFILE_NAMES.has(name)) ?? null;
+}
+
+/** A rule the profile runs and this project does not. */
+function turnedOff(profile, consumer) {
+    const off = [];
+    for (const [rule, level] of Object.entries(profile).toSorted(([left], [right]) =>
+        left < right ? -1 : 1,
+    )) {
+        if (level === 'allow') {
+            continue;
+        }
+        const here = consumer[rule];
+        if (here === undefined || here === 'allow') {
+            off.push(rule);
+        }
+    }
+
+    return off;
+}
+
+/** The line of the config that turns a rule off, when the config names it at all. */
+function lineNaming(source, rule) {
+    const bare = rule.split('/').at(-1);
+
+    return (source ?? '')
+        .split('\n')
+        .find(
+            (line) =>
+                line.includes(rule) || line.includes(`'${bare}'`) || line.includes(`"${bare}"`),
+        );
+}
+
+const isJson = argv.includes('--json');
+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 configName = CONFIGS.find((name) => existsSync(join(root, name)));
+const source = configName === undefined ? null : readFileSync(join(root, configName), 'utf8');
+const profileName = profileOf(source);
+
+const consumerRules = resolvedRules(root, oxlint, null) ?? {};
+const profileRules =
+    profileName === null
+        ? {}
+        : (resolvedRules(
+              root,
+              oxlint,
+              join(PACKAGE_ROOT, 'presets/oxlint/profiles', `${profileName}.js`),
+          ) ?? {});
+
+const off = turnedOff(profileRules, consumerRules);
+const unreasoned = off.filter((rule) => {
+    const line = lineNaming(source, rule);
+
+    return line === undefined || !REASON.test(line);
+});
+
+const baseline = readBaseline(root);
+const baselineTotal =
+    baseline === null ? null : Object.values(baseline).reduce((sum, count) => sum + count, 0);
+const suppressions = countSuppressions(root, ignorePatternsOf(argv));
+const behind = toolVersions().filter(({ verdict }) => verdict !== 'ok');
+
+if (isJson) {
+    stdout.write(
+        `${JSON.stringify(
+            {
+                baseline: baselineTotal,
+                profile: profileName,
+                rulesOff: off,
+                suppressions,
+                tools: behind,
+                unreasoned,
+            },
+            null,
+            2,
+        )}\n`,
+    );
+    exit(unreasoned.length > 0 ? 1 : 0);
+}
+
+/** The one line a reader looks for: what this project runs that the profile does not. */
+function rulesOffLine() {
+    if (profileName === null) {
+        return 'not measured';
+    }
+
+    return off.length === 0 ? 'none' : `${off.length} (${off.join(', ')})`;
+}
+
+stdout.write(`  profile               ${profileName ?? "none of this package's"}\n`);
+stdout.write(`  rules off vs profile  ${rulesOffLine()}\n`);
+stdout.write(`  suppressions          ${suppressions}\n`);
+stdout.write(`  baseline              ${baselineTotal === null ? 'absent' : baselineTotal}\n`);
+stdout.write(
+    `  tool versions         ${
+        behind.length === 0
+            ? 'in range'
+            : behind
+                  .map(({ installed, name, verdict }) => `${name} ${installed} ${verdict}`)
+                  .join(', ')
+    }\n`,
+);
+
+for (const rule of unreasoned) {
+    stdout.write(
+        `\ndrift-unreasoned  ${configName ?? 'oxlint.config'}  ${rule} is off and the line that turns it off carries no '// reason:'\n`,
+    );
+}
+
+exit(unreasoned.length > 0 ? 1 : 0);

package/lib/check-gitignore.js

@@ -125,7 +125,7 @@ function nextConfigDeclaresExport(dir) {
             continue;
         }
         try {
-            if (/output\s*:\s*['"]export['"]/.test(readFileSync(path, 'utf8'))) {
+            if (/output\s*:\s*['"]export['"]/u.test(readFileSync(path, 'utf8'))) {
                 return true;
             }
         } catch {
@@ -192,7 +192,7 @@ function findWorkspaceRoot(root) {
  * matches at any depth below it.
  */
 function isAnchored(pattern) {
-    return pattern.replace(/\/+$/, '').includes('/');
+    return pattern.replace(/\/+$/u, '').includes('/');
 }
 
 /**
@@ -203,11 +203,11 @@ function isAnchored(pattern) {
  */
 function subject(pattern) {
     const segments = pattern
-        .replace(/\/+$/, '')
+        .replace(/\/+$/u, '')
         .split('/')
         .filter((segment) => segment !== '' && segment !== '**');
 
-    return (segments.at(-1) ?? '').replace(/\*$/, '');
+    return (segments.at(-1) ?? '').replace(/\*$/u, '');
 }
 
 /** The `.artifacts/` home of the artefact a pattern names, or null. */