tsbuild/readme.hints.md

@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 - Custom directory compilation
3. tsbuild tsfolders - Auto-discover ts_* folders, compile in order
4. tsbuild emitcheck - 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

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

{
  "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:

{
  "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.