@jterrazz/typescript 5.2.0 → 6.0.0

package/bin/typescript.sh

@@ -87,19 +87,37 @@ case "$COMMAND" in
             --on-success "node --enable-source-maps dist/index.js"
         ;;
 
+    docs)
+        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"
+        ;;
+
+    check|fix)
+        exec bash "$SCRIPT_DIR/commands/check.sh" "$COMMAND" "$@"
+        ;;
+
     *)
-        printf "${CYAN_BG}${BRIGHT_WHITE} TYPESCRIPT ${NC} TypeScript/Node project toolkit\n\n"
+        printf "${CYAN_BG}${BRIGHT_WHITE} TYPESCRIPT ${NC} TypeScript toolchain\n\n"
         printf "Usage: typescript <command>\n\n"
         printf "Commands:\n"
         printf "  build     Build application (ESM + types)\n"
         printf "  bundle    Bundle library (ESM + CJS + types)\n"
         printf "  start     Run the built application\n"
-        printf "  dev       Build, run, and rebuild on changes\n\n"
+        printf "  dev       Build, run, and rebuild on changes\n"
+        printf "  docs      Generate API reference + llms.txt from TSDoc\n"
+        printf "  check     Check types, lint, formatting, and unused code\n"
+        printf "  fix       Auto-fix lint and formatting issues\n\n"
         printf "Examples:\n"
         printf "  typescript build\n"
         printf "  typescript bundle\n"
         printf "  typescript start\n"
         printf "  typescript dev\n"
+        printf "  typescript docs\n"
+        printf "  typescript check\n"
+        printf "  typescript fix\n"
         exit 1
         ;;
 esac

package/package.json

@@ -1,35 +1,50 @@
 {
-  "name": "@jterrazz/typescript",
-  "version": "5.2.0",
-  "author": "Jean-Baptiste Terrazzoni <contact@jterrazz.com>",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/jterrazz/package-typescript"
-  },
-  "bin": {
-    "typescript": "bin/typescript.sh"
-  },
-  "files": [
-    "bin",
-    "presets"
-  ],
-  "type": "module",
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/"
-  },
-  "scripts": {
-    "lint": "codestyle check",
-    "lint:fix": "codestyle fix",
-    "test": "vitest --run",
-    "build": "# no build script"
-  },
-  "dependencies": {
-    "tsdown": "^0.21.5"
-  },
-  "devDependencies": {
-    "@jterrazz/codestyle": "^2.1.0",
-    "@jterrazz/test": "^3.4.0",
-    "@types/node": "^25.5.0",
-    "vitest": "^4.1.2"
-  }
+    "name": "@jterrazz/typescript",
+    "version": "6.0.0",
+    "author": "Jean-Baptiste Terrazzoni <contact@jterrazz.com>",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/jterrazz/package-typescript"
+    },
+    "bin": {
+        "typescript": "bin/typescript.sh"
+    },
+    "files": [
+        "bin",
+        "presets",
+        "src"
+    ],
+    "type": "module",
+    "main": "src/index.js",
+    "exports": {
+        ".": "./src/index.js",
+        "./tsconfig/*": "./presets/tsconfig/*.json",
+        "./tsdown/*": "./presets/tsdown/*.js",
+        "./presets/tsconfig/*": "./presets/tsconfig/*.json",
+        "./presets/tsdown/*": "./presets/tsdown/*.js"
+    },
+    "publishConfig": {
+        "registry": "https://registry.npmjs.org/"
+    },
+    "scripts": {
+        "build": "# no build script",
+        "lint": "./bin/typescript.sh check --ignore-pattern '**/fixtures/**'",
+        "lint:fix": "./bin/typescript.sh fix --ignore-pattern '**/fixtures/**'",
+        "test": "vitest --run"
+    },
+    "dependencies": {
+        "@typescript/native-preview": "^7.0.0-dev.20260327.2",
+        "eslint-plugin-perfectionist": "^5.7.0",
+        "knip": "^6.2.0",
+        "oxfmt": "^0.42.0",
+        "oxlint": "^1.57.0",
+        "tsdown": "^0.21.5",
+        "typedoc": "^0.28.19",
+        "typedoc-plugin-markdown": "^4.11.0"
+    },
+    "devDependencies": {
+        "@jterrazz/test": "^5.3.2",
+        "@types/node": "^25.5.0",
+        "vitest": "^4.1.2"
+    }
 }

