mermaiden 3.0.0__tar.gz

mermaiden-3.0.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+src/mermaiden/_version.py
+dist/
+.compatibility-artifacts/
+.preview/
+compatibility/toolchains/*/node_modules/
+.dev/

mermaiden-3.0.0/.node-version

@@ -0,0 +1 @@
+24.17.0

mermaiden-3.0.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: mermaiden
+Version: 3.0.0
+Summary: Typed deterministic Mermaid source generation for Python.
+Project-URL: Repository, https://github.com/szpak-dev/mermaiden
+Project-URL: Issues, https://github.com/szpak-dev/mermaiden/issues
+Author: 9orky
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pydantic>=2.12
+Requires-Dist: wireup>=2.12.0
+Provides-Extra: dev
+Requires-Dist: build>=1.3; extra == 'dev'
+Requires-Dist: import-linter>=2.11; extra == 'dev'
+Requires-Dist: jsonschema>=4.25; extra == 'dev'
+Requires-Dist: packaging>=25; extra == 'dev'
+Requires-Dist: pyright>=1.1.403; extra == 'dev'
+Requires-Dist: pytest>=9; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Requires-Dist: ruff>=0.14; extra == 'dev'
+Requires-Dist: twine>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mermaiden
+
+`mermaiden` generates deterministic Mermaid source from typed Python diagram models. It supports the Mermaid syntax families registered by the package and validates each diagram before rendering its text.
+
+The package produces Mermaid text only. Render it with Mermaid in a browser, Markdown viewer, or your own CLI workflow.
+
+## Installation
+
+Python 3.12 or later is required.
+
+```sh
+pip install mermaiden
+```
+
+## Quick start
+
+```python
+from mermaiden.application import Application
+
+application = Application.create()
+source = application.rendered_diagrams()["flowchart"]
+print(source)
+```
+
+`Application.available_diagrams()` returns the supported diagram catalog. `Application.diagram_info(diagram_id)` returns the typed diagram API for an individual syntax.
+
+## Development
+
+The repository uses a single host-mode CI target:
+
+```sh
+make ci
+```
+
+It installs the development dependencies, runs linting, type checks, tests, compatibility validation, Mermaid CLI rendering, and wheel validation. To open the locally generated diagram preview, run:
+
+```sh
+make diagrams-test
+```
+
+## Release
+
+Releases are versioned by annotated `vX.Y.Z` tags. After `make ci` passes, create and push the tag, then publish the GitHub release:
+
+```sh
+git tag -a v2.0.0 -m "v2.0.0"
+git push origin v2.0.0
+gh release create v2.0.0 --verify-tag --generate-notes --title v2.0.0
+```

mermaiden-3.0.0/README.md

@@ -0,0 +1,49 @@
+# mermaiden
+
+`mermaiden` generates deterministic Mermaid source from typed Python diagram models. It supports the Mermaid syntax families registered by the package and validates each diagram before rendering its text.
+
+The package produces Mermaid text only. Render it with Mermaid in a browser, Markdown viewer, or your own CLI workflow.
+
+## Installation
+
+Python 3.12 or later is required.
+
+```sh
+pip install mermaiden
+```
+
+## Quick start
+
+```python
+from mermaiden.application import Application
+
+application = Application.create()
+source = application.rendered_diagrams()["flowchart"]
+print(source)
+```
+
+`Application.available_diagrams()` returns the supported diagram catalog. `Application.diagram_info(diagram_id)` returns the typed diagram API for an individual syntax.
+
+## Development
+
+The repository uses a single host-mode CI target:
+
+```sh
+make ci
+```
+
+It installs the development dependencies, runs linting, type checks, tests, compatibility validation, Mermaid CLI rendering, and wheel validation. To open the locally generated diagram preview, run:
+
+```sh
+make diagrams-test
+```
+
+## Release
+
+Releases are versioned by annotated `vX.Y.Z` tags. After `make ci` passes, create and push the tag, then publish the GitHub release:
+
+```sh
+git tag -a v2.0.0 -m "v2.0.0"
+git push origin v2.0.0
+gh release create v2.0.0 --verify-tag --generate-notes --title v2.0.0
+```

mermaiden-3.0.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["hatchling>=1.28", "hatch-vcs>=0.5"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mermaiden"
+dynamic = ["version"]
+description = "Typed deterministic Mermaid source generation for Python."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "9orky" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "jinja2>=3.1",
+    "pydantic>=2.12",
+    "wireup>=2.12.0",
+]
+
+[project.optional-dependencies]
+dev = ["build>=1.3", "import-linter>=2.11", "jsonschema>=4.25", "packaging>=25", "pyright>=1.1.403", "pytest>=9", "pyyaml>=6", "ruff>=0.14", "twine>=6"]
+
+[dependency-groups]
+dev = ["build>=1.3", "import-linter>=2.11", "jsonschema>=4.25", "packaging>=25", "pyright>=1.1.403", "pytest>=9", "pyyaml>=6", "ruff>=0.14", "twine>=6"]
+
+[project.urls]
+Repository = "https://github.com/szpak-dev/mermaiden"
+Issues = "https://github.com/szpak-dev/mermaiden/issues"
+
+[tool.hatch.version]
+source = "vcs"
+tag-pattern = '^v(?P<version>\d+\.\d+\.\d+)$'
+fallback-version = "0.0.0"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/mermaiden/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mermaiden"]
+
+[tool.hatch.build.targets.sdist]
+include = ["compatibility", "docs", "examples", "scripts", "src", "tests", ".node-version", "README.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["-ra", "--strict-config", "--strict-markers"]
+filterwarnings = ["error"]
+
+[tool.ruff]
+line-length = 120
+extend-exclude = ["**/_version.py"]
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.pyright]
+include = ["src", "tests"]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+venvPath = "."
+venv = ".venv"

