@xrmforge/devkit 0.7.18 → 0.7.23

package/dist/templates/AGENT.md

@@ -189,6 +189,45 @@ import { AccountNavigationProperties as AccountNav } from '../../generated/entit
 const parent = parseLookup(apiResponse, AccountNav.ParentAccountId);
 ```
 
+### 5b. Lookup fields: `Fields` enum is `_value`-form, `NavigationProperties` is blank
+
+typegen emits TWO enums per entity for lookups, with DIFFERENT values. Picking the wrong one
+compiles green but breaks at runtime (no tsc/eslint gate catches it):
+
+| Enum | Value for a lookup (e.g. `transactioncurrencyid`) | Use for |
+|---|---|---|
+| `XxxFields` | `'_transactioncurrencyid_value'` (already `_value`-form) | `$select`, `$filter` |
+| `XxxNavigationProperties` | `'transactioncurrencyid'` (blank) | `parseLookup`, `$expand`, `@odata.bind`, `$unsafe` (lookup) |
+
+```typescript
+import { AccountFields } from '../../generated/fields/account.js';
+import { AccountNavigationProperties as AccountNav } from '../../generated/entities/account.js';
+
+// $select / $filter: the Fields value is ALREADY _value-form, use it directly
+select(AccountFields.TransactionCurrencyId);              // -> "_transactioncurrencyid_value"
+
+// parseLookup: the NavigationProperties value (blank), NOT Fields
+const currency = parseLookup(apiResponse, AccountNav.TransactionCurrencyId);
+
+// BUG (F-LMA7-05): double _value wrap -> "__transactioncurrencyid_value_value" -> OData 400 at runtime
+const key = `_${AccountFields.TransactionCurrencyId}_value`;
+// BUG: parseLookup with a Fields value (already _value) -> key wrong -> always returns null
+parseLookup(apiResponse, AccountFields.TransactionCurrencyId);
+```
+
+- **`$select`/`$filter`:** use the `XxxFields` value DIRECTLY. NEVER wrap it again as
+  `` `_${XxxFields.Lookup}_value` `` - the Fields value is already complete.
+- **`parseLookup(response, X)`:** `X` MUST be `XxxNavigationProperties.Lookup` (blank). parseLookup
+  builds the key itself as `_${nav}_value`; a `XxxFields` value double-wraps and always returns `null`.
+- **`$unsafe()` on an off-form LOOKUP** uses `XxxNavigationProperties.Lookup` (blank) - it takes an
+  attribute logical name, not the `_value` Web API key. `XxxFields.Lookup` (already `_value`-form) is
+  not a valid attribute name and resolves to `null` at runtime. For a non-lookup off-form field,
+  `XxxFields` is correct (F-LMA7-06).
+- **Never write a local `lookupValue(field)` helper** that puts `_${field}_value` around a `XxxFields`
+  value (F-LMA7-05). It is plain string concatenation - green at compile time, broken at runtime.
+- **parseLookup needs the raw response** (`Record<string, unknown>`), not a value cast to a generated
+  Entity interface (no index signature). Keep the raw response for parseLookup, cast separately.
+
 ### 6. select(), $filter, $expand, $orderby with Fields Enums
 
 ALL OData query parts must use entity-level Fields Enums. No raw field name strings anywhere.
@@ -374,6 +413,8 @@ Xrm.Navigation.openForm({ entityName: EntityNames.Account, entityId: id });  //
 - Never access WebApi response properties with `as string` casts (use generated Entity interfaces)
 - Never `.getValue()[0].id` for lookups (use `formLookup`/`formLookupId`)
 - Never raw strings in `parseLookup()` (use NavigationProperties enum)
+- Never pass a `XxxFields` value to `parseLookup()` (use `XxxNavigationProperties`; a `XxxFields` value is already `_value`-form, so parseLookup double-wraps the key and always returns `null`)
+- Never wrap a `XxxFields` lookup value again as `` `_${XxxFields.X}_value` `` (it is already `_value`-form; double-wrap -> `__..._value_value` -> OData 400). Use the Fields value directly in `$select`/`$filter`; use `XxxNavigationProperties` for `parseLookup`/`$expand`/`@odata.bind`
 - Never raw strings in `$unsafe()` (use Entity-level Fields Enum: `form.$unsafe(AccountFields.X)`)
 - Never manual OData annotation access (`_value`, `@OData.Community.Display.V1.FormattedValue`, `@Microsoft.Dynamics.CRM.lookuplogicalname`). Use `parseLookup()` which extracts all three.
 
@@ -598,6 +639,7 @@ each attribute to its control. `mock.getControl(Fields.Name)` works out of the b
 | `Xrm.WebApi.retrieveRecord("account", id)` | `Xrm.WebApi.retrieveRecord(EntityNames.Account, id)` |
 | `"?$select=name,revenue"` | `select(AccountFields.Name, AccountFields.Revenue)` |
 | `value[0].id.replace("{","")` | `formLookupId(form.customerid)` |
+| `` `_${field}_value` `` hand-built lookup key | `XxxFields.X` directly in `$select`/`$filter` (already `_value`); `XxxNavigationProperties.X` for `parseLookup` |
 | `ExecuteFunctionCall("name", ...)` | `import { Name } from '../../generated/actions/global.js'` |
 | `setFormNotification(msg, 'ERROR', id)` | `setFormNotification(msg, FormNotificationLevel.Error, id)` |
 | `getValue() === 595300000` | `form.statuscode.getValue() === StatusCode.Active` |

package/dist/templates/validate-form.mjs

@@ -307,6 +307,26 @@ checkPattern(
   ['generated/', 'node_modules'],
 );
 
+// ── Lookup Convention (Fields vs NavigationProperties, F-LMA7-05) ─────────────
+
+// 3q2. Hand-built `_<field>_value` key (Fields enum is already _value-form, never wrap again).
+// Compiles green (plain string concatenation) but produces __..._value_value -> OData 400 at runtime.
+checkPattern(
+  'Double _value wrap on a lookup (Fields enum is already _value-form, no _${...}_value)',
+  allSrcFiles,
+  /_\$\{[^}]*\}_value/,
+  ['generated/'],
+);
+
+// 3q3. parseLookup with a Fields enum value (must use the NavigationProperties enum).
+// parseLookup builds the key itself as _${nav}_value; a Fields value (already _value) yields null.
+checkPattern(
+  'parseLookup with a Fields enum (use the NavigationProperties enum instead)',
+  allSrcFiles,
+  /parseLookup\s*\(\s*\w+\s*,\s*\w*Fields\b/,
+  ['generated/'],
+);
+
 // ── Legacy Helper Wrappers ───────────────────────────────────────────────────
 
 // 3r. Forbidden legacy helper functions (must use typedForm + @xrmforge/helpers)

package/package.json

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