yuho 5.0.0__py3-none-any.whl

yuho/cli/commands/ast_viz.py

@@ -0,0 +1,334 @@
+"""
+AST visualization command for Yuho.
+
+Displays statute AST structure as tree-like ASCII output in terminal.
+"""
+
+from pathlib import Path
+from typing import Optional, List, Dict, Any, Tuple
+
+import click
+
+
+# Box-drawing characters for tree
+TREE_CHARS = {
+    "pipe": "│",
+    "tee": "├",
+    "elbow": "└",
+    "dash": "─",
+    "space": " ",
+}
+
+# Minimal fallback for terminals without unicode
+TREE_CHARS_ASCII = {
+    "pipe": "|",
+    "tee": "+",
+    "elbow": "`",
+    "dash": "-",
+    "space": " ",
+}
+
+
+class ASTVisualizer:
+    """Generates tree visualization of Yuho AST."""
+    
+    def __init__(self, use_color: bool = True, use_unicode: bool = True):
+        self.use_color = use_color
+        self.chars = TREE_CHARS if use_unicode else TREE_CHARS_ASCII
+        self.lines: List[str] = []
+    
+    def colorize(self, text: str, color: str, bold: bool = False) -> str:
+        """Apply color if enabled."""
+        if not self.use_color:
+            return text
+        return click.style(text, fg=color, bold=bold)
+    
+    def _get_node_display(self, node: Any) -> Tuple[str, str]:
+        """
+        Get display text and color for a node.
+        
+        Returns:
+            (display_text, color)
+        """
+        node_type = type(node).__name__
+        
+        # Map node types to colors and display format
+        type_info = {
+            "Statute": ("cyan", True),
+            "Section": ("blue", True),
+            "Definitions": ("yellow", False),
+            "Definition": ("yellow", False),
+            "Elements": ("green", False),
+            "Element": ("green", False),
+            "ActusReus": ("green", False),
+            "MensRea": ("green", False),
+            "Circumstance": ("green", False),
+            "Penalty": ("red", False),
+            "PenaltyClause": ("red", False),
+            "Imprisonment": ("red", False),
+            "Fine": ("red", False),
+            "Illustrations": ("magenta", False),
+            "Illustration": ("magenta", False),
+            "Import": ("white", False),
+            "TypeDecl": ("cyan", False),
+            "FuncDecl": ("cyan", False),
+            "Block": ("white", False),
+            "Program": ("cyan", True),
+        }
+        
+        color, bold = type_info.get(node_type, ("white", False))
+        
+        # Build display text with node-specific info
+        display = node_type
+        
+        if hasattr(node, "section_number"):
+            display = f"{node_type}[{node.section_number}]"
+        elif hasattr(node, "title") and node.title:
+            title = node.title[:30] + "..." if len(str(node.title)) > 30 else node.title
+            display = f"{node_type}: {title}"
+        elif hasattr(node, "name") and node.name:
+            display = f"{node_type}: {node.name}"
+        elif hasattr(node, "term") and node.term:
+            display = f"{node_type}: {node.term}"
+        elif hasattr(node, "label") and node.label:
+            display = f"{node_type}: {node.label}"
+        elif hasattr(node, "element_type"):
+            display = f"{node_type}({node.element_type})"
+        
+        return display, color
+    
+    def _get_children(self, node: Any) -> List[Tuple[str, Any]]:
+        """
+        Get child nodes with their attribute names.
+        
+        Returns:
+            List of (attribute_name, child_node) tuples
+        """
+        children = []
+        
+        # Known container attributes
+        container_attrs = [
+            "statutes", "sections", "statements", "items", "children",
+            "definitions", "elements", "illustrations", "penalties",
+            "clauses", "imports", "declarations", "blocks", "body",
+        ]
+        
+        # Check for container attributes first
+        for attr in container_attrs:
+            if hasattr(node, attr):
+                items = getattr(node, attr)
+                if isinstance(items, (list, tuple)):
+                    for i, item in enumerate(items):
+                        if item is not None:
+                            children.append((f"{attr}[{i}]", item))
+        
+        # Check for single child attributes
+        single_attrs = [
+            "statute", "section", "penalty", "definition", "element",
+            "illustration", "actus_reus", "mens_rea", "circumstance",
+            "imprisonment", "fine", "supplementary", "condition",
+            "consequence", "left", "right", "value", "expression",
+        ]
+        
+        for attr in single_attrs:
+            if hasattr(node, attr):
+                child = getattr(node, attr)
+                if child is not None and not isinstance(child, (str, int, float, bool)):
+                    children.append((attr, child))
+        
+        return children
+    
+    def _render_node(
+        self,
+        node: Any,
+        prefix: str = "",
+        is_last: bool = True,
+        show_attr: str = "",
+    ) -> None:
+        """Recursively render a node and its children."""
+        # Determine connector
+        if prefix:
+            connector = self.chars["elbow"] if is_last else self.chars["tee"]
+            connector += self.chars["dash"] * 2 + " "
+        else:
+            connector = ""
+        
+        # Get display text
+        display, color = self._get_node_display(node)
+        
+        # Add attribute name if provided
+        if show_attr:
+            attr_text = self.colorize(f"{show_attr}: ", "white")
+        else:
+            attr_text = ""
+        
+        # Build line
+        node_text = self.colorize(display, color, bold=(color == "cyan"))
+        self.lines.append(f"{prefix}{connector}{attr_text}{node_text}")
+        
+        # Get children
+        children = self._get_children(node)
+        
+        # Calculate new prefix for children
+        if prefix:
+            if is_last:
+                new_prefix = prefix + "    "
+            else:
+                new_prefix = prefix + self.chars["pipe"] + "   "
+        else:
+            new_prefix = ""
+        
+        # Render children
+        for i, (attr, child) in enumerate(children):
+            is_last_child = (i == len(children) - 1)
+            self._render_node(child, new_prefix, is_last_child, attr)
+    
+    def visualize(self, ast: Any) -> str:
+        """
+        Generate tree visualization of AST.
+        
+        Args:
+            ast: The AST root node
+            
+        Returns:
+            String containing the tree visualization
+        """
+        self.lines = []
+        
+        # Handle list of nodes
+        if isinstance(ast, (list, tuple)):
+            for i, node in enumerate(ast):
+                is_last = (i == len(ast) - 1)
+                self._render_node(node, "", is_last)
+        else:
+            self._render_node(ast, "", True)
+        
+        return "\n".join(self.lines)
+
+
+def format_ast_stats(ast: Any) -> Dict[str, int]:
+    """
+    Collect statistics about the AST.
+    
+    Returns:
+        Dict mapping node type to count
+    """
+    stats: Dict[str, int] = {}
+    
+    def visit(node: Any) -> None:
+        if node is None:
+            return
+        
+        if isinstance(node, (list, tuple)):
+            for item in node:
+                visit(item)
+            return
+        
+        # Count this node type
+        node_type = type(node).__name__
+        stats[node_type] = stats.get(node_type, 0) + 1
+        
+        # Visit all attributes that might contain children
+        for attr in dir(node):
+            if attr.startswith("_"):
+                continue
+            try:
+                value = getattr(node, attr)
+                if isinstance(value, (list, tuple)):
+                    for item in value:
+                        if hasattr(item, "__class__") and not isinstance(item, (str, int, float, bool)):
+                            visit(item)
+                elif hasattr(value, "__class__") and not isinstance(value, (str, int, float, bool, type(None))):
+                    if not callable(value):
+                        visit(value)
+            except (AttributeError, TypeError):
+                pass
+    
+    visit(ast)
+    return stats
+
+
+def run_ast_viz(
+    file: str,
+    output: Optional[str] = None,
+    stats: bool = False,
+    depth: int = 0,
+    no_unicode: bool = False,
+    verbose: bool = False,
+    color: bool = True,
+) -> None:
+    """
+    Run AST visualization command.
+    
+    Args:
+        file: Input .yh file
+        output: Output file path (None = stdout)
+        stats: Show statistics
+        depth: Max depth (0 = unlimited)
+        no_unicode: Use ASCII-only characters
+        verbose: Verbose output
+        color: Use colors
+    """
+    path = Path(file)
+    
+    if not path.exists():
+        click.echo(f"Error: File not found: {file}", err=True)
+        raise SystemExit(1)
+    
+    # Read source
+    source = path.read_text()
+    
+    # Parse
+    try:
+        from yuho.parser.scanner import Scanner
+        from yuho.parser.parser import Parser
+        from yuho.ast.builder import ASTBuilder
+        
+        scanner = Scanner(source)
+        tokens = scanner.scan_tokens()
+        
+        parser = Parser(tokens)
+        tree = parser.parse()
+        
+        builder = ASTBuilder()
+        ast = builder.build(tree)
+        
+    except Exception as e:
+        click.echo(f"Parse error: {e}", err=True)
+        raise SystemExit(1)
+    
+    # Visualize
+    visualizer = ASTVisualizer(use_color=color, use_unicode=not no_unicode)
+    tree_output = visualizer.visualize(ast)
+    
+    # Build output
+    lines = []
+    
+    # Header
+    if verbose:
+        lines.append(click.style(f"AST for: {path.name}", fg="cyan", bold=True))
+        lines.append(click.style("=" * 50, fg="cyan"))
+        lines.append("")
+    
+    lines.append(tree_output)
+    
+    # Stats
+    if stats:
+        lines.append("")
+        lines.append(click.style("Statistics:", fg="yellow", bold=True))
+        lines.append(click.style("-" * 30, fg="yellow"))
+        
+        ast_stats = format_ast_stats(ast)
+        for node_type, count in sorted(ast_stats.items()):
+            lines.append(f"  {node_type}: {count}")
+        lines.append(f"  {'─' * 20}")
+        lines.append(f"  Total nodes: {sum(ast_stats.values())}")
+    
+    result = "\n".join(lines)
+    
+    # Output
+    if output:
+        Path(output).write_text(result)
+        click.echo(f"Written to {output}")
+    else:
+        click.echo(result)

