@jterrazz/typescript 6.1.1 → 6.2.0

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,71 @@ 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
+
     # 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=$?; }
 
-    # 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
     fi
 
     # Summary
@@ -178,7 +255,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 ]; then
         printf "${GREEN}✓ All checks passed${NC}\n"
         exit 0
     else

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": "6.2.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/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');
+    }
+});