@tsonic/tsbindgen 0.1.2 → 0.7.5

package/README.md

@@ -1,405 +1,198 @@
 # tsbindgen
 
-A .NET tool that generates TypeScript declaration files (`.d.ts`) from .NET assemblies for use with the Tsonic compiler.
+**TypeScript type declaration generator for .NET assemblies**
 
-## Overview
+tsbindgen generates TypeScript declaration files (`.d.ts`) from .NET assemblies using reflection. It creates fully-typed, IDE-friendly TypeScript definitions that map the entire .NET Base Class Library (BCL) to TypeScript.
 
-`tsbindgen` uses reflection to analyze .NET assemblies and produces TypeScript declarations that follow Tsonic's interop rules. This allows TypeScript code compiled with Tsonic to properly type-check when using .NET libraries.
+## Features
 
-## Installation
+- **Complete BCL coverage** - Generates declarations for all 130 BCL namespaces, 4,296 types, and 50,675+ members
+- **Zero TypeScript errors** - Output validates cleanly with `tsc --strict`
+- **Branded primitives** - Type-safe numeric types (`int`, `long`, `decimal`, etc.) via `@tsonic/types`
+- **Dual naming modes** - CLR PascalCase (`GetEnumerator`) or JavaScript camelCase (`getEnumerator`)
+- **Generic type preservation** - Full generic type parameter support with constraints
+- **Metadata sidecars** - CLR-specific information (static, virtual, override) in companion JSON files
+- **Library mode** - Generate only your assembly's types, importing BCL types from a pre-existing package
 
-Build the tool from source:
+## Installation
 
 ```bash
-dotnet build
+# Clone and build
+git clone https://github.com/tsoniclang/tsbindgen
+cd tsbindgen
+dotnet build src/tsbindgen/tsbindgen.csproj
 ```
 
-## Usage
+## Quick Start
 
-### Basic Usage
+### Generate BCL declarations
 
 ```bash
-tsbindgen <assembly-path>
+# Generate TypeScript declarations for .NET BCL
+dotnet run --project src/tsbindgen/tsbindgen.csproj -- \
+  generate -d ~/.dotnet/shared/Microsoft.NETCore.App/10.0.0 \
+  -o ./output
 ```
 
-Example:
+### Generate for a custom assembly
 
 ```bash
-tsbindgen /usr/share/dotnet/packs/Microsoft.NETCore.App.Ref/8.0.0/ref/net8.0/System.Text.Json.dll
-# Creates:
-#   ./System.Text.Json.d.ts
-#   ./System.Text.Json.metadata.json
+# Generate for your own assembly
+dotnet run --project src/tsbindgen/tsbindgen.csproj -- \
+  generate -a ./MyLibrary.dll \
+  -d ~/.dotnet/shared/Microsoft.NETCore.App/10.0.0 \
+  -o ./output
 ```
 
-### Command-Line Options
-
-| Option | Short | Description | Default |
-|--------|-------|-------------|---------|
-| `--namespaces` | `-n` | Comma-separated list of namespaces to include | All namespaces |
-| `--out-dir` | `-o` | Output directory for generated file | `.` (current directory) |
-| `--log` | `-l` | Path to write JSON log file | None |
-| `--config` | `-c` | Path to configuration JSON file | None |
-
-### Examples
-
-**Filter specific namespaces:**
+### Library mode (exclude BCL types)
 
 ```bash
-tsbindgen System.Text.Json.dll --namespaces System.Text.Json.Serialization
-```
-
-**Specify output directory:**
+# First, generate BCL types
+dotnet run -- generate -d $DOTNET_RUNTIME -o ./bcl-types
 
-```bash
-tsbindgen System.Net.Http.dll --out-dir ./declarations
+# Then generate your library, importing BCL from the pre-existing package
+dotnet run -- generate -a ./MyLibrary.dll -d $DOTNET_RUNTIME -o ./my-lib --lib ./bcl-types
 ```
 
-**Generate with logging:**
+## CLI Reference
 
-```bash
-tsbindgen System.IO.dll --log build.log.json
-```
+### Commands
 
-**Generate user library excluding BCL types:**
+| Command | Description |
+|---------|-------------|
+| `generate` | Generate TypeScript declarations from .NET assemblies |
 
-```bash
-# Step 1: Generate BCL package (once)
-tsbindgen generate -d ~/dotnet/shared/Microsoft.NETCore.App/10.0.0 -o ./bcl-package
+### Generate Options
 
-# Step 2: Generate user library, BCL types excluded
-tsbindgen generate -a MyLib.dll -d ~/dotnet/.../10.0.0 \
-  --lib ./bcl-package -o ./my-lib-package
-```
-
-## Library Mode (`--lib`)
-
-When generating declarations for a user assembly that references a base library (e.g., .NET BCL), use `--lib` to exclude base library types from output. This produces a clean package containing only your library's types.
-
-**How it works:**
-1. Generate base library package first (contains `metadata.json` + `bindings.json`)
-2. Use `--lib <base-package-path>` when generating user library
-3. tsbindgen filters: keeps types NOT in base, removes types IN base
-4. Validates no dangling references (LIB002 strict check)
-
-**Use case:** Publishing TypeScript declarations for a .NET library without duplicating BCL type definitions.
-
-See [CLI documentation](spec/cli.md#library-mode) for complete details.
-
-## Generated Output
-
-The tool generates two files for each assembly:
-
-1. **TypeScript declarations** (`.d.ts`) - TypeScript type definitions
-2. **Metadata sidecar** (`.metadata.json`) - C# semantic information
-
-### TypeScript Declarations
-
-The `.d.ts` file contains TypeScript declarations with:
-
-1. **Branded type aliases** for C# numeric types:
-   ```typescript
-   type int = number & { __brand: "int" };
-   type decimal = number & { __brand: "decimal" };
-   // ... etc
-   ```
-
-2. **Namespace declarations** matching .NET namespaces:
-   ```typescript
-   declare namespace System.Text.Json {
-     class JsonSerializer {
-       static Serialize<T>(value: T): string;
-     }
-   }
-   ```
-
-3. **Proper type mappings**:
-   - `System.String` → `string`
-   - `System.Int32` → `int`
-   - `System.Boolean` → `boolean`
-   - `Task<T>` → `Promise<T>`
-   - `T[]` → `ReadonlyArray<T>`
-   - `List<T>` → `List<T>`
-   - `Nullable<T>` → `T | null`
-
-### Metadata Sidecar Files
-
-The `.metadata.json` file contains C# semantic information that TypeScript cannot express. This enables the Tsonic compiler to generate correct C# code, particularly for:
-
-- **Virtual/override methods** - Required to correctly override base class methods
-- **Abstract classes/methods** - Required to properly extend abstract types
-- **Sealed classes/methods** - Prevents invalid inheritance
-- **Static classes** - Type-level restrictions
-- **Struct vs Class** - Value vs reference type semantics
-- **Method accessibility** - Public, protected, private, internal modifiers
-
-#### Example Structure
-
-```json
-{
-  "assemblyName": "System.Text.Json",
-  "assemblyVersion": "10.0.0.0",
-  "types": {
-    "System.Text.Json.JsonSerializer": {
-      "kind": "class",
-      "isAbstract": true,
-      "isSealed": false,
-      "isStatic": false,
-      "baseType": null,
-      "interfaces": [],
-      "members": {
-        "Serialize<T>(T)": {
-          "kind": "method",
-          "isVirtual": false,
-          "isAbstract": false,
-          "isSealed": false,
-          "isOverride": false,
-          "isStatic": true,
-          "accessibility": "public"
-        },
-        "Deserialize<T>(string)": {
-          "kind": "method",
-          "isVirtual": false,
-          "isAbstract": false,
-          "isSealed": false,
-          "isOverride": false,
-          "isStatic": true,
-          "accessibility": "public"
-        }
-      }
-    }
-  }
-}
-```
-
-#### Metadata Fields
-
-**Type-level fields:**
-- `kind`: `"class"`, `"struct"`, `"interface"`, or `"enum"`
-- `isAbstract`: True for abstract classes (excluding interfaces)
-- `isSealed`: True for sealed classes (excluding value types and enums)
-- `isStatic`: True for static classes
-- `baseType`: Full name of base class (if any)
-- `interfaces`: Array of implemented interface names
-- `members`: Dictionary of member metadata keyed by signature
-
-**Member-level fields:**
-- `kind`: `"method"`, `"property"`, or `"constructor"`
-- `isVirtual`: True if method can be overridden
-- `isAbstract`: True for abstract methods
-- `isSealed`: True if method prevents further overriding
-- `isOverride`: True if method overrides a base method
-- `isStatic`: True for static members
-- `accessibility`: `"public"`, `"protected"`, `"private"`, `"internal"`, etc.
-
-**Signature format:**
-- Methods: `MethodName(Type1,Type2,...)` using C# type names
-- Properties: `PropertyName`
-- Constructors: `ctor(Type1,Type2,...)`
-
-## Configuration File
-
-You can provide a JSON configuration file to customize behavior:
-
-```json
-{
-  "skipNamespaces": ["System.Internal"],
-  "typeRenames": {
-    "System.OldType": "NewType"
-  },
-  "skipMembers": [
-    "System.String::InternalMethod"
-  ]
-}
-```
+| Option | Short | Description | Default |
+|--------|-------|-------------|---------|
+| `--assembly` | `-a` | Path to assembly file(s) to process | - |
+| `--assembly-dir` | `-d` | Directory containing .NET runtime assemblies | - |
+| `--out-dir` | `-o` | Output directory for generated files | `out` |
+| `--namespaces` | `-n` | Comma-separated namespace filter | (all) |
+| `--naming` | - | Naming convention: `js` (camelCase) or `clr` (PascalCase) | `clr` |
+| `--lib` | - | Path to pre-existing BCL types (library mode) | - |
+| `--verbose` | `-v` | Enable detailed progress output | false |
+| `--logs` | - | Enable specific log categories (comma-separated) | - |
+| `--strict` | - | Enable strict mode validation | false |
 
-Usage:
+### Examples
 
 ```bash
-tsbindgen Assembly.dll --config config.json
-```
-
-## Log Output
-
-When using `--log`, a JSON file is generated with:
-
-```json
-{
-  "timestamp": "2025-11-01T13:03:38Z",
-  "namespaces": ["System.Text.Json"],
-  "typeCounts": {
-    "classes": 40,
-    "interfaces": 5,
-    "enums": 10,
-    "total": 55
-  },
-  "warnings": []
-}
-```
-
-## Type Mapping Rules
-
-The tool follows Tsonic's type mapping specification:
-
-- **Classes** → TypeScript classes
-- **Interfaces** → TypeScript interfaces
-- **Enums** → TypeScript enums
-- **Structs** → TypeScript classes
-- **Static methods** → `static` methods
-- **Properties** → TypeScript properties (with `readonly` when appropriate)
-- **Generic types** → TypeScript generics `<T>`
-- **Optional parameters** → `param?: Type`
-- **Params arrays** → `...values: ReadonlyArray<T>`
-
-## Excluded Members
+# Generate BCL with JavaScript naming
+dotnet run -- generate -d $DOTNET_RUNTIME -o ./out --naming js
 
-The tool automatically skips:
+# Generate specific namespaces only
+dotnet run -- generate -d $DOTNET_RUNTIME -o ./out -n System,System.Collections.Generic
 
-- Private and internal members
-- Compiler-generated types
-- Common Object methods (`Equals`, `GetHashCode`, `ToString`, `GetType`, `ReferenceEquals`)
-- Special-name members (property accessors, backing fields)
+# Verbose output with specific log categories
+dotnet run -- generate -d $DOTNET_RUNTIME -o ./out -v --logs ImportPlanner,FacadeEmitter
 
-## Reserved Keyword Escaping
-
-Parameter names that conflict with TypeScript/JavaScript reserved keywords are automatically escaped by prefixing them with an underscore. This prevents syntax errors in the generated declarations.
-
-**Escaped keywords include:**
-- Control flow: `break`, `case`, `catch`, `continue`, `default`, `do`, `else`, `finally`, `for`, `if`, `return`, `switch`, `throw`, `try`, `while`
-- Declarations: `class`, `const`, `enum`, `export`, `extends`, `function`, `import`, `let`, `var`, `void`
-- Modifiers: `async`, `await`, `implements`, `interface`, `package`, `private`, `protected`, `public`, `static`, `yield`
-- Special identifiers: `arguments`, `eval`, `this`, `super`, `new`, `typeof`, `instanceof`, `delete`, `debugger`, `with`, `in`
-
-**Example:**
-```csharp
-// C# method signature
-public static LoopExpression Loop(Expression body, LabelTarget break, LabelTarget continue)
-
-// Generated TypeScript
-static Loop(body: Expression, _break: LabelTarget, _continue: LabelTarget): LoopExpression;
+# Strict mode (additional validation)
+dotnet run -- generate -d $DOTNET_RUNTIME -o ./out --strict
 ```
 
-This ensures that all generated `.d.ts` files are valid TypeScript and can be parsed by the TypeScript compiler without syntax errors.
+## Output Structure
 
-## Testing & Validation
+For each namespace, tsbindgen generates:
 
-The project includes comprehensive test scripts to ensure correctness and prevent regressions.
-
-### Running All Tests
-
-```bash
-# TypeScript syntax validation
-npm install  # First time only
-npm run validate
-
-# Regression guards (run all)
-./scripts/test-determinism.sh      # Deterministic output
-./scripts/test-strict-mode.sh      # Strict mode compliance
-./scripts/test-surface-manifest.sh # Surface baseline guard
-./scripts/test-lib.sh              # Library mode (--lib)
 ```
-
-### TypeScript Validation
-
-Ensures all generated `.d.ts` files are syntactically valid TypeScript:
-
-```bash
-npm run validate
+output/
+├── System/
+│   ├── index.d.ts              # Public facade (imports + re-exports)
+│   └── internal/
+│       └── index.d.ts          # Type declarations
+├── System.Collections.Generic/
+│   ├── index.d.ts
+│   └── internal/
+│       └── index.d.ts
+└── ... (130 namespaces)
 ```
 
-This script:
-1. Regenerates all 38 BCL assemblies to a temporary directory
-2. Creates an `index.d.ts` with triple-slash references
-3. Runs the TypeScript compiler to validate all declarations
-4. Reports syntax errors (TS1xxx), duplicate type errors (TS6200), and semantic errors (TS2xxx)
+### Output Files
 
-**Success criteria:**
-- ✅ **Zero syntax errors (TS1xxx)** - All output is valid TypeScript
-- ⚠️ **Semantic errors acceptable** - TS2xxx errors are expected (known limitations)
+| File | Description |
+|------|-------------|
+| `index.d.ts` | Public facade with imports and friendly re-exports |
+| `internal/index.d.ts` | Full type declarations with $instance pattern |
 
-**Example output:**
-```
-✓ VALIDATION PASSED
+## Type Mapping
 
-All 38 assemblies generated successfully
-All metadata files present
-✓ No TypeScript syntax errors (TS1xxx)
+### Primitive Types
 
-Error breakdown:
-  - Syntax errors (TS1xxx): 0 ✓
-  - Duplicate types (TS6200): 0 (expected)
-  - Semantic errors (TS2xxx): 1 (expected - missing cross-assembly refs)
-```
+CLR primitive types map to branded TypeScript types from `@tsonic/types`:
 
-### Regression Guards
+| CLR Type | TypeScript Type |
+|----------|----------------|
+| `System.Int32` | `int` |
+| `System.Int64` | `long` |
+| `System.Single` | `float` |
+| `System.Double` | `double` |
+| `System.Decimal` | `decimal` |
+| `System.Byte` | `byte` |
+| `System.Boolean` | `boolean` |
+| `System.String` | `string` |
+| `System.Char` | `char` |
 
-#### Determinism Test (`test-determinism.sh`)
+### Generic Types
 
-Ensures tsbindgen produces identical output across runs:
+Generic types use underscore suffix for arity:
 
-```bash
-./scripts/test-determinism.sh
-```
+| CLR Type | TypeScript Type |
+|----------|----------------|
+| `List<T>` | `List_1<T>` |
+| `Dictionary<TKey, TValue>` | `Dictionary_2<TKey, TValue>` |
+| `Func<T, TResult>` | `Func_2<T, TResult>` |
 
-**What it tests:**
-- Same input → same output (bit-for-bit identical)
-- No nondeterministic ordering or formatting
-- Critical for reproducible builds and diffing
-
-#### Strict Mode Test (`test-strict-mode.sh`)
-
-Verifies strict mode compliance and performance baseline:
-
-```bash
-./scripts/test-strict-mode.sh
+Friendly aliases are also exported:
+```typescript
+// Both work:
+import { List_1 } from "@tsonic/dotnet/System.Collections.Generic";
+import { List } from "@tsonic/dotnet/System.Collections.Generic";  // Friendly alias
 ```
 
-**What it tests:**
-- No diagnostics with `--strict` flag
-- Performance doesn't regress beyond baseline
+### Type Kind Mapping
 
-#### Surface Baseline Test (`test-surface-manifest.sh`)
+| CLR Kind | TypeScript Pattern |
+|----------|-------------------|
+| Class | `interface + const` (instance + static sides) |
+| Struct | `interface + const` |
+| Interface | `interface` |
+| Enum | `const enum` |
+| Delegate | `type` (function signature + CLR type intersection) |
+| Static class | `abstract class` (static methods only) |
 
-Guards against accidental removal of public API surface:
+## Naming Conventions
 
-```bash
-./scripts/test-surface-manifest.sh
+### Default (CLR) Naming
+```typescript
+list.GetEnumerator();  // PascalCase
+console.WriteLine();   // PascalCase
 ```
 
-**What it tests:**
-- Type count matches baseline (prevents deletions)
-- Member count matches baseline (prevents deletions)
-- Intentional changes require baseline update
-
-#### Library Mode Test (`test-lib.sh`)
+### JavaScript Naming (`--naming js`)
+```typescript
+list.getEnumerator();  // camelCase
+console.writeLine();   // camelCase
+```
 
-Validates `--lib` mode filters base library types correctly:
+## Testing
 
 ```bash
-./scripts/test-lib.sh
-```
+# Run all regression tests
+bash test/scripts/run-all.sh
 
-**What it tests:**
-- BCL package generation succeeds
-- User library builds successfully
-- Full generation includes both user + BCL types
-- `--lib` filtered generation includes ONLY user types
-- No LIB001-003 validation errors
-- BCL namespaces correctly excluded from filtered output
-- User namespaces correctly included in filtered output
+# Run validation (TypeScript compilation check)
+node test/validate/validate.js
 
-**Expected result:**
-```
-✓ LIBRARY MODE FULLY VERIFIED
-
-Summary:
-  ✓ BCL generation succeeded (130 namespaces)
-  ✓ User library build succeeded
-  ✓ Full generation: 131 namespaces (user + BCL)
-  ✓ Filtered generation: 1 namespaces (user only)
-  ✓ BCL types correctly excluded via --lib
-  ✓ User types (MyCompany.Utils) correctly included
-  ✓ No LIB001-003 validation errors
-  ✓ Strict mode passes
+# Run completeness verification
+node test/validate/verify-completeness.js
+
+# Individual tests
+bash test/scripts/test-strict-mode.sh
+bash test/scripts/test-determinism.sh
+bash test/scripts/test-surface-manifest.sh
+bash test/scripts/test-lib.sh
 ```
 
 ## Development
@@ -408,41 +201,47 @@ Summary:
 
 ```
 tsbindgen/
-├── Src/
-│   ├── Program.cs              # CLI entry point
-│   ├── AssemblyProcessor.cs    # Reflection and type/metadata extraction
-│   ├── TypeMapper.cs           # C# to TypeScript type mapping
-│   ├── DeclarationRenderer.cs  # TypeScript output generation
-│   ├── TypeInfo.cs             # Data structures for declarations
-│   ├── MetadataModel.cs        # Data structures for metadata
-│   ├── SignatureFormatter.cs   # Method/property signature formatting
-│   ├── MetadataWriter.cs       # JSON metadata serialization
-│   ├── GeneratorConfig.cs      # Configuration support
-│   └── GenerationLogger.cs     # Logging functionality
-├── Scripts/
-│   └── validate.js             # Full validation script
-├── package.json                # npm scripts (validate)
-└── README.md
+├── src/tsbindgen/
+│   ├── Cli/                 # Command-line interface
+│   ├── Load/                # Assembly loading and reflection
+│   ├── Model/               # Symbol graph data structures
+│   ├── Shape/               # Type transformation passes
+│   ├── Normalize/           # Name reservation
+│   ├── Plan/                # Import/export planning
+│   ├── Emit/                # TypeScript file generation
+│   └── Renaming/            # Name conflict resolution
+├── test/
+│   ├── scripts/             # Test scripts
+│   ├── validate/            # Validation scripts
+│   ├── baselines/           # Surface manifest baseline
+│   └── fixtures/            # Test fixtures
+└── docs/                    # Documentation
 ```
 
-### Building
+### Build Commands
 
 ```bash
-dotnet build
-```
+# Build
+dotnet build src/tsbindgen/tsbindgen.csproj
 
-### Running
+# Build release
+dotnet build src/tsbindgen/tsbindgen.csproj -c Release
 
-```bash
-dotnet run --project Src -- <assembly-path> [options]
+# Run
+dotnet run --project src/tsbindgen/tsbindgen.csproj -- <args>
 ```
 
-## Related Documentation
+## Documentation
+
+- [User Guide](docs/user-guide.md) - Detailed usage instructions
+- [Architecture](docs/architecture/) - Internal architecture documentation
+
+## Related Projects
 
-- [Tsonic Type Mappings](../tsonic/spec/04-type-mappings.md)
-- [.NET Interop](../tsonic/spec/08-dotnet-interop.md)
-- [.NET Declarations](../tsonic/spec/14-dotnet-declarations.md)
+- **[@tsonic/dotnet](https://www.npmjs.com/package/@tsonic/dotnet)** - Pre-generated BCL types with JavaScript naming
+- **[@tsonic/dotnet-pure](https://www.npmjs.com/package/@tsonic/dotnet-pure)** - Pre-generated BCL types with CLR naming
+- **[@tsonic/types](https://www.npmjs.com/package/@tsonic/types)** - Branded primitive types
 
 ## License
 
-See LICENSE file for details.
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tsonic/tsbindgen",
-  "version": "0.1.2",
+  "version": "0.7.5",
   "description": "Generate TypeScript declarations from .NET assemblies",
   "type": "module",
   "bin": {
@@ -19,10 +19,10 @@
     "build": "./scripts/build-native.sh"
   },
   "optionalDependencies": {
-    "@tsonic/tsbindgen-darwin-arm64": "0.1.0",
-    "@tsonic/tsbindgen-darwin-x64": "0.1.0",
-    "@tsonic/tsbindgen-linux-arm64": "0.1.0",
-    "@tsonic/tsbindgen-linux-x64": "0.1.0"
+    "@tsonic/tsbindgen-darwin-arm64": "0.7.4",
+    "@tsonic/tsbindgen-darwin-x64": "0.7.4",
+    "@tsonic/tsbindgen-linux-arm64": "0.7.4",
+    "@tsonic/tsbindgen-linux-x64": "0.7.4"
   },
   "keywords": [
     "tsonic",
@@ -36,6 +36,9 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/tsoniclang/tsbindgen.git"
+    "url": "git+https://github.com/tsoniclang/tsbindgen.git"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
   }
 }