@jterrazz/typescript 9.3.0 → 10.0.0

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/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.0.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",
@@ -49,16 +51,22 @@
     },
     "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"
@@ -76,5 +84,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/tsconfig/library.json`, whose `isolatedDeclarations` is what makes
+ * the 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/prettier/astro.json

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

package/presets/tsconfig/expo.json

@@ -1,23 +1,33 @@
 {
     "display": "Expo",
     "include": ["${configDir}/**/*.ts", "${configDir}/**/*.tsx"],
-    "exclude": ["${configDir}/node_modules"],
-
+    "exclude": [
+        "${configDir}/node_modules",
+        "${configDir}/**/_fixtures",
+        "${configDir}/**/_expected"
+    ],
     "compilerOptions": {
         "allowJs": true,
-        "baseUrl": ".",
         "esModuleInterop": true,
+        "exactOptionalPropertyTypes": true,
         "incremental": true,
         "jsx": "react-native",
         "lib": ["DOM", "ESNext"],
-        "moduleResolution": "node",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
         "noEmit": true,
+        "noFallthroughCasesInSwitch": true,
+        "noImplicitOverride": true,
+        "noUncheckedIndexedAccess": true,
+        "noUncheckedSideEffectImports": true,
         "paths": {
-            "@/*": ["src/*"]
+            "@/*": ["${configDir}/src/*"]
         },
         "resolveJsonModule": true,
         "skipLibCheck": true,
+        "strict": true,
         "target": "ESNext",
-        "tsBuildInfoFile": "${configDir}/.artifacts/tsc/tsconfig.tsbuildinfo"
+        "tsBuildInfoFile": "${configDir}/.artifacts/tsc/tsconfig.tsbuildinfo",
+        "verbatimModuleSyntax": true
     }
 }

package/presets/tsconfig/library.json

@@ -0,0 +1,18 @@
+{
+    "display": "Library (ESM, declaration-emitting)",
+    "extends": "./node.json",
+    "compilerOptions": {
+        "allowJs": false,
+        "declaration": true,
+        "erasableSyntaxOnly": true,
+        "isolatedDeclarations": true
+    },
+    "include": ["${configDir}/**/*.ts"],
+    "exclude": [
+        "${configDir}/node_modules",
+        "${configDir}/dist",
+        "${configDir}/.artifacts",
+        "${configDir}/**/_fixtures",
+        "${configDir}/**/_expected"
+    ]
+}

package/presets/tsconfig/next.json

@@ -18,7 +18,13 @@
             {
                 "name": "next"
             }
-        ]
+        ],
+        "exactOptionalPropertyTypes": true,
+        "noFallthroughCasesInSwitch": true,
+        "noImplicitOverride": true,
+        "noUncheckedIndexedAccess": true,
+        "noUncheckedSideEffectImports": true,
+        "verbatimModuleSyntax": true
     },
     "include": [
         "${configDir}/next-env.d.ts",
@@ -27,5 +33,9 @@
         "${configDir}/**/*.ts",
         "${configDir}/**/*.tsx"
     ],
-    "exclude": ["${configDir}/node_modules"]
+    "exclude": [
+        "${configDir}/node_modules",
+        "${configDir}/**/_fixtures",
+        "${configDir}/**/_expected"
+    ]
 }

package/presets/tsconfig/node.json

@@ -1,19 +1,33 @@
 {
     "display": "Node ESM",
-    "include": ["${configDir}/**/*.ts"],
-    "exclude": ["${configDir}/node_modules"],
-
+    "include": ["${configDir}/**/*.ts", "${configDir}/**/*.js"],
+    "exclude": [
+        "${configDir}/node_modules",
+        "${configDir}/dist",
+        "${configDir}/.artifacts",
+        "${configDir}/**/_fixtures",
+        "${configDir}/**/_expected"
+    ],
     "compilerOptions": {
         "moduleResolution": "Bundler",
         "module": "ESNext",
         "target": "ESNext",
         "types": ["node"],
         "strict": true,
+        "exactOptionalPropertyTypes": true,
+        "noFallthroughCasesInSwitch": true,
+        "noImplicitOverride": true,
+        "noUncheckedIndexedAccess": true,
+        "noUncheckedSideEffectImports": true,
+        "verbatimModuleSyntax": true,
         "incremental": true,
         "tsBuildInfoFile": "${configDir}/.artifacts/tsc/tsconfig.tsbuildinfo",
         "experimentalDecorators": true,
         "esModuleInterop": true,
         "resolveJsonModule": true,
-        "skipLibCheck": true
+        "skipLibCheck": true,
+        "allowJs": true,
+        "checkJs": false,
+        "noEmit": true
     }
 }

package/rules/README.md

@@ -0,0 +1,23 @@
+# `rules/` — the manifest
+
+One nature lives here: a DECISION about a lint rule. Never a config object, never a path, never a tool invocation — those are `presets/`'s and `bin/`'s. What the decisions mean, and the four laws they answer to, is [Lint presets](../docs/07-lint-presets.md); this page only says where each thing is.
+
+| File                                                                | Holds                                                                                                                                                    |
+| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `_contract.js`                                                      | `fragment()`, `on()`, `typeAware()`, `off()`, `scoped()` — and the load-time refusal of a level that is not `error`/`off` and of an `off` with no reason |
+| `compile.js`                                                        | fragment → plain oxlint config, and the deterministic merge behind `compose()`. It never emits `categories`                                              |
+| `profiles.js`                                                       | which fragments each of the six profiles carries, and what none of them lints                                                                            |
+| `catalog.js`                                                        | every decision as one list, and the markdown the chapter carries between its `GENERATED` markers                                                         |
+| `core/`                                                             | one file per plugin of the rulebook every profile holds: `eslint`, `typescript`, `unicorn`, `oxc`, `import`, `promise`, `node`, `jsdoc`                  |
+| `react.js` · `a11y.js` · `next.js` · `react-native.js` · `astro.js` | what a framework profile adds to that rulebook                                                                                                           |
+| `vitest.js`                                                         | the test-file rules, as an `overrides` block — they read a test and say nothing about anything else                                                      |
+| `sorted.js`                                                         | perfectionist: only what oxfmt does not sort                                                                                                             |
+| `architecture/`                                                     | `layers.js` turns a declared layer map into `no-restricted-imports` overrides; `hexagonal.js` is the map this package ships                              |
+
+A fragment is loaded, not read: importing one runs its contract, so a decision that breaks an invariant fails at import time rather than at review time.
+
+## What proves it
+
+- `_contract.test.ts` — the invariants, and the compile of a fragment.
+- `catalog.test.ts` — the chapter is the manifest's projection, and nothing else.
+- `specs/cli/preset/` — the resolved rule set, the plugin coverage, the fixpoint against the formatter, the behaviour of each decision, and the exclusive pairs.