@jterrazz/typescript 10.1.9 → 10.2.0

package/bin/commands/check.sh

@@ -98,7 +98,15 @@ find_project_binary() {
 # and the consumer is precisely the project that no longer declares it.
 PRETTIER_ASTRO_CONFIG="$PACKAGE_ROOT/presets/prettier/astro.json"
 PRETTIER_ASTRO_PLUGIN=$(cd "$PACKAGE_ROOT" && node -e 'process.stdout.write(require.resolve("prettier-plugin-astro"))' 2>/dev/null)
-CHECKER=$(find_binary jterrazz-test-check)
+# The conventions checker is the CONSUMER's binary, like astro's: this package
+# runs it, it does not own it, and the version a project installed is the
+# rulebook it agreed to. So the lookup starts at the project and falls back
+# here only for a project that has no install of its own.
+CHECKER=$(find_project_binary jterrazz-test-check)
+
+# The release of @jterrazz/test that answers `--member` and `--format json`.
+# The number is the module's, not this script's: two commands gate on it.
+CHECKER_FLOOR=$(node "$PACKAGE_ROOT/lib/test-package.js" --floor)
 
 # ── The unit is the workspace package, not the repository ────────────────────
 # Every gate measures from the NEAREST package.json. A single-package project
@@ -130,12 +138,50 @@ nearest_package_dir() {
     done
 }
 
-# The @jterrazz/test conventions checker (D4 tokens, C8/C9 fixtures) runs only when the
-# owning package depends on @jterrazz/test — auto-detected from its package.json.
+# The @jterrazz/test conventions checker (D4 tokens, C8/C9 fixtures) runs where
+# the package is a consumer, and a package is one on either evidence: its own
+# manifest names @jterrazz/test, or it RESOLVES one from an ancestor — which is
+# what npm's hoisting makes of a monorepo, where a workspace declares the
+# dependency once at the root and every member loads it.
 project_uses_jterrazz_test() {
     local dir="${1:-.}"
     [ -f "$dir/package.json" ] || return 1
-    node -e 'const {readFileSync}=require("node:fs");const p=JSON.parse(readFileSync(process.argv[1],"utf8"));const d={...p.dependencies,...p.devDependencies,...p.peerDependencies};process.exit(d["@jterrazz/test"]?0:1)' "$dir/package.json" 2>/dev/null
+    node -e 'const {readFileSync}=require("node:fs");const p=JSON.parse(readFileSync(process.argv[1],"utf8"));const d={...p.dependencies,...p.devDependencies,...p.peerDependencies};process.exit(d["@jterrazz/test"]?0:1)' "$dir/package.json" 2>/dev/null && return 0
+    node "$PACKAGE_ROOT/lib/test-package.js" "$dir" > /dev/null 2>&1
+}
+
+# A member the checker can be run FOR at all. A member that resolves an older
+# release is counted, so the pass can say once that it is dormant rather than
+# pretend it ran.
+member_resolves_checker() {
+    node "$PACKAGE_ROOT/lib/test-package.js" "${1:-.}" > /dev/null 2>&1
+}
+
+# The checker a directory RUNS, into CHECKER_COMMAND. Version and binary come
+# from the one install the directory resolves: a member whose @jterrazz/test is
+# nested rather than hoisted owns a different release from the root's, and a
+# published consumer has no `node_modules/.bin` of this package's to fall back
+# on. Returns 1 when the directory resolves nothing that answers the flags.
+member_checker() {
+    local dir="${1:-.}" bin
+    node "$PACKAGE_ROOT/lib/test-package.js" "$dir" --at-least "$CHECKER_FLOOR" \
+        > /dev/null 2>&1 || return 1
+    bin=$(node "$PACKAGE_ROOT/lib/test-package.js" "$dir" --bin 2>/dev/null) || return 1
+    [ -n "$bin" ] || return 1
+    CHECKER_COMMAND=(node "$bin")
+}
+
+# The same, for the tree pass, which every release answers: no floor, and the
+# toolchain's own lookup for a project that declares @jterrazz/test without an
+# install this walk can reach.
+tree_checker() {
+    local bin
+    bin=$(node "$PACKAGE_ROOT/lib/test-package.js" "${1:-.}" --bin 2>/dev/null)
+    if [ -n "$bin" ]; then
+        CHECKER_COMMAND=(node "$bin")
+    else
+        CHECKER_COMMAND=("$CHECKER")
+    fi
 }
 
 # An Astro project, read off its manifest. `.astro` is the one file shape oxfmt
@@ -569,12 +615,16 @@ run_checks() {
         done
     fi
 
-    # Conventions checker: only in check mode, once per specs root the workspace
-    # owns, gated by the package that OWNS that root — a member may depend on
-    # @jterrazz/test while the root does not, and the reverse.
+    # Conventions checker: only in check mode, and in two shapes. One run per
+    # specs root the workspace owns, gated by the package that OWNS that root —
+    # a member may use @jterrazz/test while the root does not, and the reverse.
+    # And one run per workspace member that RESOLVES @jterrazz/test, `--member`,
+    # which is the half that reaches a package owning no `specs/` at all.
     local checker_pids=()
     local checker_logs=()
     local checker_status=0
+    local checker_dormant=0
+    local checker_ratcheted=false
     if [ "$FIX_MODE" = false ]; then
         local checker_index=0
         while IFS= read -r specs_root; do
@@ -582,11 +632,32 @@ run_checks() {
             local owner
             owner=$(nearest_package_dir "$(dirname "$specs_root")") || continue
             project_uses_jterrazz_test "$owner" || continue
-            "$CHECKER" "$specs_root" > "$tmp_dir/checker-$checker_index.log" 2>&1 &
+            tree_checker "$owner"
+            "${CHECKER_COMMAND[@]}" "$specs_root" > "$tmp_dir/checker-$checker_index.log" 2>&1 &
             checker_pids+=($!)
             checker_logs+=("$tmp_dir/checker-$checker_index.log")
             checker_index=$((checker_index + 1))
         done < <(discover_specs_roots)
+
+        local member
+        for member in "." "${WORKSPACE_MEMBERS[@]}"; do
+            member_resolves_checker "$member" || continue
+            if ! member_checker "$member"; then
+                checker_dormant=$((checker_dormant + 1))
+                printf 'the member pass needs @jterrazz/test %s; %s resolves %s\n' \
+                    "$CHECKER_FLOOR" \
+                    "$([ "$member" = "." ] && printf 'this project' || printf '%s' "$member")" \
+                    "$(node "$PACKAGE_ROOT/lib/test-package.js" "$member" 2>/dev/null \
+                        || printf 'none this walk reaches')" \
+                    >> "$tmp_dir/checker-dormant.log"
+                continue
+            fi
+            "${CHECKER_COMMAND[@]}" --member "$member" \
+                > "$tmp_dir/checker-$checker_index.log" 2>&1 &
+            checker_pids+=($!)
+            checker_logs+=("$tmp_dir/checker-$checker_index.log")
+            checker_index=$((checker_index + 1))
+        done
     fi
 
     # Docs (sync): only in check mode, and only for a package that has generated
@@ -629,8 +700,19 @@ run_checks() {
             "$OXLINT" --type-aware --format json "${LINT_ARGS[@]}" \
                 > "$tmp_dir/lint.json" 2>/dev/null
         fi
+        # The other reporter on the same tree. Where the installed
+        # @jterrazz/test answers `--format json`, its findings are counted
+        # under their own namespace in the same file — one ratchet, two
+        # rulebooks, and a rule at zero refused on either side.
+        local baseline_checker=()
+        if member_checker .; then
+            "${CHECKER_COMMAND[@]}" --format json > "$tmp_dir/checker.json" 2>/dev/null || true
+            baseline_checker=(--checker "$tmp_dir/checker.json")
+            [ -f "$BASELINE_FILE" ] && checker_ratcheted=true
+        fi
+
         node "$PACKAGE_ROOT/lib/check-baseline.js" "$tmp_dir/lint.json" . \
-            >> "$tmp_dir/lint.log" 2>&1
+            "${baseline_checker[@]}" >> "$tmp_dir/lint.log" 2>&1
         lint_status=$?
     fi
 
@@ -657,6 +739,15 @@ run_checks() {
         index=$((index + 1))
     done
 
+    # The ratchet is the verdict for BOTH reporters or for neither. The
+    # checker's findings were counted into `oxlint.baseline.json` under their
+    # own namespace, so an id that has not moved is recorded debt here exactly
+    # as it is in the oxlint pass, and refusing it here would fail one debt
+    # twice. The log still prints: debt a reader cannot see is debt nobody pays.
+    if [ "$checker_ratcheted" = true ]; then
+        checker_status=0
+    fi
+
     local publish_failed_logs=()
     index=0
     for pid in "${publish_pids[@]}"; do
@@ -686,6 +777,25 @@ run_checks() {
     join_logs "$tmp_dir/docs.log" "${docs_failed_logs[@]}"
     join_logs "$tmp_dir/publish.log" "${publish_failed_logs[@]}"
 
+    # Two things this pass says even when it is green, so it asks for its log
+    # the way a writer does: which findings the ratchet is holding, and which
+    # member resolves a release too old to answer `--member` — a reader left
+    # with silence would believe every member was asked.
+    local checker_write=""
+    if [ "$checker_ratcheted" = true ] && [ -s "$tmp_dir/checker.log" ]; then
+        printf '%s is this pass'"'"'s verdict too — what follows is recorded debt\n\n' \
+            "$BASELINE_FILE" | cat - "$tmp_dir/checker.log" > "$tmp_dir/checker-reported.log"
+        mv "$tmp_dir/checker-reported.log" "$tmp_dir/checker.log"
+    fi
+    if [ "$checker_dormant" -gt 0 ]; then
+        cat "$tmp_dir/checker-dormant.log" "$tmp_dir/checker.log" \
+            > "$tmp_dir/checker-reported.log"
+        mv "$tmp_dir/checker-reported.log" "$tmp_dir/checker.log"
+    fi
+    if [ "$checker_dormant" -gt 0 ] || [ "$checker_ratcheted" = true ]; then
+        checker_write="writer"
+    fi
+
     local lint_label="Oxlint Check"
     local format_label="Oxfmt Check"
     local write=""
@@ -703,8 +813,9 @@ run_checks() {
         report_pass "Gitignore (artefacts)" $gitignore_status "$tmp_dir/gitignore.log" writer
     [ "$FIX_MODE" = false ] &&
         report_pass "Knip (unused code)" $knip_status "$tmp_dir/knip.log"
-    [ ${#checker_pids[@]} -gt 0 ] &&
-        report_pass "Test Conventions (@jterrazz/test)" $checker_status "$tmp_dir/checker.log"
+    { [ ${#checker_pids[@]} -gt 0 ] || [ "$checker_dormant" -gt 0 ]; } &&
+        report_pass "Test Conventions (@jterrazz/test)" $checker_status "$tmp_dir/checker.log" \
+            "$checker_write"
     [ -n "$docs_layout_pid" ] &&
         report_pass "Docs (layout)" $docs_layout_status "$tmp_dir/docs-layout.log"
     [ ${#docs_pids[@]} -gt 0 ] &&

package/bin/typescript.sh

@@ -204,7 +204,7 @@ case "$COMMAND" in
         # 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"
+        exec node "$PACKAGE_ROOT/lib/doctor.js" "$PROJECT_ROOT"
         ;;
 
     baseline)
@@ -225,7 +225,28 @@ case "$COMMAND" in
         # 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 conventions checker judges the same tree from the other side, and
+        # a project adopting a stricter version of THAT rulebook needs the same
+        # ratchet. Its findings enter the one file under their own namespace,
+        # where the installed @jterrazz/test answers `--format json`.
+        # Binary and version come from the one install this project resolves —
+        # the same answer `check` reads, from the same module, so the file is
+        # recorded by the checker that will later be judged against it.
+        CHECKER_ARGS=()
+        CHECKER_FLOOR=$(node "$PACKAGE_ROOT/lib/test-package.js" --floor)
+        if node "$PACKAGE_ROOT/lib/test-package.js" . --at-least "$CHECKER_FLOOR" \
+            > /dev/null 2>&1; then
+            CHECKER=$(node "$PACKAGE_ROOT/lib/test-package.js" . --bin 2>/dev/null || true)
+            if [ -n "$CHECKER" ]; then
+                CHECKER_REPORT=$(mktemp)
+                trap 'rm -f "$BASELINE_REPORT" "$CHECKER_REPORT"' EXIT
+                node "$CHECKER" --format json > "$CHECKER_REPORT" 2>/dev/null || true
+                CHECKER_ARGS=(--checker "$CHECKER_REPORT")
+            fi
+        fi
+
+        node "$PACKAGE_ROOT/lib/check-baseline.js" "$BASELINE_REPORT" . \
+            "${CHECKER_ARGS[@]}" --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.

package/lib/check-baseline.js

@@ -18,7 +18,22 @@
  * 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]
+ * One file, two reporters. `@jterrazz/test`'s conventions checker judges the
+ * same tree from the other side — how a spec is written rather than what the
+ * code does — and a project adopting a stricter version of THAT rulebook needs
+ * the same ratchet for the same reason. Its `--format json` diagnostics are
+ * merged before the counting, under keys its own `jterrazz-check(<id>)` codes
+ * namespace (`jterrazz-check/<id>`), so one flat file records both and neither
+ * reporter can be recorded twice. Severity is not read: a finding a release
+ * ships at `warn` is exactly the debt a ratchet exists to hold down.
+ *
+ * A run made with no checker report — the installed `@jterrazz/test` is below
+ * the release that answers `--format json`, or there is none — judges the
+ * linter's entries alone. The recorded `jterrazz-check/*` entries are set aside
+ * rather than read as debts that reached zero: nothing measured them, and the
+ * third refusal below would otherwise delete a file the next install needs.
+ *
+ * Usage: node check-baseline.js <oxlint-json> [root] [--checker <json>] [--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
@@ -32,6 +47,9 @@ 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';
 
+/** The namespace the conventions checker's ids take in the file. */
+const CHECKER_NAMESPACE = 'jterrazz-check/';
+
 /** `eslint(no-debugger)` is how oxlint's JSON spells `eslint/no-debugger`. */
 function ruleOf(code) {
     const match = /^(?<plugin>[\w-]+)\((?<rule>[^)]+)\)$/u.exec(code ?? '');
@@ -39,12 +57,28 @@ function ruleOf(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) {
+/**
+ * The diagnostics a report carries, whichever reporter wrote it. oxlint hands
+ * back an object with a `diagnostics` array; the conventions checker's
+ * `--format json` is read in both shapes it may take, so the merge does not
+ * depend on one of them staying fixed.
+ */
+export function diagnosticsOf(report) {
+    if (Array.isArray(report)) {
+        return report;
+    }
+
+    return Array.isArray(report?.diagnostics) ? report.diagnostics : [];
+}
+
+/** How many diagnostics each rule accounts for, across every report given. */
+export function countsOf(...reports) {
     const counts = {};
-    for (const diagnostic of report.diagnostics ?? []) {
-        const rule = ruleOf(diagnostic.code);
-        counts[rule] = (counts[rule] ?? 0) + 1;
+    for (const report of reports) {
+        for (const diagnostic of diagnosticsOf(report)) {
+            const rule = ruleOf(diagnostic.code);
+            counts[rule] = (counts[rule] ?? 0) + 1;
+        }
     }
 
     return counts;
@@ -100,7 +134,11 @@ function serialise(counts) {
 /* 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 checkerIndex = argv.indexOf('--checker');
+    const checkerPath = checkerIndex === -1 ? undefined : argv[checkerIndex + 1];
+    const positional = argv
+        .slice(2)
+        .filter((argument, index) => !argument.startsWith('--') && index + 2 !== checkerIndex + 1);
     const reportPath = positional[0];
     const root = resolve(positional[1] ?? '.');
 
@@ -114,7 +152,24 @@ if (import.meta.main) {
         exit(1);
     }
 
-    const counts = countsOf(report);
+    /*
+     * The checker's report is optional and its absence is not a failure: the
+     * flag is passed only where the installed @jterrazz/test answers
+     * `--format json`, and a project on an older one keeps an oxlint-only file.
+     */
+    let checkerReport = [];
+    if (checkerPath !== undefined) {
+        try {
+            checkerReport = JSON.parse(readFileSync(checkerPath, 'utf8'));
+        } catch {
+            stdout.write(
+                `the conventions checker wrote no JSON report at ${checkerPath} — the baseline cannot be read\n`,
+            );
+            exit(1);
+        }
+    }
+
+    const counts = countsOf(report, checkerReport);
 
     if (isWrite) {
         const total = Object.values(counts).reduce((sum, count) => sum + count, 0);
@@ -125,7 +180,18 @@ if (import.meta.main) {
         exit(0);
     }
 
-    const baseline = readBaseline(root);
+    const recorded = readBaseline(root);
+
+    /*
+     * Nobody measured the checker's side of the file on this run, so nobody
+     * gets to say its debts are paid.
+     */
+    const baseline =
+        recorded === null || checkerPath !== undefined
+            ? recorded
+            : Object.fromEntries(
+                  Object.entries(recorded).filter(([rule]) => !rule.startsWith(CHECKER_NAMESPACE)),
+              );
 
     if (baseline === null) {
         const rules = Object.keys(counts).toSorted();

package/lib/check-gitignore.js

@@ -12,8 +12,9 @@
  * Two files are read, each judged by the same rules: the package's own
  * `.gitignore`, and the nearest ANCESTOR `.gitignore` above it — the workspace
  * root's, found by walking up to the nearest directory holding a lockfile or a
- * `workspaces` manifest. A workspace whose `lint` delegates to members runs this
- * gate once per member, cwd'd there; without the ancestor a root that ignores
+ * `workspaces` manifest, and never past the nearest repository boundary. A
+ * workspace whose `lint` delegates to members runs this gate once per member,
+ * cwd'd there; without the ancestor a root that ignores
  * `.artifacts/` for everyone would look, from a member with no `.gitignore` of
  * its own, exactly like a project declaring nothing. An ancestor pattern counts
  * only when it is NOT anchored to the ancestor's own directory (no `/` besides a
@@ -43,6 +44,8 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { argv, exit, stdout } from 'node:process';
 
+import { isRepositoryRoot } from './repository-root.js';
+
 /** The convention's own directory: the one path that MUST be ignored. */
 const ARTIFACTS = '.artifacts';
 
@@ -56,11 +59,10 @@ const PRODUCT = 'dist';
 const ARTEFACT_DIRECTORIES = new Map([
     ['.cache', '.artifacts/<tool>/'],
     ['.next', '.artifacts/next/'],
-    ['.turbo', '.artifacts/turbo/'],
     ['.vite', '.artifacts/vite/'],
     ['bin', '.artifacts/go/'],
     ['build', '.artifacts/<tool>/'],
-    ['coverage', '.artifacts/coverage/'],
+    ['coverage', '.artifacts/vitest/coverage/'],
     ['out', '.artifacts/next/'],
     ['playwright-report', '.artifacts/playwright/'],
     ['target', '.artifacts/cargo/'],
@@ -83,6 +85,10 @@ const EXCEPTIONS = new Set([
     '.expo',
     '.gradle',
     '.swiftpm',
+    // Turborepo writes `<package>/.turbo/turbo-<task>.log` and offers no key,
+    // flag or environment variable to move it; only its cache obeys `cacheDir`,
+    // whose home stays `.artifacts/turbo/`.
+    '.turbo',
     '.vercel',
     'DerivedData',
     'Package.resolved',
@@ -168,15 +174,27 @@ function isWorkspaceRoot(dir) {
  * The nearest ancestor ABOVE `root` that is a workspace root, or null. Never
  * `root` itself — a project reads its OWN `.gitignore` regardless, so only
  * what sits above it is worth a second file.
+ *
+ * The walk stops at the nearest repository boundary and never passes it
+ * ([repository-root.js](repository-root.js)). `root` carrying its own `.git`
+ * therefore has no ancestor at all: it IS the repository.
  */
 function findWorkspaceRoot(root) {
-    let dir = dirname(resolve(root));
+    const start = resolve(root);
+    if (isRepositoryRoot(start)) {
+        return null;
+    }
+
+    let dir = dirname(start);
     let parent = dirname(dir);
 
     while (dir !== parent) {
         if (isWorkspaceRoot(dir)) {
             return dir;
         }
+        if (isRepositoryRoot(dir)) {
+            return null;
+        }
         dir = parent;
         parent = dirname(dir);
     }

package/lib/doctor.js

@@ -9,20 +9,31 @@
  * 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
+ * Usage: node doctor.js [project root]
  *
  * 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.
+ * Then one section the PROJECT owns rather than the toolchain: a pair of
+ * packages that must be pinned to the same version, read off the project's
+ * lockfile. Vitest's browser provider is published from vitest's own
+ * repository and versioned with it — a provider a patch away from the runner
+ * loads a second copy of vitest's internals and fails at run time, in the
+ * browser, with a stack nobody reads as a version skew. The lockfile is the
+ * right file for this one question: it says what a fresh install resolves,
+ * which is what a runner will get, where a range says only what was allowed.
+ *
+ * Exit code: 0 when nothing is old, absent or skewed, 1 otherwise.
  */
 
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { resolve } from 'node:path';
-import process, { exit, stdout } from 'node:process';
+import { join, resolve } from 'node:path';
+import process, { argv, cwd, exit, stdout } from 'node:process';
+
+import { workspaceMembers } from './workspace-members.js';
 
 const require = createRequire(import.meta.url);
 const PACKAGE_ROOT = resolve(import.meta.dirname, '..');
@@ -155,8 +166,157 @@ export function toolVersions() {
     }));
 }
 
+/**
+ * The pair a browser-mode consumer must keep equal, and the reason the check
+ * exists at all: `@vitest/browser-playwright` ships from vitest's repository
+ * and carries vitest's version, so anything but an exact match is a skew.
+ */
+export const PINNED_PAIR = Object.freeze({
+    provider: '@vitest/browser-playwright',
+    runner: 'vitest',
+});
+
+/** Every version an npm lockfile resolves for one name: `node_modules/<name>` keys. */
+function npmVersions(text, name) {
+    const suffix = `node_modules/${name}`;
+    const versions = new Set();
+
+    for (const [path, entry] of Object.entries(JSON.parse(text).packages ?? {})) {
+        if ((path === suffix || path.endsWith(`/${suffix}`)) && typeof entry.version === 'string') {
+            versions.add(entry.version);
+        }
+    }
+
+    return versions;
+}
+
+/**
+ * The same, off a `bun.lock`. The file is JSON with trailing commas, and every
+ * entry of its `packages` map opens on the `<name>@<version>` the install
+ * resolved — so the one comma rule is dropped and the rest is read as JSON.
+ */
+function bunVersions(text, name) {
+    const versions = new Set();
+    const { packages } = JSON.parse(text.replaceAll(/,(?<trailing>\s*[\]}])/gu, '$<trailing>'));
+
+    for (const [key, entry] of Object.entries(packages ?? {})) {
+        const descriptor = Array.isArray(entry) ? entry[0] : entry;
+        if ((key === name || key.endsWith(`/${name}`)) && typeof descriptor === 'string') {
+            versions.add(descriptor.slice(descriptor.lastIndexOf('@') + 1));
+        }
+    }
+
+    return versions;
+}
+
+/** Lockfiles this report can read, in the order a resolver would find them. */
+const READ_LOCKFILES = [
+    ['package-lock.json', npmVersions],
+    ['npm-shrinkwrap.json', npmVersions],
+    ['bun.lock', bunVersions],
+];
+
+/** Lockfiles it cannot: a binary file and two YAML dialects, none of them JSON. */
+const UNREAD_LOCKFILES = ['bun.lockb', 'pnpm-lock.yaml', 'yarn.lock'];
+
+/** Every version a readable lockfile resolves for one name, deduplicated and sorted. */
+function lockedVersions(path, read, name) {
+    try {
+        return [...read(readFileSync(path, 'utf8'), name)].toSorted((left, right) =>
+            left < right ? -1 : 1,
+        );
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Whether a package is declared under any dependency key of the project's
+ * manifest or of any workspace member's — the provider belongs to whichever
+ * package runs browser mode, and in a monorepo that is a member, not the root.
+ */
+function declaredAnywhere(root, name) {
+    return ['.', ...workspaceMembers(root)].some((member) => {
+        try {
+            const pkg = manifestAt(join(root, member, 'package.json'));
+            return (
+                { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies }[name] !==
+                undefined
+            );
+        } catch {
+            return false;
+        }
+    });
+}
+
+/**
+ * What the project's lockfile says about the pinned pair. `null` when there is
+ * no question to answer — no lockfile this report reads, and no provider
+ * declared under one it does not.
+ */
+export function pinnedPair(root) {
+    const readable = READ_LOCKFILES.map(([name, read]) => [join(root, name), read]).find(([path]) =>
+        existsSync(path),
+    );
+
+    if (readable === undefined) {
+        const unread = UNREAD_LOCKFILES.find((name) => existsSync(join(root, name)));
+        if (unread !== undefined && declaredAnywhere(root, PINNED_PAIR.provider)) {
+            return { unread, verdict: 'unread' };
+        }
+
+        return null;
+    }
+
+    const provider = lockedVersions(readable[0], readable[1], PINNED_PAIR.provider);
+    if (provider === null || provider.length === 0) {
+        return null;
+    }
+
+    const runner = lockedVersions(readable[0], readable[1], PINNED_PAIR.runner) ?? [];
+    const matched = runner.length === 1 && provider.length === 1 && runner[0] === provider[0];
+
+    return { provider, runner, verdict: matched ? 'ok' : 'skewed' };
+}
+
+/** Every version a name resolves to, in one column — `—` when the lockfile has none. */
+function versionColumn(versions) {
+    return versions.length === 0 ? '—' : versions.join(', ');
+}
+
+/** The pinned-pair section, or nothing at all when the project asks no question. */
+function reportPinnedPair(root) {
+    const pair = pinnedPair(root);
+    if (pair === null) {
+        return false;
+    }
+
+    stdout.write('\nPinned together\n\n');
+
+    if (pair.verdict === 'unread') {
+        stdout.write(
+            `  ${PINNED_PAIR.provider.padEnd(28)}${pair.unread} is not parsed here — the pin is unchecked\n\n`,
+        );
+        return false;
+    }
+
+    stdout.write(`  ${PINNED_PAIR.runner.padEnd(28)}${versionColumn(pair.runner)}\n`);
+    stdout.write(
+        `  ${PINNED_PAIR.provider.padEnd(28)}${versionColumn(pair.provider).padEnd(12)}${pair.verdict}\n\n`,
+    );
+
+    if (pair.verdict === 'skewed') {
+        stdout.write(
+            `${PINNED_PAIR.provider} is versioned with ${PINNED_PAIR.runner} and must equal it exactly — pin both to the same version.\n`,
+        );
+    }
+
+    return pair.verdict === 'skewed';
+}
+
 /* Imported for `toolVersions`, run for the report — never both at once. */
 if (import.meta.main) {
+    const root = resolve(argv[2] ?? cwd());
     const rows = toolVersions();
     const failed = rows.some(({ verdict }) => verdict === 'old' || verdict === 'absent');
     const warned = rows.some(({ verdict }) => verdict === 'newer');
@@ -181,5 +341,7 @@ if (import.meta.main) {
         stdout.write('Every tool is in range.\n');
     }
 
-    exit(failed ? 1 : 0);
+    const skewed = reportPinnedPair(root);
+
+    exit(failed || skewed ? 1 : 0);
 }

package/lib/repository-root.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+/**
+ * Where one repository ends, for every gate that walks upward.
+ *
+ * A gate that reads a file above the project it runs in — the artefact gate
+ * looking for the workspace `.gitignore`, the dependency walk looking for an
+ * installed package — must stop somewhere, and the only honest stop is the
+ * repository. A clone checked out INSIDE another tree (a workbench under
+ * `home/<brand>/work/`, a vendored dependency) is not a member of the tree it
+ * happens to sit in, and what lies above answers for a project whose files are
+ * none of this one's business.
+ *
+ * `.git` is that boundary in both spellings it takes: a DIRECTORY in a clone,
+ * a FILE in a worktree.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Whether `dir` is a repository root — a `.git` beside it, file or directory. */
+export function isRepositoryRoot(dir) {
+    return existsSync(join(dir, '.git'));
+}

package/lib/test-package.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+
+/**
+ * The `@jterrazz/test` a package would LOAD, and the checker binary that comes
+ * with it — found the way node finds them, from the package outward.
+ *
+ * A package is a consumer of what it can RESOLVE, not of what it names: npm
+ * hoists a workspace's shared devDependency to the root, so a member declaring
+ * nothing still loads it. Version and binary are answered from the one install
+ * the walk lands on, so a workspace whose members hold different releases is
+ * never judged by whichever one the root happens to carry.
+ *
+ * The lookup is the ancestor walk itself rather than `require.resolve`: the
+ * package's `exports` map does not publish `./package.json`, so the resolver
+ * refuses the one path that carries the version.
+ *
+ * The walk stops at the nearest repository boundary
+ * ([repository-root.js](repository-root.js)): a clone sitting inside another
+ * tree loads its own install or none, and the estate's `node_modules` never
+ * makes a consumer of a project that declares nothing.
+ *
+ * Usage: node test-package.js <dir> [--at-least <version>]
+ *        node test-package.js <dir> --bin
+ *        node test-package.js --floor
+ *
+ * Prints the resolved version — or, with `--bin`, the absolute path of the
+ * checker entry the install declares. Exit code: 0 when it resolves — and,
+ * with `--at-least`, when it is that version or newer — 1 otherwise. `--floor`
+ * prints the release the checker's own flags arrive in, so the callers that
+ * gate on it read one number rather than each keeping a copy.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { argv, exit, stdout } from 'node:process';
+
+import { isRepositoryRoot } from './repository-root.js';
+
+/** The package every lookup here is about. */
+const PACKAGE = '@jterrazz/test';
+
+/** The binary it publishes, and the one the quality checks run. */
+const CHECKER_BIN = 'jterrazz-test-check';
+
+/**
+ * The release that answers the flags `typescript check` and `typescript
+ * baseline` call it with — `--member` and `--format json`. Below it both are
+ * skipped, and the gates say so rather than pretending they ran.
+ */
+export const CHECKER_FLOOR = '15.3.0';
+
+/** `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 install of `@jterrazz/test` reachable from `dir` — its directory and its
+ * manifest — or null. Every `node_modules` from the directory up to the
+ * repository boundary is asked, nearest first, which is the order node itself
+ * resolves in.
+ */
+export function resolveTestPackage(dir) {
+    let current = resolve(dir);
+
+    while (true) {
+        const installed = join(current, 'node_modules', PACKAGE);
+        const manifest = join(installed, 'package.json');
+        if (existsSync(manifest)) {
+            try {
+                return { dir: installed, manifest: JSON.parse(readFileSync(manifest, 'utf8')) };
+            } catch {
+                return null;
+            }
+        }
+
+        const parent = dirname(current);
+        if (isRepositoryRoot(current) || parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+
+/** The version of `@jterrazz/test` reachable from `dir`, or null. */
+export function testPackageVersion(dir) {
+    const { manifest } = resolveTestPackage(dir) ?? {};
+
+    return typeof manifest?.version === 'string' ? manifest.version : null;
+}
+
+/**
+ * The conventions checker `dir` would run, or null. It is the entry the SAME
+ * install declares, not a name on PATH: a `node_modules/.bin` shim answers for
+ * whichever member npm hoisted to, and PATH answers for nothing at all in a
+ * published install.
+ */
+export function testPackageBin(dir) {
+    const resolved = resolveTestPackage(dir);
+    if (resolved === null) {
+        return null;
+    }
+
+    const { bin } = resolved.manifest;
+    const entry = typeof bin === 'string' ? bin : bin?.[CHECKER_BIN];
+    if (typeof entry !== 'string') {
+        return null;
+    }
+
+    const path = join(resolved.dir, entry);
+
+    return existsSync(path) ? path : null;
+}
+
+/** Whether what `dir` resolves is at least `floor`. */
+export function testPackageAtLeast(dir, floor) {
+    const version = testPackageVersion(dir);
+
+    return version !== null && compare(version, floor) >= 0;
+}
+
+/* Imported for the walk, run for the answer — never both at once. */
+if (import.meta.main) {
+    if (argv.includes('--floor')) {
+        stdout.write(`${CHECKER_FLOOR}\n`);
+        exit(0);
+    }
+
+    const floorIndex = argv.indexOf('--at-least');
+    const floor = floorIndex === -1 ? null : (argv[floorIndex + 1] ?? null);
+    const dir =
+        argv
+            .slice(2)
+            .find(
+                (argument, index) => !argument.startsWith('--') && index + 2 !== floorIndex + 1,
+            ) ?? '.';
+
+    if (argv.includes('--bin')) {
+        const bin = testPackageBin(dir);
+        if (bin === null) {
+            exit(1);
+        }
+
+        stdout.write(`${bin}\n`);
+        exit(0);
+    }
+
+    const version = testPackageVersion(dir);
+    if (version === null) {
+        exit(1);
+    }
+
+    stdout.write(`${version}\n`);
+    exit(floor === null || compare(version, floor) >= 0 ? 0 : 1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jterrazz/typescript",
-    "version": "10.1.9",
+    "version": "10.2.0",
     "license": "MIT",
     "author": "Jean-Baptiste Terrazzoni <contact@jterrazz.com>",
     "repository": {

package/rules/catalog.js

@@ -89,7 +89,7 @@ export function render() {
 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 why = entry.level === 'off' ? reasonClause(entry.reason) : agentScopeOf(entry);
         const where = entry.profiles.length === EVERY_PROFILE ? 'all' : entry.profiles.join(', ');
 
         return `| \`${entry.rule}\` | ${state} | ${why} | ${where} |`;
@@ -98,6 +98,25 @@ export function renderReference() {
     return ['| Rule | State | Why | Profiles |', '| --- | --- | --- | --- |', ...rows].join('\n');
 }
 
+/** Where the vitest fragment applies, named by its owner rather than spelled out. */
+const TEST_FILE_ROUTE = "scoped to test files — @jterrazz/test's catalogue owns the shapes";
+
+/**
+ * The scope an AGENT is owed. Seventy-odd vitest rows each restated the same
+ * three globs, and one of them — the `__tests__` directory shape — is a layout
+ * the test package's own rulebook refuses: a page an agent reads to decide
+ * where to put a file would have been advertising it seventy times. So the
+ * vitest block names its owner and the agent goes there for the shapes, which
+ * is the package that decides them.
+ */
+function agentScopeOf(entry) {
+    if (entry.fragment === 'vitest' && entry.scoped !== undefined) {
+        return TEST_FILE_ROUTE;
+    }
+
+    return scopeOf(entry);
+}
+
 /** An `off` in one clause: its kind, and the first thing its reason names. */
 function reasonClause({ by, kind }) {
     return `${kind}: ${by.split(' — ')[0]}`;

package/rules/catalog.test.ts

@@ -66,6 +66,16 @@ test('every decision carries the version it was taken in', () => {
     }
 });
 
+test('the skill reference routes the vitest scope instead of restating it', () => {
+    // Given - the projection an agent reads
+    const reference = renderReference();
+
+    // Then - the vitest block names its owner, and no row spells a glob out
+    expect(reference).toContain("@jterrazz/test's catalogue owns the shapes");
+    expect(reference).not.toContain('__tests__');
+    expect(reference).not.toContain('{test,spec,test-d,spec-d}');
+});
+
 test.each(Object.entries(PROJECTIONS))(
     'the %s carries the catalogue the manifest renders',
     (_name, { markers, page, render: project }) => {

package/rules/core/typescript.js

@@ -37,6 +37,23 @@ export default fragment({
             files: ['**/*.js', '**/*.cjs', '**/*.mjs'],
             rules: Object.fromEntries(UNTYPED_IN_JAVASCRIPT),
         }),
+        /*
+         * A declaration file is where module augmentation lives, and only an
+         * interface merges into an existing one: a `type` alias REDECLARES the
+         * name and every member of the original is lost. A `.ts` file carrying
+         * an augmentation is still reported — the scope is the file's purpose,
+         * and oxlint scopes by path — and answers with a suppression.
+         */
+        scoped({
+            files: ['**/*.d.ts'],
+            rules: {
+                'typescript/consistent-type-definitions': off({
+                    by: 'TypeScript — an augmentation merges only as an interface, and a declaration file is where augmentations live',
+                    kind: 'covered',
+                }),
+            },
+            since: '10.2.0',
+        }),
     ],
     rules: {
         ...allOn(