spolvero 0.3.0__py3-none-any.whl

spolvero/__init__.py

@@ -0,0 +1,7 @@
+"""Public API for Visio handoff package generation."""
+
+from spolvero.builder import build_package
+from spolvero.constants import VERSION
+
+__all__ = ["VERSION", "build_package"]
+

spolvero/builder.py

@@ -0,0 +1,200 @@
+"""Package assembly orchestration."""
+
+from __future__ import annotations
+
+import datetime as dt
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+from spolvero.constants import SCHEMA_VERSION, SKILL_ID, SOURCE_EXT, TARGETS, VERSION
+from spolvero.engines import REQUESTED_ENGINES, EngineContext, run_engine
+from spolvero.ir import normalize_diagram
+from spolvero.models import DiagramSource
+from spolvero.render import render_preview
+from spolvero.reports import conversion_score, write_package_readme, write_qa_report, write_template_notes
+from spolvero.schema import SchemaValidationError, validate_ir, validate_manifest
+from spolvero.source import extract_diagrams
+from spolvero.utils import rel, write_json, write_text
+
+
+def build_package(
+    input_path: str | Path,
+    out_dir: str | Path,
+    target: str = "data-visualizer",
+    title: str = "",
+    engine_override: str | None = None,
+    template: str | Path | None = None,
+) -> int:
+    input_path = Path(input_path).resolve()
+    out_dir = Path(out_dir).resolve()
+    if target not in TARGETS:
+        print(f"Unsupported target '{target}'. Expected one of: {', '.join(TARGETS)}", file=sys.stderr)
+        return 2
+    if engine_override is not None and engine_override not in TARGETS:
+        print(
+            f"Unsupported --engine '{engine_override}'. Expected one of: {', '.join(TARGETS)}",
+            file=sys.stderr,
+        )
+        return 2
+    if not input_path.exists():
+        print(f"Input file not found: {input_path}", file=sys.stderr)
+        return 1
+
+    dirs = {
+        "source": out_dir / "source",
+        "normalized": out_dir / "normalized",
+        "preview": out_dir / "preview",
+        "visio": out_dir / "visio",
+        "qa": out_dir / "qa",
+    }
+    for directory in dirs.values():
+        directory.mkdir(parents=True, exist_ok=True)
+
+    original_name = f"original{input_path.suffix or '.txt'}"
+    original_dest = dirs["source"] / original_name
+    shutil.copy2(input_path, original_dest)
+
+    diagrams = extract_diagrams(input_path, title)
+    if not diagrams:
+        diagrams = [
+            DiagramSource(
+                id="diagram-001",
+                title=title or input_path.stem,
+                language="unknown",
+                source_type="unknown_text",
+                text=input_path.read_text(encoding="utf-8", errors="replace"),
+                warnings=["No supported diagram block was detected; packaged input as an unsupported reference."],
+            )
+        ]
+
+    manifest: dict[str, Any] = {
+        "schema_version": SCHEMA_VERSION,
+        "skill": SKILL_ID,
+        "version": VERSION,
+        "created_at": dt.datetime.now(dt.timezone.utc).isoformat(),
+        "source_files": [rel(original_dest, out_dir)],
+        "target": target,
+        "diagrams": [],
+    }
+
+    readme_rows: list[tuple[dict[str, Any], int]] = []
+
+    for index, diagram in enumerate(diagrams, start=1):
+        diagram.id = f"diagram-{index:03d}"
+        source_ext = _source_extension(diagram)
+        source_name = f"{diagram.id}{source_ext or '.txt'}"
+        source_path = dirs["source"] / source_name
+        write_text(source_path, diagram.text)
+        diagram.source_file = rel(source_path, out_dir) or source_path.name
+        manifest["source_files"].append(diagram.source_file)
+
+        ir = normalize_diagram(diagram)
+        try:
+            validate_ir(ir)
+        except SchemaValidationError as exc:
+            print(f"IR schema validation failed for {diagram.id}: {exc}", file=sys.stderr)
+            return 1
+        ir_path = dirs["normalized"] / f"{diagram.id}.ir.json"
+        write_json(ir_path, ir)
+
+        svg_path = dirs["preview"] / f"{diagram.id}.svg"
+        png_path = dirs["preview"] / f"{diagram.id}.png"
+        render_preview(diagram, ir, svg_path, png_path)
+
+        workbook_path: Path | None = None
+        template_notes_path = dirs["visio"] / f"{diagram.id}-template-notes.md"
+        warnings = list(dict.fromkeys(diagram.warnings + ir.get("warnings", [])))
+        requested_engine = REQUESTED_ENGINES.get(target, "internal_preview")
+
+        engine_target = engine_override or target
+        ctx = EngineContext(
+            diagram=diagram,
+            ir=ir,
+            target=engine_target,
+            requested_engine=requested_engine,
+            out_dir=out_dir,
+            visio_dir=dirs["visio"],
+            options={"template": template} if template else {},
+        )
+        engine_result = run_engine(ctx)
+        conversion_engine = engine_result.actual_engine
+        editability = engine_result.editability
+        workbook_path = engine_result.workbook_path
+        warnings = list(dict.fromkeys(warnings + engine_result.warnings))
+
+        write_template_notes(template_notes_path, diagram, ir, target, editability, warnings)
+
+        qa_path = dirs["qa"] / f"{diagram.id}-qa.md"
+        score = conversion_score(ir, editability, warnings)
+        write_qa_report(qa_path, diagram, ir, editability, conversion_engine, score, warnings, workbook_path, svg_path)
+
+        log_path = dirs["qa"] / f"{diagram.id}-conversion-log.json"
+        write_json(
+            log_path,
+            {
+                "schema_version": SCHEMA_VERSION,
+                "diagram_id": diagram.id,
+                "source_type": diagram.source_type,
+                "target": target,
+                "requested_engine": requested_engine,
+                "actual_engine": conversion_engine,
+                "conversion_engine": conversion_engine,
+                "editability": editability,
+                "node_count": len(ir.get("nodes", [])),
+                "edge_count": len(ir.get("edges", [])),
+                "warnings": warnings,
+                "outputs": {
+                    "source": diagram.source_file,
+                    "ir": rel(ir_path, out_dir),
+                    "preview_svg": rel(svg_path, out_dir),
+                    "preview_png": rel(png_path, out_dir),
+                    "data_visualizer_workbook": rel(workbook_path, out_dir) if workbook_path else None,
+                    "output_vsdx": rel(engine_result.output_vsdx, out_dir) if engine_result.output_vsdx else None,
+                    "template_notes": rel(template_notes_path, out_dir),
+                    "qa": rel(qa_path, out_dir),
+                },
+            },
+        )
+
+        manifest_entry = {
+            "id": diagram.id,
+            "title": diagram.title,
+            "source_type": diagram.source_type,
+            "source": diagram.source_file,
+            "normalized_ir": rel(ir_path, out_dir),
+            "output_vsdx": rel(engine_result.output_vsdx, out_dir) if engine_result.output_vsdx else None,
+            "data_visualizer_workbook": rel(workbook_path, out_dir) if workbook_path else None,
+            "preview_svg": rel(svg_path, out_dir),
+            "preview_png": rel(png_path, out_dir),
+            "editability": editability,
+            "conversion_engine": conversion_engine,
+            "requested_engine": requested_engine,
+            "actual_engine": conversion_engine,
+            "warnings": warnings,
+        }
+        manifest["diagrams"].append(manifest_entry)
+        readme_rows.append((manifest_entry, score))
+
+    manifest_path = out_dir / "manifest.json"
+    try:
+        validate_manifest(manifest)
+    except SchemaValidationError as exc:
+        print(f"Manifest schema validation failed: {exc}", file=sys.stderr)
+        return 1
+    write_json(manifest_path, manifest)
+    write_package_readme(out_dir / "README.md", input_path, target, readme_rows)
+
+    print(f"Created Visio handoff package: {out_dir}")
+    print(f"Open first: {out_dir / 'README.md'}")
+    return 0
+
+
+def _source_extension(diagram: DiagramSource) -> str:
+    if diagram.source_type == "topology.json":
+        return ".json"
+    if diagram.source_type == "topology.yaml":
+        return ".yaml"
+    return SOURCE_EXT.get(diagram.language, ".txt")
+

