wyreframe 0.1.0

package/src/parser/Errors/ErrorContext.res

@@ -0,0 +1,191 @@
+// ErrorContext.res
+// Error context builder for generating code snippets with visual indicators
+// Provides contextual information around error locations for better debugging
+
+// Import core types
+open Types
+
+// ============================================================================
+// Error Context Type
+// ============================================================================
+
+/**
+ * Contains contextual information about an error location.
+ * Includes a code snippet with surrounding lines and visual indicators.
+ */
+type t = {
+  codeSnippet: option<string>, // Formatted code snippet with line numbers and markers
+  linesBefore: int, // Number of lines shown before error
+  linesAfter: int, // Number of lines shown after error
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Convert a cellChar to a displayable string.
+ * This is used to render the grid characters in the error context.
+ */
+let cellCharToString = (cell: cellChar): string => {
+  switch cell {
+  | Corner => "+"
+  | HLine => "-"
+  | VLine => "|"
+  | Divider => "="
+  | Space => " "
+  | Char(s) => s
+  }
+}
+
+/**
+ * Build a formatted code snippet showing the error location.
+ *
+ * Features:
+ * - Line numbers (1-indexed, padded to 4 digits)
+ * - Arrow indicator (→) marking the error line
+ * - Column pointer (^) showing exact error position
+ * - Context lines before and after the error
+ *
+ * Format example:
+ * ```
+ *    1 │ +--------+
+ *    2 │ |  Test  |
+ *  → 3 │ +-------+
+ *      │         ^
+ *    4 │
+ * ```
+ *
+ * @param grid The grid containing the source code
+ * @param position The error position (row, col)
+ * @param radius Number of lines to show before and after
+ * @returns Formatted code snippet as a string
+ *
+ * REQ-18: Contextual Code Snippets
+ */
+let buildCodeSnippet = (grid: Grid.t, position: Position.t, radius: int): string => {
+  // Calculate the range of lines to display
+  // Ensure we don't go out of bounds
+  let startRow = Js.Math.max_int(0, position.row - radius)
+  let endRow = Js.Math.min_int(grid.height - 1, position.row + radius)
+
+  // Helper function to pad string to the left
+  let padStart = (str: string, targetLength: int, padChar: string): string => {
+    let currentLength = String.length(str)
+    if currentLength >= targetLength {
+      str
+    } else {
+      let padLength = targetLength - currentLength
+      let padding = String.repeat(padChar, padLength)
+      padding ++ str
+    }
+  }
+
+  // Build the snippet line by line
+  let lines = []
+
+  for row in startRow to endRow {
+    // Format line number (1-indexed, padded to 4 spaces)
+    let lineNum = (row + 1)->Int.toString->padStart(4, " ")
+
+    // Add arrow indicator for error line, spaces for others
+    let prefix = if row == position.row { " → " } else { "   " }
+
+    // Get the line content from the grid
+    switch Grid.getLine(grid, row) {
+    | Some(chars) => {
+        // Convert cell characters to string
+        let lineText = chars->Belt.Array.map(cellCharToString)->Js.Array2.joinWith("")
+
+        // Build the formatted line: "  → 123 │ content"
+        let formattedLine = `${prefix}${lineNum} │ ${lineText}`
+        lines->Js.Array2.push(formattedLine)->ignore
+
+        // Add column pointer under error position
+        if row == position.row {
+          // Calculate spacing: account for prefix (4) + line number (4) + separator (2) = 10 chars
+          let spacingBeforePointer = 10 + position.col
+          let pointer = " "->Js.String2.repeat(spacingBeforePointer) ++ "^"
+          lines->Js.Array2.push(`      │ ${pointer}`)->ignore
+        }
+      }
+    | None => {
+        // Handle missing lines gracefully (shouldn't happen in valid grid)
+        let formattedLine = `${prefix}${lineNum} │ `
+        lines->Js.Array2.push(formattedLine)->ignore
+      }
+    }
+  }
+
+  // Join all lines with newlines
+  lines->Js.Array2.joinWith("\n")
+}
+
+// ============================================================================
+// Main Constructor
+// ============================================================================
+
+/**
+ * Create an error context from a grid and position.
+ * Automatically builds a code snippet with default or custom radius.
+ *
+ * @param grid The grid containing the source code
+ * @param position The error position
+ * @param radius Number of lines to show before/after (default: 2)
+ * @returns Error context with formatted code snippet
+ */
+let make = (grid: Grid.t, position: Position.t, ~radius: int=2): t => {
+  // Calculate actual lines shown (may be less at boundaries)
+  let startRow = Js.Math.max_int(0, position.row - radius)
+  let endRow = Js.Math.min_int(grid.height - 1, position.row + radius)
+
+  let linesBefore = position.row - startRow
+  let linesAfter = endRow - position.row
+
+  // Build the code snippet
+  let snippet = buildCodeSnippet(grid, position, radius)
+
+  {
+    codeSnippet: Some(snippet),
+    linesBefore: linesBefore,
+    linesAfter: linesAfter,
+  }
+}
+
+/**
+ * Create an empty error context (no snippet).
+ * Used when grid information is not available.
+ */
+let empty = (): t => {
+  codeSnippet: None,
+  linesBefore: 0,
+  linesAfter: 0,
+}
+
+/**
+ * Get the code snippet from the context.
+ * Returns empty string if no snippet is available.
+ */
+let getSnippet = (ctx: t): string => {
+  switch ctx.codeSnippet {
+  | Some(snippet) => snippet
+  | None => ""
+  }
+}
+
+/**
+ * Check if context has a code snippet.
+ */
+let hasSnippet = (ctx: t): bool => {
+  switch ctx.codeSnippet {
+  | Some(_) => true
+  | None => false
+  }
+}
+
+/**
+ * Get the total number of context lines shown.
+ */
+let totalLines = (ctx: t): int => {
+  ctx.linesBefore + 1 + ctx.linesAfter // +1 for the error line itself
+}

package/src/parser/Errors/ErrorMessages.mjs

@@ -0,0 +1,289 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as ErrorContext from "./ErrorContext.mjs";
+
+function formatPosition(pos) {
+  return `row ` + (pos.row + 1 | 0).toString() + `, column ` + (pos.col + 1 | 0).toString();
+}
+
+function formatBoxName(name) {
+  if (name !== undefined) {
+    return `"` + name + `"`;
+  } else {
+    return "unnamed box";
+  }
+}
+
+function getTemplate(code) {
+  switch (code.TAG) {
+    case "InvalidInput" :
+      return {
+        title: "❌ Invalid input",
+        message: code.message + `
+
+The input could not be processed due to formatting or content issues.`,
+        solution: `💡 Solution:
+Check your input format:
+• Ensure the wireframe text is properly formatted
+• Use ASCII characters for box drawing
+• Check for encoding issues if pasting from external sources`
+      };
+    case "InvalidStartPosition" :
+      return {
+        title: "❌ Invalid starting position",
+        message: `Position ` + formatPosition(code._0) + ` is not a valid corner for box tracing.
+
+Box tracing must start from a '+' character that forms a valid corner.`,
+        solution: `💡 Solution:
+Ensure the starting position:
+• Contains a '+' character
+• Is part of a complete box structure
+• Has valid border characters adjacent to it`
+      };
+    case "UncloseBox" :
+      let direction = code.direction;
+      return {
+        title: "❌ Box is not closed",
+        message: `Box opened at ` + formatPosition(code.corner) + ` but never closed on the ` + direction + ` side.
+
+The parser detected a '+' corner character that starts a box, but couldn't find the matching closing border. This usually happens when:
+• The closing corner '+' is missing
+• The border characters ('-' or '|') are broken or incomplete
+• The box structure is malformed`,
+        solution: `💡 Solution:
+Add the missing ` + direction + ` border to close the box:
+• If ` + direction + ` is "top" or "bottom": use '+' corners and '-' characters
+• If ` + direction + ` is "left" or "right": use '+' corners and '|' characters
+• Ensure all four corners are present and borders are continuous`
+      };
+    case "MismatchedWidth" :
+      let bottomWidth = code.bottomWidth;
+      let topWidth = code.topWidth;
+      return {
+        title: "❌ Box width mismatch",
+        message: `Box starting at ` + formatPosition(code.topLeft) + ` has different widths on top and bottom borders:
+• Top border: ` + topWidth.toString() + ` characters wide
+• Bottom border: ` + bottomWidth.toString() + ` characters wide
+
+All boxes must have matching top and bottom border widths to form a valid rectangle.`,
+        solution: `💡 Solution:
+Make both borders the same width. Adjust the ` + (
+          topWidth > bottomWidth ? "bottom" : "top"
+        ) + ` border to match:
+• Add ` + Math.abs(topWidth - bottomWidth | 0).toString() + ` ` + "dashes" + ` to make them equal
+• Count carefully: include both corner '+' characters in the width
+• Example: "+----+" is 6 characters wide (including corners)`
+      };
+    case "MisalignedPipe" :
+      let actualCol = code.actualCol;
+      let expectedCol = code.expectedCol;
+      return {
+        title: "❌ Vertical border misaligned",
+        message: `The '|' character at ` + formatPosition(code.position) + ` is not aligned with the box edge:
+• Expected column: ` + (expectedCol + 1 | 0).toString() + `
+• Actual column: ` + (actualCol + 1 | 0).toString() + `
+• Off by: ` + Math.abs(expectedCol - actualCol | 0).toString() + ` ` + (
+          Math.abs(expectedCol - actualCol | 0) === 1 ? "space" : "spaces"
+        ) + `
+
+Vertical borders must be perfectly aligned to form valid box sides.`,
+        solution: `💡 Solution:
+Move the '|' character to column ` + (expectedCol + 1 | 0).toString() + `:
+• ` + (
+          expectedCol > actualCol ? "Add" : "Remove"
+        ) + ` ` + Math.abs(expectedCol - actualCol | 0).toString() + ` space` + (
+          Math.abs(expectedCol - actualCol | 0) === 1 ? "" : "s"
+        ) + ` ` + (
+          expectedCol > actualCol ? "before" : "after"
+        ) + ` the '|' character
+• Use a monospace font editor to ensure proper alignment
+• Check that all '|' characters in this box are in the same column`
+      };
+    case "OverlappingBoxes" :
+      return {
+        title: "❌ Overlapping boxes detected",
+        message: `Two boxes overlap at ` + formatPosition(code.position) + ` but neither completely contains the other:
+• Box 1: ` + formatBoxName(code.box1Name) + `
+• Box 2: ` + formatBoxName(code.box2Name) + `
+
+Boxes must either:
+• Be completely nested (one fully inside the other), OR
+• Be completely separate (no overlap at all)`,
+        solution: `💡 Solution:
+Fix the overlap by either:
+1. Nesting: Make one box completely inside the other
+   • Ensure all four borders of the inner box are inside the outer box
+2. Separating: Move the boxes so they don't touch
+   • Add space between the boxes
+   • Or place them on different rows
+
+Partial overlaps are not allowed in the wireframe syntax.`
+      };
+    case "InvalidElement" :
+      return {
+        title: "❌ Invalid element syntax",
+        message: `Unrecognized element syntax at ` + formatPosition(code.position) + `:
+"` + code.content + `"
+
+The parser couldn't match this content to any known element pattern:
+• Buttons: [ Text ]
+• Inputs: #fieldname
+• Links: "Link Text"
+• Checkboxes: [x] or [ ]
+• Emphasis: * Text`,
+        solution: `💡 Solution:
+Check the element syntax and fix any typos:
+• Make sure brackets match: [ and ]
+• Ensure quotes are paired: "text"
+• Verify input fields start with #
+• Use supported element patterns from the documentation
+
+If this is plain text, it will be treated as a text element automatically.`
+      };
+    case "UnclosedBracket" :
+      return {
+        title: "❌ Unclosed bracket",
+        message: `Opening bracket '[' at ` + formatPosition(code.opening) + ` is never closed.
+
+This bracket starts a button or checkbox but has no matching closing ']' bracket.`,
+        solution: `💡 Solution:
+Add the closing ']' bracket to complete the element:
+• For buttons: [ Button Text ]
+• For checkboxes: [x] or [ ]
+
+Make sure both brackets are on the same line.`
+      };
+    case "EmptyButton" :
+      return {
+        title: "❌ Empty button",
+        message: `Button at ` + formatPosition(code.position) + ` has no text content.
+
+Buttons must have descriptive text between the brackets: [ Text ]`,
+        solution: `💡 Solution:
+Add text between the brackets:
+• Bad: [ ]
+• Good: [ Submit ]
+• Good: [ Click Here ]
+
+Button text should clearly describe the action.`
+      };
+    case "InvalidInteractionDSL" :
+      let position = code.position;
+      let posInfo = position !== undefined ? ` at ` + formatPosition(position) : "";
+      return {
+        title: "❌ Invalid interaction syntax",
+        message: `Failed to parse interaction DSL` + posInfo + `:
+` + code.message + `
+
+The interaction definition doesn't match the expected YAML-like syntax.`,
+        solution: `💡 Solution:
+Check your interaction syntax:
+• Scene declarations: @scene: sceneName
+• Element selectors: #input: or [ button ]:
+• Properties: indent with 2 spaces, use "key: value"
+• Actions: @click -> goto(target)
+
+Refer to the interaction DSL documentation for examples.`
+      };
+    case "UnusualSpacing" :
+      return {
+        title: "⚠️  Unusual spacing detected",
+        message: `Spacing issue at ` + formatPosition(code.position) + `:
+` + code.issue + `
+
+While this may still parse correctly, it could cause alignment problems in some environments.`,
+        solution: `💡 Solution:
+Normalize the spacing:
+• Use spaces instead of tabs for alignment
+• Use consistent spacing throughout the wireframe
+• Use a monospace font to verify alignment visually
+
+This is a warning - parsing will continue.`
+      };
+    case "DeepNesting" :
+      return {
+        title: "⚠️  Deep nesting detected",
+        message: `Box at ` + formatPosition(code.position) + ` is nested ` + code.depth.toString() + ` levels deep.
+
+While technically valid, deeply nested boxes can:
+• Reduce readability
+• Make maintenance difficult
+• Indicate overly complex UI structure`,
+        solution: `💡 Solution:
+Consider simplifying the structure:
+• Flatten the hierarchy where possible
+• Split complex sections into separate scenes
+• Use dividers (===) instead of nested boxes for simple grouping
+• Keep nesting to 3-4 levels maximum for best readability
+
+This is a warning - parsing will continue.`
+      };
+  }
+}
+
+function format(code) {
+  let template = getTemplate(code);
+  return template.title + `
+
+` + template.message + `
+
+` + template.solution;
+}
+
+function formatError(error) {
+  return format(error.code);
+}
+
+function formatWithContext(error) {
+  let template = getTemplate(error.code);
+  let parts = [];
+  parts.push(template.title);
+  parts.push("");
+  parts.push(template.message);
+  parts.push("");
+  let ctx = error.context;
+  if (ctx !== undefined) {
+    let snippet = ErrorContext.getSnippet(ctx);
+    parts.push("📍 Location:");
+    parts.push("");
+    parts.push(snippet);
+    parts.push("");
+  }
+  parts.push(template.solution);
+  return parts.join("\n");
+}
+
+function formatComplete(error) {
+  let match = error.context;
+  if (match !== undefined) {
+    return formatWithContext(error);
+  } else {
+    return format(error.code);
+  }
+}
+
+function getTitle(code) {
+  return getTemplate(code).title;
+}
+
+function getMessage(code) {
+  return getTemplate(code).message;
+}
+
+function getSolution(code) {
+  return getTemplate(code).solution;
+}
+
+export {
+  formatPosition,
+  formatBoxName,
+  getTemplate,
+  format,
+  formatError,
+  formatWithContext,
+  formatComplete,
+  getTitle,
+  getMessage,
+  getSolution,
+}
+/* ErrorContext Not a pure module */