mermaiden-3.0.0/src/mermaiden/README.md

@@ -0,0 +1,56 @@
+# Diagram core prototype
+
+The model has five concepts:
+
+- **Diagram** owns its state and is the Visitor host.
+- **Element** is either an entity or a recursively nested container.
+- **Relation** binds IDs of existing elements.
+- **Constraint** is a side-effect-free Visitor producing structured violations.
+- **Annotation** adds data through typed references to elements or relations.
+
+Dependency direction is `flowchart/treeview -> runtime -> core`. Core is independent of
+Wireup and Mermaid. Runtime is a service-oriented building environment: frozen
+dataclass services receive dependencies through typed fields, while scoped
+`DiagramState` owns committed and staged state. No service has a handwritten
+constructor.
+
+Every mutation is executed by a Unit of Work. An Observer evaluates constraints
+before and after staging the candidate. Blocking violations roll the candidate
+back atomically; advisory violations allow deliberately incomplete diagrams to
+be built and repaired incrementally.
+
+Flowchart and Tree View are separate aggregates resolved from the composition root. Flowchart's API
+uses domain operations such as `add_start`, `add_decision`, `add_flow`, and
+`remove_flow`. Callers pass primitive arguments; the aggregate creates its
+`FlowNode`, `Flow`, and `Note` values internally. Generic `Diagram` operations
+are mapped to the same flowchart vocabulary and the same constraint pipeline,
+so they cannot bypass domain rules.
+
+The principal patterns are:
+
+- **Aggregate** for state ownership and behavior boundaries,
+- **Composite** for recursive element containment,
+- **Visitor** for structural and diagram-specific constraints,
+- **Observer** for before/after constraint evaluation,
+- **Unit of Work / Memento** for stage, commit, and rollback,
+- **Strategy** through the injected change and inspection contracts.
+
+Rendering implementations remain outside core. A renderer consumes the
+read-only `DiagramView` contract through `root_elements`, `walk_elements`,
+`find_relations`, and `find_annotations`, without access to runtime state or
+mutation services. The generic `Renderer` strategy does not prescribe a
+technology or output type.
+
+The generic `rendering` adapter package provides strict Jinja-to-text rendering
+and canonical LF-only output. It contains no Mermaid syntax and can be reused by
+diagram-specific rendering packages.
+
+The accepted initial flowchart surface is documented in
+[`diagrams/flowchart/VOCABULARY.md`](diagrams/flowchart/VOCABULARY.md).
+
+Each diagram rendering package emits deterministic Mermaid body text through Jinja
+snippets. Each semantic element, relation, and annotation owns its Mermaid
+representation in a template; renderer Python code only configures safe syntax
+filters and invokes the root template. The composition root exposes one
+`MermaidRenderer`, which dispatches every supported diagram and applies the
+same default Mermaid `wrap: true` document configuration.