spolvero/cli.py

@@ -0,0 +1,118 @@
+"""Command line interface for Spolvero."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from spolvero.builder import build_package
+from spolvero.constants import TARGETS
+from spolvero.hygiene import check_hygiene, render_hygiene_report
+from spolvero.inspection import inspect_vsdx, render_vsdx_report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Build and inspect Visio handoff artifacts.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    build = subparsers.add_parser("build", help="Build a package from one input file.")
+    build.add_argument("input", help="Markdown, Mermaid, PlantUML, DOT, SVG, PNG, PDF, or text input.")
+    build.add_argument("--out", default="spolvero-handoff", help="Output package directory.")
+    build.add_argument("--target", default="data-visualizer", choices=TARGETS, help="Requested conversion target.")
+    build.add_argument("--title", default="", help="Optional package or diagram title.")
+    build.add_argument(
+        "--template",
+        default=None,
+        help="Path to a Visio template (.vsdx) used by the vsdx-template engine.",
+    )
+    # Hidden override: force a specific engine regardless of target. Useful for
+    # testing fallbacks. Will be documented once stable.
+    build.add_argument("--engine", default=None, choices=TARGETS, help=argparse.SUPPRESS)
+
+    inspect = subparsers.add_parser("inspect-vsdx", help="Read-only inspection report for a .vsdx package.")
+    inspect.add_argument("input", help="Visio .vsdx package to inspect.")
+    inspect.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+    inspect.add_argument("--report", default=None, help="Optional Markdown or JSON report path.")
+    inspect.add_argument(
+        "--personal-term",
+        action="append",
+        default=[],
+        help="Personal name or token to flag during text scans. Can be repeated.",
+    )
+    inspect.add_argument(
+        "--forbidden-term",
+        action="append",
+        default=[],
+        help="Organization-specific term to flag during text scans. Can be repeated.",
+    )
+
+    hygiene = subparsers.add_parser("hygiene", help="Run repository migration hygiene checks.")
+    hygiene.add_argument("--root", default=".", help="Repository root to check.")
+    hygiene.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+    hygiene.add_argument("--report", default=None, help="Optional Markdown or JSON report path.")
+    hygiene.add_argument("--include-untracked", action="store_true", help="Also check untracked non-ignored files.")
+    hygiene.add_argument(
+        "--allow-vsdx",
+        action="append",
+        default=[],
+        help="Tracked .vsdx path allowed in addition to the bundled template. Can be repeated.",
+    )
+    hygiene.add_argument(
+        "--personal-term",
+        action="append",
+        default=[],
+        help="Personal name or token to flag during text scans. Can be repeated.",
+    )
+    hygiene.add_argument(
+        "--forbidden-term",
+        action="append",
+        default=[],
+        help="Organization-specific term to flag during text scans. Can be repeated.",
+    )
+
+    args = parser.parse_args(argv)
+    if args.command == "build":
+        return build_package(
+            Path(args.input),
+            Path(args.out),
+            args.target,
+            args.title,
+            engine_override=args.engine,
+            template=args.template,
+        )
+    if args.command == "inspect-vsdx":
+        report = inspect_vsdx(
+            Path(args.input),
+            personal_terms=args.personal_term,
+            forbidden_terms=args.forbidden_term,
+        )
+        _emit_report(report, render_vsdx_report(report), as_json=args.json, report_path=args.report)
+        return 0 if report["is_zip"] else 1
+    if args.command == "hygiene":
+        allowed = None
+        if args.allow_vsdx:
+            allowed = ["src/spolvero/templates/minimal_flowchart.vsdx", *args.allow_vsdx]
+        report = check_hygiene(
+            Path(args.root),
+            forbidden_terms=args.forbidden_term,
+            personal_terms=args.personal_term or None,
+            allowed_vsdx=allowed,
+            include_untracked=args.include_untracked,
+        )
+        _emit_report(report, render_hygiene_report(report), as_json=args.json, report_path=args.report)
+        return 0 if report["passed"] else 1
+    return 2
+
+
+def _emit_report(data: dict, rendered: str, *, as_json: bool, report_path: str | None) -> None:
+    content = json.dumps(data, indent=2, ensure_ascii=False) + "\n" if as_json else rendered
+    if report_path:
+        path = Path(report_path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8", newline="\n")
+    print(content, end="")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

spolvero/constants.py

@@ -0,0 +1,55 @@
+"""Shared constants for the Visio handoff package."""
+
+VERSION = "0.3.0"
+SCHEMA_VERSION = "1.0.0"
+SKILL_ID = "spolvero"
+
+TARGETS = ("package-only", "data-visualizer", "vsdx-template", "visio-com")
+
+EDITABILITY_LEVELS = ("native", "semi_native", "vector_reference", "raster_reference")
+
+DIAGRAM_LANGS = {
+    "mermaid": "mermaid",
+    "mmd": "mermaid",
+    "plantuml": "plantuml",
+    "puml": "plantuml",
+    "graphviz": "graphviz",
+    "dot": "graphviz",
+    "topology": "topology",
+    "trd": "topology",
+}
+
+SOURCE_EXT = {
+    "mermaid": ".mmd",
+    "plantuml": ".puml",
+    "graphviz": ".dot",
+    "topology": ".yaml",
+    "image": ".txt",
+    "unknown": ".txt",
+}
+
+DATA_VIS_HEADERS = [
+    "Process Step ID",
+    "Process Step Description",
+    "Next Step ID",
+    "Connector Label",
+    "Shape Type",
+    "Function",
+    "Phase",
+    "System",
+    "Owner",
+    "Criticality",
+    "SourceRef",
+]
+
+SHAPE_TYPE_MAP = {
+    "terminator": "Start/End",
+    "decision": "Decision",
+    "document": "Document",
+    "data_io": "Data",
+    "database": "External Data",
+    "subprocess": "Subprocess",
+    "process": "Process",
+    "rounded": "Process",
+    "circle": "Process",
+}

spolvero/engines/__init__.py

@@ -0,0 +1,102 @@
+"""Engine registry for Visio handoff conversion targets.
+
+Each target (``package-only``, ``data-visualizer``, ``vsdx-template``,
+``visio-com``) maps to an engine callable that consumes an
+:class:`EngineContext` and returns an :class:`EngineResult`.
+
+Engines are registered via :func:`register` (typically from the engine module's
+import-time side effect) and dispatched via :func:`run_engine`. Unknown targets
+fall back to the data-visualizer engine with a warning so behavior remains
+predictable when adapters lag behind the registry.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Mapping
+
+REQUESTED_ENGINES: Mapping[str, str] = {
+    "package-only": "internal_preview",
+    "data-visualizer": "data_visualizer_xlsx",
+    "vsdx-template": "vsdx_template_mutation",
+    "visio-com": "visio_com_automation",
+}
+
+
+@dataclass
+class EngineContext:
+    """Inputs an engine needs to produce its Visio artifact(s)."""
+
+    diagram: Any
+    ir: dict[str, Any]
+    target: str
+    requested_engine: str
+    out_dir: Path
+    visio_dir: Path
+    options: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class EngineResult:
+    """Outputs and metadata an engine produced."""
+
+    actual_engine: str = "internal_preview"
+    editability: str = "vector_reference"
+    workbook_path: Path | None = None
+    output_vsdx: Path | None = None
+    warnings: list[str] = field(default_factory=list)
+
+
+EngineFn = Callable[[EngineContext], EngineResult]
+
+_REGISTRY: dict[str, EngineFn] = {}
+
+
+def register(target: str, fn: EngineFn) -> None:
+    """Register an engine callable for a target name."""
+
+    _REGISTRY[target] = fn
+
+
+def get(target: str) -> EngineFn | None:
+    """Return the engine callable registered for ``target`` or ``None``."""
+
+    _ensure_loaded()
+    return _REGISTRY.get(target)
+
+
+def run_engine(ctx: EngineContext) -> EngineResult:
+    """Dispatch ``ctx`` to its registered engine, falling back if missing."""
+
+    _ensure_loaded()
+    fn = _REGISTRY.get(ctx.target)
+    if fn is None:
+        from spolvero.engines.data_visualizer import run as fallback
+
+        result = fallback(ctx)
+        result.warnings.insert(
+            0,
+            f"Unknown target '{ctx.target}'; fell back to data-visualizer engine.",
+        )
+        return result
+    return fn(ctx)
+
+
+_LOADED = False
+
+
+def _ensure_loaded() -> None:
+    """Import bundled engines once so their ``register`` calls run."""
+
+    global _LOADED
+    if _LOADED:
+        return
+    _LOADED = True
+    # Side-effect imports populate the registry.
+    from spolvero.engines import (  # noqa: F401
+        data_visualizer,
+        package_only,
+        visio_com,
+        vsdx_template,
+    )