yuho/cli/commands/check.py

@@ -0,0 +1,218 @@
+"""
+Check command - parse and validate Yuho files.
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+import click
+
+from yuho.parser import Parser
+from yuho.ast import ASTBuilder
+from yuho.cli.error_formatter import format_errors, format_suggestion, Colors, colorize
+
+
+# Detailed explanations for common error patterns
+ERROR_EXPLANATIONS = {
+    "Unexpected syntax": """
+This error occurs when the parser encounters code it doesn't recognize.
+
+Common causes:
+  - Missing or extra punctuation (commas, braces, colons)
+  - Typo in a keyword (e.g., 'strcut' instead of 'struct')
+  - Using syntax from another language that Yuho doesn't support
+  - Incomplete statement or expression
+
+How to fix:
+  1. Check for typos in keywords: struct, fn, match, case, consequence, etc.
+  2. Ensure all braces {{ }} and parentheses ( ) are balanced
+  3. Verify that statements are complete (not cut off mid-expression)
+  4. Compare your code against examples in the documentation
+""",
+    "Missing semicolon": """
+Yuho doesn't require semicolons in most places, but they can be used
+optionally at the end of statements.
+
+This error usually means the parser expected a statement terminator
+but found something else. Check that:
+  - The previous statement is complete
+  - You're not missing a closing brace or parenthesis
+  - Field assignments in structs are separated by commas
+""",
+    "Missing closing brace": """
+A closing brace '}}' is expected but was not found.
+
+Common causes:
+  - Forgetting to close a struct, function, or match block
+  - Nested braces that don't match up
+  - An error earlier in the file causing the parser to get confused
+
+How to fix:
+  1. Count your opening {{ and closing }} braces - they should match
+  2. Use editor features to highlight matching braces
+  3. Look for the last complete block before the error
+""",
+    "Expected identifier": """
+An identifier (name) was expected but something else was found.
+
+In Yuho, identifiers:
+  - Start with a letter or underscore
+  - Can contain letters, numbers, and underscores
+  - Are case-sensitive
+  - Cannot be reserved keywords
+
+Examples of valid identifiers: myVar, _private, CamelCase, snake_case
+""",
+    "Expected type annotation": """
+A type annotation was expected but not found.
+
+In Yuho, variable declarations require explicit types:
+
+  Correct:   int count := 0
+  Incorrect: count := 0
+
+Built-in types: int, float, bool, string, money, percent, date, duration
+User-defined types: Any struct name you've defined
+""",
+    "MISSING": """
+The parser expected to find something that wasn't there.
+
+This usually indicates incomplete code. Check that:
+  - All statements and expressions are complete
+  - Required parts of syntax aren't missing
+  - The file didn't get truncated
+""",
+}
+
+
+def get_error_explanation(error_message: str, node_type: Optional[str]) -> Optional[str]:
+    """Get a detailed explanation for an error."""
+    # Check node type first
+    if node_type and node_type.startswith("MISSING:"):
+        missing_what = node_type.replace("MISSING:", "")
+        if missing_what in ERROR_EXPLANATIONS:
+            return ERROR_EXPLANATIONS[missing_what]
+        return ERROR_EXPLANATIONS.get("MISSING")
+
+    # Check error message patterns
+    for pattern, explanation in ERROR_EXPLANATIONS.items():
+        if pattern in error_message:
+            return explanation
+
+    return None
+
+
+def run_check(
+    file: str,
+    json_output: bool = False,
+    verbose: bool = False,
+    explain_errors: bool = False,
+) -> None:
+    """
+    Parse and validate a Yuho source file.
+
+    Args:
+        file: Path to the .yh file
+        json_output: Output errors as JSON
+        verbose: Enable verbose output
+        explain_errors: Show detailed explanations for errors
+    """
+    file_path = Path(file)
+
+    if verbose:
+        click.echo(f"Checking {file_path}...")
+
+    # Parse the file
+    parser = Parser()
+    try:
+        result = parser.parse_file(file_path)
+    except FileNotFoundError:
+        if json_output:
+            print(json.dumps({"valid": False, "errors": [{"message": f"File not found: {file}"}]}))
+        else:
+            click.echo(colorize(f"error: File not found: {file}", Colors.RED), err=True)
+        sys.exit(1)
+    except UnicodeDecodeError as e:
+        if json_output:
+            print(json.dumps({"valid": False, "errors": [{"message": f"Invalid UTF-8: {e}"}]}))
+        else:
+            click.echo(colorize(f"error: Invalid UTF-8 encoding: {e}", Colors.RED), err=True)
+        sys.exit(1)
+
+    # Report parse errors
+    if result.errors:
+        if json_output:
+            errors_json = [
+                {
+                    "message": err.message,
+                    "location": {
+                        "file": err.location.file,
+                        "line": err.location.line,
+                        "col": err.location.col,
+                        "end_line": err.location.end_line,
+                        "end_col": err.location.end_col,
+                    },
+                    "node_type": err.node_type,
+                    "explanation": get_error_explanation(err.message, err.node_type) if explain_errors else None,
+                }
+                for err in result.errors
+            ]
+            print(json.dumps({"valid": False, "errors": errors_json}, indent=2))
+        else:
+            error_output = format_errors(result.errors, result.source, str(file_path))
+            click.echo(error_output, err=True)
+
+            # Add suggestions
+            for err in result.errors:
+                suggestion = format_suggestion(err, result.source)
+                if suggestion:
+                    click.echo(colorize(f"  hint: {suggestion}", Colors.YELLOW), err=True)
+
+                # Add detailed explanation if requested
+                if explain_errors:
+                    explanation = get_error_explanation(err.message, err.node_type)
+                    if explanation:
+                        click.echo(colorize("\n  Explanation:", Colors.CYAN + Colors.BOLD), err=True)
+                        for line in explanation.strip().split("\n"):
+                            click.echo(colorize(f"    {line}", Colors.DIM), err=True)
+                        click.echo("", err=True)
+
+        sys.exit(1)
+
+    # Build AST
+    try:
+        builder = ASTBuilder(result.source, str(file_path))
+        ast = builder.build(result.root_node)
+    except Exception as e:
+        if json_output:
+            print(json.dumps({"valid": False, "errors": [{"message": f"AST error: {e}"}]}))
+        else:
+            click.echo(colorize(f"error: Failed to build AST: {e}", Colors.RED), err=True)
+        sys.exit(1)
+
+    # Success
+    if json_output:
+        summary = {
+            "valid": True,
+            "file": str(file_path),
+            "stats": {
+                "imports": len(ast.imports),
+                "structs": len(ast.type_defs),
+                "functions": len(ast.function_defs),
+                "statutes": len(ast.statutes),
+                "variables": len(ast.variables),
+            }
+        }
+        print(json.dumps(summary, indent=2))
+    else:
+        click.echo(colorize(f"OK: {file_path}", Colors.CYAN + Colors.BOLD))
+        if verbose:
+            click.echo(f"  {len(ast.imports)} imports")
+            click.echo(f"  {len(ast.type_defs)} type definitions")
+            click.echo(f"  {len(ast.function_defs)} functions")
+            click.echo(f"  {len(ast.statutes)} statutes")
+            click.echo(f"  {len(ast.variables)} variables")
+
+    sys.exit(0)