@xrmforge/typegen 0.13.0 → 0.13.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 XrmForge Contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 XrmForge Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# @xrmforge/typegen
+
+[![npm version](https://img.shields.io/npm/v/@xrmforge/typegen.svg)](https://www.npmjs.com/package/@xrmforge/typegen)
+[![license](https://img.shields.io/npm/l/@xrmforge/typegen.svg)](https://github.com/juergenbeck/XrmForge/blob/main/LICENSE)
+
+**The type-generation engine of XrmForge.** Reads Dynamics 365 / Dataverse metadata and generates TypeScript declarations that *extend* `@types/xrm` (never replace it), so your generated types coexist with PCF controls and the rest of the Microsoft ecosystem.
+
+> Most users do not call this package directly -- they use [`@xrmforge/cli`](https://www.npmjs.com/package/@xrmforge/cli) (`xrmforge generate`), which wraps this engine. Install `@xrmforge/typegen` directly only when you want to embed generation in your own Node.js tooling. For the full framework docs, see the [XrmForge repository](https://github.com/juergenbeck/XrmForge#readme).
+
+---
+
+## What it generates
+
+For each entity, typegen emits flat ES modules (`.ts` files) -- one file per concern, imported and processed by your bundler. No `declare namespace`, no ambient `.d.ts`.
+
+```
+generated/
+  entities/account.ts      export interface Account { ... }       // typed Web API response objects
+  fields/account.ts        export const enum AccountFields         // $select / $filter (already _value form)
+                           export const enum AccountNavigationProperties  // parseLookup / $expand / @odata.bind
+  optionsets/account.ts    export const enum IndustryCode ...       // every picklist/status/state field
+  forms/account.ts         Union + maps + Fields enum + Form interface + FormTypeInfo + MockValues
+  actions/quote.ts         export const WinQuote = createBoundAction(...)  // typed Custom API executors
+  entity-names.ts          export const enum EntityNames
+  index.ts                 barrel re-export
+```
+
+Each generated artifact is a compile-time contract:
+
+- **Entity interfaces** -- all attributes correctly typed (string, number, boolean, Lookup, OptionSet, DateTime).
+- **Form interfaces** -- per-form `getAttribute()` / `getControl()` overloads. Only fields actually on the form are valid; no string fallback, no `any`.
+- **OptionSet enums** -- `const enum`, inlined by TypeScript (zero runtime overhead).
+- **Fields / NavigationProperties enums** -- type-safe `$select` and lookup navigation.
+- **Action / Function executors** -- generated from Custom API metadata, with typed parameters and responses.
+- **Dual-language JSDoc** -- `/** Account Name | Firmenname */` when `--secondary-language` is set.
+
+---
+
+## Usage via the CLI (recommended)
+
+```bash
+npm install --save-dev @xrmforge/cli @types/xrm
+npx xrmforge generate --url https://myorg.crm4.dynamics.com --auth interactive \
+  --tenant-id YOUR_TENANT_ID --client-id 51f81489-12ee-4a9e-aaae-a2591f45987d \
+  --entities account,contact --output ./generated
+```
+
+See [`@xrmforge/cli`](https://www.npmjs.com/package/@xrmforge/cli) for every flag, authentication method, incremental caching (`--cache`), and drift detection (`--check`).
+
+---
+
+## Programmatic API
+
+Install directly when embedding generation in your own tooling:
+
+```bash
+npm install @xrmforge/typegen @types/xrm
+```
+
+The high-level entry point is the orchestrator, which runs the full pipeline (authenticate, read metadata, generate, write). It takes a credential and a config:
+
+```typescript
+import { TypeGenerationOrchestrator, createCredential } from '@xrmforge/typegen';
+
+// 1. Build a credential from an auth config
+//    (method: 'interactive' | 'client-credentials' | 'device-code' | 'token')
+const credential = createCredential({
+  method: 'interactive',
+  tenantId: 'YOUR_TENANT_ID',
+  clientId: '51f81489-12ee-4a9e-aaae-a2591f45987d',
+});
+
+// 2. Run the pipeline
+const orchestrator = new TypeGenerationOrchestrator(credential, {
+  environmentUrl: 'https://myorg.crm4.dynamics.com',
+  entities: ['account', 'contact'],
+  outputDir: './generated',
+  labelConfig: { primaryLanguage: 1033, secondaryLanguage: 1031 },
+});
+
+const result = await orchestrator.generate();
+console.log(`Generated ${result.totalFiles} files`);
+```
+
+For finer control, the building blocks are exported individually:
+
+| Area | Exports |
+|------|---------|
+| Orchestration | `TypeGenerationOrchestrator`, types `GenerateConfig`, `GenerationResult`, `CheckResult`, `CheckFinding`, `CacheStats` |
+| Authentication | `createCredential`, types `AuthConfig`, `ClientCredentialsAuth`, `InteractiveAuth`, `DeviceCodeAuth` |
+| HTTP | `DataverseHttpClient` (ReadOnly-default, retry, rate-limit), type `HttpClientOptions` |
+| Metadata | `MetadataClient`, `MetadataCache`, `ChangeDetector`, `parseForm`, plus rich metadata types (`EntityMetadata`, `AttributeMetadata`, `OptionSetMetadata`, `SystemFormMetadata`, ...) |
+| Code generators | `generateEntityInterface`, `generateFormInterface`, `generateOptionSetEnum`, `generateEntityFieldsEnum`, `generateActionModule`, `generateEntityNamesEnum`, ... |
+| Type mapping | `getEntityPropertyType`, `getFormAttributeType`, `toSafeIdentifier`, `toPascalCase`, `isLookupType`, ... |
+| Logging | `Logger`, `ConsoleLogSink`, `JsonLogSink`, `SilentLogSink`, `LogLevel`, `configureLogging` |
+| Errors | `XrmForgeError`, `AuthenticationError`, `ApiRequestError`, `MetadataError`, `GenerationError`, `ConfigError`, `isXrmForgeError`, `isRateLimitError` |
+
+> **Node.js only.** This package pulls in `@azure/identity` and Node APIs. Do **not** import it in browser/form-script code -- use [`@xrmforge/helpers`](https://www.npmjs.com/package/@xrmforge/helpers) for the browser runtime. The `@xrmforge/eslint-plugin` rule `no-typegen-import` enforces this.
+
+---
+
+## Peer dependency
+
+`@types/xrm` (>= 9.0.0) -- the generated types build on top of it.
+
+## Documentation
+
+Full guide and generated-type patterns: [XrmForge on GitHub](https://github.com/juergenbeck/XrmForge#readme).
+
+## License
+
+[MIT](https://github.com/juergenbeck/XrmForge/blob/main/LICENSE) (c) XrmForge Contributors.

package/dist/index.d.ts

@@ -1331,6 +1331,25 @@ declare function generateEntityOptionSets(picklistAttributes: Array<{
  * ```
  */
 
+/**
+ * Machine-readable metadata for one generated form, surfaced in form-mapping.json
+ * so AI agents can pick the right form by its fields without parsing the generated
+ * code (F-MAR7-04).
+ */
+interface FormGenerationMeta {
+    /** Form display name (from FormXml) */
+    formName: string;
+    /** Generated interface name (e.g. AccountForm) */
+    interfaceName: string;
+    /** Generated Fields enum name (e.g. AccountFormFieldsEnum) */
+    fieldsEnumName: string;
+    /** Generated Tabs enum name, or '' if the form has no named tabs */
+    tabsEnumName: string;
+    /** Sorted logical names of the attributes this form binds to */
+    fields: string[];
+    /** True for a Main form (systemform_type 2), false for Quick Create etc. */
+    isMain: boolean;
+}
 /** Options for form interface generation */
 interface FormGeneratorOptions {
     /** Label configuration for dual-language JSDoc comments */
@@ -1357,9 +1376,7 @@ declare function generateFormInterface(form: ParsedForm, entityLogicalName: stri
  * @param options - Generator options
  * @returns Array of { formName, interfaceName, content }
  */
-declare function generateEntityForms(forms: ParsedForm[], entityLogicalName: string, attributes: AttributeMetadata[], options?: FormGeneratorOptions): Array<{
-    formName: string;
-    interfaceName: string;
+declare function generateEntityForms(forms: ParsedForm[], entityLogicalName: string, attributes: AttributeMetadata[], options?: FormGeneratorOptions): Array<FormGenerationMeta & {
     content: string;
 }>;
 
@@ -1566,6 +1583,8 @@ interface EntityGenerationResult {
     files: GeneratedFile[];
     /** Warnings (e.g. missing labels, empty forms) */
     warnings: string[];
+    /** Per-form metadata for this entity (drives form-mapping.json, F-MAR7-04) */
+    formMeta: FormGenerationMeta[];
 }
 /** A single generated file */
 interface GeneratedFile {
@@ -1699,10 +1718,13 @@ declare class TypeGenerationOrchestrator {
      */
     private getPicklistAttributes;
     /**
-     * Generate a form-mapping.json that maps entity names to their generated
-     * form interface names, fields enums, and tabs enums.
+     * Generate a form-mapping.json that maps each entity to its generated forms:
+     * interface name, Fields/Tabs enum names, a main-form marker (isMain), and the
+     * list of fields each form binds to. This lets AI agents pick the right form by
+     * its fields without guessing interface names.
      *
-     * This helps AI agents find the correct interface names without guessing.
+     * Built from the structured per-form metadata collected during generation
+     * (F-MAR7-04), not by parsing the generated code.
      */
     private generateFormMapping;
 }

package/dist/index.js

@@ -1954,6 +1954,7 @@ function singleQuoted(value) {
 
 // src/generators/form-generator.ts
 var FORM_TYPE_QUICK_CREATE2 = 7;
+var FORM_TYPE_MAIN2 = 2;
 function specialControlToXrmType(controlType) {
   switch (controlType) {
     case "subgrid":
@@ -1996,14 +1997,7 @@ function labelToPascalMember(label) {
   if (/^\d/.test(pascal)) return `_${pascal}`;
   return pascal;
 }
-function generateFormInterface(form, entityLogicalName, attributeMap, options = {}, baseNameOverride) {
-  const labelConfig = options.labelConfig || DEFAULT_LABEL_CONFIG;
-  const entityPascal = toPascalCase(entityLogicalName);
-  const baseName = baseNameOverride || buildFormBaseName(entityPascal, toSafeFormName(form.name));
-  const interfaceName = `${baseName}Form`;
-  const fieldsTypeName = `${baseName}FormFields`;
-  const attrMapName = `${baseName}FormAttributeMap`;
-  const ctrlMapName = `${baseName}FormControlMap`;
+function collectFormFieldNames(form, attributeMap) {
   const fieldNames = /* @__PURE__ */ new Set();
   for (const control of form.allControls) {
     if (control.datafieldname) {
@@ -2015,9 +2009,20 @@ function generateFormInterface(form, entityLogicalName, attributeMap, options =
       fieldNames.add(systemField);
     }
   }
+  return [...fieldNames].sort();
+}
+function generateFormInterface(form, entityLogicalName, attributeMap, options = {}, baseNameOverride) {
+  const labelConfig = options.labelConfig || DEFAULT_LABEL_CONFIG;
+  const entityPascal = toPascalCase(entityLogicalName);
+  const baseName = baseNameOverride || buildFormBaseName(entityPascal, toSafeFormName(form.name));
+  const interfaceName = `${baseName}Form`;
+  const fieldsTypeName = `${baseName}FormFields`;
+  const attrMapName = `${baseName}FormAttributeMap`;
+  const ctrlMapName = `${baseName}FormControlMap`;
+  const sortedFieldNames = collectFormFieldNames(form, attributeMap);
   const fields = [];
   const usedEnumNames = /* @__PURE__ */ new Set();
-  for (const fieldName of [...fieldNames].sort()) {
+  for (const fieldName of sortedFieldNames) {
     const attr = attributeMap.get(fieldName);
     if (!attr) continue;
     const primaryLabel = getPrimaryLabel(attr.DisplayName, labelConfig);
@@ -2211,7 +2216,7 @@ function generateFormInterface(form, entityLogicalName, attributeMap, options =
         const sectionNames = tab.sections.filter((s) => s.name).map((s) => s.name);
         if (sectionNames.length > 0) {
           lines.push(`      get(name: "${tab.name}"): Xrm.Controls.Tab & {`);
-          lines.push("        sections: {");
+          lines.push("        sections: Xrm.Collection.ItemCollection<Xrm.Controls.Section> & {");
           for (const sectionName of sectionNames) {
             lines.push(`          get(name: "${sectionName}"): Xrm.Controls.Section;`);
           }
@@ -2277,7 +2282,16 @@ function generateEntityForms(forms, entityLogicalName, attributes, options = {})
     }
     const interfaceName = `${baseName}Form`;
     const content = generateFormInterface(form, entityLogicalName, attributeMap, options, baseName);
-    results.push({ formName: form.name, interfaceName, content });
+    const hasNamedTabs = form.tabs.some((t) => t.name);
+    results.push({
+      formName: form.name,
+      interfaceName,
+      fieldsEnumName: `${baseName}FormFieldsEnum`,
+      tabsEnumName: hasNamedTabs ? `${baseName}FormTabs` : "",
+      fields: collectFormFieldNames(form, attributeMap),
+      isMain: form.type === FORM_TYPE_MAIN2,
+      content
+    });
   }
   return results;
 }
@@ -2753,9 +2767,9 @@ function generateBarrelIndex(files) {
     lines.push("");
   }
   if (actions.length > 0) {
-    lines.push("// Custom API Actions & Functions");
+    lines.push("// Custom API Actions & Functions - import directly from individual files to avoid name conflicts:");
     for (const f of actions) {
-      lines.push(`export * from '${toImportSpecifier(f.relativePath)}';`);
+      lines.push(`//   import { ... } from '${toImportSpecifier(f.relativePath)}';`);
     }
     lines.push("");
   }
@@ -2898,7 +2912,8 @@ var TypeGenerationOrchestrator = class {
         entityResults.push({
           entityLogicalName: entityName,
           files: [],
-          warnings: [`Failed to process: ${failedEntities.get(entityName)}`]
+          warnings: [`Failed to process: ${failedEntities.get(entityName)}`],
+          formMeta: []
         });
         continue;
       }
@@ -2921,9 +2936,9 @@ var TypeGenerationOrchestrator = class {
         type: "entity"
       });
     }
-    const formFiles = allFiles.filter((f) => f.type === "form");
-    if (formFiles.length > 0) {
-      const formMapping = this.generateFormMapping(formFiles);
+    const entityFormMeta = entityResults.filter((r) => r.formMeta.length > 0).map((r) => ({ entityName: r.entityLogicalName, forms: r.formMeta }));
+    if (entityFormMeta.length > 0) {
+      const formMapping = this.generateFormMapping(entityFormMeta);
       allFiles.push({
         relativePath: "form-mapping.json",
         content: JSON.stringify(formMapping, null, 2) + "\n",
@@ -3098,6 +3113,7 @@ var TypeGenerationOrchestrator = class {
   generateEntityFiles(entityName, entityInfo) {
     const warnings = [];
     const files = [];
+    const formMeta = [];
     if (this.config.generateEntities) {
       const entityContent = generateEntityInterface(entityInfo, {
         labelConfig: this.config.labelConfig
@@ -3143,6 +3159,9 @@ var TypeGenerationOrchestrator = class {
             content: addGeneratedHeader(combinedContent),
             type: "form"
           });
+          for (const { content: _content, ...meta } of formResults) {
+            formMeta.push(meta);
+          }
         }
       } else {
         warnings.push(`No forms found for ${entityName}`);
@@ -3163,7 +3182,7 @@ ${navPropsContent}` : fieldsEnumContent;
         type: "fields"
       });
     }
-    return { entityLogicalName: entityName, files, warnings };
+    return { entityLogicalName: entityName, files, warnings, formMeta };
   }
   /**
    * Generate Custom API Action/Function executor files.
@@ -3233,35 +3252,26 @@ ${navPropsContent}` : fieldsEnumContent;
     return result;
   }
   /**
-   * Generate a form-mapping.json that maps entity names to their generated
-   * form interface names, fields enums, and tabs enums.
+   * Generate a form-mapping.json that maps each entity to its generated forms:
+   * interface name, Fields/Tabs enum names, a main-form marker (isMain), and the
+   * list of fields each form binds to. This lets AI agents pick the right form by
+   * its fields without guessing interface names.
    *
-   * This helps AI agents find the correct interface names without guessing.
+   * Built from the structured per-form metadata collected during generation
+   * (F-MAR7-04), not by parsing the generated code.
    */
-  generateFormMapping(formFiles) {
+  generateFormMapping(entityForms) {
     const mapping = {};
-    for (const file of formFiles) {
-      const match = file.relativePath.match(/^forms\/(.+)\.ts$/);
-      if (!match) continue;
-      const entityName = match[1];
-      const interfaces = [...file.content.matchAll(/export\s+interface\s+(\w+Form)\s+extends/g)].map((m) => m[1]);
-      const fieldsEnums = [...file.content.matchAll(/export\s+const\s+enum\s+(\w+FormFieldsEnum)\s*\{/g)].map((m) => m[1]);
-      const tabsEnums = [...file.content.matchAll(/export\s+const\s+enum\s+(\w+FormTabs)\s*\{/g)].map((m) => m[1]);
-      const forms = [];
-      for (let i = 0; i < interfaces.length; i++) {
-        const interfaceName = interfaces[i];
-        const jsdocMatch = file.content.match(new RegExp(`/\\*\\*\\s*(.+?)\\s*\\*/\\s*export\\s+interface\\s+${interfaceName}`));
-        const formName = jsdocMatch?.[1] ?? interfaceName.replace(/Form$/, "");
-        forms.push({
-          formName,
-          interface: interfaceName,
-          fieldsEnum: fieldsEnums[i] ?? "",
-          tabsEnum: tabsEnums[i] ?? ""
-        });
-      }
-      if (forms.length > 0) {
-        mapping[entityName] = forms;
-      }
+    for (const { entityName, forms } of entityForms) {
+      if (forms.length === 0) continue;
+      mapping[entityName] = forms.map((f) => ({
+        formName: f.formName,
+        interface: f.interfaceName,
+        fieldsEnum: f.fieldsEnumName,
+        tabsEnum: f.tabsEnumName,
+        isMain: f.isMain,
+        fields: f.fields
+      }));
     }
     return mapping;
   }