From edda666de3e239438cb09eb04805a8b9b91b7b54 Mon Sep 17 00:00:00 2001 From: Eric Minish Date: Wed, 18 Nov 2026 20:13:59 -0500 Subject: [PATCH 1/4] feat: --sarif writes architecture rule violations as SARIF 2.1.0 `codeshot --architecture ... --sarif codeshot.sarif` writes every --forbid and --rules violation as a SARIF result, for GitHub code scanning: the depending file at its first call-site line (from the codegraph index, a snapshot edge's line, or the SCIP index's first reference; line 1 when unknown), the depended-on file as a related location, and a fingerprint from the rule and the two files so an alert survives the line moving. Written on every run, with an empty results list when nothing breaks a rule, and with --check. Line numbers are looked up only for violations, so the diagram path is unchanged. P5a of the program. --- README.md | 5 + TECHNICAL.md | 2 + USAGE.md | 35 + docs/architecture.svg | 1637 ++++++++++++++------------ internal/codegraph/index.go | 59 + internal/codegraph/index_test.go | 35 + internal/codeshot/arch.go | 15 +- internal/codeshot/cli.go | 23 +- internal/codeshot/rules.go | 1 + internal/codeshot/sarif.go | 262 +++++ internal/codeshot/sarif_test.go | 214 ++++ internal/codeshot/warnings.go | 25 +- internal/scipindex/scipindex.go | 55 + internal/scipindex/scipindex_test.go | 55 + 14 files changed, 1653 insertions(+), 770 deletions(-) create mode 100644 internal/codeshot/sarif.go create mode 100644 internal/codeshot/sarif_test.go diff --git a/README.md b/README.md index 196ea3a..3fc7fb4 100644 --- a/README.md +++ b/README.md @@ -123,6 +123,11 @@ 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). +- `--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. Written on every run, also when + nothing breaks a rule. See + [USAGE.md](USAGE.md#code-scanning-alerts-with---sarif). - `--source snapshot:` — draw from a [graph-assay](https://github.com/inth3shadows/graph-assay) snapshot (`graph-assay/snapshot@1` JSON) instead of the codegraph index under `--path`. diff --git a/TECHNICAL.md b/TECHNICAL.md index fdbc9bf..8885f6e 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/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`), 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, and `partialFingerprints["codeshotEdge/v1"]` = the first 16 bytes of SHA-256 over rule id, rule, from and to, so an alert outlives its line moving. 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, `MIN(COALESCE(e.line, s.start_line))`, with the immutable retry), `SnapshotSource` takes the smallest optional edge `line`, `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. `fillSiteLines` takes the smallest line any source gives a pair; a source that fails to answer costs only its lines, with a warning. 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. - **`internal/codeshot/arch.go`** — multi-source: `RunMultiArchitectureMode` runs `sourceFileEdges` (enumerate, `--max-symbols` cut, `FileEdges`, `AggregateFileEdges`) per `LabeledSource`, then `UnionFileEdges` merges them (first-seen order in `--source` order; `Weight` = the highest per-source weight, never a sum, since codegraph counts calls and SCIP references; `FileEdge.Seen` = each source's own weight). `finishArchitecture` is the shared tail (`--forbid`, rollup, warnings, DOT) for one source and many. `FileEdge.Full` = the sources that saw all of the edge. `RollupFileEdges` sums `Seen` per source, sets a group edge's weight to the highest per-source sum, and intersects `Full` over the file edges inside it, so a group edge is solid only when every source saw every file edge inside it. `BuildArchitectureDot` with `ArchOptions.Sources` (two or more) dashes an edge whose `Full` is shorter than the source list and labels it with each source's own weight (`seenList`, not the top weight: a group edge's top weight can come from a source that did not see all of it), adds a legend line, and with `Tooltips` (svg) gives each edge a `codegraph 3, scip-go 5` tooltip; with one source the DOT is byte-identical to before lists existed. `Violation.SeenBy` names the sources in the `--forbid` report. A source that found no edges while others did gets `SourceFoundNoEdgesWarning`; a blank union gets every source's own empty-graph warning, prefixed with its label (`labelWarning`), as do per-source budget cuts. @@ -228,6 +229,7 @@ No environment variables, and no config file read unless `--rules` names one. Al | `--group-depth` | unset (one node per file) | `--architecture`-only: rolls each file up into its first N directory segments and draws those as the graph's nodes, summing the weights of every file pair that collapses into the same group pair (`RollupFileEdges`). The answer to the per-file hairball that `--max-render` only half-solves: `--max-render` is lossy at *every* level (the least-busy files are dropped outright, and any edge touching one goes with them), while grouping is lossless at the *module* level specifically — every cross-module call still appears, drawn between directories instead of files. It is not lossless in total: calls that become intra-group are dropped exactly as same-file calls already are, so a grouped diagram's summed weights are legitimately lower (often far lower) than the per-file one's. That difference is the repo's intra-module traffic, and the docs say so, because a user reconciling the two pictures would otherwise read it as a weight-aggregation bug. Composable with `--max-render`, which then caps groups rather than files (`RenderTruncationNote` says `groups`). Must be a positive integer. Rejected — not silently ignored — outside `--architecture`: symbol mode and `--diff` have no file-level graph to roll up, so passing it there is always a mistake, and a silently-dropped flag reads as "grouping applied" in exactly the diagram you would then trust. Applied *after* the file edges are derived, never during, so this stays a pure view over the same data rather than a second scan mode. With `--embed` it claims its own marker id (`codeshot:arch-d`) and default image name rather than the plain `codeshot:arch` — the per-file and per-module pictures answer different questions, so embedding one must not silently overwrite the other's committed block; unset `--group-depth` keeps the original id. | | `--forbid` | unset (no rules) | `--architecture`-only, repeatable: `FROM->TO` architecture rules (`ParseForbidRule`; a side ending in `/` is a directory prefix, any other side one exact file, a leading `./` is stripped). `ForbiddenEdges` checks them against the per-file edges from `AggregateFileEdges`, *before* `RollupFileEdges` and `--max-render`: those are view choices, and a rule must not pass because the view hid the edge. Each violation is printed by `ForbidViolationReport` (heaviest first, with weight and rule) and drawn red (`#dc2626`, penwidth 1.8 — the one loud color in the muted house style) by `BuildArchitectureDot`'s `Violating` option; `ViolatingDrawnKeys` maps a per-file violation onto the drawn edge, the directory edge under `--group-depth` (one that rolls into a single group isn't drawn). `--max-render` is not overridden to force a violating edge into the picture; `HiddenViolationNote` counts the ones it leaves out, since the exit code already fails the run. With no violations the DOT is byte-identical to a run without `--forbid`, and `SVGStructure` ignores colour, so `--check` is unaffected either way. The diagram is still rendered and embedded, then the process exits 1. Malformed rules and use outside `--architecture` are rejected before any codegraph work. Exact/prefix matching was chosen over globs to keep it predictable; patterns are for the `--rules` file only. | | `--rules` | unset | `--architecture`-only: a YAML rules file (`version: 1`; `layers`, `forbid` with an optional `reason`, `allow`), read and validated before any graph work (`ReadRules`). Its rules join the `--forbid` flags and run at the same point, on the per-file edges before `--group-depth` and `--max-render`; an allow rule exempts an edge from every rule, flags included. A rules-file side may use `*`, `?` and `[...]` within one path segment, with `\` escaping; `**` is refused. `--forbid` flag sides stay literal. Not discovered automatically: a repo that already has a `.codeshot.yaml` is unaffected until `--rules` is passed. | +| `--sarif` | unset | `--architecture`-only: write the `--forbid`/`--rules` violations to this file as SARIF 2.1.0 (`WriteSARIF`), before the diagram is written, on every run (an empty results list when nothing breaks a rule) and with `--check`. Exit codes are unchanged. | | `--source` | `codegraph` | Where the graph comes from, in every mode. `codegraph` reads the index under `--path` (`CodegraphSource`); `snapshot:` reads a graph-assay snapshot v1 (`SnapshotSource`). Both implement `ArchSource` (`Symbols`, `FileEdges`), and everything after those two calls is shared, so `--forbid`, `--group-depth`, `--max-symbols` and `--embed --check` behave identically. `SnapshotSource` maps the snapshot onto the same `IndexRow`s the index read produces, keyed by the node's `qname` (the node id when it has none), so a snapshot exported from a codegraph index draws a byte-identical DOT (48 runs on three repos, Go, TypeScript and Python, up to 5000 symbols, canon and svg). That needs `FileEdgesFromIndexRows` to ignore row order (the index read returns SQLite plan order, a snapshot its file order): it takes each definition's targets by target file, then target id. A snapshot adds `-snapshot-` to the `--embed` marker id and default image name (`SnapshotMarkerSuffix`), so its diagram can share a doc with the codegraph one. `` is `subject.name` with every run of characters outside `[A-Za-z0-9._-]` replaced by `-`, trimmed, and capped at 40, since it lands in a filename, a markdown link and alt text; the same label names the snapshot in warnings. `--path`'s subpath (`EmbedPathSuffix`) is not added for a snapshot, whose graph doesn't come from `--path`. `UndrawnEdgeKindsWarning` names, with counts, any edge kind that is neither drawn nor known to be structural (`contains`, `extends`, `implements`, `decorates`), so another tool's kinds never drop out of the diagram and `--forbid` silently. `ArchSource.EmptyGraphWarning` words the blank-diagram warning for the source, and the `--limit` warning names the snapshot, so no message sends a snapshot user to codegraph. All three sources feed every mode. Every cheap flag check runs before the snapshot is read. In symbol mode and `--diff`, `CallSource` (`Resolve`, `Edges`, `Symbols`, `Wording`) stands where the codegraph CLI did: `CodegraphCalls` runs it as before, and `SnapshotCalls` answers `callers`/`callees --json` the way the codegraph fork does: lookup by exact name, or a qualified query (`.`, `/`, `::`, `#` all read as `.`) matched as a suffix of the qualified name, never a fuzzy hit; one definition group per (file, qualified name) with its own callers or callees over `CalleeEdgeKinds`, deduped by node, without the symbol itself; and a union capped at `--limit` with exact `total`/`truncated`. Both sources' neighbours are sorted (`SortSymbolsForEnumeration`) before drawing, because codegraph's edge query has no ORDER BY and a snapshot keeps its file's order. `Wording` keeps every symbol and `--diff` warning from sending a snapshot user to codegraph. With a snapshot, the symbol and `--diff` marker ids and image names get `-snapshot-`, and `--diff` keeps `--path`'s subdirectory suffix, since git still finds the changes there. Edge kinds the snapshot has but codeshot doesn't follow are named in every mode (`UnfollowedEdgeKindsWarning` outside `--architecture`). `IndexHealthWarning` (codegraph's unresolved-refs count) is skipped for a snapshot. `scip[:]` reads a SCIP index (`ScipSource`; default `<--path>/index.scip`). Its rule: document A depends on document B when A has an occurrence that is neither a definition nor an import, of a non-local symbol whose last descriptor isn't a namespace/package, defined in B ≠ A (to every such B). Package references are dropped because they are import-shaped and codegraph draws an import only alongside a call. Each (file, referenced symbol) pair is one unit of edge weight. `Symbols` is one `file` node per document: the edges are per file, so `--max-symbols` counts files (counting definitions spent the default 500 on struct fields and package clauses: codeshot's own index has 729), and a file that defines nothing still draws. Documents are sorted by path, and each document's definitions, references and the edge list are sorted, so the indexer's document and occurrence order never reaches the DOT. Documents sharing a path are one file split across messages and are merged. A document whose cleaned path leaves the project root is skipped; an empty, unclean or `.` path inside the root is an error. The marker suffix is `scip-` (`scipLabel`, not doubled for `scip-go`). `EmbedPathSuffix` is added to the image name (not the marker id, as for codegraph) for bare `--source scip`, which reads `<--path>/index.scip`, and not for `scip:`. `ScipSource.BudgetWarning` (the optional `budgetWarner` interface) words the `--max-symbols` cut in files. On codeshot itself, scip-go v0.2.8 vs codegraph em.41: 97 vs 88 file edges; SCIP's 11 extra are type and struct-field references (mostly `Node` fields reached through `type Node = codegraph.Node`), codegraph's 2 extra are interface dispatch (`arch.go` to the `ArchSource` implementations). In symbol mode and `--diff`, `NewScipCalls` turns `scipindex.Calls` into an in-memory snapshot and answers through `SnapshotCalls`, so lookup, grouping, `--limit` and the warnings are shared; only the phrase and `Wording` name the index. `Calls` draws a node for every non-local definition whose last descriptor is a method or type, and for a term that the indexer calls a function or method, that is a top-level constant or variable, or that has an enclosing range outside Go (scip-typescript ranges only function-valued variables; scip-go ranges every field and variable, measured on codeshot's own index and gorilla/mux). Functions, methods, types and those function-valued terms are callers: a reference's caller is the innermost enclosing range holding its position, compared by line and character (the range starting last, then ending first; end exclusive), counted from the definition's name line when the range starts above it (scip-go's range starts at the doc comment, scip-python's at the decorators), else the file node. A symbol defined more than once in one file (TypeScript overloads, nested Python functions scip-python gives one symbol) is one node there, and each of its ranges draws from it, so `--limit` counts it once. Imports, locals, namespaces, symbols defined outside the project and a definition's reference to itself draw nothing; each (caller, callee) is one `references` edge. A definition that should be a caller but has no enclosing range is counted in a warning; the references inside it are drawn from the ranged definition or file around it. Probe (2026-11-15) on codeshot at this branch, 60 functions, scip-go v0.2.8 vs codegraph em.8 symbol mode: 297 of 317 codegraph edges reproduced, 28 SCIP-only edges (type references, package variables); the 20 codegraph-only edges are its case-insensitive lookup and same-name interface linking. | | `--max-symbols` | `500` | `--architecture`: caps how many enumerated symbols have their edges included, applied client-side to the path-sorted enumeration; `SymbolBudgetWarning` prints a stderr note when it cuts. Must be a positive integer. **`--diff`/`--diff-ref` reuses the same flag for a differently-scoped budget**: it caps how many *changed, matched* symbols get probed for callers/callees (two calls each), not how many of the whole repo get enumerated — `enumerateAllSymbols` always fetches the full index first so filtering down to the changed files never loses a symbol to this cap before matching happens; `DiffSymbolBudgetWarning` prints the diff-scoped stderr note. Ignored in symbol mode. | | `--diff` | `false` | Switches to diff-scoped mode: diagrams the symbols codegraph attributes to files `git diff` (working tree vs `HEAD`, no ref) reports changed, each drawn as a bold root with its direct callers/callees fanned out — see `BuildDiffDot`/`RunDiffMode`. `MatchRootSymbols` excludes codegraph's `"kind":"file"` and `"kind":"import"` index entries from becoming roots (an import's text probed as a name can resolve to another symbol and borrow its edges) — otherwise a changed file itself would be drawn as a bold root, since enumeration deliberately keeps file entries for `--architecture`'s sake. Mutually exclusive with `--architecture` and the `` positional. `--depth`/`--max-depth-nodes`/`--group-depth` have no meaning here: `--group-depth` is rejected if passed, `--depth`/`--max-depth-nodes` unless left at their defaults. A diff with zero changed files skips the full-index enumeration entirely (it could only ever match nothing); with `--embed` (and not `--check`, which never writes and so has nothing to protect — see `handleEmptyRoots`) it refuses outright rather than rendering a blank diagram over a real, committed one — see `DiffEmbedRefusal`/`DiffEmbedRefusalNoSymbols` (the latter for the same zero-roots outcome when real changed files match no indexed symbol). A changed root with no callers/callees still draws (a lone box). Roots with no edges (`DiffEmptyRootsWarning`) and roots whose fetch was cut off by `--limit` (`DiffTruncationWarning`, decided by `ReadTruncation` as in symbol mode) are each reported once in aggregate rather than per root, to avoid stderr noise on a large diff. | diff --git a/USAGE.md b/USAGE.md index 464984e..48a4a39 100644 --- a/USAGE.md +++ b/USAGE.md @@ -153,6 +153,41 @@ overlap or a bad pattern fails at once, naming the entry. (Layers whose paths are patterns are checked for overlap file by file instead.) This repo checks its own [`.codeshot.yaml`](.codeshot.yaml) in CI. +#### Code-scanning alerts with `--sarif` + +`--sarif ` also writes the violations as [SARIF +2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html), the +format GitHub code scanning reads, so each one shows up as an alert on the line +of the pull request that added it: + +```yaml +jobs: + architecture: + runs-on: ubuntu-latest + permissions: + contents: read + security-events: write # upload-sarif needs it + steps: + - uses: actions/checkout@v4 + # ... install codeshot, codegraph and graphviz, build the index ... + - run: codeshot --architecture --path . --rules .codeshot.yaml --sarif codeshot.sarif --format svg --out arch.svg + - uses: github/codeql-action/upload-sarif@v3 + if: always() # upload even when the rules failed the step + with: + sarif_file: codeshot.sarif + category: codeshot +``` + +Each result sits in the depending file, at the first line where it calls or +refers to the other file (the smallest line codegraph, the snapshot or the +SCIP index records), with the depended-on file as a related location. When no +source knows a line, the result points at line 1 of the file. The alert's +fingerprint comes from the rule and the two files, not the line, so moving the +call doesn't open a new alert. The file is written on every run, with an empty +list when nothing breaks a rule (which is what closes fixed alerts), and also +with `--check`. Paths are the ones in the diagram, so run from the repository +root (`--path .`) for them to match what GitHub checked out. + ### Drawing from another tool's graph `--source snapshot:` draws the architecture from a graph-assay snapshot diff --git a/docs/architecture.svg b/docs/architecture.svg index dbde5ee..8e23dde 100644 --- a/docs/architecture.svg +++ b/docs/architecture.svg @@ -4,1411 +4,1528 @@ - - + + 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/cli.go->internal/codeshot/sarif.go + + +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 - - -5 + + +7 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 + + + internal/codeshot/arch.go->internal/codeshot/warnings.go - - -9 + + +9 - + 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 + + +8 + + + +internal/codeshot/sarif.go->internal/codeshot/arch.go + + +5 + + + +internal/codeshot/sarif.go->internal/codeshot/sources.go + + +1 + + + +internal/codeshot/sarif.go->internal/codeshot/warnings.go + + +2 + + + +internal/codeshot/sarif.go->internal/scipindex/scipindex.go + + +1 + + + +internal/codeshot/sarif_test.go + +internal/codeshot/sarif_test.go + + + +internal/codeshot/sarif.go->internal/codeshot/sarif_test.go + + +1 - + internal/codeshot/warnings.go->internal/codegraph/codegraph.go - - -3 + + +3 - + internal/codeshot/warnings.go->internal/codeshot/arch.go - - -6 + + +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/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/helpers_test.go - - -9 + + +9 - + internal/codeshot/arch_test.go->internal/codeshot/diff.go - - -2 + + +2 - + 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/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/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 + + +1 - + internal/codeshot/output.go->internal/codeshot/diff.go - - -2 + + +2 - + 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/helpers_test.go - - -14 + + +14 - + internal/codeshot/diff_test.go->internal/codeshot/diff.go - - -16 + + +16 - + 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/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/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/sarif_test.go->internal/codegraph/index.go + + +3 + + + +internal/codeshot/sarif_test.go->internal/codeshot/sources.go + + +1 + + + +internal/codeshot/sarif_test.go->internal/codeshot/source_snapshot.go + + +1 + + + +internal/codeshot/sarif_test.go->internal/codeshot/sarif.go + + +4 + + + +internal/codeshot/sarif_test.go->internal/codeshot/helpers_test.go + + +4 + + + +internal/codeshot/sarif_test.go->internal/snapshot/snapshot.go + + +1 + + + +internal/codeshot/sarif_test.go->internal/codeshot/source_snapshot_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/helpers_test.go - - -14 + + +14 - + internal/codeshot/source_snapshot_calls_test.go->internal/codeshot/diff.go - - -1 + + +1 - + 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 - - -11 + + +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/codegraph/index.go b/internal/codegraph/index.go index 87734e2..7926617 100644 --- a/internal/codegraph/index.go +++ b/internal/codegraph/index.go @@ -163,3 +163,62 @@ func nullable(s sql.NullString) string { // ErrNoIdentity means the enumerated symbols lack qualifiedName (codegraph // before 1.6.0), so they can't be matched to index rows. var ErrNoIdentity = errors.New("symbols carry no qualifiedName") + +// FilePair is a (from file, to file) dependency. +type FilePair struct{ From, To string } + +// ReadSiteLines returns, for every pair of files with a callee edge between +// them (imports and file-kind targets aside, as --architecture draws), the +// smallest line in From of such an edge: the edge's own line, or the calling +// node's start line when codegraph stored none. Read-only, with the same +// immutable retry as ReadIndexRows. +func ReadSiteLines(dbPath string) (map[FilePair]int, error) { + lines, err := readSiteLines(indexURI(dbPath, false)) + if err != nil && !IsSchemaError(err) && walIsEmpty(dbPath) { + if retry, rerr := readSiteLines(indexURI(dbPath, true)); rerr == nil { + return retry, nil + } + } + return lines, err +} + +func readSiteLines(uri string) (map[FilePair]int, error) { + db, err := sql.Open("sqlite", uri) + if err != nil { + return nil, err + } + defer func() { _ = db.Close() }() + var kinds []string + for _, k := range CalleeEdgeKinds { + if k != "imports" { + kinds = append(kinds, k) + } + } + placeholders := strings.TrimSuffix(strings.Repeat("?, ", len(kinds)), ", ") + args := make([]any, len(kinds)) + for i, k := range kinds { + args[i] = k + } + rows, err := db.Query(`SELECT s.file_path, t.file_path, MIN(COALESCE(e.line, s.start_line)) + FROM edges e + JOIN nodes s ON s.id = e.source + JOIN nodes t ON t.id = e.target + WHERE e.kind IN (`+placeholders+`) AND t.kind != 'file' AND s.file_path != t.file_path + GROUP BY s.file_path, t.file_path`, args...) + if err != nil { + return nil, err + } + defer func() { _ = rows.Close() }() + out := map[FilePair]int{} + for rows.Next() { + var from, to sql.NullString + var line sql.NullInt64 + if err := rows.Scan(&from, &to, &line); err != nil { + return nil, err + } + if from.Valid && to.Valid && line.Valid && line.Int64 > 0 { + out[FilePair{From: from.String, To: to.String}] = int(line.Int64) + } + } + return out, rows.Err() +} diff --git a/internal/codegraph/index_test.go b/internal/codegraph/index_test.go index 54ce5c3..8de628b 100644 --- a/internal/codegraph/index_test.go +++ b/internal/codegraph/index_test.go @@ -99,3 +99,38 @@ func TestReadIndexRowsClassifiesSchemaErrors(t *testing.T) { t.Errorf("corrupt file: err = %v, IsSchemaError = %v; want a non-schema error", err, IsSchemaError(err)) } } + +// ReadSiteLines: the smallest edge line per file pair, the caller's start +// line when the edge has none; imports, file targets and same-file edges +// are left out. +func TestReadSiteLinesTakesTheFirstCallSitePerFilePair(t *testing.T) { + dbPath := filepath.Join(t.TempDir(), ".codegraph", "codegraph.db") + if err := os.MkdirAll(filepath.Dir(dbPath), 0o755); err != nil { + t.Fatal(err) + } + db, err := sql.Open("sqlite", dbPath) + if err != nil { + t.Fatal(err) + } + for _, q := range []string{ + `CREATE TABLE nodes (id TEXT PRIMARY KEY, kind TEXT, name TEXT, qualified_name TEXT NOT NULL, file_path TEXT, start_line INTEGER)`, + `CREATE TABLE edges (source TEXT, target TEXT, kind TEXT, line INTEGER)`, + `INSERT INTO nodes VALUES ('a1','function','A1','A1','a.go',3), ('a2','function','A2','A2','a.go',40), + ('b','function','B','B','b.go',1), ('c','function','C','C','c.go',1), ('f','file','d.go','d.go','d.go',1)`, + `INSERT INTO edges VALUES ('a2','b','calls',44), ('a1','b','calls',12), ('a1','b','imports',1), + ('a2','c','calls',NULL), ('a1','f','calls',2), ('a1','a2','calls',5)`, + } { + if _, err := db.Exec(q); err != nil { + t.Fatalf("%s: %v", q, err) + } + } + _ = db.Close() + got, err := ReadSiteLines(dbPath) + if err != nil { + t.Fatal(err) + } + want := map[FilePair]int{{From: "a.go", To: "b.go"}: 12, {From: "a.go", To: "c.go"}: 40} + if len(got) != len(want) || got[FilePair{"a.go", "b.go"}] != 12 || got[FilePair{"a.go", "c.go"}] != 40 { + t.Errorf("got %v, want %v", got, want) + } +} diff --git a/internal/codeshot/arch.go b/internal/codeshot/arch.go index 0742bcb..5c552d6 100644 --- a/internal/codeshot/arch.go +++ b/internal/codeshot/arch.go @@ -218,6 +218,8 @@ type Violation struct { Weight int SeenBy string // multi-source: "codegraph 3, scip-go 5" Breaks string // rules file: what the edge breaks; empty for a --forbid flag + Kind string // "layers" for a layer violation; "" for a forbid rule or flag + Line int // --sarif: first call-site line in From; 0 when unknown or not asked } // ParseForbidRule parses FROM->TO; ok=false when malformed. @@ -504,6 +506,7 @@ type ArchParams struct { Forbid []ForbidRule 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 } // ArchSource is where --architecture's graph comes from: every symbol in @@ -542,7 +545,11 @@ func RunArchitectureMode(src ArchSource, p ArchParams, stderr io.Writer) (string if err != nil { return "", nil, err } - return finishArchitecture(rawFileEdges, p, nil, func() { warn(stderr, src.EmptyGraphWarning()) }, stderr) + dot, vs, err := finishArchitecture(rawFileEdges, p, nil, func() { warn(stderr, src.EmptyGraphWarning()) }, stderr) + if err == nil && p.SiteLines { + fillSiteLines(vs, []LabeledSource{{Src: src}}, stderr) + } + return dot, vs, err } // LabeledSource is one entry of a multi-source --source list: the source and @@ -580,7 +587,11 @@ func RunMultiArchitectureMode(srcs []LabeledSource, p ArchParams, stderr io.Writ warn(stderr, labelWarning(s.Label, s.Src.EmptyGraphWarning())) } } - return finishArchitecture(union, p, labels, emptyGraph, stderr) + dot, vs, err := finishArchitecture(union, p, labels, emptyGraph, stderr) + if err == nil && p.SiteLines { + fillSiteLines(vs, srcs, stderr) + } + return dot, vs, err } // sourceFileEdges enumerates one source's symbols, applies --max-symbols and diff --git a/internal/codeshot/cli.go b/internal/codeshot/cli.go index 2772036..1b7558f 100644 --- a/internal/codeshot/cli.go +++ b/internal/codeshot/cli.go @@ -40,7 +40,7 @@ const ( ) const usage = `Usage: codeshot [--source codegraph|snapshot:|scip[:]] [--path ] [--out ] [--limit ] [--max-render ] [--format ] [--depth ] [--max-depth-nodes ] [--embed [--check]] - or: codeshot --architecture [--source codegraph|snapshot:|scip[:][,...]] [--path ] [--out ] [--max-render ] [--max-symbols ] [--group-depth ] [--forbid to>]... [--rules ] [--format ] [--embed [--check]] + or: codeshot --architecture [--source codegraph|snapshot:|scip[:][,...]] [--path ] [--out ] [--max-render ] [--max-symbols ] [--group-depth ] [--forbid to>]... [--rules ] [--sarif ] [--format ] [--embed [--check]] or: codeshot --diff [--diff-ref ] [--source codegraph|snapshot:|scip[:]] [--path ] [--out ] [--limit ] [--max-render ] [--max-symbols ] [--format ] [--embed [--check]]` type optSpec struct { @@ -51,7 +51,7 @@ var options = map[string]optSpec{ "version": {boolean: true}, "path": {}, "out": {}, "limit": {}, "max-render": {}, "format": {}, "depth": {}, "max-depth-nodes": {}, "architecture": {boolean: true}, "max-symbols": {}, "group-depth": {}, "diff": {boolean: true}, "diff-ref": {}, - "embed": {}, "check": {boolean: true}, "forbid": {multiple: true}, "source": {}, "rules": {}, + "embed": {}, "check": {boolean: true}, "forbid": {multiple: true}, "source": {}, "rules": {}, "sarif": {}, } // parsed holds flag values; a string flag absent from str was not given. @@ -394,6 +394,16 @@ func run(args []string, stdout, stderr io.Writer) (int, error) { return 0, &Exit{Code: 1, Stderr: "codeshot: " + err.Error()} } } + // --sarif: the rule violations as SARIF 2.1.0, for code-scanning alerts. + sarifFile, hasSARIF := p.str["sarif"] + if hasSARIF { + if sarifFile == "" { + return 0, &Exit{Code: 1, Stderr: "codeshot: --sarif must not be empty"} + } + if !arch { + return 0, &Exit{Code: 1, Stderr: "codeshot: --sarif only applies with --architecture (it reports --forbid and --rules violations)"} + } + } embedFile, hasEmbed := p.str["embed"] if hasEmbed && embedFile == "" { return 0, &Exit{Code: 1, Stderr: "codeshot: --embed must not be empty"} @@ -574,7 +584,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} + ap := ArchParams{MaxSymbols: maxSymbols, MaxRender: maxRender, GroupDepth: groupDepth, Forbid: rules, Rules: rulesFile, Tooltips: tooltips, SiteLines: hasSARIF} var dot string var violations []Violation if multi != nil { @@ -611,6 +621,13 @@ func run(args []string, stdout, stderr io.Writer) (int, error) { if err != nil { return 0, err } + // Written before the diagram, so a failing --check still leaves CI + // its findings, and with zero violations, so fixed alerts close. + if hasSARIF { + if err := WriteSARIF(sarifFile, violations, versionString()); err != nil { + return 0, err + } + } out.MarkerID = archMarkerID var notes []string if groupDepth != 0 { diff --git a/internal/codeshot/rules.go b/internal/codeshot/rules.go index 763319b..cac6736 100644 --- a/internal/codeshot/rules.go +++ b/internal/codeshot/rules.go @@ -250,6 +250,7 @@ func RuleViolations(fileEdges []FileEdge, flags []ForbidRule, rules *Rules) ([]V hits = append(hits, Violation{ Rule: lf + "->" + lt, From: e.From, To: e.To, Weight: e.Weight, SeenBy: seenList(e.Seen, nil), Breaks: fmt.Sprintf("the layers in %s ('%s' may not depend on '%s', a layer above it)", rules.File, lf, lt), + Kind: "layers", }) } var kept []Violation diff --git a/internal/codeshot/sarif.go b/internal/codeshot/sarif.go new file mode 100644 index 0000000..24d8564 --- /dev/null +++ b/internal/codeshot/sarif.go @@ -0,0 +1,262 @@ +package codeshot + +import ( + "crypto/sha256" + "encoding/hex" + "encoding/json" + "fmt" + "io" + "os" + "slices" + + "github.com/inth3shadows/codeshot/internal/codegraph" + "github.com/inth3shadows/codeshot/internal/snapshot" +) + +// SiteLiner is a source that can say where, in a file, it saw a dependency +// on another file: the smallest 1-based line of such a call or reference, +// for every file pair it knows. Asked only when --sarif needs line numbers +// for violations, so the diagram path never pays for it. +type SiteLiner interface { + SiteLines() (map[codegraph.FilePair]int, error) +} + +func (s CodegraphSource) SiteLines() (map[codegraph.FilePair]int, error) { + idx, err := codegraph.FindIndex(s.RepoPath) + if err != nil { + return nil, err + } + return codegraph.ReadSiteLines(idx) +} + +// SiteLines: the smallest line of a drawn-kind edge (not imports, not to a +// file node) between nodes in two files; a snapshot's line is optional. +func (s SnapshotSource) SiteLines() (map[codegraph.FilePair]int, error) { + byID := make(map[string]snapshot.Node, len(s.Snap.Nodes)) + for _, n := range s.Snap.Nodes { + byID[n.ID] = n + } + out := map[codegraph.FilePair]int{} + for _, e := range s.Snap.Edges { + if e.Line == nil || *e.Line < 1 || e.Kind == "imports" || !slices.Contains(codegraph.CalleeEdgeKinds, e.Kind) { + continue + } + src, dst := byID[e.Src], byID[e.Dst] + if dst.Kind == "file" || src.File == "" || dst.File == "" || src.File == dst.File { + continue + } + k := codegraph.FilePair{From: src.File, To: dst.File} + if cur, ok := out[k]; !ok || *e.Line < cur { + out[k] = *e.Line + } + } + return out, nil +} + +func (s ScipSource) SiteLines() (map[codegraph.FilePair]int, error) { + out := map[codegraph.FilePair]int{} + for k, line := range s.Index.RefLines() { + out[codegraph.FilePair{From: k[0], To: k[1]}] = line + } + return out, nil +} + +// SiteLines rebases the inner source's pairs the way FileEdges does. +func (p prefixedSource) SiteLines() (map[codegraph.FilePair]int, error) { + sl, ok := p.Src.(SiteLiner) + if !ok { + return nil, nil + } + lines, err := sl.SiteLines() + if err != nil { + return nil, err + } + out := make(map[codegraph.FilePair]int, len(lines)) + for k, line := range lines { + r := codegraph.FilePair{From: p.rebase(k.From), To: p.rebase(k.To)} + if cur, ok := out[r]; !ok || line < cur { + out[r] = line + } + } + return out, nil +} + +// fillSiteLines sets each violation's Line to the smallest line any source +// gives its file pair; 0 when none knows. A source that can't answer costs +// its lines only, with a warning: the violations stand either way. +func fillSiteLines(vs []Violation, srcs []LabeledSource, stderr io.Writer) { + if len(vs) == 0 { + return + } + best := map[codegraph.FilePair]int{} + for _, s := range srcs { + sl, ok := s.Src.(SiteLiner) + if !ok { + continue + } + lines, err := sl.SiteLines() + if err != nil { + warn(stderr, labelWarning(s.Label, fmt.Sprintf("codeshot: --sarif: could not read line numbers (%v); its findings point at line 1 of the file.", err))) + continue + } + for k, line := range lines { + if cur, ok := best[k]; !ok || line < cur { + best[k] = line + } + } + } + for i := range vs { + vs[i].Line = best[codegraph.FilePair{From: vs[i].From, To: vs[i].To}] + } +} + +// SARIF rule ids, one per kind of rule. +const ( + sarifForbidRule = "codeshot/forbid" + sarifLayersRule = "codeshot/layers" +) + +type sarifLog struct { + Schema string `json:"$schema"` + Version string `json:"version"` + Runs []sarifRun `json:"runs"` +} + +type sarifRun struct { + Tool sarifTool `json:"tool"` + Results []sarifResult `json:"results"` +} + +type sarifTool struct { + Driver sarifDriver `json:"driver"` +} + +type sarifDriver struct { + Name string `json:"name"` + Version string `json:"version"` + InformationURI string `json:"informationUri"` + Rules []sarifRule `json:"rules"` +} + +type sarifRule struct { + ID string `json:"id"` + Name string `json:"name"` + ShortDescription sarifText `json:"shortDescription"` + FullDescription sarifText `json:"fullDescription"` + HelpURI string `json:"helpUri"` + DefaultConfig sarifDefault `json:"defaultConfiguration"` +} + +type sarifDefault struct { + Level string `json:"level"` +} + +type sarifText struct { + Text string `json:"text"` +} + +type sarifResult struct { + RuleID string `json:"ruleId"` + RuleIndex int `json:"ruleIndex"` + Level string `json:"level"` + Message sarifText `json:"message"` + Locations []sarifLocation `json:"locations"` + RelatedLocations []sarifLocation `json:"relatedLocations"` + PartialFingerprints map[string]string `json:"partialFingerprints"` +} + +type sarifLocation struct { + ID *int `json:"id,omitempty"` + PhysicalLocation sarifPhysical `json:"physicalLocation"` + Message *sarifText `json:"message,omitempty"` +} + +type sarifPhysical struct { + ArtifactLocation sarifArtifact `json:"artifactLocation"` + Region *sarifRegion `json:"region,omitempty"` +} + +type sarifArtifact struct { + URI string `json:"uri"` + URIBaseID string `json:"uriBaseId,omitempty"` +} + +type sarifRegion struct { + StartLine int `json:"startLine"` +} + +// BuildSARIF encodes violations as a SARIF 2.1.0 log: one result per +// violation at the depending file (the first call-site line when known, +// else line 1), the depended-on file as a related location, and a +// fingerprint from the rule and the two files, so an alert survives the +// line moving. +func BuildSARIF(vs []Violation, version string) ([]byte, error) { + rules := []sarifRule{ + { + ID: sarifForbidRule, Name: "ForbiddenDependency", + ShortDescription: sarifText{"A file depends on a file a forbid rule keeps it from."}, + FullDescription: sarifText{"A --forbid flag or a forbid rule in the --rules file says files matching FROM may not depend on files matching TO, and codeshot's graph has such an edge."}, + HelpURI: "https://github.com/inth3shadows/codeshot/blob/master/USAGE.md#enforcing-architecture-rules", + DefaultConfig: sarifDefault{"error"}, + }, + { + ID: sarifLayersRule, Name: "LayerViolation", + ShortDescription: sarifText{"A file in a lower layer depends on a higher layer."}, + FullDescription: sarifText{"The --rules file orders layers top to bottom; a layer may use itself and the layers below it, and this edge goes from a lower layer to a higher one."}, + HelpURI: "https://github.com/inth3shadows/codeshot/blob/master/USAGE.md#a-rules-file", + DefaultConfig: sarifDefault{"error"}, + }, + } + results := make([]sarifResult, 0, len(vs)) + for _, v := range vs { + id, idx := sarifForbidRule, 0 + if v.Kind == "layers" { + id, idx = sarifLayersRule, 1 + } + line := v.Line + if line < 1 { + line = 1 + } + sum := sha256.Sum256([]byte(id + "\x00" + v.Rule + "\x00" + v.From + "\x00" + v.To)) + related := 1 + results = append(results, sarifResult{ + RuleID: id, RuleIndex: idx, Level: "error", + Message: sarifText{violationText(v)}, + Locations: []sarifLocation{{PhysicalLocation: sarifPhysical{ + ArtifactLocation: sarifArtifact{URI: v.From}, + Region: &sarifRegion{StartLine: line}, + }}}, + RelatedLocations: []sarifLocation{{ + ID: &related, + PhysicalLocation: sarifPhysical{ArtifactLocation: sarifArtifact{URI: v.To}}, + Message: &sarifText{"the file it depends on"}, + }}, + PartialFingerprints: map[string]string{"codeshotEdge/v1": hex.EncodeToString(sum[:16])}, + }) + } + log := sarifLog{ + Schema: "https://json.schemastore.org/sarif-2.1.0.json", + Version: "2.1.0", + Runs: []sarifRun{{ + Tool: sarifTool{Driver: sarifDriver{Name: "codeshot", Version: version, InformationURI: "https://github.com/inth3shadows/codeshot", Rules: rules}}, + Results: results, + }}, + } + out, err := json.MarshalIndent(log, "", " ") + if err != nil { + return nil, err + } + return append(out, '\n'), nil +} + +// WriteSARIF writes BuildSARIF's log to file. +func WriteSARIF(file string, vs []Violation, version string) error { + data, err := BuildSARIF(vs, version) + if err != nil { + return err + } + if err := os.WriteFile(file, data, 0o644); err != nil { + return fmt.Errorf("could not write --sarif file '%s': %w", file, err) + } + return nil +} diff --git a/internal/codeshot/sarif_test.go b/internal/codeshot/sarif_test.go new file mode 100644 index 0000000..cf44499 --- /dev/null +++ b/internal/codeshot/sarif_test.go @@ -0,0 +1,214 @@ +package codeshot + +import ( + "encoding/json" + "os" + "os/exec" + "path/filepath" + "strings" + "testing" + + "github.com/inth3shadows/codeshot/internal/codegraph" + "github.com/inth3shadows/codeshot/internal/snapshot" +) + +// decodeSARIF reads back what BuildSARIF wrote, as generic JSON. +func decodeSARIF(t *testing.T, data []byte) map[string]any { + t.Helper() + var m map[string]any + if err := json.Unmarshal(data, &m); err != nil { + t.Fatalf("not JSON: %v\n%s", err, data) + } + return m +} + +func sarifResults(t *testing.T, m map[string]any) []any { + t.Helper() + runs := m["runs"].([]any) + if len(runs) != 1 { + t.Fatalf("runs: %d", len(runs)) + } + res, ok := runs[0].(map[string]any)["results"].([]any) + if !ok { + t.Fatalf("results is not a list: %v", runs[0].(map[string]any)["results"]) + } + return res +} + +func TestBuildSARIFWritesOneResultPerViolation(t *testing.T) { + vs := []Violation{ + {Rule: "a/->b/", From: "a/x.go", To: "b/y.go", Weight: 3, Line: 12, SeenBy: "codegraph 3, scip-go 1"}, + {Rule: "core->cli", From: "core/c.go", To: "cmd/m.go", Weight: 1, Kind: "layers", + Breaks: "the layers in .codeshot.yaml ('core' may not depend on 'cli', a layer above it)"}, + } + data, err := BuildSARIF(vs, "1.2.3") + if err != nil { + t.Fatal(err) + } + m := decodeSARIF(t, data) + if m["version"] != "2.1.0" || m["$schema"] != "https://json.schemastore.org/sarif-2.1.0.json" { + t.Errorf("header: %v %v", m["version"], m["$schema"]) + } + driver := m["runs"].([]any)[0].(map[string]any)["tool"].(map[string]any)["driver"].(map[string]any) + if driver["name"] != "codeshot" || driver["version"] != "1.2.3" { + t.Errorf("driver: %v", driver) + } + rules := driver["rules"].([]any) + if len(rules) != 2 || rules[0].(map[string]any)["id"] != "codeshot/forbid" || rules[1].(map[string]any)["id"] != "codeshot/layers" { + t.Errorf("rules: %v", rules) + } + res := sarifResults(t, m) + if len(res) != 2 { + t.Fatalf("results: %d", len(res)) + } + r0, r1 := res[0].(map[string]any), res[1].(map[string]any) + if r0["ruleId"] != "codeshot/forbid" || r0["ruleIndex"] != 0.0 || r1["ruleId"] != "codeshot/layers" || r1["ruleIndex"] != 1.0 { + t.Errorf("rule ids: %v %v / %v %v", r0["ruleId"], r0["ruleIndex"], r1["ruleId"], r1["ruleIndex"]) + } + loc := func(r map[string]any) (string, float64) { + pl := r["locations"].([]any)[0].(map[string]any)["physicalLocation"].(map[string]any) + return pl["artifactLocation"].(map[string]any)["uri"].(string), pl["region"].(map[string]any)["startLine"].(float64) + } + if uri, line := loc(r0); uri != "a/x.go" || line != 12 { + t.Errorf("first: %s:%v, want a/x.go:12", uri, line) + } + if uri, line := loc(r1); uri != "core/c.go" || line != 1 { + t.Errorf("second: %s:%v, want core/c.go:1 (line unknown)", uri, line) + } + wantMatch(t, `^a/x\.go -> b/y\.go \(weight 3\) breaks --forbid 'a/->b/' — seen by codegraph 3, scip-go 1$`, r0["message"].(map[string]any)["text"].(string)) + wantMatch(t, `breaks the layers in \.codeshot\.yaml`, r1["message"].(map[string]any)["text"].(string)) + rel := r0["relatedLocations"].([]any)[0].(map[string]any)["physicalLocation"].(map[string]any)["artifactLocation"].(map[string]any)["uri"] + if rel != "b/y.go" { + t.Errorf("related: %v", rel) + } + fp := func(r map[string]any) string { + return r["partialFingerprints"].(map[string]any)["codeshotEdge/v1"].(string) + } + if fp(r0) == fp(r1) || len(fp(r0)) != 32 { + t.Errorf("fingerprints: %q %q", fp(r0), fp(r1)) + } + // The fingerprint ignores the line, so an alert survives the call moving. + moved := vs[0] + moved.Line = 99 + again, _ := BuildSARIF([]Violation{moved}, "1.2.3") + if fp(sarifResults(t, decodeSARIF(t, again))[0].(map[string]any)) != fp(r0) { + t.Error("fingerprint changed with the line") + } +} + +// Zero violations still write a log, with an empty results list (not null), +// so an upload closes alerts that were fixed. +func TestBuildSARIFWithNoViolationsHasAnEmptyResultsList(t *testing.T) { + data, err := BuildSARIF(nil, "dev") + if err != nil { + t.Fatal(err) + } + if !strings.Contains(string(data), `"results": []`) { + t.Errorf("want an empty results list:\n%s", data) + } + if len(sarifResults(t, decodeSARIF(t, data))) != 0 { + t.Error("results not empty") + } +} + +func TestSnapshotSiteLinesTakeTheSmallestDrawnKindLine(t *testing.T) { + l := func(n int) *int { return &n } + snap := &snapshot.Snapshot{ + Nodes: []snapshot.Node{ + {ID: "1", Kind: "function", Name: "A", File: "a.go"}, + {ID: "2", Kind: "function", Name: "B", File: "b.go"}, + {ID: "3", Kind: "file", Name: "c.go", File: "c.go"}, + {ID: "4", Kind: "function", Name: "A2", File: "a.go"}, + }, + Edges: []snapshot.Edge{ + {Kind: "calls", Src: "1", Dst: "2", Line: l(30)}, + {Kind: "calls", Src: "4", Dst: "2", Line: l(8)}, + {Kind: "imports", Src: "1", Dst: "2", Line: l(1)}, + {Kind: "calls", Src: "1", Dst: "3", Line: l(2)}, + {Kind: "calls", Src: "1", Dst: "4", Line: l(3)}, + {Kind: "overrides", Src: "1", Dst: "2", Line: l(4)}, + {Kind: "calls", Src: "2", Dst: "1"}, + }, + } + got, _ := SnapshotSource{Snap: snap}.SiteLines() + if len(got) != 1 || got[codegraph.FilePair{From: "a.go", To: "b.go"}] != 8 { + t.Errorf("got %v, want only a.go -> b.go at 8", got) + } +} + +type linedSource struct { + edgesSource + lines map[codegraph.FilePair]int +} + +func (s linedSource) SiteLines() (map[codegraph.FilePair]int, error) { return s.lines, nil } + +func TestFillSiteLinesTakesTheSmallestLineAcrossSourcesAndRebases(t *testing.T) { + a := linedSource{lines: map[codegraph.FilePair]int{{From: "sub/a.go", To: "sub/b.go"}: 9}} + b := prefixedSource{Src: linedSource{lines: map[codegraph.FilePair]int{{From: "a.go", To: "b.go"}: 4, {From: "./c.go", To: "b.go"}: 7}}, Prefix: "sub/"} + vs := []Violation{{From: "sub/a.go", To: "sub/b.go"}, {From: "sub/c.go", To: "sub/b.go"}, {From: "x.go", To: "y.go"}} + var stderr strings.Builder + fillSiteLines(vs, []LabeledSource{{Label: "cg", Src: a}, {Label: "snap", Src: b}}, &stderr) + if vs[0].Line != 4 || vs[1].Line != 7 || vs[2].Line != 0 { + t.Errorf("lines: %d %d %d, want 4 7 0", vs[0].Line, vs[1].Line, vs[2].Line) + } + if stderr.Len() != 0 { + t.Errorf("stderr: %s", stderr.String()) + } +} + +const sarifSnapshot = `{"schema":"graph-assay/snapshot@1","subject":{"name":"t"}, + "capabilities":{"siteLines":true,"siteColumns":false,"unresolved":false,"provenance":false}, + "files":[],"unresolved":[], + "nodes":[{"id":"1","kind":"function","name":"A","qname":"A","file":"src/a.go","start":1,"end":20}, + {"id":"2","kind":"function","name":"B","qname":"B","file":"lib/b.go","start":1,"end":2}], + "edges":[{"kind":"calls","src":"1","dst":"2","line":14}]}` + +// End to end from a snapshot: the violation lands on its call-site line, +// the run still exits 1 after writing both files, and a clean run writes an +// empty log. +func TestCLISarifWritesViolationsAtTheirCallSite(t *testing.T) { + requireBins(t, "dot") + dot, _ := exec.LookPath("dot") + t.Setenv("PATH", filepath.Dir(dot)) + if _, err := exec.LookPath("codegraph"); err == nil { + t.Skip("codegraph shares a directory with dot; cannot hide it") + } + dir := t.TempDir() + snap := "snapshot:" + writeSnapshotFile(t, sarifSnapshot) + sarif := filepath.Join(dir, "out.sarif") + code, _, stderr := runCLI("--architecture", "--source", snap, "--forbid", "src/->lib/", "--sarif", sarif, "--format", "dot", "--out", filepath.Join(dir, "a.dot")) + if code != 1 { + t.Fatalf("exit %d, want 1; stderr: %s", code, stderr) + } + data, err := os.ReadFile(sarif) + if err != nil { + t.Fatal(err) + } + res := sarifResults(t, decodeSARIF(t, data)) + if len(res) != 1 { + t.Fatalf("results: %d", len(res)) + } + pl := res[0].(map[string]any)["locations"].([]any)[0].(map[string]any)["physicalLocation"].(map[string]any) + if pl["artifactLocation"].(map[string]any)["uri"] != "src/a.go" || pl["region"].(map[string]any)["startLine"] != 14.0 { + t.Errorf("location: %v", pl) + } + + clean := filepath.Join(dir, "clean.sarif") + if code, _, stderr := runCLI("--architecture", "--source", snap, "--forbid", "lib/->src/", "--sarif", clean, "--format", "dot", "--out", filepath.Join(dir, "b.dot")); code != 0 { + t.Fatalf("clean run: exit %d; stderr: %s", code, stderr) + } + data, _ = os.ReadFile(clean) + if len(sarifResults(t, decodeSARIF(t, data))) != 0 { + t.Error("clean run wrote results") + } +} + +func TestCLISarifIsArchitectureOnly(t *testing.T) { + wantRejected(t, `--sarif only applies with --architecture`, "Foo", "--sarif", "x.sarif") + wantRejected(t, `--sarif only applies with --architecture`, "--diff", "--sarif", "x.sarif") + wantRejected(t, `--sarif must not be empty`, "--architecture", "--sarif", "") + if !strings.Contains(usage, "[--sarif ]") { + t.Error("usage does not mention --sarif") + } +} diff --git a/internal/codeshot/warnings.go b/internal/codeshot/warnings.go index fb864bb..931e636 100644 --- a/internal/codeshot/warnings.go +++ b/internal/codeshot/warnings.go @@ -130,11 +130,7 @@ func RuleViolationReport(vs []Violation, rulesMode bool) string { } edges := map[string]bool{} for i, v := range vs { - breaks := "--forbid '" + v.Rule + "'" - if v.Breaks != "" { - breaks = v.Breaks - } - lines[i] = fmt.Sprintf(" %s -> %s (weight %d) breaks %s", v.From, v.To, v.Weight, breaks) + lines[i] = " " + violationLine(v) edges[drawnEdgeKey(v.From, v.To)] = true if v.SeenBy != "" { lines[i] += " — seen by " + v.SeenBy @@ -368,3 +364,22 @@ func RootGuessWarning(relativeToPath bool, prefix string) string { } return fmt.Sprintf("codeshot: none of its files are on disk under --path or codegraph's index root, so its paths were taken to %s; if the same file shows up twice, it guessed wrong.", how) } + +// violationLine is one violation as the report words it, before any +// multi-source provenance. +func violationLine(v Violation) string { + breaks := "--forbid '" + v.Rule + "'" + if v.Breaks != "" { + breaks = v.Breaks + } + return fmt.Sprintf("%s -> %s (weight %d) breaks %s", v.From, v.To, v.Weight, breaks) +} + +// violationText is violationLine with the sources that saw the edge, the +// message --sarif gives each result. +func violationText(v Violation) string { + if v.SeenBy != "" { + return violationLine(v) + " — seen by " + v.SeenBy + } + return violationLine(v) +} diff --git a/internal/scipindex/scipindex.go b/internal/scipindex/scipindex.go index c3281c1..3c1168e 100644 --- a/internal/scipindex/scipindex.go +++ b/internal/scipindex/scipindex.go @@ -186,3 +186,58 @@ func (x *Index) FileEdges(from map[string]bool) []FileEdge { }) return out } + +// RefLines returns, for each (from, to) pair FileEdges draws, the smallest +// 1-based line in from of a reference to a symbol defined in to, by the same +// rules: no definitions, imports, locals or namespaces. +func (x *Index) RefLines() map[[2]string]int { + definedIn := map[string][]string{} + for _, d := range x.Docs { + for _, sym := range d.Defs { + definedIn[sym] = append(definedIn[sym], d.Path) + } + } + ns := map[string]bool{} + out := map[[2]string]int{} + for _, d := range x.Docs { + raw := x.raw[d.Path] + if raw == nil { + continue + } + for _, o := range raw.GetOccurrences() { + sym := o.GetSymbol() + if sym == "" || scip.IsLocalSymbol(sym) { + continue + } + // SourceRange reads the typed range fields as well as the + // deprecated packed one; scip-go 0.2.8 writes only the typed. + r, ok := o.SourceRange() + if !ok { + continue + } + roles := o.GetSymbolRoles() + if roles&int32(scip.SymbolRole_Definition) != 0 || roles&int32(scip.SymbolRole_Import) != 0 { + continue + } + isNS, ok := ns[sym] + if !ok { + isNS = isNamespace(sym) + ns[sym] = isNS + } + if isNS { + continue + } + line := int(r.Start.Line) + 1 + for _, f := range definedIn[sym] { + if f == d.Path { + continue + } + k := [2]string{d.Path, f} + if cur, ok := out[k]; !ok || line < cur { + out[k] = line + } + } + } + } + return out +} diff --git a/internal/scipindex/scipindex_test.go b/internal/scipindex/scipindex_test.go index 73b1268..df5c729 100644 --- a/internal/scipindex/scipindex_test.go +++ b/internal/scipindex/scipindex_test.go @@ -193,3 +193,58 @@ func TestParseSkipsOutOfRootPathsBeforeTheCleanCheck(t *testing.T) { t.Errorf("err %v", err) } } + +// RefLines: the first non-import, non-definition reference line (1-based) +// from one document to a symbol another defines. +func TestRefLinesTakeTheFirstReferencePerFilePair(t *testing.T) { + at := func(sym string, roles scip.SymbolRole, line int32) *scip.Occurrence { + return &scip.Occurrence{Symbol: sym, SymbolRoles: int32(roles), Range: []int32{line, 0, 4}} + } + x, err := Parse(encode(t, &scip.Index{ + Metadata: &scip.Metadata{ToolInfo: &scip.ToolInfo{Name: "scip-go"}}, + Documents: []*scip.Document{ + {RelativePath: "a/a.go", Occurrences: []*scip.Occurrence{ + at(pkgB, scip.SymbolRole_Import, 2), + at(funcA, scip.SymbolRole_Definition, 5), + at(funcB, 0, 20), + at(typeB, 0, 9), + at(funcA, 0, 1), + at("local 3", 0, 0), + }}, + {RelativePath: "b/b.go", Occurrences: []*scip.Occurrence{ + at(pkgB, scip.SymbolRole_Definition, 0), + at(funcB, scip.SymbolRole_Definition, 3), + at(typeB, scip.SymbolRole_Definition, 7), + }}, + }, + })) + if err != nil { + t.Fatal(err) + } + got := x.RefLines() + if len(got) != 1 || got[[2]string{"a/a.go", "b/b.go"}] != 10 { + t.Errorf("got %v, want a/a.go -> b/b.go at line 10 (typeB at 0-based 9)", got) + } +} + +// scip-go 0.2.8 writes only the typed range (single_line_range); RefLines +// must read it (it found no line at all on a real index before). +func TestRefLinesReadTheTypedRangeScipGoWrites(t *testing.T) { + typed := func(sym string, roles scip.SymbolRole, line int32) *scip.Occurrence { + return &scip.Occurrence{Symbol: sym, SymbolRoles: int32(roles), + TypedRange: &scip.Occurrence_SingleLineRange{SingleLineRange: &scip.SingleLineRange{Line: line, StartCharacter: 0, EndCharacter: 4}}} + } + x, err := Parse(encode(t, &scip.Index{ + Metadata: &scip.Metadata{ToolInfo: &scip.ToolInfo{Name: "scip-go"}}, + Documents: []*scip.Document{ + {RelativePath: "a/a.go", Occurrences: []*scip.Occurrence{typed(funcB, 0, 6)}}, + {RelativePath: "b/b.go", Occurrences: []*scip.Occurrence{typed(funcB, scip.SymbolRole_Definition, 3)}}, + }, + })) + if err != nil { + t.Fatal(err) + } + if got := x.RefLines()[[2]string{"a/a.go", "b/b.go"}]; got != 7 { + t.Errorf("got line %d, want 7", got) + } +} From 0384dabe0cbf8d85cb074881051f0ca02891bf38 Mon Sep 17 00:00:00 2001 From: Eric Minish Date: Wed, 18 Nov 2026 20:16:42 -0500 Subject: [PATCH 2/4] test: mark the deliberate deprecated SCIP range use for staticcheck golangci-lint v2.15.0 (CI) flags SA1019 on the test that covers indexers writing the deprecated packed range; that coverage is on purpose. --- internal/scipindex/scipindex_test.go | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/internal/scipindex/scipindex_test.go b/internal/scipindex/scipindex_test.go index df5c729..ea90383 100644 --- a/internal/scipindex/scipindex_test.go +++ b/internal/scipindex/scipindex_test.go @@ -198,7 +198,8 @@ func TestParseSkipsOutOfRootPathsBeforeTheCleanCheck(t *testing.T) { // from one document to a symbol another defines. func TestRefLinesTakeTheFirstReferencePerFilePair(t *testing.T) { at := func(sym string, roles scip.SymbolRole, line int32) *scip.Occurrence { - return &scip.Occurrence{Symbol: sym, SymbolRoles: int32(roles), Range: []int32{line, 0, 4}} + // Older indexers write the deprecated packed range; this case covers them. + return &scip.Occurrence{Symbol: sym, SymbolRoles: int32(roles), Range: []int32{line, 0, 4}} //nolint:staticcheck // SA1019, on purpose } x, err := Parse(encode(t, &scip.Index{ Metadata: &scip.Metadata{ToolInfo: &scip.ToolInfo{Name: "scip-go"}}, From fe1bca38f90e1d8111c255fcf1a15809ecaa8924 Mon Sep 17 00:00:00 2001 From: Eric Minish Date: Wed, 18 Nov 2026 20:35:14 -0500 Subject: [PATCH 3/4] fix: SARIF review round 1 (fingerprints, URIs, lines, empty logs) - F1: codeshot's hash goes in primaryLocationLineHash, the key GitHub tracks alerts by (upload-sarif keeps a given one); it includes the rule's wording, and an exact duplicate result is written once. - F2: artifact URIs are percent-encoded per segment; absolute paths are file:// URIs. - F3/F4: a real call line wins over the caller's start line, for codegraph and snapshots alike; 0 is no line. - F6: --sarif needs --forbid or --rules (an empty log would close every open alert). - A3/A4/F9: rules carry help text; the no-lines warning names the source and an old index plainly; one smallest-line helper. --- README.md | 4 +- TECHNICAL.md | 4 +- USAGE.md | 15 +- docs/architecture.svg | 1431 +++++++++++++++--------------- internal/codegraph/index.go | 19 +- internal/codegraph/index_test.go | 36 + internal/codeshot/cli.go | 5 + internal/codeshot/sarif.go | 112 ++- internal/codeshot/sarif_test.go | 126 ++- 9 files changed, 999 insertions(+), 753 deletions(-) diff --git a/README.md b/README.md index 3fc7fb4..7cf2c85 100644 --- a/README.md +++ b/README.md @@ -125,8 +125,8 @@ so the scan takes about a second. Flags specific to this mode: [`.codeshot.yaml`](.codeshot.yaml). - `--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. Written on every run, also when - nothing breaks a rule. See + depending file that calls into the other. Needs `--forbid` or `--rules`; + written on every run, also when nothing breaks a rule. See [USAGE.md](USAGE.md#code-scanning-alerts-with---sarif). - `--source snapshot:` — draw from a [graph-assay](https://github.com/inth3shadows/graph-assay) snapshot diff --git a/TECHNICAL.md b/TECHNICAL.md index 8885f6e..f32e9ab 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/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`), 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, and `partialFingerprints["codeshotEdge/v1"]` = the first 16 bytes of SHA-256 over rule id, rule, from and to, so an alert outlives its line moving. 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, `MIN(COALESCE(e.line, s.start_line))`, with the immutable retry), `SnapshotSource` takes the smallest optional edge `line`, `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. `fillSiteLines` takes the smallest line any source gives a pair; a source that fails to answer costs only its lines, with a warning. 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/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 path becomes `file://`), and `partialFingerprints.primaryLocationLineHash` = the first 16 bytes of SHA-256 over rule id, rule, its rules-file wording, from and to, plus `:1`. 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. `fillSiteLines` takes the smallest line any source gives a pair; 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. - **`internal/codeshot/arch.go`** — multi-source: `RunMultiArchitectureMode` runs `sourceFileEdges` (enumerate, `--max-symbols` cut, `FileEdges`, `AggregateFileEdges`) per `LabeledSource`, then `UnionFileEdges` merges them (first-seen order in `--source` order; `Weight` = the highest per-source weight, never a sum, since codegraph counts calls and SCIP references; `FileEdge.Seen` = each source's own weight). `finishArchitecture` is the shared tail (`--forbid`, rollup, warnings, DOT) for one source and many. `FileEdge.Full` = the sources that saw all of the edge. `RollupFileEdges` sums `Seen` per source, sets a group edge's weight to the highest per-source sum, and intersects `Full` over the file edges inside it, so a group edge is solid only when every source saw every file edge inside it. `BuildArchitectureDot` with `ArchOptions.Sources` (two or more) dashes an edge whose `Full` is shorter than the source list and labels it with each source's own weight (`seenList`, not the top weight: a group edge's top weight can come from a source that did not see all of it), adds a legend line, and with `Tooltips` (svg) gives each edge a `codegraph 3, scip-go 5` tooltip; with one source the DOT is byte-identical to before lists existed. `Violation.SeenBy` names the sources in the `--forbid` report. A source that found no edges while others did gets `SourceFoundNoEdgesWarning`; a blank union gets every source's own empty-graph warning, prefixed with its label (`labelWarning`), as do per-source budget cuts. @@ -229,7 +229,7 @@ No environment variables, and no config file read unless `--rules` names one. Al | `--group-depth` | unset (one node per file) | `--architecture`-only: rolls each file up into its first N directory segments and draws those as the graph's nodes, summing the weights of every file pair that collapses into the same group pair (`RollupFileEdges`). The answer to the per-file hairball that `--max-render` only half-solves: `--max-render` is lossy at *every* level (the least-busy files are dropped outright, and any edge touching one goes with them), while grouping is lossless at the *module* level specifically — every cross-module call still appears, drawn between directories instead of files. It is not lossless in total: calls that become intra-group are dropped exactly as same-file calls already are, so a grouped diagram's summed weights are legitimately lower (often far lower) than the per-file one's. That difference is the repo's intra-module traffic, and the docs say so, because a user reconciling the two pictures would otherwise read it as a weight-aggregation bug. Composable with `--max-render`, which then caps groups rather than files (`RenderTruncationNote` says `groups`). Must be a positive integer. Rejected — not silently ignored — outside `--architecture`: symbol mode and `--diff` have no file-level graph to roll up, so passing it there is always a mistake, and a silently-dropped flag reads as "grouping applied" in exactly the diagram you would then trust. Applied *after* the file edges are derived, never during, so this stays a pure view over the same data rather than a second scan mode. With `--embed` it claims its own marker id (`codeshot:arch-d`) and default image name rather than the plain `codeshot:arch` — the per-file and per-module pictures answer different questions, so embedding one must not silently overwrite the other's committed block; unset `--group-depth` keeps the original id. | | `--forbid` | unset (no rules) | `--architecture`-only, repeatable: `FROM->TO` architecture rules (`ParseForbidRule`; a side ending in `/` is a directory prefix, any other side one exact file, a leading `./` is stripped). `ForbiddenEdges` checks them against the per-file edges from `AggregateFileEdges`, *before* `RollupFileEdges` and `--max-render`: those are view choices, and a rule must not pass because the view hid the edge. Each violation is printed by `ForbidViolationReport` (heaviest first, with weight and rule) and drawn red (`#dc2626`, penwidth 1.8 — the one loud color in the muted house style) by `BuildArchitectureDot`'s `Violating` option; `ViolatingDrawnKeys` maps a per-file violation onto the drawn edge, the directory edge under `--group-depth` (one that rolls into a single group isn't drawn). `--max-render` is not overridden to force a violating edge into the picture; `HiddenViolationNote` counts the ones it leaves out, since the exit code already fails the run. With no violations the DOT is byte-identical to a run without `--forbid`, and `SVGStructure` ignores colour, so `--check` is unaffected either way. The diagram is still rendered and embedded, then the process exits 1. Malformed rules and use outside `--architecture` are rejected before any codegraph work. Exact/prefix matching was chosen over globs to keep it predictable; patterns are for the `--rules` file only. | | `--rules` | unset | `--architecture`-only: a YAML rules file (`version: 1`; `layers`, `forbid` with an optional `reason`, `allow`), read and validated before any graph work (`ReadRules`). Its rules join the `--forbid` flags and run at the same point, on the per-file edges before `--group-depth` and `--max-render`; an allow rule exempts an edge from every rule, flags included. A rules-file side may use `*`, `?` and `[...]` within one path segment, with `\` escaping; `**` is refused. `--forbid` flag sides stay literal. Not discovered automatically: a repo that already has a `.codeshot.yaml` is unaffected until `--rules` is passed. | -| `--sarif` | unset | `--architecture`-only: write the `--forbid`/`--rules` violations to this file as SARIF 2.1.0 (`WriteSARIF`), before the diagram is written, on every run (an empty results list when nothing breaks a rule) and with `--check`. Exit codes are unchanged. | +| `--sarif` | unset | `--architecture`-only, and only with `--forbid` or `--rules` (an empty log would close every open alert): write the `--forbid`/`--rules` violations to this file as SARIF 2.1.0 (`WriteSARIF`), before the diagram is written, on every run (an empty results list when nothing breaks a rule) and with `--check`. Exit codes are unchanged. | | `--source` | `codegraph` | Where the graph comes from, in every mode. `codegraph` reads the index under `--path` (`CodegraphSource`); `snapshot:` reads a graph-assay snapshot v1 (`SnapshotSource`). Both implement `ArchSource` (`Symbols`, `FileEdges`), and everything after those two calls is shared, so `--forbid`, `--group-depth`, `--max-symbols` and `--embed --check` behave identically. `SnapshotSource` maps the snapshot onto the same `IndexRow`s the index read produces, keyed by the node's `qname` (the node id when it has none), so a snapshot exported from a codegraph index draws a byte-identical DOT (48 runs on three repos, Go, TypeScript and Python, up to 5000 symbols, canon and svg). That needs `FileEdgesFromIndexRows` to ignore row order (the index read returns SQLite plan order, a snapshot its file order): it takes each definition's targets by target file, then target id. A snapshot adds `-snapshot-` to the `--embed` marker id and default image name (`SnapshotMarkerSuffix`), so its diagram can share a doc with the codegraph one. `` is `subject.name` with every run of characters outside `[A-Za-z0-9._-]` replaced by `-`, trimmed, and capped at 40, since it lands in a filename, a markdown link and alt text; the same label names the snapshot in warnings. `--path`'s subpath (`EmbedPathSuffix`) is not added for a snapshot, whose graph doesn't come from `--path`. `UndrawnEdgeKindsWarning` names, with counts, any edge kind that is neither drawn nor known to be structural (`contains`, `extends`, `implements`, `decorates`), so another tool's kinds never drop out of the diagram and `--forbid` silently. `ArchSource.EmptyGraphWarning` words the blank-diagram warning for the source, and the `--limit` warning names the snapshot, so no message sends a snapshot user to codegraph. All three sources feed every mode. Every cheap flag check runs before the snapshot is read. In symbol mode and `--diff`, `CallSource` (`Resolve`, `Edges`, `Symbols`, `Wording`) stands where the codegraph CLI did: `CodegraphCalls` runs it as before, and `SnapshotCalls` answers `callers`/`callees --json` the way the codegraph fork does: lookup by exact name, or a qualified query (`.`, `/`, `::`, `#` all read as `.`) matched as a suffix of the qualified name, never a fuzzy hit; one definition group per (file, qualified name) with its own callers or callees over `CalleeEdgeKinds`, deduped by node, without the symbol itself; and a union capped at `--limit` with exact `total`/`truncated`. Both sources' neighbours are sorted (`SortSymbolsForEnumeration`) before drawing, because codegraph's edge query has no ORDER BY and a snapshot keeps its file's order. `Wording` keeps every symbol and `--diff` warning from sending a snapshot user to codegraph. With a snapshot, the symbol and `--diff` marker ids and image names get `-snapshot-`, and `--diff` keeps `--path`'s subdirectory suffix, since git still finds the changes there. Edge kinds the snapshot has but codeshot doesn't follow are named in every mode (`UnfollowedEdgeKindsWarning` outside `--architecture`). `IndexHealthWarning` (codegraph's unresolved-refs count) is skipped for a snapshot. `scip[:]` reads a SCIP index (`ScipSource`; default `<--path>/index.scip`). Its rule: document A depends on document B when A has an occurrence that is neither a definition nor an import, of a non-local symbol whose last descriptor isn't a namespace/package, defined in B ≠ A (to every such B). Package references are dropped because they are import-shaped and codegraph draws an import only alongside a call. Each (file, referenced symbol) pair is one unit of edge weight. `Symbols` is one `file` node per document: the edges are per file, so `--max-symbols` counts files (counting definitions spent the default 500 on struct fields and package clauses: codeshot's own index has 729), and a file that defines nothing still draws. Documents are sorted by path, and each document's definitions, references and the edge list are sorted, so the indexer's document and occurrence order never reaches the DOT. Documents sharing a path are one file split across messages and are merged. A document whose cleaned path leaves the project root is skipped; an empty, unclean or `.` path inside the root is an error. The marker suffix is `scip-` (`scipLabel`, not doubled for `scip-go`). `EmbedPathSuffix` is added to the image name (not the marker id, as for codegraph) for bare `--source scip`, which reads `<--path>/index.scip`, and not for `scip:`. `ScipSource.BudgetWarning` (the optional `budgetWarner` interface) words the `--max-symbols` cut in files. On codeshot itself, scip-go v0.2.8 vs codegraph em.41: 97 vs 88 file edges; SCIP's 11 extra are type and struct-field references (mostly `Node` fields reached through `type Node = codegraph.Node`), codegraph's 2 extra are interface dispatch (`arch.go` to the `ArchSource` implementations). In symbol mode and `--diff`, `NewScipCalls` turns `scipindex.Calls` into an in-memory snapshot and answers through `SnapshotCalls`, so lookup, grouping, `--limit` and the warnings are shared; only the phrase and `Wording` name the index. `Calls` draws a node for every non-local definition whose last descriptor is a method or type, and for a term that the indexer calls a function or method, that is a top-level constant or variable, or that has an enclosing range outside Go (scip-typescript ranges only function-valued variables; scip-go ranges every field and variable, measured on codeshot's own index and gorilla/mux). Functions, methods, types and those function-valued terms are callers: a reference's caller is the innermost enclosing range holding its position, compared by line and character (the range starting last, then ending first; end exclusive), counted from the definition's name line when the range starts above it (scip-go's range starts at the doc comment, scip-python's at the decorators), else the file node. A symbol defined more than once in one file (TypeScript overloads, nested Python functions scip-python gives one symbol) is one node there, and each of its ranges draws from it, so `--limit` counts it once. Imports, locals, namespaces, symbols defined outside the project and a definition's reference to itself draw nothing; each (caller, callee) is one `references` edge. A definition that should be a caller but has no enclosing range is counted in a warning; the references inside it are drawn from the ranged definition or file around it. Probe (2026-11-15) on codeshot at this branch, 60 functions, scip-go v0.2.8 vs codegraph em.8 symbol mode: 297 of 317 codegraph edges reproduced, 28 SCIP-only edges (type references, package variables); the 20 codegraph-only edges are its case-insensitive lookup and same-name interface linking. | | `--max-symbols` | `500` | `--architecture`: caps how many enumerated symbols have their edges included, applied client-side to the path-sorted enumeration; `SymbolBudgetWarning` prints a stderr note when it cuts. Must be a positive integer. **`--diff`/`--diff-ref` reuses the same flag for a differently-scoped budget**: it caps how many *changed, matched* symbols get probed for callers/callees (two calls each), not how many of the whole repo get enumerated — `enumerateAllSymbols` always fetches the full index first so filtering down to the changed files never loses a symbol to this cap before matching happens; `DiffSymbolBudgetWarning` prints the diff-scoped stderr note. Ignored in symbol mode. | | `--diff` | `false` | Switches to diff-scoped mode: diagrams the symbols codegraph attributes to files `git diff` (working tree vs `HEAD`, no ref) reports changed, each drawn as a bold root with its direct callers/callees fanned out — see `BuildDiffDot`/`RunDiffMode`. `MatchRootSymbols` excludes codegraph's `"kind":"file"` and `"kind":"import"` index entries from becoming roots (an import's text probed as a name can resolve to another symbol and borrow its edges) — otherwise a changed file itself would be drawn as a bold root, since enumeration deliberately keeps file entries for `--architecture`'s sake. Mutually exclusive with `--architecture` and the `` positional. `--depth`/`--max-depth-nodes`/`--group-depth` have no meaning here: `--group-depth` is rejected if passed, `--depth`/`--max-depth-nodes` unless left at their defaults. A diff with zero changed files skips the full-index enumeration entirely (it could only ever match nothing); with `--embed` (and not `--check`, which never writes and so has nothing to protect — see `handleEmptyRoots`) it refuses outright rather than rendering a blank diagram over a real, committed one — see `DiffEmbedRefusal`/`DiffEmbedRefusalNoSymbols` (the latter for the same zero-roots outcome when real changed files match no indexed symbol). A changed root with no callers/callees still draws (a lone box). Roots with no edges (`DiffEmptyRootsWarning`) and roots whose fetch was cut off by `--limit` (`DiffTruncationWarning`, decided by `ReadTruncation` as in symbol mode) are each reported once in aggregate rather than per root, to avoid stderr noise on a large diff. | diff --git a/USAGE.md b/USAGE.md index 48a4a39..51156f4 100644 --- a/USAGE.md +++ b/USAGE.md @@ -180,12 +180,15 @@ jobs: Each result sits in the depending file, at the first line where it calls or refers to the other file (the smallest line codegraph, the snapshot or the -SCIP index records), with the depended-on file as a related location. When no -source knows a line, the result points at line 1 of the file. The alert's -fingerprint comes from the rule and the two files, not the line, so moving the -call doesn't open a new alert. The file is written on every run, with an empty -list when nothing breaks a rule (which is what closes fixed alerts), and also -with `--check`. Paths are the ones in the diagram, so run from the repository +SCIP index records; the calling function's first line when only that is +known), with the depended-on file as a related location. When no source knows +a line, the result points at line 1 of the file. codeshot sets the alert's +fingerprint (`primaryLocationLineHash`, which GitHub uses to track an alert) +from the rule and the two files, not the line, so moving the call doesn't open +a new alert. The file is written on every run, with an empty list when nothing +breaks a rule (which is what closes fixed alerts), and also with `--check`. +`--sarif` needs `--forbid` or `--rules`: a run that checks no rule would +upload an empty list and close every open alert. Paths are the ones in the diagram, so run from the repository root (`--path .`) for them to match what GitHub checked out. ### Drawing from another tool's graph diff --git a/docs/architecture.svg b/docs/architecture.svg index 8e23dde..c747616 100644 --- a/docs/architecture.svg +++ b/docs/architecture.svg @@ -4,1528 +4,1535 @@ - - + + 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 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 - - -7 + + +8 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/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 - - -8 + + +10 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 + + +1 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 - - -1 + + +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/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/helpers_test.go - - -9 + + +9 internal/codeshot/arch_test.go->internal/codeshot/diff.go - - -2 + + +2 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/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/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 + + +1 internal/codeshot/output.go->internal/codeshot/diff.go - - -2 + + +2 - + 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/helpers_test.go - - -14 + + +14 internal/codeshot/diff_test.go->internal/codeshot/diff.go - - -16 + + +16 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/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/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/sarif_test.go->internal/codegraph/index.go - - -3 + + +5 + + + +internal/codeshot/sarif_test.go->internal/codeshot/arch.go + + +1 internal/codeshot/sarif_test.go->internal/codeshot/sources.go - - -1 + + +1 - + internal/codeshot/sarif_test.go->internal/codeshot/source_snapshot.go - - -1 + + +2 internal/codeshot/sarif_test.go->internal/codeshot/sarif.go - - -4 + + +9 internal/codeshot/sarif_test.go->internal/codeshot/helpers_test.go - - -4 + + +10 - + internal/codeshot/sarif_test.go->internal/snapshot/snapshot.go - - -1 + + +2 internal/codeshot/sarif_test.go->internal/codeshot/source_snapshot_test.go - - -1 + + +2 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/helpers_test.go - - -14 + + +14 - + internal/codeshot/source_snapshot_calls_test.go->internal/codeshot/diff.go - - -1 + + +1 - + 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/codegraph/index.go b/internal/codegraph/index.go index 7926617..3ca806f 100644 --- a/internal/codegraph/index.go +++ b/internal/codegraph/index.go @@ -169,9 +169,10 @@ type FilePair struct{ From, To string } // ReadSiteLines returns, for every pair of files with a callee edge between // them (imports and file-kind targets aside, as --architecture draws), the -// smallest line in From of such an edge: the edge's own line, or the calling -// node's start line when codegraph stored none. Read-only, with the same -// immutable retry as ReadIndexRows. +// smallest line in From of such an edge. A real edge line wins; only a pair +// whose edges carry no line falls back to the smallest calling node's start +// line. 0 counts as no line. Read-only, with the same immutable retry as +// ReadIndexRows. func ReadSiteLines(dbPath string) (map[FilePair]int, error) { lines, err := readSiteLines(indexURI(dbPath, false)) if err != nil && !IsSchemaError(err) && walIsEmpty(dbPath) { @@ -199,7 +200,8 @@ func readSiteLines(uri string) (map[FilePair]int, error) { for i, k := range kinds { args[i] = k } - rows, err := db.Query(`SELECT s.file_path, t.file_path, MIN(COALESCE(e.line, s.start_line)) + rows, err := db.Query(`SELECT s.file_path, t.file_path, + MIN(CASE WHEN e.line > 0 THEN e.line END), MIN(CASE WHEN s.start_line > 0 THEN s.start_line END) FROM edges e JOIN nodes s ON s.id = e.source JOIN nodes t ON t.id = e.target @@ -212,11 +214,14 @@ func readSiteLines(uri string) (map[FilePair]int, error) { out := map[FilePair]int{} for rows.Next() { var from, to sql.NullString - var line sql.NullInt64 - if err := rows.Scan(&from, &to, &line); err != nil { + var line, start sql.NullInt64 + if err := rows.Scan(&from, &to, &line, &start); err != nil { return nil, err } - if from.Valid && to.Valid && line.Valid && line.Int64 > 0 { + if !line.Valid { + line = start + } + if from.Valid && to.Valid && line.Valid { out[FilePair{From: from.String, To: to.String}] = int(line.Int64) } } diff --git a/internal/codegraph/index_test.go b/internal/codegraph/index_test.go index 8de628b..8a49f98 100644 --- a/internal/codegraph/index_test.go +++ b/internal/codegraph/index_test.go @@ -134,3 +134,39 @@ func TestReadSiteLinesTakesTheFirstCallSitePerFilePair(t *testing.T) { t.Errorf("got %v, want %v", got, want) } } + +// F3: a real call line beats the caller's start line, whatever the order, +// and a 0 is no line. +func TestReadSiteLinesPrefersARealCallLineAndIgnoresZero(t *testing.T) { + dbPath := filepath.Join(t.TempDir(), ".codegraph", "codegraph.db") + if err := os.MkdirAll(filepath.Dir(dbPath), 0o755); err != nil { + t.Fatal(err) + } + db, err := sql.Open("sqlite", dbPath) + if err != nil { + t.Fatal(err) + } + for _, q := range []string{ + `CREATE TABLE nodes (id TEXT PRIMARY KEY, kind TEXT, name TEXT, qualified_name TEXT NOT NULL, file_path TEXT, start_line INTEGER)`, + `CREATE TABLE edges (source TEXT, target TEXT, kind TEXT, line INTEGER)`, + `INSERT INTO nodes VALUES ('a1','function','A1','A1','a.go',40), ('a0','file','a.go','a.go','a.go',0), + ('b','function','B','B','b.go',1), ('c','function','C','C','c.go',1), ('d','function','D','D','d.go',1)`, + `INSERT INTO edges VALUES ('a1','b','calls',55), ('a1','b','references',NULL), + ('a0','c','calls',0), ('a1','c','calls',12), + ('a1','d','references',NULL)`, + } { + if _, err := db.Exec(q); err != nil { + t.Fatalf("%s: %v", q, err) + } + } + _ = db.Close() + got, err := ReadSiteLines(dbPath) + if err != nil { + t.Fatal(err) + } + for pair, want := range map[FilePair]int{{"a.go", "b.go"}: 55, {"a.go", "c.go"}: 12, {"a.go", "d.go"}: 40} { + if got[pair] != want { + t.Errorf("%v: got %d, want %d", pair, got[pair], want) + } + } +} diff --git a/internal/codeshot/cli.go b/internal/codeshot/cli.go index 1b7558f..dc89fe8 100644 --- a/internal/codeshot/cli.go +++ b/internal/codeshot/cli.go @@ -403,6 +403,11 @@ func run(args []string, stdout, stderr io.Writer) (int, error) { if !arch { return 0, &Exit{Code: 1, Stderr: "codeshot: --sarif only applies with --architecture (it reports --forbid and --rules violations)"} } + // An empty log closes every open alert, so a run that checks no + // rule must not write one (F6). + if len(rules) == 0 && rulesFile == nil { + return 0, &Exit{Code: 1, Stderr: "codeshot: --sarif needs --forbid or --rules: with no rule checked it would upload an empty log and close every open alert"} + } } embedFile, hasEmbed := p.str["embed"] if hasEmbed && embedFile == "" { diff --git a/internal/codeshot/sarif.go b/internal/codeshot/sarif.go index 24d8564..ed377c3 100644 --- a/internal/codeshot/sarif.go +++ b/internal/codeshot/sarif.go @@ -6,8 +6,12 @@ import ( "encoding/json" "fmt" "io" + "net/url" "os" + "path" + "path/filepath" "slices" + "strings" "github.com/inth3shadows/codeshot/internal/codegraph" "github.com/inth3shadows/codeshot/internal/snapshot" @@ -29,16 +33,25 @@ func (s CodegraphSource) SiteLines() (map[codegraph.FilePair]int, error) { return codegraph.ReadSiteLines(idx) } +// keepMin records line for k unless a smaller one is already there. +func keepMin(m map[codegraph.FilePair]int, k codegraph.FilePair, line int) { + if cur, ok := m[k]; !ok || line < cur { + m[k] = line + } +} + // SiteLines: the smallest line of a drawn-kind edge (not imports, not to a -// file node) between nodes in two files; a snapshot's line is optional. +// file node) between nodes in two files, as codegraph's ReadSiteLines: a +// real edge line wins, and a pair whose edges carry none falls back to the +// smallest caller start (a snapshot's line is optional, F4). func (s SnapshotSource) SiteLines() (map[codegraph.FilePair]int, error) { byID := make(map[string]snapshot.Node, len(s.Snap.Nodes)) for _, n := range s.Snap.Nodes { byID[n.ID] = n } - out := map[codegraph.FilePair]int{} + lines, starts := map[codegraph.FilePair]int{}, map[codegraph.FilePair]int{} for _, e := range s.Snap.Edges { - if e.Line == nil || *e.Line < 1 || e.Kind == "imports" || !slices.Contains(codegraph.CalleeEdgeKinds, e.Kind) { + if e.Kind == "imports" || !slices.Contains(codegraph.CalleeEdgeKinds, e.Kind) { continue } src, dst := byID[e.Src], byID[e.Dst] @@ -46,11 +59,18 @@ func (s SnapshotSource) SiteLines() (map[codegraph.FilePair]int, error) { continue } k := codegraph.FilePair{From: src.File, To: dst.File} - if cur, ok := out[k]; !ok || *e.Line < cur { - out[k] = *e.Line + if e.Line != nil && *e.Line > 0 { + keepMin(lines, k, *e.Line) + } else if src.Start > 0 { + keepMin(starts, k, src.Start) } } - return out, nil + for k, start := range starts { + if _, ok := lines[k]; !ok { + lines[k] = start + } + } + return lines, nil } func (s ScipSource) SiteLines() (map[codegraph.FilePair]int, error) { @@ -73,10 +93,7 @@ func (p prefixedSource) SiteLines() (map[codegraph.FilePair]int, error) { } out := make(map[codegraph.FilePair]int, len(lines)) for k, line := range lines { - r := codegraph.FilePair{From: p.rebase(k.From), To: p.rebase(k.To)} - if cur, ok := out[r]; !ok || line < cur { - out[r] = line - } + keepMin(out, codegraph.FilePair{From: p.rebase(k.From), To: p.rebase(k.To)}, line) } return out, nil } @@ -96,13 +113,11 @@ func fillSiteLines(vs []Violation, srcs []LabeledSource, stderr io.Writer) { } lines, err := sl.SiteLines() if err != nil { - warn(stderr, labelWarning(s.Label, fmt.Sprintf("codeshot: --sarif: could not read line numbers (%v); its findings point at line 1 of the file.", err))) + warn(stderr, siteLinesWarning(s.Label, err)) continue } for k, line := range lines { - if cur, ok := best[k]; !ok || line < cur { - best[k] = line - } + keepMin(best, k, line) } } for i := range vs { @@ -110,6 +125,36 @@ func fillSiteLines(vs []Violation, srcs []LabeledSource, stderr io.Writer) { } } +// siteLinesWarning: a source gave no line numbers (A4). An index from a +// codegraph build without the line columns is said plainly. +func siteLinesWarning(label string, err error) string { + what := "the graph source" + if label != "" { + what = label + } + why := err.Error() + if codegraph.IsSchemaError(err) { + why = "the codegraph index has no line columns; a newer codegraph build writes them" + } + return fmt.Sprintf("codeshot: --sarif: no line numbers from %s (%s); results point at line 1 of each file.", what, why) +} + +// sarifURI is a path as a SARIF artifact URI (F2): each segment +// percent-encoded, so a space, '#', '%' or a non-ASCII name survives a URI +// parser; an absolute path becomes a file URI. +func sarifURI(p string) string { + slash := filepath.ToSlash(p) + segs := strings.Split(slash, "/") + for i, s := range segs { + segs[i] = url.PathEscape(s) + } + enc := strings.Join(segs, "/") + if path.IsAbs(slash) { + return "file://" + enc + } + return enc +} + // SARIF rule ids, one per kind of rule. const ( sarifForbidRule = "codeshot/forbid" @@ -143,10 +188,16 @@ type sarifRule struct { Name string `json:"name"` ShortDescription sarifText `json:"shortDescription"` FullDescription sarifText `json:"fullDescription"` + Help sarifHelp `json:"help"` HelpURI string `json:"helpUri"` DefaultConfig sarifDefault `json:"defaultConfiguration"` } +type sarifHelp struct { + Text string `json:"text"` + Markdown string `json:"markdown"` +} + type sarifDefault struct { Level string `json:"level"` } @@ -196,18 +247,27 @@ func BuildSARIF(vs []Violation, version string) ([]byte, error) { ID: sarifForbidRule, Name: "ForbiddenDependency", ShortDescription: sarifText{"A file depends on a file a forbid rule keeps it from."}, FullDescription: sarifText{"A --forbid flag or a forbid rule in the --rules file says files matching FROM may not depend on files matching TO, and codeshot's graph has such an edge."}, - HelpURI: "https://github.com/inth3shadows/codeshot/blob/master/USAGE.md#enforcing-architecture-rules", - DefaultConfig: sarifDefault{"error"}, + Help: sarifHelp{ + Text: "Remove the dependency, move the code so the rule allows it, or add an allow exception to the --rules file if the dependency is intended.", + Markdown: "Remove the dependency, move the code so the rule allows it, or add an `allow` exception to the `--rules` file if the dependency is intended. See [Enforcing architecture rules](https://github.com/inth3shadows/codeshot/blob/master/USAGE.md#enforcing-architecture-rules).", + }, + HelpURI: "https://github.com/inth3shadows/codeshot/blob/master/USAGE.md#enforcing-architecture-rules", + DefaultConfig: sarifDefault{"error"}, }, { ID: sarifLayersRule, Name: "LayerViolation", ShortDescription: sarifText{"A file in a lower layer depends on a higher layer."}, FullDescription: sarifText{"The --rules file orders layers top to bottom; a layer may use itself and the layers below it, and this edge goes from a lower layer to a higher one."}, - HelpURI: "https://github.com/inth3shadows/codeshot/blob/master/USAGE.md#a-rules-file", - DefaultConfig: sarifDefault{"error"}, + Help: sarifHelp{ + Text: "A lower layer may not use a higher one. Move the code into the right layer, invert the dependency, or add an allow exception to the --rules file.", + Markdown: "A lower layer may not use a higher one. Move the code into the right layer, invert the dependency, or add an `allow` exception to the `--rules` file. See [A rules file](https://github.com/inth3shadows/codeshot/blob/master/USAGE.md#a-rules-file).", + }, + HelpURI: "https://github.com/inth3shadows/codeshot/blob/master/USAGE.md#a-rules-file", + DefaultConfig: sarifDefault{"error"}, }, } results := make([]sarifResult, 0, len(vs)) + seen := map[string]bool{} for _, v := range vs { id, idx := sarifForbidRule, 0 if v.Kind == "layers" { @@ -217,21 +277,29 @@ func BuildSARIF(vs []Violation, version string) ([]byte, error) { if line < 1 { line = 1 } - sum := sha256.Sum256([]byte(id + "\x00" + v.Rule + "\x00" + v.From + "\x00" + v.To)) + // GitHub keys alerts by primaryLocationLineHash and upload-sarif keeps + // one that is given (F1): the rule, its wording and the two files, + // never the line, so moving the call keeps the alert. + sum := sha256.Sum256([]byte(id + "\x00" + v.Rule + "\x00" + v.Breaks + "\x00" + v.From + "\x00" + v.To)) + fp := hex.EncodeToString(sum[:16]) + ":1" + if seen[fp] { + continue // the same rule twice on one edge is one result + } + seen[fp] = true related := 1 results = append(results, sarifResult{ RuleID: id, RuleIndex: idx, Level: "error", Message: sarifText{violationText(v)}, Locations: []sarifLocation{{PhysicalLocation: sarifPhysical{ - ArtifactLocation: sarifArtifact{URI: v.From}, + ArtifactLocation: sarifArtifact{URI: sarifURI(v.From)}, Region: &sarifRegion{StartLine: line}, }}}, RelatedLocations: []sarifLocation{{ ID: &related, - PhysicalLocation: sarifPhysical{ArtifactLocation: sarifArtifact{URI: v.To}}, + PhysicalLocation: sarifPhysical{ArtifactLocation: sarifArtifact{URI: sarifURI(v.To)}}, Message: &sarifText{"the file it depends on"}, }}, - PartialFingerprints: map[string]string{"codeshotEdge/v1": hex.EncodeToString(sum[:16])}, + PartialFingerprints: map[string]string{"primaryLocationLineHash": fp}, }) } log := sarifLog{ diff --git a/internal/codeshot/sarif_test.go b/internal/codeshot/sarif_test.go index cf44499..f66d94f 100644 --- a/internal/codeshot/sarif_test.go +++ b/internal/codeshot/sarif_test.go @@ -2,6 +2,7 @@ package codeshot import ( "encoding/json" + "errors" "os" "os/exec" "path/filepath" @@ -82,9 +83,9 @@ func TestBuildSARIFWritesOneResultPerViolation(t *testing.T) { t.Errorf("related: %v", rel) } fp := func(r map[string]any) string { - return r["partialFingerprints"].(map[string]any)["codeshotEdge/v1"].(string) + return r["partialFingerprints"].(map[string]any)["primaryLocationLineHash"].(string) } - if fp(r0) == fp(r1) || len(fp(r0)) != 32 { + if fp(r0) == fp(r1) || len(fp(r0)) != 34 { t.Errorf("fingerprints: %q %q", fp(r0), fp(r1)) } // The fingerprint ignores the line, so an alert survives the call moving. @@ -212,3 +213,124 @@ func TestCLISarifIsArchitectureOnly(t *testing.T) { t.Error("usage does not mention --sarif") } } + +// F1: GitHub keys alerts by primaryLocationLineHash; codeshot's own hash +// goes there, differs for two rules on one edge, ignores the line, and an +// exact duplicate result is written once. +func TestSARIFFingerprintIsThePrimaryLocationLineHash(t *testing.T) { + flag := Violation{Rule: "src/->lib/", From: "src/a.go", To: "lib/b.go", Weight: 1, Line: 3} + file := flag + file.Breaks = "forbid 'src/->lib/' in r.yaml" + data, err := BuildSARIF([]Violation{flag, file, flag}, "dev") + if err != nil { + t.Fatal(err) + } + res := sarifResults(t, decodeSARIF(t, data)) + if len(res) != 2 { + t.Fatalf("results: %d, want 2 (the exact duplicate dropped)", len(res)) + } + fp := func(r any) string { + v, _ := r.(map[string]any)["partialFingerprints"].(map[string]any)["primaryLocationLineHash"].(string) + return v + } + if fp(res[0]) == "" || fp(res[0]) == fp(res[1]) { + t.Errorf("fingerprints: %q %q", fp(res[0]), fp(res[1])) + } + wantMatch(t, `^[0-9a-f]{32}:1$`, fp(res[0])) +} + +// F2: uris are percent-encoded per segment; an absolute path is a file URI. +func TestSARIFURIsAreEncoded(t *testing.T) { + data, err := BuildSARIF([]Violation{{Rule: "a->b", From: "src/a b#c%20d é.go", To: "/abs/x [1].go"}}, "dev") + if err != nil { + t.Fatal(err) + } + r := sarifResults(t, decodeSARIF(t, data))[0].(map[string]any) + uri := r["locations"].([]any)[0].(map[string]any)["physicalLocation"].(map[string]any)["artifactLocation"].(map[string]any)["uri"] + rel := r["relatedLocations"].([]any)[0].(map[string]any)["physicalLocation"].(map[string]any)["artifactLocation"].(map[string]any)["uri"] + if uri != "src/a%20b%23c%2520d%20%C3%A9.go" { + t.Errorf("uri: %v", uri) + } + if rel != "file:///abs/x%20%5B1%5D.go" { + t.Errorf("related uri: %v", rel) + } +} + +// A3: every rule has help text. +func TestSARIFRulesHaveHelpText(t *testing.T) { + data, _ := BuildSARIF(nil, "dev") + rules := decodeSARIF(t, data)["runs"].([]any)[0].(map[string]any)["tool"].(map[string]any)["driver"].(map[string]any)["rules"].([]any) + for _, r := range rules { + h, _ := r.(map[string]any)["help"].(map[string]any) + if h == nil || h["text"] == "" || h["text"] == nil { + t.Errorf("%v: no help.text", r.(map[string]any)["id"]) + } + } +} + +// F4: a snapshot edge without a line falls back to its caller's start line, +// as codegraph does; a real line wins. +func TestSnapshotSiteLinesFallBackToTheCallersStart(t *testing.T) { + l := func(n int) *int { return &n } + snap := &snapshot.Snapshot{ + Nodes: []snapshot.Node{ + {ID: "1", Kind: "function", Name: "A", File: "a.go", Start: 40}, + {ID: "2", Kind: "function", Name: "B", File: "b.go", Start: 1}, + {ID: "3", Kind: "function", Name: "C", File: "c.go", Start: 1}, + }, + Edges: []snapshot.Edge{ + {Kind: "references", Src: "1", Dst: "2"}, + {Kind: "calls", Src: "1", Dst: "2", Line: l(55)}, + {Kind: "calls", Src: "1", Dst: "3"}, + }, + } + got, _ := SnapshotSource{Snap: snap}.SiteLines() + if got[codegraph.FilePair{From: "a.go", To: "b.go"}] != 55 || got[codegraph.FilePair{From: "a.go", To: "c.go"}] != 40 { + t.Errorf("got %v, want a->b 55, a->c 40", got) + } +} + +type failingLiner struct{ edgesSource } + +func (failingLiner) SiteLines() (map[codegraph.FilePair]int, error) { + return nil, errors.New("SQL logic error: no such column: e.line (1)") +} + +// A4: the warning names what failed, without a dangling "its". +func TestSiteLinesWarningNamesTheSource(t *testing.T) { + vs := []Violation{{From: "a.go", To: "b.go"}} + var stderr strings.Builder + fillSiteLines(vs, []LabeledSource{{Src: failingLiner{}}}, &stderr) + wantMatch(t, `^codeshot: --sarif: no line numbers from the graph source \(the codegraph index has no line columns; a newer codegraph build writes them\); results point at line 1 of each file\.`, stderr.String()) +} + +// F6 + T: --sarif needs rules; a write failure stops the run before the +// diagram; a stale --check still leaves the SARIF file. +func TestCLISarifNeedsRulesAndFailsCleanly(t *testing.T) { + wantRejected(t, `--sarif needs --forbid or --rules`, "--architecture", "--sarif", "x.sarif") + requireBins(t, "dot") + dir := t.TempDir() + snap := "snapshot:" + writeSnapshotFile(t, sarifSnapshot) + out := filepath.Join(dir, "a.dot") + code, _, stderr := runCLI("--architecture", "--source", snap, "--forbid", "src/->lib/", "--sarif", filepath.Join(dir, "missing", "x.sarif"), "--format", "dot", "--out", out) + if code != 1 { + t.Errorf("write failure: exit %d, want 1", code) + } + wantMatch(t, `could not write --sarif file`, stderr) + if _, err := os.Stat(out); err == nil { + t.Error("the diagram was written after the SARIF write failed") + } + + doc := filepath.Join(dir, "doc.md") + if err := os.WriteFile(doc, []byte("# Doc\n"), 0o644); err != nil { + t.Fatal(err) + } + sarif := filepath.Join(dir, "check.sarif") + code, _, _ = runCLI("--architecture", "--source", snap, "--forbid", "src/->lib/", "--sarif", sarif, "--format", "svg", "--embed", doc, "--check") + if code != 1 { + t.Errorf("stale --check: exit %d, want 1", code) + } + if data, err := os.ReadFile(sarif); err != nil || len(sarifResults(t, decodeSARIF(t, data))) != 1 { + t.Errorf("stale --check: SARIF not written with its one result (%v)", err) + } +} From 17b1e69fb2f1c4a59eca6dafa1051fd75dc15843 Mon Sep 17 00:00:00 2001 From: Eric Minish Date: Wed, 18 Nov 2026 21:25:54 -0500 Subject: [PATCH 4/4] fix: SARIF review round 2 (stable fingerprints, cut graphs, URIs) - V1: the fingerprint is the rule id, the rule and the two files; the --rules path as typed and the reason no longer reopen alerts. - V2: a --sarif run whose scan --max-symbols cut writes nothing and exits 1, since a partial log would close the alerts of violations past it. - V3: --sarif refuses a rules file that checks nothing. - V5: a ':' in a relative path's first segment is %3A; a Windows drive path is a file:///C:/ URI. - V6/V10/V11: an index without edge lines still gives start lines; the multi-source warning is about that source's results only; exact call lines beat start-line fallbacks across sources. --- README.md | 5 +- TECHNICAL.md | 4 +- USAGE.md | 14 +- docs/architecture.svg | 1672 +++++++++++++++--------------- internal/codegraph/index.go | 41 +- internal/codegraph/index_test.go | 37 +- internal/codeshot/arch.go | 11 +- internal/codeshot/cli.go | 5 + internal/codeshot/sarif.go | 83 +- internal/codeshot/sarif_test.go | 86 +- 10 files changed, 1060 insertions(+), 898 deletions(-) diff --git a/README.md b/README.md index 7cf2c85..076d888 100644 --- a/README.md +++ b/README.md @@ -125,8 +125,9 @@ so the scan takes about a second. Flags specific to this mode: [`.codeshot.yaml`](.codeshot.yaml). - `--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 `--forbid` or `--rules`; - written on every run, also when nothing breaks a rule. See + depending file that calls into the other. Needs a rule to check, and + refuses a scan `--max-symbols` cut (a partial log would close live + alerts); written on every run, also when nothing breaks a rule. See [USAGE.md](USAGE.md#code-scanning-alerts-with---sarif). - `--source snapshot:` — draw from a [graph-assay](https://github.com/inth3shadows/graph-assay) snapshot diff --git a/TECHNICAL.md b/TECHNICAL.md index f32e9ab..71507f3 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/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 path becomes `file://`), and `partialFingerprints.primaryLocationLineHash` = the first 16 bytes of SHA-256 over rule id, rule, its rules-file wording, from and to, plus `:1`. 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. `fillSiteLines` takes the smallest line any source gives a pair; 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/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. - **`internal/codeshot/arch.go`** — multi-source: `RunMultiArchitectureMode` runs `sourceFileEdges` (enumerate, `--max-symbols` cut, `FileEdges`, `AggregateFileEdges`) per `LabeledSource`, then `UnionFileEdges` merges them (first-seen order in `--source` order; `Weight` = the highest per-source weight, never a sum, since codegraph counts calls and SCIP references; `FileEdge.Seen` = each source's own weight). `finishArchitecture` is the shared tail (`--forbid`, rollup, warnings, DOT) for one source and many. `FileEdge.Full` = the sources that saw all of the edge. `RollupFileEdges` sums `Seen` per source, sets a group edge's weight to the highest per-source sum, and intersects `Full` over the file edges inside it, so a group edge is solid only when every source saw every file edge inside it. `BuildArchitectureDot` with `ArchOptions.Sources` (two or more) dashes an edge whose `Full` is shorter than the source list and labels it with each source's own weight (`seenList`, not the top weight: a group edge's top weight can come from a source that did not see all of it), adds a legend line, and with `Tooltips` (svg) gives each edge a `codegraph 3, scip-go 5` tooltip; with one source the DOT is byte-identical to before lists existed. `Violation.SeenBy` names the sources in the `--forbid` report. A source that found no edges while others did gets `SourceFoundNoEdgesWarning`; a blank union gets every source's own empty-graph warning, prefixed with its label (`labelWarning`), as do per-source budget cuts. @@ -229,7 +229,7 @@ No environment variables, and no config file read unless `--rules` names one. Al | `--group-depth` | unset (one node per file) | `--architecture`-only: rolls each file up into its first N directory segments and draws those as the graph's nodes, summing the weights of every file pair that collapses into the same group pair (`RollupFileEdges`). The answer to the per-file hairball that `--max-render` only half-solves: `--max-render` is lossy at *every* level (the least-busy files are dropped outright, and any edge touching one goes with them), while grouping is lossless at the *module* level specifically — every cross-module call still appears, drawn between directories instead of files. It is not lossless in total: calls that become intra-group are dropped exactly as same-file calls already are, so a grouped diagram's summed weights are legitimately lower (often far lower) than the per-file one's. That difference is the repo's intra-module traffic, and the docs say so, because a user reconciling the two pictures would otherwise read it as a weight-aggregation bug. Composable with `--max-render`, which then caps groups rather than files (`RenderTruncationNote` says `groups`). Must be a positive integer. Rejected — not silently ignored — outside `--architecture`: symbol mode and `--diff` have no file-level graph to roll up, so passing it there is always a mistake, and a silently-dropped flag reads as "grouping applied" in exactly the diagram you would then trust. Applied *after* the file edges are derived, never during, so this stays a pure view over the same data rather than a second scan mode. With `--embed` it claims its own marker id (`codeshot:arch-d`) and default image name rather than the plain `codeshot:arch` — the per-file and per-module pictures answer different questions, so embedding one must not silently overwrite the other's committed block; unset `--group-depth` keeps the original id. | | `--forbid` | unset (no rules) | `--architecture`-only, repeatable: `FROM->TO` architecture rules (`ParseForbidRule`; a side ending in `/` is a directory prefix, any other side one exact file, a leading `./` is stripped). `ForbiddenEdges` checks them against the per-file edges from `AggregateFileEdges`, *before* `RollupFileEdges` and `--max-render`: those are view choices, and a rule must not pass because the view hid the edge. Each violation is printed by `ForbidViolationReport` (heaviest first, with weight and rule) and drawn red (`#dc2626`, penwidth 1.8 — the one loud color in the muted house style) by `BuildArchitectureDot`'s `Violating` option; `ViolatingDrawnKeys` maps a per-file violation onto the drawn edge, the directory edge under `--group-depth` (one that rolls into a single group isn't drawn). `--max-render` is not overridden to force a violating edge into the picture; `HiddenViolationNote` counts the ones it leaves out, since the exit code already fails the run. With no violations the DOT is byte-identical to a run without `--forbid`, and `SVGStructure` ignores colour, so `--check` is unaffected either way. The diagram is still rendered and embedded, then the process exits 1. Malformed rules and use outside `--architecture` are rejected before any codegraph work. Exact/prefix matching was chosen over globs to keep it predictable; patterns are for the `--rules` file only. | | `--rules` | unset | `--architecture`-only: a YAML rules file (`version: 1`; `layers`, `forbid` with an optional `reason`, `allow`), read and validated before any graph work (`ReadRules`). Its rules join the `--forbid` flags and run at the same point, on the per-file edges before `--group-depth` and `--max-render`; an allow rule exempts an edge from every rule, flags included. A rules-file side may use `*`, `?` and `[...]` within one path segment, with `\` escaping; `**` is refused. `--forbid` flag sides stay literal. Not discovered automatically: a repo that already has a `.codeshot.yaml` is unaffected until `--rules` is passed. | -| `--sarif` | unset | `--architecture`-only, and only with `--forbid` or `--rules` (an empty log would close every open alert): write the `--forbid`/`--rules` violations to this file as SARIF 2.1.0 (`WriteSARIF`), before the diagram is written, on every run (an empty results list when nothing breaks a rule) and with `--check`. Exit codes are unchanged. | +| `--sarif` | unset | `--architecture`-only, and only with a rule to check (a `--forbid` flag, or a rules file with a forbid rule or two layers; an empty log would close every open alert). A scan `--max-symbols` cut writes no file and exits 1, since a partial log would close still-valid alerts. Writes the `--forbid`/`--rules` violations to this file as SARIF 2.1.0 (`WriteSARIF`), before the diagram is written, on every run (an empty results list when nothing breaks a rule) and with `--check`. Exit codes are unchanged. | | `--source` | `codegraph` | Where the graph comes from, in every mode. `codegraph` reads the index under `--path` (`CodegraphSource`); `snapshot:` reads a graph-assay snapshot v1 (`SnapshotSource`). Both implement `ArchSource` (`Symbols`, `FileEdges`), and everything after those two calls is shared, so `--forbid`, `--group-depth`, `--max-symbols` and `--embed --check` behave identically. `SnapshotSource` maps the snapshot onto the same `IndexRow`s the index read produces, keyed by the node's `qname` (the node id when it has none), so a snapshot exported from a codegraph index draws a byte-identical DOT (48 runs on three repos, Go, TypeScript and Python, up to 5000 symbols, canon and svg). That needs `FileEdgesFromIndexRows` to ignore row order (the index read returns SQLite plan order, a snapshot its file order): it takes each definition's targets by target file, then target id. A snapshot adds `-snapshot-` to the `--embed` marker id and default image name (`SnapshotMarkerSuffix`), so its diagram can share a doc with the codegraph one. `` is `subject.name` with every run of characters outside `[A-Za-z0-9._-]` replaced by `-`, trimmed, and capped at 40, since it lands in a filename, a markdown link and alt text; the same label names the snapshot in warnings. `--path`'s subpath (`EmbedPathSuffix`) is not added for a snapshot, whose graph doesn't come from `--path`. `UndrawnEdgeKindsWarning` names, with counts, any edge kind that is neither drawn nor known to be structural (`contains`, `extends`, `implements`, `decorates`), so another tool's kinds never drop out of the diagram and `--forbid` silently. `ArchSource.EmptyGraphWarning` words the blank-diagram warning for the source, and the `--limit` warning names the snapshot, so no message sends a snapshot user to codegraph. All three sources feed every mode. Every cheap flag check runs before the snapshot is read. In symbol mode and `--diff`, `CallSource` (`Resolve`, `Edges`, `Symbols`, `Wording`) stands where the codegraph CLI did: `CodegraphCalls` runs it as before, and `SnapshotCalls` answers `callers`/`callees --json` the way the codegraph fork does: lookup by exact name, or a qualified query (`.`, `/`, `::`, `#` all read as `.`) matched as a suffix of the qualified name, never a fuzzy hit; one definition group per (file, qualified name) with its own callers or callees over `CalleeEdgeKinds`, deduped by node, without the symbol itself; and a union capped at `--limit` with exact `total`/`truncated`. Both sources' neighbours are sorted (`SortSymbolsForEnumeration`) before drawing, because codegraph's edge query has no ORDER BY and a snapshot keeps its file's order. `Wording` keeps every symbol and `--diff` warning from sending a snapshot user to codegraph. With a snapshot, the symbol and `--diff` marker ids and image names get `-snapshot-`, and `--diff` keeps `--path`'s subdirectory suffix, since git still finds the changes there. Edge kinds the snapshot has but codeshot doesn't follow are named in every mode (`UnfollowedEdgeKindsWarning` outside `--architecture`). `IndexHealthWarning` (codegraph's unresolved-refs count) is skipped for a snapshot. `scip[:]` reads a SCIP index (`ScipSource`; default `<--path>/index.scip`). Its rule: document A depends on document B when A has an occurrence that is neither a definition nor an import, of a non-local symbol whose last descriptor isn't a namespace/package, defined in B ≠ A (to every such B). Package references are dropped because they are import-shaped and codegraph draws an import only alongside a call. Each (file, referenced symbol) pair is one unit of edge weight. `Symbols` is one `file` node per document: the edges are per file, so `--max-symbols` counts files (counting definitions spent the default 500 on struct fields and package clauses: codeshot's own index has 729), and a file that defines nothing still draws. Documents are sorted by path, and each document's definitions, references and the edge list are sorted, so the indexer's document and occurrence order never reaches the DOT. Documents sharing a path are one file split across messages and are merged. A document whose cleaned path leaves the project root is skipped; an empty, unclean or `.` path inside the root is an error. The marker suffix is `scip-` (`scipLabel`, not doubled for `scip-go`). `EmbedPathSuffix` is added to the image name (not the marker id, as for codegraph) for bare `--source scip`, which reads `<--path>/index.scip`, and not for `scip:`. `ScipSource.BudgetWarning` (the optional `budgetWarner` interface) words the `--max-symbols` cut in files. On codeshot itself, scip-go v0.2.8 vs codegraph em.41: 97 vs 88 file edges; SCIP's 11 extra are type and struct-field references (mostly `Node` fields reached through `type Node = codegraph.Node`), codegraph's 2 extra are interface dispatch (`arch.go` to the `ArchSource` implementations). In symbol mode and `--diff`, `NewScipCalls` turns `scipindex.Calls` into an in-memory snapshot and answers through `SnapshotCalls`, so lookup, grouping, `--limit` and the warnings are shared; only the phrase and `Wording` name the index. `Calls` draws a node for every non-local definition whose last descriptor is a method or type, and for a term that the indexer calls a function or method, that is a top-level constant or variable, or that has an enclosing range outside Go (scip-typescript ranges only function-valued variables; scip-go ranges every field and variable, measured on codeshot's own index and gorilla/mux). Functions, methods, types and those function-valued terms are callers: a reference's caller is the innermost enclosing range holding its position, compared by line and character (the range starting last, then ending first; end exclusive), counted from the definition's name line when the range starts above it (scip-go's range starts at the doc comment, scip-python's at the decorators), else the file node. A symbol defined more than once in one file (TypeScript overloads, nested Python functions scip-python gives one symbol) is one node there, and each of its ranges draws from it, so `--limit` counts it once. Imports, locals, namespaces, symbols defined outside the project and a definition's reference to itself draw nothing; each (caller, callee) is one `references` edge. A definition that should be a caller but has no enclosing range is counted in a warning; the references inside it are drawn from the ranged definition or file around it. Probe (2026-11-15) on codeshot at this branch, 60 functions, scip-go v0.2.8 vs codegraph em.8 symbol mode: 297 of 317 codegraph edges reproduced, 28 SCIP-only edges (type references, package variables); the 20 codegraph-only edges are its case-insensitive lookup and same-name interface linking. | | `--max-symbols` | `500` | `--architecture`: caps how many enumerated symbols have their edges included, applied client-side to the path-sorted enumeration; `SymbolBudgetWarning` prints a stderr note when it cuts. Must be a positive integer. **`--diff`/`--diff-ref` reuses the same flag for a differently-scoped budget**: it caps how many *changed, matched* symbols get probed for callers/callees (two calls each), not how many of the whole repo get enumerated — `enumerateAllSymbols` always fetches the full index first so filtering down to the changed files never loses a symbol to this cap before matching happens; `DiffSymbolBudgetWarning` prints the diff-scoped stderr note. Ignored in symbol mode. | | `--diff` | `false` | Switches to diff-scoped mode: diagrams the symbols codegraph attributes to files `git diff` (working tree vs `HEAD`, no ref) reports changed, each drawn as a bold root with its direct callers/callees fanned out — see `BuildDiffDot`/`RunDiffMode`. `MatchRootSymbols` excludes codegraph's `"kind":"file"` and `"kind":"import"` index entries from becoming roots (an import's text probed as a name can resolve to another symbol and borrow its edges) — otherwise a changed file itself would be drawn as a bold root, since enumeration deliberately keeps file entries for `--architecture`'s sake. Mutually exclusive with `--architecture` and the `` positional. `--depth`/`--max-depth-nodes`/`--group-depth` have no meaning here: `--group-depth` is rejected if passed, `--depth`/`--max-depth-nodes` unless left at their defaults. A diff with zero changed files skips the full-index enumeration entirely (it could only ever match nothing); with `--embed` (and not `--check`, which never writes and so has nothing to protect — see `handleEmptyRoots`) it refuses outright rather than rendering a blank diagram over a real, committed one — see `DiffEmbedRefusal`/`DiffEmbedRefusalNoSymbols` (the latter for the same zero-roots outcome when real changed files match no indexed symbol). A changed root with no callers/callees still draws (a lone box). Roots with no edges (`DiffEmptyRootsWarning`) and roots whose fetch was cut off by `--limit` (`DiffTruncationWarning`, decided by `ReadTruncation` as in symbol mode) are each reported once in aggregate rather than per root, to avoid stderr noise on a large diff. | diff --git a/USAGE.md b/USAGE.md index 51156f4..ffbe8c8 100644 --- a/USAGE.md +++ b/USAGE.md @@ -184,11 +184,17 @@ SCIP index records; the calling function's first line when only that is known), with the depended-on file as a related location. When no source knows a line, the result points at line 1 of the file. codeshot sets the alert's fingerprint (`primaryLocationLineHash`, which GitHub uses to track an alert) -from the rule and the two files, not the line, so moving the call doesn't open -a new alert. The file is written on every run, with an empty list when nothing +from the rule and the two files, not the line, the rules file's name or a +rule's `reason`, so moving the call or rewording a reason doesn't open a new +alert. (upload-sarif logs a warning per result that the fingerprint differs +from the one it would compute from the line's text; it keeps codeshot's.) The file is written on every run, with an empty list when nothing breaks a rule (which is what closes fixed alerts), and also with `--check`. -`--sarif` needs `--forbid` or `--rules`: a run that checks no rule would -upload an empty list and close every open alert. Paths are the ones in the diagram, so run from the repository +`--sarif` needs a rule to check (a `--forbid` flag, or a rules file with a +forbid rule or at least two layers): a run that checks none would upload an +empty list and close every open alert. For the same reason, a `--sarif` run +whose scan `--max-symbols` cut writes no file and exits 1, naming the +`--max-symbols` to rerun with: a partial list would close the alerts of +violations past the cut. Paths are the ones in the diagram, so run from the repository root (`--path .`) for them to match what GitHub checked out. ### Drawing from another tool's graph diff --git a/docs/architecture.svg b/docs/architecture.svg index c747616..765ac8d 100644 --- a/docs/architecture.svg +++ b/docs/architecture.svg @@ -4,1535 +4,1549 @@ - - + + 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 - - -8 + + +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/arch.go->internal/codeshot/diff.go + + +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 - - -10 + + +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 - - -1 + + +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/diff.go->internal/codegraph/codegraph.go + + +4 + + + +internal/codeshot/diff.go->internal/codeshot/arch.go + + +3 + + + +internal/codeshot/diff.go->internal/codeshot/dot.go + + +1 + + + +internal/codeshot/diff.go->internal/codeshot/graph.go + + +7 + + + +internal/codeshot/diff.go->internal/codeshot/warnings.go + + +12 + + + +internal/codeshot/diff.go->internal/codeshot/callsource.go + + +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 - - - -internal/codeshot/arch_test.go->internal/codeshot/helpers_test.go - - -9 + + +1 - + internal/codeshot/arch_test.go->internal/codeshot/diff.go - - -2 + + +2 + + + +internal/codeshot/arch_test.go->internal/codeshot/helpers_test.go + + +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 - - - -internal/codeshot/diff.go->internal/codegraph/codegraph.go - - -4 - - - -internal/codeshot/diff.go->internal/codeshot/arch.go - - -3 - - - -internal/codeshot/diff.go->internal/codeshot/dot.go - - -1 - - - -internal/codeshot/diff.go->internal/codeshot/graph.go - - -7 - - - -internal/codeshot/diff.go->internal/codeshot/warnings.go - - -12 - - - -internal/codeshot/diff.go->internal/codeshot/callsource.go - - -4 + + +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 + + +1 - + internal/codeshot/output.go->internal/codeshot/diff.go - - -2 + + +2 - + 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 - - - -internal/codeshot/diff_test.go->internal/codeshot/helpers_test.go - - -14 + + +6 - + internal/codeshot/diff_test.go->internal/codeshot/diff.go - - -16 + + +16 + + + +internal/codeshot/diff_test.go->internal/codeshot/helpers_test.go + + +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/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/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/sarif_test.go->internal/codegraph/index.go - - -5 + + +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 - - -9 + + +12 - + internal/codeshot/sarif_test.go->internal/codeshot/helpers_test.go - - -10 + + +15 - + internal/codeshot/sarif_test.go->internal/snapshot/snapshot.go - - -2 + + +2 + + + +internal/codeshot/sarif_test.go->internal/codeshot/rules_test.go + + +1 - + internal/codeshot/sarif_test.go->internal/codeshot/source_snapshot_test.go - - -2 + + +3 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 - - - -internal/codeshot/source_snapshot_calls_test.go->internal/codeshot/helpers_test.go - - -14 + + +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 - + 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/codegraph/index.go b/internal/codegraph/index.go index 3ca806f..a2ddb2c 100644 --- a/internal/codegraph/index.go +++ b/internal/codegraph/index.go @@ -167,23 +167,38 @@ var ErrNoIdentity = errors.New("symbols carry no qualifiedName") // FilePair is a (from file, to file) dependency. type FilePair struct{ From, To string } +// SiteLine is a dependency's first line in its From file. Exact: a call or +// reference line; otherwise the calling node's start line, a fallback. +type SiteLine struct { + Line int + Exact bool +} + // ReadSiteLines returns, for every pair of files with a callee edge between // them (imports and file-kind targets aside, as --architecture draws), the // smallest line in From of such an edge. A real edge line wins; only a pair // whose edges carry no line falls back to the smallest calling node's start -// line. 0 counts as no line. Read-only, with the same immutable retry as +// line. 0 counts as no line. An index whose edges table has no line column +// still gives the fallback. Read-only, with the same immutable retry as // ReadIndexRows. -func ReadSiteLines(dbPath string) (map[FilePair]int, error) { - lines, err := readSiteLines(indexURI(dbPath, false)) +func ReadSiteLines(dbPath string) (map[FilePair]SiteLine, error) { + read := func(uri string) (map[FilePair]SiteLine, error) { + lines, err := readSiteLines(uri, "e.line") + if IsSchemaError(err) && strings.Contains(err.Error(), "line") { + lines, err = readSiteLines(uri, "NULL") // V6: no edges.line + } + return lines, err + } + lines, err := read(indexURI(dbPath, false)) if err != nil && !IsSchemaError(err) && walIsEmpty(dbPath) { - if retry, rerr := readSiteLines(indexURI(dbPath, true)); rerr == nil { + if retry, rerr := read(indexURI(dbPath, true)); rerr == nil { return retry, nil } } return lines, err } -func readSiteLines(uri string) (map[FilePair]int, error) { +func readSiteLines(uri, edgeLine string) (map[FilePair]SiteLine, error) { db, err := sql.Open("sqlite", uri) if err != nil { return nil, err @@ -201,7 +216,7 @@ func readSiteLines(uri string) (map[FilePair]int, error) { args[i] = k } rows, err := db.Query(`SELECT s.file_path, t.file_path, - MIN(CASE WHEN e.line > 0 THEN e.line END), MIN(CASE WHEN s.start_line > 0 THEN s.start_line END) + MIN(CASE WHEN `+edgeLine+` > 0 THEN `+edgeLine+` END), MIN(CASE WHEN s.start_line > 0 THEN s.start_line END) FROM edges e JOIN nodes s ON s.id = e.source JOIN nodes t ON t.id = e.target @@ -211,18 +226,22 @@ func readSiteLines(uri string) (map[FilePair]int, error) { return nil, err } defer func() { _ = rows.Close() }() - out := map[FilePair]int{} + out := map[FilePair]SiteLine{} for rows.Next() { var from, to sql.NullString var line, start sql.NullInt64 if err := rows.Scan(&from, &to, &line, &start); err != nil { return nil, err } - if !line.Valid { - line = start + if !from.Valid || !to.Valid { + continue } - if from.Valid && to.Valid && line.Valid { - out[FilePair{From: from.String, To: to.String}] = int(line.Int64) + k := FilePair{From: from.String, To: to.String} + switch { + case line.Valid: + out[k] = SiteLine{Line: int(line.Int64), Exact: true} + case start.Valid: + out[k] = SiteLine{Line: int(start.Int64)} } } return out, rows.Err() diff --git a/internal/codegraph/index_test.go b/internal/codegraph/index_test.go index 8a49f98..bc36e12 100644 --- a/internal/codegraph/index_test.go +++ b/internal/codegraph/index_test.go @@ -130,7 +130,7 @@ func TestReadSiteLinesTakesTheFirstCallSitePerFilePair(t *testing.T) { t.Fatal(err) } want := map[FilePair]int{{From: "a.go", To: "b.go"}: 12, {From: "a.go", To: "c.go"}: 40} - if len(got) != len(want) || got[FilePair{"a.go", "b.go"}] != 12 || got[FilePair{"a.go", "c.go"}] != 40 { + if len(got) != len(want) || got[FilePair{"a.go", "b.go"}] != (SiteLine{12, true}) || got[FilePair{"a.go", "c.go"}] != (SiteLine{40, false}) { t.Errorf("got %v, want %v", got, want) } } @@ -164,9 +164,40 @@ func TestReadSiteLinesPrefersARealCallLineAndIgnoresZero(t *testing.T) { if err != nil { t.Fatal(err) } - for pair, want := range map[FilePair]int{{"a.go", "b.go"}: 55, {"a.go", "c.go"}: 12, {"a.go", "d.go"}: 40} { + for pair, want := range map[FilePair]SiteLine{{"a.go", "b.go"}: {55, true}, {"a.go", "c.go"}: {12, true}, {"a.go", "d.go"}: {40, false}} { if got[pair] != want { - t.Errorf("%v: got %d, want %d", pair, got[pair], want) + t.Errorf("%v: got %v, want %v", pair, got[pair], want) } } } + +// V6: an index with node start lines but no edge line column still gives +// the start-line fallback. +func TestReadSiteLinesFallsBackWhenEdgesHaveNoLineColumn(t *testing.T) { + dbPath := filepath.Join(t.TempDir(), ".codegraph", "codegraph.db") + if err := os.MkdirAll(filepath.Dir(dbPath), 0o755); err != nil { + t.Fatal(err) + } + db, err := sql.Open("sqlite", dbPath) + if err != nil { + t.Fatal(err) + } + for _, q := range []string{ + `CREATE TABLE nodes (id TEXT PRIMARY KEY, kind TEXT, name TEXT, qualified_name TEXT NOT NULL, file_path TEXT, start_line INTEGER)`, + `CREATE TABLE edges (source TEXT, target TEXT, kind TEXT)`, + `INSERT INTO nodes VALUES ('a','function','A','A','a.go',7), ('b','function','B','B','b.go',1)`, + `INSERT INTO edges VALUES ('a','b','calls')`, + } { + if _, err := db.Exec(q); err != nil { + t.Fatalf("%s: %v", q, err) + } + } + _ = db.Close() + got, err := ReadSiteLines(dbPath) + if err != nil { + t.Fatal(err) + } + if got[FilePair{"a.go", "b.go"}] != (SiteLine{7, false}) { + t.Errorf("got %v, want a.go -> b.go at start line 7", got) + } +} diff --git a/internal/codeshot/arch.go b/internal/codeshot/arch.go index 5c552d6..fb762b1 100644 --- a/internal/codeshot/arch.go +++ b/internal/codeshot/arch.go @@ -541,7 +541,7 @@ func (s CodegraphSource) EmptyGraphWarning() string { return EmptyArchitectureWa // RunArchitectureMode builds the file-level graph and checks --forbid rules. func RunArchitectureMode(src ArchSource, p ArchParams, stderr io.Writer) (string, []Violation, error) { - rawFileEdges, err := sourceFileEdges(src, p.MaxSymbols, "", stderr) + rawFileEdges, err := sourceFileEdges(src, p.MaxSymbols, "", p.SiteLines, stderr) if err != nil { return "", nil, err } @@ -568,7 +568,7 @@ func RunMultiArchitectureMode(srcs []LabeledSource, p ArchParams, stderr io.Writ perSource := make([][]FileEdge, len(srcs)) for i, s := range srcs { labels[i] = s.Label - edges, err := sourceFileEdges(s.Src, p.MaxSymbols, s.Label, stderr) + edges, err := sourceFileEdges(s.Src, p.MaxSymbols, s.Label, p.SiteLines, stderr) if err != nil { return "", nil, labelError(s.Label, err) } @@ -597,11 +597,16 @@ func RunMultiArchitectureMode(srcs []LabeledSource, p ArchParams, stderr io.Writ // sourceFileEdges enumerates one source's symbols, applies --max-symbols and // aggregates its callee edges into file edges. A non-empty label prefixes the // budget warning (multi-source runs). -func sourceFileEdges(src ArchSource, maxSymbols int, label string, stderr io.Writer) ([]FileEdge, error) { +func sourceFileEdges(src ArchSource, maxSymbols int, label string, refuseCut bool, stderr io.Writer) ([]FileEdge, error) { symbols, err := src.Symbols() if err != nil { return nil, err } + if len(symbols) > maxSymbols && refuseCut { + // V2: a partial log would close the alerts of violations past the + // cut, which are still in the code. + return nil, &Exit{Code: 1, Stderr: labelWarning(label, fmt.Sprintf("codeshot: --sarif: the scan stopped at --max-symbols %d of %d, and a partial log would close the alerts of violations past the cut; rerun with --max-symbols %d or more. No SARIF file was written.", maxSymbols, len(symbols), len(symbols)))} + } if len(symbols) > maxSymbols { symbols = symbols[:maxSymbols] msg := SymbolBudgetWarning(maxSymbols) diff --git a/internal/codeshot/cli.go b/internal/codeshot/cli.go index dc89fe8..f58e0e4 100644 --- a/internal/codeshot/cli.go +++ b/internal/codeshot/cli.go @@ -408,6 +408,11 @@ func run(args []string, stdout, stderr io.Writer) (int, error) { if len(rules) == 0 && rulesFile == nil { return 0, &Exit{Code: 1, Stderr: "codeshot: --sarif needs --forbid or --rules: with no rule checked it would upload an empty log and close every open alert"} } + // V3: a rules file with no forbid rule and fewer than two layers + // can't flag anything either. + if len(rules) == 0 && len(rulesFile.Forbid) == 0 && len(rulesFile.Layers) < 2 { + return 0, &Exit{Code: 1, Stderr: fmt.Sprintf("codeshot: --sarif needs a rule to check: '%s' has no forbid rule and fewer than two layers, so the log would be empty and close every open alert", rulesFile.File)} + } } embedFile, hasEmbed := p.str["embed"] if hasEmbed && embedFile == "" { diff --git a/internal/codeshot/sarif.go b/internal/codeshot/sarif.go index ed377c3..07dd799 100644 --- a/internal/codeshot/sarif.go +++ b/internal/codeshot/sarif.go @@ -22,10 +22,10 @@ import ( // for every file pair it knows. Asked only when --sarif needs line numbers // for violations, so the diagram path never pays for it. type SiteLiner interface { - SiteLines() (map[codegraph.FilePair]int, error) + SiteLines() (map[codegraph.FilePair]codegraph.SiteLine, error) } -func (s CodegraphSource) SiteLines() (map[codegraph.FilePair]int, error) { +func (s CodegraphSource) SiteLines() (map[codegraph.FilePair]codegraph.SiteLine, error) { idx, err := codegraph.FindIndex(s.RepoPath) if err != nil { return nil, err @@ -33,10 +33,12 @@ func (s CodegraphSource) SiteLines() (map[codegraph.FilePair]int, error) { return codegraph.ReadSiteLines(idx) } -// keepMin records line for k unless a smaller one is already there. -func keepMin(m map[codegraph.FilePair]int, k codegraph.FilePair, line int) { - if cur, ok := m[k]; !ok || line < cur { - m[k] = line +// keepBest records l for k unless a better one is there: an exact line +// beats a start-line fallback (V11), then the smaller line wins. +func keepBest(m map[codegraph.FilePair]codegraph.SiteLine, k codegraph.FilePair, l codegraph.SiteLine) { + cur, ok := m[k] + if !ok || l.Exact && !cur.Exact || l.Exact == cur.Exact && l.Line < cur.Line { + m[k] = l } } @@ -44,12 +46,12 @@ func keepMin(m map[codegraph.FilePair]int, k codegraph.FilePair, line int) { // file node) between nodes in two files, as codegraph's ReadSiteLines: a // real edge line wins, and a pair whose edges carry none falls back to the // smallest caller start (a snapshot's line is optional, F4). -func (s SnapshotSource) SiteLines() (map[codegraph.FilePair]int, error) { +func (s SnapshotSource) SiteLines() (map[codegraph.FilePair]codegraph.SiteLine, error) { byID := make(map[string]snapshot.Node, len(s.Snap.Nodes)) for _, n := range s.Snap.Nodes { byID[n.ID] = n } - lines, starts := map[codegraph.FilePair]int{}, map[codegraph.FilePair]int{} + out := map[codegraph.FilePair]codegraph.SiteLine{} for _, e := range s.Snap.Edges { if e.Kind == "imports" || !slices.Contains(codegraph.CalleeEdgeKinds, e.Kind) { continue @@ -60,29 +62,24 @@ func (s SnapshotSource) SiteLines() (map[codegraph.FilePair]int, error) { } k := codegraph.FilePair{From: src.File, To: dst.File} if e.Line != nil && *e.Line > 0 { - keepMin(lines, k, *e.Line) + keepBest(out, k, codegraph.SiteLine{Line: *e.Line, Exact: true}) } else if src.Start > 0 { - keepMin(starts, k, src.Start) + keepBest(out, k, codegraph.SiteLine{Line: src.Start}) } } - for k, start := range starts { - if _, ok := lines[k]; !ok { - lines[k] = start - } - } - return lines, nil + return out, nil } -func (s ScipSource) SiteLines() (map[codegraph.FilePair]int, error) { - out := map[codegraph.FilePair]int{} +func (s ScipSource) SiteLines() (map[codegraph.FilePair]codegraph.SiteLine, error) { + out := map[codegraph.FilePair]codegraph.SiteLine{} for k, line := range s.Index.RefLines() { - out[codegraph.FilePair{From: k[0], To: k[1]}] = line + out[codegraph.FilePair{From: k[0], To: k[1]}] = codegraph.SiteLine{Line: line, Exact: true} } return out, nil } // SiteLines rebases the inner source's pairs the way FileEdges does. -func (p prefixedSource) SiteLines() (map[codegraph.FilePair]int, error) { +func (p prefixedSource) SiteLines() (map[codegraph.FilePair]codegraph.SiteLine, error) { sl, ok := p.Src.(SiteLiner) if !ok { return nil, nil @@ -91,9 +88,9 @@ func (p prefixedSource) SiteLines() (map[codegraph.FilePair]int, error) { if err != nil { return nil, err } - out := make(map[codegraph.FilePair]int, len(lines)) - for k, line := range lines { - keepMin(out, codegraph.FilePair{From: p.rebase(k.From), To: p.rebase(k.To)}, line) + out := make(map[codegraph.FilePair]codegraph.SiteLine, len(lines)) + for k, l := range lines { + keepBest(out, codegraph.FilePair{From: p.rebase(k.From), To: p.rebase(k.To)}, l) } return out, nil } @@ -105,7 +102,7 @@ func fillSiteLines(vs []Violation, srcs []LabeledSource, stderr io.Writer) { if len(vs) == 0 { return } - best := map[codegraph.FilePair]int{} + best := map[codegraph.FilePair]codegraph.SiteLine{} for _, s := range srcs { sl, ok := s.Src.(SiteLiner) if !ok { @@ -116,12 +113,12 @@ func fillSiteLines(vs []Violation, srcs []LabeledSource, stderr io.Writer) { warn(stderr, siteLinesWarning(s.Label, err)) continue } - for k, line := range lines { - keepMin(best, k, line) + for k, l := range lines { + keepBest(best, k, l) } } for i := range vs { - vs[i].Line = best[codegraph.FilePair{From: vs[i].From, To: vs[i].To}] + vs[i].Line = best[codegraph.FilePair{From: vs[i].From, To: vs[i].To}].Line } } @@ -136,6 +133,10 @@ func siteLinesWarning(label string, err error) string { if codegraph.IsSchemaError(err) { why = "the codegraph index has no line columns; a newer codegraph build writes them" } + if label != "" { + // Another source may know those lines (V10). + return labelWarning(label, fmt.Sprintf("codeshot: --sarif: no line numbers from %s (%s); results only it knows of point at line 1 of their file.", what, why)) + } return fmt.Sprintf("codeshot: --sarif: no line numbers from %s (%s); results point at line 1 of each file.", what, why) } @@ -143,16 +144,30 @@ func siteLinesWarning(label string, err error) string { // percent-encoded, so a space, '#', '%' or a non-ASCII name survives a URI // parser; an absolute path becomes a file URI. func sarifURI(p string) string { - slash := filepath.ToSlash(p) + slash := strings.ReplaceAll(filepath.ToSlash(p), "\\", "/") + drive := len(slash) >= 3 && slash[1] == ':' && slash[2] == '/' && + (slash[0] >= 'A' && slash[0] <= 'Z' || slash[0] >= 'a' && slash[0] <= 'z') segs := strings.Split(slash, "/") for i, s := range segs { + if i == 0 && drive { + continue // "C:" stays as is in file:///C:/... + } segs[i] = url.PathEscape(s) } enc := strings.Join(segs, "/") - if path.IsAbs(slash) { + switch { + case drive: + return "file:///" + enc // V5: a Windows drive path is absolute + case path.IsAbs(slash): return "file://" + enc } - return enc + // V5: a ':' in a relative path's first segment would read as a scheme. + first, rest, _ := strings.Cut(enc, "/") + first = strings.ReplaceAll(first, ":", "%3A") + if rest != "" { + return first + "/" + rest + } + return first } // SARIF rule ids, one per kind of rule. @@ -278,9 +293,11 @@ func BuildSARIF(vs []Violation, version string) ([]byte, error) { line = 1 } // GitHub keys alerts by primaryLocationLineHash and upload-sarif keeps - // one that is given (F1): the rule, its wording and the two files, - // never the line, so moving the call keeps the alert. - sum := sha256.Sum256([]byte(id + "\x00" + v.Rule + "\x00" + v.Breaks + "\x00" + v.From + "\x00" + v.To)) + // one that is given (F1): the rule and the two files, never the line, + // so moving the call keeps the alert. + // Not Breaks: it holds the --rules path as typed and the reason, and + // a rename or a reworded reason must not reopen every alert (V1). + sum := sha256.Sum256([]byte(id + "\x00" + v.Rule + "\x00" + v.From + "\x00" + v.To)) fp := hex.EncodeToString(sum[:16]) + ":1" if seen[fp] { continue // the same rule twice on one edge is one result diff --git a/internal/codeshot/sarif_test.go b/internal/codeshot/sarif_test.go index f66d94f..0d72e6f 100644 --- a/internal/codeshot/sarif_test.go +++ b/internal/codeshot/sarif_test.go @@ -132,17 +132,24 @@ func TestSnapshotSiteLinesTakeTheSmallestDrawnKindLine(t *testing.T) { }, } got, _ := SnapshotSource{Snap: snap}.SiteLines() - if len(got) != 1 || got[codegraph.FilePair{From: "a.go", To: "b.go"}] != 8 { + if len(got) != 1 || got[codegraph.FilePair{From: "a.go", To: "b.go"}] != (codegraph.SiteLine{Line: 8, Exact: true}) { t.Errorf("got %v, want only a.go -> b.go at 8", got) } } type linedSource struct { edgesSource - lines map[codegraph.FilePair]int + lines map[codegraph.FilePair]int + inexact bool // the lines are start-line fallbacks } -func (s linedSource) SiteLines() (map[codegraph.FilePair]int, error) { return s.lines, nil } +func (s linedSource) SiteLines() (map[codegraph.FilePair]codegraph.SiteLine, error) { + out := map[codegraph.FilePair]codegraph.SiteLine{} + for k, l := range s.lines { + out[k] = codegraph.SiteLine{Line: l, Exact: !s.inexact} + } + return out, nil +} func TestFillSiteLinesTakesTheSmallestLineAcrossSourcesAndRebases(t *testing.T) { a := linedSource{lines: map[codegraph.FilePair]int{{From: "sub/a.go", To: "sub/b.go"}: 9}} @@ -214,20 +221,23 @@ func TestCLISarifIsArchitectureOnly(t *testing.T) { } } -// F1: GitHub keys alerts by primaryLocationLineHash; codeshot's own hash -// goes there, differs for two rules on one edge, ignores the line, and an -// exact duplicate result is written once. +// F1/V1: GitHub keys alerts by primaryLocationLineHash; codeshot's own hash +// goes there, from the rule id, the rule and the two files only: not the +// line, not the rules-file path as typed, not the reason. The same rule +// twice on one edge (a flag and the file) is one result; a layer violation +// on that edge is another. func TestSARIFFingerprintIsThePrimaryLocationLineHash(t *testing.T) { flag := Violation{Rule: "src/->lib/", From: "src/a.go", To: "lib/b.go", Weight: 1, Line: 3} file := flag - file.Breaks = "forbid 'src/->lib/' in r.yaml" - data, err := BuildSARIF([]Violation{flag, file, flag}, "dev") + file.Breaks = "forbid 'src/->lib/' in r.yaml (why)" + layer := Violation{Rule: "src->lib", From: "src/a.go", To: "lib/b.go", Weight: 1, Kind: "layers", Breaks: "the layers in r.yaml (...)"} + data, err := BuildSARIF([]Violation{flag, file, flag, layer}, "dev") if err != nil { t.Fatal(err) } res := sarifResults(t, decodeSARIF(t, data)) if len(res) != 2 { - t.Fatalf("results: %d, want 2 (the exact duplicate dropped)", len(res)) + t.Fatalf("results: %d, want 2 (the forbid once, the layer once)", len(res)) } fp := func(r any) string { v, _ := r.(map[string]any)["partialFingerprints"].(map[string]any)["primaryLocationLineHash"].(string) @@ -237,6 +247,13 @@ func TestSARIFFingerprintIsThePrimaryLocationLineHash(t *testing.T) { t.Errorf("fingerprints: %q %q", fp(res[0]), fp(res[1])) } wantMatch(t, `^[0-9a-f]{32}:1$`, fp(res[0])) + // The rules file spelt ./r.yaml, a reworded reason: the same alert. + moved := file + moved.Breaks = "forbid 'src/->lib/' in ./r.yaml (reworded)" + again, _ := BuildSARIF([]Violation{moved}, "dev") + if fp(sarifResults(t, decodeSARIF(t, again))[0]) != fp(res[0]) { + t.Error("the fingerprint depends on the rules-file path or the reason") + } } // F2: uris are percent-encoded per segment; an absolute path is a file URI. @@ -254,6 +271,12 @@ func TestSARIFURIsAreEncoded(t *testing.T) { if rel != "file:///abs/x%20%5B1%5D.go" { t.Errorf("related uri: %v", rel) } + // V5: a ':' in the first segment is not a scheme; a drive path is absolute. + for p, want := range map[string]string{"a:b.go": "a%3Ab.go", "x/a:b.go": "x/a:b.go", "C:/repo/a.go": "file:///C:/repo/a.go", `C:\repo\a.go`: "file:///C:/repo/a.go"} { + if got := sarifURI(p); got != want { + t.Errorf("sarifURI(%q) = %q, want %q", p, got, want) + } + } } // A3: every rule has help text. @@ -285,14 +308,14 @@ func TestSnapshotSiteLinesFallBackToTheCallersStart(t *testing.T) { }, } got, _ := SnapshotSource{Snap: snap}.SiteLines() - if got[codegraph.FilePair{From: "a.go", To: "b.go"}] != 55 || got[codegraph.FilePair{From: "a.go", To: "c.go"}] != 40 { + if got[codegraph.FilePair{From: "a.go", To: "b.go"}] != (codegraph.SiteLine{Line: 55, Exact: true}) || got[codegraph.FilePair{From: "a.go", To: "c.go"}] != (codegraph.SiteLine{Line: 40}) { t.Errorf("got %v, want a->b 55, a->c 40", got) } } type failingLiner struct{ edgesSource } -func (failingLiner) SiteLines() (map[codegraph.FilePair]int, error) { +func (failingLiner) SiteLines() (map[codegraph.FilePair]codegraph.SiteLine, error) { return nil, errors.New("SQL logic error: no such column: e.line (1)") } @@ -334,3 +357,44 @@ func TestCLISarifNeedsRulesAndFailsCleanly(t *testing.T) { t.Errorf("stale --check: SARIF not written with its one result (%v)", err) } } + +// V11: across sources, a real call line beats another source's fallback +// start line, whichever is smaller. +func TestFillSiteLinesPrefersAnExactLineAcrossSources(t *testing.T) { + a := linedSource{lines: map[codegraph.FilePair]int{{From: "a.go", To: "b.go"}: 40}, inexact: true} + b := linedSource{lines: map[codegraph.FilePair]int{{From: "a.go", To: "b.go"}: 55}} + vs := []Violation{{From: "a.go", To: "b.go"}} + fillSiteLines(vs, []LabeledSource{{Label: "x", Src: a}, {Label: "y", Src: b}}, &strings.Builder{}) + if vs[0].Line != 55 { + t.Errorf("line %d, want 55 (exact beats a start-line fallback)", vs[0].Line) + } +} + +// V10: in a list, the warning is about what that one source alone knew. +func TestSiteLinesWarningInAListSaysOnlyThatSourcesResults(t *testing.T) { + var stderr strings.Builder + fillSiteLines([]Violation{{From: "a.go", To: "b.go"}}, []LabeledSource{{Label: "codegraph", Src: failingLiner{}}, {Label: "scip-go", Src: linedSource{}}}, &stderr) + wantMatch(t, `^codeshot: codegraph: --sarif: no line numbers from codegraph \(.*\); results only it knows of point at line 1 of their file\.`, stderr.String()) +} + +// V2: a --sarif run on a graph --max-symbols cut writes nothing and fails. +// V3: a rules file that checks nothing is refused with --sarif. +func TestCLISarifRefusesACutGraphAndARulesFileThatChecksNothing(t *testing.T) { + requireBins(t, "dot") + dir := t.TempDir() + snap := "snapshot:" + writeSnapshotFile(t, sarifSnapshot) + sarif, out := filepath.Join(dir, "x.sarif"), filepath.Join(dir, "a.dot") + code, _, stderr := runCLI("--architecture", "--source", snap, "--forbid", "src/->lib/", "--max-symbols", "1", "--sarif", sarif, "--format", "dot", "--out", out) + if code != 1 { + t.Errorf("cut graph: exit %d, want 1", code) + } + wantMatch(t, `--sarif: the scan stopped at --max-symbols 1`, stderr) + for _, f := range []string{sarif, out} { + if _, err := os.Stat(f); err == nil { + t.Errorf("%s written for a cut graph", f) + } + } + for _, body := range []string{"version: 1\n", "version: 1\nallow:\n - {from: a/, to: b/}\n", "version: 1\nlayers:\n - {name: only, paths: [a/]}\n"} { + wantRejected(t, `--sarif needs a rule to check`, "--architecture", "--rules", writeRulesFile(t, body), "--sarif", sarif) + } +}