@codihaus/claude-skills 1.0.0

package/skills/utils/diagram/references/common-errors.md

@@ -0,0 +1,305 @@
+# Common Mermaid Errors
+
+Error patterns and auto-fix solutions.
+
+## Reserved Words
+
+**Error**: `Parse error on line X`
+
+**Cause**: Using reserved words as node IDs.
+
+**Reserved words**:
+- `end`, `End`, `END`
+- `graph`, `subgraph`
+- `style`, `class`
+- `click`, `link`
+
+**Fix**: Wrap in quotes.
+
+```diff
+- A --> End
++ A --> "End"
+
+- graph --> process
++ "graph" --> process
+```
+
+## Special Characters in Text
+
+**Error**: `Lexical error` or `Parse error`
+
+**Cause**: Unquoted special characters.
+
+**Problem characters**: `( ) [ ] { } < > | # ; :`
+
+**Fix**: Wrap text containing special chars in quotes.
+
+```diff
+- A[User (Admin)]
++ A["User (Admin)"]
+
+- B{Is count > 10?}
++ B{"Is count > 10?"}
+```
+
+## Arrow Syntax
+
+**Error**: `Parse error` near arrow
+
+**Cause**: Wrong arrow format.
+
+| Wrong | Correct | Type |
+|-------|---------|------|
+| `->` | `-->` | Flowchart arrow |
+| `—>` | `-->` | Wrong dash character |
+| `>>` | `->>` | Sequence arrow |
+
+**Fix**: Use correct arrow syntax per diagram type.
+
+```diff
+# Flowchart
+- A -> B
++ A --> B
+
+# Sequence
+- User -> API: Request
++ User ->> API: Request
+```
+
+## Subgraph Not Closed
+
+**Error**: `Parse error` at end of diagram
+
+**Cause**: Missing `end` for subgraph.
+
+**Fix**: Add `end` keyword.
+
+```diff
+  subgraph Backend
+      API --> DB
++ end
+```
+
+## Invalid Node IDs
+
+**Error**: `Parse error` on node definition
+
+**Cause**: Node ID starts with number or contains invalid chars.
+
+**Valid IDs**: Start with letter, contain letters/numbers/underscore.
+
+**Fix**: Use valid identifier.
+
+```diff
+- 1user --> 2admin
++ user1 --> admin2
+
+- user-login --> dashboard
++ userLogin --> dashboard
+```
+
+## Missing Diagram Type
+
+**Error**: First line parse error
+
+**Cause**: No diagram type declaration.
+
+**Fix**: Add diagram type as first line.
+
+```diff
++ flowchart LR
+  A --> B --> C
+```
+
+## Duplicate Node IDs with Different Shapes
+
+**Error**: Inconsistent rendering
+
+**Cause**: Same ID with different shapes.
+
+```mermaid
+# Problem
+A[Rectangle] --> B
+A(Rounded) --> C    # A already defined as rectangle
+```
+
+**Fix**: Use unique IDs.
+
+```diff
+- A[User] --> B
+- A(Admin) --> C
++ User[User] --> B
++ Admin(Admin) --> C
+```
+
+## Comments Breaking Diagrams
+
+**Error**: Parse error in comment area
+
+**Cause**: Using `//` or `/* */` instead of `%%`.
+
+**Fix**: Use mermaid comment syntax.
+
+```diff
+- // This is a comment
++ %% This is a comment
+
+- A --> B // inline
++ A --> B
+```
+
+## Curly Braces in Text
+
+**Error**: Unexpected token
+
+**Cause**: `{}` in node text or comments.
+
+**Fix**: Avoid or escape braces.
+
+```diff
+- A["Object {key: value}"]
++ A["Object with key-value"]
+```
+
+## Architecture Diagram Errors
+
+### Invalid Edge Direction
+
+**Error**: `Parse error` on edge definition
+
+**Cause**: Missing or invalid direction (L/R/T/B).
+
+**Fix**: Add direction on both sides.
+
+```diff
+- db --> server
++ db:R --> L:server
+
+- db:R --> server
++ db:R --> L:server
+```
+
+### Missing Group Parent
+
+**Error**: Group reference not found
+
+**Cause**: Nested group references non-existent parent.
+
+**Fix**: Define parent group first.
+
+```diff
++ group api(cloud)[API]
+  group db(cloud)[Database] in api
+```
+
+### Invalid Service in Group
+
+**Error**: Service parent not found
+
+**Cause**: Service references non-existent group.
+
+**Fix**: Ensure group exists.
+
+```diff
++ group backend(cloud)[Backend]
+  service api(server)[API] in backend
+```
+
+### Invalid Icon Name
+
+**Error**: Icon not recognized
+
+**Cause**: Using unsupported icon name.
+
+**Default icons**: `cloud`, `database`, `disk`, `internet`, `server`
+
+**Fix**: Use valid icon or register custom pack.
+
+```diff
+- service lambda(aws-lambda)[Lambda]
++ service lambda(server)[Lambda]
+%% Or register iconify pack for custom icons
+```
+
+## XY Chart Errors
+
+### Missing Axis Definition
+
+**Error**: Axis not defined
+
+**Fix**: Add x-axis and y-axis.
+
+```diff
+  xychart-beta
++     x-axis [Jan, Feb, Mar]
++     y-axis "Value" 0 --> 100
+      bar [10, 20, 30]
+```
+
+### Mismatched Data Points
+
+**Error**: Data length mismatch
+
+**Cause**: Bar/line data doesn't match x-axis length.
+
+**Fix**: Ensure same number of data points.
+
+```diff
+  x-axis [Jan, Feb, Mar]
+- bar [10, 20]
++ bar [10, 20, 30]
+```
+
+## Sankey Errors
+
+### Invalid CSV Format
+
+**Error**: Parse error in data
+
+**Cause**: Wrong delimiter or missing values.
+
+**Fix**: Use comma-separated format: `source,target,value`
+
+```diff
+- Revenue -> Operations: 40
++ Revenue,Operations,40
+```
+
+## Quadrant Errors
+
+### Invalid Coordinates
+
+**Error**: Point position error
+
+**Cause**: Coordinates outside 0.0-1.0 range.
+
+**Fix**: Use decimal values between 0 and 1.
+
+```diff
+- Feature A: [80, 90]
++ Feature A: [0.8, 0.9]
+```
+
+## Auto-Fix Priority
+
+When fixing, apply in this order:
+
+1. **Reserved words** → Quote them
+2. **Special chars** → Quote the text
+3. **Arrow syntax** → Replace with correct
+4. **Edge direction** → Add L/R/T/B
+5. **Missing end** → Add `end`
+6. **Invalid IDs** → Rename
+7. **Comments** → Convert to `%%`
+
+## Validation Command
+
+```bash
+# Validate single diagram
+echo 'flowchart LR
+    A --> B' > /tmp/test.mmd
+mmdc -i /tmp/test.mmd -o /tmp/test.svg 2>&1
+
+# Check exit code
+echo $?  # 0 = valid, non-zero = error
+```