spolvero 0.3.0__py3-none-any.whl

spolvero/reports.py

@@ -0,0 +1,180 @@
+"""Markdown report generation for handoff packages."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from spolvero.models import DiagramSource
+from spolvero.utils import write_text
+
+
+def write_template_notes(
+    path: Path,
+    diagram: DiagramSource,
+    ir: dict[str, Any],
+    target: str,
+    editability: str,
+    warnings: list[str],
+) -> None:
+    containers = ir.get("containers", [])
+    lines = [
+        f"# Visio Template Notes: {diagram.id}",
+        "",
+        f"- Requested target: `{target}`",
+        f"- Current editability: `{editability}`",
+        f"- Source type: `{diagram.source_type}`",
+        f"- Nodes recognized: {len(ir.get('nodes', []))}",
+        f"- Edges recognized: {len(ir.get('edges', []))}",
+        f"- Containers/swimlanes: {len(containers)}",
+        "",
+    ]
+    if containers:
+        container_labels = ", ".join(f"`{c.get('label', c['id'])}`" for c in containers)
+        lines.extend(
+            [
+                "## Recommended Visio Template",
+                "",
+                f"This diagram declares {len(containers)} container(s) ({container_labels}). When importing the generated Data Visualizer workbook into Visio, choose the **Cross-Functional Flowchart** (swimlanes) template — not Basic Flowchart — so the `Function` column maps to swimlanes.",
+                "",
+            ]
+        )
+    else:
+        lines.extend(
+            [
+                "## Recommended Visio Template",
+                "",
+                "No containers were detected. Importing into Visio's **Basic Flowchart** template is appropriate.",
+                "",
+            ]
+        )
+    lines.extend(
+        [
+            "## Native Visio Follow-Up",
+            "",
+            "Use the generated Data Visualizer workbook for the first Visio-native pass when available. For higher fidelity, map the normalized IR to organization-approved templates and stencils, then generate native `.vsdx` with Visio COM automation or a tested VSDX template mutation engine.",
+            "",
+            "## Warnings",
+            "",
+        ]
+    )
+    if warnings:
+        lines.extend(f"- {warning}" for warning in warnings)
+    else:
+        lines.append("- None")
+    write_text(path, "\n".join(lines) + "\n")
+
+
+def write_qa_report(
+    path: Path,
+    diagram: DiagramSource,
+    ir: dict[str, Any],
+    editability: str,
+    engine: str,
+    score: int,
+    warnings: list[str],
+    workbook_path: Path | None,
+    svg_path: Path,
+) -> None:
+    source = diagram.source_file
+    workbook_line = f"- Data Visualizer workbook: `{workbook_path.name}`" if workbook_path else "- Data Visualizer workbook: not generated"
+    warnings_block = "\n".join(f"- {warning}" for warning in warnings) if warnings else "- None"
+    if warnings:
+        warning_summary = f"**{len(warnings)} warning(s) — review before sharing.** See the Warnings section below."
+    else:
+        warning_summary = "**No warnings.**"
+    content = f"""# Diagram QA Report: {diagram.id}
+
+{warning_summary}
+
+## Summary
+
+- Source: `{source}`
+- Preview: `{svg_path.name}`
+{workbook_line}
+- Editability: `{editability}`
+- Engine: `{engine}`
+- Conversion score: {score}/100
+
+## Preserved
+
+- Node labels: {len(ir.get("nodes", []))}/{len(ir.get("nodes", []))}
+- Edges: {len(ir.get("edges", []))}/{len(ir.get("edges", []))}
+- Containers/swimlanes: {len(ir.get("containers", []))}
+- Source references: {"yes" if ir.get("nodes") else "not available"}
+
+## Warnings
+
+{warnings_block}
+
+## Manual Review Checklist
+
+- [ ] Confirm all node labels are readable.
+- [ ] Confirm connector directions.
+- [ ] Confirm decision branch labels.
+- [ ] Confirm title block and document metadata.
+- [ ] Confirm shape data is suitable before external sharing.
+- [ ] Decide whether future edits belong in source or only in Visio.
+"""
+    write_text(path, content)
+
+
+def conversion_score(ir: dict[str, Any], editability: str, warnings: list[str]) -> int:
+    score = 100
+    if editability == "vector_reference":
+        score -= 25
+    if editability == "raster_reference":
+        score -= 40
+    if not ir.get("nodes"):
+        score -= 20
+    if not ir.get("edges") and ir.get("diagram_type") == "flowchart":
+        score -= 15
+    score -= min(30, len(warnings) * 5)
+    return max(0, score)
+
+
+def write_package_readme(path: Path, input_path: Path, target: str, rows: list[tuple[dict[str, Any], int]]) -> None:
+    diagram_lines = []
+    for entry, score in rows:
+        first = entry.get("data_visualizer_workbook") or entry.get("preview_svg")
+        warnings = entry.get("warnings") or []
+        warning_text = " ".join(warnings) if warnings else "No warnings."
+        diagram_lines.append(
+            "\n".join(
+                [
+                    f"### {entry['id']}: {entry['title']}",
+                    "",
+                    f"- Open first: `{first}`",
+                    f"- Editability: `{entry['editability']}`",
+                    f"- Engine: `{entry['conversion_engine']}`",
+                    f"- QA score: {score}/100",
+                    f"- Known limitations: {warning_text}",
+                ]
+            )
+        )
+    content = f"""# Visio Handoff Package
+
+## What Was Generated
+
+This package was generated from `{input_path.name}` with target `{target}`. It preserves the original source, extracted diagram source, preview images, normalized IR, Visio handoff candidates, and QA reports.
+
+## Which File To Open First
+
+Start with the entries below, then review `qa/` before making final Visio edits.
+
+{chr(10).join(diagram_lines)}
+
+## Editability Declaration
+
+Generated Visio workbooks are downstream handoff artifacts. The original docs-as-code source remains canonical unless the project explicitly chooses a Visio-first lifecycle.
+
+## Manual Review Checklist
+
+- [ ] Confirm all labels and connector directions.
+- [ ] Review warnings in each QA report.
+- [ ] Open the Data Visualizer workbook in Excel/Visio if present.
+- [ ] Apply organization templates, stencils, title blocks, and approvals in Visio.
+- [ ] Push durable content edits back to the source diagram when source remains canonical.
+"""
+    write_text(path, content)
+

spolvero/schema.py

@@ -0,0 +1,65 @@
+"""Small schema loader and validator for generated artifacts."""
+
+from __future__ import annotations
+
+import json
+from importlib.resources import files
+from typing import Any
+
+
+class SchemaValidationError(ValueError):
+    """Raised when generated JSON does not match the bundled schema subset."""
+
+
+def load_schema(name: str) -> dict[str, Any]:
+    schema_path = files("spolvero.schemas").joinpath(name)
+    return json.loads(schema_path.read_text(encoding="utf-8"))
+
+
+def validate_manifest(manifest: dict[str, Any]) -> None:
+    validate_with_schema(manifest, load_schema("manifest.schema.json"))
+
+
+def validate_ir(ir: dict[str, Any]) -> None:
+    if ir.get("diagram_type") == "topology":
+        validate_with_schema(ir, load_schema("topology.schema.json"))
+        return
+    validate_with_schema(ir, load_schema("ir.schema.json"))
+
+
+def validate_with_schema(value: Any, schema: dict[str, Any], path: str = "$") -> None:
+    expected_type = schema.get("type")
+    if expected_type:
+        _assert_type(value, expected_type, path)
+
+    if "enum" in schema and value not in schema["enum"]:
+        raise SchemaValidationError(f"{path} must be one of {schema['enum']!r}")
+
+    if isinstance(value, dict):
+        for key in schema.get("required", []):
+            if key not in value:
+                raise SchemaValidationError(f"{path}.{key} is required")
+        properties = schema.get("properties", {})
+        for key, child_schema in properties.items():
+            if key in value:
+                validate_with_schema(value[key], child_schema, f"{path}.{key}")
+
+    if isinstance(value, list) and "items" in schema:
+        for index, item in enumerate(value):
+            validate_with_schema(item, schema["items"], f"{path}[{index}]")
+
+
+def _assert_type(value: Any, expected_type: str | list[str], path: str) -> None:
+    types = [expected_type] if isinstance(expected_type, str) else expected_type
+    checks = {
+        "object": lambda candidate: isinstance(candidate, dict),
+        "array": lambda candidate: isinstance(candidate, list),
+        "string": lambda candidate: isinstance(candidate, str),
+        "integer": lambda candidate: isinstance(candidate, int) and not isinstance(candidate, bool),
+        "number": lambda candidate: isinstance(candidate, int | float) and not isinstance(candidate, bool),
+        "boolean": lambda candidate: isinstance(candidate, bool),
+        "null": lambda candidate: candidate is None,
+    }
+    if not any(checks[type_name](value) for type_name in types):
+        raise SchemaValidationError(f"{path} expected {types!r}, got {type(value).__name__}")
+

spolvero/schemas/__init__.py

@@ -0,0 +1,2 @@
+"""Bundled JSON schemas."""
+

spolvero/schemas/ir.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.invalid/spolvero/ir.schema.json",
+  "title": "Visio Handoff Normalized IR",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "id",
+    "title",
+    "diagram_type",
+    "orientation",
+    "pages",
+    "nodes",
+    "edges",
+    "containers",
+    "warnings"
+  ],
+  "properties": {
+    "schema_version": { "type": "string" },
+    "id": { "type": "string" },
+    "title": { "type": "string" },
+    "diagram_type": { "type": "string", "enum": ["flowchart", "reference"] },
+    "orientation": { "type": "string" },
+    "pages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "size"],
+        "properties": {
+          "id": { "type": "string" },
+          "title": { "type": "string" },
+          "size": { "type": "string" }
+        }
+      }
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "label", "shape_kind", "metadata"],
+        "properties": {
+          "id": { "type": "string" },
+          "label": { "type": "string" },
+          "shape_kind": { "type": "string" },
+          "container": { "type": "string" },
+          "metadata": { "type": "object" }
+        }
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "from", "to", "label", "kind", "metadata"],
+        "properties": {
+          "id": { "type": "string" },
+          "from": { "type": "string" },
+          "to": { "type": "string" },
+          "label": { "type": "string" },
+          "kind": { "type": "string" },
+          "metadata": { "type": "object" }
+        }
+      }
+    },
+    "containers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "label", "kind"],
+        "properties": {
+          "id": { "type": "string" },
+          "label": { "type": "string" },
+          "kind": { "type": "string" }
+        }
+      }
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}
+

spolvero/schemas/manifest.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.invalid/spolvero/manifest.schema.json",
+  "title": "Visio Handoff Package Manifest",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "skill",
+    "version",
+    "created_at",
+    "source_files",
+    "target",
+    "diagrams"
+  ],
+  "properties": {
+    "schema_version": { "type": "string" },
+    "skill": { "type": "string" },
+    "version": { "type": "string" },
+    "created_at": { "type": "string" },
+    "source_files": {
+      "type": "array",
+      "items": { "type": ["string", "null"] }
+    },
+    "target": {
+      "type": "string",
+      "enum": ["package-only", "data-visualizer", "vsdx-template", "visio-com"]
+    },
+    "diagrams": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "title",
+          "source_type",
+          "source",
+          "normalized_ir",
+          "output_vsdx",
+          "data_visualizer_workbook",
+          "preview_svg",
+          "preview_png",
+          "editability",
+          "conversion_engine",
+          "requested_engine",
+          "actual_engine",
+          "warnings"
+        ],
+        "properties": {
+          "id": { "type": "string" },
+          "title": { "type": "string" },
+          "source_type": { "type": "string" },
+          "source": { "type": "string" },
+          "normalized_ir": { "type": "string" },
+          "output_vsdx": { "type": ["string", "null"] },
+          "data_visualizer_workbook": { "type": ["string", "null"] },
+          "preview_svg": { "type": "string" },
+          "preview_png": { "type": "string" },
+          "editability": {
+            "type": "string",
+            "enum": ["native", "semi_native", "vector_reference", "raster_reference"]
+          },
+          "conversion_engine": { "type": "string" },
+          "requested_engine": { "type": "string" },
+          "actual_engine": { "type": "string" },
+          "warnings": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}
+

spolvero/schemas/topology.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://example.invalid/spolvero/topology.schema.json",
+  "title": "Visio Handoff Topology IR",
+  "description": "Normalized intermediate representation for network diagrams and Technical Reference Diagrams (TRDs).",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "id",
+    "title",
+    "diagram_type",
+    "nodes",
+    "edges",
+    "containers",
+    "warnings"
+  ],
+  "properties": {
+    "schema_version": { "type": "string" },
+    "id": { "type": "string" },
+    "title": { "type": "string" },
+    "diagram_type": { "type": "string", "enum": ["topology"] },
+    "orientation": {
+      "type": "string",
+      "enum": ["left_to_right", "top_down", "unknown"]
+    },
+    "pages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "title"],
+        "properties": {
+          "id": { "type": "string" },
+          "title": { "type": "string" },
+          "size": { "type": "string" }
+        }
+      }
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "label", "kind"],
+        "properties": {
+          "id": { "type": "string" },
+          "label": { "type": "string" },
+          "kind": { "type": "string" },
+          "container": { "type": ["string", "null"] },
+          "metadata": { "type": "object" }
+        }
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "from", "to"],
+        "properties": {
+          "id": { "type": "string" },
+          "from": { "type": "string" },
+          "to": { "type": "string" },
+          "label": { "type": "string" },
+          "kind": { "type": "string" },
+          "metadata": { "type": "object" }
+        }
+      }
+    },
+    "containers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "label", "kind"],
+        "properties": {
+          "id": { "type": "string" },
+          "label": { "type": "string" },
+          "kind": { "type": "string" },
+          "parent": { "type": ["string", "null"] }
+        }
+      }
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

spolvero/source.py

@@ -0,0 +1,160 @@
+"""Input discovery and diagram source extraction."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from spolvero.constants import DIAGRAM_LANGS
+from spolvero.models import DiagramSource
+
+
+def extract_diagrams(input_path: Path, title: str = "") -> list[DiagramSource]:
+    suffix = input_path.suffix.lower()
+    name = input_path.name.lower()
+
+    # Topology files: ``foo.topology.yaml`` / ``.yml`` / ``.json`` or any
+    # ``*.topology.*`` extension; also bare .topology files.
+    is_topology = (
+        ".topology." in name
+        or name.endswith((".topology.yaml", ".topology.yml", ".topology.json"))
+    )
+    if is_topology:
+        text = input_path.read_text(encoding="utf-8", errors="replace")
+        fmt = "json" if name.endswith(".json") else "yaml"
+        return [
+            DiagramSource(
+                id="diagram-001",
+                title=title or input_path.stem.replace(".topology", ""),
+                language="topology",
+                source_type=f"topology.{fmt}",
+                text=text,
+                source_file=input_path.name,
+                origin_file=input_path.name,
+            )
+        ]
+
+    if suffix in {".md", ".markdown"}:
+        return extract_markdown_diagrams(input_path, title)
+    if suffix in {".mmd", ".mermaid"}:
+        text = input_path.read_text(encoding="utf-8", errors="replace")
+        return [
+            DiagramSource(
+                id="diagram-001",
+                title=title or input_path.stem,
+                language="mermaid",
+                source_type=classify_source_type("mermaid", text),
+                text=text,
+                source_file=input_path.name,
+                origin_file=input_path.name,
+            )
+        ]
+    if suffix in {".puml", ".plantuml"}:
+        text = input_path.read_text(encoding="utf-8", errors="replace")
+        return [
+            DiagramSource(
+                id="diagram-001",
+                title=title or input_path.stem,
+                language="plantuml",
+                source_type="plantuml",
+                text=text,
+                source_file=input_path.name,
+                origin_file=input_path.name,
+                warnings=["PlantUML parsing is not implemented; preview/reference output only."],
+            )
+        ]
+    if suffix in {".dot", ".gv"}:
+        text = input_path.read_text(encoding="utf-8", errors="replace")
+        return [
+            DiagramSource(
+                id="diagram-001",
+                title=title or input_path.stem,
+                language="graphviz",
+                source_type="graphviz_dot",
+                text=text,
+                source_file=input_path.name,
+                origin_file=input_path.name,
+                warnings=["Graphviz parsing is not implemented; preview/reference output only."],
+            )
+        ]
+    if suffix in {".svg", ".png", ".jpg", ".jpeg", ".pdf"}:
+        editability = "vector" if suffix == ".svg" else "raster"
+        return [
+            DiagramSource(
+                id="diagram-001",
+                title=title or input_path.stem,
+                language="image",
+                source_type=f"reference{suffix}",
+                text=f"Reference artifact: {input_path.name}\n",
+                source_file=input_path.name,
+                origin_file=input_path.name,
+                warnings=[f"Existing {editability} references are packaged as review artifacts, not native Visio shapes."],
+            )
+        ]
+    return []
+
+
+def extract_markdown_diagrams(input_path: Path, title: str = "") -> list[DiagramSource]:
+    content = input_path.read_text(encoding="utf-8", errors="replace")
+    fence_re = re.compile(
+        r"(?P<fence>```|~~~)\s*(?P<lang>[A-Za-z0-9_-]+)?[^\n]*\n(?P<body>.*?)(?:\n(?P=fence)\s*)",
+        re.DOTALL,
+    )
+    diagrams: list[DiagramSource] = []
+    for match in fence_re.finditer(content):
+        raw_lang = (match.group("lang") or "").strip().lower()
+        language = DIAGRAM_LANGS.get(raw_lang)
+        if not language:
+            continue
+        body = match.group("body").strip("\n")
+        line_offset = content[: match.start("body")].count("\n") + 1
+        diagram_title = title or nearest_heading(content[: match.start()]) or f"{input_path.stem} diagram {len(diagrams) + 1}"
+        warnings: list[str] = []
+        if language not in ("mermaid", "topology"):
+            warnings.append(f"{language} parsing is not implemented; preview/reference output only.")
+        diagrams.append(
+            DiagramSource(
+                id=f"diagram-{len(diagrams) + 1:03d}",
+                title=diagram_title,
+                language=language,
+                source_type=classify_source_type(language, body),
+                text=body + "\n",
+                line_offset=line_offset,
+                source_file=input_path.name,
+                origin_file=input_path.name,
+                warnings=warnings,
+            )
+        )
+    return diagrams
+
+
+def nearest_heading(markdown_prefix: str) -> str:
+    headings = re.findall(r"(?m)^#{1,6}\s+(.+?)\s*$", markdown_prefix)
+    return headings[-1].strip() if headings else ""
+
+
+def classify_source_type(language: str, text: str) -> str:
+    if language == "mermaid":
+        first = first_significant_line(text)
+        if re.match(r"^(flowchart|graph)\b", first, re.IGNORECASE):
+            return "mermaid_flowchart"
+        if first.lower().startswith("sequencediagram"):
+            return "mermaid_sequence"
+        return "mermaid_unknown"
+    if language == "plantuml":
+        return "plantuml"
+    if language == "graphviz":
+        return "graphviz_dot"
+    if language == "topology":
+        stripped = text.strip()
+        return "topology.json" if stripped.startswith("{") else "topology.yaml"
+    return language
+
+
+def first_significant_line(text: str) -> str:
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped and not stripped.startswith("%%"):
+            return stripped
+    return ""
+