code-gauge 5.0.0 → 6.0.0

package/README.md

@@ -7,10 +7,11 @@
 [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
 [![wbfy](https://img.shields.io/badge/wbfy-20.23.1-1e90ff.svg)](https://github.com/WillBooster/shared/tree/main/packages/wbfy)
 
-A command-line tool that ranks the files of a project by refactoring priority and gates changes
-against metric regressions, built for AI-agent workflows: an agent asked to "refactor this
-repository" runs `code-gauge` and starts from the top of the list, and a PR pipeline runs
-`code-gauge diff --base main` to force the agent to self-correct a change that made the code worse.
+A command-line tool that ranks the files of a project by refactoring priority and checks code
+against metric thresholds, built for AI-agent workflows: an agent asked to "refactor this
+repository" runs `code-gauge` and starts from the top of the list, `code-gauge check` lists every
+function, file, and duplicated block over a threshold, and a PR pipeline runs
+`code-gauge check --base main` to make the agent fix the violations in the code its change touches.
 Measurement uses tree-sitter, and the output is deliberately small — only the metrics that tell an
 agent _what to change_ are measured and reported, so nothing in the output anchors an agent toward
 out-of-scope "improvements". A [programmatic API](#programmatic-api) is also available.
@@ -50,13 +51,16 @@ over three dimensions:
 - **File NCSS** — non-commenting source statements, a comment- and formatting-independent size
   measure calibrated against PMD's `NcssCount`.
 
-Ranking is relative to the scanned project, so no absolute thresholds are involved: the top of the
-list is worth refactoring first regardless of where any cutoff would sit. Each reported file carries
+Ranking is relative to the scanned project and ignores the
+[thresholds](#threshold-check-code-gauge-check): the top of the list is worth refactoring first
+regardless of where any cutoff would sit. Each reported file carries
 the concrete evidence (worst function with location, duplication with partner files, file size) so
 an agent can act on it directly.
 
 ## Options
 
+The ranking command (`code-gauge [target]`, or spelled out, `code-gauge rank [target]`) accepts:
+
 | Option                                     | Description                                                                     |
 | ------------------------------------------ | ------------------------------------------------------------------------------- |
 | `--config <path>`                          | Use this config file instead of the auto-detected `code-gauge.config.json`.     |
@@ -68,51 +72,162 @@ an agent can act on it directly.
 | `--duplication-max-gap-tokens <n>`         | Maximum token gap merged into one gapped clone group; 0 disables (default 30).  |
 | `--duplication-min-similarity-percent <n>` | Minimum similarity percent for near-miss clones; 100 = exact only (default 70). |
 
-## Regression gate (`code-gauge diff`)
+## Threshold check (`code-gauge check`)
 
 ```sh
-code-gauge diff --base main          # gate the working tree against the merge-base with main
-code-gauge diff --base main src/api  # gate only the changed files under src/api
+code-gauge check                     # every violation in the current directory
+code-gauge check --base main         # only violations in what the working tree changed since main
+code-gauge check --base main src/api # the same, for the changed files under src/api
+```
+
+`code-gauge check [target]` reports every violation of the thresholds below in the files under
+the target. Inside a git repository it measures the repository's git-visible files (tracked, or
+untracked and not ignored), so a block copied from a file outside the target is reported with that
+file as its partner, and a copy that exists only in a git-ignored file is not duplication. The
+built-in skipped directory names (`vendor`, `fixtures`, test directories, ...) apply below the
+target, as in the ranking command, so `code-gauge check vendor` checks what is in `vendor`. A
+git-ignored file is checked only when it is the target itself, and a directory git ignores (itself or
+through a parent directory) is an error as the target (exit code 2). A directory git does not
+ignore passes as a check of zero files when it holds no git-visible source file, for example when
+its only sources are ignored build output. Outside a git repository it walks the target directory
+like the ranking command. The thresholds:
+
+| Config key                        | Violation                                         | Default |
+| --------------------------------- | ------------------------------------------------- | ------- |
+| `maxFunctionCognitiveComplexity`  | a function's cognitive complexity is above it     | 15      |
+| `maxFunctionCyclomaticComplexity` | a function's cyclomatic complexity is above it    | 10      |
+| `maxFunctionNcss`                 | a function's NCSS is above it                     | 60      |
+| `maxFunctionNestingDepth`         | a function's nesting depth is above it            | 4       |
+| `maxFunctionParameterCount`       | a function's parameter count is above it          | 7       |
+| `maxFunctionHalsteadVolume`       | a function's Halstead volume is above it          | 2000    |
+| `maxFunctionHalsteadDifficulty`   | a function's Halstead difficulty is above it      | 20      |
+| `maxFunctionHalsteadEffort`       | a function's Halstead effort is above it          | 30000   |
+| `maxFunctionDepDegree`            | a function's DepDegree is above it                | 50      |
+| `maxFileNcss`                     | a file's NCSS is above it                         | 500     |
+| `minDuplicateLines`               | a duplicated block spans at least this many lines | 10      |
+
+A duplicated block is one occurrence of a within-file or cross-file clone, found with the
+[duplication detection settings](#duplication-detection-settings); its span runs from its first to
+its last line. Occurrences of at least `minDuplicateLines` lines that overlap in a file are
+reported as one block covering all of them.
+
+Each threshold is set in the [`thresholds` config section](#configuration), where `null` disables
+it and `languages` overrides thresholds for the files of one language, or with the command-line
+option of the same name (`--max-function-ncss 80`, `--min-duplicate-lines off`), where `off`
+disables it. The command line wins over the whole config file, per-language overrides included.
+
+With `--base <ref>`, the check covers only what the working tree changed since the merge-base of
+`<ref>` and `HEAD` (committed, staged, unstaged, and untracked changes; nothing is checked out):
+
+- a function, when a diff hunk touches its span; deleting lines inside the span counts, and so does
+  deleting lines after the last line of a Python function (blank and comment-only lines aside), which may have been its
+  tail;
+- a file-level threshold, when the change adds or deletes lines of the file (a rename or a mode
+  change alone does not count);
+- a duplicated block, when it overlaps lines the change added.
+
+`--base` only filters the report: the files measured and the duplication found are those of the
+check without it, so code pasted from an unchanged file is reported where it was pasted. A
+violation the change did not introduce is reported too once the change touches its function, file,
+or duplicated block. `--base` requires a git repository.
+
+When nothing violates a threshold, `check` prints a single line. Otherwise it prints a header with
+the counts, one line per violation ordered by path and line, and one remediation hint per violated
+metric:
+
+```
+Threshold violations: 3 violations (1 functions, 0 files, 2 duplicated blocks) (4 files, 5 functions checked).
+src/legacy.ts:1-21 decide: cognitive complexity 24 (<= 15), cyclomatic complexity 15 (<= 10), nesting depth 5 (<= 4)
+src/report.ts:1-12: duplicated lines 12 (< 10), also at src/summary.ts:1-12
+src/summary.ts:1-12: duplicated lines 12 (< 10), also at src/report.ts:1-12
+
+How to fix:
+- cognitive complexity: flatten nested branching with early returns and extract nested blocks into named functions.
+- cyclomatic complexity: the function has too many independent paths; split it by decision or replace condition chains with a lookup table.
+- nesting depth: replace nested conditions with guard clauses or move inner blocks into functions.
+- duplicated lines: extract the repeated code into one shared function or module and call it from every location.
+```
+
+A function gets one line listing every threshold it exceeds, a file-level violation prints the path
+without a line span, and a duplicated block lists up to three of its other copies. Paths are
+relative to the repository root, or to the target directory outside a git repository.
+
+| Exit code | Meaning                                                                                                                          |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| 0         | No violations.                                                                                                                   |
+| 1         | Violations. Whether they are warnings or errors is up to the caller.                                                             |
+| 2         | The check is incomplete: a file it covers could not be measured, or the arguments, config file, target, or base ref are invalid. |
+
+A file that cannot be measured causes exit code 2 only when the check covers it: a file under the
+target or, with `--base`, a changed file under the target. Other unmeasured files of the
+repository are warnings on stderr.
+
+`check` accepts `--config`, `--include-tests`, `--json`, and the `--duplication-*` options of the
+ranking command.
+
+### JSON report
+
+`code-gauge check --json` prints:
+
+```json
+{
+  "passed": false,
+  "base": "main",
+  "mergeBase": "9f624517156db3290e189b9fd0b8ed38de39a04c",
+  "summary": {
+    "violationCount": 2,
+    "functionViolationCount": 1,
+    "fileViolationCount": 0,
+    "duplicationViolationCount": 1,
+    "checkedFileCount": 2,
+    "checkedFunctionCount": 2
+  },
+  "violations": [
+    {
+      "kind": "function",
+      "file": "src/legacy.ts",
+      "startLine": 1,
+      "endLine": 21,
+      "name": "decide",
+      "exceeded": [
+        { "metric": "functionCognitiveComplexity", "value": 24, "limit": 15 },
+        { "metric": "functionCyclomaticComplexity", "value": 15, "limit": 10 },
+        { "metric": "functionNestingDepth", "value": 5, "limit": 4 }
+      ]
+    },
+    {
+      "kind": "duplication",
+      "file": "src/pasted.ts",
+      "startLine": 1,
+      "endLine": 12,
+      "exceeded": [{ "metric": "duplicateLines", "value": 12, "limit": 10 }],
+      "partners": [{ "file": "src/report.ts", "startLine": 1, "endLine": 12 }]
+    }
+  ],
+  "errors": [],
+  "warnings": []
+}
 ```
 
-`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 — 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:
-
-- **Existing functions — no worsening.** A matched function must not worsen its cognitive
-  complexity, NCSS, max nesting depth, DepDegree (approximate def-use pairs, Beyer & Fararooy
-  2010), or Halstead volume beyond a small configurable tolerance. No absolute threshold is
-  involved: "your change made this function worse" is defensible regardless of metric calibration.
-- **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.** 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
-  ratchet too; purely additive changes and unrelated remove-plus-add changes stay ungated.
-
-`--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. [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.
+- `passed`: `true` when there are no violations and no errors (exit code 0).
+- `base`, `mergeBase`: the `--base` ref and the commit compared against; absent without `--base`.
+- `summary`: the violation counts in total and per kind, and the number of files and functions
+  checked: those under the target or, with `--base`, the changed files under it and the functions
+  the change touches.
+- `violations`: ordered by `file`, then `startLine`. Each has
+  - `kind`: `function`, `file`, or `duplication`;
+  - `file`, `startLine`, `endLine`: the 1-based line span of the function or duplicated block; for
+    kind `file`, the first and last line of the file;
+  - `name`: only for kind `function`; `<anonymous>` for a function without a name;
+  - `exceeded`: every violated threshold with its `metric` (the config key without its `max` or
+    `min` prefix, e.g. `functionNcss` for `maxFunctionNcss`), the measured `value`, and the `limit`
+    in force. A value violates when it is above the limit; `duplicateLines` violates from the limit
+    on;
+  - `partners`: only for kind `duplication`; every other copy of the block, ordered by `file`, then
+    `startLine`.
+- `errors`: the files the check covers that could not be measured (exit code 2).
+- `warnings`: files measured without cross-file duplication data, and unmeasured files of the
+  repository the check does not cover.
 
 ## Configuration
 
@@ -127,22 +242,19 @@ with `--config`). The following config reproduces every built-in default:
     "minSimilarityPercent": 70
   },
   "rank": { "top": 10 },
-  "gate": {
-    "newFunction": {
-      "maxCognitiveComplexity": 15,
-      "maxNcss": 60,
-      "maxNestingDepth": 4
-    },
-    "tolerance": {
-      "cognitiveComplexity": 2,
-      "ncss": 5,
-      "nestingDepth": 1,
-      "depDegree": 10,
-      "halsteadVolume": 150,
-      "fileNcss": 20,
-      "duplicateLines": 0
-    },
-    "matchSimilarityPercent": 70
+  "thresholds": {
+    "maxFunctionCognitiveComplexity": 15,
+    "maxFunctionCyclomaticComplexity": 10,
+    "maxFunctionNcss": 60,
+    "maxFunctionNestingDepth": 4,
+    "maxFunctionParameterCount": 7,
+    "maxFunctionHalsteadVolume": 2000,
+    "maxFunctionHalsteadDifficulty": 20,
+    "maxFunctionHalsteadEffort": 30000,
+    "maxFunctionDepDegree": 50,
+    "maxFileNcss": 500,
+    "minDuplicateLines": 10,
+    "languages": {}
   },
   "exclude": [],
   "includeTests": false,
@@ -151,11 +263,29 @@ 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.
+rejected so stale configuration fails loudly. `rank.top` and `failOnError` apply to the ranking
+command only.
+
+`thresholds.languages` maps a language name (`javascript`, `jsx`, `typescript`, `tsx`, `python`,
+`go`, `rust`, `java`, `ruby`, `c`, `cpp`, `csharp`, `kotlin`) to the thresholds that differ for its
+files; a threshold it leaves out keeps the value set outside `languages`:
+
+```json
+{
+  "thresholds": {
+    "maxFunctionNcss": 60,
+    "maxFunctionHalsteadVolume": null,
+    "languages": {
+      "tsx": { "maxFunctionNcss": 100 },
+      "python": { "maxFunctionParameterCount": null }
+    }
+  }
+}
+```
 
 ### Excluded files
 
-Directory scans and the regression gate skip, besides the built-in directories and file names:
+Every command skips, 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);
@@ -166,6 +296,9 @@ Directory scans and the regression gate skip, besides the built-in directories a
   `// Code generated by <tool>. DO NOT EDIT.`). Mark a hand-written file `-linguist-generated` to
   keep it measured despite such a line.
 
+Inside a git repository, `code-gauge check` additionally skips the files git ignores (see
+[Threshold check](#threshold-check-code-gauge-check)).
+
 A file passed as the explicit target is always measured.
 
 ### Duplication detection settings
@@ -209,8 +342,7 @@ The `duplication` section tunes how clones are detected:
 - Per-function cyclomatic complexity (McCabe, own body only), counted as NIST SP 500-235 defines it:
   every decision and short-circuit operator adds one, one per case-labelled statement, plus the
   file total over McCabe's components (every function, every initializer block, decisions outside
-  functions, and the module body of a file that runs top-level code); an API-only metric that
-  ranking and the regression gate ignore
+  functions, and the module body of a file that runs top-level code)
 - 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
@@ -221,16 +353,16 @@ The `duplication` section tunes how clones are detected:
 - Cross-file duplication (via `measureCrossFileDuplication`): copy-pasted blocks shared between
   files, matched with the same normalization (exact, gapped, and near-miss clones) and reported as
   groups with their file locations
-- Halstead base counts, vocabulary, length, volume, and effort, per function and per file — the
-  strongest correlates of measured cognitive load in the EEG/fMRI validation literature
+- Halstead base counts, vocabulary, length, volume, difficulty (half the distinct operators times
+  the total operands per distinct operand; 0 without operands), and effort (difficulty times
+  volume), per function and per file
 - Per-function DepDegree (Beyer & Fararooy 2010), approximated as the number of variable reads
   with a preceding same-name definition (declaration, assignment, or parameter) in the function —
-  a file-local single-assignment approximation that is stable enough for regression ratcheting
+  a file-local single-assignment approximation
 
 Metrics that the validation literature shows to be weakly grounded or that invite misdirected
 "improvements" (call-graph fan-in/fan-out, coupling and cohesion counts, maintainability index,
-and similar) are intentionally not measured, and cyclomatic complexity is kept out of the CLI
-output for the same reason; see
+and similar) are intentionally not measured; see
 [issue #44](https://github.com/WillBooster/code-gauge/issues/44) for the rationale and references.
 
 ## Supported languages