test: improved verbosity in error-checking

Author: karlllewis

Makefile

@@ -15,7 +15,7 @@ install:
 	uv venv && uv pip install -e '.[dev]'
 
 lint:
-	uv run ruff check . && uv run mypy .
+	uv run ruff check . && uv run mypy src
 
 test:
 	PYTHONPATH=src uv run pytest

src/trustforge/__init__.py

@@ -0,0 +1,4 @@
+from __future__ import annotations
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

src/trustforge/cli.py

@@ -1,85 +1,74 @@
 from __future__ import annotations
 
+import sys
 from pathlib import Path
 
 import typer
 
-from .errors import (
-    AssetMissingError,
-    DependencyMissingError,
-    HTMLBuildError,
-    InvalidFrontmatterError,
-    PDFBuildError,
-    ThemeLoadError,
-    TrustforgeError,
-)
+from .common.errors import TrustforgeError
 from .pipeline.metadata import build_index_csv
 from .pipeline.render_html import render_html
 from .pipeline.render_pdf import render_pdf
 
 app = typer.Typer(help="Trustforge Policy Foundry")
 
 
-def _bail(msg: str, code: int = 1) -> None:
-    typer.secho(msg, fg=typer.colors.RED, err=True)
-    raise typer.Exit(code)
+def _echo_err(msg: str) -> None:
+    typer.echo(msg, err=True)
 
 
 @app.command()
 def html(policy: str) -> None:
-    """Render a policy Markdown file to themed HTML."""
+    """
+    Render a policy Markdown file to themed HTML.
+    """
     try:
         out = render_html(Path(policy))
-        typer.secho(f"HTML -> {out}", fg=typer.colors.GREEN)
-    except InvalidFrontmatterError as e:
-        _bail(f"[frontmatter] {e}")
-    except (AssetMissingError, ThemeLoadError) as e:
-        _bail(f"[theme/assets] {e}")
-    except HTMLBuildError as e:
-        _bail(f"[html] {e}")
     except TrustforgeError as e:
-        _bail(f"[trustforge] {e}")
+        _echo_err(str(e))
+        raise typer.Exit(code=2)
     except Exception as e:  # safety net
-        _bail(f"[unexpected] {e.__class__.__name__}: {e}")
+        _echo_err(f"Unexpected error: {e}")
+        raise typer.Exit(code=1)
+    typer.echo(f"HTML -> {out}")
 
 
 @app.command()
 def pdf(policy: str) -> None:
-    """Render a policy Markdown file to themed PDF (xelatex required)."""
+    """
+    Render a policy Markdown file to themed PDF (XeLaTeX required).
+    """
     try:
         out = render_pdf(Path(policy))
-        typer.secho(f"PDF -> {out}", fg=typer.colors.GREEN)
-    except InvalidFrontmatterError as e:
-        _bail(f"[frontmatter] {e}")
-    except DependencyMissingError as e:
-        _bail(f"[deps] {e}\nHint: install TeX Live (XeLaTeX).")
-    except AssetMissingError as e:
-        _bail(f"[assets] {e}")
-    except ThemeLoadError as e:
-        _bail(f"[theme] {e}")
-    except PDFBuildError as e:
-        _bail(f"[pdf] {e}")
     except TrustforgeError as e:
-        _bail(f"[trustforge] {e}")
-    except Exception as e:  # safety net
-        _bail(f"[unexpected] {e.__class__.__name__}: {e}")
+        _echo_err(str(e))
+        raise typer.Exit(code=2)
+    except Exception as e:
+        _echo_err(f"Unexpected error: {e}")
+        raise typer.Exit(code=1)
+    typer.echo(f"PDF -> {out}")
 
 
 @app.command()
 def index(out: str = "out/policies.csv", policies_dir: str = "policies") -> None:
-    """Build CSV index of policy frontmatter across all markdown files."""
+    """
+    Build CSV index of policy frontmatter across all markdown files.
+    """
     try:
         p = build_index_csv(Path(policies_dir), Path(out))
-        typer.secho(f"Index -> {p}", fg=typer.colors.GREEN)
-    except InvalidFrontmatterError as e:
-        _bail(f"[frontmatter] {e}")
     except TrustforgeError as e:
-        _bail(f"[trustforge] {e}")
-    except FileNotFoundError:
-        _bail(f"[inputs] Policies dir not found: {policies_dir}")
-    except Exception as e:  # safety net
-        _bail(f"[unexpected] {e.__class__.__name__}: {e}")
+        _echo_err(str(e))
+        raise typer.Exit(code=2)
+    except Exception as e:
+        _echo_err(f"Unexpected error: {e}")
+        raise typer.Exit(code=1)
+    typer.echo(f"Index -> {p}")
 
 
 if __name__ == "__main__":
-    app()
+    # Typer uses SystemExit; this guard ensures clean non-zero codes propagate.
+    try:
+        app()
+    except SystemExit as e:
+        # Allow GH Actions to display a non-zero exit when appropriate.
+        sys.exit(e.code)

