Skip to content

code-metrics: fix six audit-duplication gaps a whole-tree run exposed #4068

Closed

Description

@kyle-sexton

Summary

A whole-tree /code-metrics:audit-duplication --all run on this repository (jscpd, with scripts/cross-plugin-source-registry.txt) exposed six gaps in the skill. None is a wrong number per se; each is a number a reader cannot act on without re-deriving it.

  1. Size caps skip files silently while status reads complete. The jscpd adapter never sets --max-lines / --max-size, so jscpd 4.x's defaults (1000 lines, 100kb) dropped 84 in-scope files, including all 17 copies of hook-utils.sh, and the run still reported complete. jscpd 5.x has no line cap and a 1mb byte cap, so the two majors measure different scopes with the same config.
  2. The registry cannot express a canonical copy outside a plugin. Registry lines are paths-within-plugin, so the root lib/ and .claude/hooks/ sources that the sync-*.sh scripts copy from pair with their plugin copies and survive as duplication (11 groups, 4,470 lines). parse-concern-value.sh can never be a single-token line because its three plugin copies sit at different paths-within-plugin.
  3. Pair reporting inflates every count. jscpd reports pairs, so 17 copies arrive as 16 groups and one registry line's excluded total reads 50,176 lines for a 3,136-line file.
  4. The markdown report is unsorted, truncates at 200 rows, and has no rollup. Whole-file copies land mid-table; per-lane and per-directory totals need hand aggregation over the JSON.
  5. The summary line is a shared template. Functions: 0. Over reference: none. means nothing for duplication.
  6. A run with no detector gives no next step. Five identical lane rows repeat the install hint; nothing names /code-metrics:setup or offers the install.

Decisions

Locked through /planning:interview (two rounds) and grounded by five verified research runs; the contract is docs/topics/code-metrics-duplication-audit/PLAN.md on branch claude/code-metrics-duplication-audit-0z4y1i. In short:

  • Adapter pre-filters files by byte size and newline count, passes explicit caps on both jscpd majors, marks the lane partial naming what it skipped, and short-circuits the all-skipped case (jscpd 4.x then writes no report at all). Defaults: duplication.max_lines: null, duplication.max_size: 1mb, aligned with jscpd 5.0.7's parser guard and SonarJS's 1000kb rule; no upstream ships a line cap by default. statistics.total.sources was ruled out as a skip signal: it counts token sources, not files.
  • jscpd pairs merge into clone classes (union-find over identical file:start-end instances with equal lines) in a skill-local post-pass before the registry filter; N copies count once, per the clone-pair/clone-class distinction (Roy and Cordy 2007; Roy, Cordy and Koschke 2009; Bellon 2007) and PMD CPD / SonarQube practice.
  • Registry grammar gains multi-token lines: <canonical path> <copy path or glob>...; a group is excluded when every instance matches one token and instances sit in distinct carrying directories. Single-token lines unchanged. scripts/check-cross-plugin-source-drift.sh skips multi-token lines; six lines are added for this repo's canonical files. No clone detector models this relation (13 pools checked); the shape mirrors what each sync-*.sh already declares as src=.
  • Markdown sorts clone rows by lines descending and adds a ## Rollup section (per lane, per directory: cumulative up the tree, counts beside share, computed after exclusion, listed to duplication.rollup_depth default 2). JSON gains summary.by_lane / summary.by_directory as additive code-metrics/v1 fields; reference/report-schema.md states readers ignore unknown keys (RFC 9110 / RFC 9413; Google AIP-180 additive-change guidance; SonarQube and Codacy rollup precedent).
  • Duplication summary line becomes Files with clones: N. plus the existing duplicated-lines and exclusion lines.
  • No-detector run prints one consolidated headline naming the install command and /code-metrics:setup; SKILL.md tells Claude to offer the install and run it only on confirmation. The plugin still never installs anything.
  • jscpd 4.x and 5.x both stay supported (4.x is a maintenance line, latest-4 = 4.3.0); adapter docstring and reference/collectors.md corrected, pin bumped to 5.2.0 with the kind field noted.
  • Version 0.1.9; one draft PR closes this issue.

Evidence from the run

Run Files with clones Surviving groups Surviving duplicated lines Groups excluded by registry
jscpd 4.3.0 default cap 379 504 10,767 21
Cap raised via temporary .jscpd.json 432 705 16,498 37

Of the 16,498 surviving lines, roughly 4,470 are root-canonical pairs the registry could not express, ~8,300 are test scaffolding, and ~3,800 are ordinary non-test duplication (code-metrics collectors, knowledge extraction, disk-hygiene).

Acceptance

The Brief's acceptance criteria are the checklist; the headline ones: on this repository the audit reads identically under jscpd 4.3.0 and 5.2.0 with no file skipped at the shipped defaults; hook-utils.sh is one 17-instance group excluded once; zero surviving groups include a file under root lib/ or .claude/hooks/; the rollup sums agree with summary.duplicated_lines; scripts/affected-tests.sh --run passes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    needs-triageNot yet classified. Floor until a type and one priority tier are set.

    Type

    Fields

    No fields configured for Task.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions