BREAKING(structure): modernize internal structure and support unpacking

2025-12-13 22:59:58 +00:00
parent 4ebc37fa5a
commit e5fcbb9a09
19 changed files with 1605 additions and 1318 deletions
--- a/readme.hints.md
+++ b/readme.hints.md
@@ -2,15 +2,13 @@

 ## 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
+### 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/
@@ -27,10 +25,71 @@
 - `--quiet` - Suppress non-error output
 - `--json` - JSON output format

-## Key Architecture Decisions
+## Architecture - Modular Structure

-### Configuration Priority (5 levels)
-1. Default options (hardcoded)
+### 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)
@@ -41,7 +100,6 @@ 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
@@ -51,12 +109,12 @@ Cannot be overridden by tsconfig.json alone:
 ## 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
+- verbatimModuleSyntax: true

 ## Error Handling

@@ -70,35 +128,59 @@ interface IErrorSummary {
 }
 ```

-### 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 }
-    ]
-  }
+### Compile Result Structure
+```typescript
+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
-2. Always: ts_shared second
+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)

@@ -107,48 +189,12 @@ 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@^4.0.19 - CLI framework
- @push.rocks/smartfile@^13.1.2 - File content handling (SmartFile, StreamFile, VirtualDirectory)
- @push.rocks/smartfs@^1.2.0 - Filesystem operations (file listing, directory listing, etc.)
- @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 Migration Notes
- smartfile v13+ split filesystem operations to a separate @push.rocks/smartfs package
- File listing uses smartfs fluent API: `smartfs.directory(path).recursive().filter(pattern).list()`
- File existence checks use: `smartfs.file(path).exists()`
- The `listFilesWithGlob()` helper in plugins.ts handles glob pattern parsing for smartfs
-
 ## 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
+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)
@@ -161,27 +207,9 @@ Plus: File counts, duration, and file type breakdown
 - Pre-emit checks before emit phase
 - CLI exit code handling (0=success, 1=error)

-## Recent Changes (from git log)
- 3.1.3 - Current version
+## 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
- Updated @git.zone/tsrun to ^2.0.1
- Updated @git.zone/tstest to ^3.1.3
- Updated @push.rocks/smartfile to ^13.1.2
- Added @push.rocks/smartfs@^1.2.0 for filesystem operations
- Updated @types/node to ^25.0.1
-
-## 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.