package/presets/knip/base.json

@@ -0,0 +1,5 @@
+{
+    "$schema": "https://unpkg.com/knip@6/schema.json",
+    "ignoreDependencies": ["@jterrazz/codestyle", "@jterrazz/test", "@jterrazz/typescript"],
+    "ignoreBinaries": ["oxlint", "oxfmt"]
+}

package/presets/oxfmt/index.js

@@ -0,0 +1,12 @@
+import { defineConfig } from 'oxfmt';
+
+export default defineConfig({
+    printWidth: 100,
+    tabWidth: 4,
+    useTabs: false,
+    semi: true,
+    singleQuote: true,
+    trailingComma: 'all',
+    bracketSpacing: true,
+    endOfLine: 'lf',
+});

package/presets/oxlint/architectures/hexagonal-rules.js

@@ -0,0 +1,39 @@
+export default [
+    {
+        from: '/domain/',
+        disallow: [
+            '/application/',
+            '/infrastructure/',
+            '/presentation/',
+            '/di/',
+            '/config/',
+            '/generated/',
+        ],
+        message: 'Domain layer must be pure - cannot import from other layers',
+    },
+    {
+        from: '/application/use-cases/',
+        disallow: ['/infrastructure/', '/presentation/', '/di/'],
+        message: 'Use cases can only depend on domain and ports',
+    },
+    {
+        from: '/application/ports/',
+        disallow: ['/infrastructure/', '/presentation/', '/di/'],
+        message: 'Ports are interfaces - cannot depend on implementations',
+    },
+    {
+        from: '/infrastructure/inbound/',
+        disallow: ['/infrastructure/outbound/'],
+        message: 'Inbound adapters should not import outbound adapters - use DI',
+    },
+    {
+        from: '/presentation/ui/(atoms|molecules)/',
+        disallow: ['/navigation/'],
+        message: 'Atoms and molecules must be pure - no navigation imports',
+    },
+    {
+        from: '/presentation/features/',
+        disallow: ['/presentation/features/(?!common)'],
+        message: 'Features should be independent - use shared code in features/common',
+    },
+];

package/presets/oxlint/architectures/hexagonal.js

@@ -0,0 +1,13 @@
+import { resolve } from 'node:path';
+import { defineConfig } from 'oxlint';
+
+import defaultRules from './hexagonal-rules.js';
+
+const pluginPath = resolve(import.meta.dirname, '../plugins/codestyle.js');
+
+export default defineConfig({
+    jsPlugins: [pluginPath],
+    rules: {
+        'codestyle/arch-hexagonal': ['error', { rules: defaultRules }],
+    },
+});

package/presets/oxlint/base.js

