@xrmforge/devkit 0.5.4 → 0.5.7

package/dist/templates/AGENT.md

@@ -18,8 +18,18 @@ Run `xrmforge generate` to create:
 - `generated/entities/{entity}.ts` - Entity interface
 - `generated/fields/{entity}.ts` - Entity Fields enum for type-safe $select queries
 - `generated/entity-names.ts` - EntityNames const enum
+- `generated/form-mapping.json` - Entity to form interface mapping (read after generate!)
 - `generated/index.ts` - Barrel file with `export * from` re-exports
 
+**After generate:** Read `generated/form-mapping.json` for the mapping of entity logical
+names to form interface names. Do NOT guess interface names from entity names.
+Fields enum member names are based on the **primary language label** (often German),
+not the logical field name. Always read the generated files to get correct names.
+
+**Large projects (50+ entities):** `form-mapping.json` can be large. Do NOT grep through
+all generated files to find interface names. Read `form-mapping.json` once, then use
+the mapping for all imports. This saves time and avoids wrong guesses.
+
 ## Rules: MANDATORY (every violation is a bug)
 
 1. **Fields Enum** for ALL getAttribute/getControl calls. Never raw strings.
@@ -42,11 +52,12 @@ Run `xrmforge generate` to create:
    const form = ctx.getFormContext() as AccountMainForm;
    ```
 
-4. **EntityNames Enum** in ALL Xrm.WebApi calls:
+4. **EntityNames Enum** in ALL Xrm.WebApi calls — no exceptions, even for system entities:
    ```typescript
    import { EntityNames } from '../generated/entity-names.js';
    Xrm.WebApi.retrieveRecord(EntityNames.Account, id)
    ```
+   If an entity is not in EntityNames, extend the generation (`--entities` flag) to include it.
 
 5. **Lookup helpers** from @xrmforge/helpers for ALL lookup value access:
    ```typescript
@@ -57,11 +68,28 @@ Run `xrmforge generate` to create:
    // Web API response lookups (_fieldname_value + OData annotations):
    const parent = parseLookup(apiResponse, 'parentaccountid');
    ```
+   **NEVER** access lookup values directly:
+   ```typescript
+   // BUG - never do this:
+   form.getAttribute(Fields.CustomerId).getValue()[0].id.replace('{','')
+   // CORRECT:
+   formLookupId(form.getAttribute(Fields.CustomerId))
+   ```
 
 6. **select()** from @xrmforge/helpers for ALL $select queries:
    ```typescript
    import { select } from '@xrmforge/helpers';
+   // Simple query:
    Xrm.WebApi.retrieveRecord(EntityNames.Account, id, select(Fields.Name, Fields.Revenue))
+   // Combined with $filter:
+   Xrm.WebApi.retrieveMultipleRecords(EntityNames.Account,
+     `${select(Fields.Name, Fields.Revenue)}&$filter=statecode eq 0`)
+   ```
+   **Signature:** `select(...fields: string[])` takes REST parameters, NOT an array.
+   ```typescript
+   select(Fields.Name, Fields.Revenue)           // CORRECT
+   select([Fields.Name, Fields.Revenue])          // WRONG - array argument
+   select('account', Fields.Name)                 // WRONG - first arg is not entity name
    ```
 
 7. **wrapHandler()** around EVERY exported async event handler:
@@ -98,11 +126,26 @@ Run `xrmforge generate` to create:
 - Never `window.X = ...` (use module exports)
 - Never `console.log/warn/error` in form scripts (use shared logger)
 - Never export async handlers without wrapHandler()
-- Never `Xrm.WebApi.retrieveRecord("account", ...)` with raw entity name (use EntityNames)
+- Never `Xrm.WebApi.retrieveRecord("account", ...)` with raw entity name (use EntityNames, no exceptions even for system entities)
 - Never `"?$select=name,revenue"` as raw string (use select() from @xrmforge/helpers)
-- Never `.getValue()[0].id.replace(...)` for lookups (use formLookup/formLookupId from @xrmforge/helpers)
+- Never `.getValue()[0].id` or `.getValue()[0].id.replace(...)` for lookups (use formLookup/formLookupId from @xrmforge/helpers)
+- Never build your own lookup helper (getLookupValueId, firstLookupValue, etc.) when formLookup/formLookupId exists
 - Never `import ... from '@xrmforge/typegen'` in browser code. @xrmforge/typegen is a Node.js CLI tool. Use `@xrmforge/helpers` for browser-safe runtime functions (select, parseLookup, formLookup, createUnboundAction, etc.)
 
+## Subagent Handoff (when delegating to sub-agents)
+
+Copy these MANDATORY rules into every sub-agent prompt:
+
+```
+1. Fields Enum for ALL getAttribute/getControl (never raw strings)
+2. OptionSet Enum for ALL value comparisons (never magic numbers)
+3. EntityNames for ALL Xrm.WebApi calls (never raw entity names, no exceptions)
+4. formLookup/formLookupId for ALL lookup access (never .getValue()[0].id)
+5. select() for ALL $select queries (never raw "$select=" strings)
+6. wrapHandler() around EVERY exported async handler
+7. createLogger() instead of console.* (except logger.ts)
+```
+
 ## Mandatory Shared Utilities
 
 Every XrmForge project MUST have these in `src/shared/`:
@@ -146,16 +189,34 @@ import { StatusCode } from '../generated/optionsets/invoice.js';
 if (status.getValue() === StatusCode.Gebucht) { ... }
 ```
 
