From 9e3ea628c5a203c6bd904836b59d8eabef4e8d6e Mon Sep 17 00:00:00 2001 From: Eric Minish Date: Wed, 18 Nov 2026 21:48:15 -0500 Subject: [PATCH 1/3] feat: --format mermaid draws --architecture as a Mermaid flowchart `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. --- .github/workflows/ci.yml | 2 + README.md | 33 +- TECHNICAL.md | 6 +- USAGE.md | 26 + docs/architecture.svg | 1791 +++++++++++++++-------------- internal/codeshot/arch.go | 9 +- internal/codeshot/cli.go | 23 +- internal/codeshot/dot.go | 53 +- internal/codeshot/mermaid.go | 77 ++ internal/codeshot/mermaid_test.go | 124 ++ internal/codeshot/output.go | 67 ++ 11 files changed, 1327 insertions(+), 884 deletions(-) create mode 100644 internal/codeshot/mermaid.go create mode 100644 internal/codeshot/mermaid_test.go diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 600d38d..2dbd256 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -135,3 +135,5 @@ jobs: --out docs/architecture.svg --embed TECHNICAL.md --check codeshot BuildDot --path . --format svg \ --out docs/BuildDot-callgraph.svg --embed TECHNICAL.md --check + codeshot --architecture --path . --max-symbols 5000 --group-depth 2 --rules .codeshot.yaml \ + --format mermaid --embed README.md --check diff --git a/README.md b/README.md index 076d888..08ab3c9 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,31 @@ it won't look like a curated conceptual pipeline diagram, it'll look like what the code actually calls into. Codeshot enumerates symbols with one `codegraph query` and reads every callee edge from codegraph's index (`.codegraph/codegraph.db`, found at or above `--path`) in one read-only query, -so the scan takes about a second. Flags specific to this mode: +so the scan takes about a second. + +This repo's own architecture, grouped by directory and drawn as Mermaid, which +GitHub renders right here (`--group-depth 2 --format mermaid --embed +README.md`, kept current by CI): + + +```mermaid +flowchart LR + accTitle: Architecture (grouped by directory, depth 2) — generated by codeshot + classDef default fill:#f8fafc,stroke:#cbd5e1,color:#334155 + classDef test fill:#f8fafc,stroke:#cbd5e1,color:#334155,stroke-dasharray:4 3 + n0("cmd/codeshot/") + n1("internal/codeshot/") + n2("internal/codegraph/") + n3("internal/scipindex/") + n4("internal/snapshot/") + n0 -->|"1"| n1 + n1 -->|"74"| n2 + n1 -->|"17"| n3 + n1 -->|"37"| n4 +``` + + +Flags specific to this mode: - `--max-symbols` — cap how many symbols get probed (default 500). Codeshot warns on stderr if this cuts the scan short. - `--group-depth ` — roll files up into their first `n` directory segments @@ -123,6 +147,13 @@ so the scan takes about a second. Flags specific to this mode: instead of a list of flags. See [USAGE.md](USAGE.md#a-rules-file) and this repo's own [`.codeshot.yaml`](.codeshot.yaml). +- `--format mermaid` — draw a Mermaid flowchart instead of a graphviz image. + GitHub renders Mermaid inline, so with `--embed` the diagram goes into the + doc as a ```` ```mermaid ```` block and no image file or graphviz is needed; + `--check` compares the block. Same graph, grouping, `--max-render`, + violation colours and multi-source styling as the image. `--architecture` + only for now. See + [USAGE.md](USAGE.md#drawing-with-mermaid-instead-of-graphviz). - `--sarif ` — the `--forbid` and `--rules` violations as SARIF 2.1.0, for GitHub code scanning: each is an alert at the first line in the depending file that calls into the other. Needs a rule to check, and diff --git a/TECHNICAL.md b/TECHNICAL.md index 71507f3..da799fe 100644 --- a/TECHNICAL.md +++ b/TECHNICAL.md @@ -187,6 +187,7 @@ It doubles as a live legend for the [Visual Encoding](#visual-encoding) rules be - **`internal/codeshot/symbol.go`** — `RunSymbolMode`, `resolveSymbol`, `collectTransitive`. - **`internal/snapshot/snapshot.go`** — Go types mirroring graph-assay's `schema/snapshot.v1.json` (`Snapshot`, `Subject`, `Capabilities`, `File`, `Node`, `Edge`, `Unresolved`) and `Read`/`Parse`. `Parse` reads the `schema` id first, so a newer schema is named even if its fields no longer decode as v1, then decodes once into wire types whose required fields are pointers: a required field that is absent or `null` is rejected rather than becoming `""` and silently dropping an edge. It also rejects negative lines, an empty or duplicate node id, and an edge whose endpoint isn't a node. A bad snapshot is rejected whole rather than drawn partly. - **`internal/codeshot/source_snapshot.go`** — `SnapshotSource`, the snapshot implementation of `ArchSource`: nodes become enumerated symbols, edges of codegraph's callee kinds become `IndexRow`s for `FileEdgesFromIndexRows`. +- **`internal/codeshot/mermaid.go`** — `--format mermaid` (`--architecture` only): `BuildArchitectureMermaid` draws the graph `BuildArchitectureDot` draws, from the same `archDrawn` step (the edges between the top `--max-render` files and their files in first-seen order), so the two can't disagree: `flowchart LR`, nodes `n0..nN` with quoted labels escaped as `#N;` entities (`mermaidLabel`), test files in a dashed `classDef`, edges `-->` with the weight, multi-source partial edges `-.->` with each source's weight and the legend as frontmatter `title:`, and violations red through one `linkStyle` line by edge index. `mermaidWithTitle` adds the alt text as `accTitle:`. `MermaidLimitWarning` warns past GitHub's (Mermaid's default) 500 edges or 50,000 characters. Output (`finishMermaid` in `output.go`) needs no graphviz: `--out` writes the text (`.mmd`), `--embed` puts a ```` ```mermaid ```` block in the doc with no image file (the `--out` file too if named), and `--check` compares both byte for byte. `IsBlankDot` recognises a Mermaid node line too, so a blank Mermaid diagram is refused for `--embed` like a blank image. Rendering verified with mermaid-cli 11.4.2 (headless Chromium): grouped, per-file, multi-source, violations and escaped labels. - **`internal/codeshot/sarif.go`** — `--sarif`: `BuildSARIF`/`WriteSARIF` encode violations as a SARIF 2.1.0 log with `encoding/json` (no dependency): one run, driver `codeshot` with the stamped version and two rules (`codeshot/forbid`, `codeshot/layers`, picked by `Violation.Kind`), each rule with `help` text and markdown, one `error` result per violation with the report line as its message (`violationText`, including who saw the edge), the depending file and its first call-site line as the location (line 1 when unknown), the depended-on file as a related location, both as percent-encoded URIs (`sarifURI`; an absolute or Windows drive path becomes a `file://` URI, and a `:` in a relative path's first segment is `%3A` so it can't read as a scheme), and `partialFingerprints.primaryLocationLineHash` = the first 16 bytes of SHA-256 over rule id, rule, from and to, plus `:1` (not the line, the `--rules` path as typed or the reason, so none of those reopens an alert). GitHub tracks alerts by that key and upload-sarif keeps one it is given, so an alert outlives its line moving; an exact duplicate result (the same rule twice on one edge) is written once. Line numbers come from the optional `SiteLiner` interface, asked only when `--sarif` is set and only after the rules ran, so the diagram path is untouched: `CodegraphSource` runs `codegraph.ReadSiteLines` (one read-only `GROUP BY` over the same callee kinds as `--architecture`, imports and file targets aside, with the immutable retry: the smallest edge line above 0, or, for a pair whose edges carry none, the smallest calling node's start line), `SnapshotSource` does the same with the optional edge `line` and the caller's `start`, `ScipSource` asks `scipindex.RefLines` (the first non-import, non-definition reference, read with `SourceRange` because scip-go 0.2.8 writes only the typed range), and `prefixedSource` rebases the inner source's pairs. `codegraph.SiteLine` marks each line exact (a call or reference line) or a start-line fallback, and `keepBest` prefers exact lines, then the smallest, within and across sources; `ReadSiteLines` still gives the fallback on an index whose edges have no line column; `fillSiteLines` merges the sources this way; a source that fails to answer costs only its lines, with a warning (`siteLinesWarning`; an index without the line columns is named as such). Output validated against the SARIF 2.1.0 JSON schema from schemastore (0 errors on this repo's runs: codegraph, SCIP, both, and a clean run). - **`internal/codeshot/rules.go`** — `--rules`: `ReadRules`/`ParseRules` decode the YAML rules file with `go.yaml.in/yaml/v3` (v3.0.6, MIT/Apache-2.0; `KnownFields(true)`, so a misspelt key is an error; `version: 1` required) into `Rules` (`Layers`, `Forbid`, `Allow`), validating every side with `cleanRuleSide` (trim, strip `./`, refuse `**` and bad `path.Match` patterns) and requiring layer paths to be directories. `RuleViolations` is `ForbiddenEdges` when there is no rules file; otherwise it checks the `--forbid` flags and the file's forbid rules together, maps each edge's files to their layer (an error when one file is in two), flags an edge from a lower layer to a higher one, drops every hit an allow rule matches, and sorts heaviest first (`sortViolations`). `ForbidRule.Breaks` / `Violation.Breaks` carry the rules-file forbid wording into `RuleViolationReport`; empty for a flag and for an allow rule (whose `reason` is a note for readers). With `--rules`, the report header and the `--max-render` note both say "architecture rule" and the header counts edges, adding the violation count when one edge breaks several rules; without it the report is the `--forbid` one, unchanged. `ForbidRule.Glob` marks a rules-file rule: `ruleMatches` sends it to `globRuleSideMatches` (segment-by-segment `path.Match`, `\` escapes, a directory side against the file's leading directories; a side with no pattern characters keeps the prefix/exact rule), while a `--forbid` flag keeps `pathMatchesRuleSide`, literal as before, so a bracketed directory such as `app/[slug]/` still matches. `ParseRules` also refuses a second YAML document with anything in it (an empty trailing `---` is fine), a `version` that isn't an integer (naming the type it got), a side starting with `/`, and two layers whose plain directory paths overlap; layers with pattern paths are checked for overlap file by file in `RuleViolations`. YAML over JSON: a rules file wants comments beside its rules. The module was already in the build graph as an indirect dependency of the SCIP bindings. - **`internal/codeshot/sources.go`** — the `--source` list: `parseSourceList` (one entry, or a comma list of two or more; a value that, read as one snapshot or SCIP entry, names an existing file is that one entry, so a file name with a comma still works; otherwise an empty or invalid entry is reported as itself, adding that no such single file exists when the whole value could have been one; the same entry twice is refused), `loadSources` (reads each snapshot and SCIP index, labels it `codegraph`, `snapshot-` or `scip-`, and refuses two entries with one label), `fileSourcePrefix` + `prefixedSource` (a file source's paths are relative to `--path`, codegraph's to its index root, which `FindIndex` may find above `--path`; with codegraph in the list, `pathsRelativeToPath` looks every file of a file source up on disk under `--path` and under the index root, and only a source found more under `--path` (or a tie between found files) is rebased onto the index root, so a repo-wide index read with `--path` below it is not double-prefixed; with no file on disk it decides from the paths (any path already under the prefix means index-root-relative) and `RootGuessWarning` says so; every file source in a list goes through `prefixedSource`, which cleans each path and never prefixes an absolute one; SCIP metadata `project_root` was not used, since it is an absolute path on the machine that ran the indexer), `labelError` (a source's error carries its label; a failing source stops the run instead of being dropped) and `joinAnd` for the alt text. @@ -222,7 +223,7 @@ No environment variables, and no config file read unless `--rules` names one. Al | `--out` | `/callgraph--.` (or `/arch--.` for `--architecture`; see `--embed` for the embed default) | Output file path | | `--limit` | `50` | Max callers/callees fetched from `codegraph` in symbol and `--diff` modes (its own CLI default is 20). Must be a positive integer — rejected with an error otherwise, since `codegraph` silently returns an empty result for a malformed limit rather than erroring itself. **Has no effect in `--architecture`**, which reads the index directly; passing it there prints a warning rather than an error, so v0.3.0 configs that set it keep working. Newer `codegraph` reports truncation outright — its `callers`/`callees` `--json` carries `truncated` and `total` beside the array — and Codeshot uses those when present, so the warning names the real total (`showing 3 of 57 callers … rerun with --limit 57`) and stays silent when nothing was cut. Versions that report neither fall back to the older signal: the result count hitting `--limit` exactly. That fallback guesses in both directions — it warns for a symbol with exactly `--limit` real results and no more, and can never say how many were cut — which is precisely what the reported fields remove. | | `--max-render` | unset (no cap) | Caps how many *distinct* (post-dedup) nodes are actually drawn, independent of `--limit`. In symbol mode this is **one shared budget across callers, callees, and `--depth`'s transitive edges combined** — not an independent `N` for each dimension (that was the original design, but it let `--max-render 20` draw up to 60 nodes once `--depth` added a third dimension, defeating the flag's purpose of keeping the image readable). Spent in priority order — direct callers first, then direct callees, then transitive edges — so the direct trail is never starved to make room for deeper hops. Exists because `--limit` controls what's fetched, not what's legible. Opt-in and orthogonal to `--limit`: fetch wide (to get an accurate truncation signal) while rendering narrow. Must be a positive integer if given. When it truncates, a stderr warning per dimension states how many of that dimension's distinct total were actually rendered (its real allotment, not the raw `--max-render` value). | -| `--format` | `png` | Passed straight to `dot -T` — no allowlist of its own, so any format `dot -T` supports works, and an unsupported one surfaces `dot`'s own error (which lists the valid ones) rather than a Codeshot-invented one. `svg` is the notable alternative: unlike a raster PNG it stays crisp at any zoom and keeps text selectable, which helps more than `--max-render` alone when a graph is dense but you still want to inspect all of it. | +| `--format` | `png` | `mermaid` (`--architecture` only) writes a Mermaid flowchart instead, with no graphviz (see `mermaid.go`). Anything else is passed straight to `dot -T` — no allowlist of its own, so any format `dot -T` supports works, and an unsupported one surfaces `dot`'s own error (which lists the valid ones) rather than a Codeshot-invented one. `svg` is the notable alternative: unlike a raster PNG it stays crisp at any zoom and keeps text selectable, which helps more than `--max-render` alone when a graph is dense but you still want to inspect all of it. | | `--depth` | `1` (direct-only) | How many hops of callers-of-callers / callees-of-callees to draw beyond the direct trail. Must be a positive integer. `codegraph`'s own `callers`/`callees` have no traversal depth of their own, so Codeshot implements this client-side: `collectTransitive` calls `callers`/`callees` on each newly discovered node, sequentially (see External Dependencies), up to `--depth` hops or `--max-depth-nodes` (below) total discovered nodes, whichever comes first. Fan-out is multiplicative with depth and branching factor, so the budget exists to stop a well-connected symbol at `--depth 3`+ from turning into hundreds of sequential `codegraph` calls; if the budget is hit first, `DepthBudgetWarning` prints a stderr note that the graph beyond that point is incomplete. Each hop beyond the first is drawn in a progressively lighter edge color (`DepthColor`) so distance from the symbol is visible at a glance; `--limit` and `--max-render` are NOT applied per-hop, only globally to the depth-1 fetch/render. Has no meaning with `--architecture` or `--diff` and is rejected if explicitly passed alongside either. | | `--max-depth-nodes` | `200` | Only meaningful with `--depth > 1`: raises or lowers `collectTransitive`'s total-discovered-node safety cap. Must be a positive integer. Exposed as a flag because a well-connected symbol at `--depth 3`+ can legitimately need a higher cap to finish, a coverage/speed tradeoff only the caller can make. Like `--depth`, it's rejected only when an *explicit, non-default* value is passed alongside `--architecture` or `--diff` (`--max-depth-nodes 200` is a silent no-op). | | `--architecture` | `false` | Switches to whole-repo file-level dependency graph mode instead of a single symbol's trail — see the second pipeline diagram above. Mutually exclusive with the `` positional and with `--diff`. | @@ -256,9 +257,10 @@ codeshot --architecture --path --out /tmp/arch.svg --format svg # manua codeshot --architecture --path --group-depth 1 --format dot # manual smoke test, directory-rollup view (prints DOT source) codeshot --diff --diff-ref HEAD~1 --path --out /tmp/diff.svg --format svg # manual smoke test, diff mode -# Regenerate this doc's two committed diagrams after a code change (CI runs the same two commands with --check appended): +# Regenerate the committed diagrams after a code change, this doc's two and README's Mermaid one (CI runs the same commands with --check appended): codeshot --architecture --path . --max-symbols 5000 --rules .codeshot.yaml --format svg --out docs/architecture.svg --embed TECHNICAL.md codeshot BuildDot --path . --format svg --out docs/BuildDot-callgraph.svg --embed TECHNICAL.md +codeshot --architecture --path . --max-symbols 5000 --group-depth 2 --rules .codeshot.yaml --format mermaid --embed README.md ``` CI (`.github/workflows/ci.yml`) has three jobs. `test` runs `gofmt`, `go vet`, `go test ./...` (no codegraph, so the end-to-end tests self-skip) and golangci-lint v2.15.0. `test-npm-codegraph` runs `go test ./...` again with npm codegraph 1.6.0 installed and this repo indexed, so the end-to-end tests run; a weekly scheduled run swaps in unpinned `@latest`, to catch an upstream release that changes the output codeshot parses or the index schema `--architecture` reads. `diagrams` is a separate blocking job: it builds codegraph from the inth3shadows/codegraph fork at tag `v1.6.2-em.44` (commit `d9d138de`, pinned by SHA since tags are mutable, WASM-only — upstream 1.6.2 plus the fork's narrow patches), builds a fresh index and `codeshot`, and runs both diagram commands above with `--check`, so a PR that changes the call graph without regenerating the committed SVGs fails. The committed diagrams must be regenerated with that same build, from a fresh clone (a reused index can miss edges a fresh `init` finds). With Node 22 for every step (codegraph refuses Node 25+), build the commit CI pins in a directory outside this repo, so `init` doesn't index it: `git init cg && git -C cg fetch --depth 1 https://github.com/inth3shadows/codegraph.git && git -C cg checkout FETCH_HEAD && (cd cg && npm ci && npm run build)`. Put a `codegraph` on `PATH` that runs `CODEGRAPH_KERNEL=0 node /dist/bin/codegraph.js "$@"` (CI writes the same wrapper), then in a fresh clone of this repo run `codegraph init .` and the two diagram commands above without `--check`. Pushing a `v*` tag runs `.github/workflows/release.yml`, which runs the tests, cross-compiles six static binaries (linux, darwin and windows, amd64 and arm64; `CGO_ENABLED=0`) with the version stamped in by `-ldflags`, writes `checksums.txt`, and publishes them as a GitHub Release. diff --git a/USAGE.md b/USAGE.md index ffbe8c8..006ca92 100644 --- a/USAGE.md +++ b/USAGE.md @@ -328,6 +328,32 @@ name contains a comma still works on its own when the file exists. Listing the sources in another order changes the edge order, the labels and the `--embed` marker, so it is a different diagram. +### Drawing with Mermaid instead of graphviz + +`--format mermaid` writes the architecture diagram as a +[Mermaid](https://mermaid.js.org/) flowchart, which GitHub, GitLab and many +docs sites render straight from markdown: + +```bash +codeshot --architecture --path . --group-depth 2 --format mermaid --embed README.md +``` + +With `--embed`, the diagram goes into the doc as a ```` ```mermaid ```` block +between the markers, so there is no image file to commit and graphviz isn't +needed at all; `--out` also writes the 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` and `--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. + +GitHub won't render a Mermaid diagram with more than 500 edges or 50,000 +characters, and codeshot warns when one does: narrow it with `--max-render` or +`--group-depth` (a per-file graph of a large repo is past that; a grouped one +usually isn't). Mermaid is `--architecture` only for now; symbol mode and +`--diff` draw with graphviz. + ## Diagramming just what a diff touched A third question, narrower than either of the above: "what does *this diff --git a/docs/architecture.svg b/docs/architecture.svg index 765ac8d..1cd8802 100644 --- a/docs/architecture.svg +++ b/docs/architecture.svg @@ -4,1549 +4,1638 @@ - - + + architecture - + cmd/codeshot/main.go - -cmd/codeshot/main.go + +cmd/codeshot/main.go internal/codeshot/cli.go - -internal/codeshot/cli.go + +internal/codeshot/cli.go cmd/codeshot/main.go->internal/codeshot/cli.go - - -1 + + +1 internal/codegraph/codegraph.go - -internal/codegraph/codegraph.go + +internal/codegraph/codegraph.go - + internal/codeshot/cli.go->internal/codegraph/codegraph.go - - -1 + + +1 internal/codeshot/arch.go - -internal/codeshot/arch.go + +internal/codeshot/arch.go - + internal/codeshot/cli.go->internal/codeshot/arch.go - - -9 + + +9 internal/codeshot/graph.go - -internal/codeshot/graph.go + +internal/codeshot/graph.go - + internal/codeshot/cli.go->internal/codeshot/graph.go - - -1 + + +1 internal/codeshot/rules.go - -internal/codeshot/rules.go + +internal/codeshot/rules.go - + internal/codeshot/cli.go->internal/codeshot/rules.go - - -1 + + +1 internal/codeshot/source_scip.go - -internal/codeshot/source_scip.go + +internal/codeshot/source_scip.go - + internal/codeshot/cli.go->internal/codeshot/source_scip.go - - -3 + + +3 internal/codeshot/sources.go - -internal/codeshot/sources.go + +internal/codeshot/sources.go - + internal/codeshot/cli.go->internal/codeshot/sources.go - - -6 + + +6 internal/codeshot/source_snapshot.go - -internal/codeshot/source_snapshot.go + +internal/codeshot/source_snapshot.go - + internal/codeshot/cli.go->internal/codeshot/source_snapshot.go - - -5 + + +5 internal/codeshot/sarif.go - -internal/codeshot/sarif.go + +internal/codeshot/sarif.go - + internal/codeshot/cli.go->internal/codeshot/sarif.go - - -1 + + +1 internal/codeshot/warnings.go - -internal/codeshot/warnings.go + +internal/codeshot/warnings.go - + internal/codeshot/cli.go->internal/codeshot/warnings.go - - -4 + + +4 - + internal/codeshot/diff.go - -internal/codeshot/diff.go + +internal/codeshot/diff.go - + internal/codeshot/cli.go->internal/codeshot/diff.go - - -6 + + +6 - + internal/codeshot/callsource.go - -internal/codeshot/callsource.go + +internal/codeshot/callsource.go - + internal/codeshot/cli.go->internal/codeshot/callsource.go - - -1 + + +1 - + internal/codeshot/source_snapshot_calls.go - -internal/codeshot/source_snapshot_calls.go + +internal/codeshot/source_snapshot_calls.go - + internal/codeshot/cli.go->internal/codeshot/source_snapshot_calls.go - - -1 + + +1 - + internal/codeshot/output.go - -internal/codeshot/output.go + +internal/codeshot/output.go - + internal/codeshot/cli.go->internal/codeshot/output.go - - -3 + + +3 - + internal/codeshot/source_scip_calls.go - -internal/codeshot/source_scip_calls.go + +internal/codeshot/source_scip_calls.go - + internal/codeshot/cli.go->internal/codeshot/source_scip_calls.go - - -1 + + +1 - + internal/codeshot/symbol.go - -internal/codeshot/symbol.go + +internal/codeshot/symbol.go - + internal/codeshot/cli.go->internal/codeshot/symbol.go - - -2 + + +2 - + internal/scipindex/scipindex.go - -internal/scipindex/scipindex.go + +internal/scipindex/scipindex.go - + internal/codeshot/cli.go->internal/scipindex/scipindex.go - - -1 + + +1 - + internal/snapshot/snapshot.go - -internal/snapshot/snapshot.go + +internal/snapshot/snapshot.go - + internal/codeshot/cli.go->internal/snapshot/snapshot.go - - -1 + + +1 internal/codegraph/codegraph_test.go - -internal/codegraph/codegraph_test.go + +internal/codegraph/codegraph_test.go internal/codegraph/codegraph_test.go->internal/codegraph/codegraph.go - - -9 + + +9 internal/codegraph/index.go - -internal/codegraph/index.go + +internal/codegraph/index.go internal/codegraph/codegraph_test.go->internal/codegraph/index.go - - -1 + + +1 internal/codegraph/index_test.go - -internal/codegraph/index_test.go + +internal/codegraph/index_test.go internal/codegraph/index_test.go->internal/codegraph/index.go - - -12 + + +12 internal/codeshot/arch.go->internal/codegraph/codegraph.go - - -4 + + +4 internal/codeshot/arch.go->internal/codegraph/index.go - - -4 + + +4 internal/codeshot/dot.go - -internal/codeshot/dot.go + +internal/codeshot/dot.go internal/codeshot/arch.go->internal/codeshot/dot.go - - -10 + + +10 internal/codeshot/arch.go->internal/codeshot/graph.go - - -10 + + +10 internal/codeshot/arch.go->internal/codeshot/rules.go - - -3 + + +3 internal/codeshot/arch.go->internal/codeshot/source_scip.go - - -4 + + +4 internal/codeshot/arch.go->internal/codeshot/sources.go - - -5 + + +5 internal/codeshot/arch.go->internal/codeshot/source_snapshot.go - - -3 + + +3 internal/codeshot/sources_test.go - -internal/codeshot/sources_test.go + +internal/codeshot/sources_test.go internal/codeshot/arch.go->internal/codeshot/sources_test.go - - -12 + + +12 internal/codeshot/arch.go->internal/codeshot/sarif.go - - -2 + + +2 internal/codeshot/arch.go->internal/codeshot/warnings.go - - -9 + + +9 - + + +internal/codeshot/mermaid.go + +internal/codeshot/mermaid.go + + +internal/codeshot/arch.go->internal/codeshot/mermaid.go + + +2 + + + internal/codeshot/arch.go->internal/codeshot/diff.go - - -1 + + +1 - + internal/codeshot/dot.go->internal/codeshot/arch.go - - -3 + + +3 - + internal/codeshot/dot.go->internal/codeshot/graph.go - - -25 + + +25 - + internal/codeshot/dot.go->internal/codeshot/warnings.go - - -1 + + +1 - + internal/codeshot/graph.go->internal/codegraph/codegraph.go - - -1 + + +1 - + internal/codeshot/rules.go->internal/codeshot/arch.go - - -11 + + +11 - + internal/codeshot/rules.go->internal/codeshot/dot.go - - -1 + + +1 - + internal/codeshot/rules.go->internal/codeshot/warnings.go - - -1 + + +1 - + internal/codeshot/source_scip.go->internal/codeshot/arch.go - - -2 + + +2 - + internal/codeshot/source_scip.go->internal/codeshot/graph.go - - -2 + + +2 - + internal/codeshot/source_scip.go->internal/codeshot/source_snapshot.go - - -1 + + +1 - + internal/codeshot/source_scip.go->internal/scipindex/scipindex.go - - -4 + + +4 - + internal/codeshot/sources.go->internal/codeshot/cli.go - - -1 + + +1 - + internal/codeshot/sources.go->internal/codegraph/codegraph.go - - -1 + + +1 - + internal/codeshot/sources.go->internal/codegraph/index.go - - -1 + + +1 - + internal/codeshot/sources.go->internal/codeshot/arch.go - - -10 + + +10 - + internal/codeshot/sources.go->internal/codeshot/graph.go - - -2 + + +2 - + internal/codeshot/sources.go->internal/codeshot/source_scip.go - - -3 + + +3 - + internal/codeshot/sources.go->internal/codeshot/source_snapshot.go - - -4 + + +4 - + internal/codeshot/sources.go->internal/codeshot/warnings.go - - -3 + + +3 - + internal/codeshot/sources.go->internal/codeshot/diff.go - - -1 + + +1 - + internal/codeshot/sources.go->internal/scipindex/scipindex.go - - -1 + + +1 - + internal/codeshot/sources.go->internal/snapshot/snapshot.go - - -1 + + +1 - + internal/codeshot/source_snapshot.go->internal/codegraph/index.go - - -1 + + +1 - + internal/codeshot/source_snapshot.go->internal/codeshot/arch.go - - -3 + + +3 - + internal/codeshot/source_snapshot.go->internal/codeshot/graph.go - - -2 + + +2 - + internal/codeshot/source_snapshot.go->internal/snapshot/snapshot.go - - -8 + + +8 - + internal/codeshot/sources_test.go->internal/codegraph/codegraph.go - - -1 + + +1 - + internal/codeshot/sources_test.go->internal/codeshot/arch.go - - -14 + + +14 - + internal/codeshot/sources_test.go->internal/codeshot/dot.go - - -6 + + +6 - + internal/codeshot/sources_test.go->internal/codeshot/graph.go - - -8 + + +8 - + internal/codeshot/sources_test.go->internal/codeshot/sources.go - - -11 + + +11 - + internal/codeshot/sources_test.go->internal/codeshot/warnings.go - - -2 + + +2 - + internal/codeshot/helpers_test.go - -internal/codeshot/helpers_test.go + +internal/codeshot/helpers_test.go - + internal/codeshot/sources_test.go->internal/codeshot/helpers_test.go - - -22 + + +22 internal/codeshot/source_snapshot_test.go - -internal/codeshot/source_snapshot_test.go + +internal/codeshot/source_snapshot_test.go - + internal/codeshot/sources_test.go->internal/codeshot/source_snapshot_test.go - - -4 + + +4 - + internal/codeshot/sarif.go->internal/codegraph/index.go - - -16 + + +16 - + internal/codeshot/sarif.go->internal/codeshot/arch.go - - -5 + + +5 - + internal/codeshot/sarif.go->internal/codeshot/sources.go - - -1 + + +1 - + internal/codeshot/sarif.go->internal/codeshot/warnings.go - - -2 + + +2 - + internal/codeshot/sarif.go->internal/scipindex/scipindex.go - - -1 + + +1 - + internal/codeshot/sarif_test.go - -internal/codeshot/sarif_test.go + +internal/codeshot/sarif_test.go - + internal/codeshot/sarif.go->internal/codeshot/sarif_test.go - - -2 + + +2 - + internal/codeshot/warnings.go->internal/codegraph/codegraph.go - - -3 + + +3 - + internal/codeshot/warnings.go->internal/codeshot/arch.go - - -8 + + +8 - + internal/codeshot/warnings.go->internal/codeshot/dot.go - - -3 + + +3 - + internal/codeshot/warnings.go->internal/codeshot/graph.go - - -5 + + +5 - + internal/codeshot/wording.go - -internal/codeshot/wording.go + +internal/codeshot/wording.go - + internal/codeshot/warnings.go->internal/codeshot/wording.go - - -7 + + +7 + + + +internal/codeshot/mermaid.go->internal/codeshot/arch.go + + +1 + + + +internal/codeshot/mermaid.go->internal/codeshot/dot.go + + +3 + + + +internal/codeshot/mermaid.go->internal/codeshot/graph.go + + +1 + + + +internal/codeshot/mermaid.go->internal/codeshot/warnings.go + + +1 - + internal/codeshot/diff.go->internal/codegraph/codegraph.go - - -4 + + +4 - + internal/codeshot/diff.go->internal/codeshot/arch.go - - -3 + + +3 - + internal/codeshot/diff.go->internal/codeshot/dot.go - - -1 + + +1 - + internal/codeshot/diff.go->internal/codeshot/graph.go - - -7 + + +7 - + internal/codeshot/diff.go->internal/codeshot/warnings.go - - -12 + + +12 - + internal/codeshot/diff.go->internal/codeshot/callsource.go - - -4 + + +4 - + internal/codeshot/arch_test.go - -internal/codeshot/arch_test.go + +internal/codeshot/arch_test.go - + internal/codeshot/arch_test.go->internal/codegraph/index.go - - -1 + + +1 - + internal/codeshot/arch_test.go->internal/codeshot/arch.go - - -26 + + +26 - + internal/codeshot/arch_test.go->internal/codeshot/graph.go - - -1 + + +1 - + internal/codeshot/arch_test.go->internal/codeshot/diff.go - - -2 + + +2 - + internal/codeshot/arch_test.go->internal/codeshot/helpers_test.go - - -9 + + +9 - + internal/codeshot/helpers_test.go->internal/codeshot/cli.go - - -1 + + +1 - + internal/codeshot/helpers_test.go->internal/codeshot/dot.go - - -1 + + +1 - + internal/codeshot/helpers_test.go->internal/codeshot/graph.go - - -1 + + +1 - + internal/codeshot/callsource.go->internal/codegraph/codegraph.go - - -5 + + +5 - + internal/codeshot/callsource.go->internal/codeshot/arch.go - - -1 + + +1 - + internal/codeshot/callsource.go->internal/codeshot/graph.go - - -2 + + +2 - + internal/codeshot/callsource.go->internal/codeshot/diff.go - - -1 + + +1 - + internal/codeshot/callsource.go->internal/codeshot/source_snapshot_calls.go - - -4 + + +4 - + internal/codeshot/callsource.go->internal/codeshot/wording.go - - -2 + + +2 - + internal/codeshot/source_snapshot_calls.go->internal/codegraph/codegraph.go - - -3 + + +3 - + internal/codeshot/source_snapshot_calls.go->internal/codeshot/arch.go - - -2 + + +2 - + internal/codeshot/source_snapshot_calls.go->internal/codeshot/graph.go - - -3 + + +3 - + internal/codeshot/source_snapshot_calls.go->internal/codeshot/source_snapshot.go - - -2 + + +2 - + internal/codeshot/source_snapshot_calls.go->internal/codeshot/diff.go - - -2 + + +2 - + internal/codeshot/source_snapshot_calls.go->internal/codeshot/wording.go - - -4 + + +4 - + internal/codeshot/source_snapshot_calls.go->internal/snapshot/snapshot.go - - -9 + + +9 - + internal/codeshot/output.go->internal/codeshot/warnings.go - - -1 + + +2 + + + +internal/codeshot/output.go->internal/codeshot/mermaid.go + + +1 - + internal/codeshot/output.go->internal/codeshot/diff.go - - -2 + + +3 - + internal/codeshot/source_scip_calls.go->internal/codeshot/source_scip.go - - -2 + + +2 - + internal/codeshot/source_scip_calls.go->internal/codeshot/source_snapshot_calls.go - - -2 + + +2 - + internal/codeshot/source_scip_calls.go->internal/codeshot/wording.go - - -1 + + +1 - + internal/codeshot/source_scip_calls.go->internal/scipindex/scipindex.go - - -3 + + +3 - + internal/codeshot/source_scip_calls.go->internal/snapshot/snapshot.go - - -3 + + +3 - + internal/scipindex/calls.go - -internal/scipindex/calls.go + +internal/scipindex/calls.go - + internal/codeshot/source_scip_calls.go->internal/scipindex/calls.go - - -2 + + +2 - + internal/codeshot/symbol.go->internal/codegraph/codegraph.go - - -3 + + +3 - + internal/codeshot/symbol.go->internal/codeshot/arch.go - - -3 + + +3 - + internal/codeshot/symbol.go->internal/codeshot/dot.go - - -2 + + +2 - + internal/codeshot/symbol.go->internal/codeshot/graph.go - - -8 + + +8 - + internal/codeshot/symbol.go->internal/codeshot/warnings.go - - -6 + + +6 - + internal/codeshot/symbol.go->internal/codeshot/callsource.go - - -6 + + +6 - + internal/codeshot/cli_test.go - -internal/codeshot/cli_test.go + +internal/codeshot/cli_test.go - + internal/codeshot/cli_test.go->internal/codeshot/cli.go - - -1 + + +1 - + internal/codeshot/cli_test.go->internal/codeshot/arch.go - - -1 + + +1 - + internal/codeshot/cli_test.go->internal/codeshot/graph.go - - -1 + + +1 - + internal/codeshot/cli_test.go->internal/codeshot/helpers_test.go - - -82 + + +82 - + internal/codeshot/diff_test.go - -internal/codeshot/diff_test.go + +internal/codeshot/diff_test.go - + internal/codeshot/diff_test.go->internal/codegraph/codegraph.go - - -15 + + +15 - + internal/codeshot/diff_test.go->internal/codeshot/graph.go - - -1 + + +1 - + internal/codeshot/diff_test.go->internal/codeshot/warnings.go - - -6 + + +6 - + internal/codeshot/diff_test.go->internal/codeshot/diff.go - - -16 + + +16 - + internal/codeshot/diff_test.go->internal/codeshot/helpers_test.go - - -14 + + +14 - + internal/codeshot/dot_test.go - -internal/codeshot/dot_test.go + +internal/codeshot/dot_test.go - + internal/codeshot/dot_test.go->internal/codeshot/arch.go - - -2 + + +2 - + internal/codeshot/dot_test.go->internal/codeshot/dot.go - - -51 + + +51 - + internal/codeshot/dot_test.go->internal/codeshot/graph.go - - -3 + + +3 - + internal/codeshot/dot_test.go->internal/codeshot/helpers_test.go - - -62 + + +62 - + internal/codeshot/graph_test.go - -internal/codeshot/graph_test.go + +internal/codeshot/graph_test.go - + internal/codeshot/graph_test.go->internal/codeshot/graph.go - - -11 + + +11 - + internal/codeshot/graph_test.go->internal/codeshot/helpers_test.go - - -5 + + +5 + + + +internal/codeshot/mermaid_test.go + +internal/codeshot/mermaid_test.go + + + +internal/codeshot/mermaid_test.go->internal/codeshot/arch.go + + +1 + + + +internal/codeshot/mermaid_test.go->internal/codeshot/dot.go + + +5 + + + +internal/codeshot/mermaid_test.go->internal/codeshot/mermaid.go + + +5 + + + +internal/codeshot/mermaid_test.go->internal/codeshot/helpers_test.go + + +5 + + + +internal/codeshot/mermaid_test.go->internal/codeshot/source_snapshot_test.go + + +1 + + + +internal/codeshot/source_snapshot_test.go->internal/codeshot/arch.go + + +3 + + + +internal/codeshot/source_snapshot_test.go->internal/codeshot/graph.go + + +1 + + + +internal/codeshot/source_snapshot_test.go->internal/codeshot/source_snapshot.go + + +9 + + + +internal/codeshot/source_snapshot_test.go->internal/codeshot/helpers_test.go + + +15 + + + +internal/codeshot/source_snapshot_test.go->internal/snapshot/snapshot.go + + +8 - + internal/codeshot/output_test.go - -internal/codeshot/output_test.go + +internal/codeshot/output_test.go - + internal/codeshot/output_test.go->internal/codeshot/dot.go - - -1 + + +1 - + internal/codeshot/output_test.go->internal/codeshot/helpers_test.go - - -7 + + +7 - + internal/codeshot/output_test.go->internal/codeshot/output.go - - -10 + + +10 - + internal/codeshot/output_test.go->internal/codeshot/dot_test.go - - -1 + + +1 - + internal/codeshot/rules_test.go - -internal/codeshot/rules_test.go + +internal/codeshot/rules_test.go - + internal/codeshot/rules_test.go->internal/codeshot/arch.go - - -4 + + +4 - + internal/codeshot/rules_test.go->internal/codeshot/dot.go - - -1 + + +1 - + internal/codeshot/rules_test.go->internal/codeshot/rules.go - - -21 + + +21 - + internal/codeshot/rules_test.go->internal/codeshot/warnings.go - - -4 + + +4 - + internal/codeshot/rules_test.go->internal/codeshot/helpers_test.go - - -20 + + +20 - + internal/codeshot/rules_test.go->internal/codeshot/source_snapshot_test.go - - -2 - - - -internal/codeshot/source_snapshot_test.go->internal/codeshot/arch.go - - -3 - - - -internal/codeshot/source_snapshot_test.go->internal/codeshot/graph.go - - -1 - - - -internal/codeshot/source_snapshot_test.go->internal/codeshot/source_snapshot.go - - -9 - - - -internal/codeshot/source_snapshot_test.go->internal/codeshot/helpers_test.go - - -15 - - - -internal/codeshot/source_snapshot_test.go->internal/snapshot/snapshot.go - - -8 + + +2 - + internal/codeshot/sarif_test.go->internal/codegraph/index.go - - -9 + + +9 - + internal/codeshot/sarif_test.go->internal/codeshot/arch.go - - -1 + + +1 - + internal/codeshot/sarif_test.go->internal/codeshot/sources.go - - -1 + + +1 - + internal/codeshot/sarif_test.go->internal/codeshot/source_snapshot.go - - -2 + + +2 - + internal/codeshot/sarif_test.go->internal/codeshot/sarif.go - - -12 + + +12 - + internal/codeshot/sarif_test.go->internal/codeshot/helpers_test.go - - -15 + + +15 - + internal/codeshot/sarif_test.go->internal/snapshot/snapshot.go - - -2 - - - -internal/codeshot/sarif_test.go->internal/codeshot/rules_test.go - - -1 + + +2 - + internal/codeshot/sarif_test.go->internal/codeshot/source_snapshot_test.go - - -3 + + +3 + + + +internal/codeshot/sarif_test.go->internal/codeshot/rules_test.go + + +1 - + internal/codeshot/source_scip_calls_test.go - -internal/codeshot/source_scip_calls_test.go + +internal/codeshot/source_scip_calls_test.go - + internal/codeshot/source_scip_calls_test.go->internal/codeshot/helpers_test.go - - -15 + + +15 - + internal/codeshot/source_scip_calls_test.go->internal/codeshot/source_scip_calls.go - - -1 + + +1 - + internal/codeshot/source_scip_calls_test.go->internal/scipindex/scipindex.go - - -1 + + +1 - + internal/codeshot/source_scip_test.go - -internal/codeshot/source_scip_test.go + +internal/codeshot/source_scip_test.go - + internal/codeshot/source_scip_test.go->internal/codeshot/arch.go - - -1 + + +1 - + internal/codeshot/source_scip_test.go->internal/codeshot/source_scip.go - - -8 + + +8 - + internal/codeshot/source_scip_test.go->internal/codeshot/helpers_test.go - - -14 + + +14 - + internal/codeshot/source_scip_test.go->internal/scipindex/scipindex.go - - -4 + + +4 - + internal/codeshot/source_snapshot_calls_test.go - -internal/codeshot/source_snapshot_calls_test.go + +internal/codeshot/source_snapshot_calls_test.go - + internal/codeshot/source_snapshot_calls_test.go->internal/codegraph/codegraph.go - - -1 + + +1 - + internal/codeshot/source_snapshot_calls_test.go->internal/codeshot/diff.go - - -1 + + +1 - + internal/codeshot/source_snapshot_calls_test.go->internal/codeshot/helpers_test.go - - -14 + + +14 - + internal/codeshot/source_snapshot_calls_test.go->internal/codeshot/source_snapshot_calls.go - - -13 + + +13 - + internal/codeshot/source_snapshot_calls_test.go->internal/codeshot/symbol.go - - -6 + + +6 - + internal/codeshot/source_snapshot_calls_test.go->internal/snapshot/snapshot.go - - -5 + + +5 - + internal/codeshot/source_snapshot_calls_test.go->internal/codeshot/diff_test.go - - -4 + + +4 - + internal/codeshot/source_snapshot_calls_test.go->internal/codeshot/source_snapshot_test.go - - -8 + + +8 - + internal/codeshot/warnings_test.go - -internal/codeshot/warnings_test.go + +internal/codeshot/warnings_test.go - + internal/codeshot/warnings_test.go->internal/codeshot/arch.go - - -1 + + +1 - + internal/codeshot/warnings_test.go->internal/codeshot/dot.go - - -2 + + +2 - + internal/codeshot/warnings_test.go->internal/codeshot/graph.go - - -1 + + +1 - + internal/codeshot/warnings_test.go->internal/codeshot/warnings.go - - -29 + + +29 - + internal/codeshot/warnings_test.go->internal/codeshot/helpers_test.go - - -29 + + +29 - + internal/scipindex/calls_test.go - -internal/scipindex/calls_test.go + +internal/scipindex/calls_test.go - + internal/scipindex/calls_test.go->internal/scipindex/scipindex.go - - -2 + + +2 - + internal/scipindex/calls_test.go->internal/scipindex/calls.go - - -4 + + +4 - + internal/scipindex/scipindex_test.go - -internal/scipindex/scipindex_test.go + +internal/scipindex/scipindex_test.go - + internal/scipindex/calls_test.go->internal/scipindex/scipindex_test.go - - -2 + + +2 - + internal/scipindex/scipindex_test.go->internal/scipindex/scipindex.go - - -15 + + +15 - + internal/snapshot/snapshot_test.go - -internal/snapshot/snapshot_test.go + +internal/snapshot/snapshot_test.go - + internal/snapshot/snapshot_test.go->internal/snapshot/snapshot.go - - -4 + + +4 diff --git a/internal/codeshot/arch.go b/internal/codeshot/arch.go index fb762b1..b6a7d20 100644 --- a/internal/codeshot/arch.go +++ b/internal/codeshot/arch.go @@ -507,6 +507,7 @@ type ArchParams struct { Rules *Rules // --rules; nil when not given Tooltips bool // svg: per-source edge weights (multi-source only) SiteLines bool // --sarif: look up each violation's first call-site line + Mermaid bool // --format mermaid: a Mermaid flowchart instead of DOT } // ArchSource is where --architecture's graph comes from: every symbol in @@ -666,7 +667,13 @@ func finishArchitecture(rawFileEdges []FileEdge, p ArchParams, sources []string, what = "an architecture rule" } warn(stderr, HiddenRuleViolationNote(fileEdges, violating, p.MaxRender, what)) - return BuildArchitectureDot(fileEdges, ArchOptions{MaxRender: p.MaxRender, Violating: violating, Sources: sources, Tooltips: p.Tooltips}), violations, nil + opt := ArchOptions{MaxRender: p.MaxRender, Violating: violating, Sources: sources, Tooltips: p.Tooltips} + if p.Mermaid { + text := BuildArchitectureMermaid(fileEdges, opt) + warn(stderr, MermaidLimitWarning(text)) + return text, violations, nil + } + return BuildArchitectureDot(fileEdges, opt), violations, nil } // warn prints a non-empty message as one stderr line. diff --git a/internal/codeshot/cli.go b/internal/codeshot/cli.go index f58e0e4..a91fcd7 100644 --- a/internal/codeshot/cli.go +++ b/internal/codeshot/cli.go @@ -330,6 +330,11 @@ func run(args []string, stdout, stderr io.Writer) (int, error) { if format == "" { return 0, &Exit{Code: 1, Stderr: "codeshot: --format must not be empty"} } + // --format mermaid: a Mermaid flowchart (text), not a graphviz render. + mermaid := strings.EqualFold(format, "mermaid") + if mermaid && !arch { + return 0, &Exit{Code: 1, Stderr: "codeshot: --format mermaid only applies with --architecture for now; symbol mode and --diff draw with graphviz"} + } depthRaw := get("depth", "1") depth, err := positiveInt("depth", depthRaw) if err != nil { @@ -492,6 +497,10 @@ func run(args []string, stdout, stderr io.Writer) (int, error) { for _, m := range multi { archMarkerID += "-" + m.label } + ext := format + if mermaid { + ext = "mmd" + } if !hasOut { var base string // #51: no checkout-directory name in an embedded image's default @@ -523,9 +532,9 @@ func run(args []string, stdout, stderr io.Writer) (int, error) { if embedFile != "" { // Stable, next to the doc: the link resolves and re-runs overwrite it. dir, _ := filepath.Abs(filepath.Dir(embedFile)) - outFile = filepath.Join(dir, fmt.Sprintf("codeshot-%s.%s", base, format)) + outFile = filepath.Join(dir, fmt.Sprintf("codeshot-%s.%s", base, ext)) } else { - outFile = filepath.Join(os.TempDir(), fmt.Sprintf("%s-%d.%s", base, time.Now().UnixMilli(), format)) + outFile = filepath.Join(os.TempDir(), fmt.Sprintf("%s-%d.%s", base, time.Now().UnixMilli(), ext)) } } else { warn(stderr, FormatMismatchWarning(outFile, format)) @@ -536,8 +545,10 @@ func run(args []string, stdout, stderr io.Writer) (int, error) { return 0, err } } - if err := requireOnPath("dot", "Install graphviz (e.g. `brew install graphviz` or `apt install graphviz`)."); err != nil { - return 0, err + if !mermaid { + if err := requireOnPath("dot", "Install graphviz (e.g. `brew install graphviz` or `apt install graphviz`)."); err != nil { + return 0, err + } } if diffMode { if err := requireOnPath("git", "Install git (e.g. `apt install git`) — --diff shells out to `git diff` to find changed files."); err != nil { @@ -562,7 +573,7 @@ func run(args []string, stdout, stderr io.Writer) (int, error) { calls = sc } tooltips := strings.EqualFold(format, "svg") || strings.EqualFold(format, "svgz") - out := OutputParams{Format: format, OutFile: outFile, EmbedFile: embedFile, Check: check} + out := OutputParams{Format: format, OutFile: outFile, EmbedFile: embedFile, Check: check, Mermaid: mermaid, WriteOut: hasOut} switch { case diffMode: @@ -594,7 +605,7 @@ func run(args []string, stdout, stderr io.Writer) (int, error) { case scipIdx != nil: src = ScipSource{Index: scipIdx} } - ap := ArchParams{MaxSymbols: maxSymbols, MaxRender: maxRender, GroupDepth: groupDepth, Forbid: rules, Rules: rulesFile, Tooltips: tooltips, SiteLines: hasSARIF} + ap := ArchParams{MaxSymbols: maxSymbols, MaxRender: maxRender, GroupDepth: groupDepth, Forbid: rules, Rules: rulesFile, Tooltips: tooltips, SiteLines: hasSARIF, Mermaid: mermaid} var dot string var violations []Violation if multi != nil { diff --git a/internal/codeshot/dot.go b/internal/codeshot/dot.go index 4d3e0e2..d05c18b 100644 --- a/internal/codeshot/dot.go +++ b/internal/codeshot/dot.go @@ -118,26 +118,7 @@ type ArchOptions struct { // BuildArchitectureDot draws the file-level dependency graph, keeping only the // top --max-render files by edge weight, with --forbid violations in red. func BuildArchitectureDot(fileEdges []FileEdge, opt ArchOptions) string { - keep := TopFilesByWeight(fileEdges, opt.MaxRender) - kept := fileEdges - if keep != nil { - kept = nil - for _, e := range fileEdges { - if keep[e.From] && keep[e.To] { - kept = append(kept, e) - } - } - } - var files []string - seen := map[string]bool{} - for _, e := range kept { - for _, f := range []string{e.From, e.To} { - if !seen[f] { - seen[f] = true - files = append(files, f) - } - } - } + kept, files := archDrawn(fileEdges, opt.MaxRender) lines := []string{"digraph architecture {", graphAttrs, nodeAttrs, edgeAttrs} multi := len(opt.Sources) > 1 if multi { @@ -174,6 +155,32 @@ func BuildArchitectureDot(fileEdges []FileEdge, opt ArchOptions) string { return strings.Join(lines, "\n") } +// archDrawn is what an architecture diagram draws, in DOT and Mermaid alike: +// the edges between the top --max-render files, in order, and their files +// in first-seen order. +func archDrawn(fileEdges []FileEdge, maxRender int) (kept []FileEdge, files []string) { + keep := TopFilesByWeight(fileEdges, maxRender) + kept = fileEdges + if keep != nil { + kept = nil + for _, e := range fileEdges { + if keep[e.From] && keep[e.To] { + kept = append(kept, e) + } + } + } + seen := map[string]bool{} + for _, e := range kept { + for _, f := range []string{e.From, e.To} { + if !seen[f] { + seen[f] = true + files = append(files, f) + } + } + } + return kept, files +} + // BuildDiffDot draws every root (a symbol in a changed file) bold, with its // direct callers/callees. Roots are always drawn; --max-render bounds only // the non-root context around them. @@ -241,8 +248,8 @@ func BuildDiffDot(roots []Node, edges []Edge, maxRender int, tooltips bool) stri return strings.Join(lines, "\n") } -var blankDotRe = regexp.MustCompile(`(?m)^\s*"`) +var blankDotRe = regexp.MustCompile(`(?m)^\s*("|n[0-9]+\()`) -// IsBlankDot reports a DOT that declares no node: every builder starts a node -// statement with its quoted id. +// IsBlankDot reports a diagram that declares no node: every DOT builder starts +// a node statement with its quoted id, and the Mermaid one with "nN(". func IsBlankDot(dot string) bool { return !blankDotRe.MatchString(dot) } diff --git a/internal/codeshot/mermaid.go b/internal/codeshot/mermaid.go new file mode 100644 index 0000000..93f3236 --- /dev/null +++ b/internal/codeshot/mermaid.go @@ -0,0 +1,77 @@ +package codeshot + +import ( + "fmt" + "strings" +) + +// GitHub renders Mermaid with its defaults, which refuse larger diagrams. +const ( + mermaidMaxEdges = 500 + mermaidMaxText = 50000 +) + +// mermaidLabel escapes text for a quoted Mermaid label: '#' first, since the +// others become "#N;" entities. +func mermaidLabel(s string) string { + return strings.NewReplacer("#", "#35;", `"`, "#34;", "<", "#60;", ">", "#62;", "&", "#38;", "\n", " ").Replace(s) +} + +// BuildArchitectureMermaid draws the same graph as BuildArchitectureDot as a +// Mermaid flowchart: the same files and edges (archDrawn), test files dashed, +// --forbid/--rules violations red, and, with several sources, edges only some +// saw dashed with each source's weight and a title naming the sources. +func BuildArchitectureMermaid(fileEdges []FileEdge, opt ArchOptions) string { + kept, files := archDrawn(fileEdges, opt.MaxRender) + var lines []string + multi := len(opt.Sources) > 1 + if multi { + title := fmt.Sprintf("Sources: %s. Dashed: not every source saw all of the edge; its label gives each source's own weight.", strings.Join(opt.Sources, ", ")) + lines = append(lines, "---", "title: "+strings.ReplaceAll(fmt.Sprintf("%q", title), `\'`, "'"), "---") + } + lines = append(lines, "flowchart LR", + " classDef default fill:#f8fafc,stroke:#cbd5e1,color:#334155", + " classDef test fill:#f8fafc,stroke:#cbd5e1,color:#334155,stroke-dasharray:4 3") + id := make(map[string]string, len(files)) + for i, f := range files { + id[f] = fmt.Sprintf("n%d", i) + class := "" + if IsTestRef("", f) { + class = ":::test" + } + lines = append(lines, fmt.Sprintf(` %s("%s")%s`, id[f], mermaidLabel(f), class)) + } + var red []string + for i, e := range kept { + label, arrow := fmt.Sprintf("%d", e.Weight), "-->" + if multi && len(e.Full) < len(opt.Sources) { + label, arrow = seenList(e.Seen, opt.Sources), "-.->" + } + lines = append(lines, fmt.Sprintf(` %s %s|"%s"| %s`, id[e.From], arrow, mermaidLabel(label), id[e.To])) + if opt.Violating[drawnEdgeKey(e.From, e.To)] { + red = append(red, fmt.Sprintf("%d", i)) + } + } + if len(red) > 0 { + lines = append(lines, " linkStyle "+strings.Join(red, ",")+" stroke:#dc2626,color:#dc2626,stroke-width:2px") + } + return strings.Join(lines, "\n") +} + +// mermaidWithTitle adds the accessible title (the alt text) after the +// flowchart line. +func mermaidWithTitle(text, title string) string { + if title == "" { + return text + } + return strings.Replace(text, "flowchart LR\n", "flowchart LR\n accTitle: "+strings.ReplaceAll(title, "\n", " ")+"\n", 1) +} + +// MermaidLimitWarning: GitHub won't render a Mermaid diagram past its limits. +func MermaidLimitWarning(text string) string { + edges := strings.Count(text, "-->|") + strings.Count(text, "-.->|") + if edges <= mermaidMaxEdges && len(text) <= mermaidMaxText { + return "" + } + return fmt.Sprintf("codeshot: the Mermaid diagram has %d edges and %d characters; GitHub renders at most %d edges and %d characters, so it will show an error there. Narrow it with --max-render or --group-depth.", edges, len(text), mermaidMaxEdges, mermaidMaxText) +} diff --git a/internal/codeshot/mermaid_test.go b/internal/codeshot/mermaid_test.go new file mode 100644 index 0000000..077aa50 --- /dev/null +++ b/internal/codeshot/mermaid_test.go @@ -0,0 +1,124 @@ +package codeshot + +import ( + "os" + "os/exec" + "path/filepath" + "regexp" + "slices" + "strings" + "testing" +) + +func TestBuildArchitectureMermaidDrawsTheSameGraphAsDot(t *testing.T) { + edges := []FileEdge{ + {From: "src/a.go", To: "lib/b.go", Weight: 5}, + {From: "src/a_test.go", To: "src/a.go", Weight: 2}, + {From: "src/a.go", To: "db/q.go", Weight: 1}, + } + opt := ArchOptions{MaxRender: Unlimited, Violating: map[string]bool{drawnEdgeKey("src/a.go", "db/q.go"): true}} + got := BuildArchitectureMermaid(edges, opt) + want := strings.Join([]string{ + "flowchart LR", + " classDef default fill:#f8fafc,stroke:#cbd5e1,color:#334155", + " classDef test fill:#f8fafc,stroke:#cbd5e1,color:#334155,stroke-dasharray:4 3", + ` n0("src/a.go")`, + ` n1("lib/b.go")`, + ` n2("src/a_test.go"):::test`, + ` n3("db/q.go")`, + ` n0 -->|"5"| n1`, + ` n2 -->|"2"| n0`, + ` n0 -->|"1"| n3`, + " linkStyle 2 stroke:#dc2626,color:#dc2626,stroke-width:2px", + }, "\n") + if got != want { + t.Errorf("got:\n%s\nwant:\n%s", got, want) + } + // --max-render keeps the same files in both formats. + opt.MaxRender = 2 + dotFiles := regexp.MustCompile(`(?m)^ "([^"]+)"(?: \[[^]]*\])?;$`).FindAllStringSubmatch(BuildArchitectureDot(edges, opt), -1) + mmdFiles := regexp.MustCompile(`(?m)^ n[0-9]+\("([^"]+)"\)`).FindAllStringSubmatch(BuildArchitectureMermaid(edges, opt), -1) + var a, b []string + for _, m := range dotFiles { + a = append(a, m[1]) + } + for _, m := range mmdFiles { + b = append(b, m[1]) + } + if !slices.Equal(a, b) || len(a) != 2 { + t.Errorf("--max-render 2: dot %v, mermaid %v", a, b) + } +} + +func TestBuildArchitectureMermaidMultiSourceAndEscaping(t *testing.T) { + edges := []FileEdge{ + {From: `a "q" #1 .go`, To: "b.go", Weight: 5, Seen: []SourceWeight{{"cg", 3}, {"scip", 5}}, Full: []string{"cg", "scip"}}, + {From: "b.go", To: "c.go", Weight: 2, Seen: []SourceWeight{{"scip", 2}}, Full: []string{"scip"}}, + } + got := BuildArchitectureMermaid(edges, ArchOptions{MaxRender: Unlimited, Sources: []string{"cg", "scip"}}) + wantMatch(t, `(?s)^---\ntitle: "Sources: cg, scip\. Dashed: not every source saw all of the edge; its label gives each source's own weight\."\n---\nflowchart LR\n`, got) + wantMatch(t, `n0\("a #34;q#34; #35;1 #60;x#62;\.go"\)`, got) + wantMatch(t, `n0 -->\|"5"\| n1`, got) + wantMatch(t, `n1 -\.->\|"scip 2"\| n2`, got) +} + +func TestMermaidTitleAndLimits(t *testing.T) { + wantMatch(t, "^flowchart LR\n accTitle: Architecture — generated by codeshot\n classDef", mermaidWithTitle(BuildArchitectureMermaid(nil, ArchOptions{MaxRender: Unlimited}), "Architecture — generated by codeshot")) + if w := MermaidLimitWarning(strings.Repeat(" n0 -->|\"1\"| n1\n", 500)); w != "" { + t.Errorf("500 edges warned: %s", w) + } + wantMatch(t, `has 501 edges .* GitHub renders at most 500 edges`, MermaidLimitWarning(strings.Repeat(" n0 -->|\"1\"| n1\n", 501))) + wantMatch(t, `GitHub renders at most 500 edges and 50000 characters`, MermaidLimitWarning(strings.Repeat("x", 50001))) + if !IsBlankDot(BuildArchitectureMermaid(nil, ArchOptions{MaxRender: Unlimited})) { + t.Error("an empty Mermaid diagram is not blank") + } + if IsBlankDot(BuildArchitectureMermaid([]FileEdge{{From: "a", To: "b", Weight: 1}}, ArchOptions{MaxRender: Unlimited})) { + t.Error("a Mermaid diagram with nodes is blank") + } +} + +// End to end from a snapshot with no graphviz on PATH: --out writes the +// .mmd text, --embed puts a mermaid block in the doc and no image file, +// --check compares it, and symbol mode refuses the format. +func TestCLIMermaidNeedsNoGraphvizAndEmbedsABlock(t *testing.T) { + t.Setenv("PATH", t.TempDir()) + if _, err := exec.LookPath("dot"); err == nil { + t.Skip("dot still on PATH") + } + dir := t.TempDir() + snap := "snapshot:" + writeSnapshotFile(t, cliSnapshot) + out := filepath.Join(dir, "arch.mmd") + if code, _, stderr := runCLI("--architecture", "--source", snap, "--format", "mermaid", "--out", out); code != 0 { + t.Fatalf("--out: exit %d; stderr: %s", code, stderr) + } + data, _ := os.ReadFile(out) + wantMatch(t, `(?s)^flowchart LR\n accTitle: Architecture \(from the t snapshot\) — generated by codeshot\n.*n0 -->\|"1"\| n1\n$`, string(data)) + + doc := filepath.Join(dir, "doc.md") + if err := os.WriteFile(doc, []byte("# Doc\n"), 0o644); err != nil { + t.Fatal(err) + } + if code, _, stderr := runCLI("--architecture", "--source", snap, "--format", "mermaid", "--embed", doc); code != 0 { + t.Fatalf("--embed: exit %d; stderr: %s", code, stderr) + } + md, _ := os.ReadFile(doc) + wantMatch(t, "(?s)\n```mermaid\nflowchart LR\n.*\n```\n", string(md)) + if matches, _ := filepath.Glob(filepath.Join(dir, "codeshot-*")); len(matches) != 0 { + t.Errorf("--embed wrote an image file: %v", matches) + } + if code, stdout, stderr := runCLI("--architecture", "--source", snap, "--format", "mermaid", "--embed", doc, "--check"); code != 0 { + t.Fatalf("--check current: exit %d; stderr: %s", code, stderr) + } else { + wantMatch(t, `up to date — the codeshot:arch-snapshot-t block`, stdout) + } + if err := os.WriteFile(doc, []byte(strings.Replace(string(md), `-->|"1"|`, `-->|"2"|`, 1)), 0o644); err != nil { + t.Fatal(err) + } + if code, _, stderr := runCLI("--architecture", "--source", snap, "--format", "mermaid", "--embed", doc, "--check"); code != 1 { + t.Errorf("--check stale: exit %d, want 1", code) + } else { + wantMatch(t, `the codeshot:arch-snapshot-t block in .* is out of date`, stderr) + } + wantRejected(t, `--format mermaid only applies with --architecture`, "Foo", "--format", "mermaid") + wantRejected(t, `--format mermaid only applies with --architecture`, "--diff", "--format", "mermaid") +} diff --git a/internal/codeshot/output.go b/internal/codeshot/output.go index f0443db..9ea1ccd 100644 --- a/internal/codeshot/output.go +++ b/internal/codeshot/output.go @@ -129,6 +129,10 @@ func EmbedRelLink(embedFile, imagePath string) string { type OutputParams struct { Format, OutFile, EmbedFile, MarkerID, Alt string Check bool + // Mermaid: the diagram is Mermaid text, written as is (no graphviz); + // with --embed it goes in the doc as a mermaid block, and the file is + // written only when --out named one (WriteOut). + Mermaid, WriteOut bool } func missingEmbed(embedFile string) *Exit { @@ -138,6 +142,9 @@ func missingEmbed(embedFile string) *Exit { // FinishOutput renders the image; with --embed also refreshes the doc block; // with --embed --check regenerates in memory and verifies both, writing nothing. func FinishOutput(dot string, p OutputParams, stdout, stderr io.Writer) error { + if p.Mermaid { + return finishMermaid(mermaidWithTitle(dot, p.Alt)+"\n", p, stdout, stderr) + } if p.EmbedFile == "" { if _, err := renderDot(dot, p.Format, p.OutFile); err != nil { return err @@ -207,3 +214,63 @@ func FinishOutput(dot string, p OutputParams, stdout, stderr io.Writer) error { fmt.Fprintln(stdout, p.OutFile) return nil } + +// finishMermaid writes a Mermaid diagram: to --out, and/or as a mermaid block +// in the --embed doc. --check compares both byte for byte (Mermaid text is +// deterministic, so no structural comparison is needed) and writes nothing. +func finishMermaid(text string, p OutputParams, stdout, stderr io.Writer) error { + writeOut := p.WriteOut || p.EmbedFile == "" + if p.EmbedFile == "" { + if err := os.WriteFile(p.OutFile, []byte(text), 0o644); err != nil { + return err + } + fmt.Fprintln(stdout, p.OutFile) + return nil + } + raw, err := os.ReadFile(p.EmbedFile) + if err != nil { + return missingEmbed(p.EmbedFile) + } + doc := string(raw) + expected, err := ApplyEmbed(doc, p.MarkerID, "```mermaid\n"+text+"```") + if err != nil { + return &Exit{Code: 1, Stderr: "codeshot: " + err.Error()} + } + if refusal := BlankEmbedRefusal(text, p.EmbedFile, p.Check); refusal != "" { + return &Exit{Code: 1, Stderr: refusal} + } + if p.Check { + var msgs []string + if writeOut { + committed, readErr := os.ReadFile(p.OutFile) + if readErr != nil || string(committed) != text { + why := "differs from a fresh render" + if readErr != nil { + why = "missing" + } + msgs = append(msgs, fmt.Sprintf("codeshot: --check: diagram '%s' is out of date (%s) — rerun 'codeshot ... --embed %s' and commit the result.", p.OutFile, why, p.EmbedFile)) + } + } + if doc != expected { + msgs = append(msgs, fmt.Sprintf("codeshot: --check: the codeshot:%s block in '%s' is out of date or missing — rerun 'codeshot ... --embed %s' and commit the result.", p.MarkerID, p.EmbedFile, p.EmbedFile)) + } + if len(msgs) > 0 { + return &Exit{Code: 1, Stderr: strings.Join(msgs, "\n")} + } + fmt.Fprintf(stdout, "codeshot: up to date — the codeshot:%s block in '%s' matches a fresh render.\n", p.MarkerID, p.EmbedFile) + return nil + } + if writeOut { + if err := os.WriteFile(p.OutFile, []byte(text), 0o644); err != nil { + return err + } + } + if expected != doc { + if err := os.WriteFile(p.EmbedFile, []byte(expected), 0o644); err != nil { + return err + } + fmt.Fprintf(stderr, "codeshot: updated the codeshot:%s block in %s\n", p.MarkerID, p.EmbedFile) + } + fmt.Fprintln(stdout, p.EmbedFile) + return nil +} From b674689bc1de21233e112145937dba2477ce1d32 Mon Sep 17 00:00:00 2001 From: Eric Minish Date: Wed, 18 Nov 2026 22:18:21 -0500 Subject: [PATCH 2/3] fix: Mermaid review round 1 (label escapes, own marker, limits) - 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. --- .github/workflows/ci.yml | 12 +- README.md | 4 +- TECHNICAL.md | 4 +- USAGE.md | 3 +- docs/architecture.svg | 1597 +++++++++++++++-------------- internal/codeshot/arch.go | 4 +- internal/codeshot/cli.go | 5 + internal/codeshot/mermaid.go | 14 +- internal/codeshot/mermaid_test.go | 99 +- internal/codeshot/output.go | 2 + internal/codeshot/warnings.go | 11 + 11 files changed, 950 insertions(+), 805 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2dbd256..c67bd87 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -127,13 +127,21 @@ jobs: - name: Build codeshot run: go build -o "$RUNNER_TEMP/bin/codeshot" ./cmd/codeshot - # Blocking gate: fail the PR if either committed diagram no longer matches + # Blocking gate: fail the PR if a committed diagram no longer matches # what the current code produces, or the code breaks .codeshot.yaml. - - name: Check committed diagrams are current + # One step per diagram, so a PR that stales several learns of all of + # them in one run. + - name: Check docs/architecture.svg is current run: | codeshot --architecture --path . --max-symbols 5000 --rules .codeshot.yaml --format svg \ --out docs/architecture.svg --embed TECHNICAL.md --check + - name: Check docs/BuildDot-callgraph.svg is current + if: ${{ !cancelled() }} + run: | codeshot BuildDot --path . --format svg \ --out docs/BuildDot-callgraph.svg --embed TECHNICAL.md --check + - name: Check README's Mermaid diagram is current + if: ${{ !cancelled() }} + run: | codeshot --architecture --path . --max-symbols 5000 --group-depth 2 --rules .codeshot.yaml \ --format mermaid --embed README.md --check diff --git a/README.md b/README.md index 08ab3c9..8335103 100644 --- a/README.md +++ b/README.md @@ -98,7 +98,7 @@ This repo's own architecture, grouped by directory and drawn as Mermaid, which GitHub renders right here (`--group-depth 2 --format mermaid --embed README.md`, kept current by CI): - + ```mermaid flowchart LR accTitle: Architecture (grouped by directory, depth 2) — generated by codeshot @@ -114,7 +114,7 @@ flowchart LR n1 -->|"17"| n3 n1 -->|"37"| n4 ``` - + Flags specific to this mode: - `--max-symbols` — cap how many symbols get probed (default 500). Codeshot diff --git a/TECHNICAL.md b/TECHNICAL.md index da799fe..529a78b 100644 --- a/TECHNICAL.md +++ b/TECHNICAL.md @@ -187,7 +187,7 @@ It doubles as a live legend for the [Visual Encoding](#visual-encoding) rules be - **`internal/codeshot/symbol.go`** — `RunSymbolMode`, `resolveSymbol`, `collectTransitive`. - **`internal/snapshot/snapshot.go`** — Go types mirroring graph-assay's `schema/snapshot.v1.json` (`Snapshot`, `Subject`, `Capabilities`, `File`, `Node`, `Edge`, `Unresolved`) and `Read`/`Parse`. `Parse` reads the `schema` id first, so a newer schema is named even if its fields no longer decode as v1, then decodes once into wire types whose required fields are pointers: a required field that is absent or `null` is rejected rather than becoming `""` and silently dropping an edge. It also rejects negative lines, an empty or duplicate node id, and an edge whose endpoint isn't a node. A bad snapshot is rejected whole rather than drawn partly. - **`internal/codeshot/source_snapshot.go`** — `SnapshotSource`, the snapshot implementation of `ArchSource`: nodes become enumerated symbols, edges of codegraph's callee kinds become `IndexRow`s for `FileEdgesFromIndexRows`. -- **`internal/codeshot/mermaid.go`** — `--format mermaid` (`--architecture` only): `BuildArchitectureMermaid` draws the graph `BuildArchitectureDot` draws, from the same `archDrawn` step (the edges between the top `--max-render` files and their files in first-seen order), so the two can't disagree: `flowchart LR`, nodes `n0..nN` with quoted labels escaped as `#N;` entities (`mermaidLabel`), test files in a dashed `classDef`, edges `-->` with the weight, multi-source partial edges `-.->` with each source's weight and the legend as frontmatter `title:`, and violations red through one `linkStyle` line by edge index. `mermaidWithTitle` adds the alt text as `accTitle:`. `MermaidLimitWarning` warns past GitHub's (Mermaid's default) 500 edges or 50,000 characters. Output (`finishMermaid` in `output.go`) needs no graphviz: `--out` writes the text (`.mmd`), `--embed` puts a ```` ```mermaid ```` block in the doc with no image file (the `--out` file too if named), and `--check` compares both byte for byte. `IsBlankDot` recognises a Mermaid node line too, so a blank Mermaid diagram is refused for `--embed` like a blank image. Rendering verified with mermaid-cli 11.4.2 (headless Chromium): grouped, per-file, multi-source, violations and escaped labels. +- **`internal/codeshot/mermaid.go`** — `--format mermaid` (`--architecture` only): `BuildArchitectureMermaid` draws the graph `BuildArchitectureDot` draws, from the same `archDrawn` step (the edges between the top `--max-render` files and their files in first-seen order), so the two can't disagree: `flowchart LR`, nodes `n0..nN` with quoted labels escaped as `#N;` entities in one pass (`mermaidLabel`: the quote and HTML characters, and what Mermaid would interpret inside a label: `\` since `\n` is a line break, a backtick since a leading one opens a markdown string, `%` for `%%{...}%%` directives, `$` for math, `:` for `fa:` icons; line breaks become spaces), test files in a dashed `classDef`, edges `-->` with the weight, multi-source partial edges `-.->` with each source's weight and the legend as frontmatter `title:`, and violations red through one `linkStyle` line by edge index. `mermaidWithTitle` adds the alt text as `accTitle:`. `MermaidLimitWarning` warns past GitHub's (Mermaid's default) 500 edges or 50,000 characters, measured on the text as written (title included). A Mermaid embed's marker id ends in `-mermaid`, so it can sit beside the graphviz image of the same graph in one doc. Output (`finishMermaid` in `output.go`) needs no graphviz: `--out` writes the text (`.mmd`), `--embed` puts a ```` ```mermaid ```` block in the doc with no image file (the `--out` file too if named), and `--check` compares both byte for byte. `IsBlankDot` recognises a Mermaid node line too, so a blank Mermaid diagram is refused for `--embed` like a blank image. Rendering verified with mermaid-cli 11.4.2 (headless Chromium): grouped, per-file, multi-source, violations and escaped labels. - **`internal/codeshot/sarif.go`** — `--sarif`: `BuildSARIF`/`WriteSARIF` encode violations as a SARIF 2.1.0 log with `encoding/json` (no dependency): one run, driver `codeshot` with the stamped version and two rules (`codeshot/forbid`, `codeshot/layers`, picked by `Violation.Kind`), each rule with `help` text and markdown, one `error` result per violation with the report line as its message (`violationText`, including who saw the edge), the depending file and its first call-site line as the location (line 1 when unknown), the depended-on file as a related location, both as percent-encoded URIs (`sarifURI`; an absolute or Windows drive path becomes a `file://` URI, and a `:` in a relative path's first segment is `%3A` so it can't read as a scheme), and `partialFingerprints.primaryLocationLineHash` = the first 16 bytes of SHA-256 over rule id, rule, from and to, plus `:1` (not the line, the `--rules` path as typed or the reason, so none of those reopens an alert). GitHub tracks alerts by that key and upload-sarif keeps one it is given, so an alert outlives its line moving; an exact duplicate result (the same rule twice on one edge) is written once. Line numbers come from the optional `SiteLiner` interface, asked only when `--sarif` is set and only after the rules ran, so the diagram path is untouched: `CodegraphSource` runs `codegraph.ReadSiteLines` (one read-only `GROUP BY` over the same callee kinds as `--architecture`, imports and file targets aside, with the immutable retry: the smallest edge line above 0, or, for a pair whose edges carry none, the smallest calling node's start line), `SnapshotSource` does the same with the optional edge `line` and the caller's `start`, `ScipSource` asks `scipindex.RefLines` (the first non-import, non-definition reference, read with `SourceRange` because scip-go 0.2.8 writes only the typed range), and `prefixedSource` rebases the inner source's pairs. `codegraph.SiteLine` marks each line exact (a call or reference line) or a start-line fallback, and `keepBest` prefers exact lines, then the smallest, within and across sources; `ReadSiteLines` still gives the fallback on an index whose edges have no line column; `fillSiteLines` merges the sources this way; a source that fails to answer costs only its lines, with a warning (`siteLinesWarning`; an index without the line columns is named as such). Output validated against the SARIF 2.1.0 JSON schema from schemastore (0 errors on this repo's runs: codegraph, SCIP, both, and a clean run). - **`internal/codeshot/rules.go`** — `--rules`: `ReadRules`/`ParseRules` decode the YAML rules file with `go.yaml.in/yaml/v3` (v3.0.6, MIT/Apache-2.0; `KnownFields(true)`, so a misspelt key is an error; `version: 1` required) into `Rules` (`Layers`, `Forbid`, `Allow`), validating every side with `cleanRuleSide` (trim, strip `./`, refuse `**` and bad `path.Match` patterns) and requiring layer paths to be directories. `RuleViolations` is `ForbiddenEdges` when there is no rules file; otherwise it checks the `--forbid` flags and the file's forbid rules together, maps each edge's files to their layer (an error when one file is in two), flags an edge from a lower layer to a higher one, drops every hit an allow rule matches, and sorts heaviest first (`sortViolations`). `ForbidRule.Breaks` / `Violation.Breaks` carry the rules-file forbid wording into `RuleViolationReport`; empty for a flag and for an allow rule (whose `reason` is a note for readers). With `--rules`, the report header and the `--max-render` note both say "architecture rule" and the header counts edges, adding the violation count when one edge breaks several rules; without it the report is the `--forbid` one, unchanged. `ForbidRule.Glob` marks a rules-file rule: `ruleMatches` sends it to `globRuleSideMatches` (segment-by-segment `path.Match`, `\` escapes, a directory side against the file's leading directories; a side with no pattern characters keeps the prefix/exact rule), while a `--forbid` flag keeps `pathMatchesRuleSide`, literal as before, so a bracketed directory such as `app/[slug]/` still matches. `ParseRules` also refuses a second YAML document with anything in it (an empty trailing `---` is fine), a `version` that isn't an integer (naming the type it got), a side starting with `/`, and two layers whose plain directory paths overlap; layers with pattern paths are checked for overlap file by file in `RuleViolations`. YAML over JSON: a rules file wants comments beside its rules. The module was already in the build graph as an indirect dependency of the SCIP bindings. - **`internal/codeshot/sources.go`** — the `--source` list: `parseSourceList` (one entry, or a comma list of two or more; a value that, read as one snapshot or SCIP entry, names an existing file is that one entry, so a file name with a comma still works; otherwise an empty or invalid entry is reported as itself, adding that no such single file exists when the whole value could have been one; the same entry twice is refused), `loadSources` (reads each snapshot and SCIP index, labels it `codegraph`, `snapshot-` or `scip-`, and refuses two entries with one label), `fileSourcePrefix` + `prefixedSource` (a file source's paths are relative to `--path`, codegraph's to its index root, which `FindIndex` may find above `--path`; with codegraph in the list, `pathsRelativeToPath` looks every file of a file source up on disk under `--path` and under the index root, and only a source found more under `--path` (or a tie between found files) is rebased onto the index root, so a repo-wide index read with `--path` below it is not double-prefixed; with no file on disk it decides from the paths (any path already under the prefix means index-root-relative) and `RootGuessWarning` says so; every file source in a list goes through `prefixedSource`, which cleans each path and never prefixes an absolute one; SCIP metadata `project_root` was not used, since it is an absolute path on the machine that ran the indexer), `labelError` (a source's error carries its label; a failing source stops the run instead of being dropped) and `joinAnd` for the alt text. @@ -263,7 +263,7 @@ codeshot BuildDot --path . --format svg --out docs/BuildDot-callgraph.svg --embe codeshot --architecture --path . --max-symbols 5000 --group-depth 2 --rules .codeshot.yaml --format mermaid --embed README.md ``` -CI (`.github/workflows/ci.yml`) has three jobs. `test` runs `gofmt`, `go vet`, `go test ./...` (no codegraph, so the end-to-end tests self-skip) and golangci-lint v2.15.0. `test-npm-codegraph` runs `go test ./...` again with npm codegraph 1.6.0 installed and this repo indexed, so the end-to-end tests run; a weekly scheduled run swaps in unpinned `@latest`, to catch an upstream release that changes the output codeshot parses or the index schema `--architecture` reads. `diagrams` is a separate blocking job: it builds codegraph from the inth3shadows/codegraph fork at tag `v1.6.2-em.44` (commit `d9d138de`, pinned by SHA since tags are mutable, WASM-only — upstream 1.6.2 plus the fork's narrow patches), builds a fresh index and `codeshot`, and runs both diagram commands above with `--check`, so a PR that changes the call graph without regenerating the committed SVGs fails. The committed diagrams must be regenerated with that same build, from a fresh clone (a reused index can miss edges a fresh `init` finds). With Node 22 for every step (codegraph refuses Node 25+), build the commit CI pins in a directory outside this repo, so `init` doesn't index it: `git init cg && git -C cg fetch --depth 1 https://github.com/inth3shadows/codegraph.git && git -C cg checkout FETCH_HEAD && (cd cg && npm ci && npm run build)`. Put a `codegraph` on `PATH` that runs `CODEGRAPH_KERNEL=0 node /dist/bin/codegraph.js "$@"` (CI writes the same wrapper), then in a fresh clone of this repo run `codegraph init .` and the two diagram commands above without `--check`. Pushing a `v*` tag runs `.github/workflows/release.yml`, which runs the tests, cross-compiles six static binaries (linux, darwin and windows, amd64 and arm64; `CGO_ENABLED=0`) with the version stamped in by `-ldflags`, writes `checksums.txt`, and publishes them as a GitHub Release. +CI (`.github/workflows/ci.yml`) has three jobs. `test` runs `gofmt`, `go vet`, `go test ./...` (no codegraph, so the end-to-end tests self-skip) and golangci-lint v2.15.0. `test-npm-codegraph` runs `go test ./...` again with npm codegraph 1.6.0 installed and this repo indexed, so the end-to-end tests run; a weekly scheduled run swaps in unpinned `@latest`, to catch an upstream release that changes the output codeshot parses or the index schema `--architecture` reads. `diagrams` is a separate blocking job: it builds codegraph from the inth3shadows/codegraph fork at tag `v1.6.2-em.44` (commit `d9d138de`, pinned by SHA since tags are mutable, WASM-only — upstream 1.6.2 plus the fork's narrow patches), builds a fresh index and `codeshot`, and runs the three diagram commands above with `--check`, one step each so a PR learns of every stale diagram in one run, so a PR that changes the call graph without regenerating the committed SVGs and README's Mermaid block fails. The committed diagrams must be regenerated with that same build, from a fresh clone (a reused index can miss edges a fresh `init` finds). With Node 22 for every step (codegraph refuses Node 25+), build the commit CI pins in a directory outside this repo, so `init` doesn't index it: `git init cg && git -C cg fetch --depth 1 https://github.com/inth3shadows/codegraph.git && git -C cg checkout FETCH_HEAD && (cd cg && npm ci && npm run build)`. Put a `codegraph` on `PATH` that runs `CODEGRAPH_KERNEL=0 node /dist/bin/codegraph.js "$@"` (CI writes the same wrapper), then in a fresh clone of this repo run `codegraph init .` and the three diagram commands above without `--check`. Pushing a `v*` tag runs `.github/workflows/release.yml`, which runs the tests, cross-compiles six static binaries (linux, darwin and windows, amd64 and arm64; `CGO_ENABLED=0`) with the version stamped in by `-ldflags`, writes `checksums.txt`, and publishes them as a GitHub Release. There is no service to restart, no rollback beyond installing a prior release or git ref, and no other services, logs, or scheduled jobs to maintain — see [README.md](README.md#install) for the install command itself. diff --git a/USAGE.md b/USAGE.md index 006ca92..8cc2694 100644 --- a/USAGE.md +++ b/USAGE.md @@ -339,7 +339,8 @@ codeshot --architecture --path . --group-depth 2 --format mermaid --embed README ``` With `--embed`, the diagram goes into the doc as a ```` ```mermaid ```` block -between the markers, so there is no image file to commit and graphviz isn't +between its own markers (`codeshot:arch-mermaid`, `arch-d2-mermaid`, ..., so it +can sit beside the graphviz image of the same graph), so there is no image file to commit and graphviz isn't needed at all; `--out` also writes the 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`, diff --git a/docs/architecture.svg b/docs/architecture.svg index 1cd8802..8f08320 100644 --- a/docs/architecture.svg +++ b/docs/architecture.svg @@ -4,1638 +4,1659 @@ - - + + architecture - + cmd/codeshot/main.go - -cmd/codeshot/main.go + +cmd/codeshot/main.go internal/codeshot/cli.go - -internal/codeshot/cli.go + +internal/codeshot/cli.go cmd/codeshot/main.go->internal/codeshot/cli.go - - -1 + + +1 internal/codegraph/codegraph.go - -internal/codegraph/codegraph.go + +internal/codegraph/codegraph.go internal/codeshot/cli.go->internal/codegraph/codegraph.go - - -1 + + +1 internal/codeshot/arch.go - -internal/codeshot/arch.go + +internal/codeshot/arch.go internal/codeshot/cli.go->internal/codeshot/arch.go - - -9 + + +9 internal/codeshot/graph.go - -internal/codeshot/graph.go + +internal/codeshot/graph.go internal/codeshot/cli.go->internal/codeshot/graph.go - - -1 + + +1 internal/codeshot/rules.go - -internal/codeshot/rules.go + +internal/codeshot/rules.go internal/codeshot/cli.go->internal/codeshot/rules.go - - -1 + + +1 internal/codeshot/source_scip.go - -internal/codeshot/source_scip.go + +internal/codeshot/source_scip.go internal/codeshot/cli.go->internal/codeshot/source_scip.go - - -3 + + +3 internal/codeshot/sources.go - -internal/codeshot/sources.go + +internal/codeshot/sources.go internal/codeshot/cli.go->internal/codeshot/sources.go - - -6 + + +6 internal/codeshot/source_snapshot.go - -internal/codeshot/source_snapshot.go + +internal/codeshot/source_snapshot.go internal/codeshot/cli.go->internal/codeshot/source_snapshot.go - - -5 + + +5 internal/codeshot/sarif.go - -internal/codeshot/sarif.go + +internal/codeshot/sarif.go internal/codeshot/cli.go->internal/codeshot/sarif.go - - -1 + + +1 internal/codeshot/warnings.go - -internal/codeshot/warnings.go + +internal/codeshot/warnings.go internal/codeshot/cli.go->internal/codeshot/warnings.go - - -4 + + +4 internal/codeshot/diff.go - -internal/codeshot/diff.go + +internal/codeshot/diff.go internal/codeshot/cli.go->internal/codeshot/diff.go - - -6 + + +6 internal/codeshot/callsource.go - -internal/codeshot/callsource.go + +internal/codeshot/callsource.go internal/codeshot/cli.go->internal/codeshot/callsource.go - - -1 + + +1 internal/codeshot/source_snapshot_calls.go - -internal/codeshot/source_snapshot_calls.go + +internal/codeshot/source_snapshot_calls.go internal/codeshot/cli.go->internal/codeshot/source_snapshot_calls.go - - -1 + + +1 internal/codeshot/output.go - -internal/codeshot/output.go + +internal/codeshot/output.go internal/codeshot/cli.go->internal/codeshot/output.go - - -3 + + +3 internal/codeshot/source_scip_calls.go - -internal/codeshot/source_scip_calls.go + +internal/codeshot/source_scip_calls.go internal/codeshot/cli.go->internal/codeshot/source_scip_calls.go - - -1 + + +1 internal/codeshot/symbol.go - -internal/codeshot/symbol.go + +internal/codeshot/symbol.go internal/codeshot/cli.go->internal/codeshot/symbol.go - - -2 + + +2 internal/scipindex/scipindex.go - -internal/scipindex/scipindex.go + +internal/scipindex/scipindex.go internal/codeshot/cli.go->internal/scipindex/scipindex.go - - -1 + + +1 internal/snapshot/snapshot.go - -internal/snapshot/snapshot.go + +internal/snapshot/snapshot.go internal/codeshot/cli.go->internal/snapshot/snapshot.go - - -1 + + +1 internal/codegraph/codegraph_test.go - -internal/codegraph/codegraph_test.go + +internal/codegraph/codegraph_test.go internal/codegraph/codegraph_test.go->internal/codegraph/codegraph.go - - -9 + + +9 internal/codegraph/index.go - -internal/codegraph/index.go + +internal/codegraph/index.go internal/codegraph/codegraph_test.go->internal/codegraph/index.go - - -1 + + +1 internal/codegraph/index_test.go - -internal/codegraph/index_test.go + +internal/codegraph/index_test.go internal/codegraph/index_test.go->internal/codegraph/index.go - - -12 + + +12 internal/codeshot/arch.go->internal/codegraph/codegraph.go - - -4 + + +4 internal/codeshot/arch.go->internal/codegraph/index.go - - -4 + + +4 internal/codeshot/dot.go - -internal/codeshot/dot.go + +internal/codeshot/dot.go internal/codeshot/arch.go->internal/codeshot/dot.go - - -10 + + +10 internal/codeshot/arch.go->internal/codeshot/graph.go - - -10 + + +10 internal/codeshot/arch.go->internal/codeshot/rules.go - - -3 + + +3 internal/codeshot/arch.go->internal/codeshot/source_scip.go - - -4 + + +4 internal/codeshot/arch.go->internal/codeshot/sources.go - - -5 + + +5 internal/codeshot/arch.go->internal/codeshot/source_snapshot.go - - -3 + + +3 internal/codeshot/sources_test.go - -internal/codeshot/sources_test.go + +internal/codeshot/sources_test.go internal/codeshot/arch.go->internal/codeshot/sources_test.go - - -12 + + +12 internal/codeshot/arch.go->internal/codeshot/sarif.go - - -2 + + +2 internal/codeshot/arch.go->internal/codeshot/warnings.go - - -9 + + +9 internal/codeshot/mermaid.go - -internal/codeshot/mermaid.go + +internal/codeshot/mermaid.go internal/codeshot/arch.go->internal/codeshot/mermaid.go - - -2 + + +1 internal/codeshot/arch.go->internal/codeshot/diff.go - - -1 + + +1 internal/codeshot/dot.go->internal/codeshot/arch.go - - -3 + + +3 internal/codeshot/dot.go->internal/codeshot/graph.go - - -25 + + +25 internal/codeshot/dot.go->internal/codeshot/warnings.go - - -1 + + +1 internal/codeshot/graph.go->internal/codegraph/codegraph.go - - -1 + + +1 - + internal/codeshot/rules.go->internal/codeshot/arch.go - - -11 + + +11 - + internal/codeshot/rules.go->internal/codeshot/dot.go - - -1 + + +1 - + internal/codeshot/rules.go->internal/codeshot/warnings.go - - -1 + + +1 - + internal/codeshot/source_scip.go->internal/codeshot/arch.go - - -2 + + +2 - + internal/codeshot/source_scip.go->internal/codeshot/graph.go - - -2 + + +2 - + internal/codeshot/source_scip.go->internal/codeshot/source_snapshot.go - - -1 + + +1 - + internal/codeshot/source_scip.go->internal/scipindex/scipindex.go - - -4 + + +4 - + internal/codeshot/sources.go->internal/codeshot/cli.go - - -1 + + +1 - + internal/codeshot/sources.go->internal/codegraph/codegraph.go - - -1 + + +1 - + internal/codeshot/sources.go->internal/codegraph/index.go - - -1 + + +1 - + internal/codeshot/sources.go->internal/codeshot/arch.go - - -10 + + +10 - + internal/codeshot/sources.go->internal/codeshot/graph.go - - -2 + + +2 - + internal/codeshot/sources.go->internal/codeshot/source_scip.go - - -3 + + +3 - + internal/codeshot/sources.go->internal/codeshot/source_snapshot.go - - -4 + + +4 - + internal/codeshot/sources.go->internal/codeshot/warnings.go - - -3 + + +3 - + internal/codeshot/sources.go->internal/codeshot/diff.go - - -1 + + +1 - + internal/codeshot/sources.go->internal/scipindex/scipindex.go - - -1 + + +1 - + internal/codeshot/sources.go->internal/snapshot/snapshot.go - - -1 + + +1 - + internal/codeshot/source_snapshot.go->internal/codegraph/index.go - - -1 + + +1 - + internal/codeshot/source_snapshot.go->internal/codeshot/arch.go - - -3 + + +3 - + internal/codeshot/source_snapshot.go->internal/codeshot/graph.go - - -2 + + +2 - + internal/codeshot/source_snapshot.go->internal/snapshot/snapshot.go - - -8 + + +8 - + internal/codeshot/sources_test.go->internal/codegraph/codegraph.go - - -1 + + +1 - + internal/codeshot/sources_test.go->internal/codeshot/arch.go - - -14 + + +14 - + internal/codeshot/sources_test.go->internal/codeshot/dot.go - - -6 + + +6 - + internal/codeshot/sources_test.go->internal/codeshot/graph.go - - -8 + + +8 - + internal/codeshot/sources_test.go->internal/codeshot/sources.go - - -11 + + +11 - + internal/codeshot/sources_test.go->internal/codeshot/warnings.go - - -2 + + +2 internal/codeshot/helpers_test.go - -internal/codeshot/helpers_test.go + +internal/codeshot/helpers_test.go - + internal/codeshot/sources_test.go->internal/codeshot/helpers_test.go - - -22 + + +22 internal/codeshot/source_snapshot_test.go - -internal/codeshot/source_snapshot_test.go + +internal/codeshot/source_snapshot_test.go - + internal/codeshot/sources_test.go->internal/codeshot/source_snapshot_test.go - - -4 + + +4 - + internal/codeshot/sarif.go->internal/codegraph/index.go - - -16 + + +16 - + internal/codeshot/sarif.go->internal/codeshot/arch.go - - -5 + + +5 - + internal/codeshot/sarif.go->internal/codeshot/sources.go - - -1 + + +1 - + internal/codeshot/sarif.go->internal/codeshot/warnings.go - - -2 + + +2 - + internal/codeshot/sarif.go->internal/scipindex/scipindex.go - - -1 + + +1 internal/codeshot/sarif_test.go - -internal/codeshot/sarif_test.go + +internal/codeshot/sarif_test.go - + internal/codeshot/sarif.go->internal/codeshot/sarif_test.go - - -2 + + +2 - + internal/codeshot/warnings.go->internal/codegraph/codegraph.go - - -3 + + +3 - + internal/codeshot/warnings.go->internal/codeshot/arch.go - - -8 + + +8 - + internal/codeshot/warnings.go->internal/codeshot/dot.go - - -3 + + +3 - + internal/codeshot/warnings.go->internal/codeshot/graph.go - - -5 + + +5 internal/codeshot/wording.go - -internal/codeshot/wording.go + +internal/codeshot/wording.go - + internal/codeshot/warnings.go->internal/codeshot/wording.go - - -7 + + +7 internal/codeshot/mermaid.go->internal/codeshot/arch.go - - -1 + + +1 internal/codeshot/mermaid.go->internal/codeshot/dot.go - - -3 + + +3 internal/codeshot/mermaid.go->internal/codeshot/graph.go - - -1 + + +1 internal/codeshot/mermaid.go->internal/codeshot/warnings.go - - -1 + + +1 internal/codeshot/diff.go->internal/codegraph/codegraph.go - - -4 + + +4 internal/codeshot/diff.go->internal/codeshot/arch.go - - -3 + + +3 internal/codeshot/diff.go->internal/codeshot/dot.go - - -1 + + +1 internal/codeshot/diff.go->internal/codeshot/graph.go - - -7 + + +7 internal/codeshot/diff.go->internal/codeshot/warnings.go - - -12 + + +12 internal/codeshot/diff.go->internal/codeshot/callsource.go - - -4 + + +4 internal/codeshot/arch_test.go - -internal/codeshot/arch_test.go + +internal/codeshot/arch_test.go internal/codeshot/arch_test.go->internal/codegraph/index.go - - -1 + + +1 internal/codeshot/arch_test.go->internal/codeshot/arch.go - - -26 + + +26 internal/codeshot/arch_test.go->internal/codeshot/graph.go - - -1 + + +1 internal/codeshot/arch_test.go->internal/codeshot/diff.go - - -2 + + +2 internal/codeshot/arch_test.go->internal/codeshot/helpers_test.go - - -9 + + +9 internal/codeshot/helpers_test.go->internal/codeshot/cli.go - - -1 + + +1 internal/codeshot/helpers_test.go->internal/codeshot/dot.go - - -1 + + +1 internal/codeshot/helpers_test.go->internal/codeshot/graph.go - - -1 + + +1 internal/codeshot/callsource.go->internal/codegraph/codegraph.go - - -5 + + +5 internal/codeshot/callsource.go->internal/codeshot/arch.go - - -1 + + +1 internal/codeshot/callsource.go->internal/codeshot/graph.go - - -2 + + +2 internal/codeshot/callsource.go->internal/codeshot/diff.go - - -1 + + +1 internal/codeshot/callsource.go->internal/codeshot/source_snapshot_calls.go - - -4 + + +4 internal/codeshot/callsource.go->internal/codeshot/wording.go - - -2 + + +2 - + internal/codeshot/source_snapshot_calls.go->internal/codegraph/codegraph.go - - -3 + + +3 - + internal/codeshot/source_snapshot_calls.go->internal/codeshot/arch.go - - -2 + + +2 - + internal/codeshot/source_snapshot_calls.go->internal/codeshot/graph.go - - -3 + + +3 - + internal/codeshot/source_snapshot_calls.go->internal/codeshot/source_snapshot.go - - -2 + + +2 - + internal/codeshot/source_snapshot_calls.go->internal/codeshot/diff.go - - -2 + + +2 - + internal/codeshot/source_snapshot_calls.go->internal/codeshot/wording.go - - -4 + + +4 - + internal/codeshot/source_snapshot_calls.go->internal/snapshot/snapshot.go - - -9 + + +9 + + + +internal/codeshot/output.go->internal/codeshot/arch.go + + +1 - + internal/codeshot/output.go->internal/codeshot/warnings.go - - -2 + + +2 - + internal/codeshot/output.go->internal/codeshot/mermaid.go - - -1 + + +2 - + internal/codeshot/output.go->internal/codeshot/diff.go - - -3 + + +3 - + internal/codeshot/source_scip_calls.go->internal/codeshot/source_scip.go - - -2 + + +2 - + internal/codeshot/source_scip_calls.go->internal/codeshot/source_snapshot_calls.go - - -2 + + +2 - + internal/codeshot/source_scip_calls.go->internal/codeshot/wording.go - - -1 + + +1 - + internal/codeshot/source_scip_calls.go->internal/scipindex/scipindex.go - - -3 + + +3 - + internal/codeshot/source_scip_calls.go->internal/snapshot/snapshot.go - - -3 + + +3 internal/scipindex/calls.go - -internal/scipindex/calls.go + +internal/scipindex/calls.go - + internal/codeshot/source_scip_calls.go->internal/scipindex/calls.go - - -2 + + +2 - + internal/codeshot/symbol.go->internal/codegraph/codegraph.go - - -3 + + +3 - + internal/codeshot/symbol.go->internal/codeshot/arch.go - - -3 + + +3 - + internal/codeshot/symbol.go->internal/codeshot/dot.go - - -2 + + +2 - + internal/codeshot/symbol.go->internal/codeshot/graph.go - - -8 + + +8 - + internal/codeshot/symbol.go->internal/codeshot/warnings.go - - -6 + + +6 - + internal/codeshot/symbol.go->internal/codeshot/callsource.go - - -6 + + +6 internal/codeshot/cli_test.go - -internal/codeshot/cli_test.go + +internal/codeshot/cli_test.go internal/codeshot/cli_test.go->internal/codeshot/cli.go - - -1 + + +1 internal/codeshot/cli_test.go->internal/codeshot/arch.go - - -1 + + +1 internal/codeshot/cli_test.go->internal/codeshot/graph.go - - -1 + + +1 internal/codeshot/cli_test.go->internal/codeshot/helpers_test.go - - -82 + + +82 internal/codeshot/diff_test.go - -internal/codeshot/diff_test.go + +internal/codeshot/diff_test.go internal/codeshot/diff_test.go->internal/codegraph/codegraph.go - - -15 + + +15 internal/codeshot/diff_test.go->internal/codeshot/graph.go - - -1 + + +1 internal/codeshot/diff_test.go->internal/codeshot/warnings.go - - -6 + + +6 internal/codeshot/diff_test.go->internal/codeshot/diff.go - - -16 + + +16 internal/codeshot/diff_test.go->internal/codeshot/helpers_test.go - - -14 + + +14 internal/codeshot/dot_test.go - -internal/codeshot/dot_test.go + +internal/codeshot/dot_test.go internal/codeshot/dot_test.go->internal/codeshot/arch.go - - -2 + + +2 internal/codeshot/dot_test.go->internal/codeshot/dot.go - - -51 + + +51 internal/codeshot/dot_test.go->internal/codeshot/graph.go - - -3 + + +3 internal/codeshot/dot_test.go->internal/codeshot/helpers_test.go - - -62 + + +62 internal/codeshot/graph_test.go - -internal/codeshot/graph_test.go + +internal/codeshot/graph_test.go internal/codeshot/graph_test.go->internal/codeshot/graph.go - - -11 + + +11 internal/codeshot/graph_test.go->internal/codeshot/helpers_test.go - - -5 + + +5 internal/codeshot/mermaid_test.go - -internal/codeshot/mermaid_test.go + +internal/codeshot/mermaid_test.go internal/codeshot/mermaid_test.go->internal/codeshot/arch.go - - -1 + + +1 internal/codeshot/mermaid_test.go->internal/codeshot/dot.go - - -5 + + +5 + + + +internal/codeshot/mermaid_test.go->internal/codeshot/warnings.go + + +1 internal/codeshot/mermaid_test.go->internal/codeshot/mermaid.go - - -5 + + +6 internal/codeshot/mermaid_test.go->internal/codeshot/helpers_test.go - - -5 + + +11 + + + +internal/codeshot/mermaid_test.go->internal/codeshot/output.go + + +2 internal/codeshot/mermaid_test.go->internal/codeshot/source_snapshot_test.go - - -1 + + +2 - + internal/codeshot/source_snapshot_test.go->internal/codeshot/arch.go - - -3 + + +3 - + internal/codeshot/source_snapshot_test.go->internal/codeshot/graph.go - - -1 + + +1 - + internal/codeshot/source_snapshot_test.go->internal/codeshot/source_snapshot.go - - -9 + + +9 - + internal/codeshot/source_snapshot_test.go->internal/codeshot/helpers_test.go - - -15 + + +15 - + internal/codeshot/source_snapshot_test.go->internal/snapshot/snapshot.go - - -8 + + +8 internal/codeshot/output_test.go - -internal/codeshot/output_test.go + +internal/codeshot/output_test.go - + internal/codeshot/output_test.go->internal/codeshot/dot.go - - -1 + + +1 - + internal/codeshot/output_test.go->internal/codeshot/helpers_test.go - - -7 + + +7 - + internal/codeshot/output_test.go->internal/codeshot/output.go - - -10 + + +10 - + internal/codeshot/output_test.go->internal/codeshot/dot_test.go - - -1 + + +1 internal/codeshot/rules_test.go - -internal/codeshot/rules_test.go + +internal/codeshot/rules_test.go - + internal/codeshot/rules_test.go->internal/codeshot/arch.go - - -4 + + +4 - + internal/codeshot/rules_test.go->internal/codeshot/dot.go - - -1 + + +1 - + internal/codeshot/rules_test.go->internal/codeshot/rules.go - - -21 + + +21 - + internal/codeshot/rules_test.go->internal/codeshot/warnings.go - - -4 + + +4 - + internal/codeshot/rules_test.go->internal/codeshot/helpers_test.go - - -20 + + +20 - + internal/codeshot/rules_test.go->internal/codeshot/source_snapshot_test.go - - -2 + + +2 - + internal/codeshot/sarif_test.go->internal/codegraph/index.go - - -9 + + +9 - + internal/codeshot/sarif_test.go->internal/codeshot/arch.go - - -1 + + +1 - + internal/codeshot/sarif_test.go->internal/codeshot/sources.go - - -1 + + +1 - + internal/codeshot/sarif_test.go->internal/codeshot/source_snapshot.go - - -2 + + +2 - + internal/codeshot/sarif_test.go->internal/codeshot/sarif.go - - -12 + + +12 - + internal/codeshot/sarif_test.go->internal/codeshot/helpers_test.go - - -15 + + +15 - + internal/codeshot/sarif_test.go->internal/snapshot/snapshot.go - - -2 + + +2 - + internal/codeshot/sarif_test.go->internal/codeshot/source_snapshot_test.go - - -3 + + +3 - + internal/codeshot/sarif_test.go->internal/codeshot/rules_test.go - - -1 + + +1 internal/codeshot/source_scip_calls_test.go - -internal/codeshot/source_scip_calls_test.go + +internal/codeshot/source_scip_calls_test.go - + internal/codeshot/source_scip_calls_test.go->internal/codeshot/helpers_test.go - - -15 + + +15 - + internal/codeshot/source_scip_calls_test.go->internal/codeshot/source_scip_calls.go - - -1 + + +1 - + internal/codeshot/source_scip_calls_test.go->internal/scipindex/scipindex.go - - -1 + + +1 internal/codeshot/source_scip_test.go - -internal/codeshot/source_scip_test.go + +internal/codeshot/source_scip_test.go - + internal/codeshot/source_scip_test.go->internal/codeshot/arch.go - - -1 + + +1 - + internal/codeshot/source_scip_test.go->internal/codeshot/source_scip.go - - -8 + + +8 - + internal/codeshot/source_scip_test.go->internal/codeshot/helpers_test.go - - -14 + + +14 - + internal/codeshot/source_scip_test.go->internal/scipindex/scipindex.go - - -4 + + +4 internal/codeshot/source_snapshot_calls_test.go - -internal/codeshot/source_snapshot_calls_test.go + +internal/codeshot/source_snapshot_calls_test.go - + internal/codeshot/source_snapshot_calls_test.go->internal/codegraph/codegraph.go - - -1 + + +1 - + internal/codeshot/source_snapshot_calls_test.go->internal/codeshot/diff.go - - -1 + + +1 - + internal/codeshot/source_snapshot_calls_test.go->internal/codeshot/helpers_test.go - - -14 + + +14 - + internal/codeshot/source_snapshot_calls_test.go->internal/codeshot/source_snapshot_calls.go - - -13 + + +13 - + internal/codeshot/source_snapshot_calls_test.go->internal/codeshot/symbol.go - - -6 + + +6 - + internal/codeshot/source_snapshot_calls_test.go->internal/snapshot/snapshot.go - - -5 + + +5 - + internal/codeshot/source_snapshot_calls_test.go->internal/codeshot/diff_test.go - - -4 + + +4 - + internal/codeshot/source_snapshot_calls_test.go->internal/codeshot/source_snapshot_test.go - - -8 + + +8 internal/codeshot/warnings_test.go - -internal/codeshot/warnings_test.go + +internal/codeshot/warnings_test.go - + internal/codeshot/warnings_test.go->internal/codeshot/arch.go - - -1 + + +1 - + internal/codeshot/warnings_test.go->internal/codeshot/dot.go - - -2 + + +2 - + internal/codeshot/warnings_test.go->internal/codeshot/graph.go - - -1 + + +1 - + internal/codeshot/warnings_test.go->internal/codeshot/warnings.go - - -29 + + +29 - + internal/codeshot/warnings_test.go->internal/codeshot/helpers_test.go - - -29 + + +29 internal/scipindex/calls_test.go - -internal/scipindex/calls_test.go + +internal/scipindex/calls_test.go - + internal/scipindex/calls_test.go->internal/scipindex/scipindex.go - - -2 + + +2 - + internal/scipindex/calls_test.go->internal/scipindex/calls.go - - -4 + + +4 internal/scipindex/scipindex_test.go - -internal/scipindex/scipindex_test.go + +internal/scipindex/scipindex_test.go - + internal/scipindex/calls_test.go->internal/scipindex/scipindex_test.go - - -2 + + +2 - + internal/scipindex/scipindex_test.go->internal/scipindex/scipindex.go - - -15 + + +15 internal/snapshot/snapshot_test.go - -internal/snapshot/snapshot_test.go + +internal/snapshot/snapshot_test.go - + internal/snapshot/snapshot_test.go->internal/snapshot/snapshot.go - - -4 + + +4 diff --git a/internal/codeshot/arch.go b/internal/codeshot/arch.go index b6a7d20..a6dc612 100644 --- a/internal/codeshot/arch.go +++ b/internal/codeshot/arch.go @@ -669,9 +669,7 @@ func finishArchitecture(rawFileEdges []FileEdge, p ArchParams, sources []string, warn(stderr, HiddenRuleViolationNote(fileEdges, violating, p.MaxRender, what)) opt := ArchOptions{MaxRender: p.MaxRender, Violating: violating, Sources: sources, Tooltips: p.Tooltips} if p.Mermaid { - text := BuildArchitectureMermaid(fileEdges, opt) - warn(stderr, MermaidLimitWarning(text)) - return text, violations, nil + return BuildArchitectureMermaid(fileEdges, opt), violations, nil } return BuildArchitectureDot(fileEdges, opt), violations, nil } diff --git a/internal/codeshot/cli.go b/internal/codeshot/cli.go index a91fcd7..45820a2 100644 --- a/internal/codeshot/cli.go +++ b/internal/codeshot/cli.go @@ -497,6 +497,11 @@ func run(args []string, stdout, stderr io.Writer) (int, error) { for _, m := range multi { archMarkerID += "-" + m.label } + // F5: a Mermaid block has its own marker, so it can sit beside the + // graphviz image of the same graph instead of overwriting it. + if mermaid { + archMarkerID += "-mermaid" + } ext := format if mermaid { ext = "mmd" diff --git a/internal/codeshot/mermaid.go b/internal/codeshot/mermaid.go index 93f3236..1288b3b 100644 --- a/internal/codeshot/mermaid.go +++ b/internal/codeshot/mermaid.go @@ -2,6 +2,7 @@ package codeshot import ( "fmt" + "strconv" "strings" ) @@ -11,10 +12,15 @@ const ( mermaidMaxText = 50000 ) -// mermaidLabel escapes text for a quoted Mermaid label: '#' first, since the -// others become "#N;" entities. +// mermaidLabel escapes text for a quoted Mermaid label as "#N;" entities +// (one pass, so the '#' they start with is never re-escaped): the quote and +// HTML characters, and what Mermaid interprets inside a label (F1): '\' ("\n" +// is a line break), a backtick (a leading one opens a markdown string), '%' +// (%%{...}%% directives), '$' ($$ math), ':' (fa: icons). A line break is a +// space. func mermaidLabel(s string) string { - return strings.NewReplacer("#", "#35;", `"`, "#34;", "<", "#60;", ">", "#62;", "&", "#38;", "\n", " ").Replace(s) + return strings.NewReplacer("#", "#35;", `"`, "#34;", "<", "#60;", ">", "#62;", "&", "#38;", + `\`, "#92;", "`", "#96;", "%", "#37;", "$", "#36;", ":", "#58;", "\n", " ", "\r", " ").Replace(s) } // BuildArchitectureMermaid draws the same graph as BuildArchitectureDot as a @@ -27,7 +33,7 @@ func BuildArchitectureMermaid(fileEdges []FileEdge, opt ArchOptions) string { multi := len(opt.Sources) > 1 if multi { title := fmt.Sprintf("Sources: %s. Dashed: not every source saw all of the edge; its label gives each source's own weight.", strings.Join(opt.Sources, ", ")) - lines = append(lines, "---", "title: "+strings.ReplaceAll(fmt.Sprintf("%q", title), `\'`, "'"), "---") + lines = append(lines, "---", "title: "+strconv.Quote(title), "---") } lines = append(lines, "flowchart LR", " classDef default fill:#f8fafc,stroke:#cbd5e1,color:#334155", diff --git a/internal/codeshot/mermaid_test.go b/internal/codeshot/mermaid_test.go index 077aa50..69e030c 100644 --- a/internal/codeshot/mermaid_test.go +++ b/internal/codeshot/mermaid_test.go @@ -102,14 +102,14 @@ func TestCLIMermaidNeedsNoGraphvizAndEmbedsABlock(t *testing.T) { t.Fatalf("--embed: exit %d; stderr: %s", code, stderr) } md, _ := os.ReadFile(doc) - wantMatch(t, "(?s)\n```mermaid\nflowchart LR\n.*\n```\n", string(md)) + wantMatch(t, "(?s)\n```mermaid\nflowchart LR\n.*\n```\n", string(md)) if matches, _ := filepath.Glob(filepath.Join(dir, "codeshot-*")); len(matches) != 0 { t.Errorf("--embed wrote an image file: %v", matches) } if code, stdout, stderr := runCLI("--architecture", "--source", snap, "--format", "mermaid", "--embed", doc, "--check"); code != 0 { t.Fatalf("--check current: exit %d; stderr: %s", code, stderr) } else { - wantMatch(t, `up to date — the codeshot:arch-snapshot-t block`, stdout) + wantMatch(t, `up to date — the codeshot:arch-snapshot-t-mermaid block`, stdout) } if err := os.WriteFile(doc, []byte(strings.Replace(string(md), `-->|"1"|`, `-->|"2"|`, 1)), 0o644); err != nil { t.Fatal(err) @@ -117,8 +117,101 @@ func TestCLIMermaidNeedsNoGraphvizAndEmbedsABlock(t *testing.T) { if code, _, stderr := runCLI("--architecture", "--source", snap, "--format", "mermaid", "--embed", doc, "--check"); code != 1 { t.Errorf("--check stale: exit %d, want 1", code) } else { - wantMatch(t, `the codeshot:arch-snapshot-t block in .* is out of date`, stderr) + wantMatch(t, `the codeshot:arch-snapshot-t-mermaid block in .* is out of date`, stderr) } wantRejected(t, `--format mermaid only applies with --architecture`, "Foo", "--format", "mermaid") wantRejected(t, `--format mermaid only applies with --architecture`, "--diff", "--format", "mermaid") } + +// F1: characters Mermaid interprets inside a quoted label are entities too: +// '\' ("\n" is a line break), a backtick (a leading one opens a markdown +// string and the diagram fails to parse), '%' (%%{...}%% directives), '$' +// ($$ math), ':' (fa: icons); a CR is a space like LF. +func TestMermaidLabelEscapesWhatMermaidWouldInterpret(t *testing.T) { + for in, want := range map[string]string{ + `src\new\node.go`: "src#92;new#92;node.go", + "`tick`.go": "#96;tick#96;.go", + "a%%{init}%%b.go": "a#37;#37;{init}#37;#37;b.go", + "fa:fa-car/x.go": "fa#58;fa-car/x.go", + "$$x$$.go": "#36;#36;x#36;#36;.go", + "a\rb\nc.go": "a b c.go", + `a "q" #1 &`: "a #34;q#34; #35;1 #60;x#62; #38;", + } { + if got := mermaidLabel(in); got != want { + t.Errorf("mermaidLabel(%q) = %q, want %q", in, got, want) + } + } +} + +// F2: the limit is checked on what is written, title and newline included. +func TestMermaidLimitIsCheckedOnTheWrittenText(t *testing.T) { + text := "flowchart LR\n" + strings.Repeat("x", mermaidMaxText-20) + var stderr strings.Builder + out := filepath.Join(t.TempDir(), "a.mmd") + if err := FinishOutput(text, OutputParams{Mermaid: true, OutFile: out, Alt: strings.Repeat("A", 40)}, &strings.Builder{}, &stderr); err != nil { + t.Fatal(err) + } + wantMatch(t, `GitHub renders at most 500 edges and 50000 characters`, stderr.String()) +} + +// F4: an .mmd --out with another --format, and a graphviz extension with +// --format mermaid, are both called out. +func TestFormatMismatchKnowsMermaid(t *testing.T) { + wantMatch(t, `--out ends in '\.mmd' but --format is 'png'`, FormatMismatchWarning("arch.mmd", "png")) + wantMatch(t, `--format is 'mermaid'.*rename --out to end in '\.mmd'`, FormatMismatchWarning("arch.svg", "mermaid")) + if w := FormatMismatchWarning("arch.mmd", "mermaid"); w != "" { + t.Errorf("matching .mmd warned: %s", w) + } +} + +// F5 + T: a Mermaid embed has its own marker (beside a graphviz one in the +// same doc), --embed with --out writes both, --check fails on a missing +// --out file, a blank graph is refused, and two sources draw dashed edges. +func TestCLIMermaidMarkerOutFileBlankAndMultiSource(t *testing.T) { + requireBins(t, "dot") + dir := t.TempDir() + snap := "snapshot:" + writeSnapshotFile(t, cliSnapshot) + doc := filepath.Join(dir, "doc.md") + if err := os.WriteFile(doc, []byte("# Doc\n"), 0o644); err != nil { + t.Fatal(err) + } + if code, _, stderr := runCLI("--architecture", "--source", snap, "--format", "svg", "--embed", doc); code != 0 { + t.Fatalf("svg embed: exit %d; stderr: %s", code, stderr) + } + out := filepath.Join(dir, "arch.mmd") + if code, _, stderr := runCLI("--architecture", "--source", snap, "--format", "mermaid", "--embed", doc, "--out", out); code != 0 { + t.Fatalf("mermaid embed: exit %d; stderr: %s", code, stderr) + } + md, _ := os.ReadFile(doc) + wantMatch(t, `\n!\[`, string(md)) + wantMatch(t, "\n```mermaid\n", string(md)) + if _, err := os.Stat(out); err != nil { + t.Errorf("--out not written with --embed: %v", err) + } + // Both blocks stay current side by side. + for _, f := range []string{"svg", "mermaid"} { + args := []string{"--architecture", "--source", snap, "--format", f, "--embed", doc, "--check"} + if f == "mermaid" { + args = append(args, "--out", out) + } + if code, _, stderr := runCLI(args...); code != 0 { + t.Errorf("%s --check: exit %d; stderr: %s", f, code, stderr) + } + } + if code, _, stderr := runCLI("--architecture", "--source", snap, "--format", "mermaid", "--embed", doc, "--check", "--out", filepath.Join(dir, "gone.mmd")); code != 1 { + t.Errorf("--check with a missing --out: exit %d, want 1", code) + } else { + wantMatch(t, `gone\.mmd' is out of date \(missing\)`, stderr) + } + empty := strings.Replace(cliSnapshot, `"edges":[{"kind":"calls","src":"1","dst":"2"}]`, `"edges":[]`, 1) + wantRejected(t, `the graph is blank`, "--architecture", "--source", "snapshot:"+writeSnapshotFile(t, empty), "--format", "mermaid", "--embed", doc) + + two := "snapshot:" + writeSnapshotFile(t, cliSnapshot) + ",snapshot:" + writeSnapshotFile(t, cliSnapshotU) + mmd := filepath.Join(dir, "two.mmd") + if code, _, stderr := runCLI("--architecture", "--source", two, "--format", "mermaid", "--out", mmd); code != 0 { + t.Fatalf("two sources: exit %d; stderr: %s", code, stderr) + } + data, _ := os.ReadFile(mmd) + wantMatch(t, `(?s)^---\ntitle: "Sources: snapshot-t, snapshot-u\.`, string(data)) + wantMatch(t, `-\.->\|"snapshot-u 1"\|`, string(data)) +} diff --git a/internal/codeshot/output.go b/internal/codeshot/output.go index 9ea1ccd..b4d6cd9 100644 --- a/internal/codeshot/output.go +++ b/internal/codeshot/output.go @@ -219,6 +219,8 @@ func FinishOutput(dot string, p OutputParams, stdout, stderr io.Writer) error { // in the --embed doc. --check compares both byte for byte (Mermaid text is // deterministic, so no structural comparison is needed) and writes nothing. func finishMermaid(text string, p OutputParams, stdout, stderr io.Writer) error { + // F2: measured on what is written, title and newline included. + warn(stderr, MermaidLimitWarning(text)) writeOut := p.WriteOut || p.EmbedFile == "" if p.EmbedFile == "" { if err := os.WriteFile(p.OutFile, []byte(text), 0o644); err != nil { diff --git a/internal/codeshot/warnings.go b/internal/codeshot/warnings.go index 931e636..aaa840b 100644 --- a/internal/codeshot/warnings.go +++ b/internal/codeshot/warnings.go @@ -73,6 +73,17 @@ func FormatMismatchWarning(outFile, format string) string { } parts := strings.Split(outFile, ".") ext := strings.ToLower(parts[len(parts)-1]) + // F4: .mmd is Mermaid's extension, and Mermaid isn't a graphviz format. + if mermaid := strings.EqualFold(format, "mermaid"); mermaid || ext == "mmd" { + switch { + case mermaid && ext == "mmd", !mermaid && !strings.Contains(outFile, "."): + return "" + case mermaid: + return fmt.Sprintf("codeshot: --out ends in '.%s' but --format is 'mermaid' — the file will contain Mermaid text despite its name; rename --out to end in '.mmd'.", ext) + default: + return fmt.Sprintf("codeshot: --out ends in '.mmd' but --format is '%s' — the file will contain %s data despite its name; pass --format mermaid to match, or rename --out.", format, format) + } + } if !knownDotFormats[ext] || ext == strings.ToLower(format) { return "" } From 30045e53219822995ce08ceac85cb6126066492b Mon Sep 17 00:00:00 2001 From: Eric Minish Date: Wed, 18 Nov 2026 22:40:21 -0500 Subject: [PATCH 3/3] fix: Mermaid review round 2 (format warning, CI gating, limits) - 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. --- .github/workflows/ci.yml | 8 +++-- docs/architecture.svg | 8 ++--- internal/codeshot/cli.go | 8 ++--- internal/codeshot/mermaid.go | 26 +++++++++++---- internal/codeshot/mermaid_test.go | 53 +++++++++++++++++++++++++++++++ internal/codeshot/output.go | 13 ++++++-- internal/codeshot/warnings.go | 7 +++- 7 files changed, 101 insertions(+), 22 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c67bd87..e8a98df 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -130,18 +130,20 @@ jobs: # Blocking gate: fail the PR if a committed diagram no longer matches # what the current code produces, or the code breaks .codeshot.yaml. # One step per diagram, so a PR that stales several learns of all of - # them in one run. + # them in one run. The later ones run after an earlier check failed, + # but not after a setup step did (the first check is then skipped). - name: Check docs/architecture.svg is current + id: arch_svg run: | codeshot --architecture --path . --max-symbols 5000 --rules .codeshot.yaml --format svg \ --out docs/architecture.svg --embed TECHNICAL.md --check - name: Check docs/BuildDot-callgraph.svg is current - if: ${{ !cancelled() }} + if: ${{ !cancelled() && steps.arch_svg.conclusion != 'skipped' }} run: | codeshot BuildDot --path . --format svg \ --out docs/BuildDot-callgraph.svg --embed TECHNICAL.md --check - name: Check README's Mermaid diagram is current - if: ${{ !cancelled() }} + if: ${{ !cancelled() && steps.arch_svg.conclusion != 'skipped' }} run: | codeshot --architecture --path . --max-symbols 5000 --group-depth 2 --rules .codeshot.yaml \ --format mermaid --embed README.md --check diff --git a/docs/architecture.svg b/docs/architecture.svg index 8f08320..1eb4162 100644 --- a/docs/architecture.svg +++ b/docs/architecture.svg @@ -1231,21 +1231,21 @@ internal/codeshot/mermaid_test.go->internal/codeshot/warnings.go -1 +2 internal/codeshot/mermaid_test.go->internal/codeshot/mermaid.go -6 +8 internal/codeshot/mermaid_test.go->internal/codeshot/helpers_test.go -11 +16 @@ -1259,7 +1259,7 @@ internal/codeshot/mermaid_test.go->internal/codeshot/source_snapshot_test.go -2 +3 diff --git a/internal/codeshot/cli.go b/internal/codeshot/cli.go index 45820a2..692766d 100644 --- a/internal/codeshot/cli.go +++ b/internal/codeshot/cli.go @@ -497,13 +497,11 @@ func run(args []string, stdout, stderr io.Writer) (int, error) { for _, m := range multi { archMarkerID += "-" + m.label } - // F5: a Mermaid block has its own marker, so it can sit beside the - // graphviz image of the same graph instead of overwriting it. - if mermaid { - archMarkerID += "-mermaid" - } ext := format if mermaid { + // F5: a Mermaid block has its own marker, so it can sit beside the + // graphviz image of the same graph instead of overwriting it. + archMarkerID += "-mermaid" ext = "mmd" } if !hasOut { diff --git a/internal/codeshot/mermaid.go b/internal/codeshot/mermaid.go index 1288b3b..90e672c 100644 --- a/internal/codeshot/mermaid.go +++ b/internal/codeshot/mermaid.go @@ -4,6 +4,7 @@ import ( "fmt" "strconv" "strings" + "unicode/utf16" ) // GitHub renders Mermaid with its defaults, which refuse larger diagrams. @@ -18,10 +19,11 @@ const ( // is a line break), a backtick (a leading one opens a markdown string), '%' // (%%{...}%% directives), '$' ($$ math), ':' (fa: icons). A line break is a // space. -func mermaidLabel(s string) string { - return strings.NewReplacer("#", "#35;", `"`, "#34;", "<", "#60;", ">", "#62;", "&", "#38;", - `\`, "#92;", "`", "#96;", "%", "#37;", "$", "#36;", ":", "#58;", "\n", " ", "\r", " ").Replace(s) -} +func mermaidLabel(s string) string { return mermaidEscape.Replace(s) } + +// mermaidEscape is mermaidLabel's fixed mapping, built once (V10). +var mermaidEscape = strings.NewReplacer("#", "#35;", `"`, "#34;", "<", "#60;", ">", "#62;", "&", "#38;", + `\`, "#92;", "`", "#96;", "%", "#37;", "$", "#36;", ":", "#58;", "\n", " ", "\r", " ") // BuildArchitectureMermaid draws the same graph as BuildArchitectureDot as a // Mermaid flowchart: the same files and edges (archDrawn), test files dashed, @@ -70,14 +72,24 @@ func mermaidWithTitle(text, title string) string { if title == "" { return text } - return strings.Replace(text, "flowchart LR\n", "flowchart LR\n accTitle: "+strings.ReplaceAll(title, "\n", " ")+"\n", 1) + title = strings.NewReplacer("\r", " ", "\n", " ").Replace(title) // V3 + return strings.Replace(text, "flowchart LR\n", "flowchart LR\n accTitle: "+title+"\n", 1) } // MermaidLimitWarning: GitHub won't render a Mermaid diagram past its limits. +// The size is counted as Mermaid counts it (V6): UTF-16 units, after the +// frontmatter is stripped. func MermaidLimitWarning(text string) string { edges := strings.Count(text, "-->|") + strings.Count(text, "-.->|") - if edges <= mermaidMaxEdges && len(text) <= mermaidMaxText { + body := text + if strings.HasPrefix(body, "---\n") { + if i := strings.Index(body[4:], "\n---\n"); i >= 0 { + body = body[4+i+5:] + } + } + size := len(utf16.Encode([]rune(body))) + if edges <= mermaidMaxEdges && size <= mermaidMaxText { return "" } - return fmt.Sprintf("codeshot: the Mermaid diagram has %d edges and %d characters; GitHub renders at most %d edges and %d characters, so it will show an error there. Narrow it with --max-render or --group-depth.", edges, len(text), mermaidMaxEdges, mermaidMaxText) + return fmt.Sprintf("codeshot: the Mermaid diagram has %d edges and %d characters; GitHub renders at most %d edges and %d characters, so it will show an error there. Narrow it with --max-render or --group-depth.", edges, size, mermaidMaxEdges, mermaidMaxText) } diff --git a/internal/codeshot/mermaid_test.go b/internal/codeshot/mermaid_test.go index 69e030c..0cda2b2 100644 --- a/internal/codeshot/mermaid_test.go +++ b/internal/codeshot/mermaid_test.go @@ -215,3 +215,56 @@ func TestCLIMermaidMarkerOutFileBlankAndMultiSource(t *testing.T) { wantMatch(t, `(?s)^---\ntitle: "Sources: snapshot-t, snapshot-u\.`, string(data)) wantMatch(t, `-\.->\|"snapshot-u 1"\|`, string(data)) } + +// V1: only a real extension (a dot in the file's own name) is compared, and +// a text name (.md, .txt) is a fine home for Mermaid text. +func TestFormatMismatchMermaidIgnoresNonExtensions(t *testing.T) { + for _, out := range []string{"arch", "out.d/arch", "/tmp/a.b/x", "./mmd", "arch.", "a.md", "a.txt", "a.mmd"} { + if w := FormatMismatchWarning(out, "mermaid"); w != "" { + t.Errorf("%q: %s", out, w) + } + } + wantMatch(t, `ends in '\.svg' but --format is 'mermaid'`, FormatMismatchWarning("a.svg", "mermaid")) +} + +// V3: a carriage return can't end the accTitle line early. +func TestMermaidTitleHasNoLineBreaks(t *testing.T) { + got := mermaidWithTitle("flowchart LR\n n0(\"a\")", "one\rtwo\nthree") + wantMatch(t, "accTitle: one two three\n", got) +} + +// V6: the limit counts characters as Mermaid does (UTF-16 units) and leaves +// out the frontmatter, which Mermaid strips first. +func TestMermaidLimitCountsCharactersWithoutFrontmatter(t *testing.T) { + front := "---\ntitle: \"" + strings.Repeat("t", 200) + "\"\n---\n" + if w := MermaidLimitWarning(front + "flowchart LR\n" + strings.Repeat("x", mermaidMaxText-20)); w != "" { + t.Errorf("frontmatter counted: %s", w) + } + if w := MermaidLimitWarning("flowchart LR\n" + strings.Repeat("日", 30000)); w != "" { + t.Errorf("bytes counted, not characters: %s", w) + } + wantMatch(t, `50001 characters`, MermaidLimitWarning(strings.Repeat("x", 50001))) +} + +// V5: with --embed and --out, stdout names the .mmd file, and --check says +// it compared it too. +func TestCLIMermaidEmbedWithOutNamesTheFile(t *testing.T) { + dir := t.TempDir() + snap := "snapshot:" + writeSnapshotFile(t, cliSnapshot) + doc, out := filepath.Join(dir, "doc.md"), filepath.Join(dir, "arch.mmd") + if err := os.WriteFile(doc, []byte("# Doc\n"), 0o644); err != nil { + t.Fatal(err) + } + code, stdout, stderr := runCLI("--architecture", "--source", snap, "--format", "mermaid", "--embed", doc, "--out", out) + if code != 0 { + t.Fatalf("exit %d; stderr: %s", code, stderr) + } + if strings.TrimSpace(stdout) != out { + t.Errorf("stdout %q, want the --out file %q", stdout, out) + } + code, stdout, _ = runCLI("--architecture", "--source", snap, "--format", "mermaid", "--embed", doc, "--out", out, "--check") + if code != 0 { + t.Fatalf("--check: exit %d", code) + } + wantMatch(t, `up to date — '.*arch\.mmd' and the codeshot:arch-snapshot-t-mermaid block`, stdout) +} diff --git a/internal/codeshot/output.go b/internal/codeshot/output.go index b4d6cd9..80e000e 100644 --- a/internal/codeshot/output.go +++ b/internal/codeshot/output.go @@ -259,7 +259,11 @@ func finishMermaid(text string, p OutputParams, stdout, stderr io.Writer) error if len(msgs) > 0 { return &Exit{Code: 1, Stderr: strings.Join(msgs, "\n")} } - fmt.Fprintf(stdout, "codeshot: up to date — the codeshot:%s block in '%s' matches a fresh render.\n", p.MarkerID, p.EmbedFile) + if writeOut { + fmt.Fprintf(stdout, "codeshot: up to date — '%s' and the codeshot:%s block in '%s' match a fresh render.\n", p.OutFile, p.MarkerID, p.EmbedFile) + } else { + fmt.Fprintf(stdout, "codeshot: up to date — the codeshot:%s block in '%s' matches a fresh render.\n", p.MarkerID, p.EmbedFile) + } return nil } if writeOut { @@ -273,6 +277,11 @@ func finishMermaid(text string, p OutputParams, stdout, stderr io.Writer) error } fmt.Fprintf(stderr, "codeshot: updated the codeshot:%s block in %s\n", p.MarkerID, p.EmbedFile) } - fmt.Fprintln(stdout, p.EmbedFile) + // V5: the --out file when there is one, as the graphviz path prints. + if writeOut { + fmt.Fprintln(stdout, p.OutFile) + } else { + fmt.Fprintln(stdout, p.EmbedFile) + } return nil } diff --git a/internal/codeshot/warnings.go b/internal/codeshot/warnings.go index aaa840b..3850dbc 100644 --- a/internal/codeshot/warnings.go +++ b/internal/codeshot/warnings.go @@ -2,6 +2,7 @@ package codeshot import ( "fmt" + "path/filepath" "strings" "github.com/inth3shadows/codeshot/internal/codegraph" @@ -74,9 +75,13 @@ func FormatMismatchWarning(outFile, format string) string { parts := strings.Split(outFile, ".") ext := strings.ToLower(parts[len(parts)-1]) // F4: .mmd is Mermaid's extension, and Mermaid isn't a graphviz format. + // V1: only a dot in the file's own name makes an extension, and a text + // name (.md, .txt) is a fine home for Mermaid text. if mermaid := strings.EqualFold(format, "mermaid"); mermaid || ext == "mmd" { + base := filepath.Base(outFile) + hasExt := strings.Contains(strings.TrimPrefix(base, "."), ".") && !strings.HasSuffix(base, ".") switch { - case mermaid && ext == "mmd", !mermaid && !strings.Contains(outFile, "."): + case !hasExt, mermaid && (ext == "mmd" || ext == "md" || ext == "txt"): return "" case mermaid: return fmt.Sprintf("codeshot: --out ends in '.%s' but --format is 'mermaid' — the file will contain Mermaid text despite its name; rename --out to end in '.mmd'.", ext)