ostruct-cli 0.7.1__py3-none-any.whl → 0.8.0__py3-none-any.whl

ostruct/cli/template_debug_help.py

@@ -0,0 +1,162 @@
+"""Template debugging help system for ostruct CLI.
+
+This module provides comprehensive help and examples for template debugging features.
+"""
+
+import click
+
+TEMPLATE_DEBUG_HELP = """
+🐛 Template Debugging Quick Reference
+
+BASIC DEBUGGING:
+  --debug                     🐛 Enable all debug output (verbose logging + template expansion)
+  --show-templates           📝 Show expanded templates only (clean output)
+  --show-context             📋 Show template variables summary
+  --show-context-detailed    📋 Show detailed variable context with content preview
+  --debug-templates          🔍 Enable step-by-step template expansion analysis
+
+OPTIMIZATION DEBUGGING:
+  --show-pre-optimization    🔧 Show template before optimization
+  --show-optimization-diff   🔄 Show optimization changes (before/after comparison)
+  --show-optimization-steps  🔧 Show detailed optimization step tracking
+  --optimization-step-detail [summary|detailed]  📊 Control step detail level
+  --no-optimization          ⚡ Skip optimization entirely for debugging
+
+PERFORMANCE ANALYSIS:
+  --profile-template         ⏱️  Show template performance breakdown (future)
+  --analyze-optimization     📊 Show optimization impact analysis (future)
+
+INTERACTIVE DEBUGGING:
+  ostruct debug template.j2 schema.json --debug-shell  🎯 Interactive debug shell (future)
+
+EXAMPLES:
+
+🔍 Basic Template Debugging:
+  # Show everything (most verbose)
+  ostruct run template.j2 schema.json --debug -ft config.yaml
+
+  # Just template content (clean output)
+  ostruct run template.j2 schema.json --show-templates -ft config.yaml
+
+  # Show template variables and context
+  ostruct run template.j2 schema.json --show-context -ft config.yaml
+
+🔧 Optimization Debugging:
+  # See template before optimization
+  ostruct run template.j2 schema.json --show-pre-optimization -ft config.yaml
+
+  # See what optimization changed
+  ostruct run template.j2 schema.json --show-optimization-diff -ft config.yaml
+
+  # See step-by-step optimization process
+  ostruct run template.j2 schema.json --show-optimization-steps -ft config.yaml
+
+  # Detailed optimization steps with full diffs
+  ostruct run template.j2 schema.json --show-optimization-steps --optimization-step-detail detailed -ft config.yaml
+
+  # Skip optimization entirely
+  ostruct run template.j2 schema.json --no-optimization -ft config.yaml
+
+🎯 Combined Debugging:
+  # Show both optimization diff and steps
+  ostruct run template.j2 schema.json --show-optimization-diff --show-optimization-steps -ft config.yaml
+
+  # Full debugging with context and optimization
+  ostruct run template.j2 schema.json --debug --show-context --show-optimization-diff -ft config.yaml
+
+🚨 Troubleshooting Common Issues:
+
+❌ Undefined Variable Errors:
+  Problem: UndefinedError: 'variable_name' is undefined
+  Solution: Use --show-context to see available variables
+  Example: ostruct run template.j2 schema.json --show-context -ft config.yaml
+
+❌ Template Not Expanding:
+  Problem: Template appears unchanged in output
+  Solution: Use --show-templates to see expansion
+  Example: ostruct run template.j2 schema.json --show-templates -ft config.yaml
+
+❌ Optimization Breaking Template:
+  Problem: Template works without optimization but fails with it
+  Solution: Use --show-optimization-diff to see changes
+  Example: ostruct run template.j2 schema.json --show-optimization-diff -ft config.yaml
+
+❌ Performance Issues:
+  Problem: Template rendering is slow
+  Solution: Use --show-optimization-steps to see bottlenecks
+  Example: ostruct run template.j2 schema.json --show-optimization-steps -ft config.yaml
+
+💡 Pro Tips:
+  • Use --dry-run with debugging flags to avoid API calls
+  • Combine multiple debug flags for comprehensive analysis
+  • Start with --show-templates for basic template issues
+  • Use --debug for full diagnostic information
+  • Use --show-context when variables are undefined
+  • Use optimization debugging when templates work but optimization fails
+
+📚 For more information, see: docs/template_debugging.md
+"""
+
+
+def show_template_debug_help() -> None:
+    """Display comprehensive template debugging help."""
+    click.echo(TEMPLATE_DEBUG_HELP, err=True)
+
+
+def show_quick_debug_tips() -> None:
+    """Show quick debugging tips for common issues."""
+    quick_tips = """
+🚀 Quick Debug Tips:
+
+Template not working? Try:
+  1. ostruct run template.j2 schema.json --show-templates --dry-run
+  2. ostruct run template.j2 schema.json --show-context --dry-run
+  3. ostruct run template.j2 schema.json --debug --dry-run
+
+Optimization issues? Try:
+  1. ostruct run template.j2 schema.json --show-optimization-diff --dry-run
+  2. ostruct run template.j2 schema.json --no-optimization --dry-run
+
+For full help: ostruct run --help-debug
+"""
+    click.echo(quick_tips, err=True)
+
+
+def show_debug_examples() -> None:
+    """Show practical debugging examples."""
+    examples = """
+🎯 Template Debugging Examples:
+
+📝 Basic Template Issues:
+  # Check if template expands correctly
+  ostruct run my_template.j2 schema.json --show-templates --dry-run -ft config.yaml
+
+  # See what variables are available
+  ostruct run my_template.j2 schema.json --show-context --dry-run -ft config.yaml
+
+  # Full debug output
+  ostruct run my_template.j2 schema.json --debug --dry-run -ft config.yaml
+
+🔧 Optimization Issues:
+  # See what optimization does to your template
+  ostruct run my_template.j2 schema.json --show-optimization-diff --dry-run -ft config.yaml
+
+  # Track each optimization step
+  ostruct run my_template.j2 schema.json --show-optimization-steps --dry-run -ft config.yaml
+
+  # Bypass optimization entirely
+  ostruct run my_template.j2 schema.json --no-optimization --dry-run -ft config.yaml
+
+🔍 Advanced Debugging:
+  # Combine multiple debug features
+  ostruct run my_template.j2 schema.json \\
+    --debug \\
+    --show-context \\
+    --show-optimization-diff \\
+    --show-optimization-steps \\
+    --dry-run \\
+    -ft config.yaml
+
+💡 Remember: Always use --dry-run when debugging to avoid API calls!
+"""
+    click.echo(examples, err=True)