-### Testing
+### Testing (onLoad + onChange)
 ```typescript
-import { createFormMock } from '@xrmforge/testing';
-const mock = createFormMock<AccountMainForm>({
-  name: 'Test', statuscode: 0
-});
+import { createFormMock, setupXrmMock, teardownXrmMock } from '@xrmforge/testing';
+
+beforeEach(() => setupXrmMock());
+afterEach(() => teardownXrmMock());
+
+// onLoad test:
+const mock = createFormMock<AccountMainForm>({ name: 'Test', statuscode: 0 });
 onLoad(mock.asEventContext());
-expect(mock.formContext.getControl('revenue').getVisible()).toBe(true);
+expect(mock.getControl(Fields.Revenue).getVisible()).toBe(true);
+
+// onChange test (MANDATORY for every onChange handler):
+mock.setValue(Fields.Revenue, 500000);
+mock.fireOnChange(Fields.Revenue);
+expect(mock.getControl(Fields.CreditLimit).getVisible()).toBe(true);
+expect(mock.getValue(Fields.CreditOnHold)).toBe(true);
 ```
 
+**Test quality rule:** At least 30% of tests MUST use `fireOnChange` or WebApi mock
+assertions. Pure smoke tests (`onLoad` + `not.toThrow`) do NOT count as behavior tests.
+Tests that only check `getOnChangeHandlers().length > 0` are registration tests, not
+behavior tests. Every onChange handler MUST have a `fireOnChange` test.
+
+**attr.controls:** Since @xrmforge/testing 0.2.3, `createFormMock()` automatically links
+each attribute to its control. `mock.getControl(Fields.Name)` works out of the box.
+No need to mock controls separately.
+
 ## File Structure
 
 ```
@@ -177,7 +238,7 @@ When you see these patterns in legacy code, apply the XrmForge replacement:
 | `getValue() === 595300000` | `getValue() === OptionSets.StatusCode.Active` |
 | `Xrm.WebApi.retrieveRecord("account", id)` | `Xrm.WebApi.retrieveRecord(EntityNames.Account, id)` |
 | `"?$select=name,revenue"` | `select(Fields.Name, Fields.Revenue)` (from @xrmforge/helpers) |
-| `value[0].id.replace("{","")...` | `parseLookup(form.getAttribute(Fields.X))` (from @xrmforge/helpers) |
+| `value[0].id.replace("{","")...` | `formLookupId(form.getAttribute(Fields.X))` for forms, `parseLookup(response, 'field')` for Web API |
 | `Xrm.Page.getAttribute(...)` | `formContext.getAttribute(...)` |
 | `var formContext` (global) | `const form = ctx.getFormContext()` (parameter) |
 | `function form_OnLoad(ctx)` | `export function onLoad(ctx: Xrm.Events.EventContext)` |
@@ -260,6 +321,13 @@ When creating manual typings without `xrmforge generate`:
 After converting ALL scripts, run these checks. Fix every violation before proceeding to tests.
 Document results in SESSION-GEDAECHTNIS.md (violation count per category).
 
+**Platform note:** The checks below use bash/grep syntax. On Windows PowerShell, use
+`Select-String` instead of `grep`. Example:
+```powershell
+# PowerShell equivalent of: grep -rn "getAttribute('" src/forms/ --include="*.ts"
+Get-ChildItem -Recurse src/forms -Filter *.ts | Select-String "getAttribute\('" | Where-Object { $_.Line -notmatch 'Fields\.' }
+```
+
 ### Pattern Compliance (all must be 0, or documented exception)
 
 ```bash
@@ -273,8 +341,9 @@ grep -rn "getValue() ===" src/ --include="*.ts" | grep -E "[0-9]{3,}"
 # 3. Direct _value access instead of parseLookup (in Web API responses)
 grep -rn "_value\b" src/ --include="*.ts" | grep -v "generated/" | grep -v "parseLookup" | grep -v "getValue"
 
