@atomic-ehr/codegen 0.0.18 → 0.0.19-canary.20260917110212.f40edba

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as FS from '@atomic-ehr/fhirschema';
 import { FHIRSchema, StructureDefinition as StructureDefinition$1, FHIRSchemaElement } from '@atomic-ehr/fhirschema';
-import { CanonicalManager, PreprocessContext } from '@atomic-ehr/fhir-canonical-manager';
+import { CanonicalManager, Patches, PreprocessContext, PackageIndexMode, ReportEntry } from '@atomic-ehr/fhir-canonical-manager';
 
 interface Extension extends Element {
     url: string;
@@ -937,6 +937,8 @@ type Register = {
     allFs(): RichFHIRSchema[];
     /** Returns all ValueSets from all packages in the resolver */
     allVs(): RichValueSet[];
+    /** Returns raw terminology resources grouped by their originating package. */
+    allTerminology(): PackageTerminology[];
     resolveVs(_pkg: PackageMeta, canonicalUrl: CanonicalUrl): RichValueSet | undefined;
     resolveAny(canonicalUrl: CanonicalUrl): any | undefined;
     resolveElementSnapshot(fhirSchema: RichFHIRSchema, path: string[]): FHIRSchemaElement;
@@ -947,6 +949,25 @@ type Register = {
 type PkgId = string;
 type PkgName = string;
 type FocusedResource = StructureDefinition$1 | ValueSet | CodeSystem;
+type TerminologyResource = {
+    resourceType: "CodeSystem" | "ValueSet" | "NamingSystem";
+    id?: string;
+    name?: string;
+    url: string;
+    /** Declared CodeSystem content mode; malformed packages may carry other strings. */
+    content?: CodeSystem["content"] | (string & {});
+    concept?: CodeSystemConcept[];
+};
+type PackageTerminology = {
+    packageMeta: PackageMeta;
+    resources: TerminologyResource[];
+};
+/**
+ * User-supplied attestation of how a package's content was verified, stamped
+ * verbatim on its entries. `"unverifiable"` also suppresses codes and
+ * displays; packages without an attestation are stamped `"not-recorded"`.
+ */
+type TerminologyVerification = "registry-integrity" | "unverifiable" | (string & {});
 type CanonicalResolution<T> = {
     deep: number;
     pkg: PackageMeta;
@@ -958,6 +979,7 @@ type PackageIndex = {
     canonicalResolution: Record<CanonicalUrl, CanonicalResolution<FocusedResource>[]>;
     fhirSchemas: Record<CanonicalUrl, RichFHIRSchema>;
     valueSets: Record<CanonicalUrl, RichValueSet>;
+    terminology: TerminologyResource[];
 };
 type PackageAwareResolver = Record<PkgId, PackageIndex>;
 type ResolutionTree = Record<PkgName, Record<CanonicalUrl, {
@@ -1087,8 +1109,29 @@ type TypeScriptOptions = {
      */
     openResourceTypeSet: boolean;
     primitiveTypeExtension: boolean;
+    /** How relative import/export specifiers are written in generated modules.
+     *
+     * - "extensionless" (default): `"./profiles"`, `"../Patient"` — resolved by
+     *   bundlers, TypeScript and Bun.
+     * - "node-esm": explicit file targets (`"./profiles/index.js"`,
+     *   `"../Patient.js"`), so output transpiled to plain `.js` modules under
+     *   `"type": "module"` loads under Node's ESM resolver.
+     */
+    moduleSpecifierStyle?: "extensionless" | "node-esm";
     extensionGetterDefault?: "flat" | "profile" | "raw";
     sliceGetterDefault?: "flat" | "raw";
+    terminology?: {
+        /** Emit one terminology module for every resolved package. Defaults to false. */
+        enabled?: boolean;
+        /**
+         * Limit terminology modules to these `name@version` package refs.
+         * When omitted, every resolved package in the closure emits one —
+         * which for real closures (VSAC, hl7.terminology, ...) can be huge.
+         */
+        packages?: string[];
+        /** Attestation per `name@version` package ref; see {@link TerminologyVerification}. */
+        packageVerification?: Record<string, TerminologyVerification>;
+    };
 } & WriterOptions;
 
 /**
@@ -1099,18 +1142,63 @@ type TypeScriptOptions = {
  */
 
 /**
- * Configuration options for the API builder
+ * Configuration of the CanonicalManager package loader. Everything in this block is forwarded
+ * verbatim to the CanonicalManager the builder constructs; it is ignored when a prebuilt
+ * `manager`/`register` is injected (they own their own configuration).
  */
+type CanonicalManagerOptions = {
+    /** Custom FHIR package registry URL (default: https://fs.get-ig.org/pkgs/). */
+    registry?: string;
+    /** How a package's shipped `.index.json` is treated: trust it (`"use"`, default), heal a
+     *  broken one with a directory scan (`"recover"`), or rebuild it unconditionally (`"regenerate"`). */
+    packageIndex?: PackageIndexMode;
+    /** Drop the CanonicalManager cache before loading packages. Note that this wipes the whole
+     *  working directory, every cached package set included — pair it with a dedicated
+     *  `workingDir` so unrelated callers keep their downloads. */
+    dropCache?: boolean;
+    /** Directory holding the downloaded packages and their processed cache
+     *  (default: `.codegen-cache/canonical-manager-cache`). */
+    workingDir?: string;
+    /** Per-phase patch handlers (package-defect fixes; helpers on the `@atomic-ehr/fhir-canonical-manager/patch` subpath). */
+    patches?: Partial<Patches>;
+};
+/** Stored generator configuration — read throughout a generation run. */
 interface APIBuilderOptions {
     outputDir: string;
     cleanOutput: boolean;
     throwException: boolean;
     typeSchema?: IrConf;
-    /** Custom FHIR package registry URL (default: https://fs.get-ig.org/pkgs/) */
-    registry: string | undefined;
-    /** Drop the canonical manager cache */
-    dropCanonicalManagerCache: boolean;
 }
+/** Old spellings of the loader configuration, each mapped onto `canonicalManager` with a
+ *  deprecation warning; the whole block is deleted together in a future release. */
+type DeprecatedLoaderOptions = {
+    /** @deprecated Use `canonicalManager: { registry }`. */
+    registry?: string;
+    /** @deprecated Use `canonicalManager: { dropCache }`. */
+    dropCanonicalManagerCache?: boolean;
+    /** @deprecated Use `canonicalManager: { patches }`. */
+    patches?: Partial<Patches>;
+    /** @deprecated Use `canonicalManager: { patches }` with the CM `/patch` subpath helpers. */
+    preprocessPackage?: (context: PreprocessContext) => PreprocessContext;
+    /** @deprecated Use `canonicalManager: { packageIndex }`. */
+    packageIndex?: PackageIndexMode;
+    /** @deprecated Use `canonicalManager: { packageIndex: "regenerate" }`. */
+    ignorePackageIndex?: boolean;
+    /** @deprecated Pass the instance via `canonicalManager` instead. */
+    manager?: ReturnType<typeof CanonicalManager>;
+};
+/** What the constructor accepts: stored options, input wiring, and the deprecated spellings. */
+type APIBuilderInput = Partial<APIBuilderOptions> & DeprecatedLoaderOptions & {
+    /** The package loader: either its configuration (registry, packageIndex, dropCache,
+     *  patches) for the manager the builder constructs, or a prebuilt CanonicalManager
+     *  instance — interchangeable from the caller's side. */
+    canonicalManager?: CanonicalManagerOptions | ReturnType<typeof CanonicalManager>;
+    /** Apply the shipped input fixes (`src/api/builtin-patches.ts`) to the constructed
+     *  loader. Defaults to true; `false` is the explicit opt-out. */
+    builtinPatches?: boolean;
+    register?: Register;
+    logger?: CodegenLogManager;
+};
 type GenerationReport = {
     success: boolean;
     outputDir: string;
@@ -1119,6 +1207,9 @@ type GenerationReport = {
     errors: string[];
     warnings: string[];
     duration: number;
+    /** CanonicalManager input-fix diagnostics (exclusions, index recoveries, deprecations).
+     *  Absent when a prebuilt `register` is used; empty for packages served from cache. */
+    inputReport?: ReportEntry[];
 };
 interface PrettyReportOptions {
     /** When a generator produces more than this many files, aggregate them by directory instead of listing each file. */
@@ -1143,13 +1234,7 @@ declare class APIBuilder {
     private managerInput;
     private logger;
     private generators;
-    constructor(userOpts?: Partial<APIBuilderOptions> & {
-        manager?: ReturnType<typeof CanonicalManager>;
-        register?: Register;
-        preprocessPackage?: (context: PreprocessContext) => PreprocessContext;
-        ignorePackageIndex?: boolean;
-        logger?: CodegenLogManager;
-    });
+    constructor(userOpts?: APIBuilderInput);
     fromPackage(packageName: string, version?: string): APIBuilder;
     fromPackageRef(packageRef: string): APIBuilder;
     localStructureDefinitions(config: LocalStructureDefinitionConfig): APIBuilder;
@@ -1159,12 +1244,21 @@ declare class APIBuilder {
     python(userOptions: Partial<PythonGeneratorOptions>): APIBuilder;
     mustache(templatePath: string, userOpts: Partial<FileSystemWriterOptions & FileBasedMustacheGeneratorOptions>): this;
     csharp(userOptions: Partial<CSharpGeneratorOptions>): APIBuilder;
+    /** Set by `outputTo`, to tell an explicit output directory from the default one. */
+    private explicitOutputDir?;
+    /** Output directory for a generator being configured now. `subdir` applies only when
+     *  `outputTo` never named one. */
+    private generatorOutputDir;
     /**
-     * Set the output directory for all generators
+     * Set the output directory for all generators, whenever they are configured
      */
     outputTo(directory: string): APIBuilder;
     throwException(enabled?: boolean): APIBuilder;
     cleanOutput(enabled?: boolean): APIBuilder;
+    /** Set when a TypeScript generator wants terminology modules: the emitted
+     *  terminology types are derived from the generated CodeSystem type, so it
+     *  must survive tree shaking even when the user's rules don't ask for it. */
+    private wantsTerminologyTypes;
     typeSchema(cfg: IrConf): this;
     irReport(userOpts: Partial<IrReportWriterWriterOptions>): this;
     generate(): Promise<GenerationReport>;