wyreframe 0.1.0

package/src/parser/Parser.res

@@ -0,0 +1,481 @@
+// WyreframeParser.res
+// Public API for Wyreframe Parser - ReScript Implementation
+// This module provides the main entry points for parsing wireframes and interactions.
+// All functions are exported to TypeScript via GenType annotations.
+
+// ============================================================================
+// Type Aliases for Public API
+// ============================================================================
+
+/**
+ * Parse result type - either a successful AST or an array of parse errors.
+ * This Result type is compatible with TypeScript through GenType.
+ */
+type parseResult = result<Types.ast, array<ErrorTypes.t>>
+
+/**
+ * Interaction parse result type.
+ */
+type interactionResult = result<array<Types.sceneInteractions>, array<ErrorTypes.t>>
+
+// ============================================================================
+// Type Aliases for Internal Use
+// ============================================================================
+
+// Box type from BoxTracer
+type box = BoxTracer.box
+
+// ============================================================================
+// Stage 1: Grid Scanner
+// ============================================================================
+
+/**
+ * Scan ASCII wireframe input into a 2D grid structure.
+ * Normalizes line endings and creates indexed grid.
+ *
+ * @param wireframe Raw ASCII wireframe string
+ * @returns Result containing Grid or errors
+ *
+ * Requirements: REQ-1, REQ-2 (Grid Scanner)
+ */
+let scanGrid = (wireframe: string): result<Grid.t, array<ErrorTypes.t>> => {
+  // Normalize line endings (CRLF -> LF, CR -> LF)
+  let normalized = wireframe->String.replaceAll("\r\n", "\n")->String.replaceAll("\r", "\n")
+
+  // Split into lines
+  let lines = normalized->String.split("\n")
+
+  // TODO: Add validation for unusual spacing (tabs vs spaces)
+  // This would generate UnusualSpacing warnings (REQ-19)
+
+  // Create grid structure
+  let grid = Grid.fromLines(lines)
+
+  Ok(grid)
+}
+
+// ============================================================================
+// Stage 2: Shape Detector
+// ============================================================================
+
+/**
+ * Detect all boxes and dividers in the grid.
+ *
+ * This function identifies boxes, traces their boundaries, detects dividers,
+ * and builds parent-child hierarchy.
+ *
+ * @param grid The 2D grid from Stage 1
+ * @returns Result containing root boxes or errors
+ *
+ * Requirements: REQ-3, REQ-4, REQ-5, REQ-6, REQ-7 (Shape Detection)
+ */
+let detectShapes = (grid: Grid.t): result<array<box>, array<ErrorTypes.t>> => {
+  // Use ShapeDetector to detect all shapes in the grid
+  ShapeDetector.detect(grid)
+}
+
+// ============================================================================
+// Stage 3: Semantic Parser
+// ============================================================================
+
+/**
+ * Convert BoxTracer.box to SemanticParser.box
+ * The types are structurally identical except BoxTracer has mutable children
+ */
+let rec convertBox = (tracerBox: box): SemanticParser.box => {
+  {
+    name: tracerBox.name,
+    bounds: tracerBox.bounds,
+    children: tracerBox.children->Array.map(convertBox),
+  }
+}
+
+/**
+ * Parse box contents into semantic elements and build AST.
+ *
+ * This function extracts content, recognizes elements, calculates alignment,
+ * parses scene directives, and builds the complete AST.
+ *
+ * @param grid The 2D grid from Stage 1
+ * @param shapes Root boxes from Stage 2
+ * @returns Result containing AST or errors
+ *
+ * Requirements: REQ-8 through REQ-15 (Semantic Parser)
+ */
+let parseSemantics = (
+  grid: Grid.t,
+  shapes: array<box>,
+): result<Types.ast, array<ErrorTypes.t>> => {
+  // Create parser registry with all element parsers
+  let registry = ParserRegistry.makeDefault()
+
+  // Convert BoxTracer boxes to SemanticParser boxes
+  let semanticBoxes = shapes->Array.map(convertBox)
+
+  // Build parse context
+  let context: SemanticParser.parseContext = {
+    gridCells: grid.cells,
+    shapes: semanticBoxes,
+    registry: registry,
+  }
+
+  // Parse semantics using SemanticParser
+  SemanticParser.parse(context)
+}
+
+// ============================================================================
+// Interaction DSL Parser (Optional)
+// ============================================================================
+
+/**
+ * Parse interaction DSL and return interaction definitions.
+ *
+ * @param dsl Interaction DSL string
+ * @returns Result containing interactions or errors
+ *
+ * Requirements: Interaction DSL Parser
+ */
+let parseInteractionsDSL = (
+  dsl: string,
+): result<array<Types.sceneInteractions>, array<ErrorTypes.t>> => {
+  // Parse interactions using InteractionParser
+  switch InteractionParser.parse(dsl) {
+  | Ok(interactions) => Ok(interactions)
+  | Error({message, position}) => {
+      // Convert InteractionParser error to ErrorTypes.t
+      let error = ErrorTypes.make(
+        InvalidInteractionDSL({
+          message: message,
+          position: position,
+        }),
+        None,
+      )
+      Error([error])
+    }
+  }
+}
+
+/**
+ * Merge interaction definitions into the AST.
+ *
+ * Matches interactions to elements by ID and attaches properties and actions.
+ *
+ * @param ast Base AST from semantic parsing
+ * @param sceneInteractions Interaction definitions grouped by scene
+ * @returns AST with interactions merged in
+ *
+ * Requirements: Integration
+ */
+let mergeInteractionsIntoAST = (
+  ast: Types.ast,
+  sceneInteractions: array<Types.sceneInteractions>,
+): Types.ast => {
+  // Merge interactions using InteractionMerger
+  switch InteractionMerger.mergeInteractions(ast, sceneInteractions) {
+  | Ok(mergedAst) => mergedAst
+  | Error(_errors) => {
+      // If merging fails, return AST without interactions
+      // Errors are silent - this maintains backward compatibility
+      ast
+    }
+  }
+}
+
+// ============================================================================
+// Main Public API Functions
+// ============================================================================
+
+/**
+ * Parse a single scene block through the 3-stage pipeline.
+ *
+ * @param sceneContent ASCII wireframe content for one scene (without directives)
+ * @param sceneMetadata Scene metadata from directives
+ * @param errors Accumulator for errors
+ * @returns Parsed scene or None if parsing failed
+ */
+let parseSingleScene = (
+  sceneContent: string,
+  sceneMetadata: SemanticParser.sceneMetadata,
+  errors: array<ErrorTypes.t>,
+): option<Types.scene> => {
+  // Stage 1: Grid Scanner
+  let gridResult = scanGrid(sceneContent)
+
+  switch gridResult {
+  | Error(gridErrors) => {
+      gridErrors->Array.forEach(err => errors->Array.push(err)->ignore)
+      None
+    }
+  | Ok(grid) => {
+      // Stage 2: Shape Detector
+      let shapesResult = detectShapes(grid)
+
+      let shapes = switch shapesResult {
+      | Error(shapeErrors) => {
+          shapeErrors->Array.forEach(err => errors->Array.push(err)->ignore)
+          []
+        }
+      | Ok(shapes) => shapes
+      }
+
+      // Stage 3: Parse box content into elements
+      let registry = ParserRegistry.makeDefault()
+      let semanticBoxes = shapes->Array.map(convertBox)
+
+      // Parse each box recursively
+      // parseBoxRecursive returns a Box element with children inside
+      // Strategy:
+      // - Named boxes (e.g., "Login", "Level1") are semantically meaningful → keep them
+      // - Unnamed boxes are just visual containers → flatten to children only
+      // This prevents duplication: children are only inside the Box, NOT duplicated at scene level
+      let elements = semanticBoxes->Array.flatMap(box => {
+        let boxElement = SemanticParser.parseBoxRecursive(box, grid.cells, registry)
+        switch boxElement {
+        | Box({name: Some(_), _}) as namedBox => [namedBox]  // Keep named boxes
+        | Box({name: None, children, _}) => children         // Flatten unnamed boxes
+        | elem => [elem]
+        }
+      })
+
+      // Build scene from metadata and elements
+      Some({
+        id: sceneMetadata.id,
+        title: sceneMetadata.title,
+        transition: sceneMetadata.transition,
+        device: sceneMetadata.device,
+        elements: elements,
+      })
+    }
+  }
+}
+
+/**
+ * Internal parsing function - parses wireframe and optional interactions separately.
+ *
+ * This executes the complete 3-stage pipeline for each scene:
+ * 1. Split wireframe by scene separators ("---")
+ * 2. For each scene:
+ *    a. Parse scene directives (@scene, @title, @transition)
+ *    b. Grid Scanner - converts ASCII to 2D grid
+ *    c. Shape Detector - identifies boxes and hierarchy
+ *    d. Semantic Parser - recognizes elements and builds scene
+ * 3. Combine all scenes into AST
+ *
+ * Optionally parses and merges interaction DSL if provided.
+ *
+ * Error Handling:
+ * - Collects errors from all stages
+ * - Returns all errors together (no early stopping)
+ * - Continues parsing even after non-fatal errors
+ *
+ * @param wireframe ASCII wireframe string (may contain multiple scenes)
+ * @param interactions Optional interaction DSL string
+ * @returns Result containing AST or array of parse errors
+ */
+let parseInternal = (wireframe: string, interactions: option<string>): parseResult => {
+  // Accumulator for all errors across stages
+  let allErrors = []
+
+  // Split wireframe into scene blocks
+  let sceneBlocks = SemanticParser.splitSceneBlocks(wireframe)
+
+  // Check if wireframe is empty
+  let trimmed = wireframe->String.trim
+  if sceneBlocks->Array.length === 0 && trimmed === "" {
+    // Empty wireframe - return empty AST
+    Ok({scenes: []})
+  } else {
+    // Parse each scene block
+    let scenes = []
+
+    sceneBlocks->Array.forEach(block => {
+      // Parse scene directives
+      let lines = block->String.split("\n")
+      let (metadata, contentLines) = SemanticParser.parseSceneDirectives(lines)
+
+      // Rejoin content lines (without directives)
+      let sceneContent = contentLines->Array.join("\n")
+
+      // Parse this scene through 3-stage pipeline
+      switch parseSingleScene(sceneContent, metadata, allErrors) {
+      | Some(scene) => scenes->Array.push(scene)->ignore
+      | None => () // Scene parsing failed, errors already collected
+      }
+    })
+
+    // Build base AST from scenes
+    let baseAst: Types.ast = {scenes: scenes}
+
+    // Optional: Parse and merge interactions
+    let finalAst = switch interactions {
+    | None => baseAst
+    | Some(dsl) => {
+        let interactionsResult = parseInteractionsDSL(dsl)
+
+        switch interactionsResult {
+        | Error(errors) => {
+            errors->Array.forEach(err => allErrors->Array.push(err)->ignore)
+            baseAst // Return AST without interactions on error
+          }
+        | Ok(sceneInteractions) => {
+            // Merge interactions into AST
+            mergeInteractionsIntoAST(baseAst, sceneInteractions)
+          }
+        }
+      }
+    }
+
+    // Return final result
+    // Return Error if all boxes failed to parse and we have errors
+    // Return Ok if at least some elements were parsed successfully
+    let totalElements = finalAst.scenes->Array.reduce(0, (acc, scene) => {
+      acc + Array.length(scene.elements)
+    })
+
+    if Array.length(allErrors) > 0 && totalElements === 0 {
+      // No elements parsed and we have errors - return error
+      Error(allErrors)
+    } else {
+      // Either no errors, or some elements were parsed - return Ok
+      Ok(finalAst)
+    }
+  }
+}
+
+/**
+ * Main parsing function - parses mixed text containing wireframe and interactions.
+ *
+ * This function accepts a single text input that can contain:
+ * - ASCII wireframe (boxes with +---+, | |, etc.)
+ * - Interaction DSL (#id:, [Button]:, "Link": with properties)
+ * - Markdown, comments, or other noise (automatically ignored)
+ *
+ * The parser intelligently extracts wireframe and interaction content,
+ * allowing you to write everything in one place.
+ *
+ * Example:
+ * ```
+ * @scene: login
+ *
+ * +---------------------------+
+ * |       'WYREFRAME'         |
+ * |  +---------------------+  |
+ * |  | #email              |  |
+ * |  +---------------------+  |
+ * |       [ Login ]           |
+ * +---------------------------+
+ *
+ * #email:
+ *   placeholder: "Enter your email"
+ *
+ * [Login]:
+ *   @click -> goto(dashboard)
+ * ```
+ *
+ * @param text Mixed text containing wireframe and/or interactions
+ * @returns Result containing AST or array of parse errors
+ *
+ * REQ-20: Backward Compatibility
+ * REQ-21: Public API Stability
+ * REQ-28: Error Recovery (collect all errors)
+ */
+@genType
+let parse = (text: string): parseResult => {
+  // Extract wireframe and interactions from mixed content
+  let extracted = TextExtractor.extract(text)
+
+  // Parse with extracted content
+  let interactions = if extracted.interactions->String.trim === "" {
+    None
+  } else {
+    Some(extracted.interactions)
+  }
+
+  parseInternal(extracted.wireframe, interactions)
+}
+
+/**
+ * Parse only the wireframe structure (no interactions).
+ * Convenience function that calls parseInternal(wireframe, None).
+ *
+ * @param wireframe ASCII wireframe string
+ * @returns Result containing AST or array of parse errors
+ *
+ * REQ-21: Public API Stability
+ */
+@genType
+let parseWireframe = (wireframe: string): parseResult => {
+  parseInternal(wireframe, None)
+}
+
+/**
+ * Parse only the interaction DSL.
+ * Useful when interactions are defined separately from the wireframe structure.
+ *
+ * @param dsl Interaction DSL string
+ * @returns Result containing scene interactions or array of parse errors
+ *
+ * REQ-21: Public API Stability
+ */
+@genType
+let parseInteractions = (dsl: string): interactionResult => {
+  parseInteractionsDSL(dsl)
+}
+
+/**
+ * Merge interaction definitions into an existing AST.
+ * Attaches properties and actions to elements based on element IDs.
+ *
+ * @param ast Base AST from wireframe parsing
+ * @param sceneInteractions Array of scene interactions to merge
+ * @returns AST with interactions merged into elements
+ *
+ * Integration requirement
+ */
+@genType
+let mergeInteractions = (
+  ast: Types.ast,
+  _sceneInteractions: array<Types.sceneInteractions>,
+): Types.ast => {
+  // TODO: Implement AST merger
+  // Match interactions to elements by ID
+  // Validate all element IDs exist
+  // Attach properties and actions
+
+  // Placeholder - return unchanged AST
+  ast
+}
+
+// ============================================================================
+// Helper Functions (Not exported to TypeScript)
+// ============================================================================
+
+/**
+ * Collect all errors from multiple parsing stages.
+ * Ensures all errors are reported, not just the first one (REQ-28).
+ */
+let collectErrors = (
+  gridErrors: array<ErrorTypes.t>,
+  shapeErrors: array<ErrorTypes.t>,
+  semanticErrors: array<ErrorTypes.t>,
+): array<ErrorTypes.t> => {
+  [gridErrors, shapeErrors, semanticErrors]->Array.flatMap(x => x)
+}
+
+// ============================================================================
+// Version Information
+// ============================================================================
+
+/**
+ * Parser version string.
+ * Exported to TypeScript for version checking and compatibility validation.
+ */
+@genType
+let version = "0.1.0"
+
+/**
+ * Parser implementation identifier.
+ * Useful for distinguishing between legacy JavaScript and new ReScript parser.
+ */
+@genType
+let implementation = "rescript"

