feat(config): add smartconfig metadata and update TypeScript build configuration docs

2026-03-24 18:13:56 +00:00
parent cfe2eafe89
commit 724e5bf7ec
10 changed files with 1196 additions and 2042 deletions
--- a/readme.md
+++ b/readme.md
@@ -1,12 +1,12 @@
 # @git.zone/tsbuild

-A powerful, modern TypeScript build tool with smart defaults, full tsconfig.json support, and automatic output directory management. 🚀
+A powerful, modern TypeScript build tool with smart defaults, full tsconfig.json support, automatic output directory management, and cross-module import path rewriting.

 ## Issue Reporting and Security

 For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

-## 📦 Install
+## Install

 ```bash
 # Using pnpm (recommended)
@@ -16,22 +16,23 @@ pnpm install @git.zone/tsbuild --save-dev
 npm install @git.zone/tsbuild --save-dev
 ```

-## ⚡ Why tsbuild?
+## Why tsbuild?

 | Feature | Description |
 |---------|-------------|
-| 🔧 **Smart tsconfig.json Integration** | Respects all your compiler options with intelligent merging |
-| 🛡️ **Protected Defaults** | Critical build settings are safeguarded while staying flexible |
-| 🎯 **Zero Config** | Works perfectly without tsconfig.json |
-| 🌐 **Glob Pattern Support** | Compile multiple directories with a single command |
-| 📊 **Dependency-Aware** | Automatically orders compilation based on module dependencies |
-| ✅ **Type Checking** | Validate code without emitting files |
-| 🧹 **Clean Builds** | Automatically clears output directories before compilation |
-| 📁 **Auto-Unpack** | Flattens nested output directories automatically |
-| 🔄 **CI/CD Ready** | JSON output mode and proper exit codes |
-| ✨ **Modern Defaults** | ESNext, NodeNext modules, decorators out of the box |
+| **Smart tsconfig.json Integration** | Respects all your compiler options with intelligent merging |
+| **Protected Defaults** | Critical build settings are safeguarded while staying flexible |
+| **Zero Config** | Works perfectly without tsconfig.json |
+| **Glob Pattern Support** | Compile multiple directories with a single command |
+| **Dependency-Aware** | Automatically orders compilation based on module dependencies |
+| **Type Checking** | Validate code without emitting files |
+| **Clean Builds** | Automatically clears output directories before compilation |
+| **Auto-Unpack** | Flattens nested output directories automatically |
+| **Import Path Rewriting** | Rewrites cross-module imports to point at compiled output |
+| **CI/CD Ready** | JSON output mode and proper exit codes |
+| **Modern Defaults** | ESNext, NodeNext modules, decorators out of the box |

-## 🚀 Quick Start
+## Quick Start

 ### CLI Usage

@@ -46,8 +47,8 @@ Compiles `./ts/**/*.ts` to `./dist_ts/`
 npx tsbuild custom src utils
 ```
 Compiles:
- `./src/**/*.ts` → `./dist_src/`
- `./utils/**/*.ts` → `./dist_utils/`
+- `./src/**/*.ts` -> `./dist_src/`
+- `./utils/**/*.ts` -> `./dist_utils/`

 **Auto-discover and compile in dependency order:**
 ```bash
@@ -97,7 +98,7 @@ await compiler.compileGlob({
 });
 ```

-## 🛠️ CLI Commands
+## CLI Commands

 ### 1. Default Build

@@ -149,7 +150,7 @@ npx tsbuild custom src utils
 npx tsbuild custom api models services --commonjs
 ```

-### 3. TSFolders (Dependency-Aware) 📊
+### 3. TSFolders (Dependency-Aware)

 ```bash
 npx tsbuild tsfolders [options]
@@ -165,14 +166,14 @@ Automatically discovers and compiles all `ts_*` folders in dependency order:
 **Example output:**
 ```
 TypeScript Folder Compilation Plan (5 folders)
-  1/5 ts_interfaces
-  2/5 ts_shared
-  3/5 ts_core
-  4/5 ts_utils
-  5/5 ts_modules
+  1. ts_interfaces
+  2. ts_shared
+  3. ts_core
+  4. ts_utils
+  5. ts_modules
 ```

-### 4. Emit Check ✓
+### 4. Emit Check

 ```bash
 npx tsbuild emitcheck <file_or_pattern> [more...] [options]
@@ -192,7 +193,7 @@ npx tsbuild emitcheck "src/**/*.ts" "test/**/*.ts"
 - `0` - All files can be emitted
 - `1` - One or more files have errors

-### 5. Type Check 🔍
+### 5. Type Check

 ```bash
 npx tsbuild check [pattern] [more...] [options]
@@ -218,7 +219,7 @@ npx tsbuild check
 # All default type checks passed!
 ```

-## 📖 API Reference
+## API Reference

 ### TsCompiler Class