spolvero/engines/data_visualizer.py

@@ -0,0 +1,56 @@
+"""Data Visualizer (xlsx) engine — the default Visio handoff path."""
+
+from __future__ import annotations
+
+from spolvero.engines import EngineContext, EngineResult, register
+from spolvero.ir import is_flowchart_ir
+from spolvero.topology import is_topology_ir
+from spolvero.utils import backup_if_manual_candidate
+from spolvero.workbook import write_data_visualizer_workbook
+
+REFERENCE_RASTER_TYPES = {
+    "reference.png",
+    "reference.jpg",
+    "reference.jpeg",
+    "reference.pdf",
+}
+
+_NOT_IMPLEMENTED_WARNING = (
+    "Native or semi-native conversion is not implemented for this diagram type."
+)
+
+
+def run(ctx: EngineContext) -> EngineResult:
+    result = EngineResult(actual_engine="internal_preview", editability="vector_reference")
+
+    if is_flowchart_ir(ctx.ir):
+        workbook_path = ctx.visio_dir / f"{ctx.diagram.id}-data-visualizer.xlsx"
+        backup_if_manual_candidate(workbook_path)
+        write_data_visualizer_workbook(workbook_path, ctx.ir)
+        result.workbook_path = workbook_path
+        result.actual_engine = "data_visualizer_xlsx"
+        result.editability = "semi_native"
+        return result
+
+    if is_topology_ir(ctx.ir):
+        if not ctx.ir.get("nodes"):
+            result.warnings.append(
+                "Topology IR has no recognized nodes; Data Visualizer workbook was not generated. "
+                "Packaged preview/reference artifacts only."
+            )
+            return result
+        workbook_path = ctx.visio_dir / f"{ctx.diagram.id}-data-visualizer.xlsx"
+        backup_if_manual_candidate(workbook_path)
+        write_data_visualizer_workbook(workbook_path, ctx.ir)
+        result.workbook_path = workbook_path
+        result.actual_engine = "data_visualizer_xlsx"
+        result.editability = "semi_native"
+        return result
+
+    if ctx.diagram.source_type in REFERENCE_RASTER_TYPES:
+        result.editability = "raster_reference"
+    result.warnings.append(_NOT_IMPLEMENTED_WARNING)
+    return result
+
+
+register("data-visualizer", run)

