v3.1.0

changelog.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 2025-11-17 - 3.1.0 - feat(tsbuild.classes)
+Update default TypeScript lib to lib.esnext.d.ts
+
+- Changed default compilerOptions.lib from ['lib.dom.d.ts', 'lib.es2022.d.ts'] to ['lib.dom.d.ts', 'lib.esnext.d.ts'] in compilerOptionsDefault.
+- Allows newer ECMAScript/DOM features by default when compiling with tsbuild (affects emitted types and available globals).
+- Behavioral default change only — no public API changes; callers can still override lib via tsconfig, programmatic options, or CLI.
+
+## 2025-11-17 - 3.0.0 - BREAKING CHANGE(TsBuild)
+Stop forcing emitDecoratorMetadata in protected compiler defaults
+
+- Removed emitDecoratorMetadata from the set of protected/critical default compiler options.
+- Projects that relied on tsbuild automatically enabling emitDecoratorMetadata (for DI frameworks like NestJS, TypeORM, Inversify) must now enable it explicitly in their tsconfig.json or via programmatic/CLI options.
+- No other protected defaults were changed; outDir, noEmitOnError, declaration and inlineSourceMap remain enforced.
+- Behavior is now more permissive: decorator metadata generation is controlled by user configuration rather than being forced by tsbuild.
+
+## 2025-11-17 - 2.7.3 - fix(tsbuild.classes)
+Remove duplicate emitDecoratorMetadata from default compiler options and centralize it in protected defaults
+
+- Removed emitDecoratorMetadata from compilerOptionsDefault in ts/tsbuild.classes.tsbuild.ts to avoid duplicate configuration.
+- emitDecoratorMetadata remains enforced via getCriticalDefaults(), ensuring decorator metadata support is protected from tsconfig.json overrides.
+- Prevents inconsistencies during compiler option merging by centralizing the decorator-related setting.
+
+## 2025-11-17 - 2.7.2 - fix(compilerOptions)
+Remove experimentalDecorators and useDefineForClassFields from default TypeScript compiler options
+
+- Removed experimentalDecorators from compilerOptionsDefault in ts/tsbuild.classes.tsbuild.ts
+- Removed useDefineForClassFields from compilerOptionsDefault in ts/tsbuild.classes.tsbuild.ts
+- Default compiler options now rely on TypeScript's upstream defaults for decorator and class field behavior
+- If your project relies on these settings, re-enable them in your tsconfig.json or pass them via the programmatic API / CLI
+
+## 2025-11-02 - 2.7.1 - fix(readme)
+Update documentation: expand README with usage, CLI and API examples; add readme.hints.md project memory
+
+- Add readme.hints.md: new project memory / quick reference with public API and CLI summaries
+- Expand and restructure readme.md: more comprehensive Quick Start, CLI Commands, API Reference, configuration, examples and troubleshooting
+- Clarify protected compiler options, default compiler options, path transformation behavior and error-handling patterns
+- Docs-only change — no source code or behavioral changes
+
 ## 2025-11-02 - 2.7.0 - feat(tsbuild)
 Add tsconfig.json support and safer compiler option merging; protect critical options; apply path and enum transforms; bump dependencies.
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git.zone/tsbuild",
-  "version": "2.7.0",
+  "version": "3.1.0",
   "private": false,
   "description": "A tool for compiling TypeScript files using the latest nightly features, offering flexible APIs and a CLI for streamlined development.",
   "main": "dist_ts/index.js",

readme.hints.md

