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

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

interface IErrorSummary {
  errorsByFile: Record<string, Diagnostic[]>
  generalErrors: Diagnostic[]
  totalErrors: number
  totalFiles: number
}

Compile Result Structure

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