mermaiden-3.0.0/src/mermaiden/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '3.0.0'
+__version_tuple__ = version_tuple = (3, 0, 0)
+
+__commit_id__ = commit_id = None

mermaiden-3.0.0/src/mermaiden/application.py

@@ -0,0 +1,98 @@
+import argparse
+from dataclasses import dataclass
+from pathlib import Path
+
+from wireup import SyncContainer, create_sync_container
+
+import mermaiden
+
+from .diagrams.registry import DiagramInfo, DiagramRegistry
+from .mermaid.compatibility import CompatibilityReport, MermaidCompatibility
+from .mermaid.compatibility.schema import MermaidDiagramConfig, MermaidSchemaStore
+from .mermaid.fixtures import DiagramFixtures
+from .mermaid.preview import MermaidPreview
+
+
+@dataclass(frozen=True, slots=True)
+class Application:
+    container: SyncContainer
+
+    @classmethod
+    def create(cls) -> "Application":
+        return cls(create_sync_container(injectables=[mermaiden], config={}))
+
+    def available_diagrams(self) -> tuple[DiagramInfo, ...]:
+        with self.container.enter_scope() as scope:
+            return scope.get(DiagramRegistry).available()
+
+    def diagram_info(self, diagram_id: str) -> DiagramInfo:
+        with self.container.enter_scope() as scope:
+            return scope.get(DiagramRegistry).get(diagram_id)
+
+    def diagram_info_for_config(self, config_key: str) -> DiagramInfo:
+        with self.container.enter_scope() as scope:
+            return scope.get(DiagramRegistry).get_by_config_key(config_key)
+
+    def mermaid_diagram_configs(self) -> tuple[MermaidDiagramConfig, ...]:
+        with self.container.enter_scope() as scope:
+            return scope.get(MermaidSchemaStore).diagram_configs()
+
+    def rendered_diagrams(self) -> dict[str, str]:
+        with self.container.enter_scope() as scope:
+            return scope.get(DiagramFixtures).render()
+
+    def write_fixtures(self, output: Path) -> tuple[Path, ...]:
+        output.mkdir(parents=True, exist_ok=True)
+        return tuple(
+            self._write_source(output, name, source) for name, source in self.rendered_diagrams().items()
+        )
+
+    def write_preview(self, output: Path) -> Path:
+        with self.container.enter_scope() as scope:
+            preview = scope.get(MermaidPreview)
+            return preview.write_sources(self.rendered_diagrams(), output)
+
+    def compatibility_report(self) -> CompatibilityReport:
+        with self.container.enter_scope() as scope:
+            return scope.get(MermaidCompatibility).inspect()
+
+    def verify_compatibility(self) -> CompatibilityReport:
+        with self.container.enter_scope() as scope:
+            return scope.get(MermaidCompatibility).verify()
+
+    @staticmethod
+    def _write_source(output: Path, name: str, source: str) -> Path:
+        path = output / f"{name}.mmd"
+        path.write_text(source, encoding="utf-8")
+        return path
+
+    @classmethod
+    def run(cls) -> None:
+        parser = argparse.ArgumentParser()
+        commands = parser.add_subparsers(dest="command", required=True)
+        fixtures = commands.add_parser("fixtures")
+        fixtures.add_argument("--output", "-o", type=Path, default=Path(".preview"))
+        preview = commands.add_parser("preview")
+        preview.add_argument("--output", "-o", type=Path, default=Path(".preview/index.html"))
+        commands.add_parser("compat")
+        arguments = parser.parse_args()
+        application = cls.create()
+        if arguments.command == "fixtures":
+            for path in application.write_fixtures(arguments.output):
+                print(path)
+        if arguments.command == "preview":
+            print(application.write_preview(arguments.output))
+        if arguments.command == "compat":
+            report = application.verify_compatibility()
+            for diagram in report.diagrams:
+                print(f"{diagram.diagram_id}: {'valid' if report.diagram_valid(diagram) else 'invalid'}")
+            for diagram in report.missing_diagrams:
+                print(f"{diagram.config_key}: not implemented ({diagram.schema_definition})")
+            for violation in report.syntax_violations:
+                print(f"{violation.diagram_id}: {violation.message}")
+            if not report.valid:
+                raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    Application.run()

