code-gauge 4.8.0 → 5.1.0

package/README.md

@@ -27,8 +27,8 @@ code-gauge path/to/project
 ```
 
 The CLI scans JavaScript, JSX, TypeScript, TSX, Python, Go, Rust, Java, Kotlin, C#, Ruby, C, and
-C++ files. By default it skips generated, vendor, test, and tool directories and prints the top 10
-refactoring candidates:
+C++ files. By default it skips generated, vendor, test, and tool directories as well as
+[generated and excluded files](#excluded-files), and prints the top 10 refactoring candidates:
 
 ```
 Measured 123 files under /path/to/project (code LOC 45678, NCSS 23456, functions 1789)
@@ -78,8 +78,9 @@ code-gauge diff --base main src/api  # gate only the changed files under src/api
 `code-gauge diff --base <ref>` measures every changed file at both revisions (working tree vs. the
 merge-base of `<ref>` and `HEAD`, read with `git cat-file` — no checkout, no persisted baseline, so
 it works identically in CI and locally) and reports **only violations**. When every gate passes it
-prints a single line and exits 0; violations print one line each — metric, base → head values, the
-`file:line` span, and a remediation direction — and exit 1 (2 when files cannot be measured).
+prints a single line and exits 0; violations print one line each — the `file:line` span, the metric
+with its value and allowed bound (base → head for ratchets), and a remediation direction — and exit
+1 (2 when files cannot be measured).
 
 Functions are matched across revisions by name and arity, then by name alone, and finally by
 normalized-token LCS similarity, so renames and moves don't appear as delete+add. The gates:
@@ -91,9 +92,14 @@ normalized-token LCS similarity, so renames and moves don't appear as delete+add
 - **New functions — absolute thresholds.** Functions with no base counterpart are the one place
   absolutes are required (SonarQube-style "Clean as You Code"): cognitive complexity ≤ 15, NCSS
   ≤ 60, nesting depth ≤ 4 by default.
-- **No new duplication.** A changed file's duplicated lines (within-file plus cross-file against
-  the whole project, so copy-paste from unchanged code into new files is caught) must not exceed
-  the base revision's count.
+- **No new duplication.** The changed lines of a file must not newly duplicate code, within the
+  file or against the whole project (so copy-paste from unchanged code is caught where it was
+  pasted). Only added lines count, and only those whose normalized tokens a partner file repeats:
+  a file whose untouched code gained a copy elsewhere is not blamed for it, and an edit between
+  lines already duplicated with the same files, a clone rewritten in place against the same
+  files, or a clone moved elsewhere in the change is not new duplication, while code pasted next
+  to an existing clone, or replacing one with a copy of unrelated code, is. Added lines come from
+  `git diff`, like the hunks reviewers see.
 - **Anti-gaming backstops.** Splitting a function resets its entity identity and could hide a
   worsening behind the laxer new-code thresholds, so when a removed named function's content
   partially reappears in unmatched new code the file's max cognitive complexity and total NCSS
@@ -102,7 +108,9 @@ normalized-token LCS similarity, so renames and moves don't appear as delete+add
 `--full` additionally prints the base → head values of every checked function; `--json` prints a
 machine-readable report. The duplication flags and `--include-tests` work like the ranking command.
 The duplication universes contain only git-visible files (tracked or untracked non-ignored), so
-local ignored artifacts cannot skew the counts, and the Halstead volume allowance scales with the
+local ignored artifacts cannot skew the counts. [Excluded files](#excluded-files) are neither gated
+nor part of the universes; a base blob is judged by the git attributes of the merge-base, so code
+that stops being generated gates as new code. The Halstead volume allowance scales with the
 base value (25%, floored at the configured tolerance) so it admits the same ~5-statement edit at
 every function size.
 
@@ -136,6 +144,7 @@ with `--config`). The following config reproduces every built-in default:
     },
     "matchSimilarityPercent": 70
   },
+  "exclude": [],
   "includeTests": false,
   "failOnError": false
 }
@@ -144,6 +153,21 @@ with `--config`). The following config reproduces every built-in default:
 The command line wins over the config file, which wins over the defaults. Unknown settings are
 rejected so stale configuration fails loudly.
 
+### Excluded files
+
+Directory scans and the regression gate skip, besides the built-in directories and file names:
+
+- files matching an `exclude` glob pattern (e.g. `"exclude": ["src/legacy/**", "**/*.pb.ts"]`),
+  relative to the config file's directory and matched with Node's `path.posix.matchesGlob` (forward slashes on every platform);
+- files git attributes mark `linguist-generated` or `linguist-vendored` (the attributes GitHub
+  uses to collapse generated diffs, e.g. `src/api/** linguist-generated` in `.gitattributes`);
+- files with a generated-code marker in their first 5 lines: an `@generated` tag or a line
+  mentioning "generated" followed by "do not edit" / "do not modify" (e.g. Go's
+  `// Code generated by <tool>. DO NOT EDIT.`). Mark a hand-written file `-linguist-generated` to
+  keep it measured despite such a line.
+
+A file passed as the explicit target is always measured.
+
 ### Duplication detection settings
 
 The `duplication` section tunes how clones are detected:
@@ -190,7 +214,8 @@ The `duplication` section tunes how clones are detected:
 - Per-function parameter counts and locations (name, node type, line span)
 - Within-file duplication: copy-pasted blocks matched on normalized tokens (identifiers anonymized
   consistently, literals by kind, and literal-dense data tables excluded unless their values also
-  match), with adjacent matches around a small edit merged into gapped (Type-3) clone groups and
+  match; dependency declarations such as imports, package clauses, `#include`s, re-exports, and
+  `require`s carry no tokens, since every module must spell out its own), with adjacent matches around a small edit merged into gapped (Type-3) clone groups and
   near-miss (Type-3) clones matched by token-LCS similarity (tolerating reordered statements and
   copies embedded in added code), plus duplicated line count and ratio
 - Cross-file duplication (via `measureCrossFileDuplication`): copy-pasted blocks shared between