From 6051a361987290dbe96a92fd9ddd4252e2242cd9 Mon Sep 17 00:00:00 2001 From: James Maes Date: Mon, 8 Jun 2026 13:04:49 -0500 Subject: [PATCH 01/18] docs(#35): spec audit summary + group-by report options --- docs/DESIGN-GH-35-audit-summary-reports.md | 79 ++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 docs/DESIGN-GH-35-audit-summary-reports.md diff --git a/docs/DESIGN-GH-35-audit-summary-reports.md b/docs/DESIGN-GH-35-audit-summary-reports.md new file mode 100644 index 0000000..8d8b6e2 --- /dev/null +++ b/docs/DESIGN-GH-35-audit-summary-reports.md @@ -0,0 +1,79 @@ +# 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 ` (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). -- 2.54.0 From c3755f7baffd731313870a8fc52d317103d41031 Mon Sep 17 00:00:00 2001 From: James Maes Date: Mon, 8 Jun 2026 13:12:04 -0500 Subject: [PATCH 02/18] feat(#35): add pure GroupFiles + ParseGroupBy for audit grouping --- internal/report/group.go | 120 ++++++++++++++++++++++++++++++++++ internal/report/group_test.go | 109 ++++++++++++++++++++++++++++++ 2 files changed, 229 insertions(+) create mode 100644 internal/report/group.go create mode 100644 internal/report/group_test.go diff --git a/internal/report/group.go b/internal/report/group.go new file mode 100644 index 0000000..4483caa --- /dev/null +++ b/internal/report/group.go @@ -0,0 +1,120 @@ +package report + +import ( + "fmt" + "path/filepath" + "sort" + "strings" + + "github.com/KofTwentyTwo/license-tool/internal/model" +) + +// 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 +) + +// 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) + } +} + +// Group is one bucket of the grouped source-file view: a key, the count of files in +// it, and the files themselves (sorted by path). +type Group struct { + Key string + Count int + Files []model.FileResult +} + +// GroupFiles partitions the non-skipped source files of r by dim, 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, dim GroupDimension) (groups []Group, skipped int) { + buckets := map[string][]model.FileResult{} + for _, fr := range r.Files { + if fr.Skipped { + skipped++ + continue + } + if dim == GroupNone { + continue + } + key := groupKey(fr, dim) + buckets[key] = append(buckets[key], 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), Files: files}) + } + return groups, skipped +} + +// 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() + case GroupType: + if fr.FileType != "" { + return fr.FileType + } + return "(unknown type)" + default: // GroupDirectory + return topDir(fr.Path) + } +} + +// topDir returns the first path segment of a forward-slash path; root-level files +// group under ".". +func topDir(path string) string { + p := filepath.ToSlash(path) + if i := strings.IndexByte(p, '/'); i >= 0 { + return p[:i] + } + return "." +} diff --git a/internal/report/group_test.go b/internal/report/group_test.go new file mode 100644 index 0000000..701e9e9 --- /dev/null +++ b/internal/report/group_test.go @@ -0,0 +1,109 @@ +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(), GroupNone) + assert.Empty(t, groups) + assert.Equal(t, 1, skipped) +} + +func TestGroupFilesByLicense(t *testing.T) { + groups, skipped := GroupFiles(sampleReport(), GroupLicense) + assert.Equal(t, 1, skipped) + // Keys sorted: "(none)" < "AGPL-3.0-or-later" < "MIT". + require.Len(t, groups, 3) + assert.Equal(t, "(none)", 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(), 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, 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(), 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, GroupDirectory) + require.Len(t, groups, 1) + assert.Equal(t, ".", groups[0].Key) +} -- 2.54.0 From dd4b34ba937d164fa0d4ff9ce0bc1c5d1d497598 Mon Sep 17 00:00:00 2001 From: James Maes Date: Mon, 8 Jun 2026 13:19:45 -0500 Subject: [PATCH 03/18] feat(#35): RenderOptions for summary + grouped views across all formats --- internal/report/group.go | 17 ++ internal/report/options_test.go | 142 ++++++++++++++ internal/report/report.go | 325 +++++++++++++++++++++++--------- 3 files changed, 399 insertions(+), 85 deletions(-) create mode 100644 internal/report/options_test.go diff --git a/internal/report/group.go b/internal/report/group.go index 4483caa..f1b4359 100644 --- a/internal/report/group.go +++ b/internal/report/group.go @@ -26,6 +26,23 @@ const ( 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) { diff --git a/internal/report/options_test.go b/internal/report/options_test.go new file mode 100644 index 0000000..e52e52b --- /dev/null +++ b/internal/report/options_test.go @@ -0,0 +1,142 @@ +package report + +import ( + "bytes" + "encoding/json" + "testing" + + "github.com/KofTwentyTwo/license-tool/internal/model" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// 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, "(none) (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 TestRenderJSONSummaryTrimsDetail(t *testing.T) { + 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, "licenseCounts") + assert.NotContains(t, raw, "files") + assert.NotContains(t, raw, "dependencies") + assert.NotContains(t, raw, "groups") // none requested +} + +func TestRenderJSONSummaryGroupByCountsOnly(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)) + groups := raw["groups"].([]any) + require.NotEmpty(t, groups) + first := groups[0].(map[string]any) + assert.Contains(t, first, "count") + assert.NotContains(t, first, "files") // counts only under summary + assert.NotContains(t, raw, "files") +} diff --git a/internal/report/report.go b/internal/report/report.go index eb4b736..54bef5e 100644 --- a/internal/report/report.go +++ b/internal/report/report.go @@ -356,17 +356,35 @@ 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 +} + +// 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 +428,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,49 +443,34 @@ 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)") + renderCountSection(bw, "by category", r.CategoryCounts, "(none)") + renderCountSection(bw, "by file type", r.FileTypeCounts, "(none)") - 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). + switch { + case opts.GroupBy != GroupNone: + renderGroupedFiles(bw, r, opts) + case !opts.Summary: + bw.printf("source files: %d\n", len(r.Files)) + for _, fr := range sortedFiles(r.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) - } - 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") @@ -480,6 +483,42 @@ func renderText(w io.Writer, r model.Report) error { return bw.err } +// renderCountSection prints a ":" 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) { + bw.printf("%s:\n", title) + if len(counts) == 0 { + bw.printf(" %s\n", emptyLabel) + } + for _, kv := range sortedCounts(counts) { + bw.printf(" %-24s %d\n", kv.key, kv.count) + } + bw.printf("\n") +} + +// 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) { + groups, skipped := GroupFiles(r, opts.GroupBy) + 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)\n", g.Key, g.Count) + 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) { diffFiles := make([]model.FileResult, 0) for _, fr := range sortedFiles(files) { @@ -524,7 +563,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") @@ -556,20 +595,27 @@ func renderMarkdown(w io.Writer, r model.Report) error { } 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)) + switch { + case opts.GroupBy != GroupNone: + renderMarkdownGroups(bw, r, opts) + case !opts.Summary: + 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)) + } + 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) + 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") if len(r.Violations) > 0 { bw.printf("## Policy violations\n\n") @@ -582,6 +628,42 @@ func renderMarkdown(w io.Writer, r model.Report) error { return bw.err } +// 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) { + groups, skipped := GroupFiles(r, opts.GroupBy) + bw.printf("## Source files by %s\n\n", opts.GroupBy) + + if opts.Summary { + bw.printf("| %s | Files |\n| --- | --- |\n", titleCase(opts.GroupBy.String())) + for _, g := range groups { + bw.printf("| `%s` | %d |\n", g.Key, g.Count) + } + bw.printf("\n") + } else { + for _, g := range groups { + bw.printf("### `%s` (%d)\n\n", g.Key, g.Count) + 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 { switch { case fr.Err != "": @@ -611,11 +693,36 @@ type jsonReport struct { 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"` } +// jsonSummaryReport is the trimmed schema emitted under --summary: counts, optional +// groups, and violations, but no per-file or per-dependency detail. A dedicated +// struct keeps the default (full) jsonReport byte-identical to its historical shape. +type jsonSummaryReport 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"` + Groups []jsonGroup `json:"groups,omitempty"` + Violations []string `json:"violations"` +} + +// 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"` + Files []jsonFile `json:"files,omitempty"` +} + type jsonConfig struct { License string `json:"license"` Holder string `json:"holder"` @@ -646,7 +753,32 @@ type jsonDependency struct { Reason string `json:"reason,omitempty"` } -func renderJSON(w io.Writer, r model.Report) error { +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. + + var groups []jsonGroup + if opts.GroupBy != GroupNone { + groups = buildJSONGroups(r, opts) + } + + if opts.Summary { + return enc.Encode(jsonSummaryReport{ + 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), + Groups: groups, + Violations: nonNilStrings(r.Violations), + }) + } + out := jsonReport{ Schema: "license-tool/report/v1", Disclaimer: Disclaimer, @@ -656,46 +788,69 @@ func renderJSON(w io.Writer, r model.Report) error { LicenseCounts: nonNilCounts(r.LicenseCounts), CategoryCounts: nonNilCounts(r.CategoryCounts), FileTypeCounts: nonNilCounts(r.FileTypeCounts), + Groups: groups, 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.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, jsonDependency{ - Ecosystem: dep.Ecosystem, - Name: dep.Name, - Version: dep.Version, - SPDXID: dep.SPDXID, - Resolution: dep.Resolution.String(), - Reason: dep.Reason, - }) + out.Dependencies = append(out.Dependencies, toJSONDependency(dep)) } - 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. 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) []jsonGroup { + groups, _ := GroupFiles(r, opts.GroupBy) + out := make([]jsonGroup, 0, len(groups)) + for _, g := range groups { + jg := jsonGroup{Key: g.Key, Count: g.Count} + if !opts.Summary { + 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 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 { -- 2.54.0 From b28d245c60c6d2bf9b5aa49188985cc4f4004ea1 Mon Sep 17 00:00:00 2001 From: James Maes <james@kof22.com> Date: Mon, 8 Jun 2026 13:29:35 -0500 Subject: [PATCH 04/18] feat(#35): wire --summary and --group-by audit flags + document them Closes #35 --- README.md | 46 +++++++++++++++++++++++++++++++ cmd/license-tool/commands.go | 32 +++++++++++++++++---- cmd/license-tool/commands_test.go | 41 +++++++++++++++++++++++++-- 3 files changed, 111 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index c02d534..b327531 100644 --- a/README.md +++ b/README.md @@ -54,8 +54,21 @@ 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 ``` +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 (with per-group +counts) instead of a flat list; combined with `--summary` it shows per-group counts +only. The flags apply to text, markdown, and JSON (JSON gains a `groups` array and +trims detail under `--summary`); they group source files, leaving the dependency +section unchanged. An unknown `--group-by` value is a usage error. + 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 +84,39 @@ 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: + (none) (1) + src/legacy.go [no managed header] + AGPL-3.0-or-later (2) + src/a.go [AGPL-3.0-or-later] + src/b.go [AGPL-3.0-or-later] + Apache-2.0 (1) + scripts/run.sh [Apache-2.0] + MIT (2) + 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: + +```text +source files by directory: + scripts (1) + src (3) + web (2) + (skipped: 6) +``` + +And `audit --group-by license --format json` emits the same grouping as machine data +(a `groups` array of `{key, count, 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`. diff --git a/cmd/license-tool/commands.go b/cmd/license-tool/commands.go index fab3ad0..9d3fd34 100644 --- a/cmd/license-tool/commands.go +++ b/cmd/license-tool/commands.go @@ -83,6 +83,18 @@ type auditFlags struct { noDeps bool resolveDeps string failOn []string + summary bool + groupBy string +} + +// renderOptions parses the summary/group-by flags into report.RenderOptions, surfacing +// an unknown --group-by 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 + } + return report.RenderOptions{Summary: f.summary, GroupBy: dim}, nil } func (f auditFlags) includeDeps() bool { @@ -108,6 +120,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 +133,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 +169,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 +182,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 +204,8 @@ 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") 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 +332,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 +344,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) diff --git a/cmd/license-tool/commands_test.go b/cmd/license-tool/commands_test.go index 5b602c2..24afce2 100644 --- a/cmd/license-tool/commands_test.go +++ b/cmd/license-tool/commands_test.go @@ -1005,12 +1005,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 +1020,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 +1032,41 @@ 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 TestLicenseSelectOptions(t *testing.T) { opts := licenseSelectOptions() require.NotEmpty(t, opts, "license picker should offer renderable licenses") -- 2.54.0 From 48fd1593688890389ced3f38b7e2a5c1e282da19 Mon Sep 17 00:00:00 2001 From: James Maes <james@kof22.com> Date: Mon, 8 Jun 2026 14:01:30 -0500 Subject: [PATCH 05/18] feat(#35): attributable policy violations (which license/rule/file) in all formats --- docs/review/04-audit-grouping-clean-room.md | 308 ++++++++++++++++++++ internal/model/model.go | 36 +++ internal/model/model_test.go | 18 ++ internal/report/options_test.go | 53 ++++ internal/report/report.go | 202 +++++++++---- 5 files changed, 568 insertions(+), 49 deletions(-) create mode 100644 docs/review/04-audit-grouping-clean-room.md diff --git a/docs/review/04-audit-grouping-clean-room.md b/docs/review/04-audit-grouping-clean-room.md new file mode 100644 index 0000000..7e51bac --- /dev/null +++ b/docs/review/04-audit-grouping-clean-room.md @@ -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. diff --git a/internal/model/model.go b/internal/model/model.go index d69efc4..9255d9d 100644 --- a/internal/model/model.go +++ b/internal/model/model.go @@ -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 +} diff --git a/internal/model/model_test.go b/internal/model/model_test.go index e58baf2..2d39ee3 100644 --- a/internal/model/model_test.go +++ b/internal/model/model_test.go @@ -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 diff --git a/internal/report/options_test.go b/internal/report/options_test.go index e52e52b..b129a33 100644 --- a/internal/report/options_test.go +++ b/internal/report/options_test.go @@ -6,10 +6,63 @@ import ( "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 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 { diff --git a/internal/report/report.go b/internal/report/report.go index 54bef5e..c610d96 100644 --- a/internal/report/report.go +++ b/internal/report/report.go @@ -285,6 +285,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 +310,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 +339,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 @@ -472,6 +521,22 @@ func renderText(w io.Writer, r model.Report, opts RenderOptions) error { bw.printf("\n") } + 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 + } if len(r.Violations) > 0 { bw.printf("policy violations:\n") for _, v := range r.Violations { @@ -479,8 +544,6 @@ func renderText(w io.Writer, r model.Report, opts RenderOptions) error { } bw.printf("\n") } - - return bw.err } // renderCountSection prints a "<title>:" header followed by the sorted counts, or @@ -617,6 +680,23 @@ func renderMarkdown(w io.Writer, r model.Report, opts RenderOptions) error { bw.printf("\n") } + 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 + } if len(r.Violations) > 0 { bw.printf("## Policy violations\n\n") for _, v := range r.Violations { @@ -624,8 +704,6 @@ func renderMarkdown(w io.Writer, r model.Report, opts RenderOptions) error { } bw.printf("\n") } - - return bw.err } // renderMarkdownGroups renders the grouped source-file view. Under --summary it emits @@ -685,34 +763,44 @@ 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"` - Groups []jsonGroup `json:"groups,omitempty"` - 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"` + 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"` } // jsonSummaryReport is the trimmed schema emitted under --summary: counts, optional // groups, and violations, but no per-file or per-dependency detail. A dedicated // struct keeps the default (full) jsonReport byte-identical to its historical shape. type jsonSummaryReport 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"` - Groups []jsonGroup `json:"groups,omitempty"` - Violations []string `json:"violations"` + 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"` + Groups []jsonGroup `json:"groups,omitempty"` + Violations []string `json:"violations"` + ViolationDetails []jsonViolation `json:"violationDetails"` } // jsonGroup is one grouped bucket in the machine schema. Files is omitted under @@ -763,33 +851,36 @@ func renderJSON(w io.Writer, r model.Report, opts RenderOptions) error { if opts.GroupBy != GroupNone { groups = buildJSONGroups(r, opts) } + details := toJSONViolations(r.ViolationDetails) if opts.Summary { return enc.Encode(jsonSummaryReport{ - 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), - Groups: groups, - Violations: nonNilStrings(r.Violations), + 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), + Groups: groups, + Violations: nonNilStrings(r.Violations), + ViolationDetails: details, }) } 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), - Groups: groups, - Violations: nonNilStrings(r.Violations), + 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), + Groups: groups, + Violations: nonNilStrings(r.Violations), + ViolationDetails: details, } out.Files = make([]jsonFile, 0, len(r.Files)) @@ -840,6 +931,19 @@ func toJSONFile(fr model.FileResult) jsonFile { } } +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, -- 2.54.0 From daef9c396d7c413072568a01873dc65844ba9a1f Mon Sep 17 00:00:00 2001 From: James Maes <james@kof22.com> Date: Mon, 8 Jun 2026 14:07:52 -0500 Subject: [PATCH 06/18] feat(#35): findings + totals/percentages + riskLevel parity across text/markdown/json --- internal/report/findings.go | 63 +++++++++++++++-- internal/report/options_test.go | 25 +++++++ internal/report/report.go | 121 ++++++++++++++++++++++++++------ internal/report/report_test.go | 9 ++- 4 files changed, 189 insertions(+), 29 deletions(-) diff --git a/internal/report/findings.go b/internal/report/findings.go index 3a1d0d9..ae3ea9c 100644 --- a/internal/report/findings.go +++ b/internal/report/findings.go @@ -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 @@ -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 { diff --git a/internal/report/options_test.go b/internal/report/options_test.go index b129a33..13c3ad5 100644 --- a/internal/report/options_test.go +++ b/internal/report/options_test.go @@ -20,6 +20,31 @@ func reportWithViolations() model.Report { 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 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)) diff --git a/internal/report/report.go b/internal/report/report.go index c610d96..2195847 100644 --- a/internal/report/report.go +++ b/internal/report/report.go @@ -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 @@ -552,13 +558,34 @@ func renderCountSection(bw *errWriter, title string, counts map[string]int, empt bw.printf("%s:\n", title) if len(counts) == 0 { bw.printf(" %s\n", emptyLabel) + bw.printf("\n") + return } + total := sumCounts(counts) for _, kv := range sortedCounts(counts) { - bw.printf(" %-24s %d\n", kv.key, kv.count) + bw.printf(" %-24s %4d (%s)\n", kv.key, kv.count, percent(kv.count, total)) } + bw.printf(" %-24s %4d\n", "total", total) bw.printf("\n") } +// 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. @@ -637,26 +664,11 @@ func renderMarkdown(w io.Writer, r model.Report, opts RenderOptions) 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") - - 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) - } - bw.printf("\n") + renderMarkdownCountTable(bw, "By SPDX id", "SPDX id", r.LicenseCounts) + renderMarkdownCountTable(bw, "By category", "Category", r.CategoryCounts) + renderMarkdownCountTable(bw, "By file type", "File type", r.FileTypeCounts) switch { case opts.GroupBy != GroupNone: @@ -706,6 +718,34 @@ func renderMarkdownViolations(bw *errWriter, r model.Report) { } } +// 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) { + bw.printf("## %s\n\n", heading) + bw.printf("| %s | Files | %% |\n| --- | --- | --- |\n", keyHeader) + total := sumCounts(counts) + for _, kv := range sortedCounts(counts) { + 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) { @@ -768,6 +808,7 @@ type jsonReport struct { 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"` @@ -795,6 +836,7 @@ type jsonSummaryReport struct { 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"` @@ -803,6 +845,22 @@ type jsonSummaryReport struct { ViolationDetails []jsonViolation `json:"violationDetails"` } +// 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 { @@ -852,6 +910,7 @@ func renderJSON(w io.Writer, r model.Report, opts RenderOptions) error { groups = buildJSONGroups(r, opts) } details := toJSONViolations(r.ViolationDetails) + findings := toJSONFindings(buildFindings(r)) if opts.Summary { return enc.Encode(jsonSummaryReport{ @@ -860,6 +919,7 @@ func renderJSON(w io.Writer, r model.Report, opts RenderOptions) error { 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), @@ -875,6 +935,7 @@ func renderJSON(w io.Writer, r model.Report, opts RenderOptions) error { 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), @@ -931,6 +992,22 @@ func toJSONFile(fr model.FileResult) jsonFile { } } +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 { diff --git a/internal/report/report_test.go b/internal/report/report_test.go index 30cae36..1328462 100644 --- a/internal/report/report_test.go +++ b/internal/report/report_test.go @@ -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 |") -- 2.54.0 From 29c7108c801a44e54c2f3d2b3a38b8d396a5ec4b Mon Sep 17 00:00:00 2001 From: James Maes <james@kof22.com> Date: Mon, 8 Jun 2026 14:14:19 -0500 Subject: [PATCH 07/18] feat(#35): per-group risk markers, (no-header) rename, --sort key|count --- cmd/license-tool/commands.go | 25 ++++++++++++++-- cmd/license-tool/commands_test.go | 27 +++++++++++++++++ internal/report/group.go | 35 ++++++++++++++++++++-- internal/report/group_test.go | 4 +-- internal/report/options_test.go | 28 +++++++++++++++--- internal/report/report.go | 49 +++++++++++++++++++++---------- 6 files changed, 141 insertions(+), 27 deletions(-) diff --git a/cmd/license-tool/commands.go b/cmd/license-tool/commands.go index 9d3fd34..e69f317 100644 --- a/cmd/license-tool/commands.go +++ b/cmd/license-tool/commands.go @@ -85,16 +85,34 @@ type auditFlags struct { failOn []string summary bool groupBy string + sort string } -// renderOptions parses the summary/group-by flags into report.RenderOptions, surfacing -// an unknown --group-by value as a usage error. +// 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 } - return report.RenderOptions{Summary: f.summary, GroupBy: dim}, nil + byCount, err := parseSort(f.sort) + if err != nil { + return report.RenderOptions{}, err + } + return report.RenderOptions{Summary: f.summary, GroupBy: dim, SortByCount: byCount}, 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 { @@ -206,6 +224,7 @@ func bindAuditFlags(cmd *cobra.Command, f *auditFlags, isCheck bool) { 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") if isCheck { cmd.Flags().StringArrayVar(&f.failOn, "fail-on", []string{"missing-header", "unknown-license", "policy-violation"}, "conditions that cause a non-zero exit") } diff --git a/cmd/license-tool/commands_test.go b/cmd/license-tool/commands_test.go index 24afce2..071da13 100644 --- a/cmd/license-tool/commands_test.go +++ b/cmd/license-tool/commands_test.go @@ -1067,6 +1067,33 @@ func TestCheckGroupByUnknownIsUsageError(t *testing.T) { 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") diff --git a/internal/report/group.go b/internal/report/group.go index f1b4359..a654358 100644 --- a/internal/report/group.go +++ b/internal/report/group.go @@ -63,10 +63,15 @@ func ParseGroupBy(raw string) (GroupDimension, error) { } // Group is one bucket of the grouped source-file view: a key, the count of files in -// it, and the files themselves (sorted by path). +// it, the worst obligation risk among its files, 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 Files []model.FileResult } @@ -98,11 +103,37 @@ func GroupFiles(r model.Report, dim GroupDimension) (groups []Group, skipped int 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), Files: files}) + groups = append(groups, Group{Key: k, Count: len(files), Risk: groupRisk(files), Files: files}) } return groups, skipped } +// groupRisk returns the worst category risk among a group's files. +func groupRisk(files []model.FileResult) string { + var w worstRisk + for _, fr := range files { + if fr.Detected.Present && fr.Detected.SPDXID != "" { + w.observe(classifyCategory(fr.Detected.SPDXID)) + } + } + level, _ := w.result() + return level +} + +// 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 { diff --git a/internal/report/group_test.go b/internal/report/group_test.go index 701e9e9..d84673e 100644 --- a/internal/report/group_test.go +++ b/internal/report/group_test.go @@ -50,9 +50,9 @@ func TestGroupFilesNone(t *testing.T) { func TestGroupFilesByLicense(t *testing.T) { groups, skipped := GroupFiles(sampleReport(), GroupLicense) assert.Equal(t, 1, skipped) - // Keys sorted: "(none)" < "AGPL-3.0-or-later" < "MIT". + // Keys sorted: "(no-header)" < "AGPL-3.0-or-later" < "MIT". require.Len(t, groups, 3) - assert.Equal(t, "(none)", groups[0].Key) + 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) diff --git a/internal/report/options_test.go b/internal/report/options_test.go index 13c3ad5..5ef8585 100644 --- a/internal/report/options_test.go +++ b/internal/report/options_test.go @@ -26,6 +26,26 @@ func TestPercent(t *testing.T) { 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() @@ -136,10 +156,10 @@ 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, "(none) (1)") // headerless bucket - assert.Contains(t, out, "(skipped: 1)") // skipped note - assert.Contains(t, out, "left-pad") // deps list still shown (not summary) + 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) { diff --git a/internal/report/report.go b/internal/report/report.go index 2195847..339433c 100644 --- a/internal/report/report.go +++ b/internal/report/report.go @@ -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 @@ -420,6 +420,9 @@ type RenderOptions struct { // 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 } // Render writes the report in the requested format to w with default options. It is @@ -499,9 +502,9 @@ func renderText(w io.Writer, r model.Report, opts RenderOptions) error { bw.printf("result: %s\n\n", passLabel(r.Passed)) // The count rollups are always shown (cheap, and the core summary). - renderCountSection(bw, "by SPDX id", r.LicenseCounts, "(no managed source files)") - renderCountSection(bw, "by category", r.CategoryCounts, "(none)") - renderCountSection(bw, "by file type", r.FileTypeCounts, "(none)") + 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) // 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). @@ -554,7 +557,7 @@ func renderTextViolations(bw *errWriter, r model.Report) { // 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) { +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) @@ -562,7 +565,7 @@ func renderCountSection(bw *errWriter, title string, counts map[string]int, empt return } total := sumCounts(counts) - for _, kv := range sortedCounts(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) @@ -591,12 +594,13 @@ func percent(n, total int) string { // trailing note reports skipped (uneditable) files, which are never grouped. func renderGroupedFiles(bw *errWriter, r model.Report, opts RenderOptions) { groups, skipped := GroupFiles(r, opts.GroupBy) + 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)\n", g.Key, g.Count) + bw.printf(" %s (%d) [risk: %s]\n", g.Key, g.Count, g.Risk) if !opts.Summary { for _, fr := range g.Files { bw.printf(" %s\n", fileLine(fr)) @@ -666,9 +670,9 @@ func renderMarkdown(w io.Writer, r model.Report, opts RenderOptions) error { renderMarkdownFindings(bw, buildFindings(r)) - renderMarkdownCountTable(bw, "By SPDX id", "SPDX id", r.LicenseCounts) - renderMarkdownCountTable(bw, "By category", "Category", r.CategoryCounts) - renderMarkdownCountTable(bw, "By file type", "File type", r.FileTypeCounts) + 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) switch { case opts.GroupBy != GroupNone: @@ -736,11 +740,11 @@ func renderMarkdownFindings(bw *errWriter, f Findings) { // 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) { +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 sortedCounts(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) @@ -750,17 +754,18 @@ func renderMarkdownCountTable(bw *errWriter, heading, keyHeader string, counts m // a single per-group count table; otherwise a per-group heading with a file table. func renderMarkdownGroups(bw *errWriter, r model.Report, opts RenderOptions) { groups, skipped := GroupFiles(r, opts.GroupBy) + sortGroups(groups, opts.SortByCount) bw.printf("## Source files by %s\n\n", opts.GroupBy) if opts.Summary { - bw.printf("| %s | Files |\n| --- | --- |\n", titleCase(opts.GroupBy.String())) + bw.printf("| %s | Files | Risk |\n| --- | --- | --- |\n", titleCase(opts.GroupBy.String())) for _, g := range groups { - bw.printf("| `%s` | %d |\n", g.Key, g.Count) + bw.printf("| `%s` | %d | %s |\n", g.Key, g.Count, g.Risk) } bw.printf("\n") } else { for _, g := range groups { - bw.printf("### `%s` (%d)\n\n", g.Key, g.Count) + bw.printf("### `%s` (%d) — risk: %s\n\n", g.Key, g.Count, g.Risk) 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)) @@ -866,6 +871,7 @@ type jsonFindings struct { type jsonGroup struct { Key string `json:"key"` Count int `json:"count"` + Risk string `json:"risk"` Files []jsonFile `json:"files,omitempty"` } @@ -961,9 +967,10 @@ func renderJSON(w io.Writer, r model.Report, opts RenderOptions) error { // included unless --summary asks for counts only. func buildJSONGroups(r model.Report, opts RenderOptions) []jsonGroup { groups, _ := GroupFiles(r, opts.GroupBy) + sortGroups(groups, opts.SortByCount) out := make([]jsonGroup, 0, len(groups)) for _, g := range groups { - jg := jsonGroup{Key: g.Key, Count: g.Count} + jg := jsonGroup{Key: g.Key, Count: g.Count, Risk: g.Risk} if !opts.Summary { jg.Files = make([]jsonFile, 0, len(g.Files)) for _, fr := range g.Files { @@ -1050,6 +1057,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. -- 2.54.0 From 96389108a8ddd0d17facb876ff2c8d083356761b Mon Sep 17 00:00:00 2001 From: James Maes <james@kof22.com> Date: Mon, 8 Jun 2026 14:21:52 -0500 Subject: [PATCH 08/18] feat(#35): per-group license breakdown, --depth directory grouping --- cmd/license-tool/commands.go | 4 +- internal/report/group.go | 80 ++++++++++++++++++++++++--------- internal/report/group_test.go | 31 ++++++++++--- internal/report/options_test.go | 17 +++++++ internal/report/report.go | 40 +++++++++++++---- 5 files changed, 137 insertions(+), 35 deletions(-) diff --git a/cmd/license-tool/commands.go b/cmd/license-tool/commands.go index e69f317..b904cf1 100644 --- a/cmd/license-tool/commands.go +++ b/cmd/license-tool/commands.go @@ -86,6 +86,7 @@ type auditFlags struct { summary bool groupBy string sort string + depth int } // renderOptions parses the summary/group-by/sort flags into report.RenderOptions, @@ -99,7 +100,7 @@ func (f auditFlags) renderOptions() (report.RenderOptions, error) { if err != nil { return report.RenderOptions{}, err } - return report.RenderOptions{Summary: f.summary, GroupBy: dim, SortByCount: byCount}, nil + return report.RenderOptions{Summary: f.summary, GroupBy: dim, SortByCount: byCount, DirectoryDepth: f.depth}, nil } // parseSort maps the --sort token to the by-count flag. "" and "key" sort @@ -225,6 +226,7 @@ func bindAuditFlags(cmd *cobra.Command, f *auditFlags, isCheck bool) { 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)") if isCheck { cmd.Flags().StringArrayVar(&f.failOn, "fail-on", []string{"missing-header", "unknown-license", "policy-violation"}, "conditions that cause a non-zero exit") } diff --git a/internal/report/group.go b/internal/report/group.go index a654358..6050d77 100644 --- a/internal/report/group.go +++ b/internal/report/group.go @@ -62,35 +62,44 @@ func ParseGroupBy(raw string) (GroupDimension, error) { } } +// 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 +} + // 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, and the files themselves (sorted by -// path). +// 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 - Files []model.FileResult + 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 by dim, returning the +// 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, dim GroupDimension) (groups []Group, skipped int) { +func GroupFiles(r model.Report, spec GroupSpec) (groups []Group, skipped int) { buckets := map[string][]model.FileResult{} for _, fr := range r.Files { if fr.Skipped { skipped++ continue } - if dim == GroupNone { + if spec.By == GroupNone { continue } - key := groupKey(fr, dim) - buckets[key] = append(buckets[key], fr) + buckets[groupKeyDepth(fr, spec)] = append(buckets[groupKeyDepth(fr, spec)], fr) } keys := make([]string, 0, len(buckets)) @@ -103,11 +112,34 @@ func GroupFiles(r model.Report, dim GroupDimension) (groups []Group, skipped int 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), Files: files}) + groups = append(groups, Group{ + Key: k, + Count: len(files), + Risk: groupRisk(files), + 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 worst category risk among a group's files. func groupRisk(files []model.FileResult) string { var w worstRisk @@ -147,22 +179,30 @@ func groupKey(fr model.FileResult, dim GroupDimension) string { return categoryToken(fr.Detected.SPDXID) } return model.CategoryUnknown.String() - case GroupType: + default: // GroupType if fr.FileType != "" { return fr.FileType } return "(unknown type)" - default: // GroupDirectory - return topDir(fr.Path) } } -// topDir returns the first path segment of a forward-slash path; root-level files -// group under ".". -func topDir(path string) string { - p := filepath.ToSlash(path) - if i := strings.IndexByte(p, '/'); i >= 0 { - return p[:i] +// 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 } - return "." + 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, "/") } diff --git a/internal/report/group_test.go b/internal/report/group_test.go index d84673e..1520e7a 100644 --- a/internal/report/group_test.go +++ b/internal/report/group_test.go @@ -42,13 +42,13 @@ func sampleReport() model.Report { } func TestGroupFilesNone(t *testing.T) { - groups, skipped := GroupFiles(sampleReport(), GroupNone) + 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(), GroupLicense) + 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) @@ -64,7 +64,7 @@ func TestGroupFilesByLicense(t *testing.T) { } func TestGroupFilesByCategory(t *testing.T) { - groups, _ := GroupFiles(sampleReport(), GroupCategory) + groups, _ := GroupFiles(sampleReport(), GroupSpec{By: GroupCategory}) keys := map[string]int{} for _, g := range groups { keys[g.Key] = g.Count @@ -79,7 +79,7 @@ func TestGroupFilesByType(t *testing.T) { headered("a.go", "Go", "MIT"), {Path: "weird", FileType: ""}, // non-skipped, no file type }} - groups, _ := GroupFiles(r, GroupType) + groups, _ := GroupFiles(r, GroupSpec{By: GroupType}) keys := map[string]int{} for _, g := range groups { keys[g.Key] = g.Count @@ -89,7 +89,7 @@ func TestGroupFilesByType(t *testing.T) { } func TestGroupFilesByDirectory(t *testing.T) { - groups, _ := GroupFiles(sampleReport(), GroupDirectory) + groups, _ := GroupFiles(sampleReport(), GroupSpec{By: GroupDirectory}) keys := map[string]int{} for _, g := range groups { keys[g.Key] = g.Count @@ -103,7 +103,26 @@ func TestGroupFilesByDirectory(t *testing.T) { func TestGroupFilesDirectoryRoot(t *testing.T) { r := model.Report{Files: []model.FileResult{headered("main.go", "Go", "MIT")}} - groups, _ := GroupFiles(r, GroupDirectory) + 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 +} + +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)"]) +} diff --git a/internal/report/options_test.go b/internal/report/options_test.go index 5ef8585..3b157db 100644 --- a/internal/report/options_test.go +++ b/internal/report/options_test.go @@ -238,3 +238,20 @@ func TestRenderJSONSummaryGroupByCountsOnly(t *testing.T) { assert.NotContains(t, first, "files") // counts only under summary assert.NotContains(t, raw, "files") } + +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") +} diff --git a/internal/report/report.go b/internal/report/report.go index 339433c..207adb6 100644 --- a/internal/report/report.go +++ b/internal/report/report.go @@ -423,6 +423,14 @@ type RenderOptions struct { // 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 +} + +// spec builds the GroupSpec for the current options. +func (o RenderOptions) spec() GroupSpec { + return GroupSpec{By: o.GroupBy, Depth: o.DirectoryDepth} } // Render writes the report in the requested format to w with default options. It is @@ -572,6 +580,15 @@ func renderCountSection(bw *errWriter, title string, counts map[string]int, empt 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 @@ -593,7 +610,7 @@ func percent(n, total int) string { // --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) { - groups, skipped := GroupFiles(r, opts.GroupBy) + groups, skipped := GroupFiles(r, opts.spec()) sortGroups(groups, opts.SortByCount) bw.printf("source files by %s:\n", opts.GroupBy) if len(groups) == 0 { @@ -601,6 +618,9 @@ func renderGroupedFiles(bw *errWriter, r model.Report, opts RenderOptions) { } 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)) @@ -753,7 +773,7 @@ func renderMarkdownCountTable(bw *errWriter, heading, keyHeader string, counts m // 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) { - groups, skipped := GroupFiles(r, opts.GroupBy) + groups, skipped := GroupFiles(r, opts.spec()) sortGroups(groups, opts.SortByCount) bw.printf("## Source files by %s\n\n", opts.GroupBy) @@ -766,6 +786,9 @@ func renderMarkdownGroups(bw *errWriter, r model.Report, opts RenderOptions) { } 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)) @@ -869,10 +892,11 @@ type jsonFindings struct { // 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"` - Files []jsonFile `json:"files,omitempty"` + 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 { @@ -966,11 +990,11 @@ func renderJSON(w io.Writer, r model.Report, opts RenderOptions) error { // 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) []jsonGroup { - groups, _ := GroupFiles(r, opts.GroupBy) + groups, _ := GroupFiles(r, opts.spec()) 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} + jg := jsonGroup{Key: g.Key, Count: g.Count, Risk: g.Risk, Licenses: g.Licenses} if !opts.Summary { jg.Files = make([]jsonFile, 0, len(g.Files)) for _, fr := range g.Files { -- 2.54.0 From 83df6402abe2f88ff177cf437f47ddc15e104d54 Mon Sep 17 00:00:00 2001 From: James Maes <james@kof22.com> Date: Mon, 8 Jun 2026 14:24:37 -0500 Subject: [PATCH 09/18] docs(#35): document audit risk/attribution/findings/sort/depth enhancements --- README.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index b327531..ed5b3e9 100644 --- a/README.md +++ b/README.md @@ -58,16 +58,26 @@ license-tool audit --summary # counts only; no per-file/dependen 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 ``` 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 (with per-group -counts) instead of a flat list; combined with `--summary` it shows per-group counts -only. The flags apply to text, markdown, and JSON (JSON gains a `groups` array and -trims detail under `--summary`); they group source files, leaving the dependency -section unchanged. An unknown `--group-by` value is a usage error. +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`) and, for non-license groupings, its +license breakdown, so a `directory` view is not license-blind. `--sort key|count` +orders rollups and groups; `--depth N` widens directory keys to N path segments. The +flags apply to text, markdown, and JSON; they group source files, leaving the +dependency section unchanged. An unknown `--group-by`/`--sort` 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. 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 -- 2.54.0 From b43e362a21be46370f8d2ae8ed44efd924fcccd0 Mon Sep 17 00:00:00 2001 From: James Maes <james@kof22.com> Date: Mon, 8 Jun 2026 14:58:42 -0500 Subject: [PATCH 10/18] fix(#35): unify (no-header) token, unknown-risk for headerless groups, full JSON under --summary --- docs/review/05-audit-grouping-clean-room-2.md | 163 ++++++++++++++++++ internal/report/findings.go | 2 +- internal/report/findings_test.go | 4 +- internal/report/group.go | 5 + internal/report/options_test.go | 20 +-- internal/report/report.go | 46 +---- 6 files changed, 186 insertions(+), 54 deletions(-) create mode 100644 docs/review/05-audit-grouping-clean-room-2.md diff --git a/docs/review/05-audit-grouping-clean-room-2.md b/docs/review/05-audit-grouping-clean-room-2.md new file mode 100644 index 0000000..c1b7aa8 --- /dev/null +++ b/docs/review/05-audit-grouping-clean-room-2.md @@ -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. diff --git a/internal/report/findings.go b/internal/report/findings.go index ae3ea9c..c6f0a22 100644 --- a/internal/report/findings.go +++ b/internal/report/findings.go @@ -139,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)" diff --git a/internal/report/findings_test.go b/internal/report/findings_test.go index 2e15bf8..cb5f9a0 100644 --- a/internal/report/findings_test.go +++ b/internal/report/findings_test.go @@ -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)") diff --git a/internal/report/group.go b/internal/report/group.go index 6050d77..58fcd6c 100644 --- a/internal/report/group.go +++ b/internal/report/group.go @@ -149,6 +149,11 @@ func groupRisk(files []model.FileResult) string { } } 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 } diff --git a/internal/report/options_test.go b/internal/report/options_test.go index 3b157db..1dd97c5 100644 --- a/internal/report/options_test.go +++ b/internal/report/options_test.go @@ -216,27 +216,25 @@ func TestRenderJSONGroupBy(t *testing.T) { assert.Contains(t, raw, "dependencies") } -func TestRenderJSONSummaryTrimsDetail(t *testing.T) { +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, "licenseCounts") - assert.NotContains(t, raw, "files") - assert.NotContains(t, raw, "dependencies") - assert.NotContains(t, raw, "groups") // none requested + assert.Contains(t, raw, "files") + assert.Contains(t, raw, "dependencies") + assert.Contains(t, raw, "findings") } -func TestRenderJSONSummaryGroupByCountsOnly(t *testing.T) { +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)) - groups := raw["groups"].([]any) - require.NotEmpty(t, groups) - first := groups[0].(map[string]any) + first := raw["groups"].([]any)[0].(map[string]any) assert.Contains(t, first, "count") - assert.NotContains(t, first, "files") // counts only under summary - assert.NotContains(t, raw, "files") + assert.Contains(t, first, "files") // JSON groups always carry detail } func TestRenderDirectoryBreakdown(t *testing.T) { diff --git a/internal/report/report.go b/internal/report/report.go index 207adb6..f045be9 100644 --- a/internal/report/report.go +++ b/internal/report/report.go @@ -855,24 +855,6 @@ type jsonViolation struct { Message string `json:"message"` } -// jsonSummaryReport is the trimmed schema emitted under --summary: counts, optional -// groups, and violations, but no per-file or per-dependency detail. A dedicated -// struct keeps the default (full) jsonReport byte-identical to its historical shape. -type jsonSummaryReport struct { - 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"` - Violations []string `json:"violations"` - ViolationDetails []jsonViolation `json:"violationDetails"` -} - // 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 { @@ -942,23 +924,9 @@ func renderJSON(w io.Writer, r model.Report, opts RenderOptions) error { details := toJSONViolations(r.ViolationDetails) findings := toJSONFindings(buildFindings(r)) - if opts.Summary { - return enc.Encode(jsonSummaryReport{ - 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, - }) - } - + // 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, @@ -995,11 +963,9 @@ func buildJSONGroups(r model.Report, opts RenderOptions) []jsonGroup { out := make([]jsonGroup, 0, len(groups)) for _, g := range groups { jg := jsonGroup{Key: g.Key, Count: g.Count, Risk: g.Risk, Licenses: g.Licenses} - if !opts.Summary { - jg.Files = make([]jsonFile, 0, len(g.Files)) - for _, fr := range g.Files { - jg.Files = append(jg.Files, toJSONFile(fr)) - } + jg.Files = make([]jsonFile, 0, len(g.Files)) + for _, fr := range g.Files { + jg.Files = append(jg.Files, toJSONFile(fr)) } out = append(out, jg) } -- 2.54.0 From 366ffece453efc1f970c130b8eb4e7277055c761 Mon Sep 17 00:00:00 2001 From: James Maes <james@kof22.com> Date: Mon, 8 Jun 2026 15:12:29 -0500 Subject: [PATCH 11/18] feat(#35): --only filter to list problem files (missing|unknown|copyleft|violations) --- cmd/license-tool/commands.go | 8 +++- cmd/license-tool/commands_test.go | 12 ++++++ internal/report/group.go | 71 +++++++++++++++++++++++++++++++ internal/report/options_test.go | 38 +++++++++++++++++ internal/report/report.go | 40 +++++++++++++---- 5 files changed, 159 insertions(+), 10 deletions(-) diff --git a/cmd/license-tool/commands.go b/cmd/license-tool/commands.go index b904cf1..65b6c1a 100644 --- a/cmd/license-tool/commands.go +++ b/cmd/license-tool/commands.go @@ -87,6 +87,7 @@ type auditFlags struct { groupBy string sort string depth int + only string } // renderOptions parses the summary/group-by/sort flags into report.RenderOptions, @@ -100,7 +101,11 @@ func (f auditFlags) renderOptions() (report.RenderOptions, error) { if err != nil { return report.RenderOptions{}, err } - return report.RenderOptions{Summary: f.summary, GroupBy: dim, SortByCount: byCount, DirectoryDepth: f.depth}, nil + 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 @@ -227,6 +232,7 @@ func bindAuditFlags(cmd *cobra.Command, f *auditFlags, isCheck bool) { 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") } diff --git a/cmd/license-tool/commands_test.go b/cmd/license-tool/commands_test.go index 071da13..3ec6b36 100644 --- a/cmd/license-tool/commands_test.go +++ b/cmd/license-tool/commands_test.go @@ -1229,3 +1229,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") +} diff --git a/internal/report/group.go b/internal/report/group.go index 58fcd6c..70be038 100644 --- a/internal/report/group.go +++ b/internal/report/group.go @@ -69,6 +69,77 @@ type GroupSpec struct { 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). diff --git a/internal/report/options_test.go b/internal/report/options_test.go index 1dd97c5..7c41810 100644 --- a/internal/report/options_test.go +++ b/internal/report/options_test.go @@ -253,3 +253,41 @@ func TestRenderDirectoryBreakdown(t *testing.T) { 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 +} diff --git a/internal/report/report.go b/internal/report/report.go index f045be9..0c3fbd0 100644 --- a/internal/report/report.go +++ b/internal/report/report.go @@ -426,6 +426,8 @@ type RenderOptions struct { // 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. @@ -433,6 +435,23 @@ 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. @@ -516,12 +535,13 @@ func renderText(w io.Writer, r model.Report, opts RenderOptions) error { // 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). + lr := opts.listingReport(r) switch { case opts.GroupBy != GroupNone: - renderGroupedFiles(bw, r, opts) + renderGroupedFiles(bw, lr, opts) case !opts.Summary: - bw.printf("source files: %d\n", len(r.Files)) - for _, fr := range sortedFiles(r.Files) { + bw.printf("source files: %d\n", len(lr.Files)) + for _, fr := range sortedFiles(lr.Files) { bw.printf(" %s\n", fileLine(fr)) } bw.printf("\n") @@ -694,13 +714,14 @@ func renderMarkdown(w io.Writer, r model.Report, opts RenderOptions) error { renderMarkdownCountTable(bw, "By category", "Category", r.CategoryCounts, opts.SortByCount) renderMarkdownCountTable(bw, "By file type", "File type", r.FileTypeCounts, opts.SortByCount) + lr := opts.listingReport(r) switch { case opts.GroupBy != GroupNone: - renderMarkdownGroups(bw, r, opts) + renderMarkdownGroups(bw, lr, opts) case !opts.Summary: - bw.printf("## Source files (%d)\n\n", len(r.Files)) + bw.printf("## Source files (%d)\n\n", len(lr.Files)) bw.printf("| Path | File type | Status |\n| --- | --- | --- |\n") - for _, fr := range sortedFiles(r.Files) { + for _, fr := range sortedFiles(lr.Files) { bw.printf("| `%s` | %s | %s |\n", fr.Path, orNone(fr.FileType), mdFileStatus(fr)) } bw.printf("\n") @@ -917,9 +938,10 @@ func renderJSON(w io.Writer, r model.Report, opts RenderOptions) error { // 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. + lr := opts.listingReport(r) var groups []jsonGroup if opts.GroupBy != GroupNone { - groups = buildJSONGroups(r, opts) + groups = buildJSONGroups(lr, opts) } details := toJSONViolations(r.ViolationDetails) findings := toJSONFindings(buildFindings(r)) @@ -942,8 +964,8 @@ func renderJSON(w io.Writer, r model.Report, opts RenderOptions) error { ViolationDetails: details, } - out.Files = make([]jsonFile, 0, len(r.Files)) - for _, fr := range sortedFiles(r.Files) { + out.Files = make([]jsonFile, 0, len(lr.Files)) + for _, fr := range sortedFiles(lr.Files) { out.Files = append(out.Files, toJSONFile(fr)) } -- 2.54.0 From bbba9d28bfbb73db258a53272bdd9c40f0839164 Mon Sep 17 00:00:00 2001 From: James Maes <james@kof22.com> Date: Mon, 8 Jun 2026 15:12:54 -0500 Subject: [PATCH 12/18] docs(#35): document --only filter and JSON-always-full behavior --- README.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index ed5b3e9..9bcd2f5 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,7 @@ 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:` @@ -69,9 +70,11 @@ organizes the source-file listing under each value of the dimension instead of a list; combined with `--summary` it shows per-group counts only. Each group reports its worst license **risk** (`high`/`medium`/`low`) and, for non-license groupings, its license breakdown, so a `directory` view is not license-blind. `--sort key|count` -orders rollups and groups; `--depth N` widens directory keys to N path segments. The -flags apply to text, markdown, and JSON; they group source files, leaving the -dependency section unchanged. An unknown `--group-by`/`--sort` value is a usage error. +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 -- 2.54.0 From ce192cad543624eb7c684c736ac958b818cffd0c Mon Sep 17 00:00:00 2001 From: James Maes <james@kof22.com> Date: Mon, 8 Jun 2026 15:30:38 -0500 Subject: [PATCH 13/18] feat(#35): exclude tool's own .license-tool.yaml from source coverage The config file is YAML (commentable), so the audit counted it as a coverable source file missing a managed header, inflating sourceTotal and sourceMissing. It is tool metadata, not coverable source, and never carries a header. Mark any file whose basename is .license-tool.yaml as skipped (reason "tool config") in the audit pipeline, so it still appears in the file listing but is excluded from source/header tallies. Export config.RepoConfigName as the single source of truth for the name. --- cmd/license-tool/commands.go | 14 ++++++++- cmd/license-tool/commands_test.go | 23 +++++++++++++++ internal/config/config.go | 12 ++++---- internal/config/config_test.go | 48 +++++++++++++++---------------- 4 files changed, 67 insertions(+), 30 deletions(-) diff --git a/cmd/license-tool/commands.go b/cmd/license-tool/commands.go index 65b6c1a..42474f4 100644 --- a/cmd/license-tool/commands.go +++ b/cmd/license-tool/commands.go @@ -539,6 +539,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{ @@ -559,7 +563,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 && filepath.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 diff --git a/cmd/license-tool/commands_test.go b/cmd/license-tool/commands_test.go index 3ec6b36..c6773c1 100644 --- a/cmd/license-tool/commands_test.go +++ b/cmd/license-tool/commands_test.go @@ -267,6 +267,29 @@ 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"]) + }) + t.Run("output file", func(t *testing.T) { dir := fixtureDir(t) outPath := filepath.Join(dir, "audit.json") diff --git a/internal/config/config.go b/internal/config/config.go index 8694ed1..4b0c8cf 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -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. diff --git a/internal/config/config_test.go b/internal/config/config_test.go index 2cf4752..d1b66ed 100644 --- a/internal/config/config_test.go +++ b/internal/config/config_test.go @@ -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") } }) -- 2.54.0 From 2822d862d84dfc8362a7dc0c5ed94e092bdb32e6 Mon Sep 17 00:00:00 2001 From: James Maes <james@kof22.com> Date: Tue, 9 Jun 2026 07:10:16 -0500 Subject: [PATCH 14/18] feat(#35): policy-aware group risk A group's [risk] marker was computed solely from its files' license categories, so it was policy-blind: an Apache-2.0 group beside an AGPL-3.0-or-later group read "low" even though the pair is a curated hard incompatibility, and a deny-listed permissive license also read "low". Escalate a group's risk to "high" when it carries a policy concern: a file whose license is party to a repo-level hard incompatibility (computed once over the distinct source ids via policy.Incompatible), or a file carrying a file-scoped policy-violation token. Category-only risk is preserved when there is no policy concern, with no false escalation (MIT beside AGPL, not an incompatibility, stays "low"). --- internal/report/group.go | 58 +++++++++++++++++++++++++++++++++-- internal/report/group_test.go | 46 +++++++++++++++++++++++++++ 2 files changed, 101 insertions(+), 3 deletions(-) diff --git a/internal/report/group.go b/internal/report/group.go index 70be038..430f123 100644 --- a/internal/report/group.go +++ b/internal/report/group.go @@ -7,6 +7,7 @@ import ( "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 @@ -161,6 +162,12 @@ type Group struct { // (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"). Compute the set of repo licenses party to a curated incompatibility + // once, and use it to make per-group risk policy-aware. + incompatIDs := incompatibleIDs(distinctSourceIDs(r.Files)) + buckets := map[string][]model.FileResult{} for _, fr := range r.Files { if fr.Skipped { @@ -186,7 +193,7 @@ func GroupFiles(r model.Report, spec GroupSpec) (groups []Group, skipped int) { groups = append(groups, Group{ Key: k, Count: len(files), - Risk: groupRisk(files), + Risk: groupRisk(files, incompatIDs), Licenses: licenseBreakdown(files), Files: files, }) @@ -211,13 +218,29 @@ func licenseBreakdown(files []model.FileResult) map[string]int { return out } -// groupRisk returns the worst category risk among a group's files. -func groupRisk(files []model.FileResult) string { +// 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" { @@ -228,6 +251,35 @@ func groupRisk(files []model.FileResult) string { 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) { diff --git a/internal/report/group_test.go b/internal/report/group_test.go index 1520e7a..99bcd7f 100644 --- a/internal/report/group_test.go +++ b/internal/report/group_test.go @@ -116,6 +116,52 @@ func TestTopDirs(t *testing.T) { 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 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 TestLicenseBreakdown(t *testing.T) { files := []model.FileResult{ headered("a.go", "Go", "MIT"), -- 2.54.0 From 56c3e9410bd1663ba39f14f974267c2b9bbdf4bc Mon Sep 17 00:00:00 2001 From: James Maes <james@kof22.com> Date: Tue, 9 Jun 2026 07:12:06 -0500 Subject: [PATCH 15/18] docs(#35): document self-config exclusion, policy-aware risk, and decisions README: policy-aware group risk and the .license-tool.yaml exclusion. CHANGELOG: comprehensive Unreleased entry for the audit reporting overhaul. DESIGN: post-implementation addenda recording the two new features and the three audit-flagged items resolved by decision (dep-grouping non-goal, JSON percentages declined, go.mod not a supported ecosystem). --- CHANGELOG.md | 16 ++++++++++++++++ README.md | 12 ++++++++++-- docs/DESIGN-GH-35-audit-summary-reports.md | 11 +++++++++++ 3 files changed, 37 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dff4fe0..0e8c15d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,22 @@ 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. + ## [0.3.0] - 2026-06-04 ### Install diff --git a/README.md b/README.md index 9bcd2f5..ca394e2 100644 --- a/README.md +++ b/README.md @@ -68,8 +68,12 @@ overview and the by-SPDX / by-category / by-file-type rollups but omits the per- 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`) and, for non-license groupings, its -license breakdown, so a `directory` view is not license-blind. `--sort key|count` +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 @@ -82,6 +86,10 @@ violation names the offending license, the rule, and the file (text/markdown) or 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. + 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, diff --git a/docs/DESIGN-GH-35-audit-summary-reports.md b/docs/DESIGN-GH-35-audit-summary-reports.md index 8d8b6e2..4c50c41 100644 --- a/docs/DESIGN-GH-35-audit-summary-reports.md +++ b/docs/DESIGN-GH-35-audit-summary-reports.md @@ -77,3 +77,14 @@ Groups are sorted by key; files within a group are sorted by path. Deterministic ## 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. -- 2.54.0 From 3852c9122b2ff784c44deb5eadd03f43b949919e Mon Sep 17 00:00:00 2001 From: James Maes <james@kof22.com> Date: Tue, 9 Jun 2026 07:44:21 -0500 Subject: [PATCH 16/18] fix(#35): harden group risk under --only; review-driven follow-ups Address findings from a three-agent adversarial review of the GH-35 delta: - Compute the repo-wide incompatibility set from the full report, not the --only-narrowed listing, so a filtered listing can no longer understate a group's policy-aware risk. Add groupFilesWith(r, spec, incompatIDs) and thread the full-report set through the text/markdown/JSON renderers. - Use path.Base (not filepath.Base) on the slash-normalized enumerate path when matching the config file, for cross-platform correctness. - Tests: directory-grouping escalation across a mixed bucket, incompat beating the headerless-unknown fallback, non-policy tokens not escalating, incompatibleIDs cardinality (0/1/3 ids), the filtered- listing risk contract, nested/--only config exclusion, no detected- license/violation leak on the skipped config, and a check exit-code regression guard for the config exclusion. - Docs: correct the README grouped-output samples (risk markers, (no-header) label, JSON group shape) and note the check exit-code implication of the config exclusion in README and CHANGELOG. --- CHANGELOG.md | 3 +- README.md | 25 ++++++----- cmd/license-tool/commands.go | 3 +- cmd/license-tool/commands_test.go | 47 +++++++++++++++++++++ docs/SESSION-STATE.md | 58 +++++++++++++++---------- internal/report/group.go | 13 ++++-- internal/report/group_test.go | 70 +++++++++++++++++++++++++++++++ internal/report/report.go | 24 +++++++---- 8 files changed, 196 insertions(+), 47 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0e8c15d..06f9585 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,7 +21,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - 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. +- 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 diff --git a/README.md b/README.md index ca394e2..ce83aa1 100644 --- a/README.md +++ b/README.md @@ -88,7 +88,8 @@ a check failed, not just that it did. Rollups show per-row percentages and total 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. +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 @@ -111,32 +112,34 @@ the gaps are: ```text source files by license: - (none) (1) + (no-header) (1) [risk: unknown] src/legacy.go [no managed header] - AGPL-3.0-or-later (2) + AGPL-3.0-or-later (2) [risk: high] src/a.go [AGPL-3.0-or-later] src/b.go [AGPL-3.0-or-later] - Apache-2.0 (1) - scripts/run.sh [Apache-2.0] - MIT (2) + 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: +"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: - scripts (1) - src (3) - web (2) + 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, files}`) for dashboards and CI summaries. +(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 diff --git a/cmd/license-tool/commands.go b/cmd/license-tool/commands.go index 42474f4..08f8c76 100644 --- a/cmd/license-tool/commands.go +++ b/cmd/license-tool/commands.go @@ -5,6 +5,7 @@ import ( "fmt" "io" "os" + "path" "path/filepath" "sort" "strings" @@ -567,7 +568,7 @@ func buildAuditPipeline(cfg model.Config, shared *sharedFlags) report.Pipeline { // 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 && filepath.Base(e.Path) == config.RepoConfigName { + if !sf.Skip && path.Base(e.Path) == config.RepoConfigName { sf.Skip = true sf.SkipReason = reasonToolConfig } diff --git a/cmd/license-tool/commands_test.go b/cmd/license-tool/commands_test.go index c6773c1..75cb98c 100644 --- a/cmd/license-tool/commands_test.go +++ b/cmd/license-tool/commands_test.go @@ -288,6 +288,41 @@ func TestAuditCommand(t *testing.T) { 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) { @@ -477,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") diff --git a/docs/SESSION-STATE.md b/docs/SESSION-STATE.md index 7d3fbce..7108273 100644 --- a/docs/SESSION-STATE.md +++ b/docs/SESSION-STATE.md @@ -1,27 +1,41 @@ # Session State -## Current Branch -`feature/GH-12-27-audit-fixes` +**Last Updated:** 2026-06-08 -## 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 +Two feature branches complete locally, both green (gofmt/vet/golangci-lint, `go test ./... -race`, 100% coverage gate, build). **Neither is pushed; no PRs opened.** -## 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` is a thin adapter, logic in `internal/initwizard` at 100%. Complete, unpushed. | +| `feature/GH-35-audit-summary-reports` | develop | Audit reporting overhaul (current branch, 12 commits ahead). Complete, unpushed. Tree clean. | -## 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`. + +## What Was Done (GH-35, this work) +- `--summary` (counts-only) and `--group-by license|category|type|directory` across text/markdown/JSON; default output preserved. +- Attributable policy violations (which license/rule/file) in all formats — `policy.Violation` data was being discarded at `report.Build`; now surfaced via `model.ViolationDetail` / JSON `violationDetails`. +- `findings` + per-row percentages/totals + `riskLevel`/`worstCategory` parity in JSON & markdown (was text-only). +- Per-group risk markers + license breakdown (fixes directory-license-blindness); `(no-header)` rename; `--sort key|count`; `--depth N`; `--only missing,unknown,copyleft,violations`. +- JSON now always emits the full report (`--summary` trims human formats only). +- Two clean-room audits run: `docs/review/04-...` (pre) and `05-...` (post). 2nd audit: 6 addressed / 3 partial / 2 open, then 4 more fixed this turn. + +## Pending Work (GH-35 punch list — from `docs/review/05-...md`) +- [ ] `--group-by dependency` (deps can't be grouped; distinct code path — deps aren't files). +- [ ] Policy-aware group risk (a group's `[risk]` ignores repo-level incompatibilities, e.g. Apache group beside AGPL reads `low`). +- [ ] Exclude the tool's own `.license-tool.yaml` from source/header expectations (inflates `sourceTotal`/`sourceMissing`). Cheap. +- [ ] JSON explicit percentages/totals (low value; derivable from counts + `findings`). +- [ ] Dep resolver returned 0 for a `go.mod` require (likely module-cache dependent) — needs CI-verified repro. + +## Other Open Threads +- [ ] Push branches + open PRs into `develop` (awaiting permission) — GH-29 and GH-35. +- [ ] GH-29 commit `bafa281` bundled planning docs (CLAUDE.md/DESIGN/PLAN/review) via `git add -A` — optional history tidy before PR. +- [ ] Independent review bugs filed but untouched: #30 (detect over-match), #31 (spdxnorm guessing), #33 (symlink LICENSE), #34 (no-op --quiet/--verbose). #32 (include `**`) was fixed on GH-29. + +## 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`, `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 must reference issues, no AI attribution. diff --git a/internal/report/group.go b/internal/report/group.go index 430f123..ffbf6c0 100644 --- a/internal/report/group.go +++ b/internal/report/group.go @@ -164,10 +164,17 @@ type Group struct { 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"). Compute the set of repo licenses party to a curated incompatibility - // once, and use it to make per-group risk policy-aware. - incompatIDs := incompatibleIDs(distinctSourceIDs(r.Files)) + // 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 { diff --git a/internal/report/group_test.go b/internal/report/group_test.go index 99bcd7f..c946cbb 100644 --- a/internal/report/group_test.go +++ b/internal/report/group_test.go @@ -152,6 +152,23 @@ func TestGroupRiskEscalatesOnRepoIncompatibility(t *testing.T) { 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". @@ -162,6 +179,59 @@ func TestGroupRiskEscalatesOnFileScopedPolicyViolation(t *testing.T) { 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"), diff --git a/internal/report/report.go b/internal/report/report.go index 0c3fbd0..d7967cd 100644 --- a/internal/report/report.go +++ b/internal/report/report.go @@ -535,10 +535,14 @@ func renderText(w io.Writer, r model.Report, opts RenderOptions) error { // 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) + renderGroupedFiles(bw, lr, opts, incompatIDs) case !opts.Summary: bw.printf("source files: %d\n", len(lr.Files)) for _, fr := range sortedFiles(lr.Files) { @@ -629,8 +633,8 @@ func percent(n, total int) string { // 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) { - groups, skipped := GroupFiles(r, opts.spec()) +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 { @@ -714,10 +718,11 @@ func renderMarkdown(w io.Writer, r model.Report, opts RenderOptions) error { renderMarkdownCountTable(bw, "By category", "Category", r.CategoryCounts, opts.SortByCount) renderMarkdownCountTable(bw, "By file type", "File type", r.FileTypeCounts, opts.SortByCount) + incompatIDs := incompatibleIDs(distinctSourceIDs(r.Files)) lr := opts.listingReport(r) switch { case opts.GroupBy != GroupNone: - renderMarkdownGroups(bw, lr, opts) + 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") @@ -793,8 +798,8 @@ func renderMarkdownCountTable(bw *errWriter, heading, keyHeader string, counts m // 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) { - groups, skipped := GroupFiles(r, opts.spec()) +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) @@ -938,10 +943,11 @@ func renderJSON(w io.Writer, r model.Report, opts RenderOptions) error { // 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) + groups = buildJSONGroups(lr, opts, incompatIDs) } details := toJSONViolations(r.ViolationDetails) findings := toJSONFindings(buildFindings(r)) @@ -979,8 +985,8 @@ func renderJSON(w io.Writer, r model.Report, opts RenderOptions) error { // 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) []jsonGroup { - groups, _ := GroupFiles(r, opts.spec()) +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 { -- 2.54.0 From 7159bc1b48de7ddf2ecadf088dcb7d6bc6776e38 Mon Sep 17 00:00:00 2001 From: James Maes <james@kof22.com> Date: Tue, 9 Jun 2026 07:45:58 -0500 Subject: [PATCH 17/18] docs(#35): close punch list; record review follow-ups and PR readiness --- docs/SESSION-STATE.md | 45 ++++++++++++++++++++++--------------------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/docs/SESSION-STATE.md b/docs/SESSION-STATE.md index 7108273..8ca89e2 100644 --- a/docs/SESSION-STATE.md +++ b/docs/SESSION-STATE.md @@ -1,41 +1,42 @@ # Session State -**Last Updated:** 2026-06-08 +**Last Updated:** 2026-06-09 ## Current Status -Two feature branches complete locally, both green (gofmt/vet/golangci-lint, `go test ./... -race`, 100% coverage gate, build). **Neither is pushed; no PRs opened.** +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). ## Active Branches | Branch | Base | Status | |--------|------|--------| -| `feature/GH-29-init-tui-wizard` | develop | Init TUI redesign — single-form + adaptive live preview; `wizard.go` is a thin adapter, logic in `internal/initwizard` at 100%. Complete, unpushed. | -| `feature/GH-35-audit-summary-reports` | develop | Audit reporting overhaul (current branch, 12 commits ahead). Complete, unpushed. Tree clean. | +| `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. | GH-29 and GH-35 are independent (touch different code); both branch from `develop`. -## What Was Done (GH-35, this work) -- `--summary` (counts-only) and `--group-by license|category|type|directory` across text/markdown/JSON; default output preserved. -- Attributable policy violations (which license/rule/file) in all formats — `policy.Violation` data was being discarded at `report.Build`; now surfaced via `model.ViolationDetail` / JSON `violationDetails`. -- `findings` + per-row percentages/totals + `riskLevel`/`worstCategory` parity in JSON & markdown (was text-only). -- Per-group risk markers + license breakdown (fixes directory-license-blindness); `(no-header)` rename; `--sort key|count`; `--depth N`; `--only missing,unknown,copyleft,violations`. -- JSON now always emits the full report (`--summary` trims human formats only). -- Two clean-room audits run: `docs/review/04-...` (pre) and `05-...` (post). 2nd audit: 6 addressed / 3 partial / 2 open, then 4 more fixed this turn. +## 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). -## Pending Work (GH-35 punch list — from `docs/review/05-...md`) -- [ ] `--group-by dependency` (deps can't be grouped; distinct code path — deps aren't files). -- [ ] Policy-aware group risk (a group's `[risk]` ignores repo-level incompatibilities, e.g. Apache group beside AGPL reads `low`). -- [ ] Exclude the tool's own `.license-tool.yaml` from source/header expectations (inflates `sourceTotal`/`sourceMissing`). Cheap. -- [ ] JSON explicit percentages/totals (low value; derivable from counts + `findings`). -- [ ] Dep resolver returned 0 for a `go.mod` require (likely module-cache dependent) — needs CI-verified repro. +## 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. ## Other Open Threads -- [ ] Push branches + open PRs into `develop` (awaiting permission) — GH-29 and GH-35. -- [ ] GH-29 commit `bafa281` bundled planning docs (CLAUDE.md/DESIGN/PLAN/review) via `git add -A` — optional history tidy before PR. -- [ ] Independent review bugs filed but untouched: #30 (detect over-match), #31 (spdxnorm guessing), #33 (symlink LICENSE), #34 (no-op --quiet/--verbose). #32 (include `**`) was fixed on GH-29. +- [ ] PRs are open into `develop` for #29 and #35 — awaiting review/merge by the author. +- [ ] GH-29 commit `bafa281` bundled planning docs (CLAUDE.md/DESIGN/PLAN/review) via `git add -A` — optional history tidy; not done (no autonomous history rewrite). +- [ ] Independent review bugs still untouched: #30 (detect over-match), #31 (spdxnorm guessing), #33 (symlink LICENSE), #34 (no-op --quiet/--verbose). #32 (include `**`) was fixed on GH-29. ## 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`, `docs/PLAN-GH-29-init-tui-redesign.md`. +- 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 must reference issues, no AI attribution. +- Repo: GitHub `KofTwentyTwo/license-tool`; default branch `develop`; commits reference issues, no AI attribution. -- 2.54.0 From 472d78b914a1b5d26747f8748fa7335ba97ede2e Mon Sep 17 00:00:00 2001 From: James Maes <james@kof22.com> Date: Tue, 9 Jun 2026 09:49:55 -0500 Subject: [PATCH 18/18] docs: track the six open PRs (#29/#30/#31/#33/#34/#35) and review notes --- docs/SESSION-STATE.md | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/docs/SESSION-STATE.md b/docs/SESSION-STATE.md index 8ca89e2..20cd1b5 100644 --- a/docs/SESSION-STATE.md +++ b/docs/SESSION-STATE.md @@ -29,10 +29,30 @@ GH-29 and GH-35 are independent (touch different code); both branch from `develo - 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 -- [ ] PRs are open into `develop` for #29 and #35 — awaiting review/merge by the author. -- [ ] GH-29 commit `bafa281` bundled planning docs (CLAUDE.md/DESIGN/PLAN/review) via `git add -A` — optional history tidy; not done (no autonomous history rewrite). -- [ ] Independent review bugs still untouched: #30 (detect over-match), #31 (spdxnorm guessing), #33 (symlink LICENSE), #34 (no-op --quiet/--verbose). #32 (include `**`) was fixed on GH-29. +- [ ] 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. -- 2.54.0