fix: detect and warn about misaligned closing borders (#4)

Add MisalignedClosingBorder warning when closing '|' characters are not
aligned with the box border. The parser now:
- Traces boxes tolerantly even with misaligned interior rows
- Generates warnings with expected/actual column information
- Continues parsing successfully instead of failing

Changes:
- Add MisalignedClosingBorder error type and warning message
- Add validateInteriorAlignment function to BoxTracer
- Update ShapeDetector to collect and return warnings
- Change parseResult type to include warnings array
- Add 3 unit tests for the new warning detection

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: wickedev

README.md

@@ -105,19 +105,24 @@ switch Renderer.createUI(ui, None) {
 ```javascript
 import { parse, render, createUI, createUIOrThrow } from 'wyreframe';
 
-// Parse only
+// Parse only - returns { success, ast } or { success, errors }
 const result = parse(text);
 
-// Render only
-const { root, sceneManager } = render(ast);
+// Render only - IMPORTANT: pass result.ast, not result directly!
+if (result.success) {
+  const { root, sceneManager } = render(result.ast);
+}
 
-// Parse + Render (recommended)
+// Parse + Render (recommended) - handles the wrapper automatically
 const result = createUI(text);
 
 // Throw on error
 const { root, sceneManager } = createUIOrThrow(text);
 ```
 
+> **Note:** `parse()` returns a wrapper object `{ success: true, ast: AST }` or `{ success: false, errors: [] }`.
+> When using `render()` directly, make sure to pass `result.ast`, not the result object itself.
+
 ### ReScript
 
 ```rescript

src/index.ts

@@ -173,6 +173,7 @@ export interface RenderResult {
 export type ParseSuccessResult = {
   success: true;
   ast: AST;
+  warnings: ParseError[];
 };
 
 export type ParseErrorResult = {
@@ -199,6 +200,7 @@ export type CreateUISuccessResult = {
   root: HTMLElement;
   sceneManager: SceneManager;
   ast: AST;
+  warnings: ParseError[];
 };
 
 export type CreateUIErrorResult = {
@@ -246,10 +248,11 @@ type ReScriptResult<T, E> = ReScriptOk<T> | ReScriptError<E>;
  * ```
  */
 export function parse(text: string): ParseResult {
-  const result = Parser.parse(text) as ReScriptResult<AST, ParseError[]>;
+  const result = Parser.parse(text) as ReScriptResult<[AST, ParseError[]], ParseError[]>;
 
   if (result.TAG === 'Ok') {
-    return { success: true, ast: result._0 };
+    const [ast, warnings] = result._0;
+    return { success: true, ast, warnings };
   } else {
     return { success: false, errors: result._0 };
   }
@@ -294,10 +297,11 @@ export function parseOrThrow(text: string): AST {
  * @returns Parse result with success flag
  */
 export function parseWireframe(wireframe: string): ParseResult {
-  const result = Parser.parseWireframe(wireframe) as ReScriptResult<AST, ParseError[]>;
+  const result = Parser.parseWireframe(wireframe) as ReScriptResult<[AST, ParseError[]], ParseError[]>;
 
   if (result.TAG === 'Ok') {
-    return { success: true, ast: result._0 };
+    const [ast, warnings] = result._0;
+    return { success: true, ast, warnings };
   } else {
     return { success: false, errors: result._0 };
   }
@@ -336,6 +340,31 @@ export function parseInteractions(dsl: string): InteractionResult {
  * ```
  */
 export function render(ast: AST, options?: RenderOptions): RenderResult {
+  // Input validation: Check if user accidentally passed ParseResult instead of AST
+  if (ast && typeof ast === 'object' && 'success' in ast) {
+    const parseResult = ast as unknown as ParseResult;
+    if (parseResult.success === true && 'ast' in parseResult) {
+      throw new Error(
+        'render() expects an AST object, but received a ParseResult. ' +
+          'Did you forget to extract .ast? Use: render(result.ast) instead of render(result)'
+      );
+    } else if (parseResult.success === false) {
+      throw new Error(
+        'render() received a failed ParseResult. ' +
+          'Check parse errors before calling render: if (result.success) { render(result.ast); }'
+      );
+    }
+  }
+
+  // Validate AST structure
+  if (!ast || typeof ast !== 'object' || !Array.isArray(ast.scenes)) {
+    throw new Error(
+      'render() expects an AST object with a scenes array. ' +
+        'Did you pass ParseResult instead of ParseResult.ast? ' +
+        'Correct usage: const result = parse(text); if (result.success) { render(result.ast); }'
+    );
+  }
+
   // Pass undefined if no options, so ReScript uses its defaults
   const result = Renderer.render(ast, options);
 
@@ -380,6 +409,7 @@ export function createUI(text: string, options?: RenderOptions): CreateUIResult
     root,
     sceneManager,
     ast: parseResult.ast,
+    warnings: parseResult.warnings,
   };
 }
 

src/parser/Detector/BoxTracer.res

@@ -70,6 +70,90 @@ let isDividerOnlyEdge = (edgeChars: array<cellChar>): bool => {
   !hasHLineOrChar
 }
 
+/**
+ * Find the last Corner character below a given position in the same column.
+ * Simple version used for fallback width mismatch detection.
+ *
+ * @param grid - The 2D character grid
+ * @param startPos - Starting position (searches below this row)
+ * @returns Option of position where the last corner was found
+ */
+let findLastCornerInColumn = (grid: Grid.t, startPos: Position.t): option<Position.t> => {
+  let lastCorner = ref(None)
+  for row in startPos.row + 1 to grid.height - 1 {
+    let pos = Position.make(row, startPos.col)
+    switch Grid.get(grid, pos) {
+    | Some(Corner) => lastCorner := Some(pos)
+    | _ => ()
+    }
+  }
+  lastCorner.contents
+}
+
+/**
+ * Check if a row has any VLine character between left and right columns (inclusive).
+ * Used to determine if a row is part of a box (even with misaligned borders).
+ */
+let rowHasVLineInRange = (grid: Grid.t, row: int, leftCol: int, rightCol: int): bool => {
+  let found = ref(false)
+  let col = ref(leftCol)
+  while col.contents <= rightCol && !found.contents {
+    switch Grid.get(grid, Position.make(row, col.contents)) {
+    | Some(VLine) => found := true
+    | _ => ()
+    }
+    col := col.contents + 1
+  }
+  found.contents
+}
+
+/**
+ * Find the bottom-right corner of a box by scanning down from top-right.
+ *
+ * This is more tolerant than the strict scanDown approach:
+ * - Continues through rows with misaligned VLines (records for warnings)
+ * - Stops at rows with no VLine at all in the box's column range (box boundary)
+ * - Handles internal dividers (+=====+) correctly by finding the last corner
+ *
+ * @param grid - The 2D character grid
+ * @param topLeft - Position of top-left corner (for determining left boundary)
+ * @param topRight - Position of top-right corner (starting point for scan)
+ * @returns Option of position where the bottom-right corner was found
+ */
+let findBottomRightCorner = (grid: Grid.t, topLeft: Position.t, topRight: Position.t): option<Position.t> => {
+  let lastCorner = ref(None)
+  let row = ref(topRight.row + 1)
+  let continue = ref(true)
+
+  while row.contents < grid.height && continue.contents {
+    let pos = Position.make(row.contents, topRight.col)
+
+    switch Grid.get(grid, pos) {
+    | Some(Corner) => {
+        // Found a corner at the expected column - remember it
+        lastCorner := Some(pos)
+        row := row.contents + 1
+      }
+    | Some(VLine) => {
+        // Found a VLine at the expected column - continue scanning
+        row := row.contents + 1
+      }
+    | _ => {
+        // No VLine/Corner at expected column - check if row is part of this box
+        if rowHasVLineInRange(grid, row.contents, topLeft.col, topRight.col) {
+          // Row has a VLine somewhere (misaligned) - continue scanning
+          row := row.contents + 1
+        } else {
+          // No VLine in this row's box range - we've reached the end of the box
+          continue := false
+        }
+      }
+    }
+  }
+
+  lastCorner.contents
+}
+
 /**
  * Trace a box starting from the top-left corner position.
  *
@@ -134,38 +218,22 @@ let traceBox = (grid: Grid.t, topLeft: Position.t): traceResult => {
           // Calculate top width
           let topWidth = topRight.col - topLeft.col
 
-          // Step 4: Scan down from top-right to find bottom-right corner
-          let rightEdgeScan = Grid.scanDown(grid, topRight, isValidVerticalChar)
+          // Step 4: Find bottom-right corner by searching the column
+          // Use tolerant search that ignores interior rows with misaligned VLines
+          let bottomRightOpt = findBottomRightCorner(grid, topLeft, topRight)
 
-          let bottomRightOpt = {
-            let lastCorner = ref(None)
-            Array.forEach(rightEdgeScan, ((pos, cell)) => {
-              switch cell {
-              | Corner if !Position.equals(pos, topRight) => lastCorner := Some(pos)
-              | _ => ()
-              }
-            })
-            lastCorner.contents
-          }
+          // Store rightEdgeScan for later validation (after we know the box is valid)
+          let rightEdgeScan = Grid.scanDown(grid, topRight, isValidVerticalChar)
 
           switch bottomRightOpt {
           | None => {
-              // Right edge scan failed - could be width mismatch
-              // Try tracing from left side to detect width mismatch
-              let leftEdgeScan = Grid.scanDown(grid, topLeft, isValidVerticalChar)
-              let bottomLeftOpt = {
-                let lastCorner = ref(None)
-                Array.forEach(leftEdgeScan, ((pos, cell)) => {
-                  switch cell {
-                  | Corner if !Position.equals(pos, topLeft) => lastCorner := Some(pos)
-                  | _ => ()
-                  }
-                })
-                lastCorner.contents
-              }
+              // No corner found in the right column at topRight.col
+              // Try to detect width mismatch by finding bottom-left via left edge
+              let bottomLeftViaLeft = findLastCornerInColumn(grid, topLeft)
 
-              switch bottomLeftOpt {
+              switch bottomLeftViaLeft {
               | None =>
+                // No bottom-left corner found either - unclosed box
                 Error(
                   ErrorTypes.makeSimple(
                     ErrorTypes.UncloseBox({
@@ -212,7 +280,7 @@ let traceBox = (grid: Grid.t, topLeft: Position.t): traceResult => {
                           ),
                         )
                       } else {
-                        // Widths match but right edge still failed - unclosed box
+                        // Widths match but right edge corners don't align - unclosed box
                         Error(
                           ErrorTypes.makeSimple(
                             ErrorTypes.UncloseBox({
@@ -372,3 +440,80 @@ let traceBox = (grid: Grid.t, topLeft: Position.t): traceResult => {
     )
   }
 }
+
+/**
+ * Validate interior row alignment for a successfully traced box.
+ *
+ * Checks each row between the top and bottom borders to ensure:
+ * - The closing '|' character is at the expected column (bounds.right)
+ * - Generates MisalignedClosingBorder warnings for any misaligned rows
+ *
+ * This validation runs AFTER successful box tracing to detect visual
+ * alignment issues that don't prevent parsing but should be warned about.
+ *
+ * @param grid - The 2D character grid
+ * @param bounds - The bounds of the traced box
+ * @returns Array of warnings for any misaligned closing borders
+ */
+let validateInteriorAlignment = (grid: Grid.t, bounds: Bounds.t): array<ErrorTypes.t> => {
+  let warnings = []
+
+  // Check each interior row (excluding top and bottom border rows)
+  for row in bounds.top + 1 to bounds.bottom - 1 {
+    // Check if there's a VLine at the expected right border column
+    let expectedRightCol = bounds.right
+    let rightCell = Grid.get(grid, Position.make(row, expectedRightCol))
+
+    switch rightCell {
+    | Some(VLine) => () // Properly aligned, no warning needed
+    | Some(_) | None => {
+        // The expected column doesn't have a VLine
+        // Try to find where the actual closing '|' is on this row
+        // Search in both directions from the expected position
+        let actualCol = ref(None)
+
+        // First, search to the RIGHT of expectedRightCol (for pipes beyond the expected boundary)
+        // Search up to 50 chars beyond to catch misaligned pipes
+        let maxSearchRight = expectedRightCol + 50
+        let colRight = ref(expectedRightCol + 1)
+        while colRight.contents <= maxSearchRight && Option.isNone(actualCol.contents) {
+          switch Grid.get(grid, Position.make(row, colRight.contents)) {
+          | Some(VLine) => actualCol := Some(colRight.contents)
+          | _ => ()
+          }
+          colRight := colRight.contents + 1
+        }
+
+        // If not found to the right, search to the LEFT (for pipes before the expected boundary)
+        // But only if it's not the opening pipe (bounds.left)
+        if Option.isNone(actualCol.contents) {
+          let col = ref(expectedRightCol - 1)
+          while col.contents > bounds.left && Option.isNone(actualCol.contents) {
+            switch Grid.get(grid, Position.make(row, col.contents)) {
+            | Some(VLine) => actualCol := Some(col.contents)
+            | _ => ()
+            }
+            col := col.contents - 1
+          }
+        }
+
+        // If we found a VLine at a different position, generate a warning
+        switch actualCol.contents {
+        | Some(foundCol) if foundCol !== expectedRightCol => {
+            let warning = ErrorTypes.makeSimple(
+              ErrorTypes.MisalignedClosingBorder({
+                position: Position.make(row, foundCol),
+                expectedCol: expectedRightCol,
+                actualCol: foundCol,
+              }),
+            )
+            warnings->Array.push(warning)->ignore
+          }
+        | _ => () // No VLine found or it's at the correct position (already handled above)
+        }
+      }
+    }
+  }
+
+  warnings
+}