@@ -0,0 +1,128 @@
+import { createRequire } from 'node:module';
+import { defineConfig } from 'oxlint';
+
+const require = createRequire(import.meta.url);
+const perfectionistPath = require.resolve('eslint-plugin-perfectionist');
+
+export default defineConfig({
+    plugins: ['typescript', 'import', 'oxc', 'unicorn'],
+    jsPlugins: [perfectionistPath],
+    categories: {
+        correctness: 'error',
+        suspicious: 'error',
+        perf: 'error',
+        pedantic: 'off',
+        style: 'error',
+        nursery: 'off',
+    },
+    rules: {
+        // ============================================
+        // ENABLED RULES
+        // ============================================
+
+        'no-unused-vars': 'error',
+
+        // -- TypeScript --
+        'typescript/consistent-type-imports': [
+            'error',
+            {
+                disallowTypeAnnotations: true,
+                fixStyle: 'inline-type-imports',
+                prefer: 'type-imports',
+            },
+        ],
+        'typescript/no-unused-expressions': [
+            'error',
+            {
+                allowShortCircuit: true,
+                allowTernary: true,
+                allowTaggedTemplates: true,
+            },
+        ],
+
+        // -- Perfectionist (sorting/ordering) --
+        'perfectionist/sort-heritage-clauses': ['error', { type: 'natural' }],
+        'perfectionist/sort-intersection-types': ['error', { type: 'natural' }],
+        'perfectionist/sort-jsx-props': ['error', { type: 'natural' }],
+        'perfectionist/sort-named-exports': ['error', { type: 'natural' }],
+        'perfectionist/sort-named-imports': ['error', { type: 'natural' }],
+        'perfectionist/sort-union-types': ['error', { type: 'natural' }],
+        'perfectionist/sort-imports': [
+            'error',
+            {
+                type: 'alphabetical',
+                order: 'asc',
+                ignoreCase: true,
+                newlinesBetween: 1,
+                groups: [
+                    ['builtin', 'external'],
+                    'internal',
+                    ['parent', 'sibling', 'index'],
+                    'style',
+                    'unknown',
+                ],
+            },
+        ],
+
+        // ============================================
+        // DISABLED - Conflicts with perfectionist
+        // ============================================
+
+        'sort-keys': 'off',
+        'sort-imports': 'off',
+
+        // ============================================
+        // DISABLED - Too strict / opinionated
+        // ============================================
+
+        'func-style': 'off',
+        'no-magic-numbers': 'off',
+        'no-ternary': 'off',
+        'init-declarations': 'off',
+        'id-length': 'off',
+        'max-statements': 'off',
+        'max-params': 'off',
+        'no-continue': 'off',
+        'arrow-body-style': 'off',
+        'prefer-destructuring': 'off',
+        'new-cap': 'off',
+        'no-await-in-loop': 'off',
+        'typescript/consistent-type-definitions': 'off',
+        'typescript/array-type': 'off',
+        'typescript/no-inferrable-types': 'off',
+        'unicorn/no-null': 'off',
+        'unicorn/no-array-sort': 'off',
+        'import/no-unassigned-import': 'off',
+        'import/no-named-default': 'off',
+        'import/no-nodejs-modules': 'off',
+
+        // ============================================
+        // ENABLED - Code style enforcement
+        // ============================================
+
+        'capitalized-comments': 'error',
+        curly: 'error',
+        'no-nested-ternary': 'error',
+        'unicorn/catch-error-name': 'error',
+        'unicorn/numeric-separators-style': 'error',
+
+        // ============================================
+        // DISABLED - Conflicts with other rules
+        // ============================================
+
+        'import/no-named-export': 'off',
+        'import/consistent-type-specifier-style': 'off',
+        'import/prefer-default-export': 'off',
+        'import/no-default-export': 'off',
+        'import/group-exports': 'off',
+        'import/no-anonymous-default-export': 'off',
+
+        // ============================================
+        // ENABLED - Clean imports
+        // ============================================
+
+        'import/first': 'error',
+        'import/no-namespace': 'error',
+    },
+    ignorePatterns: ['dist/**', 'node_modules/**'],
+});

package/presets/oxlint/expo.js

@@ -0,0 +1,33 @@
+import { resolve } from 'node:path';
+import { defineConfig } from 'oxlint';
+
+import base from './base.js';
+
+const pluginPath = resolve(import.meta.dirname, 'plugins/codestyle.js');
+
+export default defineConfig({
+    extends: [base],
+    plugins: ['typescript', 'import', 'react'],
+    jsPlugins: [pluginPath],
+    rules: {
+        'typescript/no-require-imports': [
+            'error',
+            {
+                allow: [
+                    String.raw`\.png$`,
+                    String.raw`\.jpg$`,
+                    String.raw`\.jpeg$`,
+                    String.raw`\.gif$`,
+                    String.raw`\.webp$`,
+                ],
+            },
+        ],
+        'codestyle/imports-without-ext': 'error',
+        'react/react-in-jsx-scope': 'off',
+        'react/jsx-props-no-spreading': 'off',
+        'react/jsx-boolean-value': 'off',
+        'react/jsx-handler-names': 'off',
+        'react/jsx-curly-brace-presence': 'off',
+        'unicorn/no-nested-ternary': 'off',
+    },
+});

package/presets/oxlint/next.js

@@ -0,0 +1,23 @@
+import { resolve } from 'node:path';
+import { defineConfig } from 'oxlint';
+
+import base from './base.js';
+
+const pluginPath = resolve(import.meta.dirname, 'plugins/codestyle.js');
+
+export default defineConfig({
+    extends: [base],
+    plugins: ['typescript', 'import', 'react', 'nextjs'],
+    jsPlugins: [pluginPath],
+    ignorePatterns: ['dist/**', 'node_modules/**', '.next/**', 'next-env.d.ts'],
+    rules: {
+        'codestyle/imports-without-ext': 'error',
+        'react/react-in-jsx-scope': 'off',
+        'react/jsx-props-no-spreading': 'off',
+        'react/jsx-boolean-value': 'off',
+        'react/jsx-handler-names': 'off',
+        'react/jsx-curly-brace-presence': 'off',
+        'react/jsx-max-depth': 'off',
+        'unicorn/no-nested-ternary': 'off',
+    },
+});

package/presets/oxlint/node.js

@@ -0,0 +1,14 @@
+import { resolve } from 'node:path';
+import { defineConfig } from 'oxlint';
+
+import base from './base.js';
+
+const pluginPath = resolve(import.meta.dirname, 'plugins/codestyle.js');
+
+export default defineConfig({
+    extends: [base],
+    jsPlugins: [pluginPath],
+    rules: {
+        'codestyle/imports-with-ext': 'error',
+    },
+});

package/presets/oxlint/plugins/codestyle.js