ostruct/cli/template_env.py

@@ -3,10 +3,11 @@
 This module provides a centralized factory for creating consistently configured Jinja2 environments.
 """
 
-from typing import Optional, Type
+from typing import List, Optional, Type, Union
 
 import jinja2
 from jinja2 import Environment
+from jinja2.ext import Extension
 
 from .template_extensions import CommentExtension
 from .template_filters import register_template_filters
@@ -17,6 +18,7 @@ def create_jinja_env(
     undefined: Optional[Type[jinja2.Undefined]] = None,
     loader: Optional[jinja2.BaseLoader] = None,
     validation_mode: bool = False,
+    debug_mode: bool = False,
 ) -> Environment:
     """Create a consistently configured Jinja2 environment.
 
@@ -24,6 +26,7 @@ def create_jinja_env(
         undefined: Custom undefined class to use. Defaults to StrictUndefined.
         loader: Template loader to use. Defaults to None.
         validation_mode: Whether to configure the environment for validation (uses SafeUndefined).
+        debug_mode: Whether to enable debug features like undefined variable detection.
 
     Returns:
         A configured Jinja2 environment.
@@ -35,6 +38,16 @@ def create_jinja_env(
     elif undefined is None:
         undefined = jinja2.StrictUndefined
 
+        # Configure extensions based on debug mode
+    extensions: List[Union[str, Type[Extension]]] = [
+        "jinja2.ext.do",
+        "jinja2.ext.loopcontrols",
+        CommentExtension,
+    ]
+
+    if debug_mode:
+        extensions.append("jinja2.ext.debug")  # Enable {% debug %} tag
+
     env = Environment(
         loader=loader,
         undefined=undefined,
@@ -42,11 +55,7 @@ def create_jinja_env(
         trim_blocks=True,
         lstrip_blocks=True,
         keep_trailing_newline=True,
-        extensions=[
-            "jinja2.ext.do",
-            "jinja2.ext.loopcontrols",
-            CommentExtension,
-        ],
+        extensions=extensions,
     )
 
     # Register all template filters

ostruct/cli/template_filters.py

@@ -7,15 +7,27 @@ import logging
 import re
 import textwrap
 from collections import Counter
-from typing import Any, Dict, List, Optional, Sequence, TypeVar, Union
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+    List,
+    Optional,
+    Sequence,
+    TypeVar,
+    Union,
+)
 
 import tiktoken
-from jinja2 import Environment, pass_context
+from jinja2 import Environment, TemplateRuntimeError, pass_context
 from pygments import highlight
 from pygments.formatters import HtmlFormatter, NullFormatter, TerminalFormatter
 from pygments.lexers import TextLexer, get_lexer_by_name, guess_lexer
 from pygments.util import ClassNotFound
 
+if TYPE_CHECKING:
+    pass
+
 logger = logging.getLogger(__name__)
 
 T = TypeVar("T")
@@ -127,7 +139,7 @@ def list_to_table(
     """Convert list to markdown table."""
     if not headers:
         return "| # | Value |\n| --- | --- |\n" + "\n".join(
-            f"| {i+1} | {item} |" for i, item in enumerate(items)
+            f"| {i + 1} | {item} |" for i, item in enumerate(items)
         )
     return (
         f"| {' | '.join(headers)} |\n| {' | '.join('-' * len(h) for h in headers)} |\n"
@@ -591,6 +603,44 @@ def format_code(
         return str(text)
 
 
+def single_filter(value: Any) -> Any:
+    """Extract single item from a list, ensuring exactly one item exists."""
+    # Import here to avoid circular imports
+    try:
+        from .file_list import FileInfoList
+
+        FileInfoListType = FileInfoList
+    except ImportError:
+        # Fallback if imports fail
+        FileInfoListType = None
+
+    if FileInfoListType and isinstance(value, FileInfoListType):
+        var_alias = getattr(value, "_var_alias", None) or "list"
+        if len(value) == 1:
+            return value[0]  # ✅ Return the FileInfo object, not the list
+        else:
+            raise TemplateRuntimeError(
+                f"Filter 'single' expected exactly 1 file for '{var_alias}', got {len(value)}."
+            )
+
+    # For other list types (but not strings or dicts)
+    if (
+        hasattr(value, "__len__")
+        and hasattr(value, "__getitem__")
+        and not isinstance(value, (str, dict))
+        and hasattr(value, "__iter__")
+    ):
+        if len(value) == 1:
+            return value[0]
+        else:
+            raise TemplateRuntimeError(
+                f"Filter 'single' expected exactly 1 item, got {len(value)}."
+            )
+
+    # Pass through non-list types (including FileInfo and strings)
+    return value
+
+
 def register_template_filters(env: Environment) -> None:
     """Register all template filters with the Jinja2 environment.
 
@@ -630,6 +680,8 @@ def register_template_filters(env: Environment) -> None:
         "escape_special": escape_special,
         # Table utilities
         "auto_table": auto_table,
+        # Single item extraction
+        "single": single_filter,
     }
 
     env.filters.update(filters)