Skip to content

feat: --format mermaid draws --architecture as a Mermaid flowchart - #77

Merged
inth3shadows merged 3 commits into
masterfrom
p5-mermaid
Nov 19, 2026
Merged

inth3shadows merged 3 commits into
masterfrom
p5-mermaid

Conversation

@inth3shadows

@inth3shadows inth3shadows commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner

What

--architecture can now draw a Mermaid flowchart instead of a graphviz image:

codeshot --architecture --path . --group-depth 2 --format mermaid --embed README.md
  • GitHub renders Mermaid inline in markdown. With --embed, the diagram goes into the doc as a ```mermaid block between the markers: no image file to commit, and no graphviz needed at all.
  • --out writes the Mermaid text to a .mmd file. --embed --check compares the block (and the --out file, if named) byte for byte.
  • It is the same graph the image shows: the same files and edges, --group-depth, --max-render, test files dashed, --forbid/--rules violations red, and with several sources, edges only some found dashed with each source's weight and a title naming the sources. The alt text becomes the diagram's accessible title.
  • codeshot warns when a diagram is past GitHub's Mermaid limits (500 edges, 50,000 characters) and suggests --max-render or --group-depth.
  • The README now shows this repo's own architecture this way, grouped by directory, and the CI diagrams job checks it stays current.

Mermaid is --architecture only for now; symbol mode and --diff refuse --format mermaid and keep drawing with graphviz. This is P5b of the program.

How

  • One drawing step for both formats. The part of the DOT builder that decides what is drawn (the edges between the top --max-render files, and their files in first-seen order) is now a shared function, and the Mermaid builder uses it too, so the two formats can't disagree. DOT output is unchanged.
  • Mermaid syntax: flowchart LR; nodes n0..nN with quoted labels, and ", #, <, >, & escaped as #N; entities. Test files use a dashed classDef. Edges are --> with the weight, or -.-> with each source's weight when only some sources saw them. Violations are made red by one linkStyle line that refers to edges by position. A multi-source legend goes in the frontmatter title:.
  • Output: a separate tail that writes text, never calls graphviz, and compares bytes for --check (the text is deterministic, so no structural comparison is needed).
  • Dropped: translating codeshot's own DOT text into Mermaid (it would parse our output, and every DOT tweak would break it); one shared graph model for all three modes (it would refactor symbol mode and --diff too); rendering Mermaid to SVG (a Node and Chromium dependency, when graphviz already makes SVGs).

Measured (base 33a034b vs 9e3ea62, Linux, Go 1.26.5)

  • Rendering (verified): every case below renders with mermaid-cli 11.4.2, run against headless Chromium outside the repo. The images were checked by eye.
    • this repo grouped (--group-depth 2)
    • this repo per file, 154 edges
    • two sources (codegraph + scip-go), with the title and dashed per-source edges
    • rule violations drawn red
    • labels with ", #, <, >, & and app/[slug]/ displayed as typed, and a dashed test-file box
  • DOT unchanged (verified): 5 runs give identical DOT, stderr and exit code on base and this branch: plain, failing rules, two sources with --group-depth, --max-render with --forbid, and symbol mode.
  • New tests: 4 in mermaid_test.go. One checks the exact output for a small graph with a test file and a red edge, and that --max-render keeps the same files as DOT. The others cover multi-source styling and escaping; the title, the limit warning and blank detection; and an end-to-end run from a snapshot with an empty PATH (no graphviz): --out, --embed writing a block and no image file, --check passing then failing on an edited block, and refusal in symbol mode and --diff.
  • Full suite: go test ./... ok; golangci-lint v2.15.0 0 issues.; gofmt and go vet clean.
  • Committed diagrams: all three regenerated from a fresh clone with the CI codegraph build (fork tag v1.6.2-em.44); each --check exits 0, including the new README block.

Changes since review (2026-11-18)

Round 1 (/code-review + a code-reviewer agent on 9e3ea62, the agent rendering every case with mermaid-cli), fixed in b674689:

  • Labels Mermaid would misread. A file path starting with a backtick made the whole diagram fail to parse ("Lexical error"), src\new\node.go rendered as three lines (\n is a Mermaid line break), and %%{init}%%, fa: and $$ were read as a directive, an icon and math. \, backtick, %, $ and : are now escaped as entities too, and a CR becomes a space like LF. Verified with mermaid-cli: all of them, plus app/[slug]/, render as typed.
  • Its own marker. A Mermaid embed is now codeshot:arch-...-mermaid, so it can sit beside the graphviz image of the same graph in one doc; before, the two commands overwrote each other's block. README's block is arch-d2-mermaid.
  • The size warning measures what is written, title included: a 50,036-character file used to get no warning.
  • Format mismatch: --out arch.mmd without --format mermaid (which wrote PNG bytes silently), and --format mermaid with a .svg name, are warned about.
  • CI: one step per committed diagram, so a PR that stales several learns of all of them in one run. TECHNICAL's CI paragraph counts three diagrams.
  • More tests: --embed with --out writes both, --check with a missing --out file fails, a blank graph is refused, two sources through the CLI.
  • Filed to Multi-source --architecture: one code path for one or many sources, and run sources in parallel #73: deciding blankness from the drawn files rather than a regex, and sharing one embed/check tail between graphviz and Mermaid.
  • go test ./... ok; golangci-lint v2.15.0 0 issues.; DOT output vs master 5/5 identical; all three diagram checks exit 0 (fresh clone, fork v1.6.2-em.44).

Round 2 (verify on b674689): every round-1 fix held. The agent rendered 71 odd paths with mermaid-cli and every label decoded to its input; 14 non-Mermaid runs matched master; the three CI checks passed on a fresh index. Low items fixed in 30045e5:

  • The format-mismatch warning compares a real extension only (--format mermaid --out arch no longer says "ends in '.arch'"), and .md/.txt are fine homes for Mermaid text.
  • CI: the later diagram checks still run after an earlier check fails, but not after a setup step (build, index) fails, which only added "command not found" noise.
  • With --embed and --out, stdout names the .mmd file and --check says it compared it.
  • The size limit counts characters as Mermaid does (UTF-16 units, frontmatter stripped first), so a multi-source diagram just under the limit isn't wrongly warned about.
  • A carriage return can't break the accessible title; one label replacer is built once.
  • Accepted: a marker clash needs a snapshot tool literally named <x>-mermaid; --format dot --out x.mmd now warns, as intended.
  • go test ./... ok; golangci-lint v2.15.0 0 issues.; DOT vs master 4/4 identical; the three diagram checks exit 0; CI 5/5.

Known limits

  • That GitHub's Mermaid limits are 500 edges and 50,000 characters is assumed from Mermaid's defaults, not checked against GitHub.
  • How GitHub renders the README block is checked after this PR is pushed, not before. The local render used mermaid-cli, which can differ slightly from GitHub's renderer in layout and fonts.
  • The README diagram shows call counts, so a change that moves them needs a README regeneration too, as docs/architecture.svg already does.
  • No tooltips or click links, and Mermaid is --architecture only.

`codeshot --architecture --format mermaid` writes the architecture graph
as Mermaid text, which GitHub renders inline: with --embed the diagram
goes into the doc as a mermaid block, with no image file and no
graphviz, and --check compares it byte for byte. It is the same graph
as the image (one shared drawing step): grouping, --max-render, test
files dashed, violations red, multi-source dashed edges with per-source
weights. Warns past GitHub's 500-edge / 50,000-character limit.

README now shows this repo's grouped architecture as Mermaid, checked
in the CI diagrams job.

P5b of the program.
- F1: labels also escape what Mermaid interprets ('\', backtick, '%',
  '$', ':'; CR as a space), so a path starting with a backtick no longer
  breaks the whole diagram and "src\new" isn't a line break.
- F2: the size limit is checked on the text as written.
- F4: --out *.mmd with another --format, and --format mermaid with a
  graphviz extension, are warned about.
- F5: a Mermaid embed has its own marker (arch-...-mermaid), so it sits
  beside the graphviz image of the same graph instead of overwriting it;
  README's block is now arch-d2-mermaid.
- F6: one CI step per committed diagram, so every stale one is reported.
- F3/C3: TECHNICAL's CI paragraph counts three diagrams; the title is
  quoted with strconv.Quote.
- V1: the format-mismatch warning compares a real extension only (a dot
  in the file's own name), and .md/.txt are fine for Mermaid text.
- V2: the later diagram checks run after an earlier check fails, not
  after a setup step does.
- V5: with --embed and --out, stdout names the .mmd file and --check
  says it compared it.
- V6: the size limit counts UTF-16 units without the frontmatter, as
  Mermaid does.
- V3/V10/V11: a CR can't break the accessible title; one label
  replacer; the Mermaid marker and extension set in one place.
@inth3shadows
inth3shadows merged commit b76efec into master Nov 19, 2026
5 checks passed
@inth3shadows
inth3shadows deleted the p5-mermaid branch November 19, 2026 10:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant