Detect broken XML paths and offer to fix on form load

[jingcheng16]

Product Description

When a form has hand-edited XML with wrong paths (e.g., a repeat group referencing /data/members_repeat instead of /data/sec_members/members_repeat), the form silently breaks — Question ID becomes blank and uneditable, and saving the form causes data loss. User is confused and don't know how to fix it, fill in a Question ID won't work.

After this change, a modal appears on form load showing the broken paths and their corrections (e.g., /data/members_repeat → /data/sec_members/members_repeat), with a "Fix and Reload" button that corrects the XML automatically.

I then realized I can apply same logic to broken path in bind node.

Thus the modal will become the following:

Technical Summary

Ticket: https://dimagi.atlassian.net/browse/SAAS-19569

Why Question ID breaks

When a control element's path doesn't resolve via getMugByPath, the parser creates an orphaned "control-only" mug with no data node. This causes a chain of failures:

1. isControlOnly = true → absolutePath returns null (code)
2. absolutePath null → hashtagPath null
3. The nodeID setter calls moveMug("rename", value) which skips the entire rename block for control-only mugs
4. Result: Question ID stays blank and can't be set through the UI

How this PR fixes it

During parsing, when getMugByPath fails, findDataNodeByLeafName searches for an unclaimed DataBindOnly mug with the same node name (e.g., finds members_repeat at /data/sec_members/members_repeat). If found, the correction is stored on form.pathCorrections. After parsing, showPathCorrectionModal displays the corrections. "Fix and Reload" does a find-and-replace on the raw XML and reloads the form, which resolves the control to the correct data node and restores Question ID.

Feature Flag

N/A

Safety Assurance

Safety story

This only activates when getMugByPath returns null for a control element's path — a case that previously resulted in silent data loss. Normal forms with valid paths are unaffected. The fix is opt-in via the modal (user can click "Ignore" to skip).

Automated test coverage

No existing tests cover malformed XML path handling. Manual testing with broken XML files confirms the modal appears and fix works correctly.

QA Plan

• Load a form with a wrong repeat path — modal should appear showing /data/members_repeat → /data/sec_members/members_repeat
• Click "Fix and Reload" — form reloads with corrected paths, Question ID works
• Click "Ignore" — form loads as before (broken), no crash
• Load a normal form — no modal, no change in behavior

Rollback instructions

• This PR can be reverted after deploy with no further considerations

Labels & Review

• Risk label is set correctly
• The set of people pinged as reviewers is appropriate for the level of risk of the change

🤖 Generated with Claude Code

[millerdev]

I don't think we should attempt to fix manual XML editing mistakes. All kinds of errors could be made, and there is no way we can possibly handle all of them. We may end up breaking the form even more with automated fixups. At best we would be guessing, which violates the Zen "In the face of ambiguity, refuse the temptation to guess."

[millerdev]

What if multiple data nodes are matched? It doesn't know which is the correct one. As implemented, it chooses the last match.
Imagine a scenario where two different mugs are missing data nodes, and both have the same node leaf name. I think both would be assigned the same data node, which would be incorrect.

[jingcheng16]

All kinds of errors could be made, and there is no way we can possibly handle all of them. We may end up breaking the form even more with automated fixups.

@millerdev It's true. 😞 Then in this case, what can we do to help user except for ask them to delete the repeat group and rebuild it? I built this mainly because I think all warning message is misleading, and user is not able to fix it in the UI.
All children in the repeat group would have this error:

[millerdev]

what can we do to help user except for ask them to delete the repeat group and rebuild it?

That is one option. If they have edited XML by hand, they may know enough to fix the error by editing XML, so maybe that could be suggested first? If they do not know how to fix it then the fall-back option of deleting the group and rebuilding is probably the best path forward.

It's true, the error message you referenced is pretty technical. I think it is a reasonable and correct error message if they have made a mistake while hand-editing XML. At the point of seeing it they should know that they have made a mistake while editing XML, and should probably attempt to fix it there rather than in the UI.