Merge pull request #55 from atomic-ehr/fhir-schema-export

ryukzak · web-flow · commit 79237e8d0a1e · 2026-01-21T14:14:49.000+01:00
Add FHIRSchema and StructureDefinition export for introspection
diff --git a/README.md b/README.md
@@ -145,9 +145,11 @@ const builder = new APIBuilder()
 
     // Optional: Introspection & debugging
     .throwException()                          // Throw on errors (optional)
-    .introspection({ 
-        typeSchemas: "./schemas", 
-        typeTree: "./tree.yaml" 
+    .introspection({
+        typeSchemas: "./schemas",              // Export TypeSchemas
+        typeTree: "./tree.yaml",               // Export type tree
+        fhirSchemas: "./fhir-schemas",         // Export FHIR schemas
+        structureDefinitions: "./sd"           // Export StructureDefinitions
     })
 
     // Execute generation
diff --git a/examples/typescript-r4/.gitignore b/examples/typescript-r4/.gitignore
@@ -1 +1,3 @@
 fhir-types/type-schemas/
+fhir-types/fhir-schemas/
+fhir-types/structure-definitions/
diff --git a/examples/typescript-r4/generate.ts b/examples/typescript-r4/generate.ts
@@ -17,6 +17,8 @@ if (require.main === module) {
         .introspection({
             typeSchemas: "type-schemas",
             typeTree: "type-tree.yaml",
+            fhirSchemas: "fhir-schemas",
+            structureDefinitions: "structure-definitions",
         })
         .outputTo("./examples/typescript-r4/fhir-types")
         .treeShake({
diff --git a/src/api/builder.ts b/src/api/builder.ts
@@ -396,7 +396,7 @@ export class APIBuilder {
             const typeSchemas = await generateTypeSchemas(register, this.logger);
 
             const tsIndexOpts = {
-                resolutionTree: register.resolutionTree(),
+                register,
                 logger: this.logger,
             };
             let tsIndex = mkTypeSchemaIndex(typeSchemas, tsIndexOpts);
diff --git a/src/api/writer-generator/introspection.ts b/src/api/writer-generator/introspection.ts
@@ -1,12 +1,16 @@
 import * as Path from "node:path";
-import { extractNameFromCanonical, type TypeSchema } from "@root/typeschema/types";
+import type { StructureDefinition } from "@atomic-ehr/fhirschema";
+import type { RichFHIRSchema } from "@root/typeschema/types";
+import { type CanonicalUrl, extractNameFromCanonical, type TypeSchema } from "@root/typeschema/types";
 import type { TypeSchemaIndex } from "@root/typeschema/utils";
 import YAML from "yaml";
 import { FileSystemWriter, type FileSystemWriterOptions } from "./writer";
 
 export interface IntrospectionWriterOptions extends FileSystemWriterOptions {
     typeSchemas?: string /** if .ndjson -- put in one file, else -- split into separated files*/;
     typeTree?: string /** .json or .yaml file */;
+    fhirSchemas?: string /** if .ndjson -- put in one file, else -- split into separated files*/;
+    structureDefinitions?: string /** if .ndjson -- put in one file, else -- split into separated files*/;
 }
 
 const normalizeFileName = (str: string): string => {
@@ -15,6 +19,43 @@ const normalizeFileName = (str: string): string => {
     return res;
 };
 
+const typeSchemaToJson = (ts: TypeSchema, pretty: boolean): { filename: string; content: string } => {
+    const pkgPath = normalizeFileName(ts.identifier.package);
+    const name = normalizeFileName(`${ts.identifier.name}(${extractNameFromCanonical(ts.identifier.url)})`);
+    const baseName = Path.join(pkgPath, name);
+
+    return {
+        filename: baseName,
+        content: JSON.stringify(ts, null, pretty ? 2 : undefined),
+    };
+};
+
+const fhirSchemaToJson = (fs: RichFHIRSchema, pretty: boolean): { filename: string; content: string } => {
+    const pkgPath = normalizeFileName(fs.package_meta.name);
+    const name = normalizeFileName(`${fs.name}(${extractNameFromCanonical(fs.url)})`);
+    const baseName = Path.join(pkgPath, name);
+
+    return {
+        filename: baseName,
+        content: JSON.stringify(fs, null, pretty ? 2 : undefined),
+    };
+};
+
+const structureDefinitionToJson = (sd: StructureDefinition, pretty: boolean): { filename: string; content: string } => {
+    const pkgPath = normalizeFileName(sd.package_name ?? "unknown");
+    const name = normalizeFileName(`${sd.name}(${extractNameFromCanonical(sd.url as CanonicalUrl)})`);
+    const baseName = Path.join(pkgPath, name);
+
+    // HACK: for some reason ID may change between CI and local install
+    sd = structuredClone(sd);
+    sd.id = undefined;
+
+    return {
+        filename: baseName,
+        content: JSON.stringify(sd, null, pretty ? 2 : undefined),
+    };
+};
+
 export class IntrospectionWriter extends FileSystemWriter<IntrospectionWriterOptions> {
     async generate(tsIndex: TypeSchemaIndex): Promise<void> {
         if (this.opts.typeSchemas) {
@@ -24,9 +65,12 @@ export class IntrospectionWriter extends FileSystemWriter<IntrospectionWriterOpt
             this.logger()?.debug(`IntrospectionWriter: Generating ${typeSchemas.length} schemas to ${outputPath}`);
 
             if (Path.extname(outputPath) === ".ndjson") {
-                this.writeToSingleFile(typeSchemas, outputPath);
+                this.writeNdjson(typeSchemas, outputPath, typeSchemaToJson);
             } else {
-                this.writeToSeparateFiles(typeSchemas, outputPath);
+                this.writeJsonFiles(
+                    typeSchemas.map((ts) => typeSchemaToJson(ts, true)),
+                    outputPath,
+                );
             }
 
             this.logger()?.info(`Introspection generation completed: ${typeSchemas.length} schemas written`);
@@ -36,67 +80,74 @@ export class IntrospectionWriter extends FileSystemWriter<IntrospectionWriterOpt
             await this.writeTypeTree(tsIndex);
             this.logger()?.info(`IntrospectionWriter: Type tree exported to ${this.opts.typeTree}`);
         }
-    }
-
-    private async writeToSingleFile(typeSchemas: TypeSchema[], outputFile: string): Promise<void> {
-        this.logger()?.info(`Writing introspection data to single file: ${outputFile}`);
 
-        const dir = Path.dirname(outputFile);
-        const file = Path.basename(outputFile);
+        if (this.opts.fhirSchemas && tsIndex.register) {
+            const outputPath = this.opts.fhirSchemas;
+            const fhirSchemas = tsIndex.register.allFs();
 
-        this.cd(dir, () => {
-            this.cat(file, () => {
-                for (const ts of typeSchemas) {
-                    const json = JSON.stringify(ts);
-                    this.write(`${json}\n`);
-                }
-            });
-        });
+            this.logger()?.debug(`IntrospectionWriter: Generating ${fhirSchemas.length} FHIR schemas to ${outputPath}`);
 
-        this.logger()?.info(`Single file output: ${typeSchemas.length} introspection entries written to ${outputFile}`);
-    }
+            if (Path.extname(outputPath) === ".ndjson") {
+                this.writeNdjson(fhirSchemas, outputPath, fhirSchemaToJson);
+            } else {
+                this.writeJsonFiles(
+                    fhirSchemas.map((fs) => fhirSchemaToJson(fs, true)),
+                    outputPath,
+                );
+            }
 
-    private async writeToSeparateFiles(typeSchemas: TypeSchema[], outputDir: string): Promise<void> {
-        this.logger()?.info(`Writing introspection data to separate files in ${outputDir}`);
+            this.logger()?.info(`FHIR schema generation completed: ${fhirSchemas.length} schemas written`);
+        }
 
-        // Group introspection data by package and name
-        const files: Record<string, TypeSchema[]> = {};
+        if (this.opts.structureDefinitions && tsIndex.register) {
+            const outputPath = this.opts.structureDefinitions;
+            const structureDefinitions = tsIndex.register.allSd();
 
-        for (const ts of typeSchemas) {
-            const pkgPath = normalizeFileName(ts.identifier.package);
-            const name = normalizeFileName(`${ts.identifier.name}(${extractNameFromCanonical(ts.identifier.url)})`);
-            const baseName = Path.join(pkgPath, name);
+            this.logger()?.debug(
+                `IntrospectionWriter: Generating ${structureDefinitions.length} StructureDefinitions to ${outputPath}`,
+            );
 
-            if (!files[baseName]) {
-                files[baseName] = [];
+            if (Path.extname(outputPath) === ".ndjson") {
+                this.writeNdjson(structureDefinitions, outputPath, structureDefinitionToJson);
+            } else {
+                this.writeJsonFiles(
+                    structureDefinitions.map((sd) => structureDefinitionToJson(sd, true)),
+                    outputPath,
+                );
             }
 
-            if (!files[baseName].some((e) => JSON.stringify(e) === JSON.stringify(ts))) {
-                files[baseName].push(ts);
-            }
+            this.logger()?.info(
+                `StructureDefinition generation completed: ${structureDefinitions.length} schemas written`,
+            );
         }
+    }
+
+    private async writeNdjson<T>(
+        items: T[],
+        outputFile: string,
+        toJson: (item: T, pretty: boolean) => { filename: string; content: string },
+    ): Promise<void> {
+        this.cd(Path.dirname(outputFile), () => {
+            this.cat(Path.basename(outputFile), () => {
+                for (const item of items) {
+                    const { content } = toJson(item, false);
+                    this.write(`${content}\n`);
+                }
+            });
+        });
+    }
 
+    private async writeJsonFiles(items: { filename: string; content: string }[], outputDir: string): Promise<void> {
         this.cd(outputDir, () => {
-            for (const [baseName, schemas] of Object.entries(files)) {
-                schemas.forEach((schema, index) => {
-                    const fileName =
-                        index === 0 ? `${baseName}.introspection.json` : `${baseName}-${index}.introspection.json`;
-                    const dir = Path.dirname(fileName);
-                    const file = Path.basename(fileName);
-
-                    this.cd(dir, () => {
-                        this.cat(file, () => {
-                            const json = JSON.stringify(schema, null, 2);
-                            this.write(json);
-                        });
+            for (const { filename, content } of items) {
+                const fileName = `${filename}.json`;
+                this.cd(Path.dirname(fileName), () => {
+                    this.cat(Path.basename(fileName), () => {
+                        this.write(content);
                     });
                 });
             }
         });
-
-        this.logger()?.info(
-            `Separate files output: ${typeSchemas.length} introspection entries written to ${outputDir} in ${Object.keys(files).length} groups`,
-        );
     }
 
     private async writeTypeTree(tsIndex: TypeSchemaIndex): Promise<void> {
diff --git a/src/typeschema/register.ts b/src/typeschema/register.ts
@@ -18,6 +18,7 @@ export type Register = {
     resolveFs(pkg: PackageMeta, canonicalUrl: CanonicalUrl): RichFHIRSchema | undefined;
     resolveFsGenealogy(pkg: PackageMeta, canonicalUrl: CanonicalUrl): RichFHIRSchema[];
     resolveFsSpecializations(pkg: PackageMeta, canonicalUrl: CanonicalUrl): RichFHIRSchema[];
+    allSd(): StructureDefinition[];
     allFs(): RichFHIRSchema[];
     allVs(): RichValueSet[];
     resolveVs(_pkg: PackageMeta, canonicalUrl: CanonicalUrl): RichValueSet | undefined;
@@ -248,6 +249,23 @@ export const registerFromManager = async (
             if (isStructureDefinition(res)) return res as StructureDefinition;
             return undefined;
         },
+        allSd: () =>
+            Object.values(resolver)
+                .flatMap((pkgIndex) =>
+                    Object.values(pkgIndex.canonicalResolution).flatMap((resolutions) =>
+                        resolutions.map((r) => {
+                            let sd = r.resource as StructureDefinition;
+                            if (!sd.package_name) {
+                                sd = structuredClone(sd);
+                                sd.package_name = pkgIndex.pkg.name;
+                                sd.package_version = pkgIndex.pkg.version;
+                            }
+                            return sd;
+                        }),
+                    ),
+                )
+                .filter((r): r is StructureDefinition => isStructureDefinition(r))
+                .sort((sd1, sd2) => sd1.url.localeCompare(sd2.url)),
         allFs: () => Object.values(resolver).flatMap((pkgIndex) => Object.values(pkgIndex.fhirSchemas)),
         allVs: () => Object.values(resolver).flatMap((pkgIndex) => Object.values(pkgIndex.valueSets)),
         resolveVs,
diff --git a/src/typeschema/tree-shake.ts b/src/typeschema/tree-shake.ts
@@ -280,7 +280,7 @@ export const treeShake = (
     const shaked = collectDeps(focusedSchemas, {});
 
     const report: TreeShakeReport = { skippedPackages: [], packages: {} };
-    const shakedIndex = mkTypeSchemaIndex(shaked, { resolutionTree, logger, treeShakeReport: report });
+    const shakedIndex = mkTypeSchemaIndex(shaked, { register: tsIndex.register, logger, treeShakeReport: report });
     mutableFillReport(report, tsIndex, shakedIndex);
     return shakedIndex;
 };
diff --git a/src/typeschema/utils.ts b/src/typeschema/utils.ts
@@ -3,7 +3,7 @@ import * as Path from "node:path";
 import type { TreeShakeReport } from "@root/typeschema/tree-shake";
 import type { CodegenLogger } from "@root/utils/codegen-logger";
 import * as YAML from "yaml";
-import type { ResolutionTree } from "./register";
+import type { Register } from "./register";
 import {
     type CanonicalUrl,
     type Field,
@@ -154,6 +154,7 @@ export type TypeSchemaIndex = {
     _relations: TypeRelation[];
     schemas: TypeSchema[];
     schemasByPackage: Record<PackageName, TypeSchema[]>;
+    register?: Register;
     collectComplexTypes: () => RegularTypeSchema[];
     collectResources: () => RegularTypeSchema[];
     collectLogicalModels: () => RegularTypeSchema[];
@@ -177,11 +178,11 @@ type EntityTree = Record<PackageName, Record<Identifier["kind"], Record<Canonica
 export const mkTypeSchemaIndex = (
     schemas: TypeSchema[],
     {
-        resolutionTree,
+        register,
         logger,
         treeShakeReport,
     }: {
-        resolutionTree?: ResolutionTree;
+        register?: Register;
         logger?: CodegenLogger;
         treeShakeReport?: TreeShakeReport;
     },
@@ -222,7 +223,8 @@ export const mkTypeSchemaIndex = (
         return index[id.url]?.[id.package];
     };
     const resolveByUrl = (pkgName: PackageName, url: CanonicalUrl) => {
-        if (resolutionTree) {
+        if (register) {
+            const resolutionTree = register.resolutionTree();
             const resolution = resolutionTree[pkgName]?.[url]?.[0];
             if (resolution) {
                 return index[url]?.[resolution.pkg.name];
@@ -366,6 +368,7 @@ export const mkTypeSchemaIndex = (
         _relations: relations,
         schemas,
         schemasByPackage: groupByPackages(schemas),
+        register,
         collectComplexTypes: () => schemas.filter(isComplexTypeTypeSchema),
         collectResources: () => schemas.filter(isResourceTypeSchema),
         collectLogicalModels: () => schemas.filter(isLogicalTypeSchema),
diff --git a/test/api/write-generator/__snapshots__/introspection.test.ts.snap b/test/api/write-generator/__snapshots__/introspection.test.ts.snap
diff --git a/test/api/write-generator/introspection.test.ts b/test/api/write-generator/introspection.test.ts
diff --git a/test/unit/typeschema/utils.ts b/test/unit/typeschema/utils.ts

Original file line number	Diff line number	Diff line change
`@@ -1 +1,3 @@`
`1`	`1`	`fhir-types/type-schemas/`
	`2`	`+fhir-types/fhir-schemas/`
	`3`	`+fhir-types/structure-definitions/`