energy-state-analyzer 0.10.1 → 0.12.0

package/.markdownlintignore

@@ -0,0 +1,9 @@
+# Auto-generated by ShipIt; uses inline HTML and repeated section headings on purpose.
+CHANGELOG.md
+
+# Third-party library markdown bundled inside build output / scratch dirs.
+node_modules/
+fable-out/
+fable-tests/
+out/
+.probe/

package/AGENTS.md

@@ -21,7 +21,9 @@ just watch         # Fable and webpack watchers
 just lint          # Fantomas check over F# source and tests
 just format        # Format F# source and tests
 just format-check  # CI formatting check
+just md-lint       # Check markdown formatting (CI check)
 just analyze       # Build, then run the F# CLI against src/ or supplied paths
+just fsharp-analyze# fsharp-analyzers (G-Research rules) over .fsproj; emits SARIF for CI
 just test          # Fable Scriptorium suite under Node
 just pack          # Production bundles + .vsix
 just clean         # Generated outputs and packages
@@ -36,7 +38,7 @@ webpack watch pipeline.
 
 ## Architecture
 
-Keep every F# file at or below 12 functions and 10 import sources. `src/EnergyState.fsproj` has
+Code-quality parameters such as function and import counts are enforced by the analyzer, not by hand-written limits here — the analyzer is authoritative on them, so AGENTS.md does not set those numbers. If the analyzer flags a file, fix it (or challenge the analyzer if you believe its verdict is wrong); otherwise treat its output as final. `src/EnergyState.fsproj` has
 `EnableDefaultCompileItems=false` behavior, so add every new `.fs` file explicitly in dependency
 order.
 
