yaddd-utils 0.1.0__tar.gz

yaddd_utils-0.1.0/.gitignore

@@ -0,0 +1,163 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# ty
+.ty/
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDE
+.idea
+.vscode/!launch.json
+.vscode/!tasks.json
+
+# OS
+.DS_Store
+
+*_old/

yaddd_utils-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: yaddd-utils
+Version: 0.1.0
+Summary: Utilities for yaddd: scenario inspection and Mermaid diagram generation.
+Project-URL: Homepage, https://github.com/netstuff/yaddd
+Author-email: Yuri Andreev <andreev.jr@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: mermaid-py>=0.7
+Requires-Dist: yaddd>=0.3
+Description-Content-Type: text/markdown
+
+# yaddd-utils
+
+Utilities for [yaddd](https://github.com/netstuff/yaddd): scenario inspection and Mermaid diagram generation.
+
+## Features
+
+- **Scenario inspection** — discover `yaddd` `Scenario` subclasses, their steps, branches and conditions.
+- **Mermaid renderers** — turn inspected scenarios into diagrams:
+  - flowchart per scenario;
+  - grouped flowchart with subgraphs;
+  - sequence diagram of step execution;
+  - state diagram for `State` subclasses.
+
+## Installation
+
+```bash
+pip install yaddd-utils
+```
+
+## CLI
+
+Render a Mermaid flowchart from a Python module containing scenarios:
+
+```bash
+yaddd-mermaid myapp.scenarios --output diagram.mmd
+```
+
+## API
+
+```python
+from yaddd_utils.inspect import ScenarioAnalyzer
+from yaddd_utils.mermaid import ScenarioRenderer, RenderOptions
+
+analyzer = ScenarioAnalyzer()
+model = analyzer.analyze_module("myapp.scenarios")
+
+renderer = ScenarioRenderer(RenderOptions(direction="TD"))
+print(renderer.render(model))
+```

yaddd_utils-0.1.0/README.md

@@ -0,0 +1,39 @@
+# yaddd-utils
+
+Utilities for [yaddd](https://github.com/netstuff/yaddd): scenario inspection and Mermaid diagram generation.
+
+## Features
+
+- **Scenario inspection** — discover `yaddd` `Scenario` subclasses, their steps, branches and conditions.
+- **Mermaid renderers** — turn inspected scenarios into diagrams:
+  - flowchart per scenario;
+  - grouped flowchart with subgraphs;
+  - sequence diagram of step execution;
+  - state diagram for `State` subclasses.
+
+## Installation
+
+```bash
+pip install yaddd-utils
+```
+
+## CLI
+
+Render a Mermaid flowchart from a Python module containing scenarios:
+
+```bash
+yaddd-mermaid myapp.scenarios --output diagram.mmd
+```
+
+## API
+
+```python
+from yaddd_utils.inspect import ScenarioAnalyzer
+from yaddd_utils.mermaid import ScenarioRenderer, RenderOptions
+
+analyzer = ScenarioAnalyzer()
+model = analyzer.analyze_module("myapp.scenarios")
+
+renderer = ScenarioRenderer(RenderOptions(direction="TD"))
+print(renderer.render(model))
+```

yaddd_utils-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "yaddd-utils"
+description = "Utilities for yaddd: scenario inspection and Mermaid diagram generation."
+authors = [
+    {name = "Yuri Andreev", email = "andreev.jr@gmail.com"},
+]
+license = 'MIT'
+license-files = ['LICENSE']
+classifiers = [
+    'Development Status :: 4 - Beta',
+    'Programming Language :: Python',
+    'Programming Language :: Python :: 3.12',
+    'Programming Language :: Python :: 3.13',
+    'Programming Language :: Python :: 3.14',
+    'Intended Audience :: Developers',
+    'Operating System :: OS Independent',
+    'Topic :: Software Development :: Libraries :: Python Modules',
+    'Topic :: Internet',
+]
+requires-python = '>=3.12'
+dependencies = [
+    "yaddd>=0.3",
+    "mermaid-py>=0.7",
+]
+version = "0.1.0"
+readme = 'README.md'
+
+[project.urls]
+Homepage = 'https://github.com/netstuff/yaddd'
+
+[project.scripts]
+yaddd-mermaid = "yaddd_utils.mermaid.cli:main"
+
+[tool.uv.sources]
+yaddd = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/yaddd_utils"]

yaddd_utils-0.1.0/src/yaddd_utils/__init__.py

@@ -0,0 +1,6 @@
+"""yaddd-utils — utilities for yaddd."""
+
+from yaddd_utils import inspect, mermaid
+
+
+__all__ = ["inspect", "mermaid"]

yaddd_utils-0.1.0/src/yaddd_utils/inspect/__init__.py

@@ -0,0 +1,12 @@
+"""Inspection helpers for yaddd scenarios and states."""
+
+from yaddd_utils.inspect.registry import TargetRegistry
+from yaddd_utils.inspect.scenario import ScenarioAnalyzer, ScenarioInfo, StepInfo
+
+
+__all__ = [
+    "ScenarioAnalyzer",
+    "ScenarioInfo",
+    "StepInfo",
+    "TargetRegistry",
+]

yaddd_utils-0.1.0/src/yaddd_utils/inspect/registry.py

@@ -0,0 +1,51 @@
+"""Registry of inspection targets (modules and scenario classes)."""
+
+from __future__ import annotations
+
+import importlib
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from types import ModuleType
+from typing import Any
+
+from yaddd.application.handlers.scenarios import Scenario
+
+
+def _empty_modules() -> set[str]:
+    return set()
+
+
+def _empty_classes() -> set[str]:
+    return set()
+
+
+@dataclass(kw_only=True, slots=True)
+class TargetRegistry:
+    """Collect modules and scenario classes to be inspected together."""
+
+    _modules: set[str] = field(default_factory=_empty_modules)
+    _classes: set[str] = field(default_factory=_empty_classes)
+
+    def register_module(self, module: str | ModuleType) -> None:
+        """Add a module to the inspection set."""
+        name = module if isinstance(module, str) else module.__name__
+        self._modules.add(name)
+
+    def register_class(self, scenario_cls: type[Scenario[Any]]) -> None:
+        """Add a scenario class to the inspection set."""
+        self._classes.add(scenario_cls.__module__ + ":" + scenario_cls.scenario_name())
+
+    def modules(self) -> Iterator[str]:
+        """Yield all registered module names."""
+        yield from sorted(self._modules)
+
+    def classes(self) -> Iterator[str]:
+        """Yield all registered class selectors in ``module:ClassName`` form."""
+        yield from sorted(self._classes)
+
+    def resolve_classes(self) -> Iterator[type[Scenario[Any]]]:
+        """Import and yield registered scenario classes."""
+        for selector in self._classes:
+            module_name, class_name = selector.split(":", 1)
+            module = importlib.import_module(module_name)
+            yield getattr(module, class_name)

yaddd_utils-0.1.0/src/yaddd_utils/inspect/scenario.py

@@ -0,0 +1,97 @@
+"""Scenario introspection for yaddd application workflows."""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from types import ModuleType
+from typing import Any, TypeVar
+
+from yaddd.application.handlers.scenarios import Scenario, Step
+
+
+T = TypeVar("T")
+
+
+def _is_scenario_subclass(obj: Any) -> bool:
+    return inspect.isclass(obj) and issubclass(obj, Scenario) and obj is not Scenario
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class StepInfo:
+    """Introspected metadata of a single scenario step."""
+
+    name: str
+    method_name: str
+    has_condition: bool = False
+    branch_target: str | None = None
+    level: str = "info"
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class ScenarioInfo:
+    """Introspected metadata of a yaddd Scenario class."""
+
+    name: str
+    module: str
+    steps: Sequence[StepInfo] = ()
+    dependencies: Sequence[str] = field(default_factory=tuple)
+
+
+class ScenarioAnalyzer:
+    """Collect structural metadata from yaddd Scenario classes."""
+
+    def analyze_module(self, module: str | ModuleType) -> list[ScenarioInfo]:
+        """Inspect all Scenario subclasses declared in ``module``."""
+        if isinstance(module, str):
+            module = importlib.import_module(module)
+        result: list[ScenarioInfo] = []
+        for _name, obj in inspect.getmembers(module, _is_scenario_subclass):
+            info = self.analyze_class(obj)
+            if info.steps:
+                result.append(info)
+        return result
+
+    def analyze_class(self, scenario_cls: type[Scenario[Any]]) -> ScenarioInfo:
+        """Inspect a single Scenario subclass."""
+        declared_steps: Sequence[Step[Any]] = getattr(scenario_cls, "_declared_steps", ())
+        steps = [self._step_info(step) for step in declared_steps]
+        return ScenarioInfo(
+            name=scenario_cls.scenario_name(),
+            module=scenario_cls.__module__,
+            steps=steps,
+            dependencies=self._constructor_params(scenario_cls),
+        )
+
+    def analyze_object(self, scenario: Scenario[Any]) -> ScenarioInfo:
+        """Inspect a Scenario instance (same as its class)."""
+        return self.analyze_class(type(scenario))
+
+    def _step_info(self, step: Step[Any]) -> StepInfo:
+        target: str | None = None
+        if step.branch_to is not None:
+            target = self._branch_target_name(step.branch_to)
+        return StepInfo(
+            name=step.name,
+            method_name=step.method_name,
+            has_condition=step.when is not None,
+            branch_target=target,
+            level=step.level,
+        )
+
+    def _branch_target_name(self, branch_to: Any) -> str | None:
+        if inspect.isclass(branch_to) and issubclass(branch_to, Scenario):
+            return branch_to.scenario_name()
+        if callable(branch_to) and hasattr(branch_to, "__annotations__"):
+            return getattr(branch_to, "__name__", None) or repr(branch_to)
+        return None
+
+    def _constructor_params(self, scenario_cls: type[Scenario[Any]]) -> Sequence[str]:
+        signature = inspect.signature(scenario_cls.__init__)
+        return [
+            name
+            for name, param in signature.parameters.items()
+            if name != "self" and param.default is inspect.Parameter.empty
+        ]

yaddd_utils-0.1.0/src/yaddd_utils/mermaid/__init__.py

@@ -0,0 +1,21 @@
+"""Mermaid diagram generation for yaddd scenarios and states."""
+
+from yaddd_utils.mermaid._models import GraphModel, ScenarioEdge, ScenarioNode
+from yaddd_utils.mermaid.graph import ScenarioGraphRenderer
+from yaddd_utils.mermaid.renderers import Renderer, RenderOptions
+from yaddd_utils.mermaid.scenario import ScenarioRenderer
+from yaddd_utils.mermaid.sequence import ScenarioSequenceRenderer
+from yaddd_utils.mermaid.state import ScenarioStateRenderer
+
+
+__all__ = [
+    "GraphModel",
+    "Renderer",
+    "RenderOptions",
+    "ScenarioEdge",
+    "ScenarioGraphRenderer",
+    "ScenarioNode",
+    "ScenarioRenderer",
+    "ScenarioSequenceRenderer",
+    "ScenarioStateRenderer",
+]

yaddd_utils-0.1.0/src/yaddd_utils/mermaid/_adapter.py

@@ -0,0 +1,48 @@
+"""Thin wrapper around ``mermaid-py`` with warning suppression."""
+
+from __future__ import annotations
+
+import warnings
+from pathlib import Path
+from typing import Any
+
+
+class MermaidAdapterError(Exception):
+    """mermaid-py interaction failed."""
+
+
+def _import_mermaid() -> Any:
+    """Import mermaid-py while suppressing its runtime warnings."""
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        import mermaid  # type: ignore[import-untyped]
+
+        return mermaid
+
+
+def make_graph(title: str, script: str) -> Any:
+    """Build a mermaid-py Graph object from a diagram script."""
+    mermaid = _import_mermaid()
+    graph_cls = mermaid.graph.Graph
+    return graph_cls(title, script)
+
+
+def save_image(script: str, output: Path | str, title: str = "yaddd") -> None:
+    """Render ``script`` to an image file using mermaid-py.
+
+    Supported extensions depend on the installed mermaid-py backend
+    (``.png``, ``.svg`` and ``.pdf`` are common).
+    """
+    mermaid = _import_mermaid()
+    graph = make_graph(title, script)
+    renderer = mermaid.Mermaid(graph)
+    path = Path(output)
+    suffix = path.suffix.lower()
+    if suffix == ".png":
+        renderer.to_png(str(path))
+    elif suffix == ".svg":
+        renderer.to_svg(str(path))
+    elif suffix == ".pdf":
+        renderer.to_pdf(str(path))
+    else:
+        raise MermaidAdapterError(f"Unsupported image format: {suffix!r}")

yaddd_utils-0.1.0/src/yaddd_utils/mermaid/_models.py

@@ -0,0 +1,55 @@
+"""Dataclasses shared by Mermaid renderers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+def _empty_meta() -> dict[str, Any]:
+    return {}
+
+
+def _empty_nodes() -> list[ScenarioNode]:
+    return []
+
+
+def _empty_edges() -> list[ScenarioEdge]:
+    return []
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class ScenarioNode:
+    """A node in a scenario diagram."""
+
+    id: str
+    label: str
+    scenario: str | None = None
+    step: str | None = None
+    shape: str = "round"
+    meta: dict[str, Any] = field(default_factory=_empty_meta)
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class ScenarioEdge:
+    """A directed edge between two scenario nodes."""
+
+    source: str
+    target: str
+    label: str | None = None
+    style: str | None = None
+
+
+@dataclass(kw_only=True, slots=True)
+class GraphModel:
+    """Generic graph model produced by renderers."""
+
+    title: str
+    nodes: list[ScenarioNode] = field(default_factory=_empty_nodes)
+    edges: list[ScenarioEdge] = field(default_factory=_empty_edges)
+
+    def add_node(self, node: ScenarioNode) -> None:
+        self.nodes.append(node)
+
+    def add_edge(self, edge: ScenarioEdge) -> None:
+        self.edges.append(edge)

yaddd_utils-0.1.0/src/yaddd_utils/mermaid/cli.py

@@ -0,0 +1,115 @@
+"""Command-line entrypoint for rendering yaddd scenarios as Mermaid diagrams."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Protocol, Sequence
+
+from yaddd_utils.inspect.scenario import ScenarioAnalyzer, ScenarioInfo
+from yaddd_utils.mermaid._adapter import MermaidAdapterError, save_image
+from yaddd_utils.mermaid.graph import ScenarioGraphRenderer
+from yaddd_utils.mermaid.renderers import Renderer, RenderOptions
+from yaddd_utils.mermaid.scenario import ScenarioRenderer
+from yaddd_utils.mermaid.sequence import ScenarioSequenceRenderer
+
+
+class _RendererFactory(Protocol):
+    def __call__(self, options: RenderOptions | None = None) -> Renderer: ...
+
+
+_RENDERERS: dict[str, _RendererFactory] = {
+    "flowchart": ScenarioRenderer,
+    "graph": ScenarioGraphRenderer,
+    "sequence": ScenarioSequenceRenderer,
+}
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="yaddd-mermaid",
+        description="Render yaddd scenarios as Mermaid diagrams.",
+    )
+    parser.add_argument(
+        "modules",
+        nargs="+",
+        help="Python module paths to inspect (e.g. myapp.scenarios).",
+    )
+    parser.add_argument(
+        "--renderer",
+        choices=list(_RENDERERS.keys()),
+        default="flowchart",
+        help="Diagram type to render (default: flowchart).",
+    )
+    parser.add_argument(
+        "--direction",
+        default="TD",
+        help="Flowchart direction: TD, LR, RL, BT (default: TD).",
+    )
+    parser.add_argument(
+        "--output",
+        "-o",
+        type=Path,
+        help="Write the diagram to this file instead of stdout.",
+    )
+    parser.add_argument(
+        "--image",
+        type=Path,
+        help="Also render the diagram to an image (png/svg/pdf) using mermaid-py.",
+    )
+    parser.add_argument(
+        "--show-levels",
+        action="store_true",
+        help="Include step log levels in node labels.",
+    )
+    parser.add_argument(
+        "--hide-conditions",
+        action="store_true",
+        help="Do not annotate conditional steps.",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the CLI and return an exit code."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    analyzer = ScenarioAnalyzer()
+    scenarios: list[ScenarioInfo] = []
+    for module_name in args.modules:
+        scenarios.extend(analyzer.analyze_module(module_name))
+
+    if not scenarios:
+        print("No Scenario subclasses found.", file=sys.stderr)
+        return 1
+
+    options = RenderOptions(
+        direction=args.direction,
+        show_levels=args.show_levels,
+        show_conditions=not args.hide_conditions,
+    )
+    renderer_cls = _RENDERERS[args.renderer]
+    renderer = renderer_cls(options)
+    diagram = renderer.render_infos(scenarios)
+
+    if args.output:
+        args.output.write_text(diagram, encoding="utf-8")
+        print(f"Wrote {args.output}")
+    else:
+        print(diagram)
+
+    if args.image:
+        try:
+            save_image(diagram, args.image)
+            print(f"Wrote image {args.image}")
+        except MermaidAdapterError as exc:
+            print(f"Image rendering failed: {exc}", file=sys.stderr)
+            return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

yaddd_utils-0.1.0/src/yaddd_utils/mermaid/graph.py

@@ -0,0 +1,83 @@
+"""Renderer that groups scenario steps into per-scenario subgraphs."""
+
+from __future__ import annotations
+
+from yaddd_utils.inspect.scenario import ScenarioInfo
+from yaddd_utils.mermaid._models import GraphModel, ScenarioEdge, ScenarioNode
+from yaddd_utils.mermaid.renderers import RenderOptions
+from yaddd_utils.mermaid.scenario import safe_id
+
+
+class ScenarioGraphRenderer:
+    """Render scenarios as a flowchart with a subgraph per scenario."""
+
+    def __init__(self, options: RenderOptions | None = None) -> None:
+        self._options = options or RenderOptions()
+
+    def render(self, model: GraphModel) -> str:
+        """Render ``model`` as a flowchart with subgraphs."""
+        lines = [f"flowchart {self._options.direction}"]
+        current_subgraph: str | None = None
+        for node in model.nodes:
+            if node.scenario and node.scenario != current_subgraph:
+                if current_subgraph is not None:
+                    lines.append(f"{self._options.indent}end")
+                current_subgraph = node.scenario
+                lines.append(f"{self._options.indent}subgraph {node.scenario}")
+            lines.append(self._render_node(node))
+        if current_subgraph is not None:
+            lines.append(f"{self._options.indent}end")
+        for edge in model.edges:
+            lines.append(self._render_edge(edge))
+        return "\n".join(lines)
+
+    def render_infos(self, infos: list[ScenarioInfo]) -> str:
+        """Build a grouped flowchart from several scenarios."""
+        return self.render(self.build_model(infos))
+
+    def build_model(self, infos: list[ScenarioInfo]) -> GraphModel:
+        """Create a GraphModel from multiple ScenarioInfo objects."""
+        model = GraphModel(title="scenarios")
+        for info in infos:
+            self._add_scenario(model, info)
+        return model
+
+    def _add_scenario(self, model: GraphModel, info: ScenarioInfo) -> None:
+        previous: str | None = None
+        for step in info.steps:
+            node_id = safe_id(f"{info.name}_{step.name}")
+            label = step.name
+            if self._options.show_levels:
+                label = f"[{step.level}] {label}"
+            if step.has_condition and self._options.show_conditions:
+                label = f"{label} ❓"
+            model.add_node(
+                ScenarioNode(
+                    id=node_id,
+                    label=label,
+                    scenario=info.name,
+                    step=step.name,
+                )
+            )
+            if previous is not None:
+                model.add_edge(ScenarioEdge(source=previous, target=node_id))
+            if step.branch_target is not None:
+                target_id = safe_id(step.branch_target)
+                model.add_node(ScenarioNode(id=target_id, label=step.branch_target))
+                model.add_edge(
+                    ScenarioEdge(
+                        source=node_id,
+                        target=target_id,
+                        label="branch",
+                    )
+                )
+            previous = node_id
+
+    def _render_node(self, node: ScenarioNode) -> str:
+        label = node.label.replace('"', '"')
+        return f'{self._options.indent}{node.id}("{label}")'
+
+    def _render_edge(self, edge: ScenarioEdge) -> str:
+        if edge.label:
+            return f"{self._options.indent}{edge.source} -->|{edge.label}| {edge.target}"
+        return f"{self._options.indent}{edge.source} --> {edge.target}"

yaddd_utils-0.1.0/src/yaddd_utils/mermaid/renderers.py

@@ -0,0 +1,31 @@
+"""Base renderer protocol and shared options."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from yaddd_utils.inspect.scenario import ScenarioInfo
+from yaddd_utils.mermaid._models import GraphModel
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class RenderOptions:
+    """Common options for Mermaid renderers."""
+
+    direction: str = "TD"
+    show_conditions: bool = True
+    show_levels: bool = False
+    indent: str = "    "
+
+
+class Renderer(Protocol):
+    """Protocol for objects that render scenario models to Mermaid text."""
+
+    def render(self, model: GraphModel) -> str:
+        """Render ``model`` as a Mermaid diagram string."""
+        ...
+
+    def render_infos(self, infos: list[ScenarioInfo]) -> str:
+        """Render a list of ScenarioInfo objects as a Mermaid diagram string."""
+        ...

yaddd_utils-0.1.0/src/yaddd_utils/mermaid/scenario.py

@@ -0,0 +1,86 @@
+"""Renderer that turns a single scenario into a Mermaid flowchart."""
+
+from __future__ import annotations
+
+from yaddd_utils.inspect.scenario import ScenarioInfo
+from yaddd_utils.mermaid._models import GraphModel, ScenarioEdge, ScenarioNode
+from yaddd_utils.mermaid.renderers import RenderOptions
+
+
+def safe_id(name: str) -> str:
+    """Produce a Mermaid-safe node identifier."""
+    return "".join(ch if ch.isalnum() else "_" for ch in name)
+
+
+class ScenarioRenderer:
+    """Render one or more ScenarioInfo objects as a flat flowchart."""
+
+    def __init__(self, options: RenderOptions | None = None) -> None:
+        self._options = options or RenderOptions()
+
+    def render(self, model: GraphModel) -> str:
+        """Render ``model`` as a Mermaid flowchart."""
+        lines = [f"flowchart {self._options.direction}"]
+        for node in model.nodes:
+            lines.append(self._render_node(node))
+        for edge in model.edges:
+            lines.append(self._render_edge(edge))
+        return "\n".join(lines)
+
+    def render_info(self, info: ScenarioInfo) -> str:
+        """Build a flowchart for a single scenario."""
+        return self.render(self.build_model(info))
+
+    def render_infos(self, infos: list[ScenarioInfo]) -> str:
+        """Build a flat flowchart for multiple scenarios."""
+        if len(infos) == 1:
+            return self.render_info(infos[0])
+        parts = [self.render_info(info) for info in infos]
+        return "\n\n".join(parts)
+
+    def build_model(self, info: ScenarioInfo) -> GraphModel:
+        """Create a GraphModel from a single ScenarioInfo."""
+        model = GraphModel(title=info.name)
+        previous: str | None = None
+        for step in info.steps:
+            node_id = safe_id(f"{info.name}_{step.name}")
+            label = step.name
+            if self._options.show_levels:
+                label = f"[{step.level}] {label}"
+            if step.has_condition and self._options.show_conditions:
+                label = f"{label} ❓"
+            model.add_node(
+                ScenarioNode(
+                    id=node_id,
+                    label=label,
+                    scenario=info.name,
+                    step=step.name,
+                )
+            )
+            if previous is not None:
+                model.add_edge(ScenarioEdge(source=previous, target=node_id))
+            if step.branch_target is not None:
+                target_id = safe_id(step.branch_target)
+                model.add_node(ScenarioNode(id=target_id, label=step.branch_target))
+                model.add_edge(
+                    ScenarioEdge(
+                        source=node_id,
+                        target=target_id,
+                        label="branch",
+                    )
+                )
+            previous = node_id
+        return model
+
+    def _render_node(self, node: ScenarioNode) -> str:
+        label = node.label.replace('"', '"')
+        if node.shape == "round":
+            return f'{self._options.indent}{node.id}("{label}")'
+        if node.shape == "diamond":
+            return f'{self._options.indent}{node.id}{{"{label}"}}'
+        return f'{self._options.indent}{node.id}["{label}"]'
+
+    def _render_edge(self, edge: ScenarioEdge) -> str:
+        if edge.label:
+            return f"{self._options.indent}{edge.source} -->|{edge.label}| {edge.target}"
+        return f"{self._options.indent}{edge.source} --> {edge.target}"

yaddd_utils-0.1.0/src/yaddd_utils/mermaid/sequence.py

@@ -0,0 +1,78 @@
+"""Renderer that produces a Mermaid sequence diagram from scenarios."""
+
+from __future__ import annotations
+
+from yaddd_utils.inspect.scenario import ScenarioInfo
+from yaddd_utils.mermaid._models import GraphModel, ScenarioEdge, ScenarioNode
+from yaddd_utils.mermaid.renderers import RenderOptions
+from yaddd_utils.mermaid.scenario import safe_id
+
+
+class ScenarioSequenceRenderer:
+    """Render scenario step flow as a Mermaid sequence diagram."""
+
+    def __init__(self, options: RenderOptions | None = None) -> None:
+        self._options = options or RenderOptions()
+
+    def render(self, model: GraphModel) -> str:
+        """Render ``model`` as a sequence diagram."""
+        lines = ["sequenceDiagram"]
+        actors: set[str] = set()
+        for node in model.nodes:
+            if node.scenario:
+                actors.add(node.scenario)
+        for actor in sorted(actors):
+            lines.append(f"{self._options.indent}participant {actor}")
+        current_actor: str | None = None
+        for edge in model.edges:
+            source_actor = self._actor_for(edge.source, model)
+            target_actor = self._actor_for(edge.target, model)
+            label = edge.label or "step"
+            if source_actor and target_actor:
+                lines.append(
+                    f"{self._options.indent}{source_actor}->>{target_actor}: {label}"
+                )
+            elif source_actor and current_actor != source_actor:
+                current_actor = source_actor
+                lines.append(f"{self._options.indent}Note over {source_actor}: {label}")
+        return "\n".join(lines)
+
+    def render_infos(self, infos: list[ScenarioInfo]) -> str:
+        """Build a sequence diagram from several scenarios."""
+        return self.render(self.build_model(infos))
+
+    def build_model(self, infos: list[ScenarioInfo]) -> GraphModel:
+        """Create a GraphModel representing the sequence flow."""
+        model = GraphModel(title="sequence")
+        for info in infos:
+            previous: str | None = None
+            for step in info.steps:
+                node_id = safe_id(f"{info.name}_{step.name}")
+                model.add_node(
+                    ScenarioNode(
+                        id=node_id,
+                        label=step.name,
+                        scenario=info.name,
+                        step=step.name,
+                    )
+                )
+                if previous is not None:
+                    model.add_edge(ScenarioEdge(source=previous, target=node_id))
+                if step.branch_target is not None:
+                    target_id = safe_id(step.branch_target)
+                    model.add_node(ScenarioNode(id=target_id, label=step.branch_target))
+                    model.add_edge(
+                        ScenarioEdge(
+                            source=node_id,
+                            target=target_id,
+                            label="branch",
+                        )
+                    )
+                previous = node_id
+        return model
+
+    def _actor_for(self, node_id: str, model: GraphModel) -> str | None:
+        for node in model.nodes:
+            if node.id == node_id:
+                return node.scenario
+        return None

yaddd_utils-0.1.0/src/yaddd_utils/mermaid/state.py

@@ -0,0 +1,43 @@
+"""Renderer that turns State subclasses into Mermaid state diagrams."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from yaddd_utils.mermaid._models import GraphModel, ScenarioNode
+from yaddd_utils.mermaid.renderers import RenderOptions
+
+
+class ScenarioStateRenderer:
+    """Render a yaddd State subclass as a Mermaid state diagram."""
+
+    def __init__(self, options: RenderOptions | None = None) -> None:
+        self._options = options or RenderOptions()
+
+    def render(self, model: GraphModel) -> str:
+        """Render ``model`` as a state diagram."""
+        lines = ["stateDiagram-v2"]
+        for node in model.nodes:
+            lines.append(f"{self._options.indent}[*] --> {node.id} : initialize")
+            lines.append(f"{self._options.indent}{node.id} : {node.label}")
+        return "\n".join(lines)
+
+    def render_state_class(self, state_cls: type[Any]) -> str:
+        """Build a state diagram for a single State subclass."""
+        return self.render(self.build_model(state_cls))
+
+    def build_model(self, state_cls: type[Any]) -> GraphModel:
+        """Create a GraphModel from a State subclass."""
+        title = getattr(state_cls, "__qualname__", "State")
+        model = GraphModel(title=title)
+        fields: Sequence[str] = getattr(state_cls, "_fields", ())
+        for name in fields:
+            model.add_node(
+                ScenarioNode(
+                    id=name,
+                    label=name,
+                    scenario=title,
+                )
+            )
+        return model

yaddd_utils-0.1.0/tests/unit/inspect/test_scenario.py

@@ -0,0 +1,46 @@
+import sys
+
+from yaddd import Scenario, step
+from yaddd_utils.inspect import ScenarioAnalyzer
+
+
+class SampleScenario(Scenario[int]):
+    @step
+    async def first(self, ctx) -> int:
+        return ctx.state + 1
+
+    @step(when=lambda ctx: ctx.state > 0)
+    async def second(self, ctx) -> int:
+        return ctx.state + 10
+
+
+class BranchingScenario(Scenario[int]):
+    @step
+    async def go(self, ctx) -> int:
+        return ctx.state + 1
+
+
+class EmptyScenario(Scenario[int]):
+    pass
+
+
+def test_analyzer_collects_steps_and_conditions():
+    analyzer = ScenarioAnalyzer()
+    info = analyzer.analyze_class(SampleScenario)
+
+    assert info.name == "SampleScenario"
+    assert len(info.steps) == 2
+    assert info.steps[0].name == "first"
+    assert info.steps[0].has_condition is False
+    assert info.steps[1].name == "second"
+    assert info.steps[1].has_condition is True
+
+
+def test_analyzer_skips_empty_scenarios_when_scanning_module():
+    analyzer = ScenarioAnalyzer()
+    results = analyzer.analyze_module(sys.modules[__name__])
+
+    names = {info.name for info in results}
+    assert "SampleScenario" in names
+    assert "BranchingScenario" in names
+    assert "EmptyScenario" not in names

yaddd_utils-0.1.0/tests/unit/mermaid/test_renderers.py

@@ -0,0 +1,52 @@
+import sys
+
+from yaddd import Scenario, step
+from yaddd_utils.inspect import ScenarioAnalyzer
+from yaddd_utils.mermaid import (
+    RenderOptions,
+    ScenarioGraphRenderer,
+    ScenarioRenderer,
+    ScenarioSequenceRenderer,
+)
+
+
+class DemoScenario(Scenario[int]):
+    @step
+    async def start(self, ctx) -> int:
+        return ctx.state + 1
+
+    @step(when=lambda ctx: ctx.state > 0)
+    async def maybe(self, ctx) -> int:
+        return ctx.state + 10
+
+
+def _infos():
+    return ScenarioAnalyzer().analyze_module(sys.modules[__name__])
+
+
+def test_scenario_renderer_produces_flowchart():
+    info = ScenarioAnalyzer().analyze_class(DemoScenario)
+    renderer = ScenarioRenderer(RenderOptions(show_conditions=True))
+    diagram = renderer.render_info(info)
+
+    assert diagram.startswith("flowchart TD")
+    assert "start" in diagram
+    assert "maybe" in diagram
+
+
+def test_graph_renderer_uses_subgraphs():
+    infos = _infos()
+    renderer = ScenarioGraphRenderer()
+    diagram = renderer.render_infos(infos)
+
+    assert diagram.startswith("flowchart TD")
+    assert "subgraph DemoScenario" in diagram
+
+
+def test_sequence_renderer_produces_sequence():
+    infos = _infos()
+    renderer = ScenarioSequenceRenderer()
+    diagram = renderer.render_infos(infos)
+
+    assert diagram.startswith("sequenceDiagram")
+    assert "DemoScenario" in diagram