# @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.