Metadata-Version: 2.4
Name: spolvero
Version: 0.4.0
Summary: Package docs-as-code diagrams into Visio-friendly handoff artifacts.
Author: Spolvero maintainers
License: MIT
Keywords: data-visualizer,diagram,handoff,mermaid,visio
Requires-Python: >=3.11
Provides-Extra: com
Requires-Dist: pywin32>=306; (platform_system == 'Windows') and extra == 'com'
Provides-Extra: topology
Requires-Dist: pyyaml>=6.0; extra == 'topology'
Provides-Extra: vsdx
Requires-Dist: defusedxml>=0.7; extra == 'vsdx'
Requires-Dist: pyyaml>=6.0; extra == 'vsdx'
Requires-Dist: vsdx>=0.5; extra == 'vsdx'
Description-Content-Type: text/markdown

# 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](docs/using-the-package.md) for what to do with the handoff folder once it has been generated.

## Quick Start

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

From a checkout without installation:

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

Python usage:

```python
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

```bash
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:

```bash
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](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.

```bash
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](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.
