Refactor: introduce unified typeSchema API and reporting

CLAUDE.md

@@ -123,7 +123,10 @@ The `APIBuilder` class (`src/api/builder.ts`) provides the fluent API for the th
 .fromSchemas(array)                                 // TypeSchema objects
 
 // Processing & introspection stage - Optional:
-.treeShake({...})                                     // Filter types
+.typeSchema({                                         // IR transformations
+    treeShake: {...},                                 // Filter types
+    promoteLogical: {...},                            // Promote logical models
+})
 .introspection({                                      // Debug output (optional)
     typeSchemas: "./schemas",                         // Type Schemas path/.ndjson
     typeTree: "./tree.json"                           // Type Tree
@@ -184,7 +187,7 @@ Located in `src/api/writer-generator/`:
 4. Use `bun test --watch` for development
 
 ### Working with Tree Shaking
-- Configured via `builder.treeShake({...})`
+- Configured via `builder.typeSchema({ treeShake: {...} })`
 - Specify which resources and fields to include
 - Automatically resolves dependencies
 - Reference format: `"hl7.fhir.r4.core#4.0.1"`

README.md

@@ -79,7 +79,8 @@ yarn add @atomic-ehr/codegen
     const builder = new APIBuilder()
         .fromPackage("hl7.fhir.r4.core", "4.0.1")
         .typescript({})
-        .outputTo("./examples/typescript-r4/fhir-types");
+        .outputTo("./examples/typescript-r4/fhir-types")
+        .introspection({ typeTree: "./type-tree.yaml" });
 
     const report = await builder.generate();
     console.log(prettyReport(report));
@@ -121,11 +122,14 @@ const builder = new APIBuilder()
 
     // Input sources (choose one or combine)
     .fromPackage("hl7.fhir.r4.core", "4.0.1") // NPM registry package
-    .fromPackageRef("https://...package.tgz")  // Remote TGZ file
-    .localStructureDefinitions({ ... })        // Loose JSON files
+    .fromPackageRef("https://...package.tgz") // Remote TGZ file
+    .localStructureDefinitions({ ... })       // Loose JSON files
 
     // Type Schema processing
-    .treeShake({ ... })                        // Include only specified types
+    .typeSchema({
+        treeShake: { ... },        // Include only specified types
+        promoteLogical: { ... },   // Process logical models as resources
+    })
 
     // Code generator (choose one)
     .typescript({                              // TypeScript generator
@@ -201,11 +205,13 @@ This approach enables generating idiomatic code for any programming language whi
 Tree shaking optimizes the generated output by including only the resources you explicitly need and their dependencies. Instead of generating types for an entire FHIR package (which can contain hundreds of resources), you can specify exactly which resources to include:
 
 ```typescript
-.treeShake({
-  "hl7.fhir.r4.core#4.0.1": {
-    "http://hl7.org/fhir/StructureDefinition/Patient": {},
-    "http://hl7.org/fhir/StructureDefinition/Observation": {},
-  }
+.typeSchema({
+    treeShake: {
+        "hl7.fhir.r4.core#4.0.1": {
+            "http://hl7.org/fhir/StructureDefinition/Patient": {},
+            "http://hl7.org/fhir/StructureDefinition/Observation": {}
+        }
+    }
 })
 ```
 
@@ -216,15 +222,17 @@ This feature automatically resolves and includes all dependencies (referenced ty
 Beyond resource-level filtering, tree shaking supports fine-grained field selection using `selectFields` (whitelist) or `ignoreFields` (blacklist):
 
 ```typescript
-.treeShake({
-  "hl7.fhir.r4.core#4.0.1": {
-    "http://hl7.org/fhir/StructureDefinition/Patient": {
-      selectFields: ["id", "name", "birthDate", "gender"]
-    },
-    "http://hl7.org/fhir/StructureDefinition/Observation": {
-      ignoreFields: ["performer", "note"]
+.typeSchema({
+    treeShake: {
+        "hl7.fhir.r4.core#4.0.1": {
+            "http://hl7.org/fhir/StructureDefinition/Patient": {
+                selectFields: ["id", "name", "birthDate", "gender"]
+            },
+            "http://hl7.org/fhir/StructureDefinition/Observation": {
+                ignoreFields: ["performer", "note"]
+            }
+        }
     }
-  }
 })
 ```
 
@@ -247,10 +255,12 @@ Use the programmatic API via `APIBuilder`:
 ```typescript
 const builder = new APIBuilder({})
   .fromPackage("my.custom.pkg", "4.0.1")
-  .promoteLogicToResource({
-    "my.custom.pkg": [
-      "http://example.org/StructureDefinition/MyLogicalModel"
-    ]
+  .typeSchema({
+    promoteLogical: {
+      "my.custom.pkg": [
+        "http://example.org/StructureDefinition/MyLogicalModel"
+      ]
+    }
   })
 ```
 

examples/local-package-folder/README.md

@@ -102,10 +102,12 @@ bun run examples/local-package-folder/generate.ts
 To include only specific resources:
 
 ```typescript
-.treeShake({
-    "example.folder.structures": {
-        "http://example.org/fhir/StructureDefinition/ExampleNotebook": {},
-        "http://example.org/fhir/StructureDefinition/OtherResource": {},
+.typeSchema({
+    treeShake: {
+        "example.folder.structures": {
+            "http://example.org/fhir/StructureDefinition/ExampleNotebook": {},
+            "http://example.org/fhir/StructureDefinition/OtherResource": {},
+        }
     }
 })
 ```
@@ -115,10 +117,12 @@ To include only specific resources:
 To include only specific fields:
 
 ```typescript
-.treeShake({
-    "example.folder.structures": {
-        "http://example.org/fhir/StructureDefinition/ExampleNotebook": {
-            selectFields: ["id", "title", "content"]
+.typeSchema({
+    treeShake: {
+        "example.folder.structures": {
+            "http://example.org/fhir/StructureDefinition/ExampleNotebook": {
+                selectFields: ["id", "title", "content"]
+            }
         }
     }
 })

examples/local-package-folder/generate.ts

@@ -17,9 +17,11 @@ async function generateFromLocalPackageFolder() {
         })
         .typescript({})
         .throwException(true)
-        .treeShake({
-            "example.folder.structures": {
-                "http://example.org/fhir/StructureDefinition/ExampleNotebook": {},
+        .typeSchema({
+            treeShake: {
+                "example.folder.structures": {
+                    "http://example.org/fhir/StructureDefinition/ExampleNotebook": {},
+                },
             },
         })
         .outputTo("./examples/local-package-folder/fhir-types")

examples/typescript-ccda/generate.ts

@@ -22,7 +22,7 @@ if (require.main === module) {
 
     const builder = new APIBuilder({ manager: registry })
         .throwException()
-        .promoteLogicToResource({ "hl7.cda.uv.core": cdaResources })
+        .typeSchema({ promoteLogical: { "hl7.cda.uv.core": cdaResources } })
         .typescript({ withDebugComment: false })
         .outputTo("./examples/typescript-ccda/fhir-types")
         .introspection({

examples/typescript-r4/README.md

@@ -145,10 +145,12 @@ typescript-r4/
 Uncomment the `treeShake` section in `generate.ts`:
 
 ```typescript
-.treeShake({
-  "hl7.fhir.r4.core#4.0.1": {
-    "http://hl7.org/fhir/StructureDefinition/Patient": {},
-    "http://hl7.org/fhir/StructureDefinition/Observation": {},
+.typeSchema({
+  treeShake: {
+    "hl7.fhir.r4.core#4.0.1": {
+      "http://hl7.org/fhir/StructureDefinition/Patient": {},
+      "http://hl7.org/fhir/StructureDefinition/Observation": {},
+    }
   }
 })
 ```