Repository navigation
Description
Refs #3768 (code-metrics 0.1.0 follow-ups). This is the audit-complexity leg of #3848: the skill was invoked through the Skill tool in a consumer session on this repository, first with no collectors installed, then with lizard, radon, multimetric, shellmetrics, gocyclo, and gocognit on PATH.
What was observed
Plugin 0.1.8 at 2dfaaa4, Claude Code on the web, branch at the default-branch head with a clean tree.
| Run | Scope | Result | Time |
|---|---|---|---|
| no collectors | change | empty, 0 files (branch at the merge-base) |
under 1s |
| no collectors | --all |
empty, exit 3: ESLint on PATH resolved, then failed with no eslint.config.js |
about 10s |
| collectors | --all |
partial, 1303 files, 12087 functions, 172 over cyclomatic 20 |
95s |
| collectors | change, one untracked .py |
partial, 1 file, 20 rows |
1s |
| collectors | --base HEAD~3 |
partial, 10 files, 5 in no lane |
2s |
| collectors | --json plugins/code-metrics/scripts |
932 rows, summary.functions 480 |
5s |
What worked: the coverage-of-this-run table with per-lane install hints, change scope including untracked files, --base, usage errors at exit 2, collectors batched per lane, and the code-metrics/v1 document shape.
Decisions
Agreed in an interview on 2026-09-08; each item below is independent and can be split into its own sub-issue by triage.
1. Join rows per function in the markdown renderer
One function yields one row per collector (lizard's cyclomatic row, radon's Halstead row), so the markdown table prints the same function twice with complementary nulls. In the plugin's own scripts/ directory, 441 of 932 rows share a (file, function) key. summarize() already dedups for the count; render() does not join.
Decision: join on (file, function, start_line) in render() only. The JSON keeps one row per collector, since that carries the provenance the schema promises and audit-coverage already joins those rows itself.
- The markdown Measures table shows each function once, with every measured value in that row.
- The JSON document is byte-identical to today's for the same scope.
2. Default scope exclusions for dependency and build-output directories
scope.exclude defaults to []. The whole-tree run measured a compiled bundle under a skill's output/build/lib/ and counted its functions toward the 172 over-reference rows.
Decision: ship a small default covering dependency and build-output directories only (node_modules, vendor, dist, build, and the like), reported in the excluded block. Fixtures and evals directories stay in scope; a consumer excludes those through scope.exclude.
- A whole-tree run on this repository reports the excluded directories in
excludedand measures nothing under them. reference/config.mddocuments the default list, bound toconfig-defaults.jsonby the existing gate.
3. Apply the sanctioned-replication registry to complexity rows
hook-utils.sh is vendored into about ten plugins. Its three functions over the reference (22, 45, 48) account for 30 of the 172 over-reference rows. duplication.registries exists for this case and only audit-duplication reads it.
Decision: lift the registry to a scope-level key every audit reads (keeping duplication.registries as an alias or migrating it), collapse replicas to one row carrying a replica count, and have this repository declare hook-utils.sh in its registry.
- The whole-tree complexity report shows one row per replicated function with the replica count, and the summary's over-reference count drops accordingly.
audit-duplicationbehaves as before under the lifted key.
4. Persist the JSON document in markdown mode
The renderer caps at 200 rows and prints "N more rows in the JSON", but the JSON lives in a mktemp directory the exit trap deletes.
Decision: always write the document under the plugin data directory and name its path in the truncation line.
- A markdown run whose table is truncated names an existing file that holds the full document.
5. Whole-tree performance, scoped to what the dispatcher owns
The 95-second run breaks down as shellmetrics 36s, multimetric 20s, detect-lanes 11s, and roughly 30s of per-file bash loops in dispatch.sh (about 74,000 xtrace lines for 3854 files: rebase_onto_cwd, exclusion matching). Change scope runs in one to two seconds, so this only bites --all.
Decision: run lanes in parallel (they are independent subprocesses), move the per-file path work into the existing pathglob.py helper, and print a progress line to stderr. The collectors' own run time is out of scope.
- A whole-tree run on this repository finishes in less than the sum of the collectors' own times plus a small constant, measured before and after.
- Progress is visible on stderr during a run longer than a few seconds.
6. Six small fixes, one item
- Sort over-reference rows by the over measure's value descending, then file; today they sort by file path and the highest values (79, 59, 48) are buried.
- Add a Labels column to the markdown table so
file-levelandstart-line-onlyrows are visible; the SKILL.md promises those labels and only the JSON carries them. - When the change scope is empty because the branch sits at the merge-base, say so in one line and name
--alland explicit paths. - Version probes:
multimetrichas no--versionandgocognitrejects-versionand--version, so the run table prints "unknown-version". Fall back topip showandgo version -m, or print "version unavailable (tool has no version flag)". - ESLint probe: with
eslinton PATH and no flat config, the ladder resolveseslint-complexity, the collect fails, and the run exits 3. Probe foreslint.config.*(or runeslint --print-configon one file) and reportunavailablewith that reason. - Footnote that a Halstead zero is a measurement (radon reports 0 for a function with no operators); it reads like a null today.
Acceptance criteria
- Each decision's bullets above hold on this repository at the plugin version that ships them.
- IF a collector resolves on PATH but cannot run (no configuration, no version flag), THEN the lane reads
unavailablewith the reason and the run exits 0 when any other lane measured. - WHILE the branch sits at the merge-base with a clean tree, the change-scope report says so and names the two alternatives.
- The plugin's own tests pass, and
scripts/affected-tests.sh --runselects at least one suite for every changed file.
Out of scope
- Installing collectors, or changing the "never installs" stance.
- Any finding, severity, or exit-code gate; references stay values to count against.
- The collectors' own run time.
- The plugin's own
report.pyhasrenderat cyclomatic 29 andassembleat 20, over its own reference. Noted for a tidying pass, not part of this issue.
Evidence
Reproduce on this repository with the collectors installed:
plugins/code-metrics/skills/audit-complexity/scripts/audit-complexity.sh --all
plugins/code-metrics/skills/audit-complexity/scripts/audit-complexity.sh --json plugins/code-metrics/scriptsThe second command's output shows the duplicate (file, function) keys; the first shows the replica rows, the build-output rows, and the run time.
Activity
fix(code-metrics): ground the principles skill in its primaries and a…