@xrmforge/typegen 0.7.0 → 0.7.1

package/docs/architecture/00-README.md

@@ -0,0 +1,26 @@
+# XrmForge Architecture
+
+> **Status:** Living document describing the current implementation state.
+> **Last updated:** 2026-04-04 (Session 10)
+> **Version:** 7 packages, 666+ tests across all packages.
+
+## Chapters
+
+1. [Executive Summary](01-executive-summary.md)
+2. [Package Architecture](02-packages.md)
+3. [Generated Types](03-generated-types.md)
+4. [CLI Commands](04-cli.md)
+5. [Build Architecture](05-build.md)
+6. [Incremental Generation](06-incremental.md)
+7. [HTTP Client](07-http-client.md)
+8. [Authentication](08-authentication.md)
+9. [Testing Framework](09-testing.md)
+10. [ESLint Plugin](10-eslint-plugin.md)
+11. [AGENT.md System](11-agent-md.md)
+12. [@types/xrm Pitfalls](12-xrm-pitfalls.md)
+13. [@xrmforge/helpers Package](13-helpers.md)
+14. [Showcases](14-showcases.md)
+15. [CI/CD](15-ci-cd.md)
+16. [Technical Debt](16-technical-debt.md)
+17. [Roadmap](17-roadmap.md)
+18. [Design Principles](18-design-principles.md)

package/docs/architecture/01-executive-summary.md

