@xrmforge/typegen 0.10.0 → 0.11.0

package/dist/index.d.ts

@@ -765,6 +765,10 @@ declare class MetadataClient {
      * Queries the customapi, customapirequestparameter, and customapiresponseproperty
      * tables and joins them into CustomApiTypeInfo objects.
      *
+     * APIs, request parameters, and response properties are sorted alphabetically
+     * by uniquename (ordinal) so the result is deterministic regardless of
+     * server row order.
+     *
      * @param solutionFilter - Optional: filter by solution unique name
      * @returns Array of complete Custom API definitions
      */
@@ -1543,6 +1547,19 @@ interface GenerateConfig {
     cacheDir?: string;
     /** XrmForge namespace prefix (default: "XrmForge") */
     namespacePrefix?: string;
+    /**
+     * Check mode (drift detection): generate in-memory and compare the result
+     * byte-by-byte against the files in outputDir WITHOUT any write access
+     * (no output files, no cache reads or updates, no orphan deletion).
+     * The comparison result is returned in GenerationResult.checkResult.
+     * Intended as a CI step that fails when the checked-in generated files
+     * no longer match the live environment.
+     * When enabled, useCache is ignored: the check must run against live
+     * metadata, otherwise a stale local cache would mask exactly the drift
+     * it is supposed to find.
+     * @defaultValue false
+     */
+    checkOnly?: boolean;
 }
 /** Result of generating types for a single entity */
 interface EntityGenerationResult {
@@ -1575,6 +1592,30 @@ interface CacheStats {
     /** Number of entities removed (deleted in Dataverse) */
     entitiesDeleted: number;
 }
+/** A single drift finding from check mode */
+interface CheckFinding {
+    /** Relative path from outputDir (e.g. "actions/global.ts") */
+    relativePath: string;
+    /** Category of the file (matches GeneratedFile.type) */
+    type: GeneratedFile['type'];
+    /**
+     * Drift class:
+     * - "changed": file exists on disk but differs from freshly generated content
+     * - "missing": generator produces this file but it does not exist on disk
+     * - "orphaned": file exists on disk but the generator no longer produces it
+     *   (e.g. the entity or Custom API was deleted in Dataverse)
+     */
+    status: 'changed' | 'missing' | 'orphaned';
+}
+/** Result of a drift check (GenerateConfig.checkOnly) */
+interface CheckResult {
+    /** True if at least one finding exists (generated output drifted) */
+    drift: boolean;
+    /** Number of files that are byte-identical on disk */
+    unchanged: number;
+    /** All drift findings (changed, missing, orphaned files) */
+    findings: CheckFinding[];
+}
 /** Overall result of the generation process */
 interface GenerationResult {
     /** Per-entity results */
@@ -1587,6 +1628,12 @@ interface GenerationResult {
     durationMs: number;
     /** Cache statistics (present when useCache was enabled) */
     cacheStats?: CacheStats;
+    /**
+     * Drift check result (present when checkOnly was enabled and all entities
+     * were fetched successfully; absent on fetch failures or abort, because a
+     * partial generation would produce misleading missing/orphaned findings).
+     */
+    checkResult?: CheckResult;
 }
 
 /**
@@ -1663,4 +1710,4 @@ declare class TypeGenerationOrchestrator {
     private generateFormMapping;
 }
 
-export { type ActionGeneratorOptions, ApiRequestError, type AttributeMetadata, type AuthConfig, type AuthMethod, AuthenticationError, type CacheStats, type ChangeDetectionResult, ChangeDetector, type ClientCredentialsAuth, ConfigError, ConsoleLogSink, type CustomApiTypeInfo, DEFAULT_LABEL_CONFIG, DataverseHttpClient, type DateTimeAttributeMetadata, type DecimalAttributeMetadata, type DeviceCodeAuth, type EntityFieldsGeneratorOptions, type EntityGenerationResult, type EntityGeneratorOptions, type EntityMetadata, type EntityNamesGeneratorOptions, type EntityTypeInfo, ErrorCode, FastXmlParser, type FormControl, type FormGeneratorOptions, type FormSection, type FormTab, type GenerateConfig, type GeneratedFile, GenerationError, type GenerationResult, type GroupedCustomApis, type HttpClientOptions, type IntegerAttributeMetadata, type InteractiveAuth, JsonLogSink, type Label, type LabelConfig, type LocalizedLabel, type LogEntry, LogLevel, type LogSink, Logger, type LookupAttributeMetadata, type ManyToManyRelationshipMetadata, MetadataCache, MetadataClient, MetadataError, type MoneyAttributeMetadata, type OneToManyRelationshipMetadata, type OptionMetadata, type OptionSetGeneratorOptions, type OptionSetMetadata, type ParsedForm, type PicklistAttributeMetadata, SilentLogSink, type SolutionComponent, type StateAttributeMetadata, type StatusAttributeMetadata, type StringAttributeMetadata, type SystemFormMetadata, TypeGenerationOrchestrator, type XmlElement, type XmlParser, XrmForgeError, configureLogging, createCredential, createLogger, defaultXmlParser, disambiguateEnumMembers, extractControlFields, getJSDocLabel as formatDualLabel, generateActionDeclarations, generateActionModule, generateActivityPartyInterface, generateEntityFieldsEnum, generateEntityForms, generateEntityInterface, generateEntityNamesEnum, generateEntityNavigationProperties, generateEntityOptionSets, generateEnumMembers, generateFormInterface, generateOptionSetEnum, getEntityPropertyType, getFormAttributeType, getFormControlType, getFormMockValueType, getJSDocLabel, getLabelLanguagesParam, getPrimaryLabel, getSecondaryLabel, groupCustomApis, isLookupType, isPartyListType, isRateLimitError, isXrmForgeError, labelToIdentifier, parseForm, shouldIncludeInEntityInterface, toLookupValueProperty, toPascalCase, toSafeIdentifier };
+export { type ActionGeneratorOptions, ApiRequestError, type AttributeMetadata, type AuthConfig, type AuthMethod, AuthenticationError, type CacheStats, type ChangeDetectionResult, ChangeDetector, type CheckFinding, type CheckResult, type ClientCredentialsAuth, ConfigError, ConsoleLogSink, type CustomApiTypeInfo, DEFAULT_LABEL_CONFIG, DataverseHttpClient, type DateTimeAttributeMetadata, type DecimalAttributeMetadata, type DeviceCodeAuth, type EntityFieldsGeneratorOptions, type EntityGenerationResult, type EntityGeneratorOptions, type EntityMetadata, type EntityNamesGeneratorOptions, type EntityTypeInfo, ErrorCode, FastXmlParser, type FormControl, type FormGeneratorOptions, type FormSection, type FormTab, type GenerateConfig, type GeneratedFile, GenerationError, type GenerationResult, type GroupedCustomApis, type HttpClientOptions, type IntegerAttributeMetadata, type InteractiveAuth, JsonLogSink, type Label, type LabelConfig, type LocalizedLabel, type LogEntry, LogLevel, type LogSink, Logger, type LookupAttributeMetadata, type ManyToManyRelationshipMetadata, MetadataCache, MetadataClient, MetadataError, type MoneyAttributeMetadata, type OneToManyRelationshipMetadata, type OptionMetadata, type OptionSetGeneratorOptions, type OptionSetMetadata, type ParsedForm, type PicklistAttributeMetadata, SilentLogSink, type SolutionComponent, type StateAttributeMetadata, type StatusAttributeMetadata, type StringAttributeMetadata, type SystemFormMetadata, TypeGenerationOrchestrator, type XmlElement, type XmlParser, XrmForgeError, configureLogging, createCredential, createLogger, defaultXmlParser, disambiguateEnumMembers, extractControlFields, getJSDocLabel as formatDualLabel, generateActionDeclarations, generateActionModule, generateActivityPartyInterface, generateEntityFieldsEnum, generateEntityForms, generateEntityInterface, generateEntityNamesEnum, generateEntityNavigationProperties, generateEntityOptionSets, generateEnumMembers, generateFormInterface, generateOptionSetEnum, getEntityPropertyType, getFormAttributeType, getFormControlType, getFormMockValueType, getJSDocLabel, getLabelLanguagesParam, getPrimaryLabel, getSecondaryLabel, groupCustomApis, isLookupType, isPartyListType, isRateLimitError, isXrmForgeError, labelToIdentifier, parseForm, shouldIncludeInEntityInterface, toLookupValueProperty, toPascalCase, toSafeIdentifier };

package/dist/index.js

@@ -919,6 +919,9 @@ function extractParameter(controlElement, paramName) {
 var log4 = createLogger("metadata");
 var FORM_TYPE_MAIN = 2;
 var COMPONENT_TYPE_ENTITY = 1;
+function byUniqueName(a, b) {
+  return a.uniquename < b.uniquename ? -1 : a.uniquename > b.uniquename ? 1 : 0;
+}
 var ENTITY_SELECT = "LogicalName,SchemaName,EntitySetName,DisplayName,PrimaryIdAttribute,PrimaryNameAttribute,OwnershipType,IsCustomEntity,LogicalCollectionName,MetadataId";
 var ATTRIBUTE_SELECT = "LogicalName,SchemaName,AttributeType,AttributeTypeName,DisplayName,IsPrimaryId,IsPrimaryName,RequiredLevel,IsValidForRead,IsValidForCreate,IsValidForUpdate,MetadataId";
 var FORM_SELECT = "name,formid,formxml,description,isdefault";
@@ -1183,6 +1186,10 @@ var MetadataClient = class {
    * Queries the customapi, customapirequestparameter, and customapiresponseproperty
    * tables and joins them into CustomApiTypeInfo objects.
    *
+   * APIs, request parameters, and response properties are sorted alphabetically
+   * by uniquename (ordinal) so the result is deterministic regardless of
+   * server row order.
+   *
    * @param solutionFilter - Optional: filter by solution unique name
    * @returns Array of complete Custom API definitions
    */
@@ -1236,10 +1243,11 @@ var MetadataClient = class {
           displayname: api.displayname,
           description: api.description
         },
-        requestParameters: paramsByApi.get(api.customapiid) ?? [],
-        responseProperties: propsByApi.get(api.customapiid) ?? []
+        requestParameters: (paramsByApi.get(api.customapiid) ?? []).sort(byUniqueName),
+        responseProperties: (propsByApi.get(api.customapiid) ?? []).sort(byUniqueName)
       });
     }
