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. FsHelpers - Filesystem utilities (static methods)
6. 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

  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_compiler/
    index.ts                    # exports
    classes.tscompiler.ts       # TsCompiler + legacy compatibility functions

  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

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

FsHelpers (mod_fs/classes.fshelpers.ts)

• listFilesWithGlob() - Glob pattern file listing
• 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.10.3 - Module ordering
• @push.rocks/smartcli@^4.0.19 - CLI framework
• @push.rocks/smartfile@^13.1.2 - File content handling
• @push.rocks/smartfs@^1.2.0 - Filesystem operations
• @push.rocks/smartpath@^6.0.0 - Path transformation utilities
• @push.rocks/smartpromise@^4.2.3 - Promise utilities
• @push.rocks/smartdelay@^3.0.5 - Delay utilities
• typescript@5.9.3 - 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

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

Implementation

• TsUnpacker class in mod_unpack/classes.tsunpacker.ts
• Called automatically after each successful compilation in TsCompiler.compileGlob()

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)

Recent Changes

• 3.1.4+ - Major restructuring with mod_* modules
• Full OO architecture with TsCompiler, TsConfig, TsPublishConfig, TsUnpacker, TsBuildCli, FsHelpers
• Backward compatibility maintained for legacy functions
• Automatic "unpack" feature for nested output directories
• Migrated filesystem operations from smartfile to smartfs