|
| 1 | +--- |
| 2 | +name: codelens |
| 3 | +description: >- |
| 4 | + Analyze codebase health with the codelens CLI: code stats, health scores |
| 5 | + (A-F), change hotspots, change coupling, ref-to-ref health diffs, and CI |
| 6 | + quality gates. Use this skill whenever the user asks about code quality, |
| 7 | + code health, technical debt, refactoring risk, "which files are risky or |
| 8 | + need refactoring", "what usually changes together", knowledge silos / bus |
| 9 | + factor, sizing up an unfamiliar repository, proving a refactor actually |
| 10 | + helped, or wiring a quality gate into CI or pre-commit — even when the user |
| 11 | + never mentions codelens by name. Also use it before large refactors to |
| 12 | + capture a baseline, and after them to measure the delta. |
| 13 | +--- |
| 14 | + |
| 15 | +# Codelens: code health analysis workflows |
| 16 | + |
| 17 | +Codelens is a fast code analysis CLI (Rust). It reads a source tree (and its |
| 18 | +git history) and answers: how big is this codebase, how healthy is it, where |
| 19 | +are the risky files, what changes together, and did this change make things |
| 20 | +better or worse. |
| 21 | + |
| 22 | +## Ground rules |
| 23 | + |
| 24 | +- **`--help` is the source of truth.** Run `codelens --help` and |
| 25 | + `codelens <subcommand> --help` for flags, defaults, and output formats. |
| 26 | + This skill teaches workflows and interpretation; do not assume flag |
| 27 | + details from memory. |
| 28 | +- **Use `-f json` when you consume the output yourself.** The console |
| 29 | + format is for humans. Explore the JSON shape with `jq` keys rather than |
| 30 | + assuming a schema. |
| 31 | +- **If a codelens MCP server is connected** (tools like `code_health`, |
| 32 | + `hotspots`, `change_coupling`), prefer those tools for quick read-only |
| 33 | + queries; fall back to the CLI for everything they don't cover (diffs, |
| 34 | + trends, gates, custom languages). |
| 35 | +- If `codelens` is not installed: `brew install DropFan/tap/codelens` or |
| 36 | + `cargo install codelens` (source: https://github.com/DropFan/codelens). |
| 37 | + |
| 38 | +## Workflow 1 — Size up an unfamiliar repository |
| 39 | + |
| 40 | +Use when onboarding onto a codebase or before estimating work in it. |
| 41 | + |
| 42 | +```bash |
| 43 | +codelens . # stats + health + cost estimate in one report |
| 44 | +codelens health . --top 10 # worst files and directories, A-F grades |
| 45 | +codelens hotspot . # risky files: frequently changed AND complex |
| 46 | +``` |
| 47 | + |
| 48 | +Read it in this order: overall size and language mix → project grade → |
| 49 | +which directories drag the grade down → which files are hotspots. A file |
| 50 | +that is both a hotspot and low-graded is where bugs most likely live; that |
| 51 | +is the first place to be careful in. |
| 52 | + |
| 53 | +The hotspot table also flags **knowledge islands**: risky files owned |
| 54 | +almost entirely by one author. Treat those as review/bus-factor risks, not |
| 55 | +just code-quality risks. |
| 56 | + |
| 57 | +## Workflow 2 — Risk assessment before touching a file |
| 58 | + |
| 59 | +Use before editing or refactoring a specific file the user cares about. |
| 60 | + |
| 61 | +```bash |
| 62 | +codelens hotspot . --functions # which functions absorb the churn |
| 63 | +codelens coupling . --for <FILE> # what usually changes together with it |
| 64 | +codelens health <dir-of-file> --top 5 # local health context |
| 65 | +``` |
| 66 | + |
| 67 | +Interpretation: |
| 68 | + |
| 69 | +- Coupling percentages are `shared commits / average commits of the pair`. |
| 70 | + High coupling with a file *outside* its module is a hidden dependency — |
| 71 | + plan to touch both, or you will ship half a change. |
| 72 | +- Test files are excluded from coupling by default (a test changing with |
| 73 | + its implementation is expected, not a hidden dependency). Add |
| 74 | + `--include-tests` when the user explicitly wants the test blast radius; |
| 75 | + pointing `--for` at a test file includes tests automatically. |
| 76 | +- `--functions` shows which functions inside a hotspot actually absorb the |
| 77 | + churn, so a refactor can target the hot function instead of the whole file. |
| 78 | +- An empty coupling result usually means the default noise thresholds are |
| 79 | + too strict for a low-churn file, not that nothing is coupled — lower |
| 80 | + `--min-shared` and `--min-coupling` and retry before concluding the file |
| 81 | + is isolated. |
| 82 | + |
| 83 | +## Workflow 3 — Prove a refactor helped (or catch a regression) |
| 84 | + |
| 85 | +Capture evidence, don't guess. Two interchangeable approaches: |
| 86 | + |
| 87 | +**Git refs** (no preparation needed): |
| 88 | + |
| 89 | +```bash |
| 90 | +codelens diff <BASE-REF> # base ref vs working tree |
| 91 | +codelens diff <REF-A>..<REF-B> # two refs |
| 92 | +``` |
| 93 | + |
| 94 | +**Snapshots** (works without clean refs, persists across sessions): |
| 95 | + |
| 96 | +```bash |
| 97 | +codelens trend --save --label before-refactor # before starting |
| 98 | +codelens health . --baseline latest # after: delta vs snapshot |
| 99 | +``` |
| 100 | + |
| 101 | +Report the movement, not just the endpoint: "health 79.7 (C) → 84.2 (B), |
| 102 | +file-size dimension F → A" is the sentence the user wants. Per-file grade |
| 103 | +drops listed by `diff` are the regressions to fix before shipping. |
| 104 | + |
| 105 | +## Workflow 4 — Quality gates in CI |
| 106 | + |
| 107 | +Use when the user wants declining code health to block PRs. |
| 108 | + |
| 109 | +```bash |
| 110 | +codelens health . --fail-under B # absolute gate |
| 111 | +codelens health . --baseline main --fail-on-regression # only NEW debt fails |
| 112 | +codelens diff main --fail-on-regression # ref-to-ref gate |
| 113 | +``` |
| 114 | + |
| 115 | +Choosing a gate: `--fail-under` enforces a floor (legacy debt counts); |
| 116 | +`--fail-on-regression` implements "clean as you code" (only changes fail |
| 117 | +the gate, pre-existing debt never does) — usually the right default for |
| 118 | +older codebases. There is an official GitHub Action and a pre-commit hook; |
| 119 | +see the repository README for current wiring. |
| 120 | + |
| 121 | +## Interpretation guide (stable concepts) |
| 122 | + |
| 123 | +- **Grades**: A is healthy, C is "needs attention", F drags the project |
| 124 | + down. The project score aggregates per-dimension scores (complexity, |
| 125 | + function size, comments, file size, nesting, duplication — run |
| 126 | + `codelens health --help` for the current set). |
| 127 | +- **Hotspot = churn × complexity.** Frequently changed simple files are |
| 128 | + fine; complex stable files are fine; the intersection is where defects |
| 129 | + cluster. Age and author concentration qualify the risk. |
| 130 | +- **A dimension can be legitimately absent.** On very large repositories, |
| 131 | + `--no-dup-scan` skips duplication collection to save memory; the health |
| 132 | + score then omits that dimension and renormalizes — it is *not* scored as |
| 133 | + perfect. Machine-readable output names the scoring model so you can tell. |
| 134 | +- **Expected noise**: generated/vendored code is auto-excluded by default |
| 135 | + (gitignore, linguist attributes, smart excludes). If numbers look |
| 136 | + inflated, check what was scanned before distrusting the tool — `--by-file` |
| 137 | + or `-v` shows what got counted. |
| 138 | +- **Test stats count separate test FILES only.** Languages that inline |
| 139 | + tests into source files (Rust `#[cfg(test)]`, D `unittest`) will show a |
| 140 | + near-zero test ratio even with excellent coverage. Verify with a quick |
| 141 | + grep before reporting "this project lacks tests". |
| 142 | + |
| 143 | +## Situational flags worth knowing |
| 144 | + |
| 145 | +| Situation | Flag | |
| 146 | +|---|---| |
| 147 | +| Huge repo, memory pressure | `--no-dup-scan` | |
| 148 | +| Agent-consumed output | `-f json` (also: csv, markdown, html, sarif, openmetrics) | |
| 149 | +| Unrecognized in-house language / DSL | `--languages-file <toml>` (schema in README) | |
| 150 | +| Extension counted as wrong language | `--count-as ext:lang` | |
| 151 | +| Monorepo subtree | pass the subdirectory as the path argument | |
| 152 | + |
| 153 | +Anything else: `codelens <subcommand> --help`. |
0 commit comments