@@ -0,0 +1,175 @@
+# @git.zone/tsbuild - Project Memory
+
+## Quick Reference
+
+### Public API (8 functions + 1 class)
+1. **compileFileArray()** - Basic compilation, throws on error
+2. **compileFileArrayWithErrorTracking()** - RECOMMENDED, returns IErrorSummary
+3. **compileGlobStringObject()** - Most powerful, multiple patterns
+4. **TsBuild Class** - Object-oriented API with compile, checkTypes, checkEmit methods
+5. **mergeCompilerOptions()** - Utility for option merging
+6. **compiler()** - Legacy function
+7. **emitCheck()** - Validate emit capability
+8. **checkTypes()** - Type checking only
+
+### CLI Commands (5)
+1. **tsbuild** (default) - Compiles ./ts/**/*.ts → ./dist_ts/
+2. **tsbuild custom <dir1> <dir2>** - Custom directory compilation
+3. **tsbuild tsfolders** - Auto-discover ts_* folders, compile in order
+4. **tsbuild emitcheck <pattern>** - Validate emit without output
+5. **tsbuild check [pattern]** - Type check only
+
+### CLI Flags
+- `--skiplibcheck` - Skip .d.ts type checking (shows warning)
+- `--confirmskiplibcheck` - Extended warning with 5s pause
+- `--disallowimplicitany` - Stricter type checking
+- `--commonjs` - Use CommonJS instead of ESNext
+- `--quiet` - Suppress non-error output
+- `--json` - JSON output format
+
+## Key Architecture Decisions
+
+### Configuration Priority (5 levels)
+1. Default options (hardcoded)
+2. tsconfig.json (if exists)
+3. Protected defaults (ensure integrity)
+4. Programmatic options (function params)
+5. CLI flags (highest priority)
+
+### Protected Options
+Cannot be overridden by tsconfig.json alone:
+- `outDir: 'dist_ts/'` - Path transformation logic
+- `noEmitOnError: true` - Build integrity
+- `declaration: true` - Library support
+- `emitDecoratorMetadata: true` - DI frameworks
+- `inlineSourceMap: true` - Debugging
+
+### Path Transformation
+- Automatic: `./ts_interfaces` → `./dist_ts_interfaces`
+- In tsconfig paths: `./ts_*` → `./dist_ts_*` (first array element only)
+
+## Default Compiler Options
+- Module: NodeNext (ESM with CommonJS fallback)
+- Target: ESNext (latest JavaScript)
+- Decorators: ENABLED (experimentalDecorators + emitDecoratorMetadata)
+- Source Maps: Inline (no separate .map files)
+- Declaration Files: ALWAYS generated (protected)
+- Output: dist_ts/
+- Implicit any: ALLOWED by default
+- esModuleInterop: true
+
+## Error Handling
+
+### Error Summary Structure
+```typescript
+interface IErrorSummary {
+  errorsByFile: Record<string, Diagnostic[]>
+  generalErrors: Diagnostic[]
+  totalErrors: number
+  totalFiles: number
+}
+```
+
+### Three Error Patterns
+1. **Throw Pattern** - compileFileArray: throws on error
+2. **Tracking Pattern** - compileFileArrayWithErrorTracking: returns IErrorSummary, NO throw
+3. **Boolean Pattern** - checkTypes/emitCheck: returns boolean
+
+RECOMMENDATION: Use compileFileArrayWithErrorTracking for production code
+
+## JSON Output Format
+```json
+{
+  "success": boolean,
+  "totals": {
+    "errors": number,
+    "filesWithErrors": number,
+    "tasks": number
+  },
+  "errorsByFile": {
+    "fileName": [
+      { "code": number, "message": string }
+    ]
+  }
+}
+```
+
+## Special Behaviors
+
+### tsfolders Command Ordering
+1. Always: ts_interfaces first
+2. Always: ts_shared second
+3. Then: Other folders by `order` property in their tspublish.json
+4. Finally: Folders without order property (Infinity)
+
+### check Command Default (No Arguments)
+Two-phase check:
+1. Phase 1: Type check ts/**/* (strict, include .d.ts)
+2. Phase 2: Type check test/**/* (relaxed, skipLibCheck: true)
+
+### Glob Pattern Support
+- `*` single level
+- `**` recursive
+- `?` single char
+- `{a,b}` alternation
+- Duplicates: Files matching multiple patterns compile multiple times
+
+### Task Information Display
+When compiling multiple files with taskInfo param:
+Shows: `[1/3] Compiling 45 files from ./src/**/*.ts`
+Plus: File counts, duration, and file type breakdown
+
+## File Structure
+- **index.ts** - Main entry, re-exports all
+- **tsbuild.exports.ts** - Core API functions
+- **tsbuild.classes.tsbuild.ts** - TsBuild class + utility functions
+- **tsbuild.cli.ts** - CLI command definitions
+- **plugins.ts** - Dependency imports (smartfile, smartpath, smartcli, etc.)
+- **paths.ts** - Path utilities (cwd, packageDir)
+
+## Dependencies Used
+- @git.zone/tspublish@^1.10.3 - Module ordering
+- @push.rocks/* - smartcli, smartfile, smartpath, smartpromise, smartdelay
+- typescript@5.9.3 - TypeScript compiler
+
+## Edge Cases
+
+1. **Empty file list** - Returns [], no error
+2. **Glob duplicates** - Files compile multiple times, possible duplicate errors
+3. **Non-existent files** - Handled by TypeScript "file not found" errors
+4. **skipLibCheck warning** - 1-line default, 5-second pause with --confirmskiplibcheck
+5. **Missing tsconfig.json** - Graceful fallback, no error
+6. **Module resolution** - --commonjs switches to NodeJs (not NodeNext)
+7. **Source maps** - Inline only (not separate .map files)
+8. **File filtering** - Only .ts and .tsx; .d.ts and .js ignored
+
+## Build Safety Features
+- `noEmitOnError: true` - Prevents broken builds
+- Error aggregation before final output
+- Protected options ensure integrity
+- Pre-emit checks before emit phase
+- CLI exit code handling (0=success, 1=error)
+
+## Recent Changes (from git log)
+- 2.6.8 - Current version
+- 2.6.7 - Previous version
+- Added confirmskiplibcheck flag
+- Improved CLI exit handling
+- JSON/quiet modes enhanced
+- Test script updates
+
+## Configuration Example (tsconfig.json)
+Paths get automatically transformed:
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@utils/*": ["./ts_utils/*"]  // → ["./dist_ts_utils/*"]
+    }
+  }
+}
+```
+
+## No ts_* folders found in project root
+The project itself doesn't have ts_interfaces, ts_shared, etc. directories.
+The tsfolders command is designed for OTHER projects using tsbuild.

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/tsbuild',
-  version: '2.7.0',
+  version: '3.1.0',
   description: 'A tool for compiling TypeScript files using the latest nightly features, offering flexible APIs and a CLI for streamlined development.'
 }

ts/tsbuild.classes.tsbuild.ts

@@ -18,18 +18,15 @@ export interface IErrorSummary {
  */
 export const compilerOptionsDefault: CompilerOptions = {
   declaration: true,
-  emitDecoratorMetadata: true,
-  experimentalDecorators: true,
   inlineSourceMap: true,
   noEmitOnError: true,
   outDir: 'dist_ts/',
   module: plugins.typescript.ModuleKind.NodeNext,
   target: plugins.typescript.ScriptTarget.ESNext,
   moduleResolution: plugins.typescript.ModuleResolutionKind.NodeNext,
-  lib: ['lib.dom.d.ts', 'lib.es2022.d.ts'],
+  lib: ['lib.dom.d.ts', 'lib.esnext.d.ts'],
   noImplicitAny: false, // Allow implicit any by default
   esModuleInterop: true,
-  useDefineForClassFields: false,
   verbatimModuleSyntax: true,
   baseUrl: './',
 };
@@ -133,7 +130,6 @@ export class TsBuild {
       outDir: 'dist_ts/',           // Required for path transformation logic
       noEmitOnError: true,           // Build integrity - prevent broken builds
       declaration: true,             // Library consumers depend on .d.ts files
-      emitDecoratorMetadata: true,   // Required for dependency injection frameworks
       inlineSourceMap: true,         // Consistent debugging experience
     };
   }