@@ -0,0 +1,194 @@
+// Codestyle plugin - custom rules for code quality
+// Contains: architecture boundaries, import extensions
+
+import defaultHexagonalRules from '../architectures/hexagonal-rules.js';
+
+// ============================================
+// Hexagonal - Architecture boundary rules
+// ============================================
+
+function createHexagonalRule() {
+    return {
+        meta: {
+            type: 'problem',
+            docs: {
+                description: 'Enforce hexagonal architecture layer boundaries',
+                category: 'Best Practices',
+            },
+            schema: [
+                {
+                    type: 'object',
+                    properties: {
+                        rules: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    from: { type: 'string' },
+                                    disallow: { type: 'array', items: { type: 'string' } },
+                                    message: { type: 'string' },
+                                },
+                                required: ['from', 'disallow'],
+                            },
+                        },
+                    },
+                },
+            ],
+        },
+        create(context) {
+            const options = context.options[0];
+            const rules = options && options.rules ? options.rules : defaultHexagonalRules;
+            const filename = context.getFilename();
+
+            function checkNode(node) {
+                if (!node.source || !node.source.value) {
+                    return;
+                }
+
+                const importPath = node.source.value;
+
+                for (const rule of rules) {
+                    const fromPattern = new RegExp(rule.from);
+                    if (!fromPattern.test(filename)) {
+                        continue;
+                    }
+
+                    for (const disallowPattern of rule.disallow) {
+                        if (new RegExp(disallowPattern).test(importPath)) {
+                            context.report({
+                                node: node.source,
+                                message: rule.message || 'Import violates architecture boundaries',
+                            });
+                            break;
+                        }
+                    }
+                }
+            }
+
+            return {
+                ImportDeclaration: checkNode,
+                ExportNamedDeclaration: checkNode,
+                ExportAllDeclaration: checkNode,
+            };
+        },
+    };
+}
+
+// ============================================
+// Imports-with-ext - Require .js extensions
+// ============================================
+
+const importsWithExtRule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require .js extension in imports for Node.js ESM compatibility',
+            category: 'Best Practices',
+        },
+        fixable: 'code',
+        schema: [],
+    },
+    create(context) {
+        const hasExtension = /\.[a-zA-Z0-9]+$/;
+
+        function checkNode(node) {
+            if (!node.source || !node.source.value) {
+                return;
+            }
+
+            const importPath = node.source.value;
+
+            // Only check relative imports
+            if (!importPath.startsWith('.')) {
+                return;
+            }
+
+            // Skip if it already has an extension
+            if (hasExtension.test(importPath)) {
+                return;
+            }
+
+            // Skip type-only imports (they are erased at runtime)
+            if (node.importKind === 'type') {
+                return;
+            }
+
+            context.report({
+                node: node.source,
+                message: 'Missing .js extension in import (required for Node.js ESM)',
+                fix(fixer) {
+                    const newPath = `${importPath}.js`;
+                    return fixer.replaceText(node.source, `'${newPath}'`);
+                },
+            });
+        }
+
+        return {
+            ImportDeclaration: checkNode,
+            ExportNamedDeclaration: checkNode,
+            ExportAllDeclaration: checkNode,
+        };
+    },
+};
+
+// ============================================
+// Imports-without-ext - Remove extensions
+// ============================================
+
+const importsWithoutExtRule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Remove .js, .jsx, .ts, .tsx extensions from imports',
+            category: 'Best Practices',
+        },
+        fixable: 'code',
+        schema: [],
+    },
+    create(context) {
+        const extensionsToRemove = /\.(?:js|jsx|ts|tsx)$/;
+
+        function checkNode(node) {
+            if (!node.source || !node.source.value) {
+                return;
+            }
+
+            const importPath = node.source.value;
+
+            // Check both relative imports and path alias imports
+            if (!importPath.startsWith('.') && !importPath.startsWith('@/')) {
+                return;
+            }
+
+            if (extensionsToRemove.test(importPath)) {
+                const match = importPath.match(extensionsToRemove);
+                context.report({
+                    node: node.source,
+                    message: `Remove "${match[0]}" extension from import`,
+                    fix(fixer) {
+                        const newPath = importPath.replace(extensionsToRemove, '');
+                        return fixer.replaceText(node.source, `'${newPath}'`);
+                    },
+                });
+            }
+        }
+
+        return {
+            ImportDeclaration: checkNode,
+            ExportNamedDeclaration: checkNode,
+            ExportAllDeclaration: checkNode,
+        };
+    },
+};
+
+export default {
+    meta: {
+        name: 'codestyle',
+        version: '1.0.0',
+    },
+    rules: {
+        'arch-hexagonal': createHexagonalRule(),
+        'imports-with-ext': importsWithExtRule,
+        'imports-without-ext': importsWithoutExtRule,
+    },
+};

package/presets/tsconfig/expo.json

@@ -1,21 +1,21 @@
 {
-  "display": "Expo",
-  "include": ["../../../../**/*.ts", "../../../../**/*.tsx"],
-  "exclude": ["../../../../node_modules"],
+    "display": "Expo",
+    "include": ["../../../../**/*.ts", "../../../../**/*.tsx"],
+    "exclude": ["../../../../node_modules"],
 
-  "compilerOptions": {
-    "allowJs": true,
-    "baseUrl": ".",
-    "esModuleInterop": true,
-    "jsx": "react-native",
-    "lib": ["DOM", "ESNext"],
-    "moduleResolution": "node",
-    "noEmit": true,
-    "paths": {
-      "@/*": ["src/*"]
-    },
-    "resolveJsonModule": true,
-    "skipLibCheck": true,
-    "target": "ESNext"
-  }
+    "compilerOptions": {
+        "allowJs": true,
+        "baseUrl": ".",
+        "esModuleInterop": true,
+        "jsx": "react-native",
+        "lib": ["DOM", "ESNext"],
+        "moduleResolution": "node",
+        "noEmit": true,
+        "paths": {
+            "@/*": ["src/*"]
+        },
+        "resolveJsonModule": true,
+        "skipLibCheck": true,
+        "target": "ESNext"
+    }
 }