@@ -285,7 +286,7 @@ try {

 #### compileGlob(globPatterns, customOptions?)

-Compile multiple glob patterns to different destinations. Automatically clears output directories before compilation and unpacks nested output.
+Compile multiple glob patterns to different destinations. Automatically clears output directories before compilation, unpacks nested output, and rewrites cross-module import paths.

 ```typescript
 const result = await compiler.compileGlob({
@@ -367,10 +368,28 @@ Flattens nested TypeScript output directories.
 ```typescript
 import { TsUnpacker } from '@git.zone/tsbuild';

-const unpacker = new TsUnpacker('./dist_ts', './ts');
+const unpacker = new TsUnpacker('ts_core', './dist_ts_core');
 await unpacker.unpack();
 ```

+#### TsPathRewriter
+
+Rewrites cross-module import paths in compiled output files. When TypeScript compiles files that import from sibling directories (e.g., `../ts_shared/helper.js`), TsPathRewriter rewrites those paths to reference the compiled output directories (`../dist_ts_shared/helper.js`).
+
+```typescript
+import { TsPathRewriter } from '@git.zone/tsbuild';
+
+// Auto-detect all ts_* folders in the project
+const rewriter = await TsPathRewriter.fromProjectDirectory(process.cwd());
+const filesModified = await rewriter.rewriteDirectory('./dist_ts_core');
+
+// Or from explicit glob patterns
+const rewriter2 = TsPathRewriter.fromGlobPatterns({
+  './ts_core/**/*.ts': './dist_ts_core',
+  './ts_shared/**/*.ts': './dist_ts_shared',
+});
+```
+
 #### FsHelpers

 Static filesystem utilities.
@@ -398,7 +417,7 @@ const cli = new TsBuildCli('/path/to/project');
 cli.run();
 ```

-## ⚙️ Configuration
+## Configuration

 ### tsconfig.json Support

@@ -419,19 +438,19 @@ tsbuild fully supports all compiler options from `tsconfig.json`. Your project c
 }
 ```

-### Configuration Priority (5 Levels) 📋
+### Configuration Priority (5 Levels)

 When multiple configuration sources exist, they merge in this order (later overrides earlier):

 | Priority | Source | Description |
 |----------|--------|-------------|
-| 1️⃣ | **Default Options** | tsbuild's sensible defaults |
-| 2️⃣ | **tsconfig.json** | All options from your tsconfig.json (if present) |
-| 3️⃣ | **Protected Defaults** | Critical options for build integrity |
-| 4️⃣ | **Programmatic Options** | Options passed to API functions |
-| 5️⃣ | **CLI Flags** | Command-line arguments (highest priority) |
+| 1 | **Default Options** | tsbuild's sensible defaults |
+| 2 | **tsconfig.json** | All options from your tsconfig.json (if present) |
+| 3 | **Protected Defaults** | Critical options for build integrity |
+| 4 | **Programmatic Options** | Options passed to API functions |
+| 5 | **CLI Flags** | Command-line arguments (highest priority) |

-### Protected Options 🛡️
+### Protected Options

 These options cannot be overridden by tsconfig.json alone (but can be overridden programmatically or via CLI):

@@ -449,8 +468,6 @@ When no tsconfig.json exists:
 ```typescript
 {
  declaration: true,              // Generate .d.ts files
-  emitDecoratorMetadata: true,    // Support DI frameworks
-  experimentalDecorators: true,   // Enable decorators
  inlineSourceMap: true,          // Debug-friendly
  noEmitOnError: true,            // Fail-fast on errors
  outDir: 'dist_ts/',             // Output directory
@@ -463,7 +480,7 @@ When no tsconfig.json exists:
 }
 ```

-### Path Transformation 🔄
+### Path Transformation

 tsbuild automatically transforms path mappings:

@@ -480,12 +497,12 @@ tsbuild automatically transforms path mappings:

 **Automatic transformation:**
 ```
-./ts_models/* → ./dist_ts_models/*
+./ts_models/* -> ./dist_ts_models/*
 ```

-## ✨ Features
+## Features

-### Clean Builds 🧹
+### Clean Builds

 Output directories are automatically cleared before compilation:

@@ -496,7 +513,23 @@ Compiling 14 files from ./ts/**/*.ts

 This ensures no stale files remain from previous builds.

