wgo

A clean, idiomatic Go port of WireViz (v0.4.1), the tool that documents cables and wiring harnesses.

This is a direct port: no new features, no architectural expansion. Input YAML, DOT structure, BOM tables, SVG/PNG/HTML outputs, filenames, and ordering all match the reference implementation byte-for-byte.

Usage

wgo [options] FILE...

Options:
  -f, --format string     Output formats (default "hpst")
                          g=gv  h=html  p=png  s=svg  t=tsv
  -o, --output-dir dir    Directory for output files (default: input file dir)
  -O, --output-name name  Output file name without extension (default: input stem)
  -p, --prepend file      YAML file to prepend to the input (repeatable)
  -V, --version           Print version and exit
  -h, --help              Show help

For each input file wgo produces the requested outputs:

• NAME.gv — Graphviz DOT source (always byte-identical to WireViz)
• NAME.svg / NAME.png — rendered via Graphviz dot (if installed)
• NAME.html — diagram + BOM in a HTML template
• NAME.bom.tsv — Bill of Materials

Example

wgo -f gt examples/ex01.yml

Package layout

cmd/wgo/       CLI entry point            (wv_cli.py)
pkg/parser/    YAML load + parse pipeline (wireviz.py, schema/parser)
pkg/model/     data structures            (DataClasses.py, wv_colors.py)
pkg/graph/     DOT + Graphviz HTML labels (graphviz lib 0.21, wv_gv_html.py)
pkg/harness/   harness + BOM              (Harness.py, wv_bom.py)
pkg/html/      HTML output + SVG embed    (wv_html.py, svgembed.py)
pkg/utils/     helpers, ordered maps      (wv_helper.py)

Notes on porting fidelity

• DOT source serialization replicates the graphviz Python library v0.21 (sorted attribute lists, ''.join(body) source assembly, quote/quote_edge identifier rules).
• YAML scalars are resolved with the same rules as PyYAML (YAML 1.1): e.g. 08500030 stays a string, 0123 is octal, yes is a bool, 1e3 stays a string, and quoted scalars are always strings.
• YAML merge keys (<<:) and anchors are supported, including multiple merge keys per mapping.
• Dict insertion order is preserved everywhere it matters (connectors, cables, metadata, BOM grouping), matching Python's ordered dicts.
• File writes use text-mode semantics: \n is translated to \r\n on Windows, exactly like Python's open(..., newline=None).
• Render errors when Graphviz dot is missing are surfaced as errors, matching the reference behavior.

The original agent.md spec mentions parser.py, graph.py, markdown.py, and a schema/ directory; the current WireViz repository has a different layout (no Markdown output) and this port follows the actual repository.

Testing

The golden outputs in testdata/golden were generated by the reference WireViz 0.4.1 (with graphviz 0.21 and Graphviz 15.1.0) for every example in testdata/. The integration test regenerates all outputs with wgo and diffs them byte-for-byte:

go test ./...

If Graphviz dot is on PATH, the test also covers SVG, PNG, and HTML outputs; otherwise it covers .gv and .bom.tsv.

To regenerate goldens from the reference implementation:

python -m venv .venv
.venv/Scripts/pip install wireviz==0.4.1
.venv/Scripts/wireviz -f ghtsp -O <name> testdata/<name>.yml
# copy outputs into testdata/golden/

License

wgo is a derivative work of WireViz (Copyright (C) Daniel Rojas and the WireViz contributors), which is distributed under the GNU General Public License, version 3.

wgo is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

wgo is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with wgo. If not, see https://www.gnu.org/licenses/.

See NOTICE for authorship, provenance, and third-party attributions.