Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 14 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -127,11 +127,23 @@ 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. 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() && 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() && steps.arch_svg.conclusion != 'skipped' }}
run: |
codeshot --architecture --path . --max-symbols 5000 --group-depth 2 --rules .codeshot.yaml \
--format mermaid --embed README.md --check
33 changes: 32 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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):

<!-- codeshot:arch-d2-mermaid:start -->
```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
```
<!-- codeshot:arch-d2-mermaid:end -->

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 <n>` — roll files up into their first `n` directory segments
Expand Down Expand Up @@ -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 <file>` — 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
Expand Down
8 changes: 5 additions & 3 deletions TECHNICAL.md

Large diffs are not rendered by default.

27 changes: 27 additions & 0 deletions USAGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -328,6 +328,33 @@ 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 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`,
`--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
Expand Down
Loading
Loading