-# 4. Raw entity names in WebApi calls (must use EntityNames)
+# 4. Raw entity names in WebApi calls (must use EntityNames, no exceptions)
 grep -rn "retrieveRecord\|retrieveMultipleRecords\|deleteRecord\|createRecord\|updateRecord" src/ --include="*.ts" | grep "'[a-z]" | grep -v "EntityNames"
+# Every match is a violation. If entity is missing from EntityNames, extend generation.
 
 # 5. Missing select() - no raw "$select=" strings anywhere in src/
 grep -rn '\$select' src/ --include="*.ts" | grep -v "select(" | grep -v "generated/"
@@ -293,11 +362,11 @@ grep -rn "from.*generated/fields/" src/ --include="*.ts" | wc -l
 ### Code Quality (all must be 0)
 
 ```bash
-# console.* outside logger.ts
-grep -rn "console\." src/ --include="*.ts" | grep -v "logger.ts"
+# console.* outside logger.ts (exclude JSDoc comments)
+grep -rn "console\." src/ --include="*.ts" | grep -v "logger.ts" | grep -v "^\s*\*" | grep -v "^\s*//"
 
-# Xrm.Page (deprecated since D365 v9.0)
-grep -rn "Xrm\.Page" src/ --include="*.ts"
+# Xrm.Page (deprecated since D365 v9.0, exclude JSDoc comments)
+grep -rn "Xrm\.Page" src/ --include="*.ts" | grep -v "^\s*\*" | grep -v "^\s*//"
 
 # var declarations
 grep -rnE "^\s*var " src/ --include="*.ts"
@@ -345,6 +414,30 @@ for f in tests/**/*.test.ts; do
 done
 ```
 
+### Test Gap Analysis (after writing tests)
+
+Before declaring tests complete, verify coverage gaps:
+
+```bash
+# 1. onChange handlers without fireOnChange test
+for f in tests/**/*.test.ts; do
+  has_onchange=$(grep -c "onChange\|on_change\|OnChange" "$(echo $f | sed 's|tests/|src/|;s|.test.ts|.ts|')" 2>/dev/null || echo 0)
+  has_fire=$(grep -c "fireOnChange" "$f" 2>/dev/null || echo 0)
+  [ "$has_onchange" -gt 0 ] && [ "$has_fire" -eq 0 ] && echo "Missing fireOnChange: $f"
+done
+
+# 2. WebApi calls without mock assertions
+grep -rln "Xrm.WebApi\|retrieveRecord\|retrieveMultiple" src/forms/ --include="*.ts" | while read f; do
+  test_f="tests/forms/$(basename "$f" .ts).test.ts"
+  [ -f "$test_f" ] && ! grep -q "retrieveRecord\|retrieveMultiple\|webApiOverrides" "$test_f" && echo "No WebApi mock: $test_f"
+done
+
+# 3. Behavior test ratio (target: >= 30%)
+total=$(grep -rc "it(" tests/ --include="*.test.ts" 2>/dev/null | awk -F: '{s+=$2}END{print s}')
+behavior=$(grep -rc "fireOnChange\|retrieveRecord\|retrieveMultiple\|expect.*getValue\|expect.*getVisible" tests/ --include="*.test.ts" 2>/dev/null | awk -F: '{s+=$2}END{print s}')
+echo "Behavior tests: $behavior / $total (target: >= 30%)"
+```
+
 ### Exceptions
 
 Some checks have legitimate exceptions:

package/dist/templates/self-check.sh

@@ -57,10 +57,10 @@ echo ""
 echo "--- Code Quality ---"
 
 check "console.* outside logger.ts" \
-  bash -c 'grep -rn "console\." src/ --include="*.ts" | grep -v "logger.ts"'
+  bash -c 'grep -rn "console\." src/ --include="*.ts" | grep -v "logger.ts" | grep -v "^\s*\*" | grep -v "^\s*//"'
 
 check "Xrm.Page (deprecated since D365 v9.0)" \
-  bash -c 'grep -rn "Xrm\.Page" src/ --include="*.ts"'
+  bash -c 'grep -rn "Xrm\.Page" src/ --include="*.ts" | grep -v "^\s*\*" | grep -v "^\s*//"'
 
 check "var declarations" \
   bash -c 'grep -rnE "^\s*var " src/ --include="*.ts"'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xrmforge/devkit",
-  "version": "0.5.4",
+  "version": "0.5.7",
   "description": "Build orchestration and project tooling for Dynamics 365 WebResources",
   "keywords": [
     "dynamics-365",