@jterrazz/typescript 6.1.1 → 7.0.0

package/README.md

@@ -8,150 +8,21 @@ The complete TypeScript toolchain — build, run, check, and document with zero
 npm install @jterrazz/typescript --save-dev
 ```
 
-## Setup
-
-### 1. Choose a TypeScript configuration
-
-```json
-// tsconfig.json - Pick one:
-{ "extends": "@jterrazz/typescript/tsconfig/node" }  // Node.js projects
-{ "extends": "@jterrazz/typescript/tsconfig/next" }  // Next.js projects
-{ "extends": "@jterrazz/typescript/tsconfig/expo" }  // Expo/React Native
-```
-
-### 2. Create the lint and format configs
-
-```ts
-// oxlint.config.ts
-import { oxlint } from '@jterrazz/typescript';
-import { defineConfig } from 'oxlint';
-
-export default defineConfig({
-    extends: [oxlint.node],
-});
-```
-
-```ts
-// oxfmt.config.ts
-import { oxfmt } from '@jterrazz/typescript';
-import { defineConfig } from 'oxfmt';
-
-export default defineConfig(oxfmt);
-```
-
-### 3. Use the CLI
+## The CLI
 
 ```bash
 npx typescript build       # Build application (ESM + types)
 npx typescript bundle      # Bundle library (ESM + CJS + types)
 npx typescript start       # Run the built application
 npx typescript dev         # Build, run, and rebuild on changes
