@jterrazz/typescript 6.2.0 → 7.1.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) — pointer to the shared doctrine; what's TypeScript-specific here.
+
+For agents: read the chapters and the generated [`docs/reference/`](docs/reference/) tree straight from the repo, plus the [`skills/jterrazz-typescript`](skills/jterrazz-typescript/SKILL.md) Claude Code skill (the toolchain). The repo-structure doctrine itself is a Claude Code skill too — `jterrazz-repo-structure`, shipped from [`jterrazz-studio`](https://github.com/jterrazz/jterrazz-studio).
+
 ## License
 
 MIT © [Jean-Baptiste Terrazzoni](https://github.com/jterrazz)

package/bin/commands/check.sh

@@ -190,12 +190,24 @@ run_checks() {
         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 — quiet on success, verbose on failure: a tool's captured log
     # is shown only when it failed, so green output stays byte-identical across
@@ -246,6 +258,16 @@ run_checks() {
                 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
@@ -255,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 ] && [ $checker_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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jterrazz/typescript",
-    "version": "6.2.0",
+    "version": "7.1.0",
     "author": "Jean-Baptiste Terrazzoni <contact@jterrazz.com>",
     "repository": {
         "type": "git",

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/next.js

@@ -19,5 +19,17 @@ export default defineConfig({
         'react/jsx-curly-brace-presence': 'off',
         'react/jsx-max-depth': 'off',
         'unicorn/no-nested-ternary': 'off',
+        // -- Rules that fight the Next idiom itself, not bad code --
+        // A Next file interleaves `export const metadata`, types, and the
+        // Default export — exports-at-end is not how these files read.
+        'import/exports-last': 'off',
+        // Immutable serialization maps (`.map((x) => ({ ...x, url }))`) are
+        // The dominant React idiom; the Object.assign form is strictly worse
+        // For the build-time collection sizes a site actually maps over.
+        'oxc/no-map-spread': 'off',
+        // Client components are browser-only code that means `window`;
+        // Asking them to say `globalThis` trades clarity for portability
+        // They will never need.
+        'unicorn/prefer-global-this': 'off',
     },
 });