energy-state-analyzer 0.1.2 → 0.3.0

package/.markdownlint.json

@@ -0,0 +1,4 @@
+{
+  "default": true,
+  "MD013": false
+}

package/CHANGELOG.md

@@ -1,5 +1,5 @@
 ---
-last_commit_released: 0cbd44479c8048e4313fae49fcb157a52900d5f6
+last_commit_released: 489d195ffe125b4e3ebcb9905f561f2d94daf1ad
 name: energy-state-analyzer
 updaters:
   - command: npm version {version} --no-git-tag-version --allow-same-version
@@ -11,6 +11,33 @@ All notable changes to the "energy-state-analyzer" extension are generated by
 [EasyBuild.ShipIt](https://github.com/easybuild-org/EasyBuild.ShipIt) from
 [Conventional Commits](https://www.conventionalcommits.org/).
 
+## 0.3.0 - 2026-08-25
+
+### 🚀 Features
+
+* Add Kotlin support and lazy-load language grammars (#21) ([3a1078e](https://github.com/cardamomcode/energy-state-analyzer/commit/3a1078ecac31ea1574635cb01f794e767b098183))
+* Repo scanning, PR baseline diffing, and a complexity-scored human report (#20) ([489d195](https://github.com/cardamomcode/energy-state-analyzer/commit/489d195ffe125b4e3ebcb9905f561f2d94daf1ad))
+
+<strong><small>[View changes on Github](https://github.com/cardamomcode/energy-state-analyzer/compare/b3dda28dffdd3dc8c6cee2d5b07d5a99d50761cb..489d195ffe125b4e3ebcb9905f561f2d94daf1ad)</small></strong>
+
+## 0.2.0 - 2026-08-25
+
+### 🚀 Features
+
+* Add opaque-boolean-literal detector (#16) ([d12447b](https://github.com/cardamomcode/energy-state-analyzer/commit/d12447bb07607c5fdc0b62781fb6df69ffbef1f4))
+
+### 🐞 Bug Fixes
+
+* Add braces to satisfy eslint curly rule (#10) ([8fd41cd](https://github.com/cardamomcode/energy-state-analyzer/commit/8fd41cde59103455a76ab1cbb504492578bbc3b3))
+* Tailor primitive-obsession advice to each language (#7) ([cf7807b](https://github.com/cardamomcode/energy-state-analyzer/commit/cf7807b55de2efbb0befd8a6a8a282f3a33215f3))
+* Cover primitive-obsession membership check with a test, correct heatmap color docs (#12) ([ba0050c](https://github.com/cardamomcode/energy-state-analyzer/commit/ba0050cb2b1894d0d90f7e80b273defa72f77277))
+* Split magic-value detection into separate number/string detectors (#13) ([4aca127](https://github.com/cardamomcode/energy-state-analyzer/commit/4aca127af06ee4ea2d71a4ccb8d47d26ef22014e))
+* Dogfood the extension's own CLI on its source, fix bugs it found (#14) ([bffadd3](https://github.com/cardamomcode/energy-state-analyzer/commit/bffadd3b2d50e700414ad313afdcc68be385125b))
+* Suppress primitive-obsession swap-risk for Python keyword-only params (#15) ([eb1c592](https://github.com/cardamomcode/energy-state-analyzer/commit/eb1c59211823a6dd2dff152be8bd536531b4648a))
+* Exempt Python module-level constants from magic-number detection (#17) ([0024607](https://github.com/cardamomcode/energy-state-analyzer/commit/0024607849eb0d15e5d5c5925a5e2b804b49616f))
+
+<strong><small>[View changes on Github](https://github.com/cardamomcode/energy-state-analyzer/compare/0cbd44479c8048e4313fae49fcb157a52900d5f6..b3dda28dffdd3dc8c6cee2d5b07d5a99d50761cb)</small></strong>
+
 ## 0.1.2 - 2026-08-24
 
 ### 🐞 Bug Fixes

package/README.md

@@ -8,13 +8,15 @@ Visualizes "energy states" in Python, F#, and TypeScript code as you edit: parts
 - **Cyclomatic complexity** — flags functions with too many independent execution paths (`if`/`for`/`while`/`except`/boolean operators/ternaries all count equally, regardless of nesting).
 - **Cognitive complexity** — flags functions that are hard to *read*, weighting each decision point by how deeply it's nested and not penalizing early-return guard clauses.
 - **Excessive nesting** — flags `if`/`for`/`while`/`with` blocks nested more than 3 levels deep.
-- **File coherence** — flags files with too many functions or imports (a sign of "utils/helpers sprawl"), and separately flags files with too many large functions (regardless of total function count, so languages like F# with many small functions per module aren't penalized).
-- **Magic values** — flags suspicious numeric/string literals used outside of a constant definition.
+- **File coherence** — flags files with too many functions or imports (a sign of "utils/helpers sprawl"), and separately flags files with too many large functions (regardless of total function count, so languages like F# with many small functions per module aren't penalized). A file where most functions share a leading name word (e.g. all `extractFoo`/`extractBar`) is treated as one coherent domain and exempted from the function-count check.
+- **Magic numbers** — flags numeric literals used outside of a named binding, an index/key position, or a default parameter value. Numbers get no free pass for "looking like prose" the way strings do, so this stays broad; an `energyStateAnalyzer.magicNumber.allowlist` setting (default `[0, 1, -1, 2]`) exempts the values that recur constantly without carrying hidden meaning.
+- **Magic strings** — flags a string literal only where an unnamed one actually risks a silent typo: compared with `==`/`===`, checked for membership (Python's `x in (...)`), or used as a dict/object key. A message being logged, thrown, or returned isn't a decision point, so it's left alone entirely — as is any f-string/template-literal/`.format()`/`%`-formatted string, since a placeholder is itself evidence the string isn't a stand-in for an enum value. To cut single-use false positives further, a qualifying literal is only flagged once it recurs at a decision point at least `energyStateAnalyzer.magicString.minDuplicates` times (default `2`) across the file.
 - **Parameter explosion** — flags functions with more than 5 parameters.
 - **Inversion opportunities** — flags large dominant `if` blocks and nested validation chains that could be rewritten as guard clauses with early returns.
-- **Primitive obsession** — flags consecutive same-typed primitive parameters (e.g. `lat: float, lon: float`) that callers can silently swap, and variables compared against 3+ distinct string literals (a de facto enum encoded as strings). Runs on Python, F#, and TypeScript; Python additionally flags a variable checked against a literal tuple/list/set in one `in` expression, since F# and TypeScript have no direct equivalent construct.
+- **Primitive obsession** — flags consecutive same-typed primitive parameters (e.g. `lat: float, lon: float`) that callers can silently swap, and variables compared against 3+ distinct string literals (a de facto enum encoded as strings). Runs on Python, F#, and TypeScript; Python additionally flags a variable checked against a literal tuple/list/set in one `in` expression, since F# and TypeScript have no direct equivalent construct. In Python, a same-typed pair is not flagged when both parameters are keyword-only (after a bare `*` or `*args` in the signature) since a caller can no longer pass them positionally — named-parameter naming is still a weaker mitigation than a distinct type (`NewType`, a dataclass, etc.), since nothing stops a future `**kwargs`-splat call from transposing the values. This suppression doesn't apply to TypeScript (no argument-labeling syntax for positional params) or F# (named arguments are optional at the call site, so they don't prevent a positional call).
 - **Match opportunities** — flags an `if`/`elif`/`elif` chain (or TypeScript's nested `else if`) of 3 or more branches that all compare the same single variable to a literal, suggesting a `match`/`switch` statement instead. Runs on Python, F#, and TypeScript.
 - **Logical operator as control flow** — flags a bare `condition && doSomething()` (or `condition || fallback()`) statement, an `if` hidden behind a boolean operator instead of written as one. Runs on Python and TypeScript; not on F#, which has no such statement-level idiom in its grammar.
+- **Opaque boolean literal** — flags a bare `true`/`false` passed positionally into a call (e.g. `configure(true)`), since a reader can't tell what it means without checking the callee's signature. Suppressed when the boolean is labeled at the call site: a Python keyword argument (`configure(retries=True)`), a TypeScript object-literal field (`configure({ retries: true })`), or F#'s named-argument syntax (`configure(retries = true)`) — unlike the primitive-obsession suppression above, F#'s named args count here even though they're optional, since this rule is about reader comprehension at this call site, not about preventing a future misuse. The preferred fix is usually splitting into two clearly named functions (`enableRetries()`/`disableRetries()`) or an enum; naming the argument is an acceptable but weaker mitigation. Deliberately conservative: only literal `true`/`false` are flagged, not bare `0`/`1`, to avoid noise on ordinary numeric arguments.
 
 Violations are shown three ways:
 
@@ -22,7 +24,7 @@ Violations are shown three ways:
 - A hover tooltip explaining the specific violation.
 - An entry in the Problems panel, sourced as "Energy State Analyzer".
 
-For functions flagged as too complex (cyclomatic or cognitive), a progressive red heatmap is also painted across the function body: each contributing line (an `if`, `for`, `and`, etc.) is shaded from light to dark red based on how much it drives up that function's complexity relative to its own worst line — so you can see exactly which branches to break apart first, instead of just knowing the function as a whole is complex.
+For functions flagged as too complex (cyclomatic or cognitive), a progressive heatmap in the configured high-energy color (orange by default) is also painted across the function body: each contributing line (an `if`, `for`, `and`, etc.) is shaded from light to dark based on how much it drives up that function's complexity relative to its own worst line — so you can see exactly which branches to break apart first, instead of just knowing the function as a whole is complex.
 
 ## Energy and Entropy
 
@@ -60,6 +62,21 @@ Modeled on [SonarSource's metric](https://www.sonarsource.com/resources/cognitiv
 
 This project's implementation is a simplified first pass on the SonarSource spec: `for`/`while` `else` clauses are scored like `if`/`else`, boolean-chain merging only looks at the immediate parent operator, and recursive calls aren't specially detected.
 
+### Interpreting the Scores
+
+A raw number like "34" doesn't mean much on its own. For cyclomatic complexity, McCabe's original 1976 paper proposed risk bands that are still the closest thing to an industry consensus (echoed by SonarQube, ESLint's `complexity` rule, and NIST guidance):
+
+| Score | Risk | Roughly |
+| --- | --- | --- |
+| 1–10 | Low | Simple, easy to test exhaustively |
+| 11–20 | Moderate | Getting harder to cover with tests |
+| 21–50 | High | Complex, testing all paths is impractical |
+| 50+ | Very high | Effectively untestable |
+
+Cognitive complexity has no equivalent formal consensus, since it's a newer, vendor-originated metric, but SonarSource's own convention (and this extension's defaults) treat **15** as the point where a function is hard enough to hold in your head that it's worth splitting up, with scores past 25 or so being seriously hard to follow regardless of how testable the underlying paths are.
+
+The two scores can diverge on the same function: a flat function with many independent branches can have high cyclomatic complexity but modest cognitive complexity (easy to read, hard to test exhaustively), while deeply nested code can be the reverse. See [Energy and Entropy](#energy-and-entropy) above for why this extension tracks them separately rather than collapsing them into one score.
+
 ## Command-Line Usage
 
 The same detectors also run headlessly, without VS Code — useful for CI or for an AI coding agent that wants to check the complexity of code it just generated and keep refactoring until it's clean. Published to npm, so no clone or install step is required:
@@ -85,6 +102,105 @@ npx energy-state-analyzer path/to/file.py \
 
 All threshold flags are optional: `--medium-nesting`, `--high-nesting`, `--medium-cyclomatic`, `--high-cyclomatic`, `--medium-cognitive`, `--high-cognitive`.
 
+### Scanning a repo or subtree
+
+Pass more than one path, a directory, or a `dir/**/*.ext`-style pattern to scan every supported file underneath it (skipping `node_modules`, `.git`, `dist`, `out`, `build`, `.next`, `coverage`, `.vscode-test`) and get an aggregated report instead of a single file's violations:
+
+```bash
+npx energy-state-analyzer src --report md
+```
+
+```
+# Energy State Report
+
+**3 files scanned** — 2 clean, 1 with violations
+
+| File | Score | High | Medium | Low |
+| --- | --- | --- | --- | --- |
+| src/foo.py | 13 | 1 | 1 | 0 |
+| src/bar.ts | 0  | 0 | 0 | 0 |
+| src/baz.fs | 0  | 0 | 0 | 0 |
+
+**Total score: 13** (1 high, 1 medium, 0 low)
+```
+
+`--report json` prints the same data as a structured `{ files, totalScore, totalCounts }` object instead. The per-file **score** is a simple heuristic — `1×low + 4×medium + 9×high` violation counts — meant for spotting hotspots and tracking direction over time, not a certified complexity metric.
+
+Only one glob shape is supported: a trailing `**/*.ext` pattern on an otherwise literal directory prefix (e.g. `src/**/*.py`). There's no brace expansion, negation, or mid-path wildcards — pass explicit directories/files for anything more complex.
+
+#### A report for humans: `--report human`
+
+`--report md`/`--report json` are compact, built for scripts and PR comments. `--report human` produces a longer, prose-and-tables report meant to be read by a person auditing a repo or subtree: a section per flagged file, each with its findings translated into plain language, followed by a repo-wide "Total evaluation":
+
+```bash
+npx energy-state-analyzer src --report human
+```
+
+```
+# Energy State Report
+
+## Score legend
+
+| Score | Risk | Roughly | Cyclomatic/cognitive complexity |
+| --- | --- | --- | --- |
+| 0.0 | None | No violations found | — |
+| 0.1–3.9 | Low | Simple, easy to test exhaustively | 1–10 |
+| 4.0–6.9 | Medium | Getting harder to cover with tests | 11–20 |
+| 7.0–8.9 | High | Complex, testing all paths is impractical | 21–50 |
+| 9.0–10.0 | Critical | Effectively untestable | 50+ |
+
+**25 files scanned** — 8 clean, 17 flagged
+
+## src/foo.py — High (score 7.8)
+
+- **Cyclomatic complexity**: 1 function scores 34 — score 7.8 (High): complex, testing all paths is impractical.
+- **Primitive obsession**: 2 findings (2 medium) — adjacent same-typed values a caller could silently swap without the compiler noticing.
+
+...
+
+## Total evaluation
+
+**Repo score: 7.8 (High)** — driven by the worst file in the scan, `src/foo.py` (complex, testing all paths is impractical).
+
+| Risk | Files |
+| --- | --- |
+| None | 8 |
+| Low | 12 |
+| Medium | 3 |
+| High | 2 |
+| Critical | 0 |
+
+**51 total findings** (1 high, 25 medium, 25 low) — breadth of issues across the scan, independent of peak severity.
+```
+
+Risk is reported on a 0.0–10.0 complexity score, sorted into the same None/Low/Medium/High/Critical levels used elsewhere in this tool, rather than a bespoke label set. The score is a direct re-expression of the McCabe risk table above: cyclomatic/cognitive complexity numbers are converted onto it by linear interpolation anchored at the same 10/20/50 breakpoints (see [Interpreting the Scores](#interpreting-the-scores)), so "High" here means the same thing it always has in this project, just expressed as a single number. Every other detector reports a finding count and severity instead, since it flags a pattern rather than a path count — a file with only non-complexity findings gets a fixed score from its worst one (Low 2.0 / Medium 5.0 / High 7.5), which can never reach Critical (Critical is reserved for genuinely extreme complexity).
+
+Both the per-file score and the repo-wide "Repo score" are the **maximum** found, not an average. Averaging a file's (or a repo's) scores lets one severely complex function or file hide behind many trivial ones — nine functions at complexity 2 and one at 60 average to about 8 (which itself would still misleadingly read as "Low"), hiding exactly the function most worth fixing. Total finding counts are reported separately as a breadth indicator, deliberately not folded into the same number. Flagged files are listed worst-first.
+
+### Diffing a PR against a base branch
+
+`--base-ref <ref>` compares the current working tree against a git ref, so a GitHub Actions job can report whether a PR increased or decreased complexity relative to its base branch:
+
+```bash
+npx energy-state-analyzer --base-ref origin/main --report md
+```
+
+With no path arguments, changed files are discovered via `git diff --name-only <ref>...HEAD`; pass explicit paths to override that. Each changed file's pre-PR content is read with `git show <ref>:<path>` and re-analyzed in memory — a file that doesn't exist at the base ref (new file, or a rename `git diff` didn't resolve) is reported as `new` rather than erroring out.
+
+```
+# Energy State Diff vs `origin/main`
+
+| File | Base | Head | Δ | Status |
+| --- | --- | --- | --- | --- |
+| src/foo.py | 4 | 13 | +9 | 🔴 worsened |
+| src/bar.ts | 9 | 0  | -9 | 🟢 improved |
+| src/new.py | — | 5  | — | 🆕 new |
+
+_2 files changed, 1 worsened, 1 improved, 1 new._
+```
+
+The exit code in every mode (single-file, scan, or diff) follows the same rule: `1` if any medium/high-severity violation exists in the current (head) code, `0` otherwise — whether a diff made things better or worse is visible in the report, not encoded as a separate exit code. `energy-state-cli <single-file>` with no other flags keeps its original behavior (flat JSON violation array, same exit rule) unchanged.
+
 ## Requirements
 
 The extension activates automatically when you open a Python, F#, or TypeScript file; it bundles its own grammars for parsing (via `web-tree-sitter`), so no external tools are required. F# files only get a `fsharp` language ID (and so trigger analysis) if you have an F# language extension installed (e.g. [Ionide](https://ionide.io/)) — VS Code otherwise treats `.fs` files as plain text.
@@ -97,8 +213,13 @@ Detector thresholds are configurable under **Settings → Energy State Analyzer*
 - `energyStateAnalyzer.cognitiveComplexity.mediumThreshold` / `.highThreshold`
 - `energyStateAnalyzer.coherence.largeFunctionLines` — line count above which a function counts as "large" (default `20`).
 - `energyStateAnalyzer.coherence.maxLargeFunctions` — number of large functions a file can contain before it's flagged (default `5`).
+- `energyStateAnalyzer.coherence.singleDomainNameShare` — share (0-1) of a file's functions that must share a leading name word (e.g. `extractFoo`/`extractBar`) to be treated as one coherent domain, skipping the function-count sprawl check (default `0.7`).
 - `energyStateAnalyzer.matchOpportunity.minBranches` — number of branches an if/elif chain must have, all keyed on the same variable, before it's flagged as a match/switch opportunity (default `3`).
-- `energyStateAnalyzer.magicValues.enabled` — whether to flag magic numbers and message-shaped string literals (default `true`).
+- `energyStateAnalyzer.magicNumber.enabled` — whether to flag magic numbers (default `true`).
+- `energyStateAnalyzer.magicNumber.allowlist` — numeric literals that are never flagged, regardless of context (default `[0, 1, -1, 2]`).
+- `energyStateAnalyzer.magicString.enabled` — whether to flag magic strings (default `true`).
+- `energyStateAnalyzer.magicString.minDuplicates` — number of times the same string literal must recur at a decision point before it's flagged (default `2`).
+- `energyStateAnalyzer.magicString.allowlist` — string literals that are never flagged, regardless of context (default `["", "utf-8", "__main__"]`).
 - `energyStateAnalyzer.colors.highEnergy` / `.mediumEnergy` / `.lowEnergy` — hex colors for the high/medium/low severity background tint and gutter icon (defaults `#fb8500` orange, `#ffb703` gold, `#99dd99` green).
 - `energyStateAnalyzer.colors.backgroundOpacity` — opacity of the severity background tint (default `0.1`).
 
@@ -110,7 +231,9 @@ Changes take effect immediately on the active editor.
 
 ## Known Issues
 
-- Nesting depth and parameter count thresholds are not yet configurable — only cyclomatic complexity, cognitive complexity, the large-function coherence check, the match-opportunity branch count, and the magic-value detector's on/off switch are.
+- Nesting depth and parameter count thresholds are not yet configurable — only cyclomatic complexity, cognitive complexity, the large-function coherence check, the match-opportunity branch count, and the magic-number/magic-string detectors are.
+- The magic-string detector's decision-point scan (equality/membership/dict-key) and its formatted-string exemption are fully implemented for Python and partially for TypeScript (no `.includes()` membership support yet) and F# (no dict/subscript node, no interpolated-string exemption) — see the `LanguageAdapter` fields in `src/core/language.ts` for exactly what's modeled per language.
+- The magic-string detector doesn't (yet) special-case enum-like keyword/default arguments (e.g. `mode="fast"`) as a lower-confidence decision point — only equality, membership, and dict/index-key positions count.
 - The inversion-opportunities detector only fires for Python and TypeScript; F#'s grammar has no block-boundary node to anchor that heuristic on (see Architecture).
 - TypeScript arrow functions aren't analyzed by complexity/parameter-count/coherence (same limitation Python already has for `lambda`) — only named `function` declarations and class methods are.
 - The primitive-obsession detector's `in (a, b, c)`-style membership check only runs on Python; F#'s grammar has no direct equivalent, and TypeScript's idiom (`[...].includes(x)`) is a call expression rather than a comparison node.

package/action.yml

@@ -0,0 +1,87 @@
+name: 'Energy State Report'
+description: 'Run energy-state-analyzer over a path or PR diff and post a Markdown report as a sticky PR comment.'
+author: 'dbrattli'
+branding:
+  icon: 'zap'
+  color: 'yellow'
+
+# Requires the caller's checkout step to use `fetch-depth: 0` when base-ref is
+# set, so both the head and base commits are present locally for `git diff`/
+# `git show` (see src/cliModes.ts's changedFilesFromGit/readAtRef).
+
+inputs:
+  path:
+    description: 'Path(s) to scan, space-separated. Ignored in diff mode (base-ref set), which only scans changed files.'
+    required: false
+    default: '.'
+  base-ref:
+    description: 'Git ref to diff the current HEAD against (e.g. origin/main). When set, runs in PR-diff mode instead of a full scan.'
+    required: false
+    default: ''
+  report-format:
+    description: 'Report format: md, json, or human. Diff mode (base-ref set) only supports md/json.'
+    required: false
+    default: 'md'
+  version:
+    description: 'energy-state-analyzer npm version or dist-tag to run via npx (e.g. 0.2.0, latest).'
+    required: false
+    default: 'latest'
+  fail-on-regression:
+    description: 'Fail the step when the analyzer reports a blocking result (scan mode: any medium/high violation; diff mode: any worsened file).'
+    required: false
+    default: 'true'
+  post-comment:
+    description: 'Post the report as a sticky PR comment. No-ops outside pull_request events.'
+    required: false
+    default: 'true'
+  comment-header:
+    description: 'Header used to identify and update the sticky PR comment across pushes.'
+    required: false
+    default: 'energy-state-report'
+
+outputs:
+  report-path:
+    description: 'Path to the generated report file.'
+    value: ${{ steps.run.outputs.report-path }}
+  exit-code:
+    description: 'Exit code returned by energy-state-analyzer (0 = clean, 1 = blocking violations/regressions).'
+    value: ${{ steps.run.outputs.exit-code }}
+
+runs:
+  using: composite
+  steps:
+    - name: Setup Node
+      uses: actions/setup-node@v5
+      with:
+        node-version: 22
+
+    - name: Run energy-state-analyzer
+      id: run
+      shell: bash
+      run: |
+        set +e
+        if [ -n "${{ inputs.base-ref }}" ]; then
+          npx --yes "energy-state-analyzer@${{ inputs.version }}" --base-ref "${{ inputs.base-ref }}" --report "${{ inputs.report-format }}" > energy-state-report.md
+        else
+          npx --yes "energy-state-analyzer@${{ inputs.version }}" ${{ inputs.path }} --report "${{ inputs.report-format }}" > energy-state-report.md
+        fi
+        code=$?
+        echo "exit-code=$code" >> "$GITHUB_OUTPUT"
+        echo "report-path=energy-state-report.md" >> "$GITHUB_OUTPUT"
+        # decision: always exit 0 here regardless of the analyzer's own exit code — a blocking
+        # result must still reach the comment step below (marocchino/sticky-pull-request-comment
+        # needs the report file to exist), so failure is deferred to the dedicated step at the
+        # end instead of short-circuiting the rest of this composite action.
+        exit 0
+
+    - name: Comment on PR
+      if: ${{ inputs.post-comment == 'true' && github.event_name == 'pull_request' }}
+      uses: marocchino/sticky-pull-request-comment@v2
+      with:
+        header: ${{ inputs.comment-header }}
+        path: ${{ steps.run.outputs.report-path }}
+
+    - name: Fail on regression
+      if: ${{ inputs.fail-on-regression == 'true' && steps.run.outputs.exit-code != '0' }}
+      shell: bash
+      run: exit ${{ steps.run.outputs.exit-code }}