spolvero/engines/package_only.py

@@ -0,0 +1,28 @@
+"""Package-only engine — no Visio artifact produced.
+
+Even Mermaid flowcharts are downgraded to ``vector_reference`` because the
+package contains no Visio handoff artifact.
+"""
+
+from __future__ import annotations
+
+from spolvero.engines import EngineContext, EngineResult, register
+from spolvero.engines.data_visualizer import (
+    REFERENCE_RASTER_TYPES,
+    _NOT_IMPLEMENTED_WARNING,
+)
+from spolvero.ir import is_flowchart_ir
+from spolvero.topology import is_topology_ir
+
+
+def run(ctx: EngineContext) -> EngineResult:
+    result = EngineResult(actual_engine="internal_preview", editability="vector_reference")
+    if is_flowchart_ir(ctx.ir) or is_topology_ir(ctx.ir):
+        return result
+    if ctx.diagram.source_type in REFERENCE_RASTER_TYPES:
+        result.editability = "raster_reference"
+    result.warnings.append(_NOT_IMPLEMENTED_WARNING)
+    return result
+
+
+register("package-only", run)

spolvero/engines/visio_com.py

@@ -0,0 +1,118 @@
+"""visio-com engine.
+
+Drives Microsoft Visio desktop (Plan 2 / Professional) via COM automation.
+Available only on Windows with ``pywin32`` installed and Visio reachable
+through the ``Visio.Application`` ProgID.
+
+If the COM probe fails, the engine cascades through the vsdx-template engine
+(itself feature-detected); ultimately the data-visualizer engine takes over so
+every input still produces a usable handoff package.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+
+from spolvero.engines import EngineContext, EngineResult, register
+from spolvero.engines.vsdx_template import run as vsdx_run
+
+_PROBE_CACHE: bool | None = None
+
+
+def _platform_supports_com() -> bool:
+    return sys.platform == "win32"
+
+
+def _pywin32_available() -> bool:
+    return importlib.util.find_spec("win32com") is not None
+
+
+def _probe_visio() -> bool:
+    """Return True if a Visio.Application COM object can be instantiated.
+
+    Result is cached for the life of the process so repeated builds do not pay
+    the COM startup cost. ``reset_probe_cache`` clears it for tests.
+    """
+
+    global _PROBE_CACHE
+    if _PROBE_CACHE is not None:
+        return _PROBE_CACHE
+    if not _platform_supports_com() or not _pywin32_available():
+        _PROBE_CACHE = False
+        return False
+    try:  # pragma: no cover - exercised only on Windows + Visio
+        import win32com.client  # type: ignore[import-not-found]
+
+        app = win32com.client.Dispatch("Visio.Application")
+        try:
+            app.Visible = False
+        finally:
+            app.Quit()
+    except Exception:
+        _PROBE_CACHE = False
+        return False
+    _PROBE_CACHE = True
+    return True
+
+
+def _engine_disabled_reason() -> str | None:
+    if not _platform_supports_com():
+        return f"visio-com requires Windows; current platform is {sys.platform}."
+    if not _pywin32_available():
+        return (
+            "visio-com requires pywin32 (install with: "
+            "pip install 'spolvero[com]')."
+        )
+    if not _probe_visio():
+        return (
+            "visio-com probe failed: Visio.Application COM ProgID was not "
+            "reachable. Ensure Microsoft Visio Plan 2 / Professional is "
+            "installed and licensed on this machine."
+        )
+    return None
+
+
+def run(ctx: EngineContext) -> EngineResult:
+    reason = _engine_disabled_reason()
+    if reason is not None:
+        # Cascade through the vsdx-template engine; if that also can't engage
+        # it will itself fall back to the data-visualizer workbook. Either
+        # way we annotate why the requested engine did not run.
+        result = vsdx_run(ctx)
+        result.warnings.insert(
+            0,
+            f"Requested target '{ctx.target}' (engine '{ctx.requested_engine}'): {reason} "
+            "Falling back to vsdx-template / data-visualizer.",
+        )
+        return result
+    return _run_native(ctx)
+
+
+def _run_native(ctx: EngineContext) -> EngineResult:  # pragma: no cover - Windows only
+    """Run the COM-driven path.
+
+    Until a fully native COM implementation ships we delegate to the
+    vsdx-template engine so Windows users still receive the best available
+    artifact. Delegated output keeps its original ``actual_engine`` and
+    ``editability`` because ``native`` is reserved for COM-created shapes and
+    connectors.
+    """
+
+    result = vsdx_run(ctx)
+    result.warnings.insert(
+        0,
+        "visio-com native COM shape generation is not implemented yet; delegated to "
+        "vsdx-template / data-visualizer without relabeling output as native.",
+    )
+    return result
+
+
+def reset_probe_cache() -> None:
+    """Clear the cached probe result. For test use only."""
+
+    global _PROBE_CACHE
+    _PROBE_CACHE = None
+
+
+register("visio-com", run)