@jterrazz/typescript 9.2.1 → 10.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @jterrazz/typescript
 
-The complete TypeScript toolchain — build, run, check, and document with zero configuration. Powered by tsdown, Oxlint, Oxfmt, TypeScript 7, and Knip.
+The complete TypeScript toolchain — build, run, check, and document with zero configuration. Powered by tsdown, Oxlint, Oxfmt, TypeScript 7, and Knip. Six profiles, one rulebook: every rule of every plugin it loads is decided by name.
 
 ## Installation
 
@@ -17,8 +17,10 @@ npx typescript start           # Run the built application
 npx typescript dev             # Build, run, and rebuild on changes
 npx typescript docs            # Compile the committed docs/reference tree from source
 npx typescript docs-layout .   # Check a repository's docs/ against the manual spine
-npx typescript check           # Type-check, lint, format-check, and unused-code in parallel
-npx typescript fix             # Auto-fix lint and formatting issues
+npx typescript check           # Every quality pass, in parallel, ending on a drift report
+npx typescript fix             # Auto-fix lint, formatting, the .gitignore and suppression spellings
+npx typescript doctor          # Installed tool versions against the ranges this release declares
+npx typescript baseline        # Record today's oxlint diagnostics, so the count may only fall
 npx typescript clean           # Remove .artifacts/ (dist/ stays — it is the product)
 ```
 
@@ -26,16 +28,18 @@ npx typescript clean           # Remove .artifacts/ (dist/ stays — it is the p
 
 Fully compiled — no JavaScript in the hot path:
 
-| Step         | Tool                                                             | Language |
-| ------------ | ---------------------------------------------------------------- | -------- |
-| Transpile    | [Oxc](https://oxc.rs) (via tsdown)                               | Rust     |
-| Bundle       | [Rolldown](https://rolldown.rs)                                  | Rust     |
-| Declarations | [tsdown](https://tsdown.dev) built-in                            | Rust     |
-| Type check   | [tsc (TypeScript 7)](https://github.com/microsoft/typescript-go) | Go       |
-| Lint         | [Oxlint](https://oxc.rs/docs/guide/usage/linter)                 | Rust     |
-| Format       | [Oxfmt](https://oxc.rs/docs/guide/usage/formatter)               | Rust     |
-| Unused code  | [Knip](https://knip.dev)                                         | Node     |
-| API docs     | [Typedoc](https://typedoc.org)                                   | Node     |
+| Step         | Tool                                                                        | Language |
+| ------------ | --------------------------------------------------------------------------- | -------- |
+| Transpile    | [Oxc](https://oxc.rs) (via tsdown)                                          | Rust     |
+| Bundle       | [Rolldown](https://rolldown.rs)                                             | Rust     |
+| Declarations | [tsdown](https://tsdown.dev) built-in                                       | Rust     |
+| Type check   | [tsc (TypeScript 7)](https://github.com/microsoft/typescript-go)            | Go       |
+| Lint         | [Oxlint](https://oxc.rs/docs/guide/usage/linter)                            | Rust     |
+| Format       | [Oxfmt](https://oxc.rs/docs/guide/usage/formatter)                          | Rust     |
+| Unused code  | [Knip](https://knip.dev)                                                    | Node     |
+| Packaging    | [publint](https://publint.dev) + [attw](https://arethetypeswrong.github.io) | Node     |
+| Layer map    | [dependency-cruiser](https://github.com/sverweij/dependency-cruiser)        | Node     |
+| API docs     | [Typedoc](https://typedoc.org)                                              | Node     |
 
 ## Documentation
 
@@ -46,12 +50,12 @@ The full corpus lives in [`docs/`](docs/):
 - [Testing](docs/03-testing.md) — how this toolchain proves itself.
 - [Operating](docs/04-operating.md) — what publishes it, and which number moves.
 - [Building](docs/05-building.md) — `build`, `bundle`, `start`, `dev`.
-- [Quality checks](docs/06-quality-checks.md) — `check` / `fix` and their passes.
-- [Lint presets](docs/07-lint-presets.md) — oxlint presets, `compose`, architecture, knip.
+- [Quality checks](docs/06-quality-checks.md) — `check` / `fix` and their fifteen passes.
+- [Lint presets](docs/07-lint-presets.md) — the rulebook, the six profiles, `compose`, architecture, knip.
 - [Docs pipeline](docs/08-docs-pipeline.md) — the `typescript docs` compiler.
 - [Repo structure](docs/09-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).
+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) and its generated [rule reference](skills/jterrazz-typescript/references/rules.md). 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
 

package/bin/commands/check.sh

@@ -62,10 +62,62 @@ find_tsc() {
     fi
 }
 
+# oxlint's type-aware rules run in `tsgolint`, a separate binary it looks up on
+# PATH — and a consumer's PATH has no reason to carry this package's bin dir. It
+# is a dependency here, so the lookup is made to succeed by putting the
+# directory that holds it in front, for this process and its children only.
+add_tsgolint_to_path() {
+    local tsgolint
+    tsgolint=$(find_binary tsgolint)
+    case "$tsgolint" in
+        */*)
+            PATH="$(cd -P "$(dirname "$tsgolint")" && pwd):$PATH"
+            export PATH
+            ;;
+    esac
+}
+
+add_tsgolint_to_path
+
+# The config a consumer declares its rules in — the one thing that makes the
+# drift report answerable. Without one there is no profile to have drifted from.
+OXLINT_CONFIG=""
+for candidate in oxlint.config.ts oxlint.config.mjs oxlint.config.js oxlint.config.cjs .oxlintrc.json; do
+    [ -f "$candidate" ] && { OXLINT_CONFIG="$candidate"; break; }
+done
+
+# The ratchet's file, at the project root. Its presence is what turns the oxlint
+# pass from "no diagnostic at all" into "no diagnostic above what was recorded".
+BASELINE_FILE="oxlint.baseline.json"
+
 TSC=$(find_tsc)
 OXLINT=$(find_binary oxlint)
 OXFMT=$(find_binary oxfmt)
 KNIP=$(find_binary knip)
+DEPCRUISE=$(find_binary depcruise)
+PUBLINT=$(find_binary publint)
+ATTW=$(find_binary attw)
+PRETTIER=$(find_binary prettier)
+
+# `astro` is the CONSUMER's dependency, never this package's: the pass runs its
+# checker, it does not ship one. So the lookup starts at the project.
+find_project_binary() {
+    local name="$1"
+    if [ -x "node_modules/.bin/$name" ]; then
+        echo "$PWD/node_modules/.bin/$name"
+    else
+        find_binary "$name"
+    fi
+}
+
+# The one file shape oxfmt does not parse. The values are the oxfmt values —
+# 100 / 4 / single / all — so a consumer never declares a formatter of its own.
+#
+# The plugin is passed as a RESOLVED PATH, not as a name in the config: prettier
+# resolves a plugin name from the working directory, which is the consumer's,
+# 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 unit is the workspace package, not the repository ────────────────────
@@ -106,15 +158,22 @@ project_uses_jterrazz_test() {
     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
 }
 
-# In a workspace the dependency may sit on a member alone — the warning below
-# is about the ROOT oxlint config, but the reason to print it is anywhere.
-workspace_uses_jterrazz_test() {
-    project_uses_jterrazz_test "." && return 0
-    local member
-    for member in "${WORKSPACE_MEMBERS[@]}"; do
-        project_uses_jterrazz_test "$member" && return 0
-    done
-    return 1
+# An Astro project, read off its manifest. `.astro` is the one file shape oxfmt
+# does not parse and `astro check` is the only checker that reads a template's
+# frontmatter, so the pass exists exactly where the dependency does.
+project_uses_astro() {
+    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["astro"]?0:1)' "$dir/package.json" 2>/dev/null
+}
+
+# A package the registry would accept: it names an entry (`exports`, `main`) or
+# a publish target, and it never says it is private. A private package, and a
+# workspace root that only holds members, have no tarball to be judged on.
+project_is_publishable() {
+    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"));process.exit(p.private!==true&&(p.exports||p.main||p.publishConfig)?0:1)' "$dir/package.json" 2>/dev/null
 }
 
 # A path git has been told to forget is not this workspace's source. Clones,
@@ -174,31 +233,21 @@ discover_docs_roots() {
     } | LC_ALL=C sort -u
 }
 
-# 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 ;;
+# The name of the oxlint config, when that config is CommonJS — and nothing
+# otherwise. Everything this package ships is ESM, and so is every oxlint JS
+# plugin the estate writes; a CommonJS config cannot load either, and oxlint
+# drops what it cannot load and still exits 0. The rules a config names are the
+# whole claim of a lint run, so the shape of the config is the oxlint pass's
+# business ([Quality checks](../../docs/06-quality-checks.md)).
+commonjs_oxlint_config() {
+    case "$OXLINT_CONFIG" in
+        *.cjs) printf '%s' "$OXLINT_CONFIG" ;;
         *.js)
             if ! node -e 'process.exit(require("./package.json").type==="module"?0:1)' 2>/dev/null; then
-                is_cjs=true
+                printf '%s' "$OXLINT_CONFIG"
             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
@@ -226,6 +275,75 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
+# ── How a pass speaks ────────────────────────────────────────────────────────
+# Every pass that RAN prints the same three things, in the same order: a `RUN`
+# header carrying its label, whatever it has to say, and one verdict line. A
+# pass that did not apply — no Astro in the project, no declared layer map —
+# prints nothing at all, because it answered no question.
+#
+# What sits between the header and the verdict is the one variable: a failing
+# pass prints its whole captured log, and a passing one stays silent unless it
+# WROTE something. `fix` changed a file the operator owns and silence would hide
+# it, so a writer asks for its log with the fourth argument; a reader's success
+# chatter — oxlint's summary, which its reporter prints on a runner and in a
+# terminal and drops under an AI agent — never reaches the stream, so a green
+# run is byte-identical everywhere.
+report_pass() {
+    local label="$1" status="$2" log="$3" writer="${4:-}"
+
+    printf "\n${CYAN_BG}${BRIGHT_WHITE} RUN ${NC} %s\n\n" "$label"
+    if [ "$status" -ne 0 ] || [ -n "$writer" ]; then
+        [ -s "$log" ] && cat "$log"
+    fi
+    if [ "$status" -eq 0 ]; then
+        printf "${GREEN}✓ Passed${NC}\n"
+    else
+        printf "${RED}✗ Failed with exit code %d${NC}\n" "$status"
+    fi
+}
+
+# Two ways a lint run says nothing about the rules it was supposed to enforce.
+#
+# A config oxlint cannot parse — a `jsPlugins` naming a module that is not there
+# is the common one — makes it print `Failed to parse oxlint configuration file`
+# and lint nothing; 1.83.0 exits 1 for it, and this names the refusal in the
+# toolchain's own vocabulary rather than leaving a reader with the tool's text.
+# A CommonJS config is the silent one: oxlint drops it whole, prints NOTHING and
+# exits 0, so the run is green having enforced no rule the config named.
+#
+# Both are the oxlint pass refusing, so both are written into its own log and
+# both fail it. After this, `lint_status` is the verdict on what the linter
+# actually ran, not on what it managed to exit with.
+judge_lint_config() {
+    local cjs
+    cjs=$(commonjs_oxlint_config)
+    local refusals=""
+
+    if grep -q 'Failed to parse oxlint configuration file' "$tmp_dir/lint.log" 2>/dev/null; then
+        refusals+="oxlint-config-unparsed  ${OXLINT_CONFIG}  oxlint refused this config and linted nothing — its own report is above"$'\n'
+    fi
+    if [ -n "$cjs" ]; then
+        refusals+="oxlint-config-commonjs  ${cjs}  a CommonJS config cannot load an ESM preset or plugin, and oxlint drops what it cannot load — write oxlint.config.ts or .mjs"$'\n'
+    fi
+
+    [ -z "$refusals" ] && return 0
+
+    printf '%s' "$refusals" >> "$tmp_dir/lint.log"
+    lint_status=1
+}
+
+# One pass, N runs: the logs of the runs that FAILED, joined into the single log
+# the pass reports under. A green member stays silent — it is the same pass.
+join_logs() {
+    local into="$1"
+    shift
+    : > "$into"
+    local log
+    for log in "$@"; do
+        [ -s "$log" ] && cat "$log" >> "$into"
+    done
+}
+
 # Create a temporary directory for log files
 tmp_dir=$(mktemp -d)
 cleanup() { rm -rf "$tmp_dir"; }
@@ -243,21 +361,31 @@ run_checks() {
 
     printf "${CYAN_BG}${BRIGHT_WHITE} START ${NC} ${LABEL}\n"
 
-    if workspace_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=$!
 
+    # --type-aware is explicit and unconditional: the rules it unlocks are the
+    # ones no syntactic linter can express, and a flag that is only sometimes
+    # passed is a rule set that is only sometimes enforced. `oxlint-tsgolint` is
+    # a dependency of this package, so it is there for every consumer.
     if [ "$FIX_MODE" = true ]; then
-        "$OXLINT" --fix "${LINT_ARGS[@]}" > "$tmp_dir/lint.log" 2>&1 &
+        "$OXLINT" --type-aware --fix "${LINT_ARGS[@]}" > "$tmp_dir/lint.log" 2>&1 &
     else
-        "$OXLINT" "${LINT_ARGS[@]}" > "$tmp_dir/lint.log" 2>&1 &
+        "$OXLINT" --type-aware "${LINT_ARGS[@]}" > "$tmp_dir/lint.log" 2>&1 &
     fi
     local lint_pid=$!
 
+    # The same run, machine-readable, so the ratchet can be judged rule by rule.
+    # A second invocation rather than a reformat of the first: the human log is
+    # what a failing pass prints, and neither form can be derived from the other.
+    local lint_json_pid=""
+    if [ "$FIX_MODE" = false ] && [ -f "$BASELINE_FILE" ]; then
+        "$OXLINT" --type-aware --format json "${LINT_ARGS[@]}" \
+            > "$tmp_dir/lint.json" 2>/dev/null &
+        lint_json_pid=$!
+    fi
+
     if [ "$FIX_MODE" = true ]; then
         "$OXFMT" > "$tmp_dir/format.log" 2>&1 &
     else
@@ -329,6 +457,113 @@ run_checks() {
         docs_layout_pid=$!
     fi
 
+    # Suppressions (directives): every place the project told a checker to look
+    # away is spelled in this toolchain's vocabulary, carries its reason, and
+    # names a rule that is still live. It runs in BOTH modes — `--fix` settles
+    # the two spellings a machine can settle, and never invents a reason.
+    local suppressions_pid=""
+    local suppressions_status=0
+    local suppressions_fix=()
+    [ "$FIX_MODE" = true ] && suppressions_fix=(--fix)
+    node "$PACKAGE_ROOT/lib/check-suppressions.js" . --oxlint "$OXLINT" \
+        "${suppressions_fix[@]}" "${LINT_ARGS[@]}" > "$tmp_dir/suppressions.log" 2>&1 &
+    suppressions_pid=$!
+
+    # Markdown (prose): every tracked page's coordinates resolve, and its blocks
+    # breathe. Check-only — there is no rewrite that splits a paragraph into the
+    # two ideas it was carrying. It reads the same `--ignore-pattern` globs the
+    # linter received, so one flag answers for the whole run.
+    local markdown_pid=""
+    local markdown_status=0
+    if [ "$FIX_MODE" = false ]; then
+        node "$PACKAGE_ROOT/lib/check-markdown.js" . "${LINT_ARGS[@]}" \
+            > "$tmp_dir/markdown.log" 2>&1 &
+        markdown_pid=$!
+    fi
+
+    # Names: what the project calls its own parts, under the roots where a
+    # project keeps what it wrote. Check-only — renaming a file is a move, and
+    # choosing the name it moves to is the work the rule is asking for.
+    local names_pid=""
+    local names_status=0
+    if [ "$FIX_MODE" = false ]; then
+        node "$PACKAGE_ROOT/lib/check-names.js" . "${LINT_ARGS[@]}" > "$tmp_dir/names.log" 2>&1 &
+        names_pid=$!
+    fi
+
+    # Secrets: no file the project would commit carries a live-looking
+    # credential. The gate always applies, so WHICH engine answers — gitleaks
+    # where the machine has it, the built-in patterns where it does not — is
+    # decided inside the script, not here.
+    local secrets_pid=""
+    local secrets_status=0
+    if [ "$FIX_MODE" = false ]; then
+        node "$PACKAGE_ROOT/lib/check-secrets.js" . "${LINT_ARGS[@]}" \
+            > "$tmp_dir/secrets.log" 2>&1 &
+        secrets_pid=$!
+    fi
+
+    # Astro: the consumer's own checker, plus the formatter for the one file
+    # shape oxfmt does not parse. Both halves run in fix mode too — prettier
+    # writes there, and `astro check` is read-only wherever it runs.
+    local astro_pid=""
+    local astro_status=0
+    if project_uses_astro "."; then
+        ASTRO=$(find_project_binary astro)
+        # A subshell, so both halves run and both are reported — a template that
+        # does not type-check is not a reason to stay quiet about its shape.
+        # `local` has no meaning past the `&`, hence the plain names.
+        (
+            "$ASTRO" check
+            astro_check=$?
+            if [ "$FIX_MODE" = true ]; then
+                "$PRETTIER" --write --config "$PRETTIER_ASTRO_CONFIG" \
+                    --plugin "$PRETTIER_ASTRO_PLUGIN" \
+                    --no-error-on-unmatched-pattern "**/*.astro"
+            else
+                "$PRETTIER" --check --config "$PRETTIER_ASTRO_CONFIG" \
+                    --plugin "$PRETTIER_ASTRO_PLUGIN" \
+                    --no-error-on-unmatched-pattern "**/*.astro"
+            fi
+            astro_format=$?
+            [ $astro_check -eq 0 ] && [ $astro_format -eq 0 ]
+        ) > "$tmp_dir/astro.log" 2>&1 &
+        astro_pid=$!
+    fi
+
+    # Architecture (layer map): the graph a project declared, resolved. Bash
+    # asks the one question that decides whether the gate applies at all — is
+    # there a map — and the script decides what it says. Opt-in by the file's
+    # existence: a project with no declared architecture is not in breach of one.
+    local architecture_pid=""
+    local architecture_status=0
+    if [ "$FIX_MODE" = false ] &&
+        { [ -f ".dependency-cruiser.cjs" ] || [ -f ".dependency-cruiser.js" ] ||
+            [ -f ".dependency-cruiser.mjs" ]; }; then
+        node "$PACKAGE_ROOT/lib/check-architecture.js" . --depcruise "$DEPCRUISE" \
+            > "$tmp_dir/architecture.log" 2>&1 &
+        architecture_pid=$!
+    fi
+
+    # Publish (packaging): what a published package promises, held to what the
+    # tarball will contain. Once per package the registry would accept — the
+    # unit is the workspace package, and a private one has no tarball.
+    local publish_pids=()
+    local publish_logs=()
+    local publish_status=0
+    if [ "$FIX_MODE" = false ]; then
+        local publish_index=0
+        for publish_root in "." "${WORKSPACE_MEMBERS[@]}"; do
+            project_is_publishable "$publish_root" || continue
+            node "$PACKAGE_ROOT/lib/check-publish.js" "$publish_root" \
+                --publint "$PUBLINT" --attw "$ATTW" \
+                > "$tmp_dir/publish-$publish_index.log" 2>&1 &
+            publish_pids+=($!)
+            publish_logs+=("$tmp_dir/publish-$publish_index.log")
+            publish_index=$((publish_index + 1))
+        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.
@@ -371,10 +606,27 @@ run_checks() {
     # Wait and collect statuses
     wait $type_pid;   local type_status=$?
     wait $lint_pid;   local lint_status=$?
+
+    # The ratchet, where the project keeps one: the pass is judged by what the
+    # baseline tolerates, not by oxlint's exit code. Bash decides whether the
+    # file is there; the script decides what it says.
+    if [ -n "$lint_json_pid" ]; then
+        wait $lint_json_pid
+        node "$PACKAGE_ROOT/lib/check-baseline.js" "$tmp_dir/lint.json" . \
+            >> "$tmp_dir/lint.log" 2>&1
+        lint_status=$?
+    fi
+
     wait $format_pid; local format_status=$?
     [ -n "$knip_pid" ] && { wait $knip_pid; knip_status=$?; }
     [ -n "$gitignore_pid" ] && { wait $gitignore_pid; gitignore_status=$?; }
     [ -n "$docs_layout_pid" ] && { wait $docs_layout_pid; docs_layout_status=$?; }
+    wait $suppressions_pid; suppressions_status=$?
+    [ -n "$markdown_pid" ] && { wait $markdown_pid; markdown_status=$?; }
+    [ -n "$architecture_pid" ] && { wait $architecture_pid; architecture_status=$?; }
+    [ -n "$astro_pid" ] && { wait $astro_pid; astro_status=$?; }
+    [ -n "$names_pid" ] && { wait $names_pid; names_status=$?; }
+    [ -n "$secrets_pid" ] && { wait $secrets_pid; secrets_status=$?; }
 
     # One pass, N runs: the pass fails if any run failed, and only the logs of
     # the runs that FAILED are printed — a green member stays silent.
@@ -388,6 +640,16 @@ run_checks() {
         index=$((index + 1))
     done
 
+    local publish_failed_logs=()
+    index=0
+    for pid in "${publish_pids[@]}"; do
+        if ! wait "$pid"; then
+            publish_status=1
+            publish_failed_logs+=("${publish_logs[$index]}")
+        fi
+        index=$((index + 1))
+    done
+
     local docs_failed_logs=()
     index=0
     for pid in "${docs_pids[@]}"; do
@@ -398,92 +660,61 @@ run_checks() {
         index=$((index + 1))
     done
 
-    # 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"
-    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
+    # ── The report ───────────────────────────────────────────────────────────
+    # One order, and it is the chapter's: the three tools, the artefact gate,
+    # knip, the conventions checker, the two Docs passes, then the gates a
+    # project opts into and the four that read its tree on every run. A pass
+    # that did not apply is absent; every pass that ran prints the same block.
+    join_logs "$tmp_dir/checker.log" "${checker_failed_logs[@]}"
+    join_logs "$tmp_dir/docs.log" "${docs_failed_logs[@]}"
+    join_logs "$tmp_dir/publish.log" "${publish_failed_logs[@]}"
 
     local lint_label="Oxlint Check"
-    [ "$FIX_MODE" = true ] && lint_label="Oxlint Fix"
-    printf "\n${CYAN_BG}${BRIGHT_WHITE} RUN ${NC} ${lint_label}\n\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"
-    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
-
-    # The one pass that speaks on success: a rewrite changed a file the operator
-    # owns, and silence would hide it. In check mode a green gate writes nothing,
-    # so the green output stays byte-identical with the others.
-    if [ -n "$gitignore_pid" ]; then
-        printf "\n${CYAN_BG}${BRIGHT_WHITE} RUN ${NC} Gitignore (artefacts)\n\n"
-        [ -s "$tmp_dir/gitignore.log" ] && cat "$tmp_dir/gitignore.log"
-        if [ $gitignore_status -ne 0 ]; then
-            printf "${RED}✗ Failed with exit code %d${NC}\n" $gitignore_status
-        else
-            printf "${GREEN}✓ Passed${NC}\n"
-        fi
+    local write=""
+    if [ "$FIX_MODE" = true ]; then
+        lint_label="Oxlint Fix"
+        format_label="Oxfmt Format"
+        write="writer"
     fi
 
-    if [ "$FIX_MODE" = false ]; then
-        printf "\n${CYAN_BG}${BRIGHT_WHITE} RUN ${NC} Knip (unused code)\n\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 [ ${#checker_pids[@]} -gt 0 ]; then
-            printf "\n${CYAN_BG}${BRIGHT_WHITE} RUN ${NC} Test Conventions (@jterrazz/test)\n\n"
-            if [ $checker_status -ne 0 ]; then
-                for log in "${checker_failed_logs[@]}"; do
-                    [ -s "$log" ] && cat "$log"
-                done
-                printf "${RED}✗ Failed with exit code %d${NC}\n" $checker_status
-            else
-                printf "${GREEN}✓ Passed${NC}\n"
-            fi
-        fi
-
-        if [ -n "$docs_layout_pid" ]; then
-            printf "\n${CYAN_BG}${BRIGHT_WHITE} RUN ${NC} Docs (layout)\n\n"
-            if [ $docs_layout_status -ne 0 ]; then
-                [ -s "$tmp_dir/docs-layout.log" ] && cat "$tmp_dir/docs-layout.log"
-                printf "${RED}✗ Failed with exit code %d${NC}\n" $docs_layout_status
-            else
-                printf "${GREEN}✓ Passed${NC}\n"
-            fi
-        fi
-
-        if [ ${#docs_pids[@]} -gt 0 ]; then
-            printf "\n${CYAN_BG}${BRIGHT_WHITE} RUN ${NC} Docs (sync)\n\n"
-            if [ $docs_status -ne 0 ]; then
-                for log in "${docs_failed_logs[@]}"; do
-                    [ -s "$log" ] && cat "$log"
-                done
-                printf "${RED}✗ Failed with exit code %d${NC}\n" $docs_status
-            else
-                printf "${GREEN}✓ Passed${NC}\n"
-            fi
-        fi
+    judge_lint_config
+    report_pass "TypeScript Check" $type_status "$tmp_dir/type.log"
+    report_pass "$lint_label" $lint_status "$tmp_dir/lint.log"
+    report_pass "$format_label" $format_status "$tmp_dir/format.log"
+    [ -n "$gitignore_pid" ] &&
+        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"
+    [ -n "$docs_layout_pid" ] &&
+        report_pass "Docs (layout)" $docs_layout_status "$tmp_dir/docs-layout.log"
+    [ ${#docs_pids[@]} -gt 0 ] &&
+        report_pass "Docs (sync)" $docs_status "$tmp_dir/docs.log"
+    [ ${#publish_pids[@]} -gt 0 ] &&
+        report_pass "Publish (packaging)" $publish_status "$tmp_dir/publish.log"
+    [ -n "$architecture_pid" ] &&
+        report_pass "Architecture (layer map)" $architecture_status "$tmp_dir/architecture.log"
+    [ -n "$astro_pid" ] &&
+        report_pass "Astro (check + format)" $astro_status "$tmp_dir/astro.log" "$write"
+    report_pass "Suppressions (directives)" $suppressions_status "$tmp_dir/suppressions.log" "$write"
+    [ -n "$markdown_pid" ] &&
+        report_pass "Markdown (prose)" $markdown_status "$tmp_dir/markdown.log"
+    [ -n "$names_pid" ] && report_pass "Names (tree)" $names_status "$tmp_dir/names.log"
+    [ -n "$secrets_pid" ] && report_pass "Secrets (credentials)" $secrets_status "$tmp_dir/secrets.log"
+
+    # Drift: the report, not a gate — how far this project stands from the
+    # profile it says it extends, in four numbers. It runs last and it speaks on
+    # every check, because the alternative is what the estate had: every
+    # repository quietly a little further from the shared rulebook, and nobody
+    # able to say by how much without opening every config. Only a rule turned
+    # off with no reason beside it actually fails the run.
+    local drift_status=0
+    if [ "$FIX_MODE" = false ] && [ -n "$OXLINT_CONFIG" ]; then
+        printf "\n${CYAN_BG}${BRIGHT_WHITE} DRIFT ${NC} Deviations from the profile\n\n"
+        node "$PACKAGE_ROOT/lib/check-drift.js" . --oxlint "$OXLINT" "${LINT_ARGS[@]}"
+        drift_status=$?
     fi
 
     # Summary
@@ -493,7 +724,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 ] && [ $gitignore_status -eq 0 ] && [ $checker_status -eq 0 ] && [ $docs_layout_status -eq 0 ] && [ $docs_status -eq 0 ]; then
+    if [ $type_status -eq 0 ] && [ $lint_status -eq 0 ] && [ $format_status -eq 0 ] && [ $knip_status -eq 0 ] && [ $gitignore_status -eq 0 ] && [ $checker_status -eq 0 ] && [ $docs_layout_status -eq 0 ] && [ $docs_status -eq 0 ] && [ $markdown_status -eq 0 ] && [ $names_status -eq 0 ] && [ $secrets_status -eq 0 ] && [ $suppressions_status -eq 0 ] && [ $publish_status -eq 0 ] && [ $architecture_status -eq 0 ] && [ $astro_status -eq 0 ] && [ $drift_status -eq 0 ]; then
         printf "${GREEN}✓ All checks passed${NC}\n"
         exit 0
     else