@jterrazz/typescript 9.3.0 → 10.1.0

package/lib/merge-knip-config.js

@@ -39,29 +39,26 @@ import { workspaceMembers } from './workspace-members.js';
  * alone — a comment marker in a glob (`ignore: ["**\/*.js"]`) is data.
  */
 function withoutComments(text) {
-    let output = '',
-        index = 0,
-        inString = false;
+    let output = '';
+    let index = 0;
+    let inString = false;
 
     while (index < text.length) {
         const char = text[index];
 
         if (inString) {
-            const escaped = char === '\\';
-            output += escaped ? char + (text[index + 1] ?? '') : char;
-            inString = escaped || char !== '"';
-            index += escaped ? 2 : 1;
+            const step = inStringStep(text, index);
+            output += step.kept;
+            inString = step.open;
+            index = step.next;
         } else if (char === '"') {
             inString = true;
             output += char;
             index += 1;
-        } else if (char === '/' && text[index + 1] === '/') {
-            while (index < text.length && text[index] !== '\n') {
-                index += 1;
-            }
-        } else if (char === '/' && text[index + 1] === '*') {
-            const end = text.indexOf('*/', index + 2);
-            index = end === -1 ? text.length : end + 2;
+        } else if (opens(text, index, '//')) {
+            index = afterLine(text, index);
+        } else if (opens(text, index, '/*')) {
+            index = afterBlock(text, index);
         } else {
             output += char;
             index += 1;
@@ -71,6 +68,41 @@ function withoutComments(text) {
     return output;
 }
 
+/**
+ * One step of a scan already inside a string literal: what it keeps, whether
+ * the literal is still `open` after it, and where the scan resumes. A backslash
+ * carries the character behind it, so an escaped quote never closes anything.
+ */
+function inStringStep(text, index) {
+    const char = text[index];
+    const escaped = char === '\\';
+
+    return {
+        kept: escaped ? char + (text[index + 1] ?? '') : char,
+        next: index + (escaped ? 2 : 1),
+        open: escaped || char !== '"',
+    };
+}
+
+/** Whether a two-character marker opens at `index`. */
+function opens(text, index, marker) {
+    return text.startsWith(marker, index);
+}
+
+/** Where the scan resumes past a `//` comment: the newline that ends it. */
+function afterLine(text, index) {
+    const end = text.indexOf('\n', index);
+
+    return end === -1 ? text.length : end;
+}
+
+/** Where the scan resumes past a block comment: after its closing marker. */
+function afterBlock(text, index) {
+    const end = text.indexOf('*/', index + 2);
+
+    return end === -1 ? text.length : end + 2;
+}
+
 /** Whether the comma at `index` is the last one of its collection — `["a",]`. */
 function closesCollection(text, index) {
     if (text[index] !== ',') {
@@ -87,19 +119,19 @@ function closesCollection(text, index) {
 
 /** Drops a comma that closes its collection, outside string literals. */
 function withoutTrailingCommas(text) {
-    let output = '',
-        index = 0,
-        inString = false;
+    let output = '';
+    let index = 0;
+    let inString = false;
 
     while (index < text.length) {
         const char = text[index];
         const closes = closesCollection(text, index);
 
         if (inString) {
-            const escaped = char === '\\';
-            output += escaped ? char + (text[index + 1] ?? '') : char;
-            inString = escaped || char !== '"';
-            index += escaped ? 2 : 1;
+            const step = inStringStep(text, index);
+            output += step.kept;
+            inString = step.open;
+            index = step.next;
         } else {
             inString = char === '"';
             output += closes ? '' : char;
@@ -115,8 +147,8 @@ function withoutTrailingCommas(text) {
  * package's tree, and two token classes do not earn a dependency.
  */
 function readJsonc(path) {
-    const document = readFileSync(path, 'utf8'),
-        json = withoutTrailingCommas(withoutComments(document));
+    const document = readFileSync(path, 'utf8');
+    const json = withoutTrailingCommas(withoutComments(document));
 
     return JSON.parse(json);
 }
@@ -302,7 +334,7 @@ for (const dep of devDeps) {
 for (const dep of [...prodDeps, ...devDeps]) {
     // @scope/sub-package when the unscoped root is a peer or dependency
     // E.g. @hono/node-server → hono
-    const scopeMatch = dep.match(/^@(?<scope>[^/]+)\//);
+    const scopeMatch = /^@(?<scope>[^/]+)\//u.exec(dep);
     if (
         scopeMatch &&
         (peerDeps.includes(scopeMatch.groups.scope) ||
@@ -314,7 +346,7 @@ for (const dep of [...prodDeps, ...devDeps]) {
 
     // <parent>-plugin-* or <parent>-preset-* when <parent> is installed
     // E.g. vitepress-plugin-llms → vitepress
-    const pluginMatch = dep.match(/^(?<parent>.+?)-(?:plugin|preset|transformer|loader)-/);
+    const pluginMatch = /^(?<parent>.+?)-(?:plugin|preset|transformer|loader)-/u.exec(dep);
     if (pluginMatch && allDepNames.includes(pluginMatch.groups.parent)) {
         autoIgnoreDeps.push(dep);
         continue;

package/lib/tracked-files.js

@@ -0,0 +1,165 @@
+/**
+ * The files a project would carry into a commit — the one sweep every
+ * tree-reading gate starts from.
+ *
+ * `git ls-files --cached --others --exclude-standard` is the answer wherever
+ * there is a git tree: it names what is tracked AND what the next `git add`
+ * would track, so a file fails a gate before it is committed, not after. A
+ * directory git knows nothing about — a fixture the spec runner copied, a tree
+ * nobody has `git init`ed — is walked instead, because a gate that goes silent
+ * outside git is a gate that passes on everything.
+ *
+ * The sweep REFUSES an answer that is empty while the tree is not. A read that
+ * silently sees nothing turns every rule above it vacuously green, which is the
+ * one failure mode a gate must never have — and a genuinely bare directory,
+ * which the sandboxes of `specs/cli/` build, is told apart from it by looking.
+ *
+ * It also refuses to answer for the GROUND a spec stands on. `_fixtures/`,
+ * `_expected/`, `_stubs/` and `_binary/` hold a tree deliberately broken, a
+ * golden held byte for byte, a fake system and a build — each belonging to the
+ * scenario that mounts it, not to the project carrying it. A gate judges that
+ * tree where the scenario runs it, on its own ground, and never twice.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { lstatSync, readdirSync, readFileSync } from 'node:fs';
+import { join, matchesGlob } from 'node:path';
+
+/** Never source, never prose: what no gate of this toolchain has a question about. */
+const UNSWEPT = new Set([
+    '.artifacts',
+    '.git',
+    '.next',
+    '.turbo',
+    '.vite',
+    'coverage',
+    'dist',
+    'node_modules',
+]);
+
+/** Extensions whose bytes are not text — reading them for patterns is noise. */
+const BINARY = /\.(?:avif|bin|gif|ico|jpeg|jpg|lock|mp4|pdf|png|svg|ttf|webp|woff2?|zip)$/iu;
+
+/** Every path git carries or would carry, or null when there is no git tree here. */
+function gitSweep(root) {
+    try {
+        return execFileSync(
+            'git',
+            ['ls-files', '--cached', '--others', '--exclude-standard', '-z'],
+            { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+        )
+            .split('\0')
+            .filter((path) => path !== '');
+    } catch {
+        return null;
+    }
+}
+
+/** The same listing, derived from the filesystem, for a tree git does not know. */
+function walkSweep(root) {
+    const found = [];
+
+    function walk(relativePath) {
+        let entries;
+        try {
+            entries = readdirSync(join(root, relativePath), { withFileTypes: true });
+        } catch {
+            return;
+        }
+
+        for (const entry of entries.toSorted((a, b) => (a.name < b.name ? -1 : 1))) {
+            if (UNSWEPT.has(entry.name)) {
+                continue;
+            }
+            const child = relativePath === '' ? entry.name : `${relativePath}/${entry.name}`;
+            if (entry.isDirectory()) {
+                walk(child);
+            } else if (entry.isFile()) {
+                found.push(child);
+            }
+        }
+    }
+
+    walk('');
+
+    return found;
+}
+
+/** Whether anything the gates would ever read sits at the root at all. */
+function holdsSomething(root) {
+    try {
+        return readdirSync(root).some((name) => !UNSWEPT.has(name));
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * The ground a spec stands on, by the four names `@jterrazz/test` 14 gives it.
+ * `_common/` is deliberately absent: it is the project's own shared code, and
+ * the marker there says "of the row", not "not mine".
+ */
+const GROUND = new Set(['_binary', '_expected', '_fixtures', '_stubs']);
+
+/** Whether a path lies under the ground a scenario mounts rather than in the project. */
+const isGround = (path) => path.split('/').some((segment) => GROUND.has(segment));
+
+/**
+ * The sweep, filtered by what the run was told to overlook. `ignorePatterns`
+ * carries the `--ignore-pattern` globs `check` received, so one flag answers
+ * for the linter and for every gate that reads the same tree.
+ */
+export function trackedFiles(root = '.', { ignorePatterns = [] } = {}) {
+    const swept = gitSweep(root) ?? walkSweep(root);
+
+    if (swept.length === 0) {
+        if (holdsSomething(root)) {
+            throw new Error(
+                `nothing to read under ${root} — a gate sweeping no file passes on every file`,
+            );
+        }
+
+        return [];
+    }
+
+    return swept
+        .filter((path) => !path.split('/').some((segment) => UNSWEPT.has(segment)))
+        .filter((path) => !isGround(path))
+        .filter((path) => !ignorePatterns.some((pattern) => matchesGlob(path, pattern)))
+        .toSorted((left, right) => (left < right ? -1 : 1));
+}
+
+/**
+ * A tracked file's text, or null when there is no text to read: bytes, a file
+ * too large to be prose or source, one that is gone, or a SYMLINK — whose
+ * content belongs to its target, and is judged there once instead of twice.
+ */
+export function readText(root, path) {
+    if (BINARY.test(path)) {
+        return null;
+    }
+
+    try {
+        const stats = lstatSync(join(root, path));
+        if (stats.isSymbolicLink() || stats.size > 1_000_000) {
+            return null;
+        }
+        const text = readFileSync(join(root, path), 'utf8');
+
+        return text.includes('\0') ? null : text;
+    } catch {
+        return null;
+    }
+}
+
+/** The `--ignore-pattern` globs of an argument list, in the order they arrived. */
+export function ignorePatternsOf(argv) {
+    const patterns = [];
+    for (const [index, argument] of argv.entries()) {
+        if (argument === '--ignore-pattern' && argv[index + 1] !== undefined) {
+            patterns.push(argv[index + 1]);
+        }
+    }
+
+    return patterns;
+}

package/lib/unsafe-fixers.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+/**
+ * The rules `fix` must not let oxlint rewrite, as the flags that switch them
+ * off for one run: `--allow <rule>` per rule, one per line.
+ *
+ * A fixer that changes MEANING cannot be applied unattended — it turns working
+ * code into code that does not compile, or into code that claims something
+ * else. The rules are marked in the manifest (`unsafeFix()`), this prints them
+ * for the shell, and the oxlint pass of `fix` passes them through. Check mode
+ * keeps every one of them armed: the diagnostic is still owed an answer, from
+ * a human ([Quality checks](../docs/06-quality-checks.md)).
+ *
+ * Usage: node unsafe-fixers.js
+ */
+
+import { stdout } from 'node:process';
+
+import { unsafeFixers } from '../rules/catalog.js';
+
+if (import.meta.main) {
+    for (const { rule } of unsafeFixers()) {
+        stdout.write(`--allow\n${rule}\n`);
+    }
+}

package/lib/workspace-members.js

@@ -29,19 +29,18 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join, relative, resolve, sep } from 'node:path';
 import { argv, stdout } from 'node:process';
-import { fileURLToPath } from 'node:url';
 
 const SKIPPED = new Set(['dist', 'node_modules']);
 
 /** A glob over path segments — `*` stops at a separator, `**` does not. */
 function toPattern(glob) {
     const escaped = glob
-        .replaceAll(/[.+^${}()|[\]\\]/g, String.raw`\$&`)
+        .replaceAll(/[.+^${}()|[\]\\]/gu, String.raw`\$&`)
         .replaceAll('**', ' ')
         .replaceAll('*', '[^/]*')
         .replaceAll(' ', '.*');
 
-    return new RegExp(`^${escaped}$`);
+    return new RegExp(`^${escaped}$`, 'u');
 }
 
 /** The `workspaces` globs of a package.json, in either declared form. */
@@ -70,7 +69,7 @@ export function workspaceMembers(root = '.') {
     const absolute = resolve(root);
     const patterns = declaredGlobs(absolute)
         .filter((glob) => typeof glob === 'string' && !glob.startsWith('!'))
-        .map((glob) => toPattern(glob.replace(/\/+$/, '')));
+        .map((glob) => toPattern(glob.replace(/\/+$/u, '')));
 
     if (patterns.length === 0) {
         return [];
@@ -113,11 +112,11 @@ export function workspaceMembers(root = '.') {
 
     walk(absolute, 0);
 
-    return [...members].sort();
+    return [...members].toSorted((left, right) => (left < right ? -1 : 1));
 }
 
 // CLI form — only when this file IS the process entry, never on import.
-if (argv[1] && resolve(argv[1]) === fileURLToPath(import.meta.url)) {
+if (argv[1] && resolve(argv[1]) === import.meta.filename) {
     const members = workspaceMembers(argv[2] ?? '.');
     if (members.length > 0) {
         stdout.write(`${members.join('\n')}\n`);

package/package.json

@@ -1,10 +1,11 @@
 {
     "name": "@jterrazz/typescript",
-    "version": "9.3.0",
+    "version": "10.1.0",
+    "license": "MIT",
     "author": "Jean-Baptiste Terrazzoni <contact@jterrazz.com>",
     "repository": {
         "type": "git",
-        "url": "https://github.com/jterrazz/package-typescript"
+        "url": "git+https://github.com/jterrazz/package-typescript.git"
     },
     "bin": {
         "typescript": "bin/typescript.sh"
@@ -13,6 +14,7 @@
         "bin",
         "lib",
         "presets",
+        "rules",
         "src"
     ],
     "type": "module",
@@ -37,34 +39,52 @@
         },
         "./tsconfig/*": "./presets/tsconfig/*.json",
         "./tsconfig/*.json": "./presets/tsconfig/*.json",
-        "./tsdown/*": "./presets/tsdown/*.js",
-        "./tsdown/*.js": "./presets/tsdown/*.js",
+        "./tsdown/*": {
+            "types": "./presets/tsdown/*.d.ts",
+            "default": "./presets/tsdown/*.js"
+        },
+        "./tsdown/*.js": {
+            "types": "./presets/tsdown/*.d.ts",
+            "default": "./presets/tsdown/*.js"
+        },
         "./presets/tsconfig/*": "./presets/tsconfig/*.json",
         "./presets/tsconfig/*.json": "./presets/tsconfig/*.json",
-        "./presets/tsdown/*": "./presets/tsdown/*.js",
-        "./presets/tsdown/*.js": "./presets/tsdown/*.js"
+        "./presets/tsdown/*": {
+            "types": "./presets/tsdown/*.d.ts",
+            "default": "./presets/tsdown/*.js"
+        },
+        "./presets/tsdown/*.js": {
+            "types": "./presets/tsdown/*.d.ts",
+            "default": "./presets/tsdown/*.js"
+        }
     },
     "publishConfig": {
         "registry": "https://registry.npmjs.org/"
     },
     "scripts": {
         "build": "# no build script",
-        "lint": "./bin/typescript.sh check --ignore-pattern '**/_fixtures/**'",
-        "lint:fix": "./bin/typescript.sh fix --ignore-pattern '**/_fixtures/**'",
+        "lint": "./bin/typescript.sh check",
+        "lint:fix": "./bin/typescript.sh fix",
         "test": "vitest --run"
     },
     "dependencies": {
+        "@arethetypeswrong/cli": "^0.18.5",
+        "dependency-cruiser": "^18.3.1",
         "eslint-plugin-perfectionist": "^5.10.0",
-        "knip": "^6.27.0",
-        "oxfmt": "^0.59.0",
-        "oxlint": "^1.74.0",
-        "tsdown": "^0.22.9",
+        "knip": "^6.35.1",
+        "oxfmt": "^0.68.0",
+        "oxlint": "^1.83.0",
+        "oxlint-tsgolint": "7.0.2001",
+        "prettier": "^3.9.6",
+        "prettier-plugin-astro": "^1.0.0",
+        "publint": "^0.3.24",
+        "tsdown": "^0.23.0",
         "typedoc": "^0.28.20",
         "typedoc-plugin-markdown": "^4.12.0",
         "typescript": "^6.0.0"
     },
     "devDependencies": {
-        "@jterrazz/test": "^14.0.0",
+        "@jterrazz/test": "^15.0.0",
         "@types/node": "^26.1.1",
         "vitest": "^4.1.10"
     },
@@ -76,5 +96,8 @@
         "@typescript/typescript-linux-x64": "^7.0.2",
         "@typescript/typescript-win32-arm64": "^7.0.2",
         "@typescript/typescript-win32-x64": "^7.0.2"
+    },
+    "engines": {
+        "node": ">=24.0.0"
     }
 }

package/presets/oxfmt/index.js

@@ -1,18 +1,62 @@
 import { defineConfig } from 'oxfmt';
 
+/*
+ * The formatting decisions, in one place. Four of them are the estate's and do
+ * not move — 100 columns, 4 spaces, single quotes, trailing commas everywhere —
+ * because twenty-eight repositories are written that way and two of them hold
+ * signed attestation bytes a reflow would invalidate.
+ *
+ * The three sorters are the fourth law of the rulebook: sorting is formatting.
+ * oxfmt owns import order, package.json key order and Tailwind class order, so
+ * no lint rule reorders those bytes and no two tools fight over them
+ * ([Lint presets](../../docs/07-lint-presets.md)).
+ */
 export default defineConfig({
+    bracketSpacing: true,
+    endOfLine: 'lf',
     printWidth: 100,
-    tabWidth: 4,
-    useTabs: false,
     semi: true,
     singleQuote: true,
+    /* The grouping the estate has read for three years: builtins and externals
+     * together at the top, then internals, then the relative block, then
+     * styles. A blank line between groups, case-insensitive inside one. */
+    sortImports: {
+        groups: [
+            ['builtin', 'external'],
+            ['internal', 'subpath'],
+            ['parent', 'sibling', 'index'],
+            'style',
+            'unknown',
+        ],
+        ignoreCase: true,
+        newlinesBetween: true,
+        order: 'asc',
+    },
+    sortPackageJson: true,
+    /* Tailwind's own order, on `class`/`className` and on the class-holding
+     * helpers every repo of the estate uses. Regex matchers are not supported
+     * yet — these are exact names. */
+    sortTailwindcss: {
+        functions: ['clsx', 'cn', 'cva', 'tv', 'twMerge', 'twJoin', 'tw'],
+    },
+    tabWidth: 4,
     trailingComma: 'all',
-    bracketSpacing: true,
-    endOfLine: 'lf',
+    useTabs: false,
     /* `typescript docs` writes the byte-for-byte typedoc tree to docs/reference/ —
      * formatting it would fight the Docs (sync) pass, so skip it by default.
      * Asset trees and build caches are not source either — and a content tree
      * can hold signed bytes (jterrazz-web's attestations), where one formatter
      * pass invalidates every proof. */
-    ignorePatterns: ['docs/reference', 'dist/**', 'assets/**', 'public/**', '.next/**', '.expo/**'],
+    ignorePatterns: [
+        'docs/reference',
+        'dist/**',
+        'assets/**',
+        'public/**',
+        '.next/**',
+        '.expo/**',
+        // A spec's input is deliberately mis-shaped and its golden is
+        // Byte-for-byte; formatting either would rewrite the claim.
+        '**/_fixtures/**',
+        '**/_expected/**',
+    ],
 });

package/presets/oxlint/profiles/astro.js

@@ -0,0 +1,10 @@
+import { defineConfig } from 'oxlint';
+
+import { profile } from '../../../rules/compile.js';
+import { PROFILES } from '../../../rules/profiles.js';
+
+/*
+ * Astro: the rulebook, plus React (an island is a React component here),
+ * accessibility, and the decisions an `.astro` file's own shape forces.
+ */
+export default defineConfig(profile(PROFILES.astro));

package/presets/oxlint/profiles/bun.js

@@ -0,0 +1,7 @@
+import { defineConfig } from 'oxlint';
+
+import { profile } from '../../../rules/compile.js';
+import { PROFILES } from '../../../rules/profiles.js';
+
+/** Bun: the node rulebook, plus the globals Bun's runtime defines. */
+export default defineConfig(profile(PROFILES.bun));

package/presets/oxlint/profiles/expo.js

@@ -0,0 +1,7 @@
+import { defineConfig } from 'oxlint';
+
+import { profile } from '../../../rules/compile.js';
+import { PROFILES } from '../../../rules/profiles.js';
+
+/** Expo and React Native: the rulebook, plus React, accessibility and the platform. */
+export default defineConfig(profile(PROFILES.expo));

package/presets/oxlint/profiles/library.js

@@ -0,0 +1,16 @@
+import { defineConfig } from 'oxlint';
+
+import { profile } from '../../../rules/compile.js';
+import { PROFILES } from '../../../rules/profiles.js';
+
+/*
+ * A published package: the node rulebook, plus the one tree a library carries
+ * and never lints — the committed typedoc projection.
+ *
+ * The `.js` extension on every relative import is core's (`import/extensions`
+ * at `always`), because Node ESM resolves a specifier literally and a package
+ * published as ESM is read by Node before any bundler reads it. It pairs with
+ * `presets/tsdown/bundle.js`, whose `isolatedDeclarations` is what makes the
+ * published declarations emit without a type-checker.
+ */
+export default defineConfig(profile(PROFILES.library));

package/presets/oxlint/profiles/next.js

@@ -0,0 +1,7 @@
+import { defineConfig } from 'oxlint';
+
+import { profile } from '../../../rules/compile.js';
+import { PROFILES } from '../../../rules/profiles.js';
+
+/** Next.js: the rulebook, plus React, accessibility and Next's own 21 rules. */
+export default defineConfig(profile(PROFILES.next));

package/presets/oxlint/profiles/node.js

@@ -0,0 +1,7 @@
+import { defineConfig } from 'oxlint';
+
+import { profile } from '../../../rules/compile.js';
+import { PROFILES } from '../../../rules/profiles.js';
+
+/** Node.js services and command-line tools: the rulebook, and nothing added. */
+export default defineConfig(profile(PROFILES.node));

package/presets/oxlint/profiles/react.js

@@ -0,0 +1,7 @@
+import { defineConfig } from 'oxlint';
+
+import { profile } from '../../../rules/compile.js';
+import { PROFILES } from '../../../rules/profiles.js';
+
+/** React with no framework under it: the rulebook, plus React and accessibility. */
+export default defineConfig(profile(PROFILES.react));

package/presets/prettier/astro.json

@@ -0,0 +1,6 @@
+{
+    "printWidth": 100,
+    "singleQuote": true,
+    "tabWidth": 4,
+    "trailingComma": "all"
+}

package/presets/tsconfig/astro.json

@@ -0,0 +1,25 @@
+{
+    "display": "Astro",
+    "compilerOptions": {
+        "allowJs": true,
+        "esModuleInterop": true,
+        "exactOptionalPropertyTypes": true,
+        "incremental": true,
+        "jsx": "react-jsx",
+        "jsxImportSource": "react",
+        "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
+    }
+}