src/trustforge/common/__init__.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+# Re-export errors so "from trustforge.common import FrontmatterError" also works.
+from .errors import (
+    AssetNotFoundError,
+    CSVIndexError,
+    FrontmatterError,
+    LaTeXError,
+    MissingDependencyError,
+    RenderError,
+    TemplateError,
+    TrustforgeError,
+)
+
+__all__ = [
+    "TrustforgeError",
+    "FrontmatterError",
+    "TemplateError",
+    "AssetNotFoundError",
+    "MissingDependencyError",
+    "LaTeXError",
+    "CSVIndexError",
+    "RenderError",
+]

src/trustforge/common/errors.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+class TrustforgeError(Exception):
+    """Base class for all Trustforge errors."""
+
+
+class FrontmatterError(TrustforgeError):
+    """Raised when a policy markdown file has missing/invalid YAML frontmatter."""
+
+    def __init__(self, source: str | Path, message: str) -> None:
+        super().__init__(f"{source}: {message}")
+        self.source = str(source)
+
+
+class TemplateError(TrustforgeError):
+    """Raised when a template (HTML/LaTeX) is missing or malformed."""
+
+    def __init__(self, template: str | Path, message: str) -> None:
+        super().__init__(f"Template error [{template}]: {message}")
+        self.template = str(template)
+
+
+class AssetNotFoundError(TrustforgeError):
+    """Raised when a referenced asset (logo, font, etc.) cannot be found."""
+
+    def __init__(self, asset: str | Path) -> None:
+        super().__init__(f"Asset not found: {asset}")
+        self.asset = str(asset)
+
+
+class MissingDependencyError(TrustforgeError):
+    """Raised when a required system dependency is missing (e.g., xelatex)."""
+
+    def __init__(self, binary: str) -> None:
+        super().__init__(f"Missing required dependency: {binary}. Please install it and retry.")
+        self.binary = binary
+
+
+class LaTeXError(TrustforgeError):
+    """Raised when XeLaTeX returns a non-zero exit status."""
+
+    def __init__(self, tex_file: str | Path, log_file: str | Path | None = None) -> None:
+        msg = f"LaTeX failed compiling: {tex_file}"
+        if log_file:
+            msg += f" (see log: {log_file})"
+        super().__init__(msg)
+        self.tex_file = str(tex_file)
+        self.log_file = str(log_file) if log_file else None
+
+
+class CSVIndexError(TrustforgeError):
+    """Raised for CSV index build problems (e.g., missing policies dir)."""
+
+    def __init__(self, location: str | Path, message: str) -> None:
+        super().__init__(f"CSV index error at [{location}]: {message}")
+        self.location = str(location)
+
+
+class RenderError(TrustforgeError):
+    """Generic render pipeline error wrapper."""
+
+    def __init__(self, stage: str, message: str) -> None:
+        super().__init__(f"Render error during '{stage}': {message}")
+        self.stage = stage
+
+
+__all__ = [
+    "TrustforgeError",
+    "FrontmatterError",
+    "TemplateError",
+    "AssetNotFoundError",
+    "MissingDependencyError",
+    "LaTeXError",
+    "CSVIndexError",
+    "RenderError",
+]

src/trustforge/common/md.py

@@ -1,12 +1,14 @@
 from __future__ import annotations
 
 import re
+from pathlib import Path
 from typing import cast
 
 import yaml
 from markdown_it import MarkdownIt
 
-from ..models import PolicyMeta
+from trustforge.common.errors import FrontmatterError
+from trustforge.models import PolicyMeta
 
 # Robust frontmatter:
 # - optional UTF-8 BOM
@@ -18,12 +20,17 @@
 )
 
 
-def parse_policy_markdown(text: str) -> tuple[PolicyMeta, str]:
+def parse_policy_markdown(text: str, source: str | Path = "<memory>") -> tuple[PolicyMeta, str]:
+    """
+    Parse a markdown string with YAML frontmatter and return (meta, body).
+    Raises FrontmatterError if the frontmatter block is missing/invalid.
+    """
     m = FRONTMATTER_RE.match(text)
     if not m:
-        raise ValueError(
+        raise FrontmatterError(
+            source,
             "Missing or invalid frontmatter (--- ... ---) at top of file. "
-            "Ensure the file begins with a YAML block delimited by '---' lines."
+            "Ensure the file begins with a YAML block delimited by '---' lines.",
         )
     meta_raw, body = m.group(1), m.group(2)
     meta = PolicyMeta(**(yaml.safe_load(meta_raw) or {}))
@@ -32,4 +39,5 @@ def parse_policy_markdown(text: str) -> tuple[PolicyMeta, str]:
 
 def md_to_html(body_md: str) -> str:
     md = MarkdownIt("commonmark")
+    # markdown-it types return Any; cast it to keep mypy happy.
     return cast(str, md.render(body_md))