energy-state-analyzer 0.7.0 → 0.8.0

package/.esaignore

@@ -1,6 +1,6 @@
 # Paths the energy-state analyzer itself should not scan.
 # One pattern per line — a literal path/directory (also matches at any depth if it has no
-# '/'), or a single '*' basename glob. See src/core/esaignore.ts for the exact rules.
+# '/'), or a single '*' basename glob. See src/Core/Esaignore.fs for the exact rules.
 
 # Deliberately bad/deeply-nested code used only to exercise the detectors themselves.
 src/test/fixtures

package/.vscodeignore

@@ -3,14 +3,20 @@
 out/**
 node_modules/**
 src/**
+tests/**
+cli/**
+fable-out/**
+fable-tests/**
 .gitignore
 .yarnrc
 webpack.config.js
 vsc-extension-quickstart.md
-**/tsconfig.json
-**/eslint.config.mjs
 **/*.map
-**/*.ts
+**/*.fs
+**/*.fsproj
+**/bin/**
+**/obj/**
+**/fable_modules/**
 **/.vscode-test.*
 .claude/**
 CLAUDE.md

package/AGENTS.md

@@ -1,84 +1,100 @@
 # AGENTS.md
 
-This file provides guidance to AI coding agents when working with code in this repository.
+## Project overview
 
-## Project Overview
+Energy State Analyzer is a VS Code extension and CLI that analyze Python, F#, TypeScript, and
+Kotlin through `web-tree-sitter` grammars in `grammars/`. Product source is F# and is compiled
+by Fable 5 to JavaScript before webpack packages the extension and CLI.
 
-Energy State Analyzer is a VS Code extension that visualizes "energy states" in Python, F#, TypeScript, and Kotlin code via real-time static analysis. It parses source with `web-tree-sitter` (per-language WASM grammars in `grammars/`) and highlights code that is complex, deeply nested, or otherwise hard to maintain using editor decorations, gutter icons, and Problems-panel diagnostics.
+See `energy-state.md` for the original design rationale and `docs/fable-rewrite-plan.md` for the
+completed migration and current build graph.
 
-See `energy-state.md` for the original design doc (energy-state principle, planned "detection agents", and known issues/next steps at project inception).
+## Build commands
 
-## Build Commands
-
-Commands are wrapped in a `Justfile`; run `just --list` to see all of them. Prefer these over calling `npm run` directly.
+Prefer `Justfile` recipes:
 
 ```bash
 just install       # npm install
-just build         # Build extension bundle via webpack (dev mode)
-just watch         # Webpack in watch mode
-just lint          # ESLint over src/**/*.ts
-just format        # Format src/**/*.ts in place with Prettier
-just format-check  # Check formatting without writing changes (used by CI)
-just analyze       # Run the CLI's own analyzer over src/ (or `just analyze <path...>` for specific files/dirs)
-just test          # compile-tests + compile + lint, then run the VS Code extension test host
-just pack          # Production build + package into a .vsix via vsce
-just clean         # Remove build artifacts (dist, out, *.vsix)
+just fable         # F# -> Fable JavaScript in fable-out/
+just build         # Fable + webpack development bundles
+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 analyze       # Build, then run the F# CLI against src/ or supplied paths
+just test          # Fable Scriptorium suite under Node
+just pack          # Production bundles + .vsix
+just clean         # Generated outputs and packages
 ```
 
-The underlying `npm run` scripts (`compile`, `watch`, `package`, `lint`, `format`, `format-check`, `compile-tests`, `watch-tests`, `pretest`, `test`, `analyze`) still work directly if you need finer control than the Justfile recipes give you.
-
-To run and debug the extension interactively, press `F5` in VS Code — this launches an Extension Development Host with the extension loaded, per `.vscode/launch.json`.
+Fable commands use `--lang javascript --noCache`. Fable emits ESM, so test output receives a
+`{"type":"module"}` shim. Webpack consumes those ESM files and preserves the public CommonJS
+contracts: `dist/extension.js`, `dist/cli.js`, and the CLI shebang.
 
-There is a single test suite (`src/test/extension.test.ts`); there's no mechanism yet to run a single test by name — use the Extension Test Runner's Testing view in VS Code, or edit the suite temporarily with `.only`.
+Press `F5` to launch an Extension Development Host; `.vscode/tasks.json` runs the Fable and
+webpack watch pipeline.
 
 ## Architecture
 
-Everything lives in one file, `src/extension.ts`, structured as:
-
-1. **Activation (`activate`)** — initializes the tree-sitter `Parser`, creates decoration types, registers the `energy-state-analyzer.analyze` command, and wires up editor/document change listeners to re-analyze on the fly. Each language's grammar (`grammars/tree-sitter-<language>.wasm`, path resolved via `context.extensionPath`) is loaded lazily on first use of that language, not up front — see `getOrLoadLanguage`. Activation is gated by the `onLanguage:*` entries in `package.json` (python, fsharp, typescript, kotlin).
-2. **Analysis pipeline (`analyzeDocument`)** — parses the active document's text into a tree-sitter AST, then runs a fixed set of independent detector passes over it, each returning `EnergyViolation[]`:
-   - `analyzeNesting` — flags `if`/`for`/`while`/`with` nesting deeper than 3 levels.
-   - `analyzeFunctionComplexity` — computes cyclomatic complexity per function, flags >10.
-   - `analyzeFileCoherence` — flags files with too many functions or imports (utils/helpers sprawl).
-   - `analyzeMagicValues` — flags "magic" numeric/string literals outside constant context.
-   - `analyzeParameterCount` — flags functions with >5 parameters.
-   - `analyzeInversionOpportunities` — flags large dominant if-blocks, nested validation chains, and deep if-nesting that could be rewritten as guard clauses / early returns.
-   - `extractTypeInformation` — walks the AST separately to collect function/class/variable/import type info (currently only logged; scaffolding for future features, not yet used for violations).
-   Each detector does its own `traverse(node)` walk of the tree-sitter tree; there's no shared visitor abstraction.
-   `src/core/analyze.ts` (the actual current pipeline entry point) runs a larger, up-to-date set of these plus `applySuppressions` (`src/core/suppressions.ts`) as a final pass — it filters out violations covered by an `esa-ignore`/`esa-ignore-file` comment and emits low-severity `suppression` findings for directives that are unused or name an unknown type. See `docs/detectors/suppression.md`.
-3. **Presentation** — `applyDecorations` maps violations to `vscode.TextEditorDecorationType` ranges (color/severity: red=high, yellow=medium, green=low, rendered as background tint + gutter lightning-bolt icon via `createLightningIcon`), and `updateProblemsPanel` mirrors the same violations into a `vscode.DiagnosticCollection` so they also show in the Problems panel.
-4. **Violation model** — `EnergyViolation { line, column, type, severity, message }`, with `type` and `severity` string-literal unions backed by the `VIOLATION_TYPE`/`SEVERITY` constant objects near the top of the file (keep these two in sync when adding a new detector).
-
-### Adding a new detector
-
-Follow the existing pattern: write an `analyze<Thing>(tree, document): EnergyViolation[]` function that walks `tree.rootNode`, push it into the list in `analyzeDocument`, and add a new `VIOLATION_TYPE` entry if it's a new category. If the violation needs special range highlighting, add a case in `applyDecorations`.
-
-### Build/packaging notes
-
-- Webpack bundles `src/extension.ts` → `dist/extension.js` (CommonJS, `vscode` module treated as external).
-- `web-tree-sitter`'s own `tree-sitter.wasm` is copied into `dist/` via `CopyWebpackPlugin` (webpack.config.js); the per-language grammar WASMs in `grammars/` ship separately and are loaded at runtime by path, not bundled.
-- `tsconfig.json` targets ES2022/commonjs with `strict: true`.
-
-## Before Committing or Opening a PR
-
-Run `just format`, `just lint`, and `just analyze` (this project dogfoods its own analyzer over `src/`) before every commit or PR, and fix what they flag. Don't rely on CI to catch formatting, lint, or energy-state violations you could have caught locally.
-
-If satisfying `just analyze` on your change requires refactoring existing code (e.g. splitting a file to fix a coherence violation, extracting a function to fix complexity/nesting) rather than just the new code you're adding, do that refactor as its own preceding PR, merged before the PR with the actual change. Don't mix the two in one PR — a refactor bundled with a behavior change makes the diff hard to review and obscures what the change is actually about.
-
-## Releasing
-
-Release automation runs through EasyBuild.ShipIt (see `RELEASING.md`). Use
-Conventional Commit subjects (`feat:`, `fix:`, `docs:`, `chore:`, `ci:`, etc.)
-for commits and PR titles — CI enforces this on PR titles, and ShipIt uses
-them to generate `CHANGELOG.md` and open release PRs. Do not hand-edit
-generated changelog entries or bump `package.json`'s version manually.
-
-## Agent Decision Comments
-
-This repository uses Agent Decision Comments.
-See `AGENT_DECISION_COMMENTS.md` for the locally adopted convention.
-Upstream releases: https://github.com/dbrattli/adc/releases
-
-Before modifying code, read the ADCs already governing it.
-Treat them as active constraints and justify any change explicitly.
-Add ADCs for non-obvious rationale introduced by your change.
+Keep every F# file at or below 12 functions and 10 import sources. `src/EnergyState.fsproj` has
+`EnableDefaultCompileItems=false` behavior, so add every new `.fs` file explicitly in dependency
+order.
+
+- **`src/Core/`**: host-independent synchronous detector pipeline, tree-sitter facade,
+  suppression, scanning, and report rendering. `Analyze.fs` is the one detector composition
+  point shared by extension and CLI.
+- **`src/Languages/`**: grammar-specific `LanguageAdapter` records for the four supported
+  analyzed languages.
+- **`src/Extension/`**: VS Code Fable facade, configuration boundary, grammar cache, analysis
+  orchestration, editor/Problems presentation, and `Extension.fs` composition root. The narrow
+  VS Code bindings (`Host`, `Document`, `Workspace`, `Presentation`, `Diagnostics`,
+  `DiagnosticValues`, `Identity`) live in the `src/Extension/Vscode/` subfolder with their
+  `Vscode*` prefix dropped from both path and module name. `DecorationModel.fs`,
+  `DiagnosticModel.fs`, and `ConfigurationValues.fs` remain pure and have direct Scriptorium
+  coverage.
+- **`src/Cli*.fs` and `cli/Main.fs`**: CLI argument parsing, modes, runtime, narrow Node
+  bindings, and Fable entry point. Scan, legacy single-file, `--report`, `--base-ref`, and
+  thresholds share the Core pipeline.
+- **`tests/`**: F# Scriptorium suites. `src/test/fixtures/` is retained only as multi-language
+  analyzer input, including `.ts` fixtures; it is not TypeScript product or test code.
+
+The extension composition root owns lifecycle state, grammar caches, decorations, diagnostics,
+commands, and editor/document/configuration event subscriptions. Presentation never leaks into
+`Core/`; `Core/TreeSitter.fs` is the only web-tree-sitter facade.
+
+`EnergyViolation` is the DU/record model in `src/Core/Violation.fs`. Add a new detector by adding
+its `Detector` to `Core/Analyze.fs`, and add a `ViolationType` case plus special presentation
+mapping only when required.
+
+## Build and packaging
+
+`npm run fable` writes generated JavaScript and `fable_modules` to ignored `fable-out/`. It first
+compiles the library project for the extension entry, then the CLI project for `Main.js`.
+`webpack.config.js` consumes only generated `.js`, treats `vscode` as an external, bundles
+`web-tree-sitter`, copies its WASM, and emits the fixed output names. Do not add `ts-loader`,
+`tsconfig.json`, or TypeScript product tooling back.
+
+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.
+
+## Before committing or opening a PR
+
+Run `just format`, `just lint`, and `just analyze`. Triage every analyzer finding:
+
+- **Real violation**: fix it.
+- **Wrong implementation**: add a fixture and integration test, then fix the detector.
+- **Wrong threshold**: adjust the detector/configuration threshold with a boundary test.
+- **Legitimate exception**: use a reasoned `esa-ignore` directive; stale directives remain
+  findings.
+
+Do not suppress a finding merely to make a check pass. If a required cleanup is unrelated to the
+behavior change, land it separately rather than mixing it into the behavioral change.
+
+## Releasing and decision comments
+
+ShipIt release automation is described in `RELEASING.md`. Use Conventional Commit subjects; do
+not hand-edit generated changelog entries or package versions.
+
+This repository uses Agent Decision Comments. Read `AGENT_DECISION_COMMENTS.md` before modifying
+governed code, preserve active `decision:` and `invariant:` comments, and add one for a
+non-obvious durable design choice.

package/CHANGELOG.md

@@ -1,5 +1,5 @@
 ---
-last_commit_released: 5d63923aba3248095bda4074aff14bb133f4f65b
+last_commit_released: 01777cc27c9c08136661a2f1e21409cdf94f05ce
 name: energy-state-analyzer
 updaters:
   - command: npm version {version} --no-git-tag-version --allow-same-version
@@ -11,6 +11,22 @@ 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.8.0 - 2026-08-31
+
+### 🚀 Features
+
+* Rewrite analyzer in F# for Fable (#46) ([8aaf666](https://github.com/cardamomcode/energy-state-analyzer/commit/8aaf6666c537b9f1655175805128749e56b8d933))
+* *(core)* Calculate McCabe cyclomatic complexity (#55) ([9a42b6a](https://github.com/cardamomcode/energy-state-analyzer/commit/9a42b6a68cf94c7583c1d1a8282ddffa961275c7))
+* *(core)* Add include-test-files toggle for magic detectors (#57) ([271e15c](https://github.com/cardamomcode/energy-state-analyzer/commit/271e15c8a914f550a5079789750a71caba34181d))
+* *(extension)* Split src/extension.ts by domain (#30) (#42) ([b9f1ba3](https://github.com/cardamomcode/energy-state-analyzer/commit/b9f1ba37d93cbfd34275814a7bdbfb591cd9ae06))
+
+### 🐞 Bug Fixes
+
+* *(extension)* Construct VS Code diagnostics correctly (#54) ([c9b2f3f](https://github.com/cardamomcode/energy-state-analyzer/commit/c9b2f3f4a8c1c6550776bc1b1b8c611483fba7b3))
+* *(suppressions)* Anchor esa-ignore directive regex so prose isn't matched (#45) ([c99b26a](https://github.com/cardamomcode/energy-state-analyzer/commit/c99b26ae425f16c16460b42d474dd52934f3610d))
+
+<strong><small>[View changes on Github](https://github.com/cardamomcode/energy-state-analyzer/compare/5d63923aba3248095bda4074aff14bb133f4f65b..01777cc27c9c08136661a2f1e21409cdf94f05ce)</small></strong>
+
 ## 0.7.0 - 2026-08-28
 
 ### 🚀 Features

package/README.md

@@ -1,10 +1,10 @@
 # Energy State Analyzer
 
-Visualizes "energy states" in Python, F#, and TypeScript code as you edit: parts of a file that are complex, deeply nested, or otherwise harder to understand and maintain get highlighted with colored gutter icons, inline decorations, and entries in the Problems panel.
+Visualizes "energy states" in Python, F#, TypeScript, and Kotlin code as you edit: parts of a file that are complex, deeply nested, or otherwise harder to understand and maintain get highlighted with colored gutter icons, inline decorations, and entries in the Problems panel.
 
 ## Features
 
-Real-time analysis of the active Python, F#, or TypeScript file, re-run on every edit and on editor focus change, via these detectors (see [docs/detectors](docs/detectors/README.md) for full detail on each):
+Real-time analysis of the active Python, F#, TypeScript, or Kotlin file, re-run on every edit and on editor focus change, via these detectors (see [docs/detectors](docs/detectors/README.md) for full detail on each):
 
 - [Cyclomatic complexity](docs/detectors/cyclomatic-complexity.md), too many independent execution paths.
 - [Cognitive complexity](docs/detectors/cognitive-complexity.md), too hard to read due to nesting.
@@ -36,14 +36,31 @@ The name is a deliberate analogy to thermodynamics: a function's "energy" is its
 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:
 
 ```bash
