c4studio 0.2.0__py3-none-any.whl

c4studio/__init__.py

@@ -0,0 +1,28 @@
+"""c4studio – parse Structurizr DSL/JSON and generate C4 Mermaid diagrams."""
+
+from c4studio.models import (
+    Component,
+    Container,
+    Person,
+    Relationship,
+    SoftwareSystem,
+    View,
+    ViewType,
+    Workspace,
+)
+from c4studio.parser import parse_dsl, parse_json
+from c4studio.generators import MermaidGenerator
+
+__all__ = [
+    "parse_dsl",
+    "parse_json",
+    "MermaidGenerator",
+    "Workspace",
+    "SoftwareSystem",
+    "Container",
+    "Component",
+    "Person",
+    "Relationship",
+    "View",
+    "ViewType",
+]

c4studio/__main__.py

@@ -0,0 +1,5 @@
+"""Allow ``python -m c4studio`` as an alternative to the console script."""
+
+from c4studio.cli.main import cli
+
+cli()

c4studio/cli/main.py

@@ -0,0 +1,329 @@
+"""c4studio CLI entry point."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from c4studio.diagnostics import Diagnostic, Severity
+from c4studio.generators.flowchart import FlowchartGenerator
+from c4studio.generators.mermaid import MermaidGenerator
+from c4studio.models import Workspace
+from c4studio.render import RenderError, render_view
+from c4studio.webapp.graph import is_supported
+from c4studio.webapp.loader import WorkspaceLoadError, load_workspace
+
+
+def _load_workspace(path: Path) -> Workspace:
+    """Load a workspace, mapping loader errors to a CLI-friendly message."""
+    try:
+        workspace = load_workspace(path)
+    except WorkspaceLoadError as exc:
+        raise click.BadParameter(str(exc)) from exc
+    for warning in workspace.parse_warnings:
+        click.echo(f"warning: {warning}", err=True)
+    return workspace
+
+
+@click.group()
+@click.version_option()
+def cli() -> None:
+    """c4studio – parse Structurizr files and generate C4 diagrams."""
+
+
+@cli.command("generate")
+@click.argument("input_file", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--output",
+    "-o",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Output directory (default: print to stdout).",
+)
+@click.option(
+    "--view",
+    "-v",
+    "view_key",
+    default=None,
+    help="Only generate for this view key.",
+)
+@click.option(
+    "--format",
+    "-f",
+    "fmt",
+    type=click.Choice(["mermaid", "flowchart"], case_sensitive=False),
+    default="mermaid",
+    show_default=True,
+    help=(
+        "mermaid: Mermaid C4 syntax (C4Context/C4Container/C4Component). "
+        "flowchart: Mermaid flowchart + subgraph — renders more reliably on "
+        "GitHub and dense models, and covers dynamic, deployment and "
+        "filtered views too."
+    ),
+)
+def generate(
+    input_file: Path, output: Path | None, view_key: str | None, fmt: str
+) -> None:
+    """Generate diagrams from INPUT_FILE (DSL or JSON)."""
+    workspace = _load_workspace(input_file)
+    if fmt.lower() == "flowchart":
+        diagrams = FlowchartGenerator(workspace).generate_all()
+    else:
+        diagrams = MermaidGenerator(workspace).generate_all()
+    if view_key:
+        if view_key not in diagrams:
+            available = ", ".join(diagrams) or "(none)"
+            raise click.ClickException(
+                f"View '{view_key}' not found. Available: {available}"
+            )
+        diagrams = {view_key: diagrams[view_key]}
+
+    if output is None:
+        for key, content in diagrams.items():
+            if len(diagrams) > 1:
+                click.echo(f"--- {key} ---")
+            click.echo(content)
+            if len(diagrams) > 1:
+                click.echo()
+    else:
+        output.mkdir(parents=True, exist_ok=True)
+        ext = ".mmd"
+        for key, content in diagrams.items():
+            out_path = output / f"{key}{ext}"
+            out_path.write_text(content, encoding="utf-8")
+            click.echo(f"Written: {out_path}")
+
+
+@cli.command("render")
+@click.argument("input_file", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--output",
+    "-o",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Output directory (default: print to stdout).",
+)
+@click.option(
+    "--view",
+    "-v",
+    "view_key",
+    default=None,
+    help="Only render this view key.",
+)
+@click.option(
+    "--padding",
+    type=int,
+    default=24,
+    show_default=True,
+    help="Blank margin around the diagram, in pixels.",
+)
+@click.option(
+    "--no-title",
+    is_flag=True,
+    default=False,
+    help="Omit the heading above the diagram (the SVG <title> stays).",
+)
+@click.option(
+    "--no-legend",
+    is_flag=True,
+    default=False,
+    help="Omit the legend of element styles used by the view.",
+)
+def render(
+    input_file: Path,
+    output: Path | None,
+    view_key: str | None,
+    padding: int,
+    no_title: bool,
+    no_legend: bool,
+) -> None:
+    """Render diagrams from INPUT_FILE as standalone SVG.
+
+    No browser and no server: the diagrams are laid out and painted by the
+    same code the web app runs, bundled for Node. This is the only command
+    that needs Node.js installed; set C4STUDIO_NODE if it is not on
+    PATH. Views the renderer cannot draw (custom, image) are skipped.
+    """
+    workspace = _load_workspace(input_file)
+    views = [v for v in workspace.views if is_supported(v)]
+    if view_key:
+        views = [v for v in views if v.key == view_key]
+        if not views:
+            available = ", ".join(v.key for v in workspace.views if is_supported(v))
+            raise click.ClickException(
+                f"View '{view_key}' not found or not renderable. "
+                f"Available: {available or '(none)'}"
+            )
+    if not views:
+        raise click.ClickException("this workspace has no renderable views")
+
+    if output is not None:
+        output.mkdir(parents=True, exist_ok=True)
+    try:
+        for view in views:
+            svg = render_view(
+                workspace,
+                view,
+                padding=padding,
+                show_title=not no_title,
+                show_legend=not no_legend,
+            )
+            if output is None:
+                click.echo(svg, nl=False)
+            else:
+                out_path = output / f"{view.key}.svg"
+                out_path.write_text(svg, encoding="utf-8")
+                click.echo(f"Written: {out_path}")
+    except RenderError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+@cli.command("export")
+@click.argument("input_file", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--output",
+    "-o",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Output file (default: print to stdout).",
+)
+def export(input_file: Path, output: Path | None) -> None:
+    """Export INPUT_FILE (DSL or JSON) as Structurizr workspace JSON.
+
+    The output round-trips with structurizr.com, Structurizr Lite, and
+    this package's own JSON parser.
+    """
+    from c4studio.generators.json_export import export_json, export_json_file
+
+    workspace = _load_workspace(input_file)
+    if output is None:
+        click.echo(export_json(workspace), nl=False)
+    else:
+        if output.parent != Path(""):
+            output.parent.mkdir(parents=True, exist_ok=True)
+        export_json_file(workspace, output)
+        click.echo(f"Written: {output}")
+
+
+@cli.command("check")
+@click.argument("input_file", type=click.Path(allow_dash=True, path_type=Path))
+@click.option(
+    "--path",
+    "source_path",
+    type=click.Path(path_type=Path),
+    help=(
+        "File the source on stdin belongs to. Diagnostics are reported "
+        "against it, and relative !include/!docs/!adrs targets resolve "
+        "next to it."
+    ),
+)
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    help="Emit diagnostics as JSON, for editors and other tools.",
+)
+@click.option(
+    "--strict",
+    is_flag=True,
+    help="Exit non-zero on warnings as well as errors.",
+)
+def check(
+    input_file: Path, source_path: Path | None, as_json: bool, strict: bool
+) -> None:
+    """Report problems in INPUT_FILE without generating anything.
+
+    INPUT_FILE may be ``-`` to read DSL from stdin, which is how an editor
+    checks a buffer that has not been saved. Pass ``--path`` with it so
+    diagnostics name the real file and relative directives resolve.
+
+    Exits 1 when the file has errors (or, with --strict, warnings), so it
+    can gate a CI job. Warnings cover DSL the parser understood but did not
+    implement — those constructs are skipped, and this is where that
+    becomes visible.
+    """
+    import json as json_module
+
+    from c4studio.parser.dsl import ParseError, parse_dsl, parse_dsl_file
+
+    diagnostics: list[Diagnostic] = []
+    from_stdin = str(input_file) == "-"
+    try:
+        if from_stdin:
+            resolved = source_path.resolve() if source_path is not None else None
+            workspace = parse_dsl(
+                click.get_text_stream("stdin").read(),
+                base_dir=resolved.parent if resolved is not None else None,
+                path=resolved,
+            )
+        elif input_file.suffix.lower() == ".json":
+            workspace = _load_workspace(input_file)
+        else:
+            workspace = parse_dsl_file(input_file)
+        diagnostics = list(workspace.diagnostics)
+    except ParseError as error:
+        # Every problem found, not just the one that stopped parsing.
+        diagnostics = list(error.diagnostics)
+
+    if as_json:
+        click.echo(json_module.dumps([d.to_dict() for d in diagnostics], indent=2))
+    else:
+        for diagnostic in diagnostics:
+            click.echo(f"{diagnostic.severity.value}: {diagnostic}", err=True)
+        if not diagnostics:
+            label = source_path if from_stdin and source_path else input_file
+            click.echo(f"{label}: no problems found")
+
+    errors = [d for d in diagnostics if d.severity is Severity.ERROR]
+    if errors or (strict and diagnostics):
+        raise SystemExit(1)
+
+
+@cli.command("list-views")
+@click.argument("input_file", type=click.Path(exists=True, path_type=Path))
+def list_views(input_file: Path) -> None:
+    """List all views defined in INPUT_FILE."""
+    workspace = _load_workspace(input_file)
+    if not workspace.views:
+        click.echo("No views found.")
+        return
+    click.echo(f"{'Key':<30} {'Type':<20} {'Element ID'}")
+    click.echo("-" * 65)
+    for view in workspace.views:
+        click.echo(f"{view.key:<30} {view.type:<20} {view.element_id}")
+
+
+@cli.command("webapp")
+@click.argument("path", type=click.Path(exists=True, path_type=Path))
+@click.option("--port", default=8090, show_default=True, help="Port to listen on.")
+@click.option("--host", default="127.0.0.1", show_default=True)
+@click.option(
+    "--no-browser",
+    is_flag=True,
+    default=False,
+    help="Do not open a browser window automatically.",
+)
+def webapp(path: Path, port: int, host: str, no_browser: bool) -> None:
+    """Launch the React web application backend for PATH.
+
+    PATH may be a directory (browsed as the source root) or a single source
+    file (loaded eagerly, with its parent directory as the root).
+    """
+    from c4studio.webapp.server import run_server
+
+    if path.is_dir():
+        root: Path = path
+        initial: Path | None = None
+    else:
+        root = path.parent
+        initial = path
+
+    if not no_browser:
+        import threading
+        import webbrowser
+
+        url = f"http://{host}:{port}"
+        threading.Timer(1.0, webbrowser.open, args=(url,)).start()
+
+    run_server(root=root, initial=initial, host=host, port=port)

c4studio/diagnostics.py

@@ -0,0 +1,84 @@
+"""Structured parse problems, for editors and CI.
+
+A diagnostic is a machine-readable parse problem: where it happened, how
+bad it is, and what to say about it. The parser produces these instead of
+formatting positions into message strings, so an editor can place a marker
+and a CI job can decide whether to fail.
+
+Positions are 1-based lines, matching how editors and compilers report
+them. Columns are optional: the tokeniser tracks lines only, so a
+diagnostic without a column marks the whole line.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+
+class Severity(str, Enum):
+    """How much a problem matters.
+
+    ``ERROR`` means the source could not be understood as written;
+    ``WARNING`` means it parsed but something was skipped or ignored, which
+    is the usual outcome for DSL features this parser does not implement.
+    """
+
+    ERROR = "error"
+    WARNING = "warning"
+
+
+@dataclass
+class Diagnostic:
+    """One parse problem.
+
+    Attributes:
+        message: Human-readable description, without position information.
+        severity: :class:`Severity` of the problem.
+        path: File the problem is in. ``None`` when parsing a bare string,
+            and resolved through the include source map otherwise — a
+            problem inside an ``!include``-ed fragment names that fragment,
+            not the file that included it.
+        line: 1-based line within ``path``.
+        column: 1-based start column, when known.
+        end_column: Exclusive 1-based end column, when known.
+        code: Short stable identifier for the kind of problem, so editors
+            and CI can filter without matching on message text.
+    """
+
+    message: str
+    severity: Severity = Severity.ERROR
+    path: Path | None = None
+    line: int | None = None
+    column: int | None = None
+    end_column: int | None = None
+    code: str = ""
+
+    def __str__(self) -> str:
+        """Render as ``path:line: message``, omitting unknown parts.
+
+        This is the form the CLI prints and the form retained in the legacy
+        ``Workspace.parse_warnings`` list of strings.
+        """
+        where = ""
+        if self.path is not None:
+            where = f"{self.path}:"
+            if self.line is not None:
+                where += f"{self.line}:"
+        elif self.line is not None:
+            where = f"Line {self.line}:"
+        return f"{where} {self.message}".strip()
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise for ``c4studio check --json``."""
+        return {
+            "path": str(self.path) if self.path is not None else None,
+            "line": self.line,
+            "column": self.column,
+            "endColumn": self.end_column,
+            "severity": self.severity.value,
+            "code": self.code,
+            "message": self.message,
+        }

c4studio/generators/__init__.py

@@ -0,0 +1,4 @@
+from .flowchart import FlowchartGenerator
+from .mermaid import MermaidGenerator
+
+__all__ = ["FlowchartGenerator", "MermaidGenerator"]