Skip to content

Commit 771ac33

Browse files
akoclaude
andcommitted
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>
1 parent 79a6e49 commit 771ac33

1 file changed

Lines changed: 17 additions & 2 deletions

File tree

CLAUDE.md

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -242,7 +242,7 @@ When reviewing pull requests or validating work before commit, verify these item
242242
### Bug fixes
243243
- [ ] **Fix-issue skill consulted** — read `.claude/skills/fix-issue.md` before diagnosing; match symptom to table before opening files
244244
- [ ] **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`)
246246

247247
### Overlap & duplication
248248
- [ ] 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:
267267
- [ ] **Test coverage** — version-gated tests use `-- @version:` directives or `requireMinVersion()`
268268
- [ ] **Skill updated**`.claude/skills/version-awareness.md` updated if the feature has a workaround for older versions
269269

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+
270282
### Full-stack consistency for MDL features
271283
New MDL commands or language features must be wired through the full pipeline:
272284
- [ ] **Grammar** — rule added to `MDLParser.g4` (and `MDLLexer.g4` if new tokens)
273285
- [ ] **Parser regenerated**`make grammar` run, generated files committed
274286
- [ ] **AST** — node type added in `mdl/ast/`
275287
- [ ] **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/`
277290
- [ ] **LSP** — if the feature adds formatting, diagnostics, or navigation targets, wire it into `cmd/mxcli/lsp.go` and register the capability
278291
- [ ] **DESCRIBE roundtrip** — if the feature creates artifacts, `DESCRIBE` should output re-executable MDL
279292
- [ ] **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:
309322
- [ ] Refactors are applied consistently across all relevant files (grep for the old pattern)
310323
- [ ] Manually maintained lists (keyword lists, type mappings) are flagged as maintenance risks
311324
- [ ] 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
312327

313328
## Dependencies
314329

0 commit comments

Comments
 (0)