You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: update PR checklist with backend abstraction compliance rules
Add new "Backend abstraction compliance" section covering the architectural
patterns established by the #222–#239 refactoring stack:
- Executor must not import sdk/mpr for write paths (use ctx.Backend.*)
- New backend methods belong in mdl/backend/ interfaces
- Implementations go in mdl/backend/mpr/, mocks in mdl/backend/mock/
- Compile-time interface satisfaction checks required
- ALTER operations use PageMutator/WorkflowMutator factory pattern
- New shared types go in mdl/types/ with sdk/mpr type aliases
- Map iteration over serialization output must sort keys for determinism
- Pluggable widgets via WidgetEngine/.def.json, not hardcoded builders
Also:
- Update Full-stack consistency section: executor handler must be thin
(no BSON), and backend method wiring is now an explicit pipeline step
- Update bug-fix test location to include mdl/backend/mpr/ and MockBackend
- Add Code quality items: float64→int bounds checks, convert.go drift
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: CLAUDE.md
+17-2Lines changed: 17 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -242,7 +242,7 @@ When reviewing pull requests or validating work before commit, verify these item
242
242
### Bug fixes
243
243
-[ ]**Fix-issue skill consulted** — read `.claude/skills/fix-issue.md` before diagnosing; match symptom to table before opening files
244
244
-[ ]**Symptom table updated** — new symptom/layer/file mapping added to `.claude/skills/fix-issue.md` if not already covered
245
-
-[ ]**Test written first** — failing test exists before implementation (parser test in `sdk/mpr/`, formatter test in `mdl/executor/`)
245
+
-[ ]**Test written first** — failing test exists before implementation (parser test in `sdk/mpr/`, backend mutation test in `mdl/backend/mpr/`, executor handler test in `mdl/executor/` using `MockBackend`)
246
246
247
247
### Overlap & duplication
248
248
-[ ] Check `docs/11-proposals/` for existing proposals covering the same functionality
@@ -267,13 +267,26 @@ New features that depend on a specific Mendix version must be version-gated:
267
267
-[ ]**Test coverage** — version-gated tests use `-- @version:` directives or `requireMinVersion()`
268
268
-[ ]**Skill updated** — `.claude/skills/version-awareness.md` updated if the feature has a workaround for older versions
269
269
270
+
### Backend abstraction compliance
271
+
All executor code must go through the backend abstraction layer — the executor must never import `sdk/mpr` for write paths:
272
+
-[ ]**No `sdk/mpr` write imports in executor** — executor files must not call `sdk/mpr` writer/parser types directly; use `ctx.Backend.*` instead
273
+
-[ ]**New backend methods on the interface** — any new data access or mutation goes in the appropriate interface in `mdl/backend/` (e.g., `DomainModelBackend`, `MicroflowBackend`), not as a direct SDK call
274
+
-[ ]**MPR implementation in `mdl/backend/mpr/`** — the concrete implementation lives here; all BSON/reader/writer logic stays in this package
275
+
-[ ]**Mock stub in `mdl/backend/mock/`** — every new backend method has a `Func`-field stub with a descriptive `"MockBackend.X not configured"` error default (not `nil, nil`)
276
+
-[ ]**Compile-time interface check** — new backend implementations have `var _ backend.SomeInterface = (*impl)(nil)`
277
+
-[ ]**ALTER operations use mutator pattern** — page/workflow mutations go through `ctx.Backend.OpenPageForMutation()` / `OpenWorkflowForMutation()`, not inline BSON construction
278
+
-[ ]**New shared types in `mdl/types/`** — types used by both `mdl/` and `sdk/mpr` go in `mdl/types/`; `sdk/mpr` re-exports as type aliases (`type Foo = types.Foo`), never as duplicate definitions
279
+
-[ ]**Map iteration is deterministic** — any map iterated for serialization output must sort keys first (`sort.Strings(keys)` pattern); non-deterministic output causes flaky diffs and BSON instability
280
+
-[ ]**Pluggable widgets via WidgetEngine** — new pluggable widget support uses `.def.json` + `WidgetRegistry`; no hardcoded BSON widget builders in the executor
281
+
270
282
### Full-stack consistency for MDL features
271
283
New MDL commands or language features must be wired through the full pipeline:
272
284
-[ ]**Grammar** — rule added to `MDLParser.g4` (and `MDLLexer.g4` if new tokens)
-[ ]**Visitor** — ANTLR listener bridges parse tree to AST in `mdl/visitor/`
276
-
-[ ]**Executor** — handler in `mdl/executor/` executes the AST node
288
+
-[ ]**Executor** — thin handler in `mdl/executor/` dispatches to `ctx.Backend.*`; no BSON in the handler
289
+
-[ ]**Backend method** — data access or mutation wired through `mdl/backend/` interface and implemented in `mdl/backend/mpr/`
277
290
-[ ]**LSP** — if the feature adds formatting, diagnostics, or navigation targets, wire it into `cmd/mxcli/lsp.go` and register the capability
278
291
-[ ]**DESCRIBE roundtrip** — if the feature creates artifacts, `DESCRIBE` should output re-executable MDL
279
292
-[ ]**VS Code extension** — if new LSP capabilities are added, update `vscode-mdl/package.json`
@@ -309,6 +322,8 @@ New MDL commands or language features must be wired through the full pipeline:
309
322
-[ ] Refactors are applied consistently across all relevant files (grep for the old pattern)
310
323
-[ ] Manually maintained lists (keyword lists, type mappings) are flagged as maintenance risks
311
324
-[ ] Design docs match the actual implementation — remove or update stale plans
325
+
-[ ] Numeric type conversions are bounds-checked — `float64→int` casts need overflow guards (`±2^53` for safe integer range); silent overflow produces garbage in serialized output
326
+
-[ ]`convert.go` updated when structs in `mdl/types/` gain or lose fields — `TestFieldCountDrift` will catch this at test time, but `convert.go` must be updated before merging
0 commit comments