energy-state-analyzer 0.2.0 → 0.3.0

package/.markdownlint.json

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

package/CHANGELOG.md

@@ -1,5 +1,5 @@
 ---
-last_commit_released: b3dda28dffdd3dc8c6cee2d5b07d5a99d50761cb
+last_commit_released: 489d195ffe125b4e3ebcb9905f561f2d94daf1ad
 name: energy-state-analyzer
 updaters:
   - command: npm version {version} --no-git-tag-version --allow-same-version
@@ -11,6 +11,15 @@ 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

package/README.md

@@ -102,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.

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 }}