-npx typescript docs        # Generate API reference + llms.txt
-npx typescript check       # Check types, lint, formatting, and unused code
+npx typescript docs        # Compile the committed docs/reference tree from source
+npx typescript check       # Type-check, lint, format-check, and unused-code in parallel
 npx typescript fix         # Auto-fix lint and formatting issues
 ```
 
-## Building
-
-- **Blazing fast** — Powered by [tsdown](https://tsdown.dev) / [Rolldown](https://rolldown.rs) (Rust)
-- **Zero configuration** — Works out of the box
-- **Multiple outputs** — ESM + CommonJS + TypeScript declarations
-- **Source maps** — Full debugging support
-
-| Command             | Output            | Description              |
-| ------------------- | ----------------- | ------------------------ |
-| `typescript build`  | `dist/index.js`   | ESM bundle               |
-|                     | `dist/index.d.ts` | TypeScript declarations  |
-| `typescript bundle` | `dist/index.js`   | ESM bundle               |
-|                     | `dist/index.cjs`  | CommonJS bundle          |
-|                     | `dist/index.d.ts` | TypeScript declarations  |
-| `typescript start`  | —                 | Runs `dist/index.js`     |
-| `typescript dev`    | `dist/index.js`   | Watch + rebuild + run    |
-| `typescript docs`   | `.docs/`          | API reference + llms.txt |
-
-### Project structure
-
-```
-your-project/
-├── src/
-│   ├── index.ts           # Main entry point
-│   └── instrumentation.ts # Optional instrumentation entry point
-├── dist/                  # Generated files
-└── tsconfig.json          # Extends this package
-```
-
-## Quality checks
-
-`typescript check` runs four tools in parallel:
-
-| Tool   | Purpose              |
-| ------ | -------------------- |
-| tsc    | Type checking        |
-| oxlint | Linting              |
-| oxfmt  | Formatting           |
-| knip   | Unused code analysis |
-
-`typescript fix` runs tsc, oxlint (with `--fix`), and oxfmt in parallel (knip excluded).
-
-### Lint presets
-
-| Preset        | Use Case                          |
-| ------------- | --------------------------------- |
-| `oxlint.node` | Node.js (requires .js extensions) |
-| `oxlint.expo` | Expo / React Native               |
-| `oxlint.next` | Next.js                           |
-
-### Architecture enforcement
-
-Enforce hexagonal architecture boundaries with the additive `oxlint.hexagonal` preset:
-
-```ts
-import { oxlint } from '@jterrazz/typescript';
-import { defineConfig } from 'oxlint';
-
-export default defineConfig({
-    extends: [oxlint.node, oxlint.hexagonal],
-});
-```
-
-Rules enforced:
-
-- `domain/` cannot import from other layers
-- `application/` cannot import infrastructure
-- `presentation/ui/` cannot import navigation
-- `features/` cannot import other features
-
-### Unused code detection
-
-`typescript check` runs [Knip](https://knip.dev/) to detect unused files, exports, and dependencies. A base config is automatically merged with any project-local `knip.json`, handling common ecosystem patterns:
-
-- `@jterrazz/*` packages auto-ignored
-- Published libraries: `exports`/`types`/`files` rules auto-disabled
-- Convention paths (`fixtures/`, `expected/`, `docs/`) auto-ignored
-- Plugin dependencies (`*-plugin-*`, `@scope/*`) auto-ignored
-
-For fine-tuning, create a `knip.json` with only project-specific overrides.
-
-## API docs generation
-
-`typescript docs` reads TSDoc from `src/index.ts` and generates:
-
-- **Typedoc markdown** — Full API reference under `.docs/`
-- **`llms.txt`** — Structured index following the [llms.txt standard](https://llmstxt.org/)
-- **`llms-full.txt`** — Complete reference in one file for LLM context windows
-
-No `typedoc.json` needed. Pair with the shared CI workflow to auto-deploy:
-
-```yaml
-# .github/workflows/docs.yaml
-jobs:
-    docs:
-        uses: jterrazz/jterrazz-actions/.github/workflows/docs.yaml@main
-```
-
 ## How it works
 
-The toolchain is fully compiled — no JavaScript in the hot path:
+Fully compiled — no JavaScript in the hot path:
 
 | Step         | Tool                                                             | Language |
 | ------------ | ---------------------------------------------------------------- | -------- |
@@ -164,6 +35,19 @@ The toolchain is fully compiled — no JavaScript in the hot path:
 | Unused code  | [Knip](https://knip.dev)                                         | Node     |
 | API docs     | [Typedoc](https://typedoc.org)                                   | Node     |
 
+## Documentation
+
+The full corpus lives in [`docs/`](docs/):
+
+- [Getting started](docs/01-getting-started.md) — install and configure a project.
+- [Building](docs/02-building.md) — `build`, `bundle`, `start`, `dev`.
+- [Quality checks](docs/03-quality-checks.md) — `check` / `fix` and their passes.
+- [Lint presets](docs/04-lint-presets.md) — oxlint presets, `compose`, architecture, knip.
+- [Docs pipeline](docs/05-docs-pipeline.md) — the `typescript docs` compiler.
+- [Repo structure](docs/06-repo-structure.md) — the corpus / injection / compiler doctrine.
+
+For agents: read the chapters and the generated [`docs/reference/`](docs/reference/) tree straight from the repo, plus two Claude Code skills — [`skills/jterrazz-typescript`](skills/jterrazz-typescript/SKILL.md) (the toolchain) and [`skills/jterrazz-repo-structure`](skills/jterrazz-repo-structure/SKILL.md) (the repo doctrine).
+
 ## License
 
 MIT © [Jean-Baptiste Terrazzoni](https://github.com/jterrazz)

package/bin/commands/check.sh

@@ -66,6 +66,41 @@ TSC=$(find_tsc)
 OXLINT=$(find_binary oxlint)
 OXFMT=$(find_binary oxfmt)
 KNIP=$(find_binary knip)
+CHECKER=$(find_binary jterrazz-test-check)
+
+# The @jterrazz/test conventions checker (D4 tokens, C8/C9 fixtures) runs only when the
+# consuming project depends on @jterrazz/test — auto-detected from its package.json.
+project_uses_jterrazz_test() {
+    [ -f "package.json" ] || return 1
+    node -e 'const p=require("./package.json");const d={...p.dependencies,...p.devDependencies,...p.peerDependencies};process.exit(d["@jterrazz/test"]?0:1)' 2>/dev/null
+}
+
+# The @jterrazz/test oxlint plugin is ESM-only. A CommonJS oxlint config silently drops
+# it (oxlint prints a load warning and still exits 0) — none of the jterrazz/* rules run.
+# Warn loudly when that pitfall is detectable.
+warn_cjs_oxlint_config() {
+    local cfg=""
+    for c in oxlint.config.ts oxlint.config.mjs oxlint.config.cjs oxlint.config.js; do
+        [ -f "$c" ] && { cfg="$c"; break; }
+    done
+    [ -z "$cfg" ] && return 0
+
+    local is_cjs=false
+    case "$cfg" in
+        *.cjs) is_cjs=true ;;
+        *.js)
+            if ! node -e 'process.exit(require("./package.json").type==="module"?0:1)' 2>/dev/null; then
+                is_cjs=true
+            fi
+            ;;
+    esac
+
+    if [ "$is_cjs" = true ]; then
+        printf "${RED} WARNING ${NC} @jterrazz/test is installed but %s is CommonJS.\n" "$cfg"
+        printf "          The @jterrazz/test oxlint plugin is ESM-only and will be SILENTLY DROPPED —\n"
+        printf "          none of the jterrazz/* rules will run. Switch to an ESM config (oxlint.config.ts or .mjs).\n\n"
+    fi
+}
 
 # Parse command and args
 COMMAND=""
@@ -109,6 +144,10 @@ run_checks() {
 
     printf "${CYAN_BG}${BRIGHT_WHITE} START ${NC} ${LABEL}\n"
 
+    if project_uses_jterrazz_test; then
+        warn_cjs_oxlint_config
+    fi
+
     # Run all tools in parallel
     "$TSC" --noEmit > "$tmp_dir/type.log" 2>&1 &
     local type_pid=$!
@@ -142,33 +181,93 @@ run_checks() {
         knip_pid=$!
     fi
 
+    # Conventions checker: only in check mode, only when the project uses @jterrazz/test
+    # and has a specs/ directory to validate.
+    local checker_pid=""
+    local checker_status=0
+    if [ "$FIX_MODE" = false ] && [ -d "specs" ] && project_uses_jterrazz_test; then
+        "$CHECKER" specs > "$tmp_dir/checker.log" 2>&1 &
+        checker_pid=$!
+    fi
+
+    # Docs (sync): only in check mode, and only once the project has generated
+    # its committed docs (docs/reference/ exists — opt-in by first generation).
+    # Delegates to docs.sh --check: regenerate into a temp dir, diff the
+    # committed projections. Never duplicates the compiler's logic.
+    local docs_pid=""
+    local docs_status=0
+    if [ "$FIX_MODE" = false ] && [ -d "docs/reference" ]; then
+        bash "$SCRIPT_DIR/docs.sh" "$(pwd)" "$PACKAGE_ROOT" --check > "$tmp_dir/docs.log" 2>&1 &
+        docs_pid=$!
+    fi
+
     # Wait and collect statuses
     wait $type_pid;   local type_status=$?
     wait $lint_pid;   local lint_status=$?
     wait $format_pid; local format_status=$?
     [ -n "$knip_pid" ] && { wait $knip_pid; knip_status=$?; }
+    [ -n "$checker_pid" ] && { wait $checker_pid; checker_status=$?; }
+    [ -n "$docs_pid" ] && { wait $docs_pid; docs_status=$?; }
 
-    # Print results
+    # Print results — quiet on success, verbose on failure: a tool's captured log
+    # is shown only when it failed, so green output stays byte-identical across
+    # platforms (some tool builds print success chatter on Linux but not macOS).
     printf "\n${CYAN_BG}${BRIGHT_WHITE} RUN ${NC} TypeScript Check\n\n"
-    [ -s "$tmp_dir/type.log" ] && cat "$tmp_dir/type.log"
-    [ $type_status -ne 0 ] && printf "${RED}✗ Failed with exit code %d${NC}\n" $type_status || printf "${GREEN}✓ Passed${NC}\n"
+    if [ $type_status -ne 0 ]; then
+        [ -s "$tmp_dir/type.log" ] && cat "$tmp_dir/type.log"
+        printf "${RED}✗ Failed with exit code %d${NC}\n" $type_status
+    else
+        printf "${GREEN}✓ Passed${NC}\n"
+    fi
 
     local lint_label="Oxlint Check"
     [ "$FIX_MODE" = true ] && lint_label="Oxlint Fix"
     printf "\n${CYAN_BG}${BRIGHT_WHITE} RUN ${NC} ${lint_label}\n\n"
-    [ -s "$tmp_dir/lint.log" ] && cat "$tmp_dir/lint.log"
-    [ $lint_status -ne 0 ] && printf "${RED}✗ Failed with exit code %d${NC}\n" $lint_status || printf "${GREEN}✓ Passed${NC}\n"
+    if [ $lint_status -ne 0 ]; then
+        [ -s "$tmp_dir/lint.log" ] && cat "$tmp_dir/lint.log"
+        printf "${RED}✗ Failed with exit code %d${NC}\n" $lint_status
+    else
+        printf "${GREEN}✓ Passed${NC}\n"
+    fi
 
     local format_label="Oxfmt Check"
     [ "$FIX_MODE" = true ] && format_label="Oxfmt Format"
     printf "\n${CYAN_BG}${BRIGHT_WHITE} RUN ${NC} ${format_label}\n\n"
-    [ -s "$tmp_dir/format.log" ] && cat "$tmp_dir/format.log"
-    [ $format_status -ne 0 ] && printf "${RED}✗ Failed with exit code %d${NC}\n" $format_status || printf "${GREEN}✓ Passed${NC}\n"
+    if [ $format_status -ne 0 ]; then
+        [ -s "$tmp_dir/format.log" ] && cat "$tmp_dir/format.log"
+        printf "${RED}✗ Failed with exit code %d${NC}\n" $format_status
+    else
+        printf "${GREEN}✓ Passed${NC}\n"
+    fi
 
     if [ "$FIX_MODE" = false ]; then
         printf "\n${CYAN_BG}${BRIGHT_WHITE} RUN ${NC} Knip (unused code)\n\n"
-        [ -s "$tmp_dir/knip.log" ] && cat "$tmp_dir/knip.log"
-        [ $knip_status -ne 0 ] && printf "${RED}✗ Failed with exit code %d${NC}\n" $knip_status || printf "${GREEN}✓ Passed${NC}\n"
+        if [ $knip_status -ne 0 ]; then
+            [ -s "$tmp_dir/knip.log" ] && cat "$tmp_dir/knip.log"
+            printf "${RED}✗ Failed with exit code %d${NC}\n" $knip_status
+        else
+            printf "${GREEN}✓ Passed${NC}\n"
+        fi
+
+        if [ -n "$checker_pid" ]; then
+            printf "\n${CYAN_BG}${BRIGHT_WHITE} RUN ${NC} Test Conventions (@jterrazz/test)\n\n"
+            if [ $checker_status -ne 0 ]; then
+                [ -s "$tmp_dir/checker.log" ] && cat "$tmp_dir/checker.log"
+                printf "${RED}✗ Failed with exit code %d${NC}\n" $checker_status
+            else
+                printf "${GREEN}✓ Passed${NC}\n"
+            fi
+        fi
+
+        if [ -n "$docs_pid" ]; then
+            printf "\n${CYAN_BG}${BRIGHT_WHITE} RUN ${NC} Docs (sync)\n\n"
+            if [ $docs_status -ne 0 ]; then
+                [ -s "$tmp_dir/docs.log" ] && cat "$tmp_dir/docs.log"
+                printf "${RED}✗ Failed with exit code %d${NC}\n" $docs_status
+            else
+                printf "${GREEN}✓ Passed${NC}\n"
+            fi
+        fi
     fi
 
     # Summary
@@ -178,7 +277,7 @@ run_checks() {
         printf "\n${CYAN_BG}${BRIGHT_WHITE} END ${NC} Finalizing quality checks\n\n"
     fi
 
-    if [ $type_status -eq 0 ] && [ $lint_status -eq 0 ] && [ $format_status -eq 0 ] && [ $knip_status -eq 0 ]; then
+    if [ $type_status -eq 0 ] && [ $lint_status -eq 0 ] && [ $format_status -eq 0 ] && [ $knip_status -eq 0 ] && [ $checker_status -eq 0 ] && [ $docs_status -eq 0 ]; then
         printf "${GREEN}✓ All checks passed${NC}\n"
         exit 0
     else

package/bin/commands/docs.sh

@@ -1,15 +1,35 @@
 #!/bin/bash
-# Generate API reference + llms.txt from TypeScript source.
-# Called by: typescript docs
+# Compile the committed docs projection from TypeScript source.
+# Called by: typescript docs [--check]  (via bin/typescript.sh) and the
+# Docs (sync) pass in bin/commands/check.sh.
 #
-# Runs typedoc with sensible defaults (no typedoc.json needed),
-# then generates llms.txt (index) and llms-full.txt (full reference).
+# Projection (COMMITTED, sync-checked) — a single cross-layer compilation of
+# source into docs:
+#   docs/reference/       typedoc markdown tree (stale members vanish on regen)
+#
+# Every generated file self-identifies with a first-line header. Generation is
+# deterministic: LC_ALL=C sorts, explicit find | sort, no timestamps — two runs
+# on an unchanged repo are byte-identical (E2E-tested). `--check` regenerates
+# into a temp dir and diffs against the committed reference tree (never touching
+# the committed tree), so it is safe to run in parallel from `typescript check`.
 
 set -e
 
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
 PROJECT_ROOT="$1"
 PACKAGE_ROOT="$2"
-OUT_DIR="$PROJECT_ROOT/.docs"
+MODE="${3:-generate}" # "generate" | "--check"
+
+# Header stamped as the first line of every generated file. It is an HTML
+# comment: invisible when the markdown renders, and uniform across the whole
+# reference tree.
+GEN_HEADER="<!-- GENERATED by \`typescript docs\` — DO NOT EDIT -->"
+
+# Byte-identical output regardless of the caller's locale.
+export LC_ALL=C
 
 TYPEDOC=$(
     if [ -x "$PACKAGE_ROOT/node_modules/.bin/typedoc" ]; then
@@ -21,69 +41,104 @@ TYPEDOC=$(
     fi
 )
 
-# ── Step 1: Run typedoc ──
-
-"$TYPEDOC" \
-    --entryPoints "$PROJECT_ROOT/src/index.ts" \
-    --plugin typedoc-plugin-markdown \
-    --out "$OUT_DIR" \
-    --readme none \
-    --entryFileName index.md \
-    --hideBreadcrumbs true \
-    --hidePageHeader true \
-    --outputFileStrategy members \
-    --useCodeBlocks true \
-    --excludeInternal true \
-    --excludePrivate true \
-    --excludeProtected true \
-    --githubPages false \
-    --indexFormat table \
-    --parametersFormat table \
-    --enumMembersFormat table \
-    --typeDeclarationFormat table \
-    --tsconfig "$PROJECT_ROOT/tsconfig.json"
-
-# ── Step 2: Read package name ──
-
-PKG_NAME=$(node -e "console.log(require('$PROJECT_ROOT/package.json').name)")
-PKG_DESC=$(node -e "console.log(require('$PROJECT_ROOT/package.json').description || '')")
-
-# ── Step 3: Generate llms.txt ──
-
-{
-    echo "# $PKG_NAME"
-    echo ""
-    if [ -n "$PKG_DESC" ]; then
-        echo "> $PKG_DESC"
-        echo ""
+# Entry barrel: src/index.ts for source projects, or src/index.d.ts for
+# JS-shipped packages that carry hand-written declarations (this toolchain
+# itself is one).
+ENTRY=""
+if [ -f "$PROJECT_ROOT/src/index.ts" ]; then
+    ENTRY="$PROJECT_ROOT/src/index.ts"
+elif [ -f "$PROJECT_ROOT/src/index.d.ts" ]; then
+    ENTRY="$PROJECT_ROOT/src/index.d.ts"
+fi
+
+# Guard: nothing to compile without an entry barrel AND a docs/ corpus. In
+# --check mode a project that owns no docs is trivially in sync (exit 0).
+if [ -z "$ENTRY" ] || [ ! -d "$PROJECT_ROOT/docs" ]; then
+    if [ "$MODE" = "--check" ]; then
+        exit 0
     fi
-    echo "## API Reference"
-    echo ""
-    sed -n '/^## /,$ p' "$OUT_DIR/index.md"
-} > "$OUT_DIR/llms.txt"
-
-# ── Step 4: Generate llms-full.txt ──
-
-{
-    echo "# $PKG_NAME — Full API Reference"
-    echo ""
-    if [ -n "$PKG_DESC" ]; then
-        echo "> $PKG_DESC"
-        echo ""
+    printf "${RED}Error: 'typescript docs' needs an entry barrel and a docs/ directory.${NC}\n" >&2
+    [ -z "$ENTRY" ] && printf "       No src/index.ts or src/index.d.ts found.\n" >&2
+    [ ! -d "$PROJECT_ROOT/docs" ] && printf "       No docs/ directory found — create it with your hand-written chapters.\n" >&2
+    exit 1
+fi
+
+# Prepend the generated-file header as the first line of a file.
+prepend_header() {
+    local file="$1"
+    local tmp
+    tmp="$(mktemp)"
+    {
+        printf '%s\n' "$GEN_HEADER"
+        cat "$file"
+    } > "$tmp"
+    mv "$tmp" "$file"
+}
+
+# Generate the reference projection into <out_base>:
+#   <out_base>/reference/   typedoc tree
+generate_docs() {
+    local OUT_BASE="$1"
+    local REF="$OUT_BASE/reference"
+
+    mkdir -p "$OUT_BASE"
+
+    # Step 1 — typedoc markdown tree. cleanOutputDir (default) wipes the target
+    # first, so members removed from the source vanish from the committed tree.
+    # --gitRevision main pins source links to the branch, not a commit SHA:
+    # a SHA link would name the commit BEFORE the one carrying the regenerated
+    # docs, so every docs-carrying commit would invalidate its own projection
+    # (bootstrap paradox — the sync check could never be green at HEAD).
+    "$TYPEDOC" \
+        --entryPoints "$ENTRY" \
+        --plugin typedoc-plugin-markdown \
+        --out "$REF" \
+        --gitRevision main \
+        --readme none \
+        --entryFileName index.md \
+        --hideBreadcrumbs true \
+        --hidePageHeader true \
+        --outputFileStrategy members \
+        --useCodeBlocks true \
+        --excludeInternal true \
+        --excludePrivate true \
+        --excludeProtected true \
+        --githubPages false \
+        --indexFormat table \
+        --parametersFormat table \
+        --enumMembersFormat table \
+        --typeDeclarationFormat table \
+        --tsconfig "$PROJECT_ROOT/tsconfig.json"
+
+    # Step 2 — stamp every reference markdown file with the generated header.
+    local f
+    while IFS= read -r f; do
+        prepend_header "$f"
+    done < <(find "$REF" -name '*.md' | LC_ALL=C sort)
+}
+
+# ── --check: regenerate into a temp dir, diff against the committed tree ──
+if [ "$MODE" = "--check" ]; then
+    TMP_BASE=$(mktemp -d)
+    trap 'rm -rf "$TMP_BASE"' EXIT
+
+    # Typedoc chatter is noise here — the diff is the signal.
+    generate_docs "$TMP_BASE" > /dev/null 2>&1
+
+    OUT_OF_SYNC=()
+    diff -r -q "$TMP_BASE/reference" "$PROJECT_ROOT/docs/reference" > /dev/null 2>&1 || OUT_OF_SYNC+=("docs/reference/")
+
+    if [ ${#OUT_OF_SYNC[@]} -gt 0 ]; then
+        printf "${RED}Docs are out of sync:${NC}\n"
+        for p in "${OUT_OF_SYNC[@]}"; do
+            printf "  ${RED}✗${NC} %s\n" "$p"
+        done
+        printf "Run 'typescript docs' to regenerate.\n"
+        exit 1
     fi
+    exit 0
+fi
 
-    for f in "$OUT_DIR"/index.md \
-             "$OUT_DIR"/functions/*.md \
-             "$OUT_DIR"/classes/*.md \
-             "$OUT_DIR"/interfaces/*.md \
-             "$OUT_DIR"/type-aliases/*.md \
-             "$OUT_DIR"/variables/*.md; do
-        [ -f "$f" ] || continue
-        echo "---"
-        echo ""
-        cat "$f"
-        echo ""
-    done
-} > "$OUT_DIR/llms-full.txt"
-
-echo "Generated $OUT_DIR/llms.txt and $OUT_DIR/llms-full.txt"
+# ── generate: write the committed projection in place ──
+generate_docs "$PROJECT_ROOT/docs"
+echo "Generated docs/reference/"

package/bin/typescript.sh

@@ -88,11 +88,19 @@ case "$COMMAND" in
         ;;
 
     docs)
-        printf "${CYAN_BG}${BRIGHT_WHITE} TYPESCRIPT ${NC} Generating API docs...\n\n"
+        if [ "${1:-}" = "--check" ]; then
+            printf "${CYAN_BG}${BRIGHT_WHITE} TYPESCRIPT ${NC} Checking docs are in sync...\n\n"
 
-        bash "$SCRIPT_DIR/commands/docs.sh" "$PROJECT_ROOT" "$PACKAGE_ROOT"
+            bash "$SCRIPT_DIR/commands/docs.sh" "$PROJECT_ROOT" "$PACKAGE_ROOT" --check
 
-        printf "\n${GREEN}Docs generated at .docs/${NC}\n"
+            printf "${GREEN}Docs are in sync${NC}\n"
+        else
+            printf "${CYAN_BG}${BRIGHT_WHITE} TYPESCRIPT ${NC} Generating API docs...\n\n"
+
+            bash "$SCRIPT_DIR/commands/docs.sh" "$PROJECT_ROOT" "$PACKAGE_ROOT"
+
+            printf "\n${GREEN}Docs generated at docs/${NC}\n"
+        fi
         ;;
 
     check|fix)
@@ -107,7 +115,7 @@ case "$COMMAND" in
         printf "  bundle    Bundle library (ESM + CJS + types)\n"
         printf "  start     Run the built application\n"
         printf "  dev       Build, run, and rebuild on changes\n"
-        printf "  docs      Generate API reference + llms.txt from TSDoc\n"
+        printf "  docs      Generate the committed docs/reference tree; --check verifies sync\n"
         printf "  check     Check types, lint, formatting, and unused code\n"
         printf "  fix       Auto-fix lint and formatting issues\n\n"
         printf "Examples:\n"
@@ -116,6 +124,7 @@ case "$COMMAND" in
         printf "  typescript start\n"
         printf "  typescript dev\n"
         printf "  typescript docs\n"
+        printf "  typescript docs --check\n"
         printf "  typescript check\n"
         printf "  typescript fix\n"
         exit 1

package/lib/merge-knip-config.js

@@ -75,7 +75,7 @@ if (existsSync('docs')) {
 }
 
 // Scan for fixtures/** and expected/** directories anywhere in the tree (up to 3 levels)
-const scanDirs = ['tests', 'test', 'src'];
+const scanDirs = ['specs', 'tests', 'test', 'src'];
 for (const root of scanDirs) {
     if (!existsSync(root)) {
         continue;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jterrazz/typescript",
-    "version": "6.1.1",
+    "version": "7.0.0",
     "author": "Jean-Baptiste Terrazzoni <contact@jterrazz.com>",
     "repository": {
         "type": "git",
@@ -23,6 +23,10 @@
             "types": "./src/index.d.ts",
             "default": "./src/index.js"
         },
+        "./oxlint": {
+            "types": "./src/oxlint.d.ts",
+            "default": "./src/oxlint.js"
+        },
         "./tsconfig/*": "./presets/tsconfig/*.json",
         "./tsconfig/*.json": "./presets/tsconfig/*.json",
         "./tsdown/*": "./presets/tsdown/*.js",
@@ -52,7 +56,7 @@
         "typescript": "^6.0.0"
     },
     "devDependencies": {
-        "@jterrazz/test": "^8.0.0",
+        "@jterrazz/test": "^9.0.0",
         "@types/node": "^26.1.1",
         "vitest": "^4.1.10"
     },

package/presets/oxfmt/index.js

@@ -9,4 +9,7 @@ export default defineConfig({
     trailingComma: 'all',
     bracketSpacing: true,
     endOfLine: 'lf',
+    /* `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. */
+    ignorePatterns: ['docs/reference'],
 });