mermaiden-3.0.0/src/mermaiden/core/__init__.py

@@ -0,0 +1,34 @@
+from .annotation import Annotation, DataAnnotation, TargetKind, TargetRef
+from .constraint import (
+    ChangeRejected,
+    ChangeReport,
+    Constraint,
+    ConstraintLevel,
+    ValidationReport,
+    Violation,
+)
+from .diagram import Diagram, DiagramView, DiagramVisitor
+from .element import Container, Element, Entity
+from .error import OperationError
+from .relation import Relation
+
+__all__ = [
+    "Annotation",
+    "ChangeRejected",
+    "ChangeReport",
+    "Constraint",
+    "ConstraintLevel",
+    "Container",
+    "DataAnnotation",
+    "Diagram",
+    "DiagramView",
+    "DiagramVisitor",
+    "Element",
+    "Entity",
+    "OperationError",
+    "Relation",
+    "TargetKind",
+    "TargetRef",
+    "ValidationReport",
+    "Violation",
+]

mermaiden-3.0.0/src/mermaiden/core/annotation.py

@@ -0,0 +1,25 @@
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class TargetKind(StrEnum):
+    ELEMENT = "element"
+    RELATION = "relation"
+
+
+@dataclass(frozen=True, slots=True)
+class TargetRef:
+    kind: TargetKind
+    id: str
+
+
+@dataclass(frozen=True, slots=True)
+class Annotation:
+    id: str
+    targets: tuple[TargetRef, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class DataAnnotation(Annotation):
+    data: Mapping[str, object]

mermaiden-3.0.0/src/mermaiden/core/constraint.py

@@ -0,0 +1,109 @@
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Protocol
+
+from .annotation import Annotation
+from .element import Element
+from .relation import Relation
+
+
+class ConstraintLevel(StrEnum):
+    BLOCKING = "blocking"
+    ADVISORY = "advisory"
+
+
+class ConstraintDiagram(Protocol):
+    @property
+    def root_elements(self) -> Sequence[Element]: ...
+
+    def walk_elements(self, parent_id: str = "") -> Sequence[Element]: ...
+
+    def find_relations(self, element_id: str = "") -> Sequence[Relation]: ...
+
+    def find_annotations(self, target_id: str = "") -> Sequence[Annotation]: ...
+
+
+@dataclass(frozen=True, slots=True)
+class Violation:
+    code: str
+    message: str
+    path: str = ""
+    level: ConstraintLevel = ConstraintLevel.ADVISORY
+
+
+@dataclass(frozen=True, slots=True)
+class ValidationReport:
+    violations: tuple[Violation, ...] = ()
+
+    @property
+    def blocking(self) -> tuple[Violation, ...]:
+        return tuple(item for item in self.violations if item.level is ConstraintLevel.BLOCKING)
+
+    @property
+    def advisory(self) -> tuple[Violation, ...]:
+        return tuple(item for item in self.violations if item.level is ConstraintLevel.ADVISORY)
+
+    @property
+    def can_commit(self) -> bool:
+        return not self.blocking
+
+    @property
+    def is_valid(self) -> bool:
+        return not self.violations
+
+    def __bool__(self) -> bool:
+        return self.can_commit
+
+
+@dataclass(frozen=True, slots=True)
+class ChangeReport:
+    operation: str
+    before: ValidationReport
+    after: ValidationReport
+    accepted: bool
+
+    @property
+    def introduced(self) -> tuple[Violation, ...]:
+        return tuple(item for item in self.after.violations if item not in self.before.violations)
+
+    @property
+    def resolved(self) -> tuple[Violation, ...]:
+        return tuple(item for item in self.before.violations if item not in self.after.violations)
+
+    @property
+    def current(self) -> ValidationReport:
+        return self.after if self.accepted else self.before
+
+
+@dataclass(frozen=True, slots=True)
+class ChangeRejected(RuntimeError):
+    operation: str
+    report: ValidationReport
+
+    def __str__(self) -> str:
+        details = "; ".join(item.message for item in self.report.blocking)
+        return f"Cannot {self.operation}: {details or 'the operation was rejected.'}"
+
+
+class Constraint(ABC):
+    @property
+    @abstractmethod
+    def code(self) -> str: ...
+
+    @property
+    def level(self) -> ConstraintLevel:
+        return ConstraintLevel.ADVISORY
+
+    @abstractmethod
+    def visit(self, diagram: ConstraintDiagram) -> tuple[Violation, ...]: ...
+
+    def violation(self, message: str, *, path: str = "") -> Violation:
+        return Violation(code=self.code, message=message, path=path, level=self.level)
+
+
+class BlockingConstraint(Constraint):
+    @property
+    def level(self) -> ConstraintLevel:
+        return ConstraintLevel.BLOCKING

mermaiden-3.0.0/src/mermaiden/core/diagram.py

@@ -0,0 +1,68 @@
+from abc import ABC, abstractmethod
+from collections.abc import Mapping, Sequence
+from typing import Protocol, TypeVar
+
+from .annotation import Annotation
+from .constraint import ChangeReport, ValidationReport
+from .element import Container, Element, Entity
+from .relation import Relation
+
+Result = TypeVar("Result", covariant=True)
+
+
+class DiagramVisitor(Protocol[Result]):
+    def visit(self, diagram: "Diagram") -> Result: ...
+
+
+class DiagramView(ABC):
+    @property
+    @abstractmethod
+    def kind(self) -> str: ...
+
+    @property
+    @abstractmethod
+    def mermaid_configuration(self) -> Mapping[str, object]: ...
+
+    @property
+    @abstractmethod
+    def root_elements(self) -> Sequence[Element]: ...
+
+    @abstractmethod
+    def find_element(self, id: str) -> Element | None: ...
+
+    @abstractmethod
+    def walk_elements(self, parent_id: str = "") -> Sequence[Element]: ...
+
+    @abstractmethod
+    def find_relations(self, element_id: str = "") -> Sequence[Relation]: ...
+
+    @abstractmethod
+    def find_annotations(self, target_id: str = "") -> Sequence[Annotation]: ...
+
+    @abstractmethod
+    def validate(self) -> ValidationReport: ...
+
+
+class Diagram(DiagramView):
+    @abstractmethod
+    def remove_element(self, id: str, *, cascade: bool = False) -> ChangeReport: ...
+
+    @abstractmethod
+    def remove_relation(self, id: str) -> ChangeReport: ...
+
+    @abstractmethod
+    def remove_annotation(self, id: str) -> ChangeReport: ...
+
+    def accept(self, visitor: DiagramVisitor[Result]) -> Result:
+        return visitor.visit(self)
+
+
+__all__ = [
+    "Container",
+    "Diagram",
+    "DiagramView",
+    "DiagramVisitor",
+    "Element",
+    "Entity",
+    "Relation",
+]

mermaiden-3.0.0/src/mermaiden/core/element.py

@@ -0,0 +1,18 @@
+from abc import ABC
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Element(ABC):
+    id: str
+    label: str
+
+
+@dataclass(frozen=True, slots=True)
+class Entity(Element):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class Container(Element):
+    elements: tuple[Element, ...] = ()

mermaiden-3.0.0/src/mermaiden/core/error.py

@@ -0,0 +1,2 @@
+class OperationError(Exception):
+    pass

mermaiden-3.0.0/src/mermaiden/core/relation.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Relation:
+    id: str
+    element_ids: tuple[str, ...]
+    label: str = ""