2.7.1

changelog.md

@@ -1,5 +1,99 @@
 # Changelog
 
+## 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.
+
+- Add robust tsconfig.json reading with graceful fallback when no tsconfig is present or it is invalid
+- Merge compiler options in a clear priority order (defaults -> tsconfig -> protected defaults -> programmatic -> CLI flags)
+- Introduce protected (critical) compiler options that cannot be overridden by tsconfig.json: outDir, noEmitOnError, declaration, emitDecoratorMetadata, inlineSourceMap
+- Convert string values from tsconfig (target, module, moduleResolution) to TypeScript enum values where applicable; special-case NodeNext
+- Transform tsconfig path mappings by replacing './ts_' with './dist_ts_' to keep runtime path resolution consistent with compiled output
+- Expose getCriticalDefaults helper and adjust mergeCompilerOptions to apply protected defaults before programmatic and CLI overrides
+- Update README with documentation for tsconfig support, merge order, protected compiler options, and example tsconfig
+- Bump dependencies/devDependencies: @push.rocks/smartcli ^4.0.19, @push.rocks/smartlog ^3.1.10, typescript 5.9.3, @git.zone/tsrun ^1.6.2, @git.zone/tstest ^2.7.0
+
+## 2025-08-29 - 2.6.8 - fix(tsbuild)
+Avoid process.exit in library, add confirmskiplibcheck flag, improve CLI exit handling and JSON/quiet modes, update test script
+
+- Changed package.json test script from "tsrun test/test.ts --verbose" to "tstest test/test.ts --verbose".
+- Library no longer calls process.exit from compile and compileWithErrorTracking; errors are returned or thrown so callers can decide process termination.
+- skipLibCheck behavior updated: delay/warning only happens when --confirmskiplibcheck is present; otherwise a short informational note is printed (suppressed in --quiet/--json).
+- CLI now awaits compileGlobStringObject calls and inspects a final error summary attached to argv to decide process.exit(1) when errors occurred.
+- compileGlobStringObject/exports now respect --quiet and --json modes, emit a JSON summary when --json is used, and attach the final error summary to argv so the CLI can determine exit behavior.
+
+## 2025-08-18 - 2.6.7 - fix(tspublish)
+Bump @git.zone/tspublish dependency to ^1.10.3
+
+- Updated dependency @git.zone/tspublish from ^1.10.2 to ^1.10.3 in package.json
+
+## 2025-08-18 - 2.6.6 - fix(dependencies)
+Update dependency @git.zone/tspublish to ^1.10.2
+
+- Bumped @git.zone/tspublish in package.json from ^1.10.1 to ^1.10.2
+
+## 2025-08-18 - 2.6.5 - fix(dependencies)
+Bump dependencies and add pnpm-workspace configuration
+
+- Updated @git.zone/tspublish from ^1.9.1 to ^1.10.1
+- Updated @push.rocks/smartfile from ^11.2.4 to ^11.2.7
+- Updated @push.rocks/smartpath from ^5.0.18 to ^6.0.0
+- Updated typescript from 5.8.3 to 5.9.2
+- Updated devDependency @git.zone/tstest from ^1.10.1 to ^2.3.4
+- Added pnpm-workspace.yaml with onlyBuiltDependencies list (esbuild, mongodb-memory-server, puppeteer)
+
+## 2025-05-24 - 2.6.4 - fix(dependencies)
+Add .npmrc and update dependency versions for smartfile and tstest
+
+- Add .npmrc with registry configuration for npm
+- Bump @push.rocks/smartfile version from ^11.2.3 to ^11.2.4
+- Bump @git.zone/tstest version from ^1.9.0 to ^1.10.1
+
+## 2025-05-21 - 2.6.3 - fix(tsbuild)
+minor maintenance updates and documentation improvements
+
+- Updated commit metadata to align with project version
+- Refined CLI command parsing and diagnostics logging for better clarity
+- Improved code readability in compiler options merging
+
+## 2025-05-21 - 2.6.2 - fix(npm configuration)
+Remove .npmrc file to default npm registry behavior
+
+- Deleted .npmrc file that hard-coded the npm registry URL to https://registry.npmjs.org/
+- This change leverages npm's default registry settings and reduces configuration clutter
+
+## 2025-05-21 - 2.6.1 - fix(tsbuild.classes)
+Improve error diagnostics handling by removing legacy helper and integrating more robust error summaries in the compilation process
+
+- Removed the handleDiagnostics method and its legacy usage
+- Replaced legacy calls with inline processDiagnostics checks for pre-emit and emit phases
+- Combined error summaries for clearer reporting during emit checks and type validation
+- Enhanced error output to guide users on resolving TypeScript errors before emission
+
+## 2025-05-21 - 2.6.0 - feat(tsbuild)
+Improve task logging and update dependencies
+
+- Add .npmrc file with npm registry configuration
+- Update test script to use '--verbose' flag
+- Bump dependency versions for @push.rocks packages and TypeScript
+- Enhance TsBuild logging by incorporating task info (e.g. task number, total tasks, output folder, and compile durations)
+- Propagate task info in compileFileArrayWithErrorTracking for better task tracking
+
+## 2025-05-21 - 2.5.2 - fix(tsbuild)
+Improve diagnostic error handling and summary reporting for TypeScript compilation by refactoring diagnostic processing and adding pre-emit error checks.
+
+- Introduce a dedicated processDiagnostics function that categorizes errors by file and computes error totals.
+- Refactor displayErrorSummary to provide clearer, color-coded output of error details.
+- Add pre-emit error checking in compileWithErrorTracking to prevent emission when errors exist.
+- Consolidate error summary merging in compileFileArrayWithErrorTracking for improved reporting.
+
 ## 2025-05-15 - 2.5.1 - fix(commitinfo)
 Update commit information and metadata to synchronize release data
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git.zone/tsbuild",
-  "version": "2.5.1",
+  "version": "2.7.1",
   "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",
