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