@@ -0,0 +1,11 @@
+# Executive Summary
+
+XrmForge is an open-source TypeScript toolkit for type-safe Dynamics 365 / Dataverse WebResource development. It generates TypeScript declarations from live Dataverse metadata, turning runtime string errors into compile-time type errors.
+
+**Core value proposition:** Every field name, OptionSet value, tab name, entity name, and subgrid name becomes a typed constant with IDE autocomplete and compile-time validation.
+
+**Target audience:** D365 developers who write form scripts (WebResources) in JavaScript/TypeScript and want compile-time safety, zero magic strings, and modern tooling (esbuild, vitest, ESLint).
+
+**Tech stack:** TypeScript, pnpm monorepo with Turborepo, esbuild for IIFE bundles, vitest for testing, @azure/identity for authentication, fast-xml-parser for FormXml parsing.
+
+**npm organization:** [@xrmforge](https://www.npmjs.com/org/xrmforge)

package/docs/architecture/02-packages.md

@@ -0,0 +1,110 @@
+# Package Architecture
+
+## Package Overview
+
+| Package | Version | Tests | Description |
+|---------|---------|-------|-------------|
+| @xrmforge/typegen | 0.6.0 | 444 | Core: type generation engine, metadata client, HTTP client, helpers |
+| @xrmforge/cli | 0.4.2 | 10 | CLI: generate, build, init commands |
+| @xrmforge/testing | 0.2.0 | 76 | Test utilities: createFormMock, fireOnChange, setupXrmMock |
+| @xrmforge/helpers | 0.1.0 | 59 | Browser-safe runtime: select(), parseLookup(), typedForm(), Xrm constants, Action executors |
+| @xrmforge/webapi | 0.1.0 | 45 | Type-safe Xrm.WebApi client with QueryBuilder |
+| @xrmforge/devkit | 0.4.0 | 42 | Build orchestration, scaffolding, AGENT.md generation |
+| @xrmforge/eslint-plugin | 0.2.0 | 32 | 5 D365-specific ESLint rules |
+
+**Total:** 708 tests across 7 packages.
+
+## Dependency Graph
+
+```
+@xrmforge/cli
+  |-- @xrmforge/typegen (generate command)
+  |-- @xrmforge/devkit  (build + init commands)
+  '-- commander (CLI framework)
+
+@xrmforge/typegen
+  |-- @azure/identity  (authentication)
+  '-- fast-xml-parser  (FormXml parsing)
+
+@xrmforge/devkit
+  '-- esbuild (IIFE bundling)
+
+@xrmforge/testing     (no runtime deps)
+@xrmforge/helpers     (no runtime deps)
+@xrmforge/webapi      (no runtime deps)
+@xrmforge/eslint-plugin (ESLint peer dep)
+```
+
+## Package Details
+
+### @xrmforge/typegen
+
+The core package. Contains:
+
+- **TypeGenerationOrchestrator** - Coordinates the entire generation pipeline
+- **MetadataClient** - Queries Dataverse metadata (entities, forms, OptionSets, Custom APIs)
+- **DataverseHttpClient** - Resilient REST client with retry, rate limiting, concurrency control
+- **ChangeDetector** - Incremental generation via RetrieveMetadataChanges
+- **MetadataCache** - Filesystem-based caching with version stamps
+- **Generators** - Entity interfaces, form interfaces, OptionSet enums, Fields enums, EntityNames, Navigation Properties, Action/Function executors
+- **Helpers** - select(), parseLookup(), parseFormattedValue() (moved to @xrmforge/helpers)
+- **Xrm Constants** - DisplayState, FormNotificationLevel, RequiredLevel, SubmitMode, SaveMode, ClientType, ClientState (moved to @xrmforge/helpers)
+- **Authentication** - createCredential() factory for 4 auth methods
+- **Logging** - Scoped loggers with pluggable sinks (Console, JSON, Silent)
+- **Errors** - Structured error hierarchy with ErrorCode enum (AUTH_1xxx, API_2xxx, META_3xxx, GEN_4xxx, CONFIG_5xxx)
+
+### @xrmforge/cli
+
+Command-line interface built with commander.js. Three commands:
+- `xrmforge generate` - Orchestrates TypeGenerationOrchestrator
+- `xrmforge build` - Delegates to devkit build()
+- `xrmforge init` - Delegates to devkit scaffoldProject()
+
+### @xrmforge/testing
+
+FormContext mocking for unit tests:
+- `createFormMock<TForm>(values)` - Creates a complete mock from simple key-value pairs
+- `MockAttribute` - getValue/setValue, dirty tracking, onChange handlers, required level, submit mode
+- `MockControl` - visible, disabled, label, notifications
+- `MockUi` - Form notifications, tab/section stubs
+- `MockEntity` - Entity ID, name, primary attribute
+- `fireOnChange(fieldName)` - Triggers registered onChange handlers
+- `setupXrmMock(options)` / `teardownXrmMock()` - Global Xrm mock with WebApi/Navigation stubs
+
+### @xrmforge/helpers
+
+Consolidates all browser-safe runtime code. Zero Node.js dependencies. Contains:
+- **Web API helpers** - select(), parseLookup(), parseFormattedValue()
+- **Xrm constants** - DisplayState, SubmitMode, RequiredLevel, SaveMode, ClientType, ClientState, FormNotificationLevel, OperationType
+- **Action/Function executors** - createBoundAction(), executeRequest(), withProgress()
+- **typedForm() proxy** - Proxy-based FormContext wrapper where `form.name` delegates to `getAttribute('name')`
+
+### @xrmforge/webapi
+
+Type-safe wrapper around Xrm.WebApi:
+- `retrieve<T>(entityName, id, query)` - Single record
+- `retrieveMultiple<T>(entityName, query, options)` - With pagination (maxPages)
+- `create(entityName, data)` - Returns record ID
+- `update(entityName, id, data)` - Void
+- `remove(entityName, id)` - Void
+- `QueryBuilder` - Fluent API: `.select().filter().orderBy().top().expand().build()`
+- `WebApiError` - Structured errors with statusCode, errorCode, innerMessage
+
+### @xrmforge/devkit
+
+Build orchestration and project scaffolding:
+- `build(config)` - Parallel esbuild IIFE builds via Promise.allSettled
+- `watch(config)` - esbuild watch mode with rebuild callbacks
+- `scaffoldProject(config)` - Generates 11 project files from templates
+- `validateBuildConfig(config)` / `resolveBuildConfig(config)` - Config validation
+- `BuildError` with codes: CONFIG_INVALID, ENTRY_NOT_FOUND, BUILD_FAILED, WATCH_ERROR
+- Template system: 7 text templates in `src/scaffold/templates/`, loaded via `template-loader.ts`
+
+### @xrmforge/eslint-plugin
+
+5 rules for D365 form scripts (ESLint v9 flat config):
+- `no-xrm-page` (error) - Forbids deprecated Xrm.Page API
+- `no-magic-optionset` (warn) - Forbids magic numbers in OptionSet comparisons
+- `no-sync-webapi` (error) - Forbids synchronous XMLHttpRequest
+- `require-error-handling` (warn) - Requires try/catch in async on* event handlers
+- `require-namespace` (warn) - Forbids window/globalThis assignments

package/docs/architecture/03-generated-types.md

@@ -0,0 +1,176 @@
+# Generated Types
+
+Running `xrmforge generate` produces the following TypeScript declarations:
+
+### 3.1 Entity Interfaces (`entities/{entity}.d.ts`)
+
+```typescript
+declare namespace XrmForge.Entities {
+  /** Account | Konto */
+  interface Account {
+    /** Account Name | Kontoname */
+    name: string | null;
+    accountid: string | null;
+    revenue: number | null;
+    _parentaccountid_value: string | null;  // Lookup GUID
+    // ...
+  }
+}
+```
+
+**Type mapping:** String/Memo/EntityName to `string`, Integer/BigInt/Decimal/Double/Money to `number`, Boolean to `boolean`, DateTime/Uniqueidentifier/Lookup to `string`, Picklist/State/Status to `number`.
+
+### 3.2 Entity Fields Enums (`entities/{entity}.d.ts`)
+
+```typescript
+declare namespace XrmForge.Entities {
+  const enum AccountFields {
+    /** Account Name | Kontoname */
+    Name = 'name',
+    Revenue = 'revenue',
+    // all readable attributes
+  }
+}
+```
+
+Used for Web API `$select`: `select(AccountFields.Name, AccountFields.Revenue)`.
+
+### 3.3 Navigation Properties (`entities/{entity}.d.ts`)
+
+```typescript
+declare namespace XrmForge.Entities {
+  const enum AccountNavigation {
+    PrimaryContactId = 'primarycontactid',
+    ContactCustomerAccounts = 'contact_customer_accounts',
+    // OneToMany + ManyToMany relationships
+  }
+}
+```
+
+### 3.4 Form Interfaces (`forms/{entity}.d.ts`)
+
+```typescript
+declare namespace XrmForge.Forms.Account {
+  // Union type restricting valid field names
+  type AccountMainFormFields = 'name' | 'telephone1' | 'revenue';
+
+  // Mapped type: field name to Xrm attribute type
+  type AccountMainFormAttributeMap = {
+    name: Xrm.Attributes.StringAttribute;
+    telephone1: Xrm.Attributes.StringAttribute;
+    revenue: Xrm.Attributes.NumberAttribute;
+  };
+
+  // Mapped type: field name to Xrm control type
+  type AccountMainFormControlMap = {
+    name: Xrm.Controls.StringControl;
+    telephone1: Xrm.Controls.StringControl;
+    revenue: Xrm.Controls.NumberControl;
+  };
+
+  // Fields enum for autocomplete
+  const enum AccountMainFormFieldsEnum {
+    /** Account Name | Kontoname */
+    AccountName = 'name',
+    Telephone1 = 'telephone1',
+    Revenue = 'revenue',
+  }
+
+  // Type-safe FormContext with overloaded getAttribute/getControl
+  interface AccountMainForm extends Omit<Xrm.FormContext, 'getAttribute' | 'getControl'> {
+    getAttribute<K extends AccountMainFormFields>(name: K): AccountMainFormAttributeMap[K];
+    getAttribute(index: number): Xrm.Attributes.Attribute;
+    getAttribute(): Xrm.Attributes.Attribute[];
+
+    getControl<K extends AccountMainFormFields>(name: K): AccountMainFormControlMap[K];
+    getControl(index: number): Xrm.Controls.Control;
+    getControl(): Xrm.Controls.Control[];
+  }
+}
+```
+
+**Special controls** are typed based on their FormXml ClassID:
+- Subgrid: `Xrm.Controls.GridControl`
+- Editable Grid: `Xrm.Controls.GridControl`
+- Quick View: `Xrm.Controls.QuickFormControl`
+- Web Resource / iFrame: `Xrm.Controls.IframeControl`
+
+### 3.5 Tabs/Sections/Subgrids/QuickViews Enums
+
+```typescript
+const enum AccountMainFormTabs { Summary = 'SUMMARY_TAB', Details = 'DETAILS_TAB' }
+const enum AccountMainFormSections { General = 'GENERAL', Address = 'ADDRESS' }
+const enum AccountMainFormSubgrids { Contacts = 'Contacts_Subgrid' }
+const enum AccountMainFormQuickViews { ContactPreview = 'ContactQuickView' }
+```
+
+### 3.6 OptionSet Enums (`optionsets/{entity}.d.ts`)
+
+```typescript
+declare namespace XrmForge.OptionSets.Account {
+  /** Account Category Code | Kontokategoriecode */
+  const enum AccountCategoryCode {
+    /** Preferred Customer | Bevorzugter Kunde */
+    PreferredCustomer = 1,
+    Standard = 2,
+  }
+}
+```
+
+Includes Picklist, Status, State, and MultiSelectPicklist attributes. Duplicate labels are disambiguated with `_{Value}` suffix.
+
+### 3.7 EntityNames Enum (`entity-names.d.ts`)
+
+```typescript
+declare namespace XrmForge {
+  const enum EntityNames {
+    Account = 'account',
+    Contact = 'contact',
+    // all entities in scope
+  }
+}
+```
+
+### 3.8 MockValues Types (in form interfaces)
+
+```typescript
+type AccountMainFormMockValues = {
+  name?: string | null;
+  telephone1?: string | null;
+  revenue?: number | null;
+};
+```
+
+Used with `createFormMock<AccountMainForm, AccountMainFormMockValues>({ name: 'Test' })`.
+
+### 3.9 Action/Function Executors (`actions/{entity|global}.d.ts` + `.ts`)
+
+**Declaration (.d.ts):**
+```typescript
+declare namespace XrmForge.Actions {
+  interface NormalizePhoneParams { Input: string; AllowSuspicious?: boolean; }
+  interface NormalizePhoneResult { Normalized: string; Status: number; }
+}
+```
+
+**Runtime module (.ts):**
+```typescript
+import { createUnboundAction } from '@xrmforge/typegen';
+export const NormalizePhone = createUnboundAction<NormalizePhoneParams, NormalizePhoneResult>(
+  'markant_NormalizePhone',
+  { Input: { typeName: 'String', structuralProperty: 1 } }
+);
+// Usage: const result = await NormalizePhone.execute({ Input: '123' });
+```
+
+Factory functions: `createBoundAction`, `createUnboundAction`, `createBoundFunction`, `createUnboundFunction`. Batch execution via `executeMultiple()`, progress UI via `withProgress()`.
+
+### 3.10 Dual-Language Labels
+
+All generated JSDoc comments support dual-language labels:
+```typescript
+/** Account Name | Kontoname */
+Name = 'name',
+```
+
+German umlauts are transliterated in identifiers: ae, oe, ue, ss (e.g. "Ubergeordnet" becomes `Uebergeordnet`).

package/docs/architecture/04-cli.md

@@ -0,0 +1,58 @@
+# CLI Commands
+
+### 4.1 `xrmforge generate`
+
+Generates TypeScript declarations from a Dataverse environment.
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--url <url>` | string | required | Dataverse environment URL |
+| `--auth <method>` | string | required | Auth method: client-credentials, interactive, device-code, token |
+| `--tenant-id <id>` | string | varies | Azure AD tenant ID |
+| `--client-id <id>` | string | varies | Azure AD application ID |
+| `--client-secret <s>` | string | varies | Client secret (client-credentials only) |
+| `--token <token>` | string | varies | Pre-acquired bearer token (token auth only) |
+| `--entities <list>` | string | - | Comma-separated entity logical names |
+| `--solutions <list>` | string | - | Comma-separated solution unique names |
+| `--output <dir>` | string | ./typings | Output directory |
+| `--label-language <n>` | string | 1033 | Primary label language (LCID) |
+| `--secondary-language <n>` | string | - | Secondary label language for JSDoc |
+| `--no-forms` | flag | - | Skip form interface generation |
+| `--no-optionsets` | flag | - | Skip OptionSet enum generation |
+| `--actions` | flag | false | Generate Custom API executors |
+| `--actions-filter <prefix>` | string | - | Filter Custom APIs by uniquename prefix |
+| `--cache` | flag | false | Enable metadata caching for incremental generation |
+| `--no-cache` | flag | - | Force full metadata refresh |
+| `--cache-dir <dir>` | string | .xrmforge/cache | Cache directory |
+| `-v, --verbose` | flag | false | Debug logging |
+
+At least one of `--entities` or `--solutions` is required.
+
+### 4.2 `xrmforge build`
+
+Builds WebResources as IIFE bundles using esbuild (via @xrmforge/devkit).
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--watch` | flag | false | Watch mode with incremental rebuilds |
+| `--minify` | flag | from config | Override minification setting |
+| `--no-sourcemap` | flag | - | Disable source maps |
+| `--out-dir <dir>` | string | from config | Override output directory |
+| `-v, --verbose` | flag | false | Show error stacks |
+
+Reads configuration from `xrmforge.config.json`.
+
+### 4.3 `xrmforge init`
+
+Scaffolds a new D365 form scripting project.
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `[dir]` | positional | . | Target directory |
+| `--name <name>` | string | dir name | Project name for package.json |
+| `--prefix <prefix>` | string | contoso | Publisher prefix |
+| `--namespace <ns>` | string | PascalCase(prefix) | Base namespace for scripts |
+| `--skip-install` | flag | false | Skip npm install |
+| `--force` | flag | false | Allow non-empty directories |
+
+Generates 11 files: package.json, tsconfig.json, xrmforge.config.json, vitest.config.ts, .gitignore, AGENT.md, example-form.ts, example-form.test.ts, typings/.gitkeep, GitHub Actions CI, Azure DevOps Pipeline.

package/docs/architecture/05-build.md

@@ -0,0 +1,50 @@
+# Build Architecture
+
+### 5.1 esbuild IIFE Bundles
+
+XrmForge uses esbuild to create IIFE (Immediately Invoked Function Expression) bundles for Dynamics 365. D365 requires scripts to be registered as namespace.function (e.g. `Contoso.Account.onLoad`).
+
+**esbuild configuration per entry:**
+```
+format: 'iife'
+bundle: true
+globalName: entry.namespace    // e.g. 'Contoso.Account'
+target: config.target          // default: 'es2020'
+minify: config.minify
+sourcemap: config.sourcemap
+external: config.external      // e.g. ['fs', 'path'] for Node.js deps
+```
+
+All entries are built in parallel using `Promise.allSettled()`, allowing partial success.
+
+### 5.2 xrmforge.config.json Schema
+
+```json
+{
+  "build": {
+    "outDir": "./dist/prefix_/JS",
+    "target": "es2020",
+    "sourcemap": true,
+    "minify": true,
+    "external": [],
+    "entries": {
+      "entry_name": {
+        "input": "./src/forms/account-form.ts",
+        "namespace": "Contoso.Account",
+        "out": "Account/OnLoad.js"
+      }
+    }
+  }
+}
+```
+
+### 5.3 globalName Handling
+
+esbuild automatically creates nested globals from dotted namespaces:
+```javascript
+// namespace: "Contoso.Account" produces:
+var Contoso = Contoso || {};
+Contoso.Account = (() => { return { onLoad, onSave }; })();
+```
+
+D365 event registration: `Contoso.Account.onLoad`.

package/docs/architecture/06-incremental.md

@@ -0,0 +1,42 @@
+# Incremental Generation
+
+### 6.1 Overview
+
+Incremental generation uses the Dataverse `RetrieveMetadataChanges` function to detect which entities have changed since the last generation. This reduces generation time from seconds to milliseconds (measured: 4720ms to 473ms, 10x improvement).
+
+### 6.2 Components
+
+**ChangeDetector** (`src/metadata/change-detector.ts`):
+- `getInitialVersionStamp()` - First run: fetches the initial ServerVersionStamp
+- `detectChanges(clientVersionStamp)` - Subsequent runs: returns changedEntityNames, deletedEntityNames, newVersionStamp
+
+**MetadataCache** (`src/metadata/cache.ts`):
+- Filesystem-based: `.xrmforge/cache/metadata.json`
+- Stores: manifest (version, environment URL, ServerVersionStamp, last refreshed, entity list) + entityTypeInfos per entity
+- Validation: checks cache version, environment URL match, file existence
+
+### 6.3 Flow
+
+```
+First run (no cache):
+  1. Fetch all entity metadata
+  2. getInitialVersionStamp()
+  3. Save cache with ServerVersionStamp
+
+Subsequent run (cache exists):
+  1. Load cache, validate environment URL
+  2. detectChanges(cachedVersionStamp)
+  3. Fetch only changed entities
+  4. Remove deleted entities from cache
+  5. Save cache with new ServerVersionStamp
+
+Expired stamp (>90 days):
+  Error code 0x80044352 detected
+  Fall back to full refresh
+```
+
+### 6.4 RetrieveMetadataChanges API
+
+- **Type:** OData Function (GET, not POST)
+- **URL:** `/RetrieveMetadataChanges(Query=@q,ClientVersionStamp=@s)?@q={...}&@s='...'`
+- **Response:** EntityMetadata[] with HasChanged flag, ServerVersionStamp, DeletedMetadata

package/docs/architecture/07-http-client.md

@@ -0,0 +1,59 @@
+# HTTP Client
+
+### 7.1 DataverseHttpClient
+
+The core HTTP client (`src/http/client.ts`) provides resilient communication with the Dataverse Web API.
+
+**Key methods:**
+- `get<T>(path, signal?)` - Single GET request with retry
+- `getAll<T>(path, signal?)` - GET with automatic @odata.nextLink paging (max 100 pages)
+
+### 7.2 Read-Only Default
+
+The client defaults to `readOnly: true`, blocking POST/PATCH/PUT/DELETE requests. This prevents accidental data mutations during type generation. Write access requires explicit `readOnly: false`.
+
+### 7.3 Retry with Exponential Backoff
+
+- **Base delay:** 1000ms (configurable)
+- **Max backoff:** 60 seconds
+- **Jitter:** Random delay up to base delay
+- **Formula:** `min(baseDelay * 2^(attempt-1) + jitter, 60000)`
+- **Max retries:** configurable (default: 3)
+
+### 7.4 Rate Limiting (HTTP 429)
+
+- **Separate counter** from standard retries (not mixed)
+- **Retry-After header** respected (seconds converted to milliseconds)
+- **Max 10 consecutive 429 retries** (DEFAULT_MAX_RATE_LIMIT_RETRIES)
+- 429 responses do NOT increment the standard retry counter
+
+### 7.5 Concurrency Control
+
+Non-recursive semaphore pattern:
+- **maxConcurrency:** 5 (default)
+- Wait queue with FIFO ordering
+- All retries happen inside a single slot (prevents slot exhaustion)
+
+### 7.6 Token Caching
+
+- In-memory only (never persisted to disk)
+- 5-minute buffer before expiry (TOKEN_BUFFER_MS = 300000)
+- Pending token refresh promise prevents concurrent token requests
+
+### 7.7 Input Sanitization
+
+OData injection prevention:
+- `sanitizeIdentifier()` - Regex `[a-zA-Z_][a-zA-Z0-9_]*`
+- `sanitizeGuid()` - GUID format validation
+- `escapeODataString()` - Single quote doubling
+
+### 7.8 Error Handling
+
+| HTTP Status | Behavior | Retried |
+|-------------|----------|---------|
+| 2xx | Success | No |
+| 401 | Clear token cache, retry once | Yes (1x) |
+| 429 | Respect Retry-After, separate counter | Yes (up to 10x) |
+| 5xx | Exponential backoff | Yes (up to maxRetries) |
+| 404, 403 | Non-retryable | No |
+| Network error | Exponential backoff | Yes |

package/docs/architecture/08-authentication.md

@@ -0,0 +1,18 @@
+# Authentication
+
+### 8.1 Credential Factory
+
+`createCredential(config: AuthConfig)` returns a `TokenCredential` (from @azure/identity) based on the auth method:
+
+### 8.2 Four Auth Flows
+
+| Method | Config | @azure/identity Class | Use Case |
+|--------|--------|-----------------------|----------|
+| client-credentials | tenantId, clientId, clientSecret | ClientSecretCredential | CI/CD, automated pipelines |
+| interactive | tenantId, clientId? | InteractiveBrowserCredential | Developer workstation |
+| device-code | tenantId, clientId? | DeviceCodeCredential | Headless CLI environments |
+| token | token (string) | StaticTokenCredential | Pre-acquired tokens (e.g. from TokenVault) |
+
+### 8.3 Token Scope
+
+All auth flows request the scope: `{environmentUrl}/.default`

package/docs/architecture/09-testing.md

@@ -0,0 +1,55 @@
+# Testing Framework
+
+### 9.1 createFormMock
+
+```typescript
+import { createFormMock } from '@xrmforge/testing';
+import type { AccountMainForm, AccountMainFormMockValues } from '../typings/forms/account';
+
+const mock = createFormMock<AccountMainForm, AccountMainFormMockValues>({
+  name: 'Contoso Ltd',
+  statuscode: 0,
+  revenue: 1000000,
+});
+
+// Use in tests:
+onLoad(mock.executionContext);
+expect(mock.formContext.getControl('revenue').getVisible()).toBe(true);
+```
+
+**What it mocks:**
+- Attributes: MockAttribute instances with getValue/setValue, dirty tracking, onChange handlers, required level, submit mode
+- Controls: MockControl instances with visible/disabled/label/notification state
+- UI: Form notifications, tab/section stubs
+- Entity: ID, entity name, primary attribute
+- Data: refresh(), save() stubs returning Promise-like
+- Navigation: openForm/openAlertDialog stubs
+
+**Lazy initialization:** Attributes accessed via `getAttribute()` that were not in the initial values are created on-the-fly with null value.
+
+### 9.2 fireOnChange
+
+```typescript
+mock.fireOnChange('statuscode');
+// Triggers all handlers registered via getAttribute('statuscode').addOnChange(handler)
+```
+
+Creates a MockEventContext with the attribute as event source.
+
+### 9.3 setupXrmMock / teardownXrmMock
+
+```typescript
+import { setupXrmMock, teardownXrmMock } from '@xrmforge/testing';
+
+beforeEach(() => setupXrmMock());
+afterEach(() => teardownXrmMock());
+
+// With WebApi overrides:
+setupXrmMock({
+  webApiOverrides: {
+    retrieveMultipleRecords: async () => ({ entities: [{ name: 'Test' }] }),
+  },
+});
+```
+
+Sets up a global `Xrm` object on `globalThis` with minimal WebApi, Navigation, and Utility stubs.