spolvero 0.5.0

Package docs-as-code diagrams into Visio-friendly handoff artifacts.

Spolvero

spolvero turns docs-as-code diagrams into a Visio handoff package with preserved source, normalized IR, SVG/PNG previews, Data Visualizer workbooks for Mermaid flowcharts and topology inputs, QA reports, and explicit editability declarations.

The package treats source diagrams as canonical unless a project deliberately moves to a Visio-first workflow. Native Visio generation is intentionally conservative: the Data Visualizer workbook is the default cross-platform path, the vsdx-template engine produces a real .vsdx when the [vsdx] extra is installed, and visio-com currently probes Windows/Visio availability before cascading to downstream engines. Every engine records fallback downgrades in the manifest; native is reserved for future COM-created shapes/connectors.

See docs/using-the-package.md for what to do with the handoff folder once it has been generated.

Quick Start

spolvero build input.md --out ./handoff --target data-visualizer

From a checkout without installation:

uv run spolvero build tests/fixtures/sample.md --out .tmp/sample-output --target data-visualizer

Python usage:

from pathlib import Path

from spolvero import build_package

build_package(Path("input.md"), Path("handoff"), "data-visualizer", title="Review")

Repository Layout

• src/spolvero/: neutral Python library and CLI.
• src/spolvero/schemas/: versioned manifest and IR schemas.
• skills/codex/spolvero/: Codex-installable skill bundle generated from canonical docs and wrappers.
• adapters/: Claude Code, GitHub Copilot, and generic agent install notes/instruction files.
• tests/: pytest coverage for extraction, Mermaid parsing, schemas, artifacts, adapters, and CLI smoke builds.

Validation

uv run pytest
uv run python -m compileall src tests
uv run spolvero build tests/fixtures/sample.md --out .tmp/ci-smoke --target data-visualizer

Generated packages are intentionally ignored by git.

Operating hygiene checks are also available:

uv run spolvero hygiene --report .tmp/operating-hygiene.md
uv run spolvero inspect-vsdx src/spolvero/templates/minimal_flowchart.vsdx --report .tmp/minimal-flowchart-vsdx.md
uv run spolvero sanitize-vsdx src/spolvero/templates/minimal_flowchart.vsdx --out .tmp/minimal-flowchart-sanitized.vsdx --report .tmp/minimal-flowchart-sanitized.md

See docs/declaratus-migration.md for post-import operating guidance.

Optional Extras

The core install is stdlib-only. Each extra unlocks one optional engine or input format and is feature-detected at runtime so it never blocks the default path.

pip install spolvero            # stdlib-only default
pip install 'spolvero[vsdx]'     # vsdx-template engine (cross-platform)
pip install 'spolvero[topology]' # YAML topology inputs (PyYAML)
pip install 'spolvero[com]'      # visio-com engine (Windows + Visio Plan 2)

A Mermaid CLI (mmdc) on PATH is auto-detected for higher-fidelity Mermaid previews. Set SPOLVERO_DISABLE_MMDC=1 to force the built-in renderer.

Targets and Editability

Target	Engine	Flowchart editability	Notes
package-only	internal_preview	vector_reference	Skips workbook generation. Even Mermaid flowcharts and topology IRs are downgraded to a vector reference because no Visio handoff artifact is produced.
data-visualizer	data_visualizer_xlsx	semi_native	Default semi-native path. Generates a Visio Data Visualizer workbook for supported Mermaid flowcharts and topology IRs with recognized nodes. Empty/failed topology parses are downgraded to reference previews with no empty workbook.
vsdx-template	vsdx_template_mutation	semi_native (real .vsdx)	Mutates a template via the [vsdx] extra to produce a real .vsdx for supported flowchart and topology IRs. Use --template PATH to override the bundled template. Unsupported inputs and missing extras/templates cascade with clear warnings.
visio-com	visio_com_automation	delegated output editability	Probes Visio Plan 2 / Professional via COM (Windows + [com] extra), then currently delegates through vsdx-template and data-visualizer. A future true COM-native path will be the only source of native output.

The manifest always records both requested_engine and actual_engine so engine fallbacks are visible without parsing warning strings.

The VSDX template stamp contract is documented in docs/vsdx-template-contract.md. The bundled template is intentionally minimal; richer templates can provide preferred flowchart, topology, and container stamp names while remaining synthetic and organization-agnostic.

Inputs

• Mermaid flowchart (.mmd, fenced ```mermaid in Markdown) — primary input; full IR + workbook.
• Mermaid sequence diagrams, PlantUML, Graphviz DOT, SVG, PNG, JPG, PDF — packaged as references with previews.
• Topology: *.topology.yaml, *.topology.yml, *.topology.json, or fenced ```topology blocks. Raw source accepts node-level container and containers[].members; normalized IR resolves memberships into node container. Stencil kinds: router, switch, firewall, load_balancer, server, database, storage, client, cloud, internet, application, service, actor, datastore, external_system. Container kinds: subnet, zone, region, environment, vpc, system, boundary.

The name

Spolvero (Italian, spol-VEH-roh) is the Renaissance pouncing technique: an artist pricks holes along the lines of a finished drawing, then dusts pigment through them to transfer the design onto a wall or panel. The pricked cartoon is a deliberate intermediate — made for transfer, distinct from the original. This tool works the same way: it produces a transfer-ready rendering of a source diagram for the Visio surface, while the source stays canonical.