Repository navigation
feat: --format mermaid draws --architecture as a Mermaid flowchart - #77
Merged
Merged
Conversation
`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.
Open
11 tasks
- 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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
--architecturecan now draw a Mermaid flowchart instead of a graphviz image:codeshot --architecture --path . --group-depth 2 --format mermaid --embed README.md--embed, the diagram goes into the doc as a```mermaidblock between the markers: no image file to commit, and no graphviz needed at all.--outwrites the Mermaid text to a.mmdfile.--embed --checkcompares the block (and the--outfile, if named) byte for byte.--group-depth,--max-render, test files dashed,--forbid/--rulesviolations 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.--max-renderor--group-depth.Mermaid is
--architectureonly for now; symbol mode and--diffrefuse--format mermaidand keep drawing with graphviz. This is P5b of the program.How
--max-renderfiles, 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.flowchart LR; nodesn0..nNwith quoted labels, and",#,<,>,&escaped as#N;entities. Test files use a dashedclassDef. Edges are-->with the weight, or-.->with each source's weight when only some sources saw them. Violations are made red by onelinkStyleline that refers to edges by position. A multi-source legend goes in the frontmattertitle:.--check(the text is deterministic, so no structural comparison is needed).--difftoo); rendering Mermaid to SVG (a Node and Chromium dependency, when graphviz already makes SVGs).Measured (base
33a034bvs9e3ea62, Linux, Go 1.26.5)--group-depth 2)",#,<,>,&andapp/[slug]/displayed as typed, and a dashed test-file box--group-depth,--max-renderwith--forbid, and symbol mode.mermaid_test.go. One checks the exact output for a small graph with a test file and a red edge, and that--max-renderkeeps 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 emptyPATH(no graphviz):--out,--embedwriting a block and no image file,--checkpassing then failing on an edited block, and refusal in symbol mode and--diff.go test ./...ok; golangci-lint v2.15.00 issues.; gofmt and go vet clean.--checkexits 0, including the new README block.Changes since review (2026-11-18)
Round 1 (
/code-review+ a code-reviewer agent on9e3ea62, the agent rendering every case with mermaid-cli), fixed inb674689:src\new\node.gorendered as three lines (\nis 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, plusapp/[slug]/, render as typed.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 isarch-d2-mermaid.--out arch.mmdwithout--format mermaid(which wrote PNG bytes silently), and--format mermaidwith a.svgname, are warned about.--embedwith--outwrites both,--checkwith a missing--outfile fails, a blank graph is refused, two sources through the CLI.go test ./...ok; golangci-lint v2.15.00 issues.; DOT output vsmaster5/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 matchedmaster; the three CI checks passed on a fresh index. Low items fixed in30045e5:--format mermaid --out archno longer says "ends in '.arch'"), and.md/.txtare fine homes for Mermaid text.--embedand--out, stdout names the.mmdfile and--checksays it compared it.<x>-mermaid;--format dot --out x.mmdnow warns, as intended.go test ./...ok; golangci-lint v2.15.00 issues.; DOT vsmaster4/4 identical; the three diagram checks exit 0; CI 5/5.Known limits
docs/architecture.svgalready does.--architectureonly.