@jterrazz/typescript 8.0.0 → 8.1.0

package/bin/commands/check.sh

@@ -68,11 +68,110 @@ OXFMT=$(find_binary oxfmt)
 KNIP=$(find_binary knip)
 CHECKER=$(find_binary jterrazz-test-check)
 
+# ── The unit is the workspace package, not the repository ────────────────────
+# Every gate measures from the NEAREST package.json. A single-package project
+# has exactly one — the cwd — and nothing below changes for it. A workspace
+# root has one per member, and the per-member gates run once per member
+# instead of once for a root that owns neither the specs nor the docs.
+#
+# Root-only by nature, and deliberately left alone: tsc, oxlint and oxfmt
+# measure from their CONFIG file, not from a package, and each already walks
+# the whole tree from the cwd; knip is natively workspace-aware, so a member's
+# knip config belongs under the root config's `workspaces` key, not in a second
+# invocation.
+WORKSPACE_MEMBERS=()
+while IFS= read -r workspace_member; do
+    [ -n "$workspace_member" ] && WORKSPACE_MEMBERS+=("$workspace_member")
+done < <(node "$PACKAGE_ROOT/lib/workspace-members.js" 2>/dev/null)
+
+# The nearest package.json OWNS a directory. Walk up from the given path and
+# stop at the cwd — a gate never asks a question above the project it runs in.
+nearest_package_dir() {
+    local dir="$1"
+    while true; do
+        if [ -f "$dir/package.json" ]; then
+            printf '%s\n' "$dir"
+            return 0
+        fi
+        [ "$dir" = "." ] && return 1
+        dir=$(dirname "$dir")
+    done
+}
+
 # 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.
+# owning package 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
+    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
+}
+
+# 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
+}
+
+# A path git has been told to forget is not this workspace's source. Clones,
+# workbenches and build output live under gitignored paths, and the conventions
+# checker walks whatever root it is handed — so the filter belongs here, before
+# the handing over. Outside a git tree the question has no answer, and the
+# non-zero exit reads as "not ignored", which is the right default.
+path_is_gitignored() {
+    git check-ignore --quiet "$1" 2>/dev/null
+}
+
+# A discovered root must belong to the member that produced it. Walk back up
+# from the candidate: a nested `.git`, or a package.json no workspace glob
+# claims, means the walk crossed OUT of this workspace into a foreign tree —
+# a vendored dependency, a sibling clone — whose conventions are not ours.
+inside_owning_member() {
+    local dir member="$2"
+    dir=$(dirname "$1")
+    while [ "$dir" != "$member" ] && [ "$dir" != "." ] && [ "$dir" != "/" ]; do
+        if [ -e "$dir/.git" ] || [ -f "$dir/package.json" ]; then
+            return 1
+        fi
+        dir=$(dirname "$dir")
+    done
+    return 0
+}
+
+# Every specs root the workspace owns: the root's own, plus the first one found
+# At or below each member (a member that nests its facet — web/specs — counts).
+# Never descends INTO a specs tree: the fixtures under it are not specs roots.
+discover_specs_roots() {
+    {
+        [ -d "specs" ] && ! path_is_gitignored "specs" && printf '%s\n' "specs"
+        local member candidate
+        for member in "${WORKSPACE_MEMBERS[@]}"; do
+            while IFS= read -r candidate; do
+                [ -n "$candidate" ] || continue
+                path_is_gitignored "$candidate" && continue
+                inside_owning_member "$candidate" "$member" || continue
+                printf '%s\n' "$candidate"
+            done < <(find "$member" \
+                \( -name node_modules -o -name dist -o -name .git \) -prune -o \
+                -type d -name specs -prune -print 2>/dev/null)
+        done
+    } | LC_ALL=C sort -u
+}
+
+# Every package that owns a committed docs projection. A package's docs sit at
+# its own root — that IS the nearest-package.json rule, so no walk is needed.
+discover_docs_roots() {
+    {
+        [ -d "docs/reference" ] && printf '%s\n' "."
+        local member
+        for member in "${WORKSPACE_MEMBERS[@]}"; do
+            [ -d "$member/docs/reference" ] && printf '%s\n' "$member"
+        done
+    } | LC_ALL=C sort -u
 }
 
 # The @jterrazz/test oxlint plugin is ESM-only. A CommonJS oxlint config silently drops
@@ -144,7 +243,7 @@ run_checks() {
 
     printf "${CYAN_BG}${BRIGHT_WHITE} START ${NC} ${LABEL}\n"
 
-    if project_uses_jterrazz_test; then
+    if workspace_uses_jterrazz_test; then
         warn_cjs_oxlint_config
     fi
 
@@ -167,7 +266,9 @@ run_checks() {
     local format_pid=$!
 
     # Knip: only run in check mode (fix mode is destructive)
-    # Merge base config (from this package) with optional project-local knip.json
+    # Merge base config (from this package) with optional project-local knip.json.
+    # Root-only on purpose: knip reads the workspace globs itself and reports per
+    # member from one run — a second invocation per member would double-report.
     local knip_pid=""
     local knip_status=0
     if [ "$FIX_MODE" = false ]; then
@@ -181,24 +282,43 @@ 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=""
+    # 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.
+    local checker_pids=()
+    local checker_logs=()
     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=$!
+    if [ "$FIX_MODE" = false ]; then
+        local checker_index=0
+        while IFS= read -r specs_root; do
+            [ -n "$specs_root" ] || continue
+            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 &
+            checker_pids+=($!)
+            checker_logs+=("$tmp_dir/checker-$checker_index.log")
+            checker_index=$((checker_index + 1))
+        done < <(discover_specs_roots)
     fi
 
-    # Docs (sync): only in check mode, and only once the project has generated
+    # Docs (sync): only in check mode, and only for a package that 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_pids=()
+    local docs_logs=()
     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=$!
+    if [ "$FIX_MODE" = false ]; then
+        local docs_index=0
+        while IFS= read -r docs_root; do
+            [ -n "$docs_root" ] || continue
+            bash "$SCRIPT_DIR/docs.sh" "$(cd "$docs_root" && pwd)" "$PACKAGE_ROOT" --check \
+                > "$tmp_dir/docs-$docs_index.log" 2>&1 &
+            docs_pids+=($!)
+            docs_logs+=("$tmp_dir/docs-$docs_index.log")
+            docs_index=$((docs_index + 1))
+        done < <(discover_docs_roots)
     fi
 
     # Wait and collect statuses
@@ -206,8 +326,28 @@ run_checks() {
     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=$?; }
+
+    # 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.
+    local checker_failed_logs=()
+    local index=0
+    for pid in "${checker_pids[@]}"; do
+        if ! wait "$pid"; then
+            checker_status=1
+            checker_failed_logs+=("${checker_logs[$index]}")
+        fi
+        index=$((index + 1))
+    done
+
+    local docs_failed_logs=()
+    index=0
+    for pid in "${docs_pids[@]}"; do
+        if ! wait "$pid"; then
+            docs_status=1
+            docs_failed_logs+=("${docs_logs[$index]}")
+        fi
+        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
@@ -249,20 +389,24 @@ run_checks() {
             printf "${GREEN}✓ Passed${NC}\n"
         fi
 
-        if [ -n "$checker_pid" ]; then
+        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
-                [ -s "$tmp_dir/checker.log" ] && cat "$tmp_dir/checker.log"
+                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_pid" ]; then
+        if [ ${#docs_pids[@]} -gt 0 ]; 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"
+                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"

package/bin/typescript.sh

@@ -88,18 +88,59 @@ case "$COMMAND" in
         ;;
 
     docs)
+        # The unit is the PACKAGE. A projection is compiled from a package's own
+        # Barrel against its own tsconfig into its own docs/ — three things a
+        # Workspace root does not have, and each member does. docs.sh was always
+        # Parameterised by a project root; what was missing is the list.
+        owns_a_projection() {
+            local root="$1"
+            [ -d "$root/docs" ] || return 1
+            [ -f "$root/src/index.ts" ] || [ -f "$root/src/index.d.ts" ]
+        }
+
+        DOCS_UNITS=()
+        if owns_a_projection "$PROJECT_ROOT"; then
+            DOCS_UNITS+=("$PROJECT_ROOT")
+        fi
+        while IFS= read -r docs_member; do
+            [ -n "$docs_member" ] || continue
+            if owns_a_projection "$PROJECT_ROOT/$docs_member"; then
+                DOCS_UNITS+=("$PROJECT_ROOT/$docs_member")
+            fi
+        done < <(node "$PACKAGE_ROOT/lib/workspace-members.js" "$PROJECT_ROOT" 2>/dev/null)
+
+        # Nothing qualified: hand the project root over anyway, so the compiler's
+        # Own diagnostic is what the operator reads.
+        if [ ${#DOCS_UNITS[@]} -eq 0 ]; then
+            DOCS_UNITS=("$PROJECT_ROOT")
+        fi
+
         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" --check
+            for docs_unit in "${DOCS_UNITS[@]}"; do
+                if [ ${#DOCS_UNITS[@]} -gt 1 ]; then
+                    printf "%s\n" "${docs_unit#"$PROJECT_ROOT/"}"
+                fi
+                bash "$SCRIPT_DIR/commands/docs.sh" "$docs_unit" "$PACKAGE_ROOT" --check
+            done
 
             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"
+            for docs_unit in "${DOCS_UNITS[@]}"; do
+                if [ ${#DOCS_UNITS[@]} -gt 1 ]; then
+                    printf "%s\n" "${docs_unit#"$PROJECT_ROOT/"}"
+                fi
+                bash "$SCRIPT_DIR/commands/docs.sh" "$docs_unit" "$PACKAGE_ROOT"
+            done
+
+            if [ ${#DOCS_UNITS[@]} -gt 1 ]; then
+                printf "\n${GREEN}Docs generated for %d packages${NC}\n" ${#DOCS_UNITS[@]}
+            else
+                printf "\n${GREEN}Docs generated at docs/${NC}\n"
+            fi
         fi
         ;;
 

package/lib/merge-knip-config.js

@@ -14,12 +14,21 @@
  *
  * Dynamic detection:
  *   - Published library (main/exports/publishConfig) → disable exports/types/files rules
- *   - Auto-ignore docs/**, fixtures/**, expected/** convention paths
+ *   - Auto-ignore docs/**, fixtures/**, expected/** convention paths — at the root
+ *     AND inside every workspace member, because the convention is the package's
+ *     and knip resolves `ignore` globs from the root
  *   - Vitest workspace workaround → explicit vitest config when vitest is a dependency
+ *
+ * Knip itself is workspace-aware: it reads the `workspaces` globs and reports per
+ * member from one run. A consumer that needs per-member knip settings spells them
+ * under a `workspaces` key in its own knip.json — the base preset has none, so the
+ * key passes through the merge untouched.
  */
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 
+import { workspaceMembers } from './workspace-members.js';
+
 const basePath = process.argv[2];
 const projectPath = process.argv[3];
 
@@ -68,19 +77,26 @@ if (pkg.main || pkg.exports || pkg.publishConfig) {
     merged.rules = { exports: 'off', files: 'off', types: 'off', ...merged.rules };
 }
 
-// 2. Auto-ignore convention paths that exist on disk
+// 2. Auto-ignore convention paths that exist on disk.
+//    The convention belongs to a PACKAGE, so the scan runs once per unit — the
+//    Root and each workspace member. Knip resolves `ignore` globs from the root,
+//    So a member's paths are emitted with their member prefix.
 const conventionIgnores = [];
-if (existsSync('docs')) {
-    conventionIgnores.push('docs/**');
-}
+const units = ['.', ...workspaceMembers('.')];
 
-// Scan for fixtures/** and expected/** directories anywhere in the tree (up to 3 levels)
-const scanDirs = ['specs', 'tests', 'test', 'src'];
-for (const root of scanDirs) {
-    if (!existsSync(root)) {
-        continue;
+for (const unit of units) {
+    const prefix = unit === '.' ? '' : `${unit}/`;
+
+    if (existsSync(`${prefix}docs`)) {
+        conventionIgnores.push(`${prefix}docs/**`);
+    }
+
+    // Scan for fixtures/** and expected/** directories anywhere in the unit (up to 3 levels)
+    for (const scanDir of ['specs', 'tests', 'test', 'src']) {
+        if (existsSync(`${prefix}${scanDir}`)) {
+            findConventionDirs(`${prefix}${scanDir}`, 0);
+        }
     }
-    findConventionDirs(root, 0);
 }
 
 function findConventionDirs(dir, depth) {

package/lib/workspace-members.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+/**
+ * The workspace members declared by a package.json — the unit every
+ * per-package gate measures from.
+ *
+ * As a module: `workspaceMembers(root)` returns the member directories,
+ * relative to the root, no trailing slash, sorted. As a CLI, the same list on
+ * stdout, one per line:
+ *
+ *     node workspace-members.js [root]
+ *
+ * The toolchain's unit is the workspace PACKAGE, not the repository: a gate
+ * that reads `specs/` or `docs/` at cwd sees only the root's, and a monorepo's
+ * members are silently never checked. Callers ask here what the members are;
+ * the list is empty when the package declares no `workspaces`, and the caller
+ * falls back to the root itself.
+ *
+ * Supported declarations (the npm/yarn/bun surface):
+ *   "workspaces": ["apps/*", "packages/*"]
+ *   "workspaces": { "packages": ["apps/*"] }        // yarn classic
+ *
+ * A member is a directory matching a glob AND holding a package.json — the
+ * same rule the package managers apply. Globs support `*` (one segment) and
+ * `**` (any depth); `node_modules`, `dist` and dot-directories are never
+ * descended into.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import { argv, stdout } from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const SKIPPED = new Set(['dist', 'node_modules']);
+
+/** A glob over path segments — `*` stops at a separator, `**` does not. */
+function toPattern(glob) {
+    const escaped = glob
+        .replaceAll(/[.+^${}()|[\]\\]/g, String.raw`\$&`)
+        .replaceAll('**', ' ')
+        .replaceAll('*', '[^/]*')
+        .replaceAll(' ', '.*');
+
+    return new RegExp(`^${escaped}$`);
+}
+
+/** The `workspaces` globs of a package.json, in either declared form. */
+function declaredGlobs(root) {
+    const manifest = join(root, 'package.json');
+    if (!existsSync(manifest)) {
+        return [];
+    }
+
+    let declared;
+    try {
+        const pkg = JSON.parse(readFileSync(manifest, 'utf8'));
+        declared = Array.isArray(pkg.workspaces) ? pkg.workspaces : pkg.workspaces?.packages;
+    } catch {
+        return [];
+    }
+
+    return Array.isArray(declared) ? declared : [];
+}
+
+/**
+ * The member directories of the workspace rooted at `root` — empty for a
+ * single-package project, which every caller reads as "the root is the unit".
+ */
+export function workspaceMembers(root = '.') {
+    const absolute = resolve(root);
+    const patterns = declaredGlobs(absolute)
+        .filter((glob) => typeof glob === 'string' && !glob.startsWith('!'))
+        .map((glob) => toPattern(glob.replace(/\/+$/, '')));
+
+    if (patterns.length === 0) {
+        return [];
+    }
+
+    const members = new Set();
+
+    /** Walk the tree once, keeping every directory a pattern claims as a package. */
+    function walk(dir, depth) {
+        if (depth > 6) {
+            return;
+        }
+
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith('.') || SKIPPED.has(entry.name)) {
+                continue;
+            }
+
+            const child = join(dir, entry.name);
+            const path = relative(absolute, child).split(sep).join('/');
+
+            if (
+                patterns.some((pattern) => pattern.test(path)) &&
+                existsSync(join(child, 'package.json'))
+            ) {
+                members.add(path);
+                continue;
+            }
+
+            walk(child, depth + 1);
+        }
+    }
+
+    walk(absolute, 0);
+
+    return [...members].sort();
+}
+
+// CLI form — only when this file IS the process entry, never on import.
+if (argv[1] && resolve(argv[1]) === fileURLToPath(import.meta.url)) {
+    const members = workspaceMembers(argv[2] ?? '.');
+    if (members.length > 0) {
+        stdout.write(`${members.join('\n')}\n`);
+    }
+}

package/package.json

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

package/presets/oxlint/plugins/codestyle.js

@@ -78,6 +78,41 @@ function createHexagonalRule() {
 // Imports-with-ext - Require .js extensions
 // ============================================
 
+// The extensions a bundler or Node actually resolves from an import specifier.
+// Anything else after a dot is part of the module NAME (`user.entity`,
+// `dashboard.post`, `article.repository`) and still needs its `.js`.
+const KNOWN_IMPORT_EXTENSIONS = [
+    'cjs',
+    'css',
+    'cts',
+    'graphql',
+    'gql',
+    'html',
+    'jpeg',
+    'jpg',
+    'js',
+    'json',
+    'jsx',
+    'less',
+    'md',
+    'mdx',
+    'mjs',
+    'mts',
+    'node',
+    'png',
+    'sass',
+    'scss',
+    'svg',
+    'toml',
+    'ts',
+    'tsx',
+    'txt',
+    'wasm',
+    'webp',
+    'yaml',
+    'yml',
+];
+
 const importsWithExtRule = {
     meta: {
         type: 'problem',
@@ -89,7 +124,9 @@ const importsWithExtRule = {
         schema: [],
     },
     create(context) {
-        const hasExtension = /\.[a-zA-Z0-9]+$/;
+        // Only a KNOWN extension counts as already-extended — "anything after the
+        // Last dot" read `./entities/dashboard.post` as extended and skipped it.
+        const hasExtension = new RegExp(`\\.(?:${KNOWN_IMPORT_EXTENSIONS.join('|')})$`, 'i');
 
         function checkNode(node) {
             if (!node.source || !node.source.value) {

package/presets/tsconfig/expo.json

@@ -1,7 +1,7 @@
 {
     "display": "Expo",
-    "include": ["../../../../**/*.ts", "../../../../**/*.tsx"],
-    "exclude": ["../../../../node_modules"],
+    "include": ["${configDir}/**/*.ts", "${configDir}/**/*.tsx"],
+    "exclude": ["${configDir}/node_modules"],
 
     "compilerOptions": {
         "allowJs": true,

package/presets/tsconfig/node.json

@@ -1,7 +1,7 @@
 {
     "display": "Node ESM",
-    "include": ["../../../../**/*.ts"],
-    "exclude": ["../../../../node_modules"],
+    "include": ["${configDir}/**/*.ts"],
+    "exclude": ["${configDir}/node_modules"],
 
     "compilerOptions": {
         "moduleResolution": "Bundler",