tsbuild/readme.hints.md

# @git.zone/tsbuild - Project Memory

## Quick Reference

### Public API - Classes
1. **TsCompiler** - Main compilation class with compileFiles, compileGlob, checkTypes, checkEmit methods
2. **TsConfig** - TypeScript configuration management (tsconfig.json handling)
3. **TsPublishConfig** - TsPublish configuration (tspublish.json handling)
4. **TsUnpacker** - Output directory flattening
5. **TsPathRewriter** - Cross-module import path rewriting in compiled output
6. **FsHelpers** - Filesystem utilities (static methods)
7. **TsBuildLogger** - Centralized structured console output (4-level hierarchy)
8. **TsBuildCli** - CLI command handler

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

## Architecture - Modular Structure

### Module Organization
```
ts/
  index.ts                      # Main entry, re-exports all modules
  plugins.ts                    # Dependency imports only
  00_commitinfo_data.ts         # Commit info data

  mod_fs/
    index.ts                    # exports
    classes.fshelpers.ts        # FsHelpers - static filesystem utilities

  mod_config/
    index.ts                    # exports
    classes.tsconfig.ts         # TsConfig - tsconfig.json handling
    classes.tspublishconfig.ts  # TsPublishConfig - tspublish.json handling

  mod_unpack/
    index.ts                    # exports
    classes.tsunpacker.ts       # TsUnpacker - output flattening

  mod_pathrewrite/
    index.ts                    # exports
    classes.tspathrewriter.ts   # TsPathRewriter - import path rewriting

  mod_logger/
    index.ts                    # exports
    classes.logger.ts           # TsBuildLogger - structured console output

  mod_compiler/
    index.ts                    # exports
    classes.tscompiler.ts       # TsCompiler - main compilation engine

  mod_cli/
    index.ts                    # exports
    classes.tsbuildcli.ts       # TsBuildCli - CLI command handler
```

### Class Responsibilities

**TsCompiler** (`mod_compiler/classes.tscompiler.ts`)
- Core compilation with `compileFiles()`, `compileGlob()`
- Type checking with `checkTypes()`, `checkEmit()`
- Configuration via TsConfig
- Automatic unpacking via TsUnpacker
- Import path rewriting via TsPathRewriter (in compileGlob)

**TsConfig** (`mod_config/classes.tsconfig.ts`)
- Load and parse tsconfig.json
- Merge configuration with priority order
- Protected defaults handling

**TsPublishConfig** (`mod_config/classes.tspublishconfig.ts`)
- Load and parse tspublish.json
- `shouldUnpack` property (default true)
- `order` property for tsfolders ordering

**TsUnpacker** (`mod_unpack/classes.tsunpacker.ts`)
- Detect nested output structure
- Flatten output directories
- Configurable via TsPublishConfig

**TsPathRewriter** (`mod_pathrewrite/classes.tspathrewriter.ts`)
- Auto-detect ts_* folders in project
- Rewrite ES module imports, dynamic imports, and require() calls
- Transforms `../ts_*` references to `../dist_ts_*` in compiled output

**TsBuildLogger** (`mod_logger/classes.logger.ts`)
- 4-level visual hierarchy: HEADER, STEP, DETAIL, SUCCESS/ERROR/WARN
- ANSI color output
- Static methods (no instantiation needed)

**FsHelpers** (`mod_fs/classes.fshelpers.ts`)
- `listFilesWithGlob()` - Glob pattern file listing via smartfs
- `extractSourceFolder()` - Pattern parsing
- File/directory existence checks
- Directory operations

**TsBuildCli** (`mod_cli/classes.tsbuildcli.ts`)
- All CLI commands registered
- Uses TsCompiler for compilation

## Configuration Priority (5 levels)
1. Default options (hardcoded in TsConfig)
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
- `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)
- Source Maps: Inline (no separate .map files)
- Declaration Files: ALWAYS generated (protected)
- Output: dist_ts/
- Implicit any: ALLOWED by default
- esModuleInterop: true
- verbatimModuleSyntax: true

## Error Handling

### Error Summary Structure
```typescript
interface IErrorSummary {
  errorsByFile: Record<string, Diagnostic[]>
  generalErrors: Diagnostic[]
  totalErrors: number
  totalFiles: number
}
```

### Compile Result Structure
```typescript
interface ICompileResult {
  emittedFiles: string[]
  errorSummary: IErrorSummary
}
```

## Dependencies Used
- @git.zone/tspublish@^1.11.3 - Module ordering
- @push.rocks/early@^4.0.4 - Early initialization
- @push.rocks/smartcli@^4.0.20 - CLI framework
- @push.rocks/smartdelay@^3.0.5 - Delay utilities
- @push.rocks/smartfile@^13.1.2 - File content handling
- @push.rocks/smartfs@^1.5.0 - Filesystem operations
- @push.rocks/smartlog@^3.2.1 - Logging
- @push.rocks/smartpath@^6.0.0 - Path transformation utilities
- @push.rocks/smartpromise@^4.2.3 - Promise utilities
- typescript@^6.0.2 - TypeScript compiler

### smartfs Usage
- File listing: `smartfs.directory(path).recursive().filter(pattern).list()`
- File existence: `smartfs.file(path).exists()`
- Directory existence: `smartfs.directory(path).exists()`
- FsHelpers wraps smartfs for glob pattern support

## Compilation Pipeline (compileGlob)

1. **Phase 1: Resolve & Clean** - Resolve glob patterns, list files, clear all output dirs
2. **Phase 2: Compile** - Compile each task sequentially with error tracking
3. **Phase 3: Unpack** - Flatten nested output directories for successful compilations
4. **Phase 4: Path Rewrite** - Rewrite cross-module import paths in output dirs

## Unpack Feature

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
```

The unpack feature automatically flattens this to:
```
dist_ts_core/
  index.js        <- flat
```

### Configuration
- Reads `tspublish.json` from source folder
- `unpack: true` (default if not present) -> flatten output
- `unpack: false` -> skip unpacking

## Special Behaviors

### tsfolders Command Ordering
1. Always: ts_interfaces first (if no tspublish.json)
2. Always: ts_shared second (if no tspublish.json)
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)

## Edge Cases

1. **Empty file list** - Returns [], no error
2. **Glob duplicates** - Files compile multiple times
3. **Non-existent files** - TypeScript "file not found" errors
4. **skipLibCheck warning** - 1-line default, 5s 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)
- Event loop yield after emit for XFS filesystem reliability