@@ -10,7 +10,7 @@
     "tsbuild": "./cli.js"
   },
   "scripts": {
-    "test": "tsrun test/test.ts",
+    "test": "tstest test/test.ts --verbose",
     "build": "node cli.ts.js --web",
     "buildDocs": "tsdoc"
   },
@@ -36,20 +36,20 @@
   },
   "homepage": "https://code.foss.global/git.zone/tsbuild#README",
   "dependencies": {
-    "@git.zone/tspublish": "^1.9.1",
+    "@git.zone/tspublish": "^1.10.3",
     "@push.rocks/early": "^4.0.4",
-    "@push.rocks/smartcli": "^4.0.11",
+    "@push.rocks/smartcli": "^4.0.19",
     "@push.rocks/smartdelay": "^3.0.5",
-    "@push.rocks/smartfile": "^11.1.5",
-    "@push.rocks/smartlog": "^3.0.7",
-    "@push.rocks/smartpath": "^5.0.18",
-    "@push.rocks/smartpromise": "^4.2.2",
-    "typescript": "5.7.3"
+    "@push.rocks/smartfile": "^11.2.7",
+    "@push.rocks/smartlog": "^3.1.10",
+    "@push.rocks/smartpath": "^6.0.0",
+    "@push.rocks/smartpromise": "^4.2.3",
+    "typescript": "5.9.3"
   },
   "devDependencies": {
-    "@git.zone/tsrun": "^1.2.47",
-    "@push.rocks/tapbundle": "^5.5.6",
-    "@types/node": "^22.12.0"
+    "@git.zone/tsrun": "^1.6.2",
+    "@git.zone/tstest": "^2.7.0",
+    "@types/node": "^22.15.21"
   },
   "files": [
     "ts/**/*",

pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+onlyBuiltDependencies:
+  - esbuild
+  - mongodb-memory-server
+  - puppeteer

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.

test/test.ts

@@ -1,4 +1,4 @@
-import { tap, expect, expectAsync } from '@push.rocks/tapbundle';
+import { tap, expect } from '@git.zone/tstest/tapbundle';
 
 import * as tsbuild from '../ts/index.js';
 

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/tsbuild',
-  version: '2.5.1',
+  version: '2.7.1',
   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

@@ -3,6 +3,16 @@ import * as plugins from './plugins.js';
 import * as paths from './paths.js';
 import type { CompilerOptions, ScriptTarget, ModuleKind } from './tsbuild.exports.js';
 
+/**
+ * Interface for error summary data
+ */
+export interface IErrorSummary {
+  errorsByFile: Record<string, plugins.typescript.Diagnostic[]>;
+  generalErrors: plugins.typescript.Diagnostic[];
+  totalErrors: number;
+  totalFiles: number;
+}
+
 /**
  * Default compiler options for TypeScript compilation
  */
@@ -31,6 +41,7 @@ export class TsBuild {
   private fileNames: string[] = [];
   private options: plugins.typescript.CompilerOptions;
   private argvArg?: any;
+  private taskInfo?: any;
 
   /**
    * Create a new TsBuild instance
@@ -38,10 +49,12 @@ export class TsBuild {
   constructor(
     fileNames: string[] = [], 
     customOptions: CompilerOptions = {}, 
-    argvArg?: any
+    argvArg?: any,
+    taskInfo?: any
   ) {
     this.fileNames = fileNames;
     this.argvArg = argvArg;
+    this.taskInfo = taskInfo;
     this.options = this.mergeCompilerOptions(customOptions, argvArg);
   }
 
@@ -49,19 +62,56 @@ export class TsBuild {
    * Helper function to read and process tsconfig.json
    */
   private getTsConfigOptions(): CompilerOptions {
-    const tsconfig = plugins.smartfile.fs.toObjectSync(plugins.path.join(paths.cwd, 'tsconfig.json'));
-    const returnObject: CompilerOptions = {};
-    
+    let tsconfig: any;
+
+    // Try to read tsconfig.json, but don't fail if it doesn't exist
+    try {
+      tsconfig = plugins.smartfile.fs.toObjectSync(plugins.path.join(paths.cwd, 'tsconfig.json'));
+    } catch (error) {
+      // tsconfig.json doesn't exist or is invalid - use defaults
+      return {};
+    }
+
     if (!tsconfig || !tsconfig.compilerOptions) {
-      return returnObject;
+      return {};
     }
-    
-    // Process baseUrl
-    if (tsconfig.compilerOptions.baseUrl) {
-      returnObject.baseUrl = tsconfig.compilerOptions.baseUrl;
+
+    // Start by copying ALL compiler options from tsconfig.json
+    const returnObject: CompilerOptions = { ...tsconfig.compilerOptions };
+
+    // Apply special transformations for string-to-enum conversions
+
+    // Process target (convert string to enum)
+    if (tsconfig.compilerOptions.target && typeof tsconfig.compilerOptions.target === 'string') {
+      const targetKey = tsconfig.compilerOptions.target.toUpperCase();
+      if (targetKey in plugins.typescript.ScriptTarget) {
+        returnObject.target = plugins.typescript.ScriptTarget[targetKey as keyof typeof plugins.typescript.ScriptTarget];
+      }
     }
-    
-    // Process paths
+
+    // Process module (convert string to enum)
+    if (tsconfig.compilerOptions.module && typeof tsconfig.compilerOptions.module === 'string') {
+      const moduleKey = tsconfig.compilerOptions.module.toUpperCase();
+      if (moduleKey in plugins.typescript.ModuleKind) {
+        returnObject.module = plugins.typescript.ModuleKind[moduleKey as keyof typeof plugins.typescript.ModuleKind];
+      } else if (moduleKey === 'NODENEXT') {
+        returnObject.module = plugins.typescript.ModuleKind.NodeNext;
+      }
+    }
+
+    // Process moduleResolution (convert string to enum)
+    if (tsconfig.compilerOptions.moduleResolution && typeof tsconfig.compilerOptions.moduleResolution === 'string') {
+      const moduleResolutionKey = tsconfig.compilerOptions.moduleResolution.toUpperCase();
+      if (moduleResolutionKey in plugins.typescript.ModuleResolutionKind) {
+        returnObject.moduleResolution = plugins.typescript.ModuleResolutionKind[
+          moduleResolutionKey as keyof typeof plugins.typescript.ModuleResolutionKind
+        ];
+      } else if (moduleResolutionKey === 'NODENEXT') {
+        returnObject.moduleResolution = plugins.typescript.ModuleResolutionKind.NodeNext;
+      }
+    }
+
+    // Apply path transformations (ts_ → dist_ts_)
     if (tsconfig.compilerOptions.paths) {
       returnObject.paths = { ...tsconfig.compilerOptions.paths };
       for (const path of Object.keys(returnObject.paths)) {
@@ -70,58 +120,24 @@ export class TsBuild {
         }
       }
     }
-    
-    // Process target
-    if (tsconfig.compilerOptions.target) {
-      if (typeof tsconfig.compilerOptions.target === 'string') {
-        const targetKey = tsconfig.compilerOptions.target.toUpperCase();
-        if (targetKey in plugins.typescript.ScriptTarget) {
-          returnObject.target = plugins.typescript.ScriptTarget[targetKey as keyof typeof plugins.typescript.ScriptTarget];
-        }
-      }
-    }
-    
-    // Process module
-    if (tsconfig.compilerOptions.module) {
-      if (typeof tsconfig.compilerOptions.module === 'string') {
-        const moduleKey = tsconfig.compilerOptions.module.toUpperCase();
-        if (moduleKey in plugins.typescript.ModuleKind) {
-          returnObject.module = plugins.typescript.ModuleKind[moduleKey as keyof typeof plugins.typescript.ModuleKind];
-        } else if (moduleKey === 'NODENEXT') {
-          returnObject.module = plugins.typescript.ModuleKind.NodeNext;
-        }
-      }
-    }
-    
-    // Process moduleResolution
-    if (tsconfig.compilerOptions.moduleResolution) {
-      if (typeof tsconfig.compilerOptions.moduleResolution === 'string') {
-        const moduleResolutionKey = tsconfig.compilerOptions.moduleResolution.toUpperCase();
-        if (moduleResolutionKey in plugins.typescript.ModuleResolutionKind) {
-          returnObject.moduleResolution = plugins.typescript.ModuleResolutionKind[
-            moduleResolutionKey as keyof typeof plugins.typescript.ModuleResolutionKind
-          ];
-        } else if (moduleResolutionKey === 'NODENEXT') {
-          returnObject.moduleResolution = plugins.typescript.ModuleResolutionKind.NodeNext;
-        }
-      }
-    }
-    
-    // Copy boolean options directly
-    const booleanOptions = [
-      'experimentalDecorators', 'useDefineForClassFields', 
-      'esModuleInterop', 'verbatimModuleSyntax'
-    ];
-    
-    for (const option of booleanOptions) {
-      if (option in tsconfig.compilerOptions) {
-        (returnObject as any)[option] = (tsconfig.compilerOptions as any)[option];
-      }
-    }
-    
+
     return returnObject;
   }
 
+  /**
+   * Returns critical default options that should not be overridden by tsconfig.json
+   * These options are essential for tsbuild's functionality and build integrity
+   */
+  private getCriticalDefaults(): CompilerOptions {
+    return {
+      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
+    };
+  }
+
   /**
    * Process command line arguments and return applicable compiler options
    */
@@ -149,6 +165,13 @@ export class TsBuild {
 
   /**
    * Merges compilerOptions with the default compiler options
+   *
+   * Merge order (later overwrites earlier):
+   * 1. compilerOptionsDefault - Base defaults for all options
+   * 2. getTsConfigOptions() - User's tsconfig.json (all options)
+   * 3. getCriticalDefaults() - Protected options that shouldn't be overridden by tsconfig.json
+   * 4. customTsOptions - Programmatic options (can override critical defaults)
+   * 5. getCommandLineOptions() - CLI flags (highest priority)
    */
   public mergeCompilerOptions(
     customTsOptions: CompilerOptions = {},
@@ -156,24 +179,20 @@ export class TsBuild {
   ): CompilerOptions {
     // create merged options
     const mergedOptions: CompilerOptions = {
-      ...compilerOptionsDefault,
-      ...customTsOptions,
-      ...this.getCommandLineOptions(argvArg),
-      ...this.getTsConfigOptions(),
+      ...compilerOptionsDefault,           // 1. All defaults
+      ...this.getTsConfigOptions(),        // 2. User's tsconfig.json (all options)
+      ...this.getCriticalDefaults(),       // 3. Protected overrides
+      ...customTsOptions,                  // 4. Programmatic options
+      ...this.getCommandLineOptions(argvArg), // 5. CLI flags (highest priority)
     };
 
     return mergedOptions;
   }
 
   /**
-   * Helper function to handle and log TypeScript diagnostics
+   * Helper function to process TypeScript diagnostics and return error summary
    */
-  private handleDiagnostics(diagnostics: readonly plugins.typescript.Diagnostic[]): boolean {
-    if (diagnostics.length === 0) {
-      return false;
-    }
-    
-    // Group errors by file for better readability
+  private processDiagnostics(diagnostics: readonly plugins.typescript.Diagnostic[]): IErrorSummary {
     const errorsByFile: Record<string, plugins.typescript.Diagnostic[]> = {};
     const generalErrors: plugins.typescript.Diagnostic[] = [];
     
@@ -190,12 +209,27 @@ export class TsBuild {
       }
     });
     
-    // Print error summary header
-    const totalErrorCount = diagnostics.length;
-    const fileCount = Object.keys(errorsByFile).length;
+    return {
+      errorsByFile,
+      generalErrors,
+      totalErrors: diagnostics.length,
+      totalFiles: Object.keys(errorsByFile).length
+    };
+  }
+
+  /**
+   * Helper function to display error summary
+   */
+  private displayErrorSummary(errorSummary: IErrorSummary): void {
+    if (errorSummary.totalErrors === 0) {
+      return;
+    }
     
+    const { errorsByFile, generalErrors, totalErrors, totalFiles } = errorSummary;
+    
+    // Print error summary header
     console.log('\n' + '='.repeat(80));
-    console.log(`❌ Found ${totalErrorCount} error${totalErrorCount !== 1 ? 's' : ''} in ${fileCount} file${fileCount !== 1 ? 's' : ''}:`);
+    console.log(`❌ Found ${totalErrors} error${totalErrors !== 1 ? 's' : ''} in ${totalFiles} file${totalFiles !== 1 ? 's' : ''}:`);
     console.log('='.repeat(80));
     
     // Color codes for error formatting
@@ -255,10 +289,9 @@ export class TsBuild {
     }
     
     console.log('\n' + '='.repeat(80) + '\n');
-    
-    return diagnostics.length > 0;
   }
 
+
   /**
    * Creates a TypeScript program from file names and options
    */
@@ -282,15 +315,114 @@ export class TsBuild {
     this.options = { ...this.options, ...options };
   }
 
+  /**
+   * The main compiler function that compiles the files and returns error summary
+   */
+  public async compileWithErrorTracking(): Promise<{ emittedFiles: any[], errorSummary: IErrorSummary }> {
+    if (this.options.skipLibCheck) {
+      if (this.argvArg?.confirmskiplibcheck) {
+        console.log('\n⚠️  WARNING ⚠️');
+        console.log('You are skipping libcheck... Is that really wanted?');
+        console.log('Continuing in 5 seconds...\n');
+        await plugins.smartdelay.delayFor(5000);
+      } else {
+        // No delay by default; keep a short note unless in quiet/json modes
+        if (!this.argvArg?.quiet && !this.argvArg?.json) {
+          console.log('⚠️  skipLibCheck enabled; use --confirmskiplibcheck to pause with warning.');
+        }
+      }
+    }
+    
+    // Enhanced logging with task info
+    const startTime = Date.now();
+    if (this.taskInfo) {
+      const { taskNumber, totalTasks, sourcePattern, destDir, fileCount } = this.taskInfo;
+      const relativeDestDir = destDir.replace(process.cwd(), '').replace(/^\//, '');
+      console.log(`\n🔨 [${taskNumber}/${totalTasks}] Compiling ${fileCount} file${fileCount !== 1 ? 's' : ''} from ${sourcePattern}`);
+      console.log(`   📁 Output: ${relativeDestDir}`);
+    } else {
+      console.log(`🔨 Compiling ${this.fileNames.length} files...`);
+    }
+    
+    const done = plugins.smartpromise.defer<{ emittedFiles: any[], errorSummary: IErrorSummary }>();
+    const program = this.createProgram();
+    
+    // Check for pre-emit diagnostics first
+    const preEmitDiagnostics = plugins.typescript.getPreEmitDiagnostics(program);
+    const preEmitErrorSummary = this.processDiagnostics(preEmitDiagnostics);
+    
+    // Only continue to emit phase if no pre-emit errors
+    if (preEmitErrorSummary.totalErrors > 0) {
+      this.displayErrorSummary(preEmitErrorSummary);
+      console.error('\n❌ TypeScript pre-emit checks failed. Please fix the issues listed above before proceeding.');
+      console.error('   Type errors must be resolved before the compiler can emit output files.\n');
+      // Return error summary instead of exiting to allow final summary display
+      done.resolve({ emittedFiles: [], errorSummary: preEmitErrorSummary });
+      return done.promise;
+    }
+    
+    // If no pre-emit errors, proceed with emit
+    const emitResult = program.emit();
+    const emitErrorSummary = this.processDiagnostics(emitResult.diagnostics);
+    
+    // Combine error summaries
+    const combinedErrorSummary: IErrorSummary = {
+      errorsByFile: { ...preEmitErrorSummary.errorsByFile, ...emitErrorSummary.errorsByFile },
+      generalErrors: [...preEmitErrorSummary.generalErrors, ...emitErrorSummary.generalErrors],
+      totalErrors: preEmitErrorSummary.totalErrors + emitErrorSummary.totalErrors,
+      totalFiles: Object.keys({ ...preEmitErrorSummary.errorsByFile, ...emitErrorSummary.errorsByFile }).length
+    };
+
+    const exitCode = emitResult.emitSkipped ? 1 : 0;
+    if (exitCode === 0) {
+      const endTime = Date.now();
+      const duration = endTime - startTime;
+      
+      if (this.taskInfo) {
+        const { taskNumber, totalTasks } = this.taskInfo;
+        console.log(`✅ [${taskNumber}/${totalTasks}] Task completed in ${duration}ms`);
+      } else {
+        console.log(`✅ TypeScript emit succeeded! (${duration}ms)`);
+      }
+      
+      // Get count of emitted files by type
+      const jsFiles = emitResult.emittedFiles?.filter(f => f.endsWith('.js')).length || 0;
+      const dtsFiles = emitResult.emittedFiles?.filter(f => f.endsWith('.d.ts')).length || 0;
+      const mapFiles = emitResult.emittedFiles?.filter(f => f.endsWith('.map')).length || 0;
+      
+      // If we have emitted files, show a summary
+      if (emitResult.emittedFiles && emitResult.emittedFiles.length > 0) {
+        console.log(`   📄 Generated ${emitResult.emittedFiles.length} files: ${jsFiles} .js, ${dtsFiles} .d.ts, ${mapFiles} source maps`);
+      }
+      
+      done.resolve({ emittedFiles: emitResult.emittedFiles || [], errorSummary: combinedErrorSummary });
+    } else {
+      this.displayErrorSummary(combinedErrorSummary);
+      console.error('\n❌ TypeScript emit failed. Please investigate the errors listed above!');
+      console.error('   No output files have been generated.\n');
+      // Do not exit here; return error summary so caller can decide
+      done.resolve({ emittedFiles: [], errorSummary: combinedErrorSummary });
+      return done.promise;
+    }
+
+    return done.promise;
+  }
+
   /**
    * The main compiler function that compiles the files
    */
   public async compile(): Promise<any[]> {
     if (this.options.skipLibCheck) {
-      console.log('\n⚠️  WARNING ⚠️');
-      console.log('You are skipping libcheck... Is that really wanted?');
-      console.log('Continuing in 5 seconds...\n');
-      await plugins.smartdelay.delayFor(5000);
+      if (this.argvArg?.confirmskiplibcheck) {
+        console.log('\n⚠️  WARNING ⚠️');
+        console.log('You are skipping libcheck... Is that really wanted?');
+        console.log('Continuing in 5 seconds...\n');
+        await plugins.smartdelay.delayFor(5000);
+      } else {
+        if (!this.argvArg?.quiet && !this.argvArg?.json) {
+          console.log('⚠️  skipLibCheck enabled; use --confirmskiplibcheck to pause with warning.');
+        }
+      }
     }
     
     console.log(`🔨 Compiling ${this.fileNames.length} files...`);
@@ -299,18 +431,20 @@ export class TsBuild {
     
     // Check for pre-emit diagnostics first
     const preEmitDiagnostics = plugins.typescript.getPreEmitDiagnostics(program);
-    const hasPreEmitErrors = this.handleDiagnostics(preEmitDiagnostics);
+    const preEmitErrorSummary = this.processDiagnostics(preEmitDiagnostics);
     
     // Only continue to emit phase if no pre-emit errors
-    if (hasPreEmitErrors) {
+    if (preEmitErrorSummary.totalErrors > 0) {
+      this.displayErrorSummary(preEmitErrorSummary);
       console.error('\n❌ TypeScript pre-emit checks failed. Please fix the issues listed above before proceeding.');
       console.error('   Type errors must be resolved before the compiler can emit output files.\n');
-      process.exit(1);
+      // Throw instead of exiting to keep library pure
+      throw new Error('TypeScript pre-emit checks failed.');
     }
     
     // If no pre-emit errors, proceed with emit
     const emitResult = program.emit();
-    const hasEmitErrors = this.handleDiagnostics(emitResult.diagnostics);
+    const emitErrorSummary = this.processDiagnostics(emitResult.diagnostics);
 
     const exitCode = emitResult.emitSkipped ? 1 : 0;
     if (exitCode === 0) {
@@ -328,9 +462,11 @@ export class TsBuild {
       
       done.resolve(emitResult.emittedFiles);
     } else {
+      this.displayErrorSummary(emitErrorSummary);
       console.error('\n❌ TypeScript emit failed. Please investigate the errors listed above!');
       console.error('   No output files have been generated.\n');
-      process.exit(exitCode);
+      // Throw instead of exiting to keep library pure
+      throw new Error('TypeScript emit failed.');
     }
 
     return done.promise;
@@ -351,18 +487,27 @@ export class TsBuild {
     
     // Check for pre-emit diagnostics
     const preEmitDiagnostics = plugins.typescript.getPreEmitDiagnostics(program);
-    const hasPreEmitErrors = this.handleDiagnostics(preEmitDiagnostics);
+    const preEmitErrorSummary = this.processDiagnostics(preEmitDiagnostics);
     
     // Run the emit phase but with noEmit: true to check for emit errors without producing files
     const emitResult = program.emit(undefined, undefined, undefined, true);
-    const hasEmitErrors = this.handleDiagnostics(emitResult.diagnostics);
+    const emitErrorSummary = this.processDiagnostics(emitResult.diagnostics);
     
-    const success = !hasPreEmitErrors && !hasEmitErrors && !emitResult.emitSkipped;
+    // Combine error summaries
+    const combinedErrorSummary: IErrorSummary = {
+      errorsByFile: { ...preEmitErrorSummary.errorsByFile, ...emitErrorSummary.errorsByFile },
+      generalErrors: [...preEmitErrorSummary.generalErrors, ...emitErrorSummary.generalErrors],
+      totalErrors: preEmitErrorSummary.totalErrors + emitErrorSummary.totalErrors,
+      totalFiles: Object.keys({ ...preEmitErrorSummary.errorsByFile, ...emitErrorSummary.errorsByFile }).length
+    };
+    
+    const success = combinedErrorSummary.totalErrors === 0 && !emitResult.emitSkipped;
     
     if (success) {
       console.log('\n✅ TypeScript emit check passed! All files can be emitted successfully.');
       console.log(`   ${fileCount} file${fileCount !== 1 ? 's' : ''} ${fileCount !== 1 ? 'are' : 'is'} ready to be compiled.\n`);
     } else {
+      this.displayErrorSummary(combinedErrorSummary);
       console.error('\n❌ TypeScript emit check failed. Please fix the issues listed above.');
       console.error('   The compilation cannot proceed until these errors are resolved.\n');
     }
@@ -385,15 +530,16 @@ export class TsBuild {
     
     // Check for type errors
     const diagnostics = plugins.typescript.getPreEmitDiagnostics(program);
-    const hasErrors = this.handleDiagnostics(diagnostics);
+    const errorSummary = this.processDiagnostics(diagnostics);
     
     // Set success flag
-    const success = !hasErrors;
+    const success = errorSummary.totalErrors === 0;
     
     if (success) {
       console.log('\n✅ TypeScript type check passed! No type errors found.');
       console.log(`   All ${fileCount} file${fileCount !== 1 ? 's' : ''} passed type checking successfully.\n`);
     } else {
+      this.displayErrorSummary(errorSummary);
       console.error('\n❌ TypeScript type check failed. Please fix the type errors listed above.');
       console.error('   The type checker found issues that need to be resolved.\n');
     }
@@ -447,4 +593,4 @@ export const checkTypes = async (
 ): Promise<boolean> => {
   const tsBuild = new TsBuild(fileNames, options, argvArg);
   return tsBuild.checkTypes();
-};
+};

ts/tsbuild.cli.ts

@@ -9,7 +9,7 @@ export const runCli = async () => {
    * the standard task compiles anything in ts/ directory to dist directory
    */
   tsbuildCli.standardCommand().subscribe(async (argvArg) => {
-    tsbuild.compileGlobStringObject(
+    await tsbuild.compileGlobStringObject(
       {
         './ts/**/*.ts': './dist_ts',
       },
@@ -17,6 +17,10 @@ export const runCli = async () => {
       process.cwd(),
       argvArg
     );
+    const summary = (argvArg as any)?.__tsbuildFinalErrorSummary;
+    if (summary && summary.totalErrors > 0) {
+      process.exit(1);
+    }
   });
 
   /**
@@ -30,6 +34,10 @@ export const runCli = async () => {
       compilationCommandObject[`./${directory}/**/*.ts`] = `./dist_${directory}`;
     }
     await tsbuild.compileGlobStringObject(compilationCommandObject, {}, process.cwd(), argvArg);
+    const summary = (argvArg as any)?.__tsbuildFinalErrorSummary;
+    if (summary && summary.totalErrors > 0) {
+      process.exit(1);
+    }
   });
 
   /**
@@ -182,6 +190,10 @@ export const runCli = async () => {
       compilationCommandObject[`./${tsFolder}/**/*.ts`] = `./dist_${tsFolder}`;
     }
     await tsbuild.compileGlobStringObject(compilationCommandObject, {}, process.cwd(), argvArg);
+    const summary = (argvArg as any)?.__tsbuildFinalErrorSummary;
+    if (summary && summary.totalErrors > 0) {
+      process.exit(1);
+    }
   });
   
   /**

ts/tsbuild.exports.ts

@@ -6,6 +6,31 @@ export type { CompilerOptions, ScriptTarget, ModuleKind };
 
 export * from './tsbuild.classes.tsbuild.js';
 
+/**
+ * Interface for task information
+ */
+export interface ITaskInfo {
+  taskNumber: number;
+  totalTasks: number;
+  sourcePattern: string;
+  destDir: string;
+  fileCount: number;
+}
+
+/**
+ * compile an array of absolute file paths with error tracking
+ */
+export let compileFileArrayWithErrorTracking = async (
+  fileStringArrayArg: string[],
+  compilerOptionsArg: CompilerOptions = {},
+  argvArg?: any,
+  taskInfo?: ITaskInfo
+): Promise<{ emittedFiles: any[], errorSummary: import('./tsbuild.classes.tsbuild.js').IErrorSummary }> => {
+  const { TsBuild } = await import('./tsbuild.classes.tsbuild.js');
+  const tsBuild = new TsBuild(fileStringArrayArg, compilerOptionsArg, argvArg, taskInfo);
+  return tsBuild.compileWithErrorTracking();
+};
+
 /**
  * compile am array of absolute file paths
  */
@@ -17,6 +42,75 @@ export let compileFileArray = (
   return compiler(fileStringArrayArg, mergeCompilerOptions(compilerOptionsArg, argvArg), argvArg);
 };
 
+/**
+ * Helper function to merge error summaries
+ */
+function mergeErrorSummaries(summaries: import('./tsbuild.classes.tsbuild.js').IErrorSummary[]): import('./tsbuild.classes.tsbuild.js').IErrorSummary {
+  const mergedErrorsByFile: Record<string, plugins.typescript.Diagnostic[]> = {};
+  const mergedGeneralErrors: plugins.typescript.Diagnostic[] = [];
+  let totalErrors = 0;
+  
+  summaries.forEach(summary => {
+    // Merge errors by file
+    Object.entries(summary.errorsByFile).forEach(([fileName, errors]) => {
+      if (!mergedErrorsByFile[fileName]) {
+        mergedErrorsByFile[fileName] = [];
+      }
+      mergedErrorsByFile[fileName] = mergedErrorsByFile[fileName].concat(errors);
+    });
+    
+    // Merge general errors
+    mergedGeneralErrors.push(...summary.generalErrors);
+    totalErrors += summary.totalErrors;
+  });
+  
+  return {
+    errorsByFile: mergedErrorsByFile,
+    generalErrors: mergedGeneralErrors,
+    totalErrors,
+    totalFiles: Object.keys(mergedErrorsByFile).length
+  };
+}
+
+/**
+ * Helper function to display final compilation summary
+ */
+function displayFinalErrorSummary(errorSummary: import('./tsbuild.classes.tsbuild.js').IErrorSummary): void {
+  if (errorSummary.totalErrors === 0) {
+    console.log('\n📊 \x1b[32mCompilation Summary: All tasks completed successfully! ✅\x1b[0m\n');
+    return;
+  }
+  
+  const colors = {
+    reset: '\x1b[0m',
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    cyan: '\x1b[36m',
+    brightRed: '\x1b[91m',
+    brightYellow: '\x1b[93m'
+  };
+  
+  console.log('\n' + '='.repeat(80));
+  console.log(`📊 ${colors.brightYellow}Final Compilation Summary${colors.reset}`);
+  console.log('='.repeat(80));
+  
+  if (errorSummary.totalFiles > 0) {
+    console.log(`${colors.brightRed}❌ Files with errors (${errorSummary.totalFiles}):${colors.reset}`);
+    
+    Object.entries(errorSummary.errorsByFile).forEach(([fileName, errors]) => {
+      const displayPath = fileName.replace(process.cwd(), '').replace(/^\//, '');
+      console.log(`  ${colors.red}•${colors.reset} ${colors.cyan}${displayPath}${colors.reset} ${colors.yellow}(${errors.length} error${errors.length !== 1 ? 's' : ''})${colors.reset}`);
+    });
+  }
+  
+  if (errorSummary.generalErrors.length > 0) {
+    console.log(`${colors.brightRed}❌ General errors: ${errorSummary.generalErrors.length}${colors.reset}`);
+  }
+  
+  console.log(`\n${colors.brightRed}Total: ${errorSummary.totalErrors} error${errorSummary.totalErrors !== 1 ? 's' : ''} across ${errorSummary.totalFiles} file${errorSummary.totalFiles !== 1 ? 's' : ''}${colors.reset}`);
+  console.log('='.repeat(80) + '\n');
+}
+
 /**
  * compile advanced glob configurations
  * @param globStringArrayArg a array of glob strings
@@ -31,13 +125,21 @@ export let compileGlobStringObject = async (
   argvArg?: any
 ) => {
   let compiledFiles: any[] = [];
+  const errorSummaries: import('./tsbuild.classes.tsbuild.js').IErrorSummary[] = [];
   
-  // Log the compilation tasks in a nice format
-  console.log('\n👷 TypeScript Compilation Tasks:');
-  Object.entries(globStringObjectArg).forEach(([source, dest]) => {
-    console.log(`  📂 ${source} → ${dest}`);
-  });
-  console.log('');
+  const totalTasks = Object.keys(globStringObjectArg).length;
+  let currentTask = 0;
+  
+  // Log the compilation tasks in a nice format (skip for --quiet or --json)
+  const isQuiet = argvArg?.quiet === true;
+  const isJson = argvArg?.json === true;
+  if (!isQuiet && !isJson) {
+    console.log(`\n👷 TypeScript Compilation Tasks (${totalTasks} task${totalTasks !== 1 ? 's' : ''}):`);
+    Object.entries(globStringObjectArg).forEach(([source, dest]) => {
+      console.log(`  📂 ${source} → ${dest}`);
+    });
+    console.log('');
+  }
   
   for (const keyArg in globStringObjectArg) {
     // Type safety check for key
@@ -69,12 +171,53 @@ export let compileGlobStringObject = async (
         outDir: destDir,
       };
       
-      // Compile the files and correctly concat the results
-      // Fixed: removed duplicating compiledFiles in the concat operation
-      const newlyCompiledFiles = await compileFileArray(absoluteFilePathArray, updatedTsOptions, argvArg);
-      compiledFiles = compiledFiles.concat(newlyCompiledFiles);
+      // Compile with error tracking
+      currentTask++;
+      const taskInfo = {
+        taskNumber: currentTask,
+        totalTasks,
+        sourcePattern: keyArg,
+        destDir: globStringObjectArg[keyArg],
+        fileCount: absoluteFilePathArray.length
+      };
+      
+      const result = await compileFileArrayWithErrorTracking(absoluteFilePathArray, updatedTsOptions, argvArg, taskInfo);
+      compiledFiles = compiledFiles.concat(result.emittedFiles);
+      errorSummaries.push(result.errorSummary);
     }
   }
   
+  // Display final error summary after all compilation tasks
+  const finalErrorSummary = mergeErrorSummaries(errorSummaries);
+
+  // Output summary based on mode
+  if (isJson) {
+    const result = {
+      success: finalErrorSummary.totalErrors === 0,
+      totals: {
+        errors: finalErrorSummary.totalErrors,
+        filesWithErrors: finalErrorSummary.totalFiles,
+        tasks: totalTasks,
+      },
+      errorsByFile: Object.fromEntries(
+        Object.entries(finalErrorSummary.errorsByFile).map(([file, diags]) => [
+          file,
+          diags.map(d => ({
+            code: d.code,
+            message: plugins.typescript.flattenDiagnosticMessageText(d.messageText as any, '\n'),
+          }))
+        ])
+      ),
+    };
+    console.log(JSON.stringify(result));
+  } else if (!isQuiet) {
+    displayFinalErrorSummary(finalErrorSummary);
+  }
+
+  // Attach summary to argvArg so CLI can decide exit behavior
+  if (argvArg && typeof argvArg === 'object') {
+    (argvArg as any).__tsbuildFinalErrorSummary = finalErrorSummary;
+  }
+
   return compiledFiles;
-};
+};