audit: summary + group-by report options (#35) #36

Merged
KofTwentyTwo merged 18 commits from feature/GH-35-audit-summary-reports into develop 2026-06-09 15:17:56 +00:00
19 changed files with 2462 additions and 208 deletions

No files matched your search

+17
View File
@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
- `audit --summary`: a counts-only report (findings plus the by-SPDX, by-category, and by-file-type rollups) that omits the per-file and per-dependency lists and any pending diffs.
- `audit --group-by license|category|type|directory`: organizes the source-file listing under each value of the dimension; combined with `--summary` it shows per-group counts only.
- `audit --sort key|count`, `--depth N` (widen directory keys to N path segments), and `--only missing,unknown,copyleft,violations` (narrow the file listing to problem files without distorting the rollups).
- Per-group **risk** markers and per-group license breakdowns, so a `directory` or `type` grouping is not license-blind.
- Policy-aware group risk: a group's risk escalates to `high` when its license is party to a repo-level hard incompatibility (e.g. an Apache group beside an AGPL group) or a file in it carries a policy violation, instead of reporting the license category's risk alone.
- Attributable policy violations in every format: each violation names the offending license, the rule, and the file (text/markdown) or a structured `violationDetails` array (JSON).
- `findings` summary, per-row percentages/totals, and `riskLevel`/`worstCategory` in the JSON and markdown reports (previously text-only).
### Changed
- The JSON report always emits the complete report; `--summary` only trims the human-readable (text/markdown) formats.
- Renamed the headerless source-file bucket label to `(no-header)`.
### Fixed
- Excluded the tool's own `.license-tool.yaml` from source-header coverage (it is listed as skipped with reason `tool config`), so it no longer inflates the source-file and missing-header counts and `check` no longer fails on it for lacking a header.
- Made per-group risk reflect the full repo's incompatibilities under `--only`: the risk marker is now derived from the whole report, so narrowing the listing no longer understates a group's risk.
## [0.3.0] - 2026-06-04
### Install
+70
View File
@@ -54,8 +54,43 @@ license-tool audit --format json --output audit.json
license-tool audit --format markdown --output LICENSE-AUDIT.md
license-tool audit --deps=false
license-tool audit --resolve-deps tool
license-tool audit --summary # counts only; no per-file/dependency lists
license-tool audit --group-by license # group source files by license
license-tool audit --group-by directory # group by top-level directory
license-tool audit --summary --group-by type # per-group counts only
license-tool audit --group-by directory --depth 2 # group by two path segments
license-tool audit --group-by license --sort count # most common first
license-tool audit --only missing,copyleft # list only problem files
```
By default the report lists every source file. `--summary` keeps the `findings:`
overview and the by-SPDX / by-category / by-file-type rollups but omits the per-file
and per-dependency lists and any pending diffs. `--group-by license|category|type|directory`
organizes the source-file listing under each value of the dimension instead of a flat
list; combined with `--summary` it shows per-group counts only. Each group reports its
worst license **risk** (`high`/`medium`/`low`, or `unknown` for a headerless group)
and, for non-license groupings, its license breakdown, so a `directory` view is not
license-blind. Group risk is **policy-aware**: it escalates to `high` when the group's
license is party to a repo-level hard incompatibility (e.g. an Apache group beside an
AGPL group) or a file in it carries a policy violation, so a group is never reported
"low" while it is actually an audit liability. `--sort key|count`
orders rollups and groups; `--depth N` widens directory keys to N path segments;
`--only missing,unknown,copyleft,violations` narrows the file listing to problem files
without distorting the rollups. The flags apply to text, markdown, and JSON (which
always emits the complete report — `--summary` only trims the human formats). An
unknown `--group-by`/`--sort`/`--only` value is a usage error.
Every format now carries the `findings` summary (coverage, license mix, risk level,
copyleft, dependency resolution, policy) and **attributable policy violations** — each
violation names the offending license, the rule, and the file (text/markdown) or a
structured `violationDetails` array (JSON), so both engineers and tools can see *why*
a check failed, not just that it did. Rollups show per-row percentages and totals.
The tool's own `.license-tool.yaml` is treated as metadata, not coverable source: it
is listed as skipped (reason `tool config`) and never counted toward source-header
coverage, so it cannot inflate the missing-header tally — and `check` no longer fails
on the config for lacking a header.
Audit output is read-only. Audit always prints a "not legal advice" disclaimer.
Text output starts with a `findings:` summary that calls out source-file header
coverage, license types, unknown or unrecognized license ids, copyleft licenses,
@@ -71,6 +106,41 @@ findings:
policy: FAIL (1: policy-violation)
```
`--group-by` turns the flat file list into a grouped view. For example,
`audit --group-by license` shows exactly which files carry which license, and where
the gaps are:
```text
source files by license:
(no-header) (1) [risk: unknown]
src/legacy.go [no managed header]
AGPL-3.0-or-later (2) [risk: high]
src/a.go [AGPL-3.0-or-later]
src/b.go [AGPL-3.0-or-later]
MIT (2) [risk: low]
web/c.ts [MIT]
web/d.ts [MIT]
(skipped: 6)
```
For a tree-shaped view of coverage, `audit --summary --group-by directory` answers
"which parts of the repo are licensed" at a glance, with no per-file noise. Each
directory carries its worst risk and its license breakdown, so the grouping is not
license-blind:
```text
source files by directory:
src (3) [risk: high]
licenses: (no-header) 1, AGPL-3.0-or-later 2
web (2) [risk: low]
licenses: MIT 2
(skipped: 6)
```
And `audit --group-by license --format json` emits the same grouping as machine data
(a `groups` array of `{key, count, risk, licenses, files}`) for dashboards and CI
summaries.
Dependency audit discovers manifests in the root and in subdirectories, while
honoring git, `.gitignore`, configured excludes, and common vendor-heavy
directories such as `node_modules`, `vendor`, `build`, `dist`, and `.gradle`.
+68 -6
View File
@@ -5,6 +5,7 @@ import (
"fmt"
"io"
"os"
"path"
"path/filepath"
"sort"
"strings"
@@ -83,6 +84,42 @@ type auditFlags struct {
noDeps bool
resolveDeps string
failOn []string
summary bool
groupBy string
sort string
depth int
only string
}
// renderOptions parses the summary/group-by/sort flags into report.RenderOptions,
// surfacing an unknown --group-by or --sort value as a usage error.
func (f auditFlags) renderOptions() (report.RenderOptions, error) {
dim, err := report.ParseGroupBy(f.groupBy)
if err != nil {
return report.RenderOptions{}, err
}
byCount, err := parseSort(f.sort)
if err != nil {
return report.RenderOptions{}, err
}
only, err := report.ParseOnly(f.only)
if err != nil {
return report.RenderOptions{}, err
}
return report.RenderOptions{Summary: f.summary, GroupBy: dim, SortByCount: byCount, DirectoryDepth: f.depth, Only: only}, nil
}
// parseSort maps the --sort token to the by-count flag. "" and "key" sort
// alphabetically; "count" sorts by descending frequency.
func parseSort(raw string) (bool, error) {
switch raw {
case "", "key":
return false, nil
case "count":
return true, nil
default:
return false, fmt.Errorf("audit: unknown sort %q (expected key|count)", raw)
}
}
func (f auditFlags) includeDeps() bool {
@@ -108,6 +145,10 @@ func newAuditCmd(shared *sharedFlags) *cobra.Command {
if validateErr := validateResolveDeps(f.resolveDeps); validateErr != nil {
return usageError(validateErr)
}
renderOpts, err := f.renderOptions()
if err != nil {
return usageError(err)
}
r, err := report.Audit(path, cfg, report.Options{
Format: format,
IncludeDeps: f.includeDeps(),
@@ -117,7 +158,7 @@ func newAuditCmd(shared *sharedFlags) *cobra.Command {
if err != nil {
return internalError(err)
}
if err := renderCommandReport(cmd, f.output, r, format); err != nil {
if err := renderCommandReport(cmd, f.output, r, format, renderOpts); err != nil {
return err
}
return nil
@@ -153,6 +194,10 @@ func newCheckCmd(shared *sharedFlags) *cobra.Command {
if validateErr := validateResolveDeps(f.resolveDeps); validateErr != nil {
return usageError(validateErr)
}
renderOpts, err := f.renderOptions()
if err != nil {
return usageError(err)
}
r, err := report.Audit(path, cfg, report.Options{
Format: format,
IncludeDeps: f.includeDeps(),
@@ -162,7 +207,7 @@ func newCheckCmd(shared *sharedFlags) *cobra.Command {
if err != nil {
return internalError(err)
}
if err := renderCommandReport(cmd, f.output, r, format); err != nil {
if err := renderCommandReport(cmd, f.output, r, format, renderOpts); err != nil {
return err
}
if !r.Passed {
@@ -184,6 +229,11 @@ func bindAuditFlags(cmd *cobra.Command, f *auditFlags, isCheck bool) {
cmd.Flags().BoolVar(&f.deps, "deps", true, "resolve dependency licenses")
cmd.Flags().BoolVar(&f.noDeps, "no-deps", false, "skip dependency license resolution")
cmd.Flags().StringVar(&f.resolveDeps, "resolve-deps", "ondisk", "dependency resolution tier: ondisk|tool|off")
cmd.Flags().BoolVar(&f.summary, "summary", false, "counts only: omit the per-file and per-dependency lists")
cmd.Flags().StringVar(&f.groupBy, "group-by", "", "group source files by: license|category|type|directory")
cmd.Flags().StringVar(&f.sort, "sort", "key", "rollup/group order: key|count")
cmd.Flags().IntVar(&f.depth, "depth", 1, "directory grouping depth (with --group-by directory)")
cmd.Flags().StringVar(&f.only, "only", "", "list only problem files: missing|unknown|copyleft|violations (comma-separated)")
if isCheck {
cmd.Flags().StringArrayVar(&f.failOn, "fail-on", []string{"missing-header", "unknown-license", "policy-violation"}, "conditions that cause a non-zero exit")
}
@@ -310,9 +360,9 @@ var createReportFile = func(name string) (io.WriteCloser, error) {
return os.Create(name)
}
func renderCommandReport(cmd *cobra.Command, output string, r model.Report, format report.Format) error {
func renderCommandReport(cmd *cobra.Command, output string, r model.Report, format report.Format, opts report.RenderOptions) error {
if output == "" {
if err := report.Render(cmd.OutOrStdout(), r, format); err != nil {
if err := report.RenderWithOptions(cmd.OutOrStdout(), r, format, opts); err != nil {
return internalError(err)
}
return nil
@@ -322,7 +372,7 @@ func renderCommandReport(cmd *cobra.Command, output string, r model.Report, form
if err != nil {
return internalError(fmt.Errorf("report: create output %s: %w", output, err))
}
renderErr := report.Render(f, r, format)
renderErr := report.RenderWithOptions(f, r, format, opts)
closeErr := f.Close()
if renderErr != nil {
return internalError(renderErr)
@@ -490,6 +540,10 @@ func newVersionCmd(info buildInfo) *cobra.Command {
// content (the report layer needs the bytes for detection); Detect is the detector
// directly; ResolveDeps iterates the ecosystem resolvers detected at the root and
// concatenates their findings (unresolved entries included, never guessed).
// reasonToolConfig is the skip reason recorded for the tool's own config file, so it
// is shown in the file listing but excluded from source/header coverage tallies.
const reasonToolConfig = "tool config"
func buildAuditPipeline(cfg model.Config, shared *sharedFlags) report.Pipeline {
classify := config.ContentLookupFunc(cfg)
return report.Pipeline{
@@ -510,7 +564,15 @@ func buildAuditPipeline(cfg model.Config, shared *sharedFlags) report.Pipeline {
Skip: e.Skip,
SkipReason: e.SkipReason,
}
if !e.Skip {
// The tool's own .license-tool.yaml is metadata, not coverable source: it
// never carries a managed header, so counting it would inflate
// sourceTotal/sourceMissing. Mark it skipped (still listed, with a reason)
// rather than counting it as a headerless source file.
if !sf.Skip && path.Base(e.Path) == config.RepoConfigName {
sf.Skip = true
sf.SkipReason = reasonToolConfig
}
if !sf.Skip {
content, rerr := os.ReadFile(e.AbsPath)
if rerr != nil {
sf.Skip = true
+147 -3
View File
@@ -267,6 +267,64 @@ func TestAuditCommand(t *testing.T) {
assert.Contains(t, out, `"schema": "license-tool/report/v1"`)
})
t.Run("tool config file is excluded from source coverage", func(t *testing.T) {
dir := t.TempDir()
writeFile(t, dir, ".license-tool.yaml", configYAML)
writeFile(t, dir, "main.go", "package main\n\nfunc main() {}\n")
out, err := runRoot(t, "audit", dir, "--format", "json", "--deps=false")
require.NoError(t, err)
var got struct {
Findings struct {
SourceTotal int `json:"sourceTotal"`
SourceMissing int `json:"sourceMissing"`
} `json:"findings"`
}
require.NoError(t, json.Unmarshal([]byte(out), &got))
assert.Equal(t, 1, got.Findings.SourceTotal, "only main.go is coverable source; the tool's own config is not")
assert.Equal(t, 1, got.Findings.SourceMissing, "the headerless config file must not inflate sourceMissing")
entry := jsonFileEntry(t, out, ".license-tool.yaml")
assert.Equal(t, true, entry["skipped"], ".license-tool.yaml should be skipped, not counted as source")
assert.Equal(t, "tool config", entry["skipReason"])
// Detection and policy never run on the skipped config, so its declared license
// does not leak into the report as a detected header or a violation.
assert.Equal(t, false, entry["hasHeader"], "no header is detected on the skipped config")
assert.NotContains(t, entry, "spdxId", "the config's declared license must not surface as a detected id")
assert.NotContains(t, entry, "violations", "the skipped config carries no policy violations")
})
t.Run("tool config is excluded when nested and under --only", func(t *testing.T) {
// Basename match excludes the config at any depth, and a headerless config must
// never leak into the --only=missing problem list.
dir := t.TempDir()
writeFile(t, dir, ".license-tool.yaml", configYAML)
writeFile(t, dir, filepath.Join("sub", ".license-tool.yaml"), configYAML)
writeFile(t, dir, "main.go", "package main\n\nfunc main() {}\n")
out, err := runRoot(t, "audit", dir, "--format", "json", "--deps=false", "--only", "missing")
require.NoError(t, err)
var got struct {
Findings struct {
SourceTotal int `json:"sourceTotal"`
} `json:"findings"`
Files []map[string]any `json:"files"`
}
require.NoError(t, json.Unmarshal([]byte(out), &got))
assert.Equal(t, 1, got.Findings.SourceTotal, "both root and nested config are excluded; only main.go counts")
// The --only=missing listing lists the headerless main.go but neither config.
listed := map[string]bool{}
for _, f := range got.Files {
listed[f["path"].(string)] = true
}
assert.True(t, listed["main.go"], "the headerless main.go is a missing-header problem file")
assert.False(t, listed[".license-tool.yaml"], "the root config must not appear in --only=missing")
assert.False(t, listed[filepath.ToSlash(filepath.Join("sub", ".license-tool.yaml"))], "the nested config must not appear in --only=missing")
})
t.Run("output file", func(t *testing.T) {
dir := fixtureDir(t)
outPath := filepath.Join(dir, "audit.json")
@@ -454,6 +512,18 @@ func TestCheckCommand(t *testing.T) {
require.NoError(t, err)
})
t.Run("tool config does not trigger a missing-header check failure", func(t *testing.T) {
// The config is headerless YAML; under the default fail_on (which includes
// missing-header) it would fail check if counted as source. Excluding it lets a
// repo whose only other file is properly headered pass. This guards the audit
// pipeline's config exclusion against regression on the check exit code.
dir := t.TempDir()
writeFile(t, dir, ".license-tool.yaml", configYAML)
writeFile(t, dir, "main.go", "/* SPDX-License-Identifier: AGPL-3.0-or-later */\n\npackage main\n")
_, err := runRoot(t, "check", dir, "--deps=false")
require.NoError(t, err, "the tool's own config must not cause a missing-header check failure")
})
t.Run("fail-on flag overrides check policy", func(t *testing.T) {
dir := fixtureDir(t)
out, err := runRoot(t, "check", dir, "--fail-on", "unresolved-dependency", "--deps=false")
@@ -1005,12 +1075,12 @@ func TestRenderCommandReportErrors(t *testing.T) {
var out bytes.Buffer
root.SetOut(&out)
err := renderCommandReport(root, "", model.Report{}, report.Format(99))
err := renderCommandReport(root, "", model.Report{}, report.Format(99), report.RenderOptions{})
require.Error(t, err)
assert.Equal(t, exitInternal, exitCode(err))
assert.Empty(t, out.String())
err = renderCommandReport(root, filepath.Join(t.TempDir(), "report.txt"), model.Report{}, report.Format(99))
err = renderCommandReport(root, filepath.Join(t.TempDir(), "report.txt"), model.Report{}, report.Format(99), report.RenderOptions{})
require.Error(t, err)
assert.Equal(t, exitInternal, exitCode(err))
@@ -1020,7 +1090,7 @@ func TestRenderCommandReportErrors(t *testing.T) {
}
t.Cleanup(func() { createReportFile = orig })
err = renderCommandReport(root, filepath.Join(t.TempDir(), "report.txt"), model.Report{}, report.FormatText)
err = renderCommandReport(root, filepath.Join(t.TempDir(), "report.txt"), model.Report{}, report.FormatText, report.RenderOptions{})
require.Error(t, err)
assert.Equal(t, exitInternal, exitCode(err))
assert.Contains(t, err.Error(), "close failed")
@@ -1032,6 +1102,68 @@ func TestWriteOrInternalErrorClassifiesUnexpectedErrors(t *testing.T) {
assert.Equal(t, exitInternal, exitCode(err))
}
func TestAuditSummaryOmitsFileList(t *testing.T) {
isolateEnv(t)
dir := fixtureDir(t)
out, err := runRoot(t, "audit", dir, "--deps=false", "--summary")
require.NoError(t, err)
assert.Contains(t, out, "by SPDX id:")
assert.NotContains(t, out, "\nsource files:")
}
func TestAuditGroupByLicense(t *testing.T) {
isolateEnv(t)
dir := fixtureDir(t)
out, err := runRoot(t, "audit", dir, "--deps=false", "--group-by", "license")
require.NoError(t, err)
assert.Contains(t, out, "source files by license:")
}
func TestAuditGroupByUnknownIsUsageError(t *testing.T) {
isolateEnv(t)
dir := fixtureDir(t)
stdout, stderr, code := executeRoot(t, "audit", dir, "--deps=false", "--group-by", "bogus")
assert.Equal(t, 2, code)
assert.Empty(t, stdout)
assert.Contains(t, stderr, "unknown group-by dimension")
}
func TestCheckGroupByUnknownIsUsageError(t *testing.T) {
isolateEnv(t)
dir := fixtureDir(t)
stdout, stderr, code := executeRoot(t, "check", dir, "--deps=false", "--group-by", "bogus")
assert.Equal(t, 2, code)
assert.Empty(t, stdout)
assert.Contains(t, stderr, "unknown group-by dimension")
}
func TestParseSort(t *testing.T) {
for _, tok := range []string{"", "key"} {
got, err := parseSort(tok)
require.NoError(t, err)
assert.False(t, got)
}
got, err := parseSort("count")
require.NoError(t, err)
assert.True(t, got)
_, err = parseSort("bogus")
require.Error(t, err)
assert.Contains(t, err.Error(), "unknown sort")
}
func TestAuditSortAndUnknownSort(t *testing.T) {
isolateEnv(t)
dir := fixtureDir(t)
_, err := runRoot(t, "audit", dir, "--deps=false", "--sort", "count")
require.NoError(t, err)
_, stderr, code := executeRoot(t, "audit", dir, "--deps=false", "--sort", "bogus")
assert.Equal(t, 2, code)
assert.Contains(t, stderr, "unknown sort")
}
func TestLicenseSelectOptions(t *testing.T) {
opts := licenseSelectOptions()
require.NotEmpty(t, opts, "license picker should offer renderable licenses")
@@ -1167,3 +1299,15 @@ func (w closeErrorWriter) Write(p []byte) (int, error) {
func (w closeErrorWriter) Close() error {
return w.closeErr
}
func TestAuditOnlyFilter(t *testing.T) {
isolateEnv(t)
dir := fixtureDir(t) // headerless main.go
out, err := runRoot(t, "audit", dir, "--deps=false", "--only", "missing")
require.NoError(t, err)
assert.Contains(t, out, "main.go")
_, stderr, code := executeRoot(t, "audit", dir, "--deps=false", "--only", "bogus")
assert.Equal(t, 2, code)
assert.Contains(t, stderr, "unknown --only filter")
}
@@ -0,0 +1,90 @@
# DESIGN: GH-35 Audit Summary + Group-By Report Options
Status: **proposed** (brainstormed and approved; awaiting spec review). Issue: #35.
## Problem
The text and markdown audit renderers always emit a flat per-file list (every path), which buries the grouped rollups (`by SPDX id`, `by category`, `by file type`) on any non-trivial repo. There is no way to get a concise, human-readable, grouped view. Add opt-in summary and group-by options. The default output stays exactly as today (backward compatible).
## Approach
**Render-time grouping.** `model.Report` stays frozen. Grouping is derived from `r.Files` at render time by a pure, unit-tested function. A `RenderOptions` value is threaded into `report.Render` and honored by all three renderers. (Rejected: adding a `Groups` field to the frozen model; a separate `summarize` subcommand.)
## Flags (bound on both `audit` and `check` via the shared `bindAuditFlags`)
- `--summary` (bool, default false): counts only. Omits the per-file list, the per-dependency list, and pending diffs. Keeps findings, the count rollups, and policy violations.
- `--group-by <dim>` (string, default ""): one of `license` | `category` | `type` | `directory`. Organizes the source-file listing under each value of the dimension. Empty means the default flat list. An unknown value is a usage error (exit 2), validated like `--resolve-deps`.
### Orthogonal model
The three standalone count rollups (`by SPDX id`, `by category`, `by file type`) are **always** shown (unchanged). Only the **file listing** changes:
| flags | file listing |
|---|---|
| (none) | flat list of every source file — unchanged default |
| `--group-by X` | source files nested under each value of X: `KEY (n):` then the file lines |
| `--summary` | omitted entirely (also omits dep list + diffs) |
| `--summary --group-by X` | per-group **counts** for X only (`KEY: n`), no file paths |
### Scope
- `--group-by` groups **source files only**. The dependency section is unaffected (full list normally; replaced by the resolved/unresolved counts under `--summary`). Grouping dependencies by license/ecosystem is a deliberate non-goal.
- `GroupFiles` operates over the **non-skipped** source set (the licensable files), for every dimension. Skipped files (binary/uncommentable/unknown) are reported as a trailing `(skipped: N)` note in the grouped section, never grouped. The pre-existing count rollups keep their current populations.
### Group keys
- `license`: `fr.Detected.SPDXID` when a header is present and non-empty, else `(none)`.
- `category`: the policy category token for that id (`permissive`, `strong-copyleft`, ...), else `unknown`.
- `type`: `fr.FileType` (the matched type name).
- `directory`: the first path segment of `fr.Path`; files at the root group under `.`.
Groups are sorted by key; files within a group are sorted by path. Deterministic for identical input.
## Components
- **`internal/report/group.go`** (new):
- `type GroupDimension int` with `GroupNone, GroupLicense, GroupCategory, GroupType, GroupDirectory`.
- `func ParseGroupBy(string) (GroupDimension, error)` — `""`->`GroupNone` (no error); the four tokens; else error `report: unknown group-by dimension %q (expected license|category|type|directory)`.
- `type Group struct { Key string; Count int; Files []model.FileResult }`.
- `func GroupFiles(r model.Report, dim GroupDimension) (groups []Group, skipped int)` — pure, sorted, deterministic. `GroupNone` returns `(nil, skipped)`.
- **`internal/report/report.go`**:
- `type RenderOptions struct { Summary bool; GroupBy GroupDimension }`.
- `Render(w, r, format, opts)` — signature gains `opts`. `renderText` / `renderMarkdown` / `renderJSON` each honor `opts`:
- text/markdown: always print findings + the three count rollups; render the file listing per the table above; under `--summary` also drop the dependency list and pending diffs (keep `dependencies: N (resolved R, unresolved U)` from findings) and policy violations stay.
- JSON: when `GroupBy != GroupNone`, add a `groups` array (`[{key, count, files?}]`); under `Summary`, omit per-file `files` detail and the `dependencies` array, keeping the count maps and `violations`. Default JSON (no flags) is byte-identical to today. Additive schema, still `license-tool/report/v1`.
- **`cmd/license-tool/commands.go`**:
- `auditFlags` gains `summary bool` and `groupBy string`.
- `bindAuditFlags` registers `--summary` and `--group-by`.
- `newAuditCmd`/`newCheckCmd` parse+validate `--group-by` (usage error on unknown) and pass `report.RenderOptions` through `renderCommandReport` -> `report.Render`.
## Error handling
- Unknown `--group-by` value: usage error, exit 2, before any rendering.
- `--summary` and `--group-by` compose (no conflict); both may be combined per the table.
- All existing exit-code and rendering behavior for the no-flag case is preserved.
## Testing (hold the 100% gate)
- `ParseGroupBy`: every token + empty + unknown.
- `GroupFiles`: each dimension's keying (including `(none)` license, `unknown` category, root `.` directory), skipped-count exclusion, sort determinism, `GroupNone`.
- Renderers: for text, markdown, and JSON — default unchanged (golden), `--summary`, `--group-by` each dimension, and `--summary --group-by`.
- Command layer: flag wiring, unknown-dimension usage error (exit 2), `--summary`/`--group-by` reach `Render`.
## Docs
- README `audit` section: document `--summary` and `--group-by` with a short example of each.
## Out of scope
- Grouping dependencies; multiple simultaneous `--group-by` dimensions; a configurable directory depth (top-level only for now).
## Post-implementation addenda (2026-06-08)
The implementation extended past the original scope in two deliberate places, and three audit-flagged items were resolved by decision rather than code:
- **Implemented beyond original scope.** A configurable directory depth (`--depth N`), per-group risk markers and license breakdowns, `--sort key|count`, `--only` filtering, attributable `violationDetails`, and JSON/markdown findings parity were all added. The "top-level only" directory-depth non-goal above was superseded.
- **Self-config exclusion.** The tool's own `.license-tool.yaml` is YAML (commentable) and was being counted as a headerless source file, inflating `sourceTotal`/`sourceMissing`. It is now marked skipped (reason `tool config`) in the audit pipeline (`buildAuditPipeline`), keyed off the exported `config.RepoConfigName`. It stays in the file listing for transparency but is excluded from coverage tallies.
- **Policy-aware group risk.** A group's `[risk]` was computed only from its files' license categories, so it was policy-blind (an Apache group beside AGPL read `low`). Group risk now escalates to `high` when a group's license is party to a repo-level hard incompatibility (computed via `policy.Incompatible` over the distinct source ids) or a file in the group carries a file-scoped `policy-violation` token. Heterogeneity is intentionally not escalated (a whole-repo property; escalating every group would be noise).
- **`--group-by dependency` — confirmed non-goal.** Re-flagged by the clean-room audit but reaffirmed as out of scope: dependencies are not files, the semantics are ambiguous (by-license vs by-ecosystem), and the dependency section already has its own resolved/unresolved view.
- **JSON explicit percentages/totals — declined.** Per-row percentages are a presentation concern of the human formats; the JSON report stays normalized (counts + `findings`), from which any consumer can derive them. Adding redundant fields was judged low value.
- **`go.mod` dependency resolution — not a defect.** The audit flagged "dep resolver returned 0 for a go.mod require." Go modules are not a supported dependency ecosystem (only npm, Maven, and Gradle manifests are discovered), so resolving zero dependencies for a Go-module repo is correct behavior, not a bug.
+57 -22
View File
@@ -1,27 +1,62 @@
# Session State
## Current Branch
`feature/GH-12-27-audit-fixes`
**Last Updated:** 2026-06-09
## Current Objective
Resolve GitHub issues #6 through #27 using TDD, keep the 100% coverage gate passing, and merge the passing local feature branch back to local `develop`.
## Current Status
GH-35 audit-reporting work is complete and the punch list is closed. Both feature
branches are green (gofmt/vet/golangci-lint, `go test ./... -race`, 100% coverage gate,
build) and being pushed with PRs opened into `develop` for review. No merges performed
(left for review).
## Status
- Branch created from `develop`.
- Audit issues filed and de-duplicated against existing open issues #6 through #11.
- Plan and TODO created.
- Worktrees created under `/private/tmp/license-tool-worktrees/` for write safety, CLI reporting, SPDX/policy, dependency/release/docs, and header placement slices.
- Worker agents assigned:
- Write safety: #12, #13, #14, #15 on `feature/GH-12-27-write-safety`.
- CLI/reporting: #16, #17, #18, #25 on `feature/GH-12-27-cli-reporting`.
- SPDX/policy: #19, #20 on `feature/GH-12-27-spdx-policy`.
- Dependency/release/docs: #11, #21, #22, #23, #26 on `feature/GH-12-27-deps-release-docs`.
- Header placement: #6, #7, #8, #24, #27 on `feature/GH-12-27-header-placement`.
- File-type coverage: #9 and #10 on `feature/GH-9-10-filetype-coverage`.
- GitHub issue comments reviewed for #6 through #27 and closed tracker #3.
- Worker branches integrated into `feature/GH-12-27-audit-fixes`.
- Local gates passed: `gofmt -l .`, `go vet ./...`, `golangci-lint run`, `go test ./... -race -cover`, 100% configured coverage gate, `go build ./...`, `goreleaser check`, and `gitleaks detect`.
- `feature/GH-12-27-audit-fixes` fast-forward merged into local `develop`.
## Active Branches
| Branch | Base | Status |
|--------|------|--------|
| `feature/GH-29-init-tui-wizard` | develop | Init TUI redesign — single-form + adaptive live preview; `wizard.go` thin adapter, logic in `internal/initwizard` at 100%. Complete; pushed; PR opened. |
| `feature/GH-35-audit-summary-reports` | develop | Audit reporting overhaul. Complete; pushed; PR opened. 16 commits ahead of develop. |
## Next Step
Manual review and testing before any push to GitHub, promotion to `main`, tag, or release.
GH-29 and GH-35 are independent (touch different code); both branch from `develop`.
## GH-35 punch list — CLOSED
- [x] Self-config exclusion: `.license-tool.yaml` marked skipped (reason `tool config`), excluded from source coverage; `check` no longer fails on it. (`ce192ca`)
- [x] Policy-aware group risk: escalates to `high` on repo-level hard incompatibility or file-scoped policy violation. (`2822d86`)
- [x] Hardened: incompatibility set derived from the full report so `--only` cannot distort a group's risk; `path.Base` for slash paths. (`3852c91`)
- [~] `--group-by dependency`: confirmed **non-goal** (deps aren't files; ambiguous semantics; deps already have their own resolved/unresolved view). Recorded in the design doc.
- [~] JSON explicit %/totals: **declined** — presentation concern; JSON stays normalized (counts + findings), from which consumers derive percentages.
- [~] Dep resolver "0 for a go.mod require": **not a defect** — Go modules are not a supported ecosystem (only npm/Maven/Gradle manifests are discovered).
## This session's work (GH-35)
- Two features + hardening (commits above), all TDD, gate green at every step.
- Three-agent adversarial review of the delta (`bbba9d2..HEAD`); findings addressed: the `--only` risk-distortion contract, cross-platform `path.Base`, and several coverage-of-intent test gaps (directory-group escalation, incompat-vs-headerless precedence, `incompatibleIDs` cardinality, nested/`--only` config exclusion, no detected-license leak, `check` exit-code regression guard).
- Docs: README (policy-aware risk, config exclusion, corrected grouped-output samples + JSON group shape), CHANGELOG `[Unreleased]`, DESIGN addenda recording the three by-decision resolutions.
## Open PRs into `develop` (all CI-green; none merged — awaiting author review)
| PR | Issue | Branch | Summary |
|----|-------|--------|---------|
| #36 | #35 | feature/GH-35-audit-summary-reports | Audit reporting overhaul + self-config exclusion + policy-aware risk |
| #37 | #29 | feature/GH-29-init-tui-wizard | Init full TUI wizard + live preview |
| #38 | #31 | feature/GH-31-spdxnorm-no-guess | Stop guessing SPDX ids for ambiguous aliases (resolve to unresolved) |
| #39 | #34 | feature/GH-34-quiet-verbose-flags | Remove no-op `--quiet`/`--verbose` flags (Option B; isWriteRefusal LOW deferred) |
| #40 | #33 | feature/GH-33-symlink-license | Refuse to clobber a symlinked LICENSE (exit 3) |
| #41 | #30 | feature/GH-30-detect-overmatch | Confine header detection to contiguous comment lines; SPDX tag must start a line |
All six branch from `develop` and are independent. Bug fixes #38–#41 were done by
parallel worktree-isolated agents, each TDD + full gate (100% coverage) + own PR.
## Other Open Threads
- [ ] Review/merge the six PRs above (independent; flexible order). Resolve CHANGELOG `[Unreleased]` conflicts at merge time — each branch added its own entry.
- [ ] GH-29 commit `bafa281` bundled planning docs via `git add -A` — optional history tidy; not done (no autonomous history rewrite).
- [ ] Deferred LOW items flagged in PRs: #41 block-comment de-stacking (left to avoid over-detection); #39 `isWriteRefusal` typed-sentinel refactor (deferred to avoid colliding with #40's applier changes) and the still-dead `model.ResolveOptions.Verbose` field.
- [ ] #32 (include `**`) was fixed on GH-29.
## Judgment calls made autonomously (worth a glance during review)
- #41: SPDX-tag detection now requires the tag at the start of a comment line (mid-prose mention no longer matches) — intentional under prefer-under-detection.
- #38: kept `gnu affero general public license v3.0 or later` alias (pins version+grant, curated id); alias validation switched from `spdx.Validate` to `spdx.Lookup` so "resolved" implies classifiable.
- #39: removed the flags rather than wiring hollow behavior.
- #40: refuses (does not dereference) a symlinked license target; an already-matching symlink still reports `action: none`.
## Key Reference
- Issues: #29 (init TUI), #35 (audit reports); bugs #30/#31/#33/#34.
- Design/spec: `docs/DESIGN-init-tui-redesign.md`, `docs/DESIGN-GH-35-audit-summary-reports.md` (see post-implementation addenda), `docs/PLAN-GH-29-init-tui-redesign.md`.
- Reviews: `docs/review/01-03` (full codebase), `04`/`05` (audit clean-room).
- Gate: `gofmt -l .`; `go vet ./...`; `go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest run`; `go test ./... -race -coverpkg=./internal/...,./cmd/... -covermode=atomic -coverprofile=cover.out`; `go run github.com/vladopajic/go-test-coverage/v2@v2.18.8 --config=.testcoverage.yml`.
- Repo: GitHub `KofTwentyTwo/license-tool`; default branch `develop`; commits reference issues, no AI attribution.
+308
View File
@@ -0,0 +1,308 @@
# Clean-room review: `audit --summary` and `--group-by`
Reviewer: independent, no prior context. Evaluated `feature/GH-35-audit-summary-reports`
built to `/tmp/cr-lt` from `cmd/license-tool`. Exercised against this repo, a hand-built
mixed-license repo (`/tmp/cr-mix`: MIT/Apache-2.0/AGPL/BSD + unlicensed `vendor/` + a
markdown file), and a 96-file tree (`/tmp/cr-big`). All output below is pasted from real
runs.
Lens: a compliance engineer scanning a repo, and an LLM/dashboard consuming the JSON.
---
## TL;DR verdict
The two features work and compose cleanly across all three formats, output is
deterministic, and the code is well-factored (`group.go` is pure, `findings.go` is pure).
But the views are **shallow**: they answer "how many files have license X" and stop. They
do not answer the questions a compliance engineer actually asks — *what's my coverage %,
where is my copyleft exposure, which group is the problem, why did policy fail*. The two
biggest gaps are:
1. **The grouped/summary views carry no risk signal.** A group is just `key (count)`.
There is no per-group license/category, no copyleft flag, no "this group is the
violation." You can group by `directory` but each group then hides which licenses live
in it — the one cross-tab a human wants (license × directory) is impossible.
2. **`policy-violation` is opaque everywhere.** The top-level verdict says
`FAIL (1: policy-violation)` and the JSON emits `"violations": ["policy-violation"]`
with zero detail about *which license* tripped *which rule*. For an LLM this is nearly
useless — it can see AGPL is present and that policy failed, but cannot state the causal
link with confidence.
Plus a pile of quick wins: lexical directory sort (`pkg10` before `pkg2`), no totals/
percentages anywhere, the rich `findings:` block exists **only** in text (Markdown and JSON
don't get it), no "problems only" filter, and `(none)` is overloaded as both "no header"
and "empty section."
---
## What works well (credit where due)
- **Composition is clean.** `--summary` × `--group-by` × `--format` all combine sensibly.
Summary+group gives per-group counts only; full+group nests files. No crashes, no weird
interactions.
- **Determinism.** Keys and files are sorted; JSON map keys come out stable; empty
aggregates render `{}`/`[]` not `null` (`nonNilCounts`/`nonNilStrings`). Good for diffing
reports in CI.
- **The `findings:` text block is genuinely good** — coverage, license mix, unknown count,
copyleft list, deps resolution, policy cause on one screen. The problem is only that it's
trapped in the text renderer.
- **Skipped files are handled honestly** — never grouped, surfaced as a trailing
`(skipped: N)` so they don't pollute the license buckets, and `(none)` is a deliberate
sentinel (documented in code) so missing headers stay visible.
- **JSON `--summary` trims correctly and keeps a separate DTO** (`jsonSummaryReport`) so the
full schema stays byte-stable. Schema is versioned (`license-tool/report/v1`).
---
## Data quality
### Right info present, but no totals or percentages — anywhere
`licenseCounts` sums to 9 but the tool never tells you that, nor "78% headered." A
compliance reader has to add the columns by hand.
```
$ /tmp/cr-lt audit . --deps=false --format json | jq 'has("totals"), (.licenseCounts|add)'
false
9
```
There is no `totals` / `coverage` object in JSON, and the count tables in text/markdown have
no total row and no percentage column.
### The verdict cause is invisible
This is the worst data-quality gap. The mix repo has AGPL files and fails policy:
```
$ /tmp/cr-lt audit . --deps=false
policy: FAIL (1: policy-violation)
...
policy violations:
policy-violation
```
```
$ /tmp/cr-lt audit . --deps=false --format json | jq '.violations'
[ "policy-violation" ]
```
`policy-violation` is a bare token. It does not name the offending license
(`AGPL-3.0-or-later`), the rule (deny? copyleft-not-allowed?), or the files. The *per-file*
`missing-header` tokens are present on file records, but the repo-level policy reason is a
black box. An LLM asked "why did this fail and what do I do" can only guess.
### Grouped views have no risk dimension
Every group is `key (count)`. When you group by `directory`, you lose all license
information for that group:
```
$ /tmp/cr-lt audit . --group-by directory --summary
source files by directory:
scripts (1)
src (4)
vendor (2)
web (2)
```
`src` holds both MIT (`src/core`) and Apache (`src/util`) — invisible here. `web` is all
AGPL (the risky one) — also invisible. The group that matters for compliance (where's the
copyleft?) is indistinguishable from the rest. There is no copyleft/risk flag per group, no
secondary breakdown.
### Directory grouping is top-segment only — collapses real structure
`groupKey`→`topDir` takes only the first path segment, so `src/core` and `src/util` both
become `src`. On a deep monorepo this collapses everything under a handful of top dirs and
the view is nearly content-free. There's no depth control (`--group-by directory:2`) and no
full-path option.
### No multi-dimension grouping, no filtering to problems
```
$ /tmp/cr-lt audit . --group-by license,directory
report: unknown group-by dimension "license,directory" ...
$ /tmp/cr-lt audit --help | grep -iE 'only|filter|problem'
(nothing)
```
You cannot cross-tab (license × directory is the killer compliance view), and you cannot say
"show me only the files that are missing headers / unknown / copyleft." On the 96-file tree
the full grouped view is 125 lines of mostly-fine files; the 24 problem files are buried.
### Dependencies are second-class
`--group-by` only ever touches **source files**. Dependencies — arguably the higher
compliance risk — cannot be grouped at all (by license, by ecosystem, by resolution).
`--summary` drops the dep list entirely, leaving only `dependencies: N (resolved R,
unresolved U)` in the text findings; the Markdown/JSON summary don't even carry that.
### `(none)` is overloaded
`(none)` is the missing-header license bucket **and** the empty-section placeholder
(`renderCountSection(..., "(none)")`). In `--group-by license` a real bucket `(none) (2)`
sits next to potential `(none)` placeholders elsewhere — ambiguous for both humans and
parsers. A distinct token like `(no-header)` for the bucket would disambiguate.
---
## Display / UX (text)
- **Lexical directory sort is wrong for humans.** On the big tree:
```
source files by directory:
pkg1 (8)
pkg10 (8)
pkg11 (8)
pkg12 (8)
pkg2 (8)
...
```
`pkg10`–`pkg12` jump ahead of `pkg2`. Natural sort, or sort-by-count-desc, would read far
better. There is **no sort option** at all — everything is alpha-by-key.
- **No sort-by-count.** The thing a human scans for is "which license/dir dominates" — that
wants count-descending. Alpha order buries it.
- **Counts columns use a fixed `%-24s`** which is fine for short SPDX ids but `network-
copyleft` and `JavaScript/TypeScript` nearly fill it; longer keys would misalign. Minor.
- **No color / no visual hierarchy.** Output is plain (no ANSI even to a TTY-ish pipe). For
a compliance tool, flagging copyleft/violations in red and headings in bold would make the
risk pop. At minimum the `(none)` and copyleft rows deserve a marker (`!`).
- **Large repos dump everything.** Full grouped view on 96 files = 125 lines. With no
`--summary`-by-default-over-N and no problems filter, the signal-to-noise is low. The
flat list under `--summary`-off is unbounded.
- **The findings block is the best part of the text output** and should be promoted/ported,
not buried below the rollups.
---
## Machine / LLM usefulness (JSON)
The schema is clean and stable, which is the right foundation. Gaps that specifically hurt
LLM/dashboard use:
- **No totals/derived fields.** Every consumer re-derives `total`, `headered`, `coverage`,
`copyleftCount`. The text renderer already computes all of this in `buildFindings` — it
just isn't in the JSON. Ship a `findings`/`summary` object in JSON.
- **`violations` is a flat string array of opaque tokens.** `["policy-violation"]` cannot be
reasoned over. An LLM can't tell the user *which* license or rule without inventing it.
Make each violation an object: `{rule, severity, license, files:[...], message}`.
- **Risk flags absent.** There is `categoryCounts` with `network-copyleft: 2`, but no
boolean/severity the consumer can branch on. A `riskLevel` per license or per group, or a
top-level `hasCopyleft`/`worstCategory`, would let a dashboard color a badge without a
hardcoded category list.
- **Groups carry no breakdown.** `groups[]` is `{key, count, files[]}`. For an LLM doing
"summarize compliance by directory" the group needs its own `licenseCounts`/`categoryCounts`
/`copyleft` so it doesn't have to re-aggregate `files[]` (and under `--summary`, `files`
is gone, so re-aggregation is *impossible*).
- **Summary-trimming the JSON is the wrong default for machines.** Stripping `files`/
`dependencies` under `--summary` is fine for text/markdown (human ergonomics), but a JSON
consumer usually wants *complete* data and will do its own projection. Recommend: JSON
ignores `--summary` for trimming (always complete), or gates trimming behind an explicit
`--json-compact`. At minimum, when groups are summary-trimmed, still emit per-group
aggregate counts so the data isn't lossy.
- Good: `omitempty` on optional file fields keeps records tight; `hasHeader` boolean is
clean; resolution is a string enum.
---
## Markdown
- **Paste-into-PR quality is decent** — proper tables, code-fenced paths, per-group `###`
headings, a `_Skipped (uneditable): N_` note. A reviewer can read it.
- **But Markdown is missing the findings block entirely.** The header jumps from
`**Result:** FAIL` straight to `## By SPDX id`. None of coverage / copyleft / unknown /
*why it failed* appears. The single most useful thing to paste into a PR ("this PR
introduces AGPL, here's the exposure") is absent.
- **No summary/TL;DR up top, no totals in the tables.** A `> 78% headered, 2 copyleft files,
policy FAIL` callout would make it a real report.
- Violations render as a bare bullet list of the same opaque tokens.
---
## Surprising / confusing / wrong
- **`policy: FAIL (1: policy-violation)` with no cause** — surprising for a compliance tool
whose whole job is to explain exposure. (The default policy fails on the AGPL present in
`web/js`, but you'd never know that from the output.)
- **`GPL-3.0-only` is a recognized SPDX id the tool refuses to render** a header for
(`apply` errors: "recognized ... but license-tool cannot render it"). Limited template set;
worth documenting which ids are renderable, since it surprised me mid-test.
- **`apply` refuses on a dirty git tree** (sensible) but this makes scripting a multi-license
scaffold awkward — every subtree apply needs an intervening commit. Not an audit issue, but
noted while building fixtures.
- **Directory grouping silently collapsing `src/core`+`src/util` into `src`** is easy to
misread as "all of src is one license."
---
## Prioritized improvements
### Quick wins (small, high leverage)
1. **Expand `policy-violation` into a structured cause.** *Rationale: the verdict is the
headline and it's currently unexplainable; biggest ROI for both humans and LLMs.*
```
policy violations:
copyleft-not-allowed: AGPL-3.0-or-later (2 files: web/js/app.js, web/js/lib.js)
```
JSON: `"violations":[{"rule":"copyleft-not-allowed","license":"AGPL-3.0-or-later","severity":"high","files":["web/js/app.js","web/js/lib.js"]}]`
2. **Put `findings` in JSON and Markdown, not just text.** *Rationale: the best content
already exists (`buildFindings`); it's a renderer gap, near-zero new logic.*
JSON: `"findings":{"sourceTotal":9,"headered":7,"missing":2,"coverage":0.78,"copyleft":["AGPL-3.0-or-later"],"unknown":0}`
3. **Add totals + percentages to every count table.** *Rationale: stops every consumer
re-summing; one line per table.*
```
by category:
network-copyleft 2 (22%)
permissive 5 (56%)
unknown 2 (22%)
total 9
```
4. **Natural-sort (or offer `--sort count|name`) for groups/counts.** *Rationale: `pkg10`
before `pkg2` is visibly wrong; count-desc surfaces the dominant license first.*
5. **Rename the missing-header bucket from `(none)` to `(no-header)`.** *Rationale: removes
the overload with the empty-section placeholder; trivial.*
6. **Mark risk in text output** (e.g. trailing ` !copyleft` or a leading `*` on copyleft/
none rows; respect `NO_COLOR`). *Rationale: a compliance reader should see risk without
reading every line.*
### Bigger bets (more design, more value)
7. **Per-group breakdown / risk flag.** Every `Group` carries its own `licenseCounts`,
`categoryCounts`, and a `copyleft`/`riskLevel`. *Rationale: makes `--group-by directory`
actually useful (which dirs hold copyleft) and lets JSON groups stand alone under
`--summary`.*
```
source files by directory:
web (2) AGPL-3.0-or-later 2 [COPYLEFT]
src (4) MIT 2, Apache-2.0 2
```
8. **Multi-dimension / cross-tab grouping** (`--group-by directory,license`). *Rationale:
"which directories introduce which licenses" is the central compliance question and is
currently unanswerable.*
9. **A `--only` / `--filter` problems mode** (`--only missing,unknown,copyleft,violations`).
*Rationale: on real repos the problem files are a tiny fraction; surfacing only them is
what a reviewer and an LLM both want.*
10. **Group dependencies too** (`--group-deps-by license|ecosystem|resolution`), and keep
a dep rollup in `--summary`. *Rationale: deps are often the bigger compliance risk and
are currently entirely ungroupable and dropped from summaries.*
11. **Directory grouping depth control** (`--group-by directory:2` or full-path mode).
*Rationale: top-segment-only collapses monorepos into meaningless buckets.*
12. **Decouple JSON from `--summary` trimming** (always-complete JSON, or `--json-compact`).
*Rationale: machines want full data + their own projection; lossy summary JSON forces
a second full run.*
### Specifically valuable for LLM consumption
- **Structured violations** (#1) — turns "it failed somehow" into an actionable,
attributable fact the model can repeat verbatim.
- **A top-level `findings`/`totals` object** (#2, #3) — lets the model state coverage and
risk without arithmetic it might get wrong.
- **Per-group aggregates that survive `--summary`** (#7, #12) — so the model can summarize a
grouped report without the (now-stripped) file list.
- **An explicit `riskLevel`/`worstCategory` field** — so the model branches on a value
instead of pattern-matching category strings against memorized copyleft knowledge.
@@ -0,0 +1,163 @@
# Clean-Room Review 2 — `audit` Grouping & Reporting
Reviewer: independent (engineer + LLM-consumer lens). Skeptical, evidence-based.
Date: 2026-06-08. Branch: `feature/GH-29-init-tui-wizard`.
Binary built to `/tmp/cr2-lt` from `cmd/license-tool` (clean build, no tracked files touched).
## Test rig
Throwaway git repo at `/tmp/cr2repo`. Real headers applied with the tool's own
`apply --write --force`, one license per subtree so groupings have something to chew on:
- `src/core/*.go` → MIT (one file deliberately stripped of its header → `(no-header)`)
- `src/util/{c.go,d.py}` → Apache-2.0
- `scripts/{f.sh,g.py}` → AGPL-3.0-only
- `vendor/lib/e.go` → MIT
- `.license-tool.yaml` committed with `policy: { allow: [MIT] }` so Apache/AGPL fire violations
- `go.mod` with a `require` to exercise the dependency path
File mix: Go, Python, Shell, YAML across 4 directory subtrees and 2 depths. Every flag
combination was run across `text`, `json`, and `markdown`.
---
## Prior-issue verdicts
### 1. Grouped/summary views had no risk signal; `--group-by directory` lost license info — ADDRESSED
Every group now carries a per-group `[risk: …]` and (for non-license groupings) a
`licenses:` breakdown. `--group-by directory` shows both, in all three formats. JSON
groups carry `key/count/risk/licenses{}/files[]`. Markdown renders per-group `risk:` and a
`Licenses:` line plus a file table. Solid.
### 2. `policy-violation` was opaque — ADDRESSED
File-attributable violations now name license + rule + file. Text/markdown:
`scripts/f.sh: license "AGPL-3.0-only" is not on the allow list`. Markdown gives a real
table with separate `Condition | License | Location | Detail` columns. JSON
`violationDetails[]` carries structured `{condition, spdxId, path, message}`. An LLM can
branch on `condition`/`spdxId` without string-parsing. This is the biggest improvement.
### 3. No totals or percentages — ADDRESSED (text/markdown), PARTIAL (JSON)
Text and markdown rollups now show per-row `%` and a `total` row. JSON deliberately does
**not** carry percentages or totals — it ships raw count maps (`licenseCounts{}` etc.) and
expects the consumer to compute. Defensible (machines can divide), but worth noting it is
not symmetric with the human formats. Counts-only in JSON is fine; the asymmetry is a
documentation footnote, not a bug.
### 4. `findings` block existed only in text — ADDRESSED
`findings` is present in all three. JSON `findings{}` is the richest: explicit
`riskLevel`, `worstCategory`, `sourceTotal/Headered/Missing`, `unknownCount`, `copyleft[]`,
and `depsScanned/Total/Resolved/Unresolved`. Markdown has a `## Findings` section. Good for
LLMs — a model can read one object and decide pass/fail/triage.
### 5. Lexical-only sort; no sort-by-count — ADDRESSED
`--sort count` works and reorders rollups and groups by descending count (ties fall back to
key order, so output stays byte-stable). `--sort key` remains the default.
### 6. Directory grouping was top-segment only — ADDRESSED
`--depth N` works. At `--depth 1`, `src/core` and `src/util` collapse to `src`; at
`--depth 2` they split correctly into `src/core` and `src/util` with independent risk and
license breakdowns. Behaves as documented.
### 7. No "problems only" filter (`--only missing,copyleft,violations`) — STILL OPEN
`--only` is not a flag (`unknown flag: --only`). There is no way to filter the report to
just the failing rows. For large trees an engineer still has to eyeball or post-filter, and
an LLM has to ingest the whole file list to find the 3 violations. This is the most
impactful remaining gap.
### 8. Dependencies couldn't be grouped; dropped from `--summary` — PARTIAL
- Dropped-from-summary: ADDRESSED. JSON `--summary` `findings{}` retains
`depsScanned/depsTotal/depsResolved/depsUnresolved`, so dependency posture survives the
trim.
- Grouped: STILL OPEN. `--group-by dependency` is rejected:
`unknown group-by dimension "dependency" (expected license|category|type|directory)`.
Dependencies cannot be grouped by license/ecosystem. (Note: in my rig the resolver
reported 0 deps despite a `go.mod require`, likely module-cache dependent; I could not
exercise a populated dependency grouping, but the dimension simply does not exist.)
### 9. `(none)` overloaded as both missing-header bucket and empty placeholder — PARTIAL
Mostly fixed: the missing-header bucket is consistently `(no-header)` in rollup tables and
in every group's `licenses:` map; the empty config placeholder is `(none)`. They are now
visually distinct. **Residual inconsistency:** the `findings:` line still labels the same
bucket `none` (`license types: … none 2`), a third spelling for the same concept. Pick one
token (`(no-header)`) everywhere.
### 10. JSON `--summary` trimmed files/deps (wrong for machines) — STILL OPEN (by design)
JSON `--summary` still omits the `files` and `dependencies` arrays (confirmed in
`internal/report/report.go:858` `jsonSummaryReport`, and at runtime: `files`/`dependencies`
keys absent). The code comment states this is intentional ("counts only … no per-file or
per-dependency detail"). The original objection stands as a philosophical disagreement: a
machine asking for `--format json` arguably always wants the full record, and `--summary`
is a human ergonomic. Today a consumer must choose between summary-shaped findings and the
file list — they cannot get findings + machine detail in one trimmed call. Verdict: OPEN,
but it is a deliberate stance rather than a regression.
**Tally:** ADDRESSED 6 (1,2,4,5,6 + the summary-deps half of 8) · PARTIAL 3 (3, 8, 9) ·
STILL OPEN 2 (7, 10).
---
## Fresh assessment
### Genuinely good
- **Markdown is PR-ready.** The violations table with discrete License/Location/Detail
columns drops straight into a PR comment and reads well. Findings + rollups + grouped
tables are all coherent.
- **JSON is LLM-friendly where it counts.** `findings.riskLevel`/`worstCategory` and
structured `violationDetails[]` mean a model branches on enums, not prose. `schema`
versioning (`license-tool/report/v1`) is present and a good signal.
- **Risk + license breakdown on every group**, in every format, with depth control. This
was the headline ask and it lands.
- **Byte-stable output** (sorted maps, pre-sorted slices) — important for diffing audit
runs in CI and for caching.
### Still weak / confusing / suspect data
- **No problems-only filter (item 7).** Biggest usability gap for both audiences.
- **Group risk is local-only and can mislead.** With `policy.allow: [MIT]` and an AGPL↔Apache
hard-incompatibility flagged at repo level, the `src/util` (Apache) group still prints
`[risk: low]`. A reader scanning groups sees "low" next to a license that is part of a
repo-level hard conflict. Group risk should reflect policy violations attributed to that
group, not just the intrinsic license category.
- **`unknown` / missing-header rendered as `[risk: none]`.** Files with no header are an
audit *liability* (unknown obligations), but the category group prints `risk: none`. "none"
reads as "nothing to worry about." `unknown` would be more honest than `none`.
- **`.license-tool.yaml` counted as a missing-header "source file."** The config file itself
lands in `sourceMissing` and generates a `missing-header` violation. That inflates
`sourceTotal`/`sourceMissing` (9/2 where a human would say 8/1) and produces a violation
for the tool's own config. The tool should exclude its own config (and arguably data files
like YAML/JSON) from header expectations by default.
- **`none` vs `(no-header)` token drift** in the findings line (item 9 residual).
- **`--summary` JSON can't also carry detail (item 10).** No way to get findings + machine
file records in one trimmed response.
- **Dependency resolution returned 0** on a repo with a `go.mod require` — could not verify
the dep path end-to-end; may be environment-specific, but worth a smoke test in CI with a
populated module cache.
### New problems / regressions
- No outright regression observed; the full (non-summary) JSON shape is preserved as
intended. The new concerns above (config-as-source-file, local-only group risk,
`risk: none` for unknowns) are pre-existing semantics now made more visible by the
richer output, not breakage introduced by the grouping work.
---
## Prioritized next steps
Quick wins
1. **Add `--only missing,copyleft,violations` (item 7).** Highest value/effort ratio; makes
the report actionable for large trees and cheap for LLMs to consume.
2. **Exclude the tool's own `.license-tool.yaml` (and ideally data files) from header
expectations.** Stops the tool flagging its own config and fixes inflated source counts.
3. **Unify the missing-header token to `(no-header)` in the `findings` line** (drop `none`).
One-line consistency fix.
4. **Render unknown/missing-header group risk as `unknown`, not `none`.** Avoids a false
"all clear" read.
Bigger bets
5. **Make group risk policy-aware.** Roll attributed policy violations (allow-list, hard
incompatibilities) into each group's risk so a group containing a conflicting license
doesn't read `low`. Most likely to change an engineer's triage decision.
6. **Add `--group-by dependency` (item 8) and verify the resolver in CI.** Dependencies are
half the license-risk surface; they should be groupable by license/ecosystem like source.
7. **Reconsider JSON `--summary` (item 10):** either always emit `files`/`dependencies` for
`--format json` (treat `--summary` as human-only), or add `--fields`/`--include-files` so a
machine can request findings + detail in one call.
+7 -5
View File
@@ -23,9 +23,11 @@ import (
"github.com/KofTwentyTwo/license-tool/internal/spdx"
)
// repoConfigName is the committed, per-repo config file discovered at the scan
// root. It doubles as the apply input and the check expectation for a repo.
const repoConfigName = ".license-tool.yaml"
// RepoConfigName is the committed, per-repo config file discovered at the scan
// root. It doubles as the apply input and the check expectation for a repo, and is
// the basename the audit excludes from source/header coverage (tool metadata, not
// coverable source).
const RepoConfigName = ".license-tool.yaml"
// userConfigRel is the user/global config path relative to $XDG_CONFIG_HOME.
const userConfigRel = "license-tool/config.yaml"
@@ -238,7 +240,7 @@ var renderFile = RenderFile
// committed config, so an existing target is a hard error unless the caller opted in
// with force (the --force flag). The 0o644 mode matches a normal committed text file.
func WriteFile(path string, cfg model.Config, force bool) (string, error) {
target := filepath.Join(path, repoConfigName)
target := filepath.Join(path, RepoConfigName)
if !force && fileExists(target) {
return "", fmt.Errorf("config: %s already exists (use --force)", target)
}
@@ -674,7 +676,7 @@ func repoConfigPath(scanPath, configFlag string) (path string, explicit bool) {
if configFlag != "" {
return configFlag, true
}
return filepath.Join(scanPath, repoConfigName), false
return filepath.Join(scanPath, RepoConfigName), false
}
// fileExists reports whether path names an existing regular-readable file.
+24 -24
View File
@@ -223,7 +223,7 @@ file_types:
func TestLoadFile(t *testing.T) {
t.Run("valid file seeds from defaults", func(t *testing.T) {
dir := t.TempDir()
p := filepath.Join(dir, repoConfigName)
p := filepath.Join(dir, RepoConfigName)
writeFile(t, p, `
license: MIT
holder: Acme
@@ -257,7 +257,7 @@ style: reuse
t.Run("invalid style errors", func(t *testing.T) {
dir := t.TempDir()
p := filepath.Join(dir, repoConfigName)
p := filepath.Join(dir, RepoConfigName)
writeFile(t, p, "style: bogus\n")
if _, err := LoadFile(p); err == nil {
t.Fatal("LoadFile with invalid style should error")
@@ -266,7 +266,7 @@ style: reuse
t.Run("explicit manage_license_file false", func(t *testing.T) {
dir := t.TempDir()
p := filepath.Join(dir, repoConfigName)
p := filepath.Join(dir, RepoConfigName)
writeFile(t, p, "manage_license_file: false\n")
cfg, err := LoadFile(p)
if err != nil {
@@ -344,7 +344,7 @@ func TestFileTypeOverrides(t *testing.T) {
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
dir := t.TempDir()
p := filepath.Join(dir, repoConfigName)
p := filepath.Join(dir, RepoConfigName)
writeFile(t, p, tt.yaml+"\n")
cfg, err := LoadFile(p)
if tt.wantErr {
@@ -454,7 +454,7 @@ year: current
// Repo layer overrides holder and style; inherits nothing else from user
// except where it stays silent (license, year here).
repo := t.TempDir()
writeFile(t, filepath.Join(repo, repoConfigName), `
writeFile(t, filepath.Join(repo, RepoConfigName), `
holder: RepoHolder
style: notice
`)
@@ -483,7 +483,7 @@ style: notice
isolateXDG(t)
repo := t.TempDir()
// Discovered repo file would set MIT; explicit --config sets Apache.
writeFile(t, filepath.Join(repo, repoConfigName), "license: MIT\nholder: A\n")
writeFile(t, filepath.Join(repo, RepoConfigName), "license: MIT\nholder: A\n")
explicit := filepath.Join(t.TempDir(), "custom.yaml")
writeFile(t, explicit, "license: Apache-2.0\nholder: B\n")
@@ -509,7 +509,7 @@ style: notice
xdg := isolateXDG(t)
writeFile(t, filepath.Join(xdg, "license-tool", "config.yaml"), "license: MIT\nholder: A\nexclude: [\"**/vendor/**\"]\n")
repo := t.TempDir()
writeFile(t, filepath.Join(repo, repoConfigName), "exclude: [\"**/generated/**\"]\n")
writeFile(t, filepath.Join(repo, RepoConfigName), "exclude: [\"**/generated/**\"]\n")
cfg, err := Resolve(repo, Flags{Exclude: []string{"**/*.pb.go"}}, Options{Interactive: false})
if err != nil {
t.Fatalf("Resolve error: %v", err)
@@ -652,7 +652,7 @@ func TestResolveBadConfigSurfaces(t *testing.T) {
t.Run("invalid year in repo config errors", func(t *testing.T) {
isolateXDG(t)
repo := t.TempDir()
writeFile(t, filepath.Join(repo, repoConfigName), "license: MIT\nholder: A\nyear: nope\n")
writeFile(t, filepath.Join(repo, RepoConfigName), "license: MIT\nholder: A\nyear: nope\n")
if _, err := Resolve(repo, Flags{}, Options{Interactive: false}); err == nil {
t.Fatal("invalid year in config should error")
}
@@ -661,7 +661,7 @@ func TestResolveBadConfigSurfaces(t *testing.T) {
t.Run("invalid fail_on in repo config errors", func(t *testing.T) {
isolateXDG(t)
repo := t.TempDir()
writeFile(t, filepath.Join(repo, repoConfigName), "license: MIT\nholder: A\npolicy:\n fail_on: [bogus]\n")
writeFile(t, filepath.Join(repo, RepoConfigName), "license: MIT\nholder: A\npolicy:\n fail_on: [bogus]\n")
if _, err := Resolve(repo, Flags{}, Options{Interactive: false}); err == nil {
t.Fatal("invalid fail_on in config should error")
}
@@ -670,7 +670,7 @@ func TestResolveBadConfigSurfaces(t *testing.T) {
t.Run("invalid policy required expression errors with field and value", func(t *testing.T) {
isolateXDG(t)
repo := t.TempDir()
writeFile(t, filepath.Join(repo, repoConfigName), "license: MIT\nholder: A\npolicy:\n required: NOT-A-LICENSE\n")
writeFile(t, filepath.Join(repo, RepoConfigName), "license: MIT\nholder: A\npolicy:\n required: NOT-A-LICENSE\n")
_, err := Resolve(repo, Flags{}, Options{Interactive: false})
if err == nil {
t.Fatal("invalid policy.required should error")
@@ -683,7 +683,7 @@ func TestResolveBadConfigSurfaces(t *testing.T) {
t.Run("policy required expression rejected because enforcement is exact id", func(t *testing.T) {
isolateXDG(t)
repo := t.TempDir()
writeFile(t, filepath.Join(repo, repoConfigName), "license: MIT\nholder: A\npolicy:\n required: MIT OR Apache-2.0\n")
writeFile(t, filepath.Join(repo, RepoConfigName), "license: MIT\nholder: A\npolicy:\n required: MIT OR Apache-2.0\n")
_, err := Resolve(repo, Flags{}, Options{Interactive: false})
if err == nil {
t.Fatal("policy.required expression should error")
@@ -696,7 +696,7 @@ func TestResolveBadConfigSurfaces(t *testing.T) {
t.Run("invalid policy allow expression errors with field and value", func(t *testing.T) {
isolateXDG(t)
repo := t.TempDir()
writeFile(t, filepath.Join(repo, repoConfigName), "license: MIT\nholder: A\npolicy:\n allow: [MIT AND]\n")
writeFile(t, filepath.Join(repo, RepoConfigName), "license: MIT\nholder: A\npolicy:\n allow: [MIT AND]\n")
_, err := Resolve(repo, Flags{}, Options{Interactive: false})
if err == nil {
t.Fatal("invalid policy.allow should error")
@@ -709,7 +709,7 @@ func TestResolveBadConfigSurfaces(t *testing.T) {
t.Run("policy allow expression rejected because enforcement is exact id", func(t *testing.T) {
isolateXDG(t)
repo := t.TempDir()
writeFile(t, filepath.Join(repo, repoConfigName), "license: MIT\nholder: A\npolicy:\n allow: [MIT OR Apache-2.0]\n")
writeFile(t, filepath.Join(repo, RepoConfigName), "license: MIT\nholder: A\npolicy:\n allow: [MIT OR Apache-2.0]\n")
_, err := Resolve(repo, Flags{}, Options{Interactive: false})
if err == nil {
t.Fatal("policy.allow expression should error")
@@ -722,7 +722,7 @@ func TestResolveBadConfigSurfaces(t *testing.T) {
t.Run("invalid policy deny expression errors with field and value", func(t *testing.T) {
isolateXDG(t)
repo := t.TempDir()
writeFile(t, filepath.Join(repo, repoConfigName), "license: MIT\nholder: A\npolicy:\n deny: [GPL-2.0-typo]\n")
writeFile(t, filepath.Join(repo, RepoConfigName), "license: MIT\nholder: A\npolicy:\n deny: [GPL-2.0-typo]\n")
_, err := Resolve(repo, Flags{}, Options{Interactive: false})
if err == nil {
t.Fatal("invalid policy.deny should error")
@@ -735,7 +735,7 @@ func TestResolveBadConfigSurfaces(t *testing.T) {
t.Run("policy deny expression rejected because enforcement is exact id", func(t *testing.T) {
isolateXDG(t)
repo := t.TempDir()
writeFile(t, filepath.Join(repo, repoConfigName), "license: MIT\nholder: A\npolicy:\n deny: [GPL-2.0-only AND Apache-2.0]\n")
writeFile(t, filepath.Join(repo, RepoConfigName), "license: MIT\nholder: A\npolicy:\n deny: [GPL-2.0-only AND Apache-2.0]\n")
_, err := Resolve(repo, Flags{}, Options{Interactive: false})
if err == nil {
t.Fatal("policy.deny expression should error")
@@ -748,7 +748,7 @@ func TestResolveBadConfigSurfaces(t *testing.T) {
t.Run("policy from config carried through", func(t *testing.T) {
isolateXDG(t)
repo := t.TempDir()
writeFile(t, filepath.Join(repo, repoConfigName), `
writeFile(t, filepath.Join(repo, RepoConfigName), `
license: AGPL-3.0-or-later
holder: Kingsrook, LLC
policy:
@@ -775,7 +775,7 @@ policy:
t.Run("valid policy ids including unrenderable ids are preserved", func(t *testing.T) {
isolateXDG(t)
repo := t.TempDir()
writeFile(t, filepath.Join(repo, repoConfigName), `
writeFile(t, filepath.Join(repo, RepoConfigName), `
license: MIT
holder: Acme
policy:
@@ -936,7 +936,7 @@ func TestResolveUserLayerErrors(t *testing.T) {
func TestResolveRepoLayerLoadError(t *testing.T) {
isolateXDG(t)
repo := t.TempDir()
writeFile(t, filepath.Join(repo, repoConfigName), "license: [unterminated\n")
writeFile(t, filepath.Join(repo, RepoConfigName), "license: [unterminated\n")
if _, err := Resolve(repo, Flags{}, Options{Interactive: false}); err == nil {
t.Fatal("malformed repo config should error from Resolve")
}
@@ -946,7 +946,7 @@ func TestResolveRepoLayerLoadError(t *testing.T) {
// file that reads fine but fails YAML decoding.
func TestLoadSchemaParseError(t *testing.T) {
dir := t.TempDir()
p := filepath.Join(dir, repoConfigName)
p := filepath.Join(dir, RepoConfigName)
writeFile(t, p, "license: [unterminated\n")
_, err := loadSchema(p)
if err == nil {
@@ -1030,7 +1030,7 @@ func TestResolveSkipsUserLayerWithoutHome(t *testing.T) {
t.Setenv("XDG_CONFIG_HOME", "")
t.Setenv("HOME", "")
repo := t.TempDir()
writeFile(t, filepath.Join(repo, repoConfigName), "license: MIT\nholder: Acme\n")
writeFile(t, filepath.Join(repo, RepoConfigName), "license: MIT\nholder: Acme\n")
cfg, err := Resolve(repo, Flags{}, Options{Interactive: false})
if err != nil {
t.Fatalf("Resolve error: %v", err)
@@ -1115,7 +1115,7 @@ func TestRenderFile(t *testing.T) {
// Decode the rendered bytes back via the real loader and assert the fields.
dir := t.TempDir()
p := filepath.Join(dir, repoConfigName)
p := filepath.Join(dir, RepoConfigName)
writeFile(t, p, string(data))
got, err := LoadFile(p)
if err != nil {
@@ -1184,8 +1184,8 @@ func TestWriteFile(t *testing.T) {
if err != nil {
t.Fatalf("WriteFile error: %v", err)
}
if target != filepath.Join(dir, repoConfigName) {
t.Errorf("target = %q, want %q", target, filepath.Join(dir, repoConfigName))
if target != filepath.Join(dir, RepoConfigName) {
t.Errorf("target = %q, want %q", target, filepath.Join(dir, RepoConfigName))
}
// The written file must load back to the same identity fields.
got, lerr := LoadFile(target)
@@ -1247,7 +1247,7 @@ func TestWriteFile(t *testing.T) {
t.Fatalf("WriteFile should surface the render error, got %v", err)
}
// A render failure must abort before any file is written.
if _, statErr := os.Stat(filepath.Join(dir, repoConfigName)); !os.IsNotExist(statErr) {
if _, statErr := os.Stat(filepath.Join(dir, RepoConfigName)); !os.IsNotExist(statErr) {
t.Errorf("no file should be written when render fails")
}
})
+36
View File
@@ -68,6 +68,23 @@ func (c Category) String() string {
}
}
// Risk renders the obligation severity of a category as a coarse, sortable token
// ("high"|"medium"|"low"|"unknown"), so reports and machine consumers can branch on a
// single value instead of pattern-matching category names. Strong/network copyleft and
// proprietary are high; weak copyleft is medium; permissive is low.
func (c Category) Risk() string {
switch c {
case CategoryStrongCopyleft, CategoryNetworkCopyleft, CategoryProprietary:
return "high"
case CategoryWeakCopyleft:
return "medium"
case CategoryPermissive:
return "low"
default:
return "unknown"
}
}
// HeaderStyle selects which parts of the canonical header are emitted into a file.
type HeaderStyle int
@@ -383,6 +400,25 @@ type Report struct {
FileTypeCounts map[string]int
// Violations lists repo-level policy violation tokens.
Violations []string
// ViolationDetails carries every policy finding (file, dependency, and repo level)
// with its attribution: the condition, the offending SPDX id, the file/dependency
// path, and a human-readable message. WHY both this and Violations: Violations is
// the legacy repo-level token set; ViolationDetails is the full, attributable set
// reports and machine consumers need to explain WHICH license/rule/file failed.
ViolationDetails []ViolationDetail
// Passed is true when no fail_on condition tripped (drives check exit code).
Passed bool
}
// ViolationDetail is one policy finding with its attribution, so a reader (or an LLM)
// can see the cause, not just a token.
type ViolationDetail struct {
// Condition is the fail_on category this finding belongs to.
Condition FailCondition
// SPDXID is the offending license id, if applicable.
SPDXID string
// Path is the offending file or dependency label; empty for whole-repo findings.
Path string
// Message is the human-readable explanation.
Message string
}
+18
View File
@@ -28,6 +28,24 @@ func TestCategoryString(t *testing.T) {
}
}
func TestCategoryRisk(t *testing.T) {
tests := []struct {
category Category
want string
}{
{CategoryStrongCopyleft, "high"},
{CategoryNetworkCopyleft, "high"},
{CategoryProprietary, "high"},
{CategoryWeakCopyleft, "medium"},
{CategoryPermissive, "low"},
{CategoryUnknown, "unknown"},
{Category(99), "unknown"},
}
for _, tt := range tests {
assert.Equal(t, tt.want, tt.category.Risk())
}
}
func TestHeaderStyleString(t *testing.T) {
tests := []struct {
name string
+60 -5
View File
@@ -52,6 +52,12 @@ type Findings struct {
Passed bool
// Violations are the repo-level violation tokens, sorted, surfaced when failing.
Violations []string
// RiskLevel is the worst obligation severity among the headered source licenses
// ("high"|"medium"|"low"|"none"), so a reader or model can branch on one value.
RiskLevel string
// WorstCategory is the license category contributing RiskLevel (empty when none).
WorstCategory string
}
// buildFindings folds a finished model.Report into a Findings summary. It is pure
@@ -64,6 +70,7 @@ func buildFindings(r model.Report) Findings {
}
copyleftSeen := map[string]bool{}
worst := worstRisk{}
for _, fr := range r.Files {
// Coverable means a file that participates in license management. Skipped
// files (binary, uncommentable, unknown type) carry no managed header and are
@@ -84,10 +91,12 @@ func buildFindings(r model.Report) Findings {
f.UnknownCount++
}
switch categoryToken(id) {
case model.CategoryWeakCopyleft.String(),
model.CategoryStrongCopyleft.String(),
model.CategoryNetworkCopyleft.String():
cat := classifyCategory(id)
worst.observe(cat)
switch cat {
case model.CategoryWeakCopyleft,
model.CategoryStrongCopyleft,
model.CategoryNetworkCopyleft:
copyleftSeen[id] = true
}
} else {
@@ -96,6 +105,7 @@ func buildFindings(r model.Report) Findings {
}
f.Copyleft = sortedKeys(copyleftSeen)
f.RiskLevel, f.WorstCategory = worst.result()
if len(r.Dependencies) > 0 {
f.DepsScanned = true
@@ -129,7 +139,7 @@ func (f Findings) licenseSummary() string {
parts = append(parts, fmt.Sprintf("%s %d", id, f.LicenseCounts[id]))
}
if f.SourceMissing > 0 {
parts = append(parts, fmt.Sprintf("none %d", f.SourceMissing))
parts = append(parts, fmt.Sprintf("%s %d", noLicenseKey, f.SourceMissing))
}
if len(parts) == 0 {
return "(none)"
@@ -166,6 +176,7 @@ func renderFindings(bw *errWriter, f Findings) {
bw.printf(" license types: %s\n", f.licenseSummary())
bw.printf(" unknown/unrecognized: %d\n", f.UnknownCount)
bw.printf(" copyleft: %s\n", f.copyleftSummary())
bw.printf(" risk: %s\n", f.riskSummary())
if f.DepsScanned {
bw.printf(" dependencies: %d (resolved %d, unresolved %d)\n", f.DepsTotal, f.DepsResolved, f.DepsUnresolved)
}
@@ -173,6 +184,50 @@ func renderFindings(bw *errWriter, f Findings) {
bw.printf("\n")
}
// worstRisk tracks the highest-severity license category observed across headered
// source files, for the findings RiskLevel. Ties on risk rank break toward the higher
// Category enum so the result is deterministic.
type worstRisk struct {
cat model.Category
have bool
}
func (w *worstRisk) observe(c model.Category) {
if !w.have || riskRank(c) > riskRank(w.cat) || (riskRank(c) == riskRank(w.cat) && c > w.cat) {
w.cat = c
w.have = true
}
}
func (w worstRisk) result() (level, category string) {
if !w.have {
return "none", ""
}
return w.cat.Risk(), w.cat.String()
}
// riskRank ranks a category's obligation severity for "worst" comparison.
func riskRank(c model.Category) int {
switch c.Risk() {
case "high":
return 3
case "medium":
return 2
case "low":
return 1
default:
return 0
}
}
// riskSummary renders the risk level and the worst category, or "none".
func (f Findings) riskSummary() string {
if f.WorstCategory == "" {
return "none"
}
return fmt.Sprintf("%s (%s)", f.RiskLevel, f.WorstCategory)
}
// sortedKeys returns the keys of a string-keyed map in ascending order, the canonical
// ordering used throughout the renderers for determinism.
func sortedKeys[V any](m map[string]V) []string {
+2 -2
View File
@@ -37,7 +37,7 @@ func TestBuildFindingsSourceCoverageAndLicenseMix(t *testing.T) {
assert.Equal(t, 1, f.LicenseCounts["GPL-3.0-or-later"])
// License mix is sorted by id, with the missing bucket last.
assert.Equal(t, "GPL-3.0-or-later 1, MIT 2, none 1", f.licenseSummary())
assert.Equal(t, "GPL-3.0-or-later 1, MIT 2, (no-header) 1", f.licenseSummary())
}
func TestBuildFindingsUnknownAndCopyleft(t *testing.T) {
@@ -118,7 +118,7 @@ func TestRenderFindingsBlock(t *testing.T) {
assert.Contains(t, out, "findings:")
assert.Contains(t, out, "source files: 2 (headered 1, missing 1)")
assert.Contains(t, out, "license types: MIT 1, none 1")
assert.Contains(t, out, "license types: MIT 1, (no-header) 1")
assert.Contains(t, out, "unknown/unrecognized: 0")
assert.Contains(t, out, "copyleft: none")
assert.Contains(t, out, "dependencies: 1 (resolved 1, unresolved 0)")
+343
View File
@@ -0,0 +1,343 @@
package report
import (
"fmt"
"path/filepath"
"sort"
"strings"
"github.com/KofTwentyTwo/license-tool/internal/model"
"github.com/KofTwentyTwo/license-tool/internal/policy"
)
// GroupDimension selects how the source-file listing is organized for the
// --group-by option. GroupNone is the default flat listing.
type GroupDimension int
const (
// GroupNone is the default: a flat, ungrouped file listing.
GroupNone GroupDimension = iota
// GroupLicense groups files by detected SPDX id.
GroupLicense
// GroupCategory groups files by license category (permissive, copyleft, ...).
GroupCategory
// GroupType groups files by matched file-type name.
GroupType
// GroupDirectory groups files by top-level path segment.
GroupDirectory
)
// String renders the dimension as its --group-by token (and the word used in
// rendered section headers). GroupNone renders as "none".
func (d GroupDimension) String() string {
switch d {
case GroupLicense:
return "license"
case GroupCategory:
return "category"
case GroupType:
return "type"
case GroupDirectory:
return "directory"
default:
return "none"
}
}
// ParseGroupBy parses a --group-by token. An empty token is GroupNone (no error);
// an unrecognized token is a usage error.
func ParseGroupBy(raw string) (GroupDimension, error) {
switch raw {
case "":
return GroupNone, nil
case "license":
return GroupLicense, nil
case "category":
return GroupCategory, nil
case "type":
return GroupType, nil
case "directory":
return GroupDirectory, nil
default:
return GroupNone, fmt.Errorf("report: unknown group-by dimension %q (expected license|category|type|directory)", raw)
}
}
// GroupSpec parameterizes GroupFiles: the dimension to group by and, for the
// directory dimension, how many leading path segments form the key (Depth, min 1).
type GroupSpec struct {
By GroupDimension
Depth int
}
// OnlyFilter restricts the source-file listing to "problem" files.
type OnlyFilter int
const (
// OnlyMissing keeps files with no managed header.
OnlyMissing OnlyFilter = iota
// OnlyUnknown keeps files whose detected license is unclassifiable.
OnlyUnknown
// OnlyCopyleft keeps files under a copyleft license (weak/strong/network).
OnlyCopyleft
// OnlyViolations keeps files carrying a policy violation.
OnlyViolations
)
// ParseOnly parses a comma-separated --only spec into filters. Empty yields none (no
// filtering); an unrecognized token is a usage error.
func ParseOnly(raw string) ([]OnlyFilter, error) {
var out []OnlyFilter
for _, tok := range strings.Split(raw, ",") {
tok = strings.TrimSpace(tok)
switch tok {
case "":
continue
case "missing":
out = append(out, OnlyMissing)
case "unknown":
out = append(out, OnlyUnknown)
case "copyleft":
out = append(out, OnlyCopyleft)
case "violations":
out = append(out, OnlyViolations)
default:
return nil, fmt.Errorf("report: unknown --only filter %q (expected missing|unknown|copyleft|violations)", tok)
}
}
return out, nil
}
// keepFile reports whether fr passes the --only filters (matches ANY). An empty
// filter set keeps everything; skipped files never match a problem filter.
func keepFile(fr model.FileResult, only []OnlyFilter) bool {
if len(only) == 0 {
return true
}
if fr.Skipped {
return false
}
for _, f := range only {
switch f {
case OnlyMissing:
if !fr.Detected.Present {
return true
}
case OnlyUnknown:
if fr.Detected.Present && fr.Detected.SPDXID != "" && classifyCategory(fr.Detected.SPDXID) == model.CategoryUnknown {
return true
}
case OnlyCopyleft:
switch classifyCategory(fr.Detected.SPDXID) {
case model.CategoryWeakCopyleft, model.CategoryStrongCopyleft, model.CategoryNetworkCopyleft:
return true
}
case OnlyViolations:
if len(fr.Violations) > 0 {
return true
}
}
}
return false
}
// Group is one bucket of the grouped source-file view: a key, the count of files in
// it, the worst obligation risk among its files, the license breakdown within it, and
// the files themselves (sorted by path).
type Group struct {
Key string
Count int
// Risk is the worst category risk among the group's files ("high"|"medium"|
// "low"|"none"), so directory/type groups carry a license-risk signal instead of
// being a license-blind count.
Risk string
// Licenses is the license breakdown within the group (SPDX id or "(no-header)" ->
// count), so a directory/type group shows WHICH licenses it mixes, not just a count.
Licenses map[string]int
Files []model.FileResult
}
// GroupFiles partitions the non-skipped source files of r per spec, returning the
// groups (sorted by key, files sorted by path) and the count of skipped files
// (binary/uncommentable/unknown) which are never grouped. GroupNone returns no
// groups. Pure and deterministic for identical input.
func GroupFiles(r model.Report, spec GroupSpec) (groups []Group, skipped int) {
// Repo-level hard incompatibilities are not attributed to any single file, so a
// group's risk would otherwise be blind to them (an Apache group beside AGPL would
// read "low"). Derive the incompatibility set from r's own files; callers that have
// narrowed r for the listing (e.g. --only) must use groupFilesWith with the full
// repo's set so the risk marker is not distorted by the filter.
return groupFilesWith(r, spec, incompatibleIDs(distinctSourceIDs(r.Files)))
}
// groupFilesWith is GroupFiles with an explicit repo-wide incompatibility set. The set
// must be computed over the full repo's distinct source ids (not a --only-narrowed
// listing), so a group's policy-aware risk reflects repo-level incompatibilities even
// when r.Files has been filtered down to the files actually being listed.
func groupFilesWith(r model.Report, spec GroupSpec, incompatIDs map[string]bool) (groups []Group, skipped int) {
buckets := map[string][]model.FileResult{}
for _, fr := range r.Files {
if fr.Skipped {
skipped++
continue
}
if spec.By == GroupNone {
continue
}
buckets[groupKeyDepth(fr, spec)] = append(buckets[groupKeyDepth(fr, spec)], fr)
}
keys := make([]string, 0, len(buckets))
for k := range buckets {
keys = append(keys, k)
}
sort.Strings(keys)
groups = make([]Group, 0, len(keys))
for _, k := range keys {
files := buckets[k]
sort.Slice(files, func(i, j int) bool { return files[i].Path < files[j].Path })
groups = append(groups, Group{
Key: k,
Count: len(files),
Risk: groupRisk(files, incompatIDs),
Licenses: licenseBreakdown(files),
Files: files,
})
}
return groups, skipped
}
// groupKeyDepth derives a file's bucket key, honoring the directory depth.
func groupKeyDepth(fr model.FileResult, spec GroupSpec) string {
if spec.By == GroupDirectory {
return topDirs(fr.Path, spec.Depth)
}
return groupKey(fr, spec.By)
}
// licenseBreakdown counts the license (or no-header) of each file in a group.
func licenseBreakdown(files []model.FileResult) map[string]int {
out := map[string]int{}
for _, fr := range files {
out[groupKey(fr, GroupLicense)]++
}
return out
}
// groupRisk returns the group's risk: the worst category risk among its files,
// escalated to "high" when the group carries a policy concern. A policy concern is
// a file whose license is party to a repo-level hard incompatibility (incompatIDs)
// or a file carrying a file-scoped policy violation (deny/allow/required breach).
// WHY escalate: a license-category-only risk is policy-blind -- an Apache group
// beside AGPL, or a deny-listed permissive license, both read "low" by category yet
// are real audit liabilities.
func groupRisk(files []model.FileResult, incompatIDs map[string]bool) string {
var w worstRisk
policyConcern := false
for _, fr := range files {
if fr.Detected.Present && fr.Detected.SPDXID != "" {
w.observe(classifyCategory(fr.Detected.SPDXID))
if incompatIDs[fr.Detected.SPDXID] {
policyConcern = true
}
}
if hasPolicyViolation(fr) {
policyConcern = true
}
}
if policyConcern {
return "high"
}
level, _ := w.result()
if level == "none" {
// A non-empty group with no classifiable license (all missing/headerless) is an
// audit liability, not "all clear" -- report it as unknown risk.
return "unknown"
}
return level
}
// incompatibleIDs returns the set of SPDX ids that are party to a curated hard
// incompatibility with another id in the same repo. ids is the distinct source-id
// set; the pairwise scan is over the (small) distinct set, not every file.
func incompatibleIDs(ids []string) map[string]bool {
out := map[string]bool{}
for i := 0; i < len(ids); i++ {
for j := i + 1; j < len(ids); j++ {
if policy.Incompatible(ids[i], ids[j]) {
out[ids[i]] = true
out[ids[j]] = true
}
}
}
return out
}
// hasPolicyViolation reports whether a file carries a file-scoped policy-violation
// token (allow/deny/required breach). Missing-header and unknown-license tokens are
// excluded: those are already reflected by the category-based risk (headerless ->
// unknown, unclassifiable id -> unknown) and are not policy escalations.
func hasPolicyViolation(fr model.FileResult) bool {
for _, tok := range fr.Violations {
if tok == model.FailOnPolicyViolation.String() {
return true
}
}
return false
}
// sortGroups orders groups by descending count (ties by key) when byCount is set,
// otherwise leaves the key-sorted order GroupFiles produced.
func sortGroups(groups []Group, byCount bool) {
if !byCount {
return
}
sort.SliceStable(groups, func(i, j int) bool {
if groups[i].Count != groups[j].Count {
return groups[i].Count > groups[j].Count
}
return groups[i].Key < groups[j].Key
})
}
// groupKey derives a file's bucket key for the given dimension.
func groupKey(fr model.FileResult, dim GroupDimension) string {
switch dim {
case GroupLicense:
if fr.Detected.Present && fr.Detected.SPDXID != "" {
return fr.Detected.SPDXID
}
return noLicenseKey
case GroupCategory:
if fr.Detected.Present && fr.Detected.SPDXID != "" {
return categoryToken(fr.Detected.SPDXID)
}
return model.CategoryUnknown.String()
default: // GroupType
if fr.FileType != "" {
return fr.FileType
}
return "(unknown type)"
}
}
// topDirs returns the first depth directory segments of a forward-slash path (the
// directory containing the file, capped at depth). A file with fewer leading
// directories than depth groups under its own directory; root-level files group
// under ".". Depth below 1 is treated as 1.
func topDirs(path string, depth int) string {
if depth < 1 {
depth = 1
}
p := filepath.ToSlash(path)
segments := strings.Split(p, "/")
if len(segments) <= 1 {
return "." // file at root, no directory
}
dirs := segments[:len(segments)-1] // drop the file name
if len(dirs) > depth {
dirs = dirs[:depth]
}
return strings.Join(dirs, "/")
}
+244
View File
@@ -0,0 +1,244 @@
package report
import (
"testing"
"github.com/KofTwentyTwo/license-tool/internal/model"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
func headered(path, ft, id string) model.FileResult {
return model.FileResult{Path: path, FileType: ft, Detected: model.DetectedHeader{Present: true, SPDXID: id}}
}
func TestParseGroupBy(t *testing.T) {
cases := map[string]GroupDimension{
"": GroupNone,
"license": GroupLicense,
"category": GroupCategory,
"type": GroupType,
"directory": GroupDirectory,
}
for in, want := range cases {
got, err := ParseGroupBy(in)
require.NoError(t, err, "ParseGroupBy(%q)", in)
assert.Equal(t, want, got)
}
_, err := ParseGroupBy("nonsense")
require.Error(t, err)
assert.Contains(t, err.Error(), "unknown group-by dimension")
}
func sampleReport() model.Report {
return model.Report{Files: []model.FileResult{
headered("src/a.go", "Go", "MIT"),
headered("src/b.go", "Go", "MIT"),
headered("web/c.ts", "TypeScript/JavaScript", "AGPL-3.0-or-later"),
{Path: "src/headerless.go", FileType: "Go"}, // non-skipped, no header
{Path: "img/logo.png", FileType: "", Skipped: true, SkipReason: "binary"}, // skipped
}}
}
func TestGroupFilesNone(t *testing.T) {
groups, skipped := GroupFiles(sampleReport(), GroupSpec{By: GroupNone})
assert.Empty(t, groups)
assert.Equal(t, 1, skipped)
}
func TestGroupFilesByLicense(t *testing.T) {
groups, skipped := GroupFiles(sampleReport(), GroupSpec{By: GroupLicense})
assert.Equal(t, 1, skipped)
// Keys sorted: "(no-header)" < "AGPL-3.0-or-later" < "MIT".
require.Len(t, groups, 3)
assert.Equal(t, "(no-header)", groups[0].Key)
assert.Equal(t, 1, groups[0].Count)
assert.Equal(t, "src/headerless.go", groups[0].Files[0].Path)
assert.Equal(t, "AGPL-3.0-or-later", groups[1].Key)
assert.Equal(t, "MIT", groups[2].Key)
assert.Equal(t, 2, groups[2].Count)
// Files within a group are path-sorted.
assert.Equal(t, "src/a.go", groups[2].Files[0].Path)
assert.Equal(t, "src/b.go", groups[2].Files[1].Path)
}
func TestGroupFilesByCategory(t *testing.T) {
groups, _ := GroupFiles(sampleReport(), GroupSpec{By: GroupCategory})
keys := map[string]int{}
for _, g := range groups {
keys[g.Key] = g.Count
}
assert.Equal(t, 2, keys["permissive"]) // MIT x2
assert.Equal(t, 1, keys["network-copyleft"]) // AGPL
assert.Equal(t, 1, keys["unknown"]) // headerless
}
func TestGroupFilesByType(t *testing.T) {
r := model.Report{Files: []model.FileResult{
headered("a.go", "Go", "MIT"),
{Path: "weird", FileType: ""}, // non-skipped, no file type
}}
groups, _ := GroupFiles(r, GroupSpec{By: GroupType})
keys := map[string]int{}
for _, g := range groups {
keys[g.Key] = g.Count
}
assert.Equal(t, 1, keys["Go"])
assert.Equal(t, 1, keys["(unknown type)"])
}
func TestGroupFilesByDirectory(t *testing.T) {
groups, _ := GroupFiles(sampleReport(), GroupSpec{By: GroupDirectory})
keys := map[string]int{}
for _, g := range groups {
keys[g.Key] = g.Count
}
assert.Equal(t, 3, keys["src"]) // a.go, b.go, headerless.go
assert.Equal(t, 1, keys["web"])
// img/logo.png is skipped, so "img" never appears.
_, hasImg := keys["img"]
assert.False(t, hasImg)
}
func TestGroupFilesDirectoryRoot(t *testing.T) {
r := model.Report{Files: []model.FileResult{headered("main.go", "Go", "MIT")}}
groups, _ := GroupFiles(r, GroupSpec{By: GroupDirectory})
require.Len(t, groups, 1)
assert.Equal(t, ".", groups[0].Key)
}
func TestTopDirs(t *testing.T) {
assert.Equal(t, ".", topDirs("main.go", 1))
assert.Equal(t, "src", topDirs("src/a.go", 1))
assert.Equal(t, "src", topDirs("src/sub/deep/a.go", 1)) // capped at depth 1
assert.Equal(t, "src/sub", topDirs("src/sub/deep/a.go", 2)) // depth 2
assert.Equal(t, "src", topDirs("src/a.go", 0)) // depth < 1 -> 1
}
// groupByKey returns the group with the given key, failing the test if absent.
func groupByKey(t *testing.T, groups []Group, key string) Group {
t.Helper()
for _, g := range groups {
if g.Key == key {
return g
}
}
t.Fatalf("no group with key %q in %v", key, groups)
return Group{}
}
func TestGroupRiskCategoryOnlyWhenNoPolicyConcern(t *testing.T) {
// sampleReport mixes MIT (permissive) and AGPL (network-copyleft). MIT and AGPL
// are NOT a curated hard incompatibility, so the MIT group must stay "low" (no
// false escalation), AGPL stays "high" by its category, and the headerless group
// is "unknown".
groups, _ := GroupFiles(sampleReport(), GroupSpec{By: GroupLicense})
assert.Equal(t, "low", groupByKey(t, groups, "MIT").Risk)
assert.Equal(t, "high", groupByKey(t, groups, "AGPL-3.0-or-later").Risk)
assert.Equal(t, "unknown", groupByKey(t, groups, noLicenseKey).Risk)
}
func TestGroupRiskEscalatesOnRepoIncompatibility(t *testing.T) {
// Apache-2.0 is permissive (category risk "low"), but beside AGPL-3.0-or-later it
// is party to a curated hard incompatibility. The Apache group must read "high",
// not "low" -- a group is not "all clear" when its license clashes repo-wide.
r := model.Report{Files: []model.FileResult{
headered("a/x.go", "Go", "Apache-2.0"),
headered("b/y.go", "Go", "AGPL-3.0-or-later"),
}}
groups, _ := GroupFiles(r, GroupSpec{By: GroupLicense})
assert.Equal(t, "high", groupByKey(t, groups, "Apache-2.0").Risk)
assert.Equal(t, "high", groupByKey(t, groups, "AGPL-3.0-or-later").Risk)
}
func TestGroupFilesWithRepoWideIncompatibility(t *testing.T) {
// The listing has been narrowed to just the Apache file (its AGPL partner filtered
// out of Files, e.g. by --only), but the repo-wide incompatibility set still names
// both. The Apache group must still escalate to "high": a narrowed listing must not
// distort the policy-aware risk marker (the rollup-distortion contract of --only).
r := model.Report{Files: []model.FileResult{headered("a/x.go", "Go", "Apache-2.0")}}
full := map[string]bool{"Apache-2.0": true, "AGPL-3.0-or-later": true}
groups, _ := groupFilesWith(r, GroupSpec{By: GroupLicense}, full)
assert.Equal(t, "high", groupByKey(t, groups, "Apache-2.0").Risk)
// Control: with an empty repo-wide set (what the filtered listing alone would
// yield), Apache reads its category risk "low" -- proving the passed-in set is what
// drives escalation, not the listing's own ids.
groups2, _ := groupFilesWith(r, GroupSpec{By: GroupLicense}, map[string]bool{})
assert.Equal(t, "low", groupByKey(t, groups2, "Apache-2.0").Risk)
}
func TestGroupRiskEscalatesOnFileScopedPolicyViolation(t *testing.T) {
// A permissive license carrying a file-scoped policy violation (e.g. deny-listed)
// must escalate its group to "high" rather than reading its category risk "low".
denied := headered("a/x.go", "Go", "MIT")
denied.Violations = []string{model.FailOnPolicyViolation.String()}
r := model.Report{Files: []model.FileResult{denied}}
groups, _ := GroupFiles(r, GroupSpec{By: GroupLicense})
assert.Equal(t, "high", groupByKey(t, groups, "MIT").Risk)
}
func TestGroupRiskDirectoryEscalatesMixedGroup(t *testing.T) {
// The headline case for policy-aware risk: a non-license grouping where one bad
// file taints the bucket. pkg/ mixes an Apache file (party to a repo incompatibility
// with the AGPL in lib/) with an innocent MIT file; both are category-low, yet pkg/
// must read "high". A sibling directory of only MIT stays "low".
r := model.Report{Files: []model.FileResult{
headered("pkg/a.go", "Go", "Apache-2.0"),
headered("pkg/b.go", "Go", "MIT"),
headered("other/c.go", "Go", "MIT"),
headered("lib/d.go", "Go", "AGPL-3.0-or-later"),
}}
groups, _ := GroupFiles(r, GroupSpec{By: GroupDirectory})
assert.Equal(t, "high", groupByKey(t, groups, "pkg").Risk)
assert.Equal(t, "low", groupByKey(t, groups, "other").Risk)
assert.Equal(t, "high", groupByKey(t, groups, "lib").Risk) // AGPL: category high and incompatible
}
func TestGroupRiskIncompatBeatsHeaderlessUnknown(t *testing.T) {
// A group with an incompatible-license file AND a headerless file escalates to
// "high" (policy concern), not the headerless "unknown" fallback.
r := model.Report{Files: []model.FileResult{
headered("pkg/a.go", "Go", "Apache-2.0"),
{Path: "pkg/b.go", FileType: "Go"}, // headerless
headered("lib/c.go", "Go", "AGPL-3.0-or-later"),
}}
groups, _ := GroupFiles(r, GroupSpec{By: GroupDirectory})
assert.Equal(t, "high", groupByKey(t, groups, "pkg").Risk)
}
func TestGroupRiskNonPolicyViolationTokenDoesNotEscalate(t *testing.T) {
// missing-header / unknown-license tokens are not policy escalations: a permissive
// group carrying only such a token keeps its category risk ("low"), not "high".
fr := headered("a/x.go", "Go", "MIT")
fr.Violations = []string{model.FailOnUnknownLicense.String()}
r := model.Report{Files: []model.FileResult{fr}}
groups, _ := GroupFiles(r, GroupSpec{By: GroupLicense})
assert.Equal(t, "low", groupByKey(t, groups, "MIT").Risk)
}
func TestIncompatibleIDs(t *testing.T) {
// Three ids where exactly one pair (AGPL x Apache) is a curated hard incompatibility:
// both are flagged, the innocent MIT is not.
got := incompatibleIDs([]string{"AGPL-3.0-or-later", "Apache-2.0", "MIT"})
assert.True(t, got["AGPL-3.0-or-later"])
assert.True(t, got["Apache-2.0"])
assert.False(t, got["MIT"])
// No incompatible pair, a single id, and the empty set all yield an empty result.
assert.Empty(t, incompatibleIDs([]string{"MIT", "Apache-2.0"}))
assert.Empty(t, incompatibleIDs([]string{"Apache-2.0"}))
assert.Empty(t, incompatibleIDs(nil))
}
func TestLicenseBreakdown(t *testing.T) {
files := []model.FileResult{
headered("a.go", "Go", "MIT"),
headered("b.go", "Go", "MIT"),
{Path: "c.go", FileType: "Go"}, // no header
}
got := licenseBreakdown(files)
assert.Equal(t, 2, got["MIT"])
assert.Equal(t, 1, got["(no-header)"])
}
+293
View File
@@ -0,0 +1,293 @@
package report
import (
"bytes"
"encoding/json"
"testing"
"github.com/KofTwentyTwo/license-tool/internal/model"
"github.com/KofTwentyTwo/license-tool/internal/policy"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
func reportWithViolations() model.Report {
r := optionsFixture()
r.ViolationDetails = []model.ViolationDetail{
{Condition: model.FailOnMissingHeader, Path: "src/legacy.go", Message: "src/legacy.go: no managed license header"},
{Condition: model.FailOnPolicyViolation, SPDXID: "AGPL-3.0-or-later", Path: "web/c.ts", Message: `web/c.ts: license "AGPL-3.0-or-later" is not on the allow list`},
}
return r
}
func TestPercent(t *testing.T) {
assert.Equal(t, "0.0%", percent(5, 0))
assert.Equal(t, "50.0%", percent(1, 2))
assert.Equal(t, "100.0%", percent(4, 4))
}
func TestSortByCountHelpers(t *testing.T) {
counts := map[string]int{"a": 1, "b": 3, "c": 2}
byKey := sortedCountsBy(counts, false)
assert.Equal(t, []string{"a", "b", "c"}, []string{byKey[0].key, byKey[1].key, byKey[2].key})
byCount := sortedCountsBy(counts, true)
assert.Equal(t, []string{"b", "c", "a"}, []string{byCount[0].key, byCount[1].key, byCount[2].key})
groups := []Group{{Key: "a", Count: 1}, {Key: "b", Count: 3}, {Key: "c", Count: 2}}
sortGroups(groups, false) // no-op leaves key order
assert.Equal(t, "a", groups[0].Key)
sortGroups(groups, true)
assert.Equal(t, []string{"b", "c", "a"}, []string{groups[0].Key, groups[1].Key, groups[2].Key})
tied := []Group{{Key: "z", Count: 2}, {Key: "a", Count: 2}}
sortGroups(tied, true) // equal counts -> alphabetical key
assert.Equal(t, "a", tied[0].Key)
}
func TestWorstRiskAndSummary(t *testing.T) {
var w worstRisk
lvl, cat := w.result()
assert.Equal(t, "none", lvl)
assert.Empty(t, cat)
w.observe(model.CategoryPermissive) // low
w.observe(model.CategoryStrongCopyleft) // high beats low
w.observe(model.CategoryWeakCopyleft) // medium does not beat high
w.observe(model.CategoryNetworkCopyleft) // tie on high, higher enum wins
w.observe(model.CategoryUnknown) // unknown (rank 0) loses
lvl, cat = w.result()
assert.Equal(t, "high", lvl)
assert.Equal(t, "network-copyleft", cat)
assert.Equal(t, "none", Findings{}.riskSummary())
assert.Equal(t, "high (network-copyleft)", Findings{RiskLevel: "high", WorstCategory: "network-copyleft"}.riskSummary())
}
func TestToViolationDetailsSortsDedupesAndHandlesEmpty(t *testing.T) {
assert.Empty(t, toViolationDetails(nil))
got := toViolationDetails([]policy.Violation{
{Condition: model.FailOnPolicyViolation, SPDXID: "MIT", Path: "b", Message: "m"},
{Condition: model.FailOnMissingHeader, Path: "a", Message: "m2"},
{Condition: model.FailOnMissingHeader, Path: "a", Message: "m1"}, // same cond+path, diff msg
{Condition: model.FailOnMissingHeader, Path: "a", Message: "m1"}, // exact duplicate
})
require.Len(t, got, 3) // duplicate collapsed
// missing-header (0) sorts before policy-violation (2); within, by path then message.
assert.Equal(t, model.FailOnMissingHeader, got[0].Condition)
assert.Equal(t, "m1", got[0].Message)
assert.Equal(t, "m2", got[1].Message)
assert.Equal(t, model.FailOnPolicyViolation, got[2].Condition)
}
func TestRenderTextViolationDetails(t *testing.T) {
out := renderToString(t, reportWithViolations(), FormatText, RenderOptions{})
assert.Contains(t, out, "policy violations:")
assert.Contains(t, out, "[missing-header] src/legacy.go: no managed license header")
assert.Contains(t, out, `[policy-violation] web/c.ts: license "AGPL-3.0-or-later" is not on the allow list`)
}
func TestRenderMarkdownViolationDetails(t *testing.T) {
out := renderToString(t, reportWithViolations(), FormatMarkdown, RenderOptions{})
assert.Contains(t, out, "## Policy violations")
assert.Contains(t, out, "| Condition | License | Location | Detail |")
assert.Contains(t, out, "| policy-violation | `AGPL-3.0-or-later` | web/c.ts |")
}
func TestRenderJSONViolationDetails(t *testing.T) {
out := renderToString(t, reportWithViolations(), FormatJSON, RenderOptions{})
var raw map[string]any
require.NoError(t, json.Unmarshal([]byte(out), &raw))
vd, ok := raw["violationDetails"].([]any)
require.True(t, ok)
require.Len(t, vd, 2)
first := vd[0].(map[string]any)
assert.Equal(t, "missing-header", first["condition"])
assert.Contains(t, first, "message")
}
// optionsFixture builds a realistic report (counts populated by Build) with headered,
// headerless, and skipped source files plus resolved/unresolved dependencies.
func optionsFixture() model.Report {
files := []model.FileResult{
headered("src/a.go", "Go", "MIT"),
{Path: "src/b.go", FileType: "Go"}, // headerless
{Path: "img/logo.png", FileType: "", Skipped: true, SkipReason: "binary"}, // skipped
}
deps := []model.DependencyLicense{
{Ecosystem: "npm", Name: "left-pad", Version: "1.0.0", SPDXID: "MIT", Resolution: model.ResolutionResolved},
{Ecosystem: "maven", Name: "foo", Resolution: model.ResolutionUnresolved, Reason: "no metadata"},
}
return Build("/root", model.Config{License: "MIT", Holder: "Acme", Style: model.StyleReuse}, files, deps, nil)
}
func renderToString(t *testing.T, r model.Report, format Format, opts RenderOptions) string {
t.Helper()
var b bytes.Buffer
require.NoError(t, RenderWithOptions(&b, r, format, opts))
return b.String()
}
func TestGroupDimensionString(t *testing.T) {
assert.Equal(t, "none", GroupNone.String())
assert.Equal(t, "license", GroupLicense.String())
assert.Equal(t, "category", GroupCategory.String())
assert.Equal(t, "type", GroupType.String())
assert.Equal(t, "directory", GroupDirectory.String())
}
func TestTitleCase(t *testing.T) {
assert.Equal(t, "", titleCase(""))
assert.Equal(t, "License", titleCase("license"))
}
func TestRenderTextSummaryOmitsLists(t *testing.T) {
out := renderToString(t, optionsFixture(), FormatText, RenderOptions{Summary: true})
assert.Contains(t, out, "by SPDX id:") // rollups stay
assert.Contains(t, out, "findings:") // findings stays
// The flat list header sits at the line start; the findings line is indented.
assert.NotContains(t, out, "\nsource files:")
assert.NotContains(t, out, "left-pad") // dependency list omitted
}
func TestRenderTextGroupBy(t *testing.T) {
out := renderToString(t, optionsFixture(), FormatText, RenderOptions{GroupBy: GroupLicense})
assert.Contains(t, out, "source files by license:")
assert.Contains(t, out, "MIT (1)")
assert.Contains(t, out, " src/a.go") // nested file line
assert.Contains(t, out, "(no-header) (1)") // headerless bucket
assert.Contains(t, out, "(skipped: 1)") // skipped note
assert.Contains(t, out, "left-pad") // deps list still shown (not summary)
}
func TestRenderTextGroupBySummaryCountsOnly(t *testing.T) {
out := renderToString(t, optionsFixture(), FormatText, RenderOptions{Summary: true, GroupBy: GroupDirectory})
assert.Contains(t, out, "source files by directory:")
assert.Contains(t, out, "src (2)") // src/a.go + src/b.go
assert.NotContains(t, out, " src/a.go") // no file paths under summary
assert.NotContains(t, out, "left-pad") // deps omitted
}
func TestRenderTextGroupByEmpty(t *testing.T) {
// A report with only skipped files yields no groups but still a skipped note.
r := model.Report{Files: []model.FileResult{{Path: "a.bin", Skipped: true, SkipReason: "binary"}}}
out := renderToString(t, r, FormatText, RenderOptions{GroupBy: GroupType})
assert.Contains(t, out, "(no managed source files)")
assert.Contains(t, out, "(skipped: 1)")
}
func TestRenderMarkdownGroupBy(t *testing.T) {
out := renderToString(t, optionsFixture(), FormatMarkdown, RenderOptions{GroupBy: GroupLicense})
assert.Contains(t, out, "## Source files by license")
assert.Contains(t, out, "### `MIT` (1)")
assert.Contains(t, out, "| `src/a.go` |")
assert.Contains(t, out, "_Skipped (uneditable): 1_")
}
func TestRenderMarkdownSummaryGroupBy(t *testing.T) {
out := renderToString(t, optionsFixture(), FormatMarkdown, RenderOptions{Summary: true, GroupBy: GroupLicense})
assert.Contains(t, out, "| License | Files |")
assert.Contains(t, out, "| `MIT` | 1 |")
assert.NotContains(t, out, "| `src/a.go` |")
}
func TestRenderMarkdownSummaryOmitsTables(t *testing.T) {
out := renderToString(t, optionsFixture(), FormatMarkdown, RenderOptions{Summary: true})
assert.Contains(t, out, "## By SPDX id")
assert.NotContains(t, out, "## Source files")
assert.NotContains(t, out, "## Dependencies")
}
func TestRenderJSONGroupBy(t *testing.T) {
out := renderToString(t, optionsFixture(), FormatJSON, RenderOptions{GroupBy: GroupLicense})
var raw map[string]any
require.NoError(t, json.Unmarshal([]byte(out), &raw))
groups, ok := raw["groups"].([]any)
require.True(t, ok, "groups array present")
require.NotEmpty(t, groups)
first := groups[0].(map[string]any)
assert.Contains(t, first, "key")
assert.Contains(t, first, "count")
assert.Contains(t, first, "files") // detail present in non-summary group-by
// Full report still carries the top-level files/dependencies.
assert.Contains(t, raw, "files")
assert.Contains(t, raw, "dependencies")
}
func TestRenderJSONIgnoresSummaryTrim(t *testing.T) {
// JSON is always the complete report: --summary only trims human formats, so a
// machine consumer still gets files, dependencies, and findings in one call.
out := renderToString(t, optionsFixture(), FormatJSON, RenderOptions{Summary: true})
var raw map[string]any
require.NoError(t, json.Unmarshal([]byte(out), &raw))
assert.Equal(t, "license-tool/report/v1", raw["schema"])
assert.Contains(t, raw, "files")
assert.Contains(t, raw, "dependencies")
assert.Contains(t, raw, "findings")
}
func TestRenderJSONSummaryGroupKeepsFiles(t *testing.T) {
out := renderToString(t, optionsFixture(), FormatJSON, RenderOptions{Summary: true, GroupBy: GroupCategory})
var raw map[string]any
require.NoError(t, json.Unmarshal([]byte(out), &raw))
first := raw["groups"].([]any)[0].(map[string]any)
assert.Contains(t, first, "count")
assert.Contains(t, first, "files") // JSON groups always carry detail
}
func TestRenderDirectoryBreakdown(t *testing.T) {
r := optionsFixture() // src/a.go (MIT), src/b.go (no header)
textOut := renderToString(t, r, FormatText, RenderOptions{GroupBy: GroupDirectory})
assert.Contains(t, textOut, "source files by directory:")
assert.Contains(t, textOut, "licenses: ") // per-group breakdown line (non-license dim)
mdOut := renderToString(t, r, FormatMarkdown, RenderOptions{GroupBy: GroupDirectory})
assert.Contains(t, mdOut, "Licenses: ")
jsonOut := renderToString(t, r, FormatJSON, RenderOptions{GroupBy: GroupDirectory})
var raw map[string]any
require.NoError(t, json.Unmarshal([]byte(jsonOut), &raw))
g := raw["groups"].([]any)[0].(map[string]any)
assert.Contains(t, g, "licenses")
assert.Contains(t, g, "risk")
}
func TestParseOnly(t *testing.T) {
got, err := ParseOnly("missing, copyleft,violations,unknown")
require.NoError(t, err)
assert.Equal(t, []OnlyFilter{OnlyMissing, OnlyCopyleft, OnlyViolations, OnlyUnknown}, got)
empty, err := ParseOnly("")
require.NoError(t, err)
assert.Empty(t, empty)
_, err = ParseOnly("bogus")
require.Error(t, err)
assert.Contains(t, err.Error(), "unknown --only filter")
}
func TestKeepFile(t *testing.T) {
missing := model.FileResult{Path: "a.go"}
mit := headered("b.go", "Go", "MIT")
agpl := headered("c.go", "Go", "AGPL-3.0-or-later")
unknownLic := headered("d.go", "Go", "Frobnicate-9000")
violating := model.FileResult{Path: "e.go", Detected: model.DetectedHeader{Present: true, SPDXID: "MIT"}, Violations: []string{"policy-violation"}}
skipped := model.FileResult{Path: "x.bin", Skipped: true}
assert.True(t, keepFile(missing, nil)) // empty -> keep all
assert.False(t, keepFile(skipped, []OnlyFilter{OnlyMissing})) // skipped never matches
assert.True(t, keepFile(missing, []OnlyFilter{OnlyMissing}))
assert.False(t, keepFile(mit, []OnlyFilter{OnlyMissing}))
assert.True(t, keepFile(unknownLic, []OnlyFilter{OnlyUnknown}))
assert.True(t, keepFile(agpl, []OnlyFilter{OnlyCopyleft}))
assert.False(t, keepFile(mit, []OnlyFilter{OnlyCopyleft}))
assert.True(t, keepFile(violating, []OnlyFilter{OnlyViolations}))
}
func TestRenderTextOnlyFilter(t *testing.T) {
out := renderToString(t, optionsFixture(), FormatText, RenderOptions{Only: []OnlyFilter{OnlyMissing}})
assert.Contains(t, out, "src/b.go") // headerless kept
assert.NotContains(t, out, "src/a.go") // MIT-headered filtered out
}
+509 -138
View File
@@ -31,7 +31,7 @@ const Disclaimer = "This tool reports and enforces license metadata; it is not l
// empty string: an empty map key is invisible in rendered output and silently
// indistinguishable from "absent", so missing headers would never surface in the
// by-license breakdown. A named bucket makes the gap explicit and sortable.
const noLicenseKey = "(none)"
const noLicenseKey = "(no-header)"
// Format selects the output rendering.
type Format int
@@ -186,10 +186,16 @@ func Build(root string, cfg model.Config, files []model.FileResult, deps []model
// vendored curated set. Ids outside the curated rendering set classify as unknown,
// which is the honest answer: we have no vendored metadata to categorize them.
func categoryToken(id string) string {
return classifyCategory(id).String()
}
// classifyCategory maps an SPDX id to its model.Category via the vendored snapshot;
// ids outside the curated set are CategoryUnknown.
func classifyCategory(id string) model.Category {
if lic, ok := spdx.Lookup(id); ok {
return lic.Category.String()
return lic.Category
}
return model.CategoryUnknown.String()
return model.CategoryUnknown
}
// conditionFromToken maps a stable fail_on token back to its FailCondition. It is
@@ -285,6 +291,7 @@ func Audit(path string, cfg model.Config, opts Options, pipe Pipeline) (model.Re
}
files := make([]model.FileResult, 0, len(sources))
var allViolations []policy.Violation
for _, s := range sources {
fr := model.FileResult{
Path: s.Path,
@@ -309,12 +316,15 @@ func Audit(path string, cfg model.Config, opts Options, pipe Pipeline) (model.Re
}
// Per-file policy verdicts attach their stable tokens to the file so the
// by-file view and the fail-on evaluation both see them.
for _, v := range policy.EvaluateFile(cfg.Policy, fr) {
// by-file view and the fail-on evaluation both see them; the full structs are
// retained for the attributable ViolationDetails.
fileViolations := policy.EvaluateFile(cfg.Policy, fr)
for _, v := range fileViolations {
fr.Violations = append(fr.Violations, v.Token())
}
sort.Strings(fr.Violations)
fr.Violations = dedupeStrings(fr.Violations)
allViolations = append(allViolations, fileViolations...)
files = append(files, fr)
}
@@ -335,8 +345,53 @@ func Audit(path string, cfg model.Config, opts Options, pipe Pipeline) (model.Re
// Repo-level checks run over the distinct SPDX ids actually found in source.
repoViolations = append(repoViolations, policy.EvaluateRepo(cfg.Policy, distinctSourceIDs(files))...)
allViolations = append(allViolations, repoViolations...)
return Build(path, cfg, files, deps, repoViolations), nil
r := Build(path, cfg, files, deps, repoViolations)
r.ViolationDetails = toViolationDetails(allViolations)
return r, nil
}
// toViolationDetails maps the full policy.Violation set (file + dependency + repo) to
// attributable model.ViolationDetail records, sorted and de-duplicated for stable
// output. WHY the report layer owns this mapping: model stays free of a policy import,
// and the rich attribution policy already produces is preserved instead of being
// flattened to bare tokens.
func toViolationDetails(vs []policy.Violation) []model.ViolationDetail {
out := make([]model.ViolationDetail, 0, len(vs))
for _, v := range vs {
out = append(out, model.ViolationDetail{
Condition: v.Condition,
SPDXID: v.SPDXID,
Path: v.Path,
Message: v.Message,
})
}
sort.Slice(out, func(i, j int) bool {
if out[i].Condition != out[j].Condition {
return out[i].Condition < out[j].Condition
}
if out[i].Path != out[j].Path {
return out[i].Path < out[j].Path
}
return out[i].Message < out[j].Message
})
return dedupeViolationDetails(out)
}
// dedupeViolationDetails removes adjacent duplicate findings; the input is pre-sorted,
// so a single linear pass suffices.
func dedupeViolationDetails(in []model.ViolationDetail) []model.ViolationDetail {
if len(in) == 0 {
return nil
}
out := in[:1]
for _, v := range in[1:] {
if v != out[len(out)-1] {
out = append(out, v)
}
}
return out
}
// distinctSourceIDs returns the sorted, unique set of SPDX ids detected across the
@@ -356,17 +411,65 @@ func distinctSourceIDs(files []model.FileResult) []string {
return ids
}
// Render writes the report in the requested format to w, prefixing the disclaimer
// where appropriate. All three renderers walk the model through a sorted view, so
// output is deterministic for identical inputs regardless of input ordering.
// RenderOptions tunes the human/JSON rendering of a report. The zero value is the
// default full report (every renderer's historical behavior).
type RenderOptions struct {
// Summary suppresses the per-file list, the per-dependency list, and pending
// diffs, leaving findings, the count rollups, and policy violations.
Summary bool
// GroupBy organizes the source-file listing under each value of a dimension
// instead of a flat list. GroupNone is the flat default.
GroupBy GroupDimension
// SortByCount orders the count rollups and groups by descending count (ties by
// key) instead of the default alphabetical key order.
SortByCount bool
// DirectoryDepth is how many leading path segments form a directory group key
// (min 1); only meaningful with GroupBy == GroupDirectory.
DirectoryDepth int
// Only restricts the source-file listing to problem files; empty lists all.
Only []OnlyFilter
}
// spec builds the GroupSpec for the current options.
func (o RenderOptions) spec() GroupSpec {
return GroupSpec{By: o.GroupBy, Depth: o.DirectoryDepth}
}
// listingReport returns r with its Files filtered by the --only set, for the
// (flat or grouped) file listing. The count rollups and findings stay derived from
// the full report, so --only narrows what is listed without distorting the totals.
func (o RenderOptions) listingReport(r model.Report) model.Report {
if len(o.Only) == 0 {
return r
}
filtered := make([]model.FileResult, 0, len(r.Files))
for _, fr := range r.Files {
if keepFile(fr, o.Only) {
filtered = append(filtered, fr)
}
}
r.Files = filtered
return r
}
// Render writes the report in the requested format to w with default options. It is
// the backward-compatible entry point; callers needing summary/group-by use
// RenderWithOptions.
func Render(w io.Writer, r model.Report, format Format) error {
return RenderWithOptions(w, r, format, RenderOptions{})
}
// RenderWithOptions writes the report honoring opts. All three renderers walk the
// model through a sorted view, so output is deterministic for identical inputs
// regardless of input ordering.
func RenderWithOptions(w io.Writer, r model.Report, format Format, opts RenderOptions) error {
switch format {
case FormatText:
return renderText(w, r)
return renderText(w, r, opts)
case FormatJSON:
return renderJSON(w, r)
return renderJSON(w, r, opts)
case FormatMarkdown:
return renderMarkdown(w, r)
return renderMarkdown(w, r, opts)
default:
return fmt.Errorf("report: cannot render unknown format %d", format)
}
@@ -410,7 +513,7 @@ func classifier(cfg model.Config) func(string) (model.FileType, bool) {
// ----- text renderer -----
func renderText(w io.Writer, r model.Report) error {
func renderText(w io.Writer, r model.Report, opts RenderOptions) error {
bw := &errWriter{w: w}
bw.printf("license-tool audit report\n")
@@ -425,50 +528,56 @@ func renderText(w io.Writer, r model.Report) error {
bw.printf("result: %s\n\n", passLabel(r.Passed))
bw.printf("by SPDX id:\n")
if len(r.LicenseCounts) == 0 {
bw.printf(" (no managed source files)\n")
}
for _, kv := range sortedCounts(r.LicenseCounts) {
bw.printf(" %-24s %d\n", kv.key, kv.count)
}
bw.printf("\n")
// The count rollups are always shown (cheap, and the core summary).
renderCountSection(bw, "by SPDX id", r.LicenseCounts, "(no managed source files)", opts.SortByCount)
renderCountSection(bw, "by category", r.CategoryCounts, "(none)", opts.SortByCount)
renderCountSection(bw, "by file type", r.FileTypeCounts, "(none)", opts.SortByCount)
bw.printf("by category:\n")
if len(r.CategoryCounts) == 0 {
bw.printf(" (none)\n")
// Source-file listing: flat by default, grouped under --group-by, omitted under
// --summary (a bare --summary with no group-by shows only the rollups above).
// Incompatibility risk is repo-wide, so derive it from the full report before
// --only narrows the listing; otherwise a filtered listing would understate a
// group's policy-aware risk.
incompatIDs := incompatibleIDs(distinctSourceIDs(r.Files))
lr := opts.listingReport(r)
switch {
case opts.GroupBy != GroupNone:
renderGroupedFiles(bw, lr, opts, incompatIDs)
case !opts.Summary:
bw.printf("source files: %d\n", len(lr.Files))
for _, fr := range sortedFiles(lr.Files) {
bw.printf(" %s\n", fileLine(fr))
}
bw.printf("\n")
}
for _, kv := range sortedCounts(r.CategoryCounts) {
bw.printf(" %-24s %d\n", kv.key, kv.count)
}
bw.printf("\n")
bw.printf("by file type:\n")
if len(r.FileTypeCounts) == 0 {
bw.printf(" (none)\n")
// Diffs and the per-dependency list are detail, suppressed in summary mode; the
// findings block already reports dependency resolution counts.
if !opts.Summary {
renderTextDiffs(bw, r.Files)
bw.printf("dependencies: %d\n", len(r.Dependencies))
for _, dep := range sortedDeps(r.Dependencies) {
bw.printf(" %s\n", depLine(dep))
}
bw.printf("\n")
}
for _, kv := range sortedCounts(r.FileTypeCounts) {
bw.printf(" %-24s %d\n", kv.key, kv.count)
renderTextViolations(bw, r)
return bw.err
}
// renderTextViolations prints the attributable findings (condition + message) when
// available, falling back to the legacy repo-level tokens otherwise.
func renderTextViolations(bw *errWriter, r model.Report) {
if len(r.ViolationDetails) > 0 {
bw.printf("policy violations:\n")
for _, v := range r.ViolationDetails {
bw.printf(" [%s] %s\n", v.Condition, v.Message)
}
bw.printf("\n")
return
}
bw.printf("\n")
// Source-vs-dependency split: source files come from Files, dependencies from
// Dependencies. Both are surfaced so the reader sees the two halves the
// requirements call out.
bw.printf("source files: %d\n", len(r.Files))
for _, fr := range sortedFiles(r.Files) {
bw.printf(" %s\n", fileLine(fr))
}
bw.printf("\n")
renderTextDiffs(bw, r.Files)
bw.printf("dependencies: %d\n", len(r.Dependencies))
for _, dep := range sortedDeps(r.Dependencies) {
bw.printf(" %s\n", depLine(dep))
}
bw.printf("\n")
if len(r.Violations) > 0 {
bw.printf("policy violations:\n")
for _, v := range r.Violations {
@@ -476,8 +585,76 @@ func renderText(w io.Writer, r model.Report) error {
}
bw.printf("\n")
}
}
return bw.err
// renderCountSection prints a "<title>:" header followed by the sorted counts, or
// emptyLabel when the map is empty.
func renderCountSection(bw *errWriter, title string, counts map[string]int, emptyLabel string, byCount bool) {
bw.printf("%s:\n", title)
if len(counts) == 0 {
bw.printf(" %s\n", emptyLabel)
bw.printf("\n")
return
}
total := sumCounts(counts)
for _, kv := range sortedCountsBy(counts, byCount) {
bw.printf(" %-24s %4d (%s)\n", kv.key, kv.count, percent(kv.count, total))
}
bw.printf(" %-24s %4d\n", "total", total)
bw.printf("\n")
}
// breakdownSummary renders a license breakdown map as "id n, id n" in key order.
func breakdownSummary(counts map[string]int) string {
parts := make([]string, 0, len(counts))
for _, kv := range sortedCounts(counts) {
parts = append(parts, fmt.Sprintf("%s %d", kv.key, kv.count))
}
return strings.Join(parts, ", ")
}
// sumCounts totals a count map.
func sumCounts(counts map[string]int) int {
total := 0
for _, v := range counts {
total += v
}
return total
}
// percent formats n as a one-decimal percentage of total ("55.6%"); 0/0 is "0.0%".
func percent(n, total int) string {
if total == 0 {
return "0.0%"
}
return fmt.Sprintf("%.1f%%", float64(n)*100/float64(total))
}
// renderGroupedFiles prints the source files grouped under opts.GroupBy. Under
// --summary it prints per-group counts only; otherwise it nests the file lines. A
// trailing note reports skipped (uneditable) files, which are never grouped.
func renderGroupedFiles(bw *errWriter, r model.Report, opts RenderOptions, incompatIDs map[string]bool) {
groups, skipped := groupFilesWith(r, opts.spec(), incompatIDs)
sortGroups(groups, opts.SortByCount)
bw.printf("source files by %s:\n", opts.GroupBy)
if len(groups) == 0 {
bw.printf(" (no managed source files)\n")
}
for _, g := range groups {
bw.printf(" %s (%d) [risk: %s]\n", g.Key, g.Count, g.Risk)
if opts.GroupBy != GroupLicense {
bw.printf(" licenses: %s\n", breakdownSummary(g.Licenses))
}
if !opts.Summary {
for _, fr := range g.Files {
bw.printf(" %s\n", fileLine(fr))
}
}
}
if skipped > 0 {
bw.printf(" (skipped: %d)\n", skipped)
}
bw.printf("\n")
}
func renderTextDiffs(bw *errWriter, files []model.FileResult) {
@@ -524,7 +701,7 @@ func depLine(dep model.DependencyLicense) string {
// ----- markdown renderer -----
func renderMarkdown(w io.Writer, r model.Report) error {
func renderMarkdown(w io.Writer, r model.Report, opts RenderOptions) error {
bw := &errWriter{w: w}
bw.printf("# license-tool audit report\n\n")
@@ -535,42 +712,53 @@ func renderMarkdown(w io.Writer, r model.Report) error {
bw.printf("- **Style:** `%s`\n", r.Config.Style)
bw.printf("- **Result:** %s\n\n", passLabel(r.Passed))
bw.printf("## By SPDX id\n\n")
bw.printf("| SPDX id | Files |\n| --- | --- |\n")
for _, kv := range sortedCounts(r.LicenseCounts) {
bw.printf("| `%s` | %d |\n", kv.key, kv.count)
}
bw.printf("\n")
renderMarkdownFindings(bw, buildFindings(r))
bw.printf("## By category\n\n")
bw.printf("| Category | Files |\n| --- | --- |\n")
for _, kv := range sortedCounts(r.CategoryCounts) {
bw.printf("| %s | %d |\n", kv.key, kv.count)
}
bw.printf("\n")
renderMarkdownCountTable(bw, "By SPDX id", "SPDX id", r.LicenseCounts, opts.SortByCount)
renderMarkdownCountTable(bw, "By category", "Category", r.CategoryCounts, opts.SortByCount)
renderMarkdownCountTable(bw, "By file type", "File type", r.FileTypeCounts, opts.SortByCount)
bw.printf("## By file type\n\n")
bw.printf("| File type | Files |\n| --- | --- |\n")
for _, kv := range sortedCounts(r.FileTypeCounts) {
bw.printf("| %s | %d |\n", kv.key, kv.count)
incompatIDs := incompatibleIDs(distinctSourceIDs(r.Files))
lr := opts.listingReport(r)
switch {
case opts.GroupBy != GroupNone:
renderMarkdownGroups(bw, lr, opts, incompatIDs)
case !opts.Summary:
bw.printf("## Source files (%d)\n\n", len(lr.Files))
bw.printf("| Path | File type | Status |\n| --- | --- | --- |\n")
for _, fr := range sortedFiles(lr.Files) {
bw.printf("| `%s` | %s | %s |\n", fr.Path, orNone(fr.FileType), mdFileStatus(fr))
}
bw.printf("\n")
}
bw.printf("\n")
bw.printf("## Source files (%d)\n\n", len(r.Files))
bw.printf("| Path | File type | Status |\n| --- | --- | --- |\n")
for _, fr := range sortedFiles(r.Files) {
bw.printf("| `%s` | %s | %s |\n", fr.Path, orNone(fr.FileType), mdFileStatus(fr))
if !opts.Summary {
bw.printf("## Dependencies (%d)\n\n", len(r.Dependencies))
bw.printf("| Ecosystem | Name | Version | License | Resolution |\n| --- | --- | --- | --- | --- |\n")
for _, dep := range sortedDeps(r.Dependencies) {
bw.printf("| %s | `%s` | %s | `%s` | %s |\n",
dep.Ecosystem, orNone(dep.Name), orNone(dep.Version), orNone(dep.SPDXID), dep.Resolution)
}
bw.printf("\n")
}
bw.printf("\n")
bw.printf("## Dependencies (%d)\n\n", len(r.Dependencies))
bw.printf("| Ecosystem | Name | Version | License | Resolution |\n| --- | --- | --- | --- | --- |\n")
for _, dep := range sortedDeps(r.Dependencies) {
bw.printf("| %s | `%s` | %s | `%s` | %s |\n",
dep.Ecosystem, orNone(dep.Name), orNone(dep.Version), orNone(dep.SPDXID), dep.Resolution)
renderMarkdownViolations(bw, r)
return bw.err
}
// renderMarkdownViolations renders an attributable findings table (condition, license,
// location, detail) when details are present, falling back to the legacy token list.
func renderMarkdownViolations(bw *errWriter, r model.Report) {
if len(r.ViolationDetails) > 0 {
bw.printf("## Policy violations\n\n")
bw.printf("| Condition | License | Location | Detail |\n| --- | --- | --- | --- |\n")
for _, v := range r.ViolationDetails {
bw.printf("| %s | `%s` | %s | %s |\n", v.Condition, orNone(v.SPDXID), orNone(v.Path), v.Message)
}
bw.printf("\n")
return
}
bw.printf("\n")
if len(r.Violations) > 0 {
bw.printf("## Policy violations\n\n")
for _, v := range r.Violations {
@@ -578,8 +766,74 @@ func renderMarkdown(w io.Writer, r model.Report) error {
}
bw.printf("\n")
}
}
return bw.err
// renderMarkdownFindings renders the at-a-glance summary (coverage, license mix,
// risk, copyleft, dependency resolution, policy) so Markdown reports carry the same
// overview the text renderer does.
func renderMarkdownFindings(bw *errWriter, f Findings) {
bw.printf("## Findings\n\n")
bw.printf("- **Source files:** %d (headered %d, missing %d)\n", f.SourceTotal, f.SourceHeadered, f.SourceMissing)
bw.printf("- **License types:** %s\n", f.licenseSummary())
bw.printf("- **Risk:** %s\n", f.riskSummary())
bw.printf("- **Copyleft:** %s\n", f.copyleftSummary())
bw.printf("- **Unknown/unrecognized:** %d\n", f.UnknownCount)
if f.DepsScanned {
bw.printf("- **Dependencies:** %d (resolved %d, unresolved %d)\n", f.DepsTotal, f.DepsResolved, f.DepsUnresolved)
}
bw.printf("- **Policy:** %s\n\n", f.policySummary())
}
// renderMarkdownCountTable renders one count rollup as a table with a percentage
// column and a total row.
func renderMarkdownCountTable(bw *errWriter, heading, keyHeader string, counts map[string]int, byCount bool) {
bw.printf("## %s\n\n", heading)
bw.printf("| %s | Files | %% |\n| --- | --- | --- |\n", keyHeader)
total := sumCounts(counts)
for _, kv := range sortedCountsBy(counts, byCount) {
bw.printf("| `%s` | %d | %s |\n", kv.key, kv.count, percent(kv.count, total))
}
bw.printf("| **total** | **%d** | |\n\n", total)
}
// renderMarkdownGroups renders the grouped source-file view. Under --summary it emits
// a single per-group count table; otherwise a per-group heading with a file table.
func renderMarkdownGroups(bw *errWriter, r model.Report, opts RenderOptions, incompatIDs map[string]bool) {
groups, skipped := groupFilesWith(r, opts.spec(), incompatIDs)
sortGroups(groups, opts.SortByCount)
bw.printf("## Source files by %s\n\n", opts.GroupBy)
if opts.Summary {
bw.printf("| %s | Files | Risk |\n| --- | --- | --- |\n", titleCase(opts.GroupBy.String()))
for _, g := range groups {
bw.printf("| `%s` | %d | %s |\n", g.Key, g.Count, g.Risk)
}
bw.printf("\n")
} else {
for _, g := range groups {
bw.printf("### `%s` (%d) — risk: %s\n\n", g.Key, g.Count, g.Risk)
if opts.GroupBy != GroupLicense {
bw.printf("Licenses: %s\n\n", breakdownSummary(g.Licenses))
}
bw.printf("| Path | File type | Status |\n| --- | --- | --- |\n")
for _, fr := range g.Files {
bw.printf("| `%s` | %s | %s |\n", fr.Path, orNone(fr.FileType), mdFileStatus(fr))
}
bw.printf("\n")
}
}
if skipped > 0 {
bw.printf("_Skipped (uneditable): %d_\n\n", skipped)
}
}
// titleCase upper-cases the first byte of an ASCII word for a table header.
func titleCase(s string) string {
if s == "" {
return s
}
return strings.ToUpper(s[:1]) + s[1:]
}
func mdFileStatus(fr model.FileResult) string {
@@ -603,17 +857,54 @@ func mdFileStatus(fr model.FileResult) string {
// decouples wire compatibility from internal refactors, and lets us emit the
// disclaimer, a schema version, and sorted aggregates explicitly.
type jsonReport struct {
Schema string `json:"schema"`
Disclaimer string `json:"disclaimer"`
Root string `json:"root"`
Passed bool `json:"passed"`
Config jsonConfig `json:"config"`
LicenseCounts map[string]int `json:"licenseCounts"`
CategoryCounts map[string]int `json:"categoryCounts"`
FileTypeCounts map[string]int `json:"fileTypeCounts"`
Files []jsonFile `json:"files"`
Dependencies []jsonDependency `json:"dependencies"`
Violations []string `json:"violations"`
Schema string `json:"schema"`
Disclaimer string `json:"disclaimer"`
Root string `json:"root"`
Passed bool `json:"passed"`
Config jsonConfig `json:"config"`
Findings jsonFindings `json:"findings"`
LicenseCounts map[string]int `json:"licenseCounts"`
CategoryCounts map[string]int `json:"categoryCounts"`
FileTypeCounts map[string]int `json:"fileTypeCounts"`
Groups []jsonGroup `json:"groups,omitempty"`
Files []jsonFile `json:"files"`
Dependencies []jsonDependency `json:"dependencies"`
Violations []string `json:"violations"`
ViolationDetails []jsonViolation `json:"violationDetails"`
}
// jsonViolation is one attributable finding in the machine schema.
type jsonViolation struct {
Condition string `json:"condition"`
SPDXID string `json:"spdxId,omitempty"`
Path string `json:"path,omitempty"`
Message string `json:"message"`
}
// jsonFindings is the machine form of the at-a-glance summary, including the explicit
// riskLevel/worstCategory so a model can branch on a value instead of parsing strings.
type jsonFindings struct {
SourceTotal int `json:"sourceTotal"`
SourceHeadered int `json:"sourceHeadered"`
SourceMissing int `json:"sourceMissing"`
UnknownCount int `json:"unknownCount"`
Copyleft []string `json:"copyleft"`
RiskLevel string `json:"riskLevel"`
WorstCategory string `json:"worstCategory,omitempty"`
DepsScanned bool `json:"depsScanned"`
DepsTotal int `json:"depsTotal"`
DepsResolved int `json:"depsResolved"`
DepsUnresolved int `json:"depsUnresolved"`
}
// jsonGroup is one grouped bucket in the machine schema. Files is omitted under
// --summary (counts only).
type jsonGroup struct {
Key string `json:"key"`
Count int `json:"count"`
Risk string `json:"risk"`
Licenses map[string]int `json:"licenses"`
Files []jsonFile `json:"files,omitempty"`
}
type jsonConfig struct {
@@ -646,56 +937,126 @@ type jsonDependency struct {
Reason string `json:"reason,omitempty"`
}
func renderJSON(w io.Writer, r model.Report) error {
out := jsonReport{
Schema: "license-tool/report/v1",
Disclaimer: Disclaimer,
Root: r.Root,
Passed: r.Passed,
Config: jsonConfig{License: r.Config.License, Holder: r.Config.Holder, Style: r.Config.Style.String()},
LicenseCounts: nonNilCounts(r.LicenseCounts),
CategoryCounts: nonNilCounts(r.CategoryCounts),
FileTypeCounts: nonNilCounts(r.FileTypeCounts),
Violations: nonNilStrings(r.Violations),
}
out.Files = make([]jsonFile, 0, len(r.Files))
for _, fr := range sortedFiles(r.Files) {
out.Files = append(out.Files, jsonFile{
Path: fr.Path,
FileType: fr.FileType,
Skipped: fr.Skipped,
SkipReason: fr.SkipReason,
HasHeader: fr.Detected.Present,
SPDXID: fr.Detected.SPDXID,
Holder: fr.Detected.Holder,
Year: fr.Detected.Year,
Action: fr.Action,
Diff: fr.Diff,
Violations: nonNilStrings(fr.Violations),
Error: fr.Err,
})
}
out.Dependencies = make([]jsonDependency, 0, len(r.Dependencies))
for _, dep := range sortedDeps(r.Dependencies) {
out.Dependencies = append(out.Dependencies, jsonDependency{
Ecosystem: dep.Ecosystem,
Name: dep.Name,
Version: dep.Version,
SPDXID: dep.SPDXID,
Resolution: dep.Resolution.String(),
Reason: dep.Reason,
})
}
func renderJSON(w io.Writer, r model.Report, opts RenderOptions) error {
enc := json.NewEncoder(w)
enc.SetIndent("", " ")
// Map keys are marshaled in sorted order by encoding/json, and every slice is
// pre-sorted, so the emitted JSON is byte-stable for identical reports.
incompatIDs := incompatibleIDs(distinctSourceIDs(r.Files))
lr := opts.listingReport(r)
var groups []jsonGroup
if opts.GroupBy != GroupNone {
groups = buildJSONGroups(lr, opts, incompatIDs)
}
details := toJSONViolations(r.ViolationDetails)
findings := toJSONFindings(buildFindings(r))
// JSON always emits the complete report regardless of --summary: machine consumers
// (scripts, dashboards, LLMs) want the full data in one call and slice it
// themselves. --summary only trims the human (text/markdown) renderers.
out := jsonReport{
Schema: "license-tool/report/v1",
Disclaimer: Disclaimer,
Root: r.Root,
Passed: r.Passed,
Config: jsonConfig{License: r.Config.License, Holder: r.Config.Holder, Style: r.Config.Style.String()},
Findings: findings,
LicenseCounts: nonNilCounts(r.LicenseCounts),
CategoryCounts: nonNilCounts(r.CategoryCounts),
FileTypeCounts: nonNilCounts(r.FileTypeCounts),
Groups: groups,
Violations: nonNilStrings(r.Violations),
ViolationDetails: details,
}
out.Files = make([]jsonFile, 0, len(lr.Files))
for _, fr := range sortedFiles(lr.Files) {
out.Files = append(out.Files, toJSONFile(fr))
}
out.Dependencies = make([]jsonDependency, 0, len(r.Dependencies))
for _, dep := range sortedDeps(r.Dependencies) {
out.Dependencies = append(out.Dependencies, toJSONDependency(dep))
}
return enc.Encode(out)
}
// buildJSONGroups builds the machine grouping for opts.GroupBy. File detail is
// included unless --summary asks for counts only.
func buildJSONGroups(r model.Report, opts RenderOptions, incompatIDs map[string]bool) []jsonGroup {
groups, _ := groupFilesWith(r, opts.spec(), incompatIDs)
sortGroups(groups, opts.SortByCount)
out := make([]jsonGroup, 0, len(groups))
for _, g := range groups {
jg := jsonGroup{Key: g.Key, Count: g.Count, Risk: g.Risk, Licenses: g.Licenses}
jg.Files = make([]jsonFile, 0, len(g.Files))
for _, fr := range g.Files {
jg.Files = append(jg.Files, toJSONFile(fr))
}
out = append(out, jg)
}
return out
}
func toJSONFile(fr model.FileResult) jsonFile {
return jsonFile{
Path: fr.Path,
FileType: fr.FileType,
Skipped: fr.Skipped,
SkipReason: fr.SkipReason,
HasHeader: fr.Detected.Present,
SPDXID: fr.Detected.SPDXID,
Holder: fr.Detected.Holder,
Year: fr.Detected.Year,
Action: fr.Action,
Diff: fr.Diff,
Violations: nonNilStrings(fr.Violations),
Error: fr.Err,
}
}
func toJSONFindings(f Findings) jsonFindings {
return jsonFindings{
SourceTotal: f.SourceTotal,
SourceHeadered: f.SourceHeadered,
SourceMissing: f.SourceMissing,
UnknownCount: f.UnknownCount,
Copyleft: nonNilStrings(f.Copyleft),
RiskLevel: f.RiskLevel,
WorstCategory: f.WorstCategory,
DepsScanned: f.DepsScanned,
DepsTotal: f.DepsTotal,
DepsResolved: f.DepsResolved,
DepsUnresolved: f.DepsUnresolved,
}
}
func toJSONViolations(details []model.ViolationDetail) []jsonViolation {
out := make([]jsonViolation, 0, len(details))
for _, v := range details {
out = append(out, jsonViolation{
Condition: v.Condition.String(),
SPDXID: v.SPDXID,
Path: v.Path,
Message: v.Message,
})
}
return out
}
func toJSONDependency(dep model.DependencyLicense) jsonDependency {
return jsonDependency{
Ecosystem: dep.Ecosystem,
Name: dep.Name,
Version: dep.Version,
SPDXID: dep.SPDXID,
Resolution: dep.Resolution.String(),
Reason: dep.Reason,
}
}
// ----- ordering + formatting helpers -----
type countKV struct {
@@ -714,6 +1075,16 @@ func sortedCounts(m map[string]int) []countKV {
return out
}
// sortedCountsBy returns the entries key-sorted (default) or by descending count with
// key ties broken alphabetically when byCount is set.
func sortedCountsBy(m map[string]int, byCount bool) []countKV {
out := sortedCounts(m)
if byCount {
sort.SliceStable(out, func(i, j int) bool { return out[i].count > out[j].count })
}
return out
}
// sortedFiles returns a copy of files ordered by path, the stable key for the
// per-file views. Ties on path (which should not occur for a real tree) fall back
// to FileType then detected id to stay total.
+6 -3
View File
@@ -686,12 +686,15 @@ func TestRenderMarkdown(t *testing.T) {
assert.Contains(t, out, "**License:** `MIT`")
assert.Contains(t, out, "**Holder:** Kingsrook, LLC")
assert.Contains(t, out, "**Result:** FAIL")
assert.Contains(t, out, "## Findings")
assert.Contains(t, out, "**Risk:** low (permissive)")
assert.Contains(t, out, "## By SPDX id")
assert.Contains(t, out, "| `MIT` | 3 |")
assert.Contains(t, out, "| `MIT` | 3 | 75.0% |")
assert.Contains(t, out, "## By category")
assert.Contains(t, out, "| permissive | 3 |")
assert.Contains(t, out, "| `permissive` | 3 | 75.0% |")
assert.Contains(t, out, "## By file type")
assert.Contains(t, out, "| Go | 4 |")
assert.Contains(t, out, "| `Go` | 4 | 80.0% |")
assert.Contains(t, out, "| **total** | **5** | |")
assert.Contains(t, out, "## Source files (6)")
// mdFileStatus branches.
assert.Contains(t, out, "| `a.go` | Go | MIT |")