Add --show-code flag to collagraph CLI

Pretty print the Python code that is compiled for a .cgx component
(with rich when available, plain print otherwise) and exit, instead of
rendering the component. This provides a direct way to inspect the
generated code, complementing the CGX_DEBUG temp-file flow.

The printing logic is extracted from _write_debug_file into a shared
print_source helper, and a generate_source function is added to the
compiler. format_code now also falls back to unformatted code when
ruff is not installed, since the CLI can run without dev dependencies.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: berendkleinhaneveld

README.md

@@ -75,6 +75,12 @@ Instead of using a python file as an entry point to run components, you can run
 uv run collagraph examples/pyside/counter.cgx
 ```
 
+To inspect the Python code that is compiled for a component, use the `--show-code` flag:
+
+```sh
+uv run collagraph --show-code examples/pyside/counter.cgx
+```
+
 For more examples, please take a look at the [examples folder](examples).
 
 Currently there are two renderers:

collagraph/__main__.py

@@ -81,6 +81,14 @@ def animate():
         breakpoint()  # noqa: T100
 
 
+def show_code(component_path: Path):
+    """Pretty print the Python code that is compiled for a component."""
+    from collagraph.sfc import print_source
+    from collagraph.sfc.compiler import generate_source
+
+    print_source(generate_source(component_path), component_path)
+
+
 def existing_component_file(value):
     path = Path(value)
     if not path.exists():
@@ -134,8 +142,17 @@ def run():
         action="store_true",
         help="Enable hot reloading (reload on file changes)",
     )
+    parser.add_argument(
+        "--show-code",
+        action="store_true",
+        help="Pretty print the compiled Python code for the component and exit",
+    )
     args = parser.parse_args()
 
+    if args.show_code:
+        show_code(args.component)
+        return
+
     init_collagraph(args.renderer, args.component, args.state, args.hot_reload)
 
 

collagraph/sfc/__init__.py

@@ -83,7 +83,27 @@ def load_from_string(template, path=None, namespace=None):
     return component_class, namespace
 
 
-def _write_debug_file(tree, path):  # pragma: no cover
+def print_source(source, path, footer=None):
+    """Pretty print (Python) source with rich, when available,
+    falling back to plain print otherwise.
+    """
+    try:
+        from rich.console import Console
+        from rich.syntax import Syntax
+
+        console = Console()
+        console.print(f"#---{path}---")
+        console.print(Syntax(source, "python", line_numbers=True))
+        if footer:
+            console.print(f"[dim]{footer}[/dim]")
+    except ImportError:
+        print(f"#---{path}---")  # noqa: T201
+        print(source)  # noqa: T201
+        if footer:
+            print(footer)  # noqa: T201
+
+
+def _write_debug_file(tree, path):
     """Write the compiled AST to a temporary Python file for debugging.
 
     Returns a tuple of (path, formatted_source), or (None, None) if writing fails.
@@ -96,8 +116,7 @@ def _write_debug_file(tree, path):  # pragma: no cover
     logger = logging.getLogger(__name__)
 
     try:
-        plain_result = ast.unparse(tree)
-        formatted = format_code(plain_result)
+        formatted = format_code(ast.unparse(tree))
 
         # Create a meaningful filename based on the source .cgx file
         source_name = Path(path).stem if path else "template"
@@ -112,19 +131,7 @@ def _write_debug_file(tree, path):  # pragma: no cover
         debug_file = Path(fh.name)
         logger.debug("CGX debug file written to: %s", debug_file)
 
-        try:
-            from rich.console import Console
-            from rich.syntax import Syntax
-
-            console = Console()
-            syntax = Syntax(formatted, "python")
-            console.print(f"#---{path}---")
-            console.print(syntax)
-            console.print(f"[dim]Debug file: {debug_file}[/dim]")
-        except ImportError:
-            print(f"#---{path}---")  # noqa: T201
-            print(formatted)  # noqa: T201
-            print(f"Debug file: {debug_file}")  # noqa: T201
+        print_source(formatted, path, footer=f"Debug file: {debug_file}")
 
         return debug_file, formatted
     except Exception as e:

collagraph/sfc/compiler.py

@@ -1011,13 +1011,26 @@ def format_code(code):
     """
     from subprocess import run
 
-    result = run(
-        ["ruff", "format", "-"],
-        input=code,
-        encoding="utf-8",
-        capture_output=True,
-    )
+    try:
+        result = run(
+            ["ruff", "format", "-"],
+            input=code,
+            encoding="utf-8",
+            capture_output=True,
+        )
+    except FileNotFoundError:
+        logger.warning("Could not format code: ruff not found")
+        return code
     if result.returncode != 0 or not result.stdout:
         logger.warning("Could not format code with ruff: %s", result.stderr)
         return code
     return result.stdout
+
+
+def generate_source(path, template=None):
+    """
+    Return the formatted Python source that is generated
+    for the .cgx file at the given path.
+    """
+    tree, _ = construct_ast(path=path, template=template)
+    return format_code(ast.unparse(tree))

tests/test_show_code.py

@@ -0,0 +1,29 @@
+"""Tests for the --show-code CLI feature."""
+
+import sys
+from pathlib import Path
+
+from collagraph.__main__ import run
+from collagraph.sfc.compiler import generate_source
+
+EXAMPLE_CGX = Path(__file__).parent / "data" / "example.cgx"
+
+
+def test_generate_source():
+    source = generate_source(EXAMPLE_CGX)
+
+    assert "class Example(cg.Component):" in source
+    assert "def render(self, renderer):" in source
+    # The generated source should be valid Python
+    compile(source, "example.py", mode="exec")
+
+
+def test_cli_show_code(monkeypatch, capsys):
+    monkeypatch.setattr(sys, "argv", ["collagraph", "--show-code", str(EXAMPLE_CGX)])
+
+    run()
+
+    captured = capsys.readouterr()
+    assert "example.cgx" in captured.out
+    assert "class Example" in captured.out
+    assert "def render" in captured.out