|
| 1 | +# Fix Issue Skill |
| 2 | + |
| 3 | +A fast-path workflow for diagnosing and fixing bugs in mxcli. Each fix appends |
| 4 | +to the symptom table below, so the next similar issue costs fewer reads. |
| 5 | + |
| 6 | +## How to Use |
| 7 | + |
| 8 | +1. Match the issue symptom to a row in the table — go straight to that file. |
| 9 | +2. Follow the fix pattern for that row. |
| 10 | +3. Write a failing test first, then implement. |
| 11 | +4. After the fix: **add a new row** to the table if the symptom is not already covered. |
| 12 | + |
| 13 | +--- |
| 14 | + |
| 15 | +## Symptom → Layer → File Table |
| 16 | + |
| 17 | +| Symptom | Root cause layer | First file to open | Fix pattern | |
| 18 | +|---------|-----------------|-------------------|-------------| |
| 19 | +| `DESCRIBE` shows `$var = LIST OPERATION ...;` | Missing parser case | `sdk/mpr/parser_microflow.go` → `parseListOperation()` | Add `case "Microflows$XxxType":` returning the correct struct | |
| 20 | +| `DESCRIBE` shows `$var = ACTION ...;` | Missing formatter case | `mdl/executor/cmd_microflows_format_action.go` → `formatActionStatement()` | Add `case *microflows.XxxAction:` with `fmt.Sprintf` output | |
| 21 | +| `DESCRIBE` shows `$var = LIST OPERATION %T;` (with type name) | Missing formatter case | `mdl/executor/cmd_microflows_format_action.go` → `formatListOperation()` | Add `case *microflows.XxxOperation:` before the `default` | |
| 22 | +| Compile error: `undefined: microflows.XxxOperation` | Missing SDK struct | `sdk/microflows/microflows_actions.go` | Add struct + `func (XxxOperation) isListOperation() {}` marker | |
| 23 | +| `TypeCacheUnknownTypeException` in Studio Pro | Wrong `$Type` storage name in BSON write | `sdk/mpr/writer_microflow.go` | Check the storage name table in CLAUDE.md; verify against `reference/mendixmodellib/reflection-data/` | |
| 24 | +| CE0066 "Entity access is out of date" | MemberAccess added to wrong entity | `sdk/mpr/writer_domainmodel.go` | MemberAccess must only be on the FROM entity (`ParentPointer`), not the TO entity — see CLAUDE.md association semantics | |
| 25 | +| CE0463 "widget definition changed" | Object property structure doesn't match Type PropertyTypes | `sdk/widgets/templates/` | Re-extract template from Studio Pro; see `sdk/widgets/templates/README.md` | |
| 26 | +| Parser returns `nil` for a known BSON type | Unhandled `default` in a `parseXxx()` switch | `sdk/mpr/parser_microflow.go` or `parser_page.go` | Find the switch by grepping for `default: return nil`; add the missing case | |
| 27 | +| MDL check gives "unexpected token" on valid-looking syntax | Grammar missing rule or token | `mdl/grammar/MDLParser.g4` + `MDLLexer.g4` | Add rule/token, run `make grammar` | |
| 28 | + |
| 29 | +--- |
| 30 | + |
| 31 | +## TDD Protocol |
| 32 | + |
| 33 | +Always follow this order — never implement before the test exists: |
| 34 | + |
| 35 | +``` |
| 36 | +Step 1: Write a failing unit test (parser test or formatter test) |
| 37 | +Step 2: Confirm it fails to compile or fails at runtime |
| 38 | +Step 3: Implement the minimum code to make it pass |
| 39 | +Step 4: Run: /c/Users/Ylber.Sadiku/go/go/bin/go test ./mdl/executor/... ./sdk/mpr/... |
| 40 | +Step 5: Add the symptom row to the table above if not already present |
| 41 | +``` |
| 42 | + |
| 43 | +Parser tests go in `sdk/mpr/parser_<domain>_test.go`. |
| 44 | +Formatter tests go in `mdl/executor/cmd_<domain>_format_<area>_test.go`. |
| 45 | + |
| 46 | +--- |
| 47 | + |
| 48 | +## Issue #212 — Reference Fix (seeding example) |
| 49 | + |
| 50 | +**Symptom:** `DESCRIBE MICROFLOW` showed `$var = LIST OPERATION ...;` for |
| 51 | +`Microflows$Find`, `Microflows$Filter`, `Microflows$ListRange`. |
| 52 | + |
| 53 | +**Root cause:** `parseListOperation()` in `sdk/mpr/parser_microflow.go` had no |
| 54 | +cases for these three BSON types — they fell to `default: return nil`. |
| 55 | + |
| 56 | +**Files changed:** |
| 57 | +| File | Change | |
| 58 | +|------|--------| |
| 59 | +| `sdk/microflows/microflows_actions.go` | Added `FindByAttributeOperation`, `FilterByAttributeOperation`, `RangeOperation` | |
| 60 | +| `sdk/mpr/parser_microflow.go` | Added 3 parser cases | |
| 61 | +| `mdl/executor/cmd_microflows_format_action.go` | Added 3 formatter cases | |
| 62 | +| `mdl/executor/cmd_microflows_format_listop_test.go` | Added 4 formatter tests | |
| 63 | +| `sdk/mpr/parser_listoperation_test.go` | New file, 4 parser tests | |
| 64 | + |
| 65 | +**Key insight:** `Microflows$ListRange` stores offset/limit inside a nested |
| 66 | +`CustomRange` map — must cast `raw["CustomRange"].(map[string]any)` before |
| 67 | +extracting `OffsetExpression`/`LimitExpression`. |
| 68 | + |
| 69 | +--- |
| 70 | + |
| 71 | +## After Every Fix — Checklist |
| 72 | + |
| 73 | +- [ ] Failing test written before implementation |
| 74 | +- [ ] `go test ./mdl/executor/... ./sdk/mpr/...` passes |
| 75 | +- [ ] New symptom row added to the table above (if not already covered) |
| 76 | +- [ ] PR title: `fix: <one-line description matching the symptom>` |
0 commit comments