+    result.sort((a, b) => byUniqueName(a.api, b.api));
     log4.info(`Loaded ${result.length} Custom APIs with parameters and response properties`);
     return result;
   }
@@ -1859,7 +1867,8 @@ function generateEntityInterface(info, options = {}) {
     if (jsdocParts.length > 0) {
       lines.push(`  /** ${jsdocParts.join(" - ")} */`);
     }
-    lines.push(`  ${propertyName}: ${tsType} | null;`);
+    const nullable = attr.IsPrimaryId ? "" : " | null";
+    lines.push(`  ${propertyName}: ${tsType}${nullable};`);
   }
   if (partyListAttrs.length > 0) {
     const relationship = info.oneToManyRelationships.find(
@@ -2558,7 +2567,7 @@ function groupCustomApis(apis) {
 }
 
 // src/orchestrator/file-writer.ts
-import { mkdir, writeFile, readFile, unlink } from "fs/promises";
+import { mkdir, writeFile, readFile, unlink, readdir, access } from "fs/promises";
 import { join as join2, dirname } from "path";
 async function writeGeneratedFile(outputDir, file) {
   const absolutePath = join2(outputDir, file.relativePath);
@@ -2608,6 +2617,73 @@ async function deleteOrphanedFiles(outputDir, deletedEntityNames) {
   }
   return deleted;
 }
+var GENERATED_SUBDIRS = ["entities", "optionsets", "forms", "fields", "actions", "functions"];
+var GENERATED_ROOT_FILES = ["entity-names.ts", "form-mapping.json", "index.ts"];
+function typeFromRelativePath(relativePath) {
+  if (relativePath.startsWith("optionsets/")) return "optionset";
+  if (relativePath.startsWith("forms/")) return "form";
+  if (relativePath.startsWith("fields/")) return "fields";
+  if (relativePath.startsWith("actions/") || relativePath.startsWith("functions/")) return "action";
+  return "entity";
+}
+async function checkGeneratedFile(outputDir, file) {
+  const absolutePath = join2(outputDir, file.relativePath);
+  try {
+    const existing = await readFile(absolutePath, "utf-8");
+    return existing === file.content ? "unchanged" : "changed";
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return "missing";
+    }
+    throw error;
+  }
+}
+async function findOrphanedFiles(outputDir, expectedPaths) {
+  const orphans = [];
+  for (const subdir of GENERATED_SUBDIRS) {
+    let entries;
+    try {
+      entries = await readdir(join2(outputDir, subdir), { withFileTypes: true });
+    } catch (error) {
+      if (error.code === "ENOENT") continue;
+      throw error;
+    }
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".ts")) continue;
+      const relativePath = `${subdir}/${entry.name}`;
+      if (!expectedPaths.has(relativePath)) {
+        orphans.push(relativePath);
+      }
+    }
+  }
+  for (const rootFile of GENERATED_ROOT_FILES) {
+    if (expectedPaths.has(rootFile)) continue;
+    try {
+      await access(join2(outputDir, rootFile));
+      orphans.push(rootFile);
+    } catch {
+    }
+  }
+  return orphans.sort();
+}
+async function checkAllFiles(outputDir, files) {
+  const findings = [];
+  let unchanged = 0;
+  for (const file of files) {
+    const status = await checkGeneratedFile(outputDir, file);
+    if (status === "unchanged") {
+      unchanged++;
+    } else {
+      findings.push({ relativePath: file.relativePath, type: file.type, status });
+    }
+  }
+  const expectedPaths = new Set(files.map((f) => f.relativePath));
+  const orphans = await findOrphanedFiles(outputDir, expectedPaths);
+  for (const relativePath of orphans) {
+    findings.push({ relativePath, type: typeFromRelativePath(relativePath), status: "orphaned" });
+  }
+  return { drift: findings.length > 0, unchanged, findings };
+}
 var GENERATED_HEADER = `// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 // This file was generated by @xrmforge/typegen. Do not edit manually.
 // Re-run 'xrmforge generate' to update.
@@ -2687,7 +2763,8 @@ var TypeGenerationOrchestrator = class {
       actionsFilter: config.actionsFilter ?? "",
       useCache: config.useCache ?? false,
       cacheDir: config.cacheDir ?? ".xrmforge/cache",
-      namespacePrefix: config.namespacePrefix ?? "XrmForge"
+      namespacePrefix: config.namespacePrefix ?? "XrmForge",
+      checkOnly: config.checkOnly ?? false
     };
   }
   /**
@@ -2706,10 +2783,15 @@ var TypeGenerationOrchestrator = class {
     if (signal?.aborted) {
       return { entities: [], totalFiles: 0, totalWarnings: 0, durationMs: 0 };
     }
-    this.logger.info("Starting type generation", {
+    const checkOnly = this.config.checkOnly;
+    const useCache = this.config.useCache && !checkOnly;
+    if (this.config.useCache && checkOnly) {
+      this.logger.warn("Check mode ignores the metadata cache (drift check must run against live metadata)");
+    }
+    this.logger.info(checkOnly ? "Starting drift check (read-only)" : "Starting type generation", {
       entities: this.config.entities,
       outputDir: this.config.outputDir,
-      useCache: this.config.useCache
+      useCache
     });
     const httpClient = new DataverseHttpClient({
       environmentUrl: this.config.environmentUrl,
@@ -2738,7 +2820,7 @@ var TypeGenerationOrchestrator = class {
     let cache;
     let newVersionStamp = null;
     const deletedEntityNames = [];
-    if (this.config.useCache) {
+    if (useCache) {
       const cacheResult = await this.resolveCache(httpClient, entitiesToFetch);
       cache = cacheResult.cache;
       newVersionStamp = cacheResult.newVersionStamp;
@@ -2837,15 +2919,28 @@ var TypeGenerationOrchestrator = class {
       };
       allFiles.push(indexFile);
     }
-    const writeResult = await writeAllFiles(this.config.outputDir, allFiles);
-    if (deletedEntityNames.length > 0) {
-      const deleted = await deleteOrphanedFiles(this.config.outputDir, deletedEntityNames);
-      if (deleted > 0) {
-        this.logger.info(`Deleted ${deleted} orphaned files for removed entities`);
+    let checkResult;
+    let writeResult = { written: 0, unchanged: 0, warnings: [] };
+    if (checkOnly) {
+      if (failedEntities.size === 0 && !signal?.aborted) {
+        checkResult = await checkAllFiles(this.config.outputDir, allFiles);
+        this.logger.info(
+          checkResult.drift ? `Drift detected: ${checkResult.findings.length} finding(s), ${checkResult.unchanged} files unchanged` : `No drift: ${checkResult.unchanged} files unchanged`
+        );
+      } else {
+        this.logger.warn("Drift check skipped: generation incomplete (fetch failures or abort)");
+      }
+    } else {
+      writeResult = await writeAllFiles(this.config.outputDir, allFiles);
+      if (deletedEntityNames.length > 0) {
+        const deleted = await deleteOrphanedFiles(this.config.outputDir, deletedEntityNames);
+        if (deleted > 0) {
+          this.logger.info(`Deleted ${deleted} orphaned files for removed entities`);
+        }
+      }
+      if (useCache && cache) {
+        await this.updateCache(cache, cachedEntityInfos, deletedEntityNames, newVersionStamp);
       }
-    }
-    if (this.config.useCache && cache) {
-      await this.updateCache(cache, cachedEntityInfos, deletedEntityNames, newVersionStamp);
     }
     const durationMs = Date.now() - startTime;
     const entityWarnings = entityResults.reduce((sum, r) => sum + r.warnings.length, 0);
@@ -2853,7 +2948,7 @@ var TypeGenerationOrchestrator = class {
     for (const w of writeResult.warnings) {
       this.logger.warn(w);
     }
-    this.logger.info("Type generation complete", {
+    this.logger.info(checkOnly ? "Drift check complete" : "Type generation complete", {
       entities: entityResults.length,
       filesWritten: writeResult.written,
       filesUnchanged: writeResult.unchanged,
@@ -2867,7 +2962,8 @@ var TypeGenerationOrchestrator = class {
       totalFiles: allFiles.length,
       totalWarnings,
       durationMs,
-      cacheStats
+      cacheStats,
+      checkResult
     };
   }
   /**