@@ -78,9 +80,31 @@ compiles the library project for the extension entry, then the CLI project for `
 The `.vsix` and npm package ship transpiled bundles, grammar WASMs, and metadata only. Keep F#
 sources, tests, `fable-out/`, `fable_modules/`, `bin/`, `obj/`, and maps excluded by ignore files.
 
+## F# analyzers (fsharp-analyzers)
+
+Beyond our own product analyzer, the repo runs the [fsharp-analyzers](https://g-research.github.io/fsharp-analyzers/) rule set over our written F# via a dedicated CI job (`fsharp-analyzers` in `.github/workflows/ci.yml`). It is wired through MSBuild:
+
+- `Directory.Build.props` adds `FSharp.Analyzers.Build` (the `AnalyzeFSharpProject` target) and `G-Research.FSharp.Analyzers` (the rules), and sets `RunAnalyzers=false` so these external rules never fire during Fable transpilation — the check is driven only through the explicit target.
+- `Directory.Build.targets` sets `FSharpAnalyzersOtherFlags` (`--analyzers-path`, `--code-root`, `--report`). The rule package version in that path (currently `0.23.0`) must match the SDK the rules were built against; pair it with matching tooling versions in `.config/dotnet-tools.json` (`fsharp-analyzers`), or the CLI refuses to load the analyzer DLL on an SDK-version mismatch.
+- `Directory.Build.*` are evaluated for every project, so their XML must be valid: **XML comments may not contain `--`** (write "the analyzers-path flag", not `--analyzers-path` inside a comment) — otherwise every project fails MSBuild evaluation and no SARIF is produced.
+- The `fsharp-analyzers` dotnet tool (0.37.2) is restored by the existing `dotnet tool restore` step; run it locally with `just fsharp-analyze [paths]`.
+
+The job is **soft-gated**: the `AnalyzeFSharpProject` target ignores the CLI exit code, so findings never fail the build, and a real restore/build/analysis error surfaces via the "Verify analyzer report exists" step (which fails loudly) instead of being hidden. A SARIF uploads per project to GitHub Code Scanning for triage over time. To make it blocking once the backlog clears, change the verify step to fail when results are non-empty.
+
+**Default-branch scanning.** GitHub marks a tool as scanning the default branch only after it receives a SARIF upload tied to a commit *on that branch*. PR uploads populate just the PR-level view (the `?query=pr:N` Code Scanning filter); a successful **push to `main`** — which fires on every merge — is what populates the repository-wide alerts, so keep the job's `push: branches: [main]` trigger intact. The job also triggers on `pull_request` (PR-level view) and `workflow_dispatch` (manual scan), and declares `permissions: security_events: write` so those non-PR contexts can upload SARIF. That permission is required for the SARIF upload step; without it, push-to-`main` uploads fail even though analysis succeeds.
+
+To force a scan of `main` on demand, run `just fsharp-scan-main` (or the equivalent `gh workflow trigger ci.yml --ref main`); it dispatches the CI job against `main` and uploads its SARIF. Use this if a push-to-`main` run fails — a failed upload leaves the default branch unscanned until one succeeds. Then check [Code Scanning](https://github.com/cardamomcode/energy-state-analyzer/security/code-scanning) for the default branch.
+
 ## Before committing or opening a PR
 
-Run `just format`, `just lint`, and `just analyze`. Triage every analyzer finding:
+**Never commit directly to `main`.** Always create and work on a feature branch off `main`
+(e.g. `fix/...`, `chore/...`, `ci/...`), open a PR from that branch targeting `main`, and never
+force-push onto `main`. Keep `main` matching `origin/main`; if you accidentally commit to `main`,
+reset it back to `origin/main` and carry the work on a feature branch instead. This keeps every
+change reviewable through a PR and preserves ShipIt's release flow, which reads conventional
+commit subjects from merged PRs.
+
+Run `just format`, `just lint`, `just md-lint`, and `just analyze`. Triage every analyzer finding:
 
 - **Real violation**: fix it.
 - **Wrong implementation**: add a fixture and integration test, then fix the detector.

package/CHANGELOG.md

@@ -1,5 +1,5 @@
 ---
-last_commit_released: b2795c89d9df95e46d26171a5393129c8f0208c3
+last_commit_released: f21dcbf98bde0c68ffe935b91e74432e39c26977
 name: energy-state-analyzer
 updaters:
   - command: npm version {version} --no-git-tag-version --allow-same-version
@@ -11,6 +11,31 @@ 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.12.0 - 2026-09-04
+
+### 🚀 Features
+
+* Add per-detector enable/disable toggles and color settings (#90) ([f21dcbf](https://github.com/cardamomcode/energy-state-analyzer/commit/f21dcbf98bde0c68ffe935b91e74432e39c26977))
+* *(core)* Add god-class detector to file-coherence check (#80) ([0da71cd](https://github.com/cardamomcode/energy-state-analyzer/commit/0da71cd1b518f1f2f8adea1e9f5613f5eddcbdc5))
+
+### 🐞 Bug Fixes
+
+* Resolve all fsharp-analyzers findings across F# source (#84) ([34892de](https://github.com/cardamomcode/energy-state-analyzer/commit/34892de4f18a9ae0564a004ed8668e74bcac5bd4))
+* Reduce remaining analyzer findings in TypeCohesion and Python functions (#89) ([94f2c38](https://github.com/cardamomcode/energy-state-analyzer/commit/94f2c380df809a7972442883218dfca942f29587))
+* *(analyzer)* Extract magic-number constants into named module-level bindings (#87) ([95b517c](https://github.com/cardamomcode/energy-state-analyzer/commit/95b517c0c559a3bb1753b3e4489672024d57e79e))
+* *(ci)* Scan the default branch via schedule + manual trigger (#86) ([e213496](https://github.com/cardamomcode/energy-state-analyzer/commit/e2134966acb85beeb7bedd6cbd0b820d2e96e3b2))
+
+<strong><small>[View changes on Github](https://github.com/cardamomcode/energy-state-analyzer/compare/7951a86146ecb0068b5d308f8a7b80134b819a4f..f21dcbf98bde0c68ffe935b91e74432e39c26977)</small></strong>
+
+## 0.11.0 - 2026-09-03
+
+### 🚀 Features
+
+* Make Core.Config the single source of truth for thresholds and options (#74) ([42dcd1d](https://github.com/cardamomcode/energy-state-analyzer/commit/42dcd1d32c29a19fc16cba2c3d4860d0f42f74e3))
+* *(core)* Make import-coherence thresholds configurable (#78) ([7951a86](https://github.com/cardamomcode/energy-state-analyzer/commit/7951a86146ecb0068b5d308f8a7b80134b819a4f))
+
+<strong><small>[View changes on Github](https://github.com/cardamomcode/energy-state-analyzer/compare/b2795c89d9df95e46d26171a5393129c8f0208c3..7951a86146ecb0068b5d308f8a7b80134b819a4f)</small></strong>
+
 ## 0.10.1 - 2026-09-02
 
 ### 🐞 Bug Fixes

package/Directory.Build.props

@@ -0,0 +1,33 @@
+<Project>
+  <PropertyGroup>
+    <!--
+      F# analyzer (fsharp-analyzers) integration.
+
+      We run the fsharp-analyzers host explicitly via the AnalyzeFSharpProject target
+      (see Directory.Build.targets and `just fsharp-analyze`), not during a normal build.
+      Our production build is Fable transpilation; we do not want these external rules firing
+      while `dotnet fable` type-checks, so compiler-integrated analysis is disabled here and the
+      check is driven only through the explicit target in CI or on demand.
+    -->
+    <RunAnalyzers>false</RunAnalyzers>
+    <RunAnalyzersDuringBuild>false</RunAnalyzersDuringBuild>
+    <EnableDefaultAnalyzerOutputs>false</EnableDefaultAnalyzerOutputs>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <!-- MSBuild hook: defines the AnalyzeFSharpProject / FSharpAnalyzerAfterBuild targets that
+         shell out to the `fsharp-analyzers` CLI. Restored as a normal package (not an analyzer
+         asset) because it contributes build targets, not compiler plugins. -->
+    <PackageReference Include="FSharp.Analyzers.Build" Version="0.5.0">
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+    <!-- The rule set (G-Research F# checker rules). Referenced as an analyzer asset so NuGet
+         extracts the DLL to disk; the CLI locates it via the analyzers-path flag (using $(
+        NuGetPackageRoot)) in Directory.Build.targets. RunAnalyzers=false above keeps it from
+         running at build time. -->
+    <PackageReference Include="G-Research.FSharp.Analyzers" Version="0.23.0">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+  </ItemGroup>
+</Project>

package/Directory.Build.targets

@@ -0,0 +1,13 @@
+<Project>
+  <PropertyGroup>
+    <!--
+      CLI arguments for the fsharp-analyzers host, consumed by the AnalyzeFSharpProject target.
+      Kept on ONE line: <Exec Command="..."> is passed to sh verbatim, so any newline in the
+      value would be treated as a separate command. analyzers-path points at the G-Research rule
+      DLL extracted from its NuGet package (resolved per machine via $(NuGetPackageRoot));
+      code-root makes SARIF positions relative to the repo root; report writes one SARIF per
+      project under fsharp-analyzer-reports/ (git-ignored) for CI code-scanning upload.
+    -->
+    <FSharpAnalyzersOtherFlags>--analyzers-path "$(NuGetPackageRoot)g-research.fsharp.analyzers/0.23.0/analyzers/dotnet/fs" --code-root "$(MSBuildProjectDirectory)/.." --report "$(MSBuildProjectDirectory)/../fsharp-analyzer-reports/$(MSBuildProjectName).sarif"</FSharpAnalyzersOtherFlags>
+  </PropertyGroup>
+</Project>

package/README.md

@@ -64,22 +64,41 @@ for the Extension Development Host.
 
 ## Extension Settings
 
-Detector thresholds are configurable under **Settings → Energy State Analyzer**. See each detector's doc (linked under Features above) for what a setting does; the keys and defaults are:
-
-- `energyStateAnalyzer.cyclomaticComplexity.mediumThreshold` / `.highThreshold` (`10` / `15`)
-- `energyStateAnalyzer.cognitiveComplexity.mediumThreshold` / `.highThreshold` (`15` / `25`)
-- `energyStateAnalyzer.coherence.largeFunctionLines` (`20`)
-- `energyStateAnalyzer.coherence.maxLargeFunctions` (`5`)
-- `energyStateAnalyzer.coherence.singleDomainNameShare` (`0.7`)
-- `energyStateAnalyzer.matchOpportunity.minBranches` (`3`)
+Settings split into two concerns: **which detectors run and how they look** live in VS Code (editor-only toggles and colors), while **how strict each detector is** lives in a project `.esaconfig.json` shared with the CLI/CI.
+
+### Enable/disable detectors and pick colors (VS Code settings)
+
+Every detector has an `enabled` toggle, plus the magic-number/string switches and the color palette. All toggles default to `true`. See each detector's doc (linked under Features above) for what it flags:
+
+- `energyStateAnalyzer.nesting.enabled` (`true`)
+- `energyStateAnalyzer.cyclomaticComplexity.enabled` (`true`)
+- `energyStateAnalyzer.cognitiveComplexity.enabled` (`true`)
+- `energyStateAnalyzer.coherence.enabled` (`true`)
+- `energyStateAnalyzer.matchOpportunity.enabled` (`true`)
+- `energyStateAnalyzer.parameterCount.enabled` (`true`)
+- `energyStateAnalyzer.primitiveObsession.enabled` (`true`)
+- `energyStateAnalyzer.opaqueBoolean.enabled` (`true`)
+- `energyStateAnalyzer.logicalControlFlow.enabled` (`true`)
+- `energyStateAnalyzer.inversion.enabled` (`true`)
 - `energyStateAnalyzer.magicNumber.enabled` (`true`)
-- `energyStateAnalyzer.magicNumber.allowlist` (`[0, 1, -1, 2]`)
 - `energyStateAnalyzer.magicString.enabled` (`true`)
-- `energyStateAnalyzer.magicString.minDuplicates` (`2`)
-- `energyStateAnalyzer.magicString.allowlist` (`["", "utf-8", "__main__"]`)
 - `energyStateAnalyzer.colors.highEnergy` / `.mediumEnergy` / `.lowEnergy` (`#fb8500` / `#ffb703` / `#99dd99`)
 - `energyStateAnalyzer.colors.backgroundOpacity` (`0.1`)
 