-npx energy-state-analyzer path/to/file.py   # or .fs / .fsx / .ts
+npx energy-state-analyzer path/to/file.py   # or .fs / .fsx / .ts / .kt
 ```
 
 See [docs/cli.md](docs/cli.md) for scanning a whole repo, aggregated markdown/JSON/human reports, and diffing a PR against a base branch.
 
 ## 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.
+The extension activates automatically when you open a Python, F#, TypeScript, or Kotlin 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.
+
+## Development
+
+Product and test sources are F#. Install the pinned .NET tools (Fable and Fantomas) and npm
+dependencies, then use the wrapped commands:
+
+```bash
+just setup
+just install
+just build
+just test
+```
+
+Fable emits JavaScript with `--lang javascript --noCache` into ignored `fable-out/`; webpack then
+creates `dist/extension.js` and `dist/cli.js`. `just lint` checks F# formatting, `just format`
+formats it, and `just analyze` runs the built F# CLI against the production F# source. Press `F5`
+for the Extension Development Host.
 
 ## Extension Settings
 
@@ -73,6 +90,5 @@ To exclude files/folders (e.g. test fixtures, generated code) from both the exte
 
 ## Known Issues
 
-- Nesting depth and parameter count thresholds are not yet configurable via VS Code settings, only cyclomatic complexity, cognitive complexity, the large-function coherence check, the match-opportunity branch count, and the magic-number/magic-string detectors are.
 - 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.
 - Several detectors have per-language gaps beyond the above, see the "Known limitations" section of the relevant [detector doc](docs/detectors/README.md).

package/action.yml

@@ -7,7 +7,7 @@ branding:
 
 # 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).
+# `git show` (see src/CliModes.fs's changedFilesFromGit/readAtRef).
 
 inputs:
   path:
@@ -51,7 +51,7 @@ runs:
   using: composite
   steps:
     - name: Setup Node
-      uses: actions/setup-node@v5
+      uses: actions/setup-node@v7
       with:
         node-version: 22
 
@@ -76,7 +76,7 @@ runs:
 
     - name: Comment on PR
       if: ${{ inputs.post-comment == 'true' && github.event_name == 'pull_request' }}
-      uses: marocchino/sticky-pull-request-comment@v2
+      uses: marocchino/sticky-pull-request-comment@v3
       with:
         header: ${{ inputs.comment-header }}
         path: ${{ steps.run.outputs.report-path }}