package/src/parser/Scanner/__tests__/Grid_manual.mjs

@@ -0,0 +1,214 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Grid from "../../Core/Grid.mjs";
+import * as Types from "../../Core/Types.mjs";
+import * as Core__Array from "@rescript/core/src/Core__Array.mjs";
+import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+
+function check(condition, message) {
+  if (condition) {
+    console.log("✓ PASS: " + message);
+  } else {
+    console.error("✗ FAIL: " + message);
+  }
+}
+
+function assertEqual(actual, expected, message) {
+  if (Primitive_object.equal(actual, expected)) {
+    console.log("✓ PASS: " + message);
+  } else {
+    console.error("✗ FAIL: " + message);
+  }
+}
+
+console.log("\n=== Grid Construction Tests ===\n");
+
+let lines1 = [
+  "abc",
+  "def",
+  "ghi"
+];
+
+let grid1 = Grid.fromLines(lines1);
+
+assertEqual(grid1.width, 3, "Grid width for uniform lines");
+
+assertEqual(grid1.height, 3, "Grid height for uniform lines");
+
+let lines2 = [
+  "abc",
+  "de",
+  "f"
+];
+
+let grid2 = Grid.fromLines(lines2);
+
+assertEqual(grid2.width, 3, "Grid width after normalization");
+
+assertEqual(grid2.height, 3, "Grid height after normalization");
+
+let lines3 = [
+  "+--+",
+  "|  |",
+  "+--+"
+];
+
+let grid3 = Grid.fromLines(lines3);
+
+assertEqual(grid3.cornerIndex.length, 4, "Corner index count");
+
+assertEqual(grid3.hLineIndex.length, 4, "HLine index count");
+
+assertEqual(grid3.vLineIndex.length, 2, "VLine index count");
+
+console.log("\n=== Character Access Tests ===\n");
+
+let match = Grid.get(grid3, Types.Position.make(0, 0));
+
+if (match === "Corner" && typeof match !== "object") {
+  console.log("✓ PASS: Get character at (0,0) returns Corner");
+} else {
+  console.error("✗ FAIL: Get character at (0,0) should return Corner");
+}
+
+let match$1 = Grid.get(grid3, Types.Position.make(10, 10));
+
+if (match$1 !== undefined) {
+  console.error("✗ FAIL: Get character out of bounds should return None");
+} else {
+  console.log("✓ PASS: Get character out of bounds returns None");
+}
+
+let line = Grid.getLine(grid3, 0);
+
+if (line !== undefined) {
+  assertEqual(line.length, 4, "Get line returns correct length");
+} else {
+  console.error("✗ FAIL: Get line should return Some");
+}
+
+console.log("\n=== Directional Scanning Tests ===\n");
+
+let scanResults = Grid.scanRight(grid3, Types.Position.make(0, 0), cell => {
+  if (typeof cell === "object") {
+    return false;
+  }
+  switch (cell) {
+    case "Corner" :
+    case "HLine" :
+      return true;
+    default:
+      return false;
+  }
+});
+
+assertEqual(scanResults.length, 4, "Scan right collects correct number of characters");
+
+let scanDownResults = Grid.scanDown(grid3, Types.Position.make(0, 0), cell => {
+  if (typeof cell === "object") {
+    return false;
+  }
+  switch (cell) {
+    case "Corner" :
+    case "VLine" :
+      return true;
+    default:
+      return false;
+  }
+});
+
+assertEqual(scanDownResults.length, 3, "Scan down collects correct number of characters");
+
+console.log("\n=== Search Operations Tests ===\n");
+
+let allCorners = Grid.findAll(grid3, "Corner");
+
+assertEqual(allCorners.length, 4, "Find all corners returns 4 positions");
+
+let bounds = Types.Bounds.make(0, 0, 1, 2);
+
+let cornersInRange = Grid.findInRange(grid3, "Corner", bounds);
+
+assertEqual(cornersInRange.length, 1, "Find in range returns corners within bounds");
+
+console.log("\n=== Performance Tests ===\n");
+
+let largeLines = Core__Array.make(1000, "+".repeat(100));
+
+let startTime = Date.now();
+
+let largeGrid = Grid.fromLines(largeLines);
+
+let endTime = Date.now();
+
+let duration = endTime - startTime;
+
+assertEqual(largeGrid.height, 1000, "Large grid has correct height");
+
+assertEqual(largeGrid.width, 100, "Large grid has correct width");
+
+check(duration < 10.0, `Grid construction <10ms (actual: ` + duration.toString() + `ms)`);
+
+let findStartTime = Date.now();
+
+let _corners = Grid.findAll(largeGrid, "Corner");
+
+let findEndTime = Date.now();
+
+let findDuration = findEndTime - findStartTime;
+
+check(findDuration < 5.0, `Finding all corners using index <5ms (actual: ` + findDuration.toString() + `ms)`);
+
+console.log("\n=== Edge Cases Tests ===\n");
+
+let singleCharLines = ["+"];
+
+let singleCharGrid = Grid.fromLines(singleCharLines);
+
+assertEqual(singleCharGrid.width, 1, "Single character grid width");
+
+assertEqual(singleCharGrid.height, 1, "Single character grid height");
+
+let emptyLines = [
+  "",
+  "",
+  ""
+];
+
+let emptyGrid = Grid.fromLines(emptyLines);
+
+assertEqual(emptyGrid.width, 0, "Empty lines grid width is 0");
+
+assertEqual(emptyGrid.height, 3, "Empty lines grid height is 3");
+
+console.log("\n=== All Tests Complete ===\n");
+
+export {
+  check,
+  assertEqual,
+  lines1,
+  grid1,
+  lines2,
+  grid2,
+  lines3,
+  grid3,
+  scanResults,
+  scanDownResults,
+  allCorners,
+  bounds,
+  cornersInRange,
+  largeLines,
+  startTime,
+  largeGrid,
+  endTime,
+  duration,
+  findStartTime,
+  _corners,
+  findEndTime,
+  findDuration,
+  singleCharLines,
+  singleCharGrid,
+  emptyLines,
+  emptyGrid,
+}
+/*  Not a pure module */