-### Monorepo Support with tspublish 📦
+### Import Path Rewriting
+
+When working with multi-module projects (multiple `ts_*` folders), TypeScript compiles import paths relative to source directories. After compilation and unpacking, these paths would be wrong because the directory structure changes.
+
+tsbuild automatically detects all `ts_*` folders in the project and rewrites import paths in the compiled output:
+
+```
+# Source code
+import { helper } from '../ts_shared/helper.js';
+
+# Compiled output (after rewriting)
+import { helper } from '../dist_ts_shared/helper.js';
+```
+
+This works for ES module imports, dynamic `import()` calls, and CommonJS `require()` statements. The rewriting happens automatically as part of `compileGlob()`.
+
+### Monorepo Support with tspublish

 tsbuild is designed to work seamlessly with [@git.zone/tspublish](https://code.foss.global/git.zone/tspublish) for monorepo workflows. This enables building and publishing multiple packages from a single repository.

@@ -504,12 +537,12 @@ tsbuild is designed to work seamlessly with [@git.zone/tspublish](https://code.f

 ```
 my-project/
-├── ts/                    # Main package source
-├── ts_interfaces/         # Shared interfaces (order: 1)
-├── ts_shared/             # Shared utilities (order: 2)
-├── ts_core/               # Core logic (order: 3)
-├── ts_web/                # Web-specific code (order: 4)
-└── ts_node/               # Node-specific code (order: 5)
+  ts/                    # Main package source
+  ts_interfaces/         # Shared interfaces (order: 1)
+  ts_shared/             # Shared utilities (order: 2)
+  ts_core/               # Core logic (order: 3)
+  ts_web/                # Web-specific code (order: 4)
+  ts_node/               # Node-specific code (order: 5)
 ```

 Each `ts_*` folder can contain its own `tspublish.json` to configure compilation and publishing behavior.
@@ -529,10 +562,10 @@ Create a `tspublish.json` in each `ts_*` folder:

 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `name` | string | — | Package name for publishing |
+| `name` | string | -- | Package name for publishing |
 | `order` | number | `Infinity` | Build sequence (lower builds first) |
 | `unpack` | boolean | `true` | Flatten nested output directories |
-| `dependencies` | string[] | — | Monorepo dependencies to bundle |
+| `dependencies` | string[] | -- | Monorepo dependencies to bundle |

 #### Build Order

@@ -548,31 +581,21 @@ npx tsbuild tsfolders
 3. Other folders sorted by `order` property
 4. Folders without `order` are built last

-**Example output:**
-```
-TypeScript Folder Compilation Plan (5 folders)
-  1/5 ts_interfaces  (order: 1)
-  2/5 ts_shared      (order: 2)
-  3/5 ts_core        (order: 3)
-  4/5 ts_web         (order: 4)
-  5/5 ts_node        (order: 5)
-```
-
-### Auto-Unpack 📁
+### Auto-Unpack

 When TypeScript compiles files that import from sibling directories, it creates nested output:

 ```
 dist_ts_core/
-  ts_core/        ← nested output
-  ts_shared/      ← pulled-in dependency
+  ts_core/        <-- nested output
+  ts_shared/      <-- pulled-in dependency
 ```

 tsbuild automatically flattens this to:

 ```
 dist_ts_core/
-  index.js        ← flat, clean structure
+  index.js        <-- flat, clean structure
 ```

 This is especially important for monorepos where packages import from each other.
@@ -591,11 +614,11 @@ This is especially important for monorepos where packages import from each other
 - The source folder's contents (`ts_core/`) are moved to the root of `dist_ts_core/`
 - Sibling folders (`ts_shared/`) that were pulled in are removed (they have their own dist)

-### Decorator Support 🎨
+### Decorator Support

 tsbuild supports both **TC39 standard decorators** (recommended) and legacy experimental decorators.

-**TC39 Standard Decorators (Preferred)** 🌟
+**TC39 Standard Decorators (Preferred)**

 We strongly recommend using TC39 standard decorators for all new code. They are the official JavaScript standard and provide better semantics:

@@ -618,19 +641,8 @@ class UserService {

 **Legacy Decorators (Backwards Compatibility)**

-For existing projects using frameworks like NestJS, TypeORM, or Angular that still require experimental decorators:
+For existing projects using frameworks that still require experimental decorators:

-```typescript
-@Injectable()
-class UserService {
-  constructor(
-    @Inject('CONFIG') private config: Config,
-    private logger: Logger
-  ) {}
-}
-```
-
-Enable legacy decorators in your `tsconfig.json`:
 ```json
 {
  "compilerOptions": {
@@ -640,9 +652,18 @@ Enable legacy decorators in your `tsconfig.json`:
 }
 ```

-> 💡 **Tip:** When starting new projects or migrating existing ones, prefer TC39 decorators. They're the future of JavaScript and don't require experimental flags.
+### Structured Logging

-## 🔄 CI/CD Integration
+tsbuild uses a 4-level visual hierarchy for console output, making it easy to follow compilation progress:
+
+- **HEADER** - Top-level section start (emoji + bold text + separator)
+- **STEP** - Major action within a section (emoji + text)
+- **DETAIL** - Supplementary info under a step (indented)
+- **SUCCESS/ERROR/WARN** - Outcome indicators with color coding
+
+All output uses ANSI color codes for terminal readability. Use `--quiet` to suppress output or `--json` for machine-readable format.
+
+## CI/CD Integration

 ### GitHub Actions

@@ -657,7 +678,7 @@ jobs:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
-          node-version: '20'
+          node-version: '22'

      - run: npm install
      - run: npx tsbuild
@@ -694,7 +715,7 @@ npx tsbuild --json --quiet
 }
 ```

-## 🔧 Troubleshooting
+## Troubleshooting

 ### Common Issues

@@ -725,7 +746,7 @@ Only use this if you trust your dependencies' type definitions.

 ## License and Legal Information

-This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./license) file.

 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.