package/presets/oxlint/base.js

@@ -4,6 +4,19 @@ import { defineConfig } from 'oxlint';
 const require = createRequire(import.meta.url);
 const perfectionistPath = require.resolve('eslint-plugin-perfectionist');
 
+/*
+ * Base lint preset — tooling rules only. Wiring is EXPLICIT: this preset never
+ * auto-detects other jterrazz packages. A project using @jterrazz/test composes
+ * its `testing` fragment itself:
+ *
+ *     import { testing } from '@jterrazz/test/oxlint';
+ *     import { compose, node } from '@jterrazz/typescript/oxlint';
+ *
+ *     export default compose(node, testing);
+ *
+ * (The @jterrazz/test plugin is ESM-only: a CommonJS oxlint config silently
+ * drops it — `typescript check` still warns loudly about that pitfall.)
+ */
 export default defineConfig({
     plugins: ['typescript', 'import', 'oxc', 'unicorn'],
     jsPlugins: [perfectionistPath],

package/src/oxlint.d.ts

@@ -0,0 +1,15 @@
+type ConfigObject = Record<string, unknown>;
+
+declare const expo: ConfigObject;
+declare const hexagonal: ConfigObject;
+declare const next: ConfigObject;
+declare const node: ConfigObject;
+
+/**
+ * Deterministic merge of oxlint config fragments, left to right:
+ * jsPlugins/plugins/ignorePatterns/extends concatenated + deduped,
+ * rules/categories shallow-merged (last wins), overrides concatenated.
+ */
+declare function compose(...fragments: ConfigObject[]): ConfigObject;
+
+export { compose, expo, hexagonal, next, node };

package/src/oxlint.js

@@ -0,0 +1,56 @@
+/*
+ * The tool-facing oxlint entry (`@jterrazz/typescript/oxlint`): the named
+ * presets plus the `compose()` helper. Wiring is EXPLICIT — a consumer
+ * composes exactly the fragments it wants, nothing is auto-detected:
+ *
+ *     import { testing } from '@jterrazz/test/oxlint';
+ *     import { compose, node } from '@jterrazz/typescript/oxlint';
+ *
+ *     export default compose(node, testing);
+ */
+
+/** Config keys concatenated across fragments, duplicates dropped (===). */
+const CONCAT_DEDUPE = new Set(['extends', 'ignorePatterns', 'jsPlugins', 'plugins']);
+/** Config keys concatenated verbatim (order matters, no dedupe). */
+const CONCAT = new Set(['overrides']);
+/** Config keys shallow-merged as objects — the LAST fragment wins per key. */
+const SHALLOW_MERGE = new Set(['categories', 'env', 'globals', 'rules', 'settings']);
+
+/**
+ * Deterministic merge of oxlint config fragments, left to right:
+ * `jsPlugins` / `plugins` / `ignorePatterns` / `extends` are concatenated and
+ * deduped, `rules` / `categories` (and env/globals/settings) are shallow-merged
+ * with last-wins per key, `overrides` are concatenated, and any other key is
+ * taken from the last fragment that sets it.
+ */
+export function compose(...fragments) {
+    const merged = {};
+    for (const fragment of fragments) {
+        if (!fragment || typeof fragment !== 'object') {
+            continue;
+        }
+        for (const [key, value] of Object.entries(fragment)) {
+            if (value === undefined) {
+                continue;
+            }
+            if (CONCAT_DEDUPE.has(key)) {
+                const previous = Array.isArray(merged[key]) ? merged[key] : [];
+                const combined = [...previous, ...(Array.isArray(value) ? value : [value])];
+                merged[key] = combined.filter((entry, index) => combined.indexOf(entry) === index);
+            } else if (CONCAT.has(key)) {
+                const previous = Array.isArray(merged[key]) ? merged[key] : [];
+                merged[key] = [...previous, ...(Array.isArray(value) ? value : [value])];
+            } else if (SHALLOW_MERGE.has(key)) {
+                merged[key] = { ...merged[key], ...value };
+            } else {
+                merged[key] = value;
+            }
+        }
+    }
+    return merged;
+}
+
+export { default as hexagonal } from '../presets/oxlint/architectures/hexagonal.js';
+export { default as expo } from '../presets/oxlint/expo.js';
+export { default as next } from '../presets/oxlint/next.js';
+export { default as node } from '../presets/oxlint/node.js';

package/src/oxlint.test.ts

@@ -0,0 +1,79 @@
+import { expect, test } from 'vitest';
+
+import { compose, expo, hexagonal, next, node } from './oxlint.js';
+
+test('concatenates and dedupes plugin lists', () => {
+    // Given - two fragments sharing one jsPlugin
+    const merged = compose(
+        { jsPlugins: ['a', 'b'], plugins: ['typescript'] },
+        { jsPlugins: ['b', 'c'], plugins: ['typescript', 'import'] },
+    );
+
+    // Then - order preserved, duplicates dropped
+    expect(merged.jsPlugins).toEqual(['a', 'b', 'c']);
+    expect(merged.plugins).toEqual(['typescript', 'import']);
+});
+
+test('shallow-merges rules with last fragment winning', () => {
+    // Given - two fragments disagreeing on one rule
+    const merged = compose(
+        { rules: { curly: 'error', 'no-ternary': 'off' } },
+        { rules: { curly: 'off', 'jterrazz/b4-given-then': 'error' } },
+    );
+
+    // Then - the later fragment wins per key, others survive
+    expect(merged.rules).toEqual({
+        curly: 'off',
+        'jterrazz/b4-given-then': 'error',
+        'no-ternary': 'off',
+    });
+});
+
+test('concatenates overrides in order without deduping', () => {
+    // Given - two fragments each shipping an override
+    const first = { files: ['**/*.specification.ts'], rules: {} };
+    const second = { files: ['src/**'], rules: {} };
+    const merged = compose({ overrides: [first] }, { overrides: [second] });
+
+    // Then - both overrides survive, in composition order
+    expect(merged.overrides).toEqual([first, second]);
+});
+
+test('concatenates and dedupes ignorePatterns', () => {
+    // Given - overlapping ignore lists
+    const merged = compose(
+        { ignorePatterns: ['dist/**', 'node_modules/**'] },
+        { ignorePatterns: ['node_modules/**', '**/fixtures/**'] },
+    );
+
+    // Then - one entry each
+    expect(merged.ignorePatterns).toEqual(['dist/**', 'node_modules/**', '**/fixtures/**']);
+});
+
+test('takes unknown scalar keys from the last fragment', () => {
+    // Given - fragments disagreeing on a scalar key
+    const merged = compose({ somethingElse: 1 }, { somethingElse: 2 });
+
+    // Then - last wins
+    expect(merged.somethingElse).toBe(2);
+});
+
+test('ignores null and undefined fragments', () => {
+    // Given - a composition with holes (conditional fragments)
+    const merged = compose(
+        undefined as unknown as Record<string, unknown>,
+        { rules: { curly: 'error' } },
+        null as unknown as Record<string, unknown>,
+    );
+
+    // Then - the holes contribute nothing
+    expect(merged.rules).toEqual({ curly: 'error' });
+});
+
+test('exports the named presets', () => {
+    // Given - the tool-facing entry
+    // Then - every preset is a config object
+    for (const preset of [node, expo, next, hexagonal]) {
+        expect(typeof preset).toBe('object');
+    }
+});