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