Merge pull request #46 from atomic-ehr/actualize-documentation

Actualize documentation & add GenerationReport prettifier

Author: ryukzak

.github/ISSUE_TEMPLATE/blank.md

@@ -0,0 +1,8 @@
+---
+name: Blank issue
+about: Create a blank issue
+title: ''
+labels: ''
+assignees: ''
+
+---

.github/ISSUE_TEMPLATE/config.yml

@@ -1,4 +1,4 @@
-blank_issues_enabled: false
+blank_issues_enabled: true
 contact_links:
   - name: 🗣️ Chat
     url: https://discord.gg/rumCG3dwgF

CLAUDE.md

@@ -37,13 +37,15 @@ This is a FHIR code generation toolkit with a **three-stage pipeline**:
 
 ### 2. High-Level API (`src/api/`)
 - **APIBuilder** (`builder.ts`): Fluent interface for chaining operations
-- **Generators** (`generators/`): Language-specific code generators
+- **Generators** (`writer-generator/`): Language-specific code generators
   - `typescript.ts`: Generates TypeScript interfaces and types
+  - `python.ts`: Generates Python/Pydantic models
+  - `csharp.ts`: Generates C# classes
 
 ### 3. CLI Interface (`src/cli/`)
 - **Commands** (`commands/`):
   - `typeschema`: Generate and validate TypeSchema from FHIR packages