+### Thresholds and allowlists (`.esaconfig.json`)
+
+Set thresholds, ratios, and magic-number/string allowlists in an `.esaconfig.json` file to share them between the editor and CLI/CI — see [docs/configuration.md](docs/configuration.md) for the schema, per-key defaults, and how the file layers over VS Code settings (`defaults < .esaconfig.json < host override`). Thresholds are **not** configurable in VS Code on purpose: a project decides how strict its detectors are, and that decision travels with the repo. The keys (all optional; an absent key keeps its default) include:
+
+- `nesting.mediumThreshold` / `highThreshold` (`3` / `5`)
+- `cognitiveComplexity.mediumThreshold` / `highThreshold` (`15` / `25`)
+- `coherence.largeFunctionLines` (`20`), `maxLargeFunctions` (`5`), `singleDomainNameShare` (`0.7`)
+- `matchOpportunity.minBranches` (`3`)
+- `parameterCount.mediumThreshold` / `highThreshold` (`5` / `8`)
+- `magicNumber.allowlist` (`[0, 1, -1, 2]`)
+- `magicString.minDuplicates` (`2`), `allowlist` (`["", "utf-8", "__main__"]`)
+
+The magic-number/string `enabled` toggles above remain in VS Code — enabling or disabling a detector is an editor-only convenience, so it stays out of the shared project file.
+
 Changes take effect immediately on the active editor.
 
 To exclude files/folders (e.g. test fixtures, generated code) from both the extension's live analysis and the CLI, add a `.esaignore` file to your workspace root — see [`docs/cli.md`](docs/cli.md#excluding-files-and-folders-esaignore).