-  - `generate`: Generate code from TypeSchema (TypeScript)
+  - `generate`: Generate code from TypeSchema (TypeScript, Python, C#)
 - **Main entry** (`index.ts`): CLI setup with yargs
 
 ### Key Data Flow
@@ -89,26 +91,152 @@ FHIR Package → TypeSchema Generator → TypeSchema Format → Code Generators
 ## Important Implementation Details
 
 ### FHIR Package Processing
-- Supports FHIR R4 packages (R5 planned)
+- Supports FHIR R4 packages (R5 in progress)
 - Handles profiles and extensions (US Core in development)
 - Caches parsed schemas for performance
-- Multi-package dependency resolution
+- Multi-package dependency resolution via Canonical Manager
 
 ### TypeSchema Format
 - Intermediate representation between FHIR and target languages
 - Enables multi-language code generation
 - Supports field validation and constraints
 - Handles nested types and references
+- Flattens FHIR's hierarchical structure for easier generation
 
 ### Code Generation
-- Modular generator system
+- Modular generator system via APIBuilder
+- Language-specific writers in `src/api/writer-generator/`
 - TypeScript generator creates interfaces with proper inheritance
-- Extensible for future languages (Python, Rust planned)
+- Extensible architecture for new languages
 - Supports custom naming conventions and output formats
 
+## APIBuilder Flow
+
+The `APIBuilder` class (`src/api/builder.ts`) provides the fluent API for the three-stage pipeline:
+
+```typescript
+// Input stage - Choose one or combine:
+.fromPackage("hl7.fhir.r4.core", "4.0.1")           // NPM registry
+.fromPackageRef("https://example.com/package.tgz")  // Remote TGZ
+.localStructureDefinitions({...})                    // Local files
+.fromSchemas(array)                                   // TypeSchema objects
+
+// Processing stage - Optional:
+.treeShake({...})                                     // Filter types
+.writeTypeSchemas("./schemas")                        // Debug output
+
+// Output stage - Choose one:
+.typescript({...})                                    // TypeScript
+.python({...})                                        // Python
+.csharp("Namespace", "./path")                       // C#
+
+// Finalize:
+.outputTo("./output")                                 // Output directory
+.cleanOutput(true)                                    // Clean before generation
+.generate()                                           // Execute
+```
+
+## Core Concepts
+
+### TypeSchema
+- Universal intermediate format for FHIR data
+- Defined in `src/typeschema/types.ts`
+- Contains: identifier, description, fields, dependencies, base type
+- Fields include type, required flag, array flag, binding info
+- Supports enums for constrained value sets
+
+### Transformers
+Located in `src/typeschema/core/`:
+- `transformer.ts`: Main conversion logic from FHIR to TypeSchema
+- Handles different FHIR element types
+- Processes inheritance and choice types
+- Manages field flattening and snapshot generation
+
+### Writers
+Located in `src/api/writer-generator/`:
+- Base `Writer` class: Handles I/O, indentation, formatting
+- Language writers: TypeScript, Python, C#, Mustache
+- Each writer traverses TypeSchema index and generates code
+- Maintains language-specific idioms and conventions
+
+## Common Development Patterns
+
+### Adding a New Generator Feature
+1. Extend the transformer in `src/typeschema/core/transformer.ts` to produce TypeSchema data
+2. Add logic to the language writer in `src/api/writer-generator/[language].ts`
+3. Add tests in `test/unit/typeschema/` and `test/unit/api/`
+4. Document in design docs if it's a major feature
+
+### Debugging TypeSchema Generation
+1. Use `builder.writeTypeSchemas("./debug-schemas")` to inspect intermediate output
+2. Check `src/typeschema/types.ts` for TypeSchema structure
+3. Review `src/typeschema/core/transformer.ts` for transformation logic
+4. Enable verbose logging with `builder.setLogLevel("DEBUG")`
+
+### Testing Generated Code
+1. Use `builder.build()` instead of `generate()` to avoid file I/O
+2. Tests are organized by component in `test/unit/`
+3. Run `bun test:coverage` to see coverage metrics
+4. Use `bun test --watch` for development
+
+### Working with Tree Shaking
+- Configured via `builder.treeShake({...})`
+- Specify which resources and fields to include
+- Automatically resolves dependencies
+- Reference format: `"hl7.fhir.r4.core#4.0.1"`
+
+## Key File Locations
+
+### Core Logic
+- `src/index.ts` - Main entry point and exports
+- `src/config.ts` - Configuration type definitions
+- `src/api/builder.ts` - APIBuilder implementation
+- `src/typeschema/types.ts` - TypeSchema type definitions
+- `src/typeschema/generator.ts` - TypeSchema generation orchestration
+
+### Generators
+- `src/api/writer-generator/typescript.ts` - TypeScript code generation
+- `src/api/writer-generator/python.ts` - Python/Pydantic generation
+- `src/api/writer-generator/csharp.ts` - C# generation
+- `src/api/writer-generator/base.ts` - Common writer utilities
+
+### FHIR Processing
+- `src/typeschema/register.ts` - Package registration and canonical resolution
+- `src/typeschema/core/transformer.ts` - FHIR → TypeSchema conversion
+- `src/typeschema/core/field-builder.ts` - Field extraction logic
+- `src/typeschema/core/binding.ts` - Value set and binding handling
+
+### Testing
+- `test/unit/typeschema/` - TypeSchema processor tests
+- `test/unit/api/` - Generator and builder tests
+- `test/assets/` - Test fixtures and sample data
+
+## Known Limitations & Gotchas
+
+1. **R5 Support**: Limited, still in development
+2. **Profile Extensions**: Basic parsing only, US Core in progress
+3. **Choice Types**: Supported but representation differs by language
+4. **Circular References**: Handled but may affect tree shaking
+5. **Large Packages**: May require increased Node.js memory (`--max-old-space-size`)
+
+## Performance Optimization Tips
+
+1. Use tree shaking to reduce schema count
+2. Enable caching in APIBuilder
+3. Process large packages in batches
+4. Use `build()` instead of `generate()` for testing
+5. Run `bun run quality` before committing (combines typecheck, lint, test:unit)
+
 ## Roadmap Context
 
 This toolkit focuses on type generation and code generation:
-- **Current**: TypeScript interface generation from FHIR schemas
-- **Next**: Profile/extension support and expanded TypeScript generator capabilities
-- **Future**: Multi-language support, GraphQL schemas, validation functions
+- **Current**: TypeScript, Python, C# interface/class generation from FHIR R4
+- **In Progress**: R5 support, profile/extension enhancements
+- **Planned**: Rust, GraphQL, OpenAPI, validation functions, mock data generation
+
+## Useful External Resources
+
+- [FHIR Specification](https://www.hl7.org/fhir/)
+- [Canonical Manager](https://github.com/atomic-ehr/canonical-manager)
+- [FHIR Schema](https://github.com/fhir-schema/fhir-schema)
+- [TypeSchema Spec](https://www.health-samurai.io/articles/type-schema-a-pragmatic-approach-to-build-fhir-sdk)

CONTRIBUTING.md

@@ -110,38 +110,9 @@ bun test --coverage
 
 ## Testing
 
-### Test Structure
+For comprehensive guidance on writing and running tests, see the [Testing Generators Guide](./docs/guides/testing-generators.md).
 
-```
-test/
-├── unit/             # Unit tests
-│   ├── typeschema/   # TypeSchema tests
-│   └── api/          # API tests
-├── integration/      # Integration tests
-└── e2e/             # End-to-end tests
-```
-
-### Writing Tests
-
-```typescript
-import { describe, expect, it } from "bun:test";
-
-describe("YourFeature", () => {
-  it("should do something specific", async () => {
-    // Arrange
-    const input = createTestInput();
-
-    // Act
-    const result = await yourFunction(input);
-
-    // Assert
-    expect(result).toBeDefined();
-    expect(result.property).toBe(expectedValue);
-  });
-});
-```
-
-### Running Tests
+Quick reference:
 
 ```bash
 # Run all tests
@@ -155,6 +126,9 @@ bun test --coverage
 
 # Run in watch mode
 bun test --watch
+
+# Update snapshots after intentional changes
+bun test -- --update-snapshots
 ```
 
 ## Submitting Changes
@@ -308,44 +282,6 @@ export { helperFunction };
 
 ## Adding New Features
 
-### Adding a New Generator
-
-1. Create generator file: `src/generators/[language].ts`
-
-```typescript
-import type { TypeSchema } from "../typeschema/types";
-
-export interface GeneratorOptions {
-  outputDir: string;
-  // Add language-specific options
-}
-
-export class LanguageGenerator {
-  constructor(private options: GeneratorOptions) {}
-
-  async generate(schemas: TypeSchema[]): Promise<void> {
-    // Implementation
-  }
-}
-```
-
-2. Add to API builder: `src/api/builder.ts`
-
-```typescript
-generateLanguage(options: LanguageGeneratorOptions): this {
-  this.operations.push({
-    type: 'generate',
-    generator: 'language',
-    options
-  });
-  return this;
-}
-```
-
-3. Add CLI command: `src/cli/commands/generate/[language].ts`
-
-4. Add tests: `test/unit/generators/[language].test.ts`
-
 ### Adding a New FHIR Package
 
 1. Update package resolver

README.md

@@ -19,14 +19,24 @@
       - [Load Local StructureDefinitions & TGZ Archives](#load-local-structuredefinitions--tgz-archives)
     - [Intermediate - Type Schema](#intermediate---type-schema)
       - [Tree Shaking](#tree-shaking)
+        - [Field-Level Tree Shaking](#field-level-tree-shaking)
     - [Generation](#generation)
+      - [1. Writer-Based Generation (Programmatic)](#1-writer-based-generation-programmatic)
   - [Roadmap](#roadmap)
   - [Support](#support)
+- [Footnotes](#footnotes)
 
 <!-- markdown-toc end -->
 
 A powerful, extensible code generation toolkit for FHIR ([Fast Healthcare Interoperability Resources](https://www.hl7.org/fhir/)) that transforms FHIR specifications into strongly-typed code for multiple programming languages.
 
+Guides:
+
+- **[Writer Generator Guide](docs/guides/writer-generator.md)** - Build custom code generators with the Writer base class
+- **[TypeSchemaIndex Guide](docs/guides/typeschema-index.md)** - Type Schema structure and utilities
+- **[Testing Generators Guide](docs/guides/testing-generators.md)** - Unit tests, snapshot testing, and best practices
+- **[Contributing Guide](CONTRIBUTING.md)** - Development setup and workflow
+
 ## Features
 
 - 🚀 **High-Performance** - Built with Bun runtime for blazing-fast generation
@@ -62,15 +72,15 @@ yarn add @atomic-ehr/codegen
 1. Write SDK generation script (`generate-types.ts`):
 
     ```typescript
-    import { APIBuilder } from '@atomic-ehr/codegen';
+    import { APIBuilder, prettyReport } from '@atomic-ehr/codegen';
 
     const builder = new APIBuilder()
         .fromPackage("hl7.fhir.r4.core", "4.0.1")
         .typescript({})
         .outputTo("./examples/typescript-r4/fhir-types");
 
     const report = await builder.generate();
-    console.log(report);
+    console.log(prettyReport(report));
     ```
 
 2. Run the script with:
@@ -221,14 +231,21 @@ FHIR choice types (like `multipleBirth[x]` which can be boolean or integer) are
 
 ### Generation
 
-The generation stage uses a `WriterGenerator` system that transforms Type Schema into target language code. The architecture consists of:
+The generation stage transforms Type Schema into target language code using two complementary approaches:
+
+#### 1. Writer-Based Generation (Programmatic)
+
+For languages with built-in support (TypeScript, Python, C#), extend the `Writer` class to implement language-specific generators:
+
+- **FileSystemWriter**: Base class providing file I/O, directory management, and buffer handling (both disk and in-memory modes)
+- **Writer**: Extends FileSystemWriter with code formatting utilities (indentation, blocks, comments, line management)
+- **Language Writers** (`TypeScript`, `Python`[^py], `CSharp`): Implement language-specific generation logic by traversing TypeSchema index and generating corresponding types, interfaces, or classes
 
-- **Base Writer** (`Writer`): Handles file I/O, indentation, and code formatting primitives
-- **Language Writers** (e.g., `TypeScript`): Implement language-specific generation logic
+[^py]: For details on [Type Schema: Python SDK for FHIR](https://www.health-samurai.io/articles/type-schema-python-sdk-for-fhir)
 
-Writers provide high-level abstractions for common code patterns (blocks, imports, type definitions) while maintaining full control over output formatting. Each language writer traverses the Type Schema index and generates corresponding types, interfaces, or classes following that language's idioms and best practices.
+Each language writer maintains full control over output formatting while leveraging high-level abstractions for common code patterns. Writers follow language idioms and best practices, with optimized output for production use.
 
-- [Type Schema: Python SDK for FHIR](https://www.health-samurai.io/articles/type-schema-python-sdk-for-fhir)
+**When to use**: Full control needed, complex generation logic, performance-critical, language has a dedicated writer, production-grade output
 
 ## Roadmap
 
@@ -266,7 +283,8 @@ Writers provide high-level abstractions for common code patterns (blocks, import
         .execute();
     ```
 
-- [ ] **Python generation**
+- [x] **Python generation**
+- [x] **C# generation**
 - [ ] **Rust generation**
 - [ ] **GraphQL schema generation**
 - [ ] **OpenAPI specification generation**