falsegreen-js 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,143 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-06-28
+
+### Added
+- `JS23` (high, J1): `expect.assertions(N)` with a numeric `N` higher than the unconditional,
+  reachable, non-nested `expect()` calls that can run. The guard can never be met, so the test
+  passes without ever exercising the count it claims. Fires only when `N` is a numeric literal
+  and the shortfall is provable: an `expect` in a loop, a branch, a `.then`/callback, or a
+  helper makes the count indeterminate and suppresses the finding. `expect.hasAssertions()`
+  carries no count and is skipped. This is the implemented sibling of the still-skipped JS16.
+- `JS24` (low, J4): a Cypress query chain (`cy.get`/`cy.find`/`cy.contains`) used as a statement
+  with no terminating `.should`/`.and` and no `expect` inside a `.then` callback. The query
+  produces a subject that is never asserted, the cy.* analogue of JS13. Action commands
+  (`click`/`type`/`visit`/...) do work rather than just query, so a chain ending in one stays
+  clean, as does a chain that ends in `.should`/`.and` or asserts in `.then`.
+- CLI `--enable <codes>` (and `--enable=...`): re-activates listed off or opt-in codes at their
+  catalog severity, flipping a default-off code on. It cannot raise a code above catalog
+  severity. `--disable` wins over `--enable`, so a code passed to both stays off.
+- `examples/` tree (#47): a worked sample for every emitted code, a BAD test the scanner flags
+  paired with a CLEAN look-alike one token away that it leaves alone. Files are grouped by
+  RiskGroup (`effectiveness`, `execution`, `nondeterminism`, `dependency`), with `cypress.cy.ts`
+  for the Cypress code and `diagnostics.test.ts` for the opt-in maintainability group. C16 keeps
+  a separate frozen-clock file because the fake-timer signal is file-wide. `vitest.config.ts`
+  excludes `examples/**` from collection, and `test/examples.test.ts` scans each file with
+  `analyze(parse(...))` to assert every code fires in its file, with a drift guard that fails if a
+  new default-on code lands without an example. The config-audit-only PL series scans Jest/Vitest
+  config rather than a test file, so it has no test-file example.
+
+### Changed
+- `JS8` now also catches the `jest.spyOn`/`vi.spyOn` form: a spy with a canned return
+  (`mockReturnValue`/`mockResolvedValue`/`mockImplementation`) whose spied target root is also an
+  `expect` subject. The test asserts the canned value, not real behaviour. Conservative
+  same-binding guard: spying a collaborator (a different object) stays clean, and asserting on
+  the spy handle itself (`expect(spy).toHaveBeenCalled()`) is not treated as the subject.
+- `JS3` gains a distinct detail when the snapshot is an empty inline baseline:
+  `toMatchInlineSnapshot()` with no argument, or an empty or whitespace-only string baseline,
+  passes by writing itself on the first run. A populated inline snapshot keeps the existing
+  detail; the snapshot-only detection logic is unchanged.
+
+### Docs
+- `CONTRIBUTING.md` documents the FP-boundary decisions that previously lived only in
+  source comments: the admission criteria for a new code (statically provable, FP-guarded,
+  ships with a CLEAN look-alike one token from the BAD, carries a catalog entry, clears the
+  panel and principal-reviewer gate) and the standing per-code rules for C44, C6, JS5, C16,
+  JS23, JS24, and JS8 (#51).
+
+## [0.4.0] - 2026-06-28
+
+### Fixed
+- C21 no longer false-positives on a `do { expect } while(c)`: a do/while body always runs at least
+  once, so its assertion is unconditional (#60).
+- C16 crypto match is anchored to a crypto root (`crypto.randomUUID`, `globalThis/window/self.crypto`,
+  or the bare node:crypto import), so a user method named `randomUUID()`/`getRandomValues()` is no
+  longer flagged (#61).
+- C20 and C21 no longer double-report on a dead-code-only assertion: an assertion already flagged
+  C20 (unreachable) is excluded from the C21 set, so C20 owns the line. C21 still fires when a live
+  conditional assertion remains (#62).
+
+### Added
+- `C16` nondeterminism now also flags `new Date()` (zero-arg, reads the system clock),
+  `crypto.randomUUID()`, and `crypto.getRandomValues()`. `new Date(<literal/expr>)` is a fixed
+  instant and stays clean, and the file-wide fake-timer suppression applies. Aliased/destructured
+  clock reads (`const now = Date.now; now()`) stay out: tracking them would trade a rare miss for
+  a frequent false positive on user `now()` helpers (#46).
+- `C48` (dark patch): a test that flips a known test-mode flag into test mode and then
+  asserts is exercising the product's test-only branch, not real behaviour. Detection-only;
+  v1 covers raw writes (`process.env.NODE_ENV = "test"`, `process.env.TESTING = "1"`,
+  `settings.TESTING = true`). `NODE_ENV` only counts as `"test"`; config values and product
+  feature flags are not flagged; a flag write with no assertion after it is setup, not a dark
+  patch. Parity with falsegreen (Python) `C48`, same id and J1/low (#39).
+
+### Tests
+- Lock the floating `expect(p).resolves`/`.rejects.<matcher>()` case for `JS5`: a non-awaited
+  promise matcher is already flagged through the oracle registry (the matcher builds a promise
+  that never settles before the test ends), and tests now pin that, including an exact-count
+  guard so a future change cannot double-report it. Awaited/returned forms stay clean (#43).
+- Characterization tests for the cfg reachability edge cases: for-in (C20 after / C21 inside),
+  labeled `break outer`, a switch case that falls through without escaping, an IIFE holding the
+  only assertion (no phantom C21), and `performance.now()` C16 (#63).
+
+### Changed
+- `C20` and `C21` now use a structured intra-test reachability walk (`src/cfg.ts`) instead of
+  a top-level-only scan. `C20` (dead code) catches an assertion after any non-falling-through
+  statement: a `return`/`throw`, `process.exit()`, a `break`/`continue`, an `if` whose both
+  arms terminate, a terminating block, or an exhaustive `switch` (every case plus a `default`
+  escapes). `C21` (no unconditional assertion) fires only when no assertion is on the guaranteed
+  spine; an assertion in an `if(true)` branch, a `finally`, or a `try` block now counts as
+  guaranteed, and an assertion only in a `catch` or a loop body is correctly flagged. The walk
+  stops at nested functions, so a `return` inside a `forEach`/IIFE callback no longer reads as
+  dead code. False-positive-averse: anything unmodeled is treated as reachable/guaranteed (#35).
+- README Status no longer pins a stale `0.1.0` literal; it points to STATUS.md for the current
+  version and coverage. Removed two boolean sub-clauses fully subsumed by their first disjunct
+  in `isTestBlock` and the JS6 suite guard (behavior-preserving) (#64, #65).
+
+### Fixed (earlier in the 0.4.0 cycle)
+- JS5 surfaces a floating promise observed only by a non-assignment binary op (||, &&, ===); only a real assignment with the call as RHS counts as observed.
+- JS7 timer control now consults lifecycle hooks that install/flush fake timers at both the enclosing-describe and source-file top level (#41).
+
+
+### Added
+- C44 (numeric tautology, high, J2): `expect(x.length).toBeGreaterThanOrEqual(0)`. A
+  `.length` is never negative and never NaN, so `>= 0` holds for every input and checks
+  nothing — the JS/TS mirror of the Python `len(x) >= 0`. The subject must be a direct
+  `.length` property access: a derived expression that only mentions `.length`
+  (`a.length - b.length`) can be negative and is not flagged, and a bound that can still
+  fail (`>= 1`, `> 0`) is a real check. Finiteness/NaN guards (`toBeLessThan(Infinity)`,
+  `toBeGreaterThan(-Infinity)`) are deliberately not flagged: they are false for `NaN`, so
+  they catch divide-by-zero and invalid-number bugs.
+- Output-format parity with the Python scanner: `--format text|json|sarif|junit`
+  (default `text`; `--json` stays as an alias for `--format json`). SARIF 2.1.0
+  emits one rule per code and one result per finding, maps high to `error`, low to
+  `warning`, off to `note`, and tags each result with its judgment, `risk:<group>`,
+  and `level:<conf>`. JUnit XML turns high findings into `<failure>` and the rest
+  into `<skipped>`. `--output` writes any of the four formats (sarif -> `.sarif`,
+  junit -> `.xml`).
+- Baseline ratchet: `--baseline [PATH]` suppresses findings already recorded (so CI
+  fails only on net-new ones), and `--write-baseline [PATH]` records the current
+  findings and exits 0. Both default to `.falsegreen-baseline.json`. A finding's
+  identity is a content fingerprint (`sha1` of relative path + code + detail, no
+  line number), stable across unrelated line shifts. The fingerprint omits the
+  source snippet the Python scanner folds in, since the js `Finding` carries none.
+- Risk-group taxonomy: every code now carries an explicit conceptual failure mode
+  (`effectiveness`, `execution`, `nondeterminism`, `dependency`, `structure`,
+  `diagnostic`), read from a closed per-code table (`riskGroupOf`) rather than the
+  code prefix. An unknown code is rejected instead of defaulted. The JSON report
+  gains a `riskGroup` field; the legacy `group` field stays for transition compatibility.
+- A code's metadata is split into independent axes: `group` (taxonomy), `severity`
+  (`high`/`low`), `defaultOn` (whether the default scan emits it), and `judgment`
+  (J1-J6). The taxonomy no longer depends on whether a finding blocks.
+- Oracle registry (`oracles.ts`): the assertion-API vocabulary is one versioned
+  table, each family classified by how its failure reaches the runner (`sync-fail`,
+  `promise`, `runner-registered`, `value-only`). The JSON report records the
+  `oracleRegistryVersion` that classified it.
+
+### Fixed
+- `--version` and the JSON report's `version` field read from `package.json` at
+  runtime; they were pinned to a stale `0.2.0` literal while the package was `0.3.0`.
+
 ## [0.3.0] - 2026-06-23
 
 ### Added
@@ -84,7 +221,9 @@ All notable changes to this project are documented here. The format is based on
 - pre-commit hook (`.pre-commit-hooks.yaml`), CI matrix (Node 18/20/22), and an npm
   trusted-publishing release workflow.
 
-[Unreleased]: https://github.com/vinicq/falsegreen-js/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/vinicq/falsegreen-js/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/vinicq/falsegreen-js/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/vinicq/falsegreen-js/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/vinicq/falsegreen-js/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/vinicq/falsegreen-js/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/vinicq/falsegreen-js/releases/tag/v0.1.0

package/README.md

@@ -1,5 +1,13 @@
 # falsegreen-js
 
+[![CI](https://github.com/vinicq/falsegreen-js/actions/workflows/ci.yml/badge.svg)](https://github.com/vinicq/falsegreen-js/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/falsegreen-js.svg)](https://www.npmjs.com/package/falsegreen-js)
+[![Node](https://img.shields.io/node/v/falsegreen-js.svg)](https://www.npmjs.com/package/falsegreen-js)
+[![Downloads](https://img.shields.io/npm/dm/falsegreen-js.svg)](https://www.npmjs.com/package/falsegreen-js)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://vinicq.github.io/falsegreen-docs/)
+
 Find JavaScript/TypeScript unit tests that give false positives: green tests that
 protect nothing, and tests that pass while asserting the wrong thing. Deterministic
 AST scan, no code execution. Sibling of [`falsegreen`](https://github.com/vinicq/falsegreen)
@@ -7,6 +15,15 @@ AST scan, no code execution. Sibling of [`falsegreen`](https://github.com/vinicq
 
 Covers `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`, `.mts`, `.cts`.
 
+**The falsegreen family** (install the one for your stack):
+
+| Tool | Stack | Install | Package |
+|---|---|---|---|
+| [falsegreen](https://github.com/vinicq/falsegreen) | Python / pytest | `pip install falsegreen` | [PyPI](https://pypi.org/project/falsegreen/) |
+| **falsegreen-js** | JS / TS | `npm i -D falsegreen-js` (`npx falsegreen-js`) | [npm](https://www.npmjs.com/package/falsegreen-js) |
+| [robotframework-falsegreen](https://github.com/vinicq/robotframework-falsegreen) | Robot Framework | `pip install robotframework-falsegreen` | [PyPI](https://pypi.org/project/robotframework-falsegreen/) |
+| [falsegreen-skill](https://github.com/vinicq/falsegreen-skill) | semantic LLM pass | `npx falsegreen-skill analyze <path>` | [npm](https://www.npmjs.com/package/falsegreen-skill) |
+
 ## Why
 
 A test can be green and still protect nothing: an empty body, an assertion that is
@@ -27,15 +44,36 @@ npm install -D falsegreen-js
 npx falsegreen-js                 # scan cwd
 npx falsegreen-js src test        # scan paths
 npx falsegreen-js --staged        # only test files staged in git (pre-commit)
-npx falsegreen-js --json          # machine-readable output
+npx falsegreen-js --json          # machine-readable output (alias for --format json)
+npx falsegreen-js --format sarif  # SARIF 2.1.0 for GitHub code scanning
+npx falsegreen-js --format junit  # JUnit XML for CI test reporters
 npx falsegreen-js --output report.json   # write to a file
 npx falsegreen-js --output .falsegreen/  # write report.<ext> into a directory
 npx falsegreen-js --config-audit  # audit Jest/Vitest config (project-layer PL codes)
 npx falsegreen-js --disable C7,JS3
+npx falsegreen-js --enable D8,M2   # re-activate off/opt-in codes at catalog severity
 ```
 
 Each finding is reported with its pyramid level (unit / integration / e2e, read from the file's imports) and a one-line fix hint, and the summary breaks the findings down by level and lists the most common fixes. `--output` takes a file or a directory: an extension-less or trailing-slash path (e.g. `.falsegreen/`) receives `report.<ext>` for the chosen format. Reports are run artifacts; keep the output directory gitignored.
 
+### Output formats
+
+`--format text|json|sarif|junit` (default `text`; `--json` stays as an alias for `--format json`). These match the [Python sibling](https://github.com/vinicq/falsegreen) byte-for-concept, so a pipeline can swap one scanner for the other.
+
+- **`sarif`**: SARIF 2.1.0. One rule per code present, one result per finding, with `error` for high-severity findings, `warning` for low, and `note` for off. Result tags carry the judgment (J1-J6), the risk group (`risk:effectiveness`...), and the level (`level:high`). Upload it to GitHub code scanning to see findings inline on the PR.
+- **`junit`**: JUnit XML. High-severity findings become `<failure>`, everything else `<skipped>`, so a CI test reporter surfaces them as a failing suite.
+
+### Baseline (ratchet)
+
+Adopting the scanner on a large codebase without fixing every legacy finding at once:
+
+```bash
+npx falsegreen-js --write-baseline   # record current findings to .falsegreen-baseline.json, exit 0
+npx falsegreen-js --baseline         # report and fail only on findings not in the baseline
+```
+
+`--baseline [PATH]` and `--write-baseline [PATH]` default to `.falsegreen-baseline.json`. A finding's identity is a content fingerprint (`sha1` of relative path + code + detail, no line number), so it survives unrelated line shifts in the file. Commit the baseline, then let CI block only on net-new findings. (The fingerprint omits the source snippet the Python scanner folds in, since the js scanner does not carry one; two findings with the same code and detail in one file share an id.)
+
 `--config-audit` is a separate mode: instead of scanning test files, it reads the Jest/Vitest config (`package.json` `jest` field, `jest.config.*`, `vitest.config.*`) and reports the project-layer ways a suite stays green by configuration: `PL10` (`passWithNoTests` passes an empty or filtered-to-nothing run), `PL7` (no `coverageThreshold` / `coverage.thresholds`), `PL8` (`bail` stops the run early). The per-file scan cannot see config.
 
 For the layer no static scan reaches (does a green test fail when the code is wrong?), run a **mutation tester** like [Stryker](https://stryker-mutator.io/). falsegreen-js is the cheap pre-filter on every commit; mutation testing is the deeper audit.
@@ -95,7 +133,8 @@ line up in the research. `JS*` codes are ecosystem-specific.
 | C5  | high | always-true check (`expect(true).toBe(true)`, `assert(1)`) |
 | C6  | low  | weak check — only verifies something came back (`toBeTruthy`/`toBeDefined`, `length > 0`) |
 | C7  | high | compares a thing to itself (`expect(x).toBe(x)`) |
-| C20 | high | assertion in dead code after a `return`/`throw` — it never runs |
+| C44 | high | numeric tautology — a length compared so the result is always true (`x.length >= 0`) |
+| C20 | high | assertion in unreachable code (after a `return`/`throw`/`process.exit`, a `break`, a both-arms-terminating `if`, or an exhaustive `switch`) — it never runs |
 | C23 | low  | reads a real file at a literal path, or a hard-coded URL (mystery guest) |
 | C8  | low  | exact equality on a float (use `toBeCloseTo`) |
 | C9  | low  | `toThrow()` with no error type or message — accepts any error |
@@ -103,6 +142,7 @@ line up in the research. `JS*` codes are ecosystem-specific.
 | C18 | low  | compares `String(x)` / `JSON.stringify(x)` / `` `${x}` `` to a literal (formatting, not value) |
 | C21 | low  | every assertion is conditional — none runs unconditionally |
 | C37 | low  | duplicate case in `it.each`/`test.each` — the same scenario runs twice |
+| C48 | low  | dark patch — the test flips a test-mode flag (`process.env.NODE_ENV = "test"`, `process.env.TESTING`, a `TESTING` flag) then asserts, exercising the product's test-only branch |
 | CC  | low  | commented-out assertion |
 | JS1 | high | focused test (`it.only` / `fit`) silently skips the rest of the suite |
 | JS2 | high | `expect(x)` with no matcher — the assertion never runs |
@@ -120,13 +160,15 @@ line up in the research. `JS*` codes are ecosystem-specific.
 | JS18 | low | test takes a `done` callback instead of async/await — a mistimed `done` passes early |
 | JS21 | high | matcher referenced but never called (`expect(x).toBe` with no `()`) — the assertion never runs |
 | JS22 | high | empty `it.each`/`test.each` table — generated with zero cases, never runs |
+| JS23 | high | `expect.assertions(N)` with fewer unconditional `expect()` calls than N — the guard can never be met |
+| JS24 | low  | Cypress query (`cy.get`/`cy.find`/`cy.contains`) as a loose statement with no terminating `.should`/`.and` and no `expect` in `.then` — its result is never asserted |
 
 Each code carries a judgment tag (J1-J6) shared with the
 [falsegreen-skill](https://github.com/vinicq/falsegreen-skill) semantic framework.
 
 ### Opt-in: maintainability group (default off)
 
-These are **not** false-green — the test still protects something — so they are off by
+These are **not** false-green - the test still protects something - so they are off by
 default. Enable them with `--diagnostics`, or per code via config `severity`. They are a
 "plus" for test-code health, mirroring falsegreen's diagnostic/coupling groups.
 
@@ -149,18 +191,32 @@ npx falsegreen-js --diagnostics      # include D*/M* as warnings
 Some catalog codes were reviewed and left out, on purpose:
 
 - **JS19** (`toBe` on an object/array literal): `expect(x).toBe({...})` compares by reference,
-  so it always fails. That is a loud red test, the opposite of false-green, and out of scope.
+  so it always fails. That is the false-red axis (a test that always fails), the opposite of
+  what this scanner looks for, and out of scope on principle.
 - **JS20** (a Promise compared without `resolves`/`rejects`): telling that a value is a
-  Promise needs type information the parser does not have, so it would be too noisy.
+  Promise needs type information the AST does not carry, so it would be too noisy.
 - **JS12** (a floating promise whose `expect` is never returned): already covered by JS7.
-- **JS16** (`async` test with no `expect.assertions(n)`): the absence of a guard is not a
-  smell on its own; flagging it would fire on most async tests.
+- **JS16** (`async` test with no `expect.assertions(n)`): the *absence* of a guard is not a
+  smell on its own; flagging it would fire on most async tests. The implemented sibling is
+  `JS23`, which fires on a present-but-unsatisfiable guard: `expect.assertions(N)` with a
+  numeric `N` higher than the unconditional `expect()` calls that can run, so the count can
+  never be met.
+- **JS14** (a giant inline snapshot): a readability and review-noise concern, not a
+  false-green one. The snapshot still protects, so it belongs to the diagnostic group and is
+  better served by `eslint-plugin-jest` (`no-large-snapshots`) as an opt-in lint rule.
 - **JS10** (any conditional in a test body): handled by `eslint-plugin-jest`
   (`no-conditional-in-test`); JS9 and C21 already cover the false-green subset.
+- **C1** (an assertion under an `if`/`for` that may not run): redundant once C21 and JS9
+  exist, and high-FP on its own. C21 already fires the actual false-green case, where
+  *every* assertion is conditional and the test can pass with nothing checked. A test that
+  mixes a conditional assertion with an unconditional one is not false-green: the
+  unconditional assertion still protects. JS9 covers the dead-branch form (`if(false)`).
+  Flagging every conditional assertion (C1's full scope) is the linter concern JS10 already
+  names (`no-conditional-in-test`), so C1 would add noise without a new false-green signal.
 
 ### What carries over from falsegreen, what does not
 
-Ported (same concept): C2, C2b, C5, C7, C8, C16, CC.
+Ported (same concept): C2, C2b, C5, C7, C8, C16, C44, C48, CC.
 
 Python-only, not applicable to JS/TS: pytest collection rules (C4 family), `pytest.raises`
 breadth (C9/C19/C27/C28), fixtures and `os.environ`/global-state codes (C23/C24/C29),
@@ -183,7 +239,7 @@ Optional. `falsegreen.json`, `.falsegreenrc.json`, or a `"falsegreen"` key in
 }
 ```
 
-Precedence: CLI `--disable` > config `disable`/`severity` > catalog default.
+Precedence: CLI `--disable` > CLI `--enable` > config `disable`/`severity` > catalog default. `--enable <codes>` re-activates listed off or opt-in codes at their catalog severity (it flips a default-off code on; it cannot raise a code above catalog). A code passed to both `--enable` and `--disable` stays off — `--disable` wins.
 
 ## Scope and honesty
 
@@ -193,20 +249,23 @@ test re-implements the production logic. Those are semantic and belong to the
 `falsegreen-skill` LLM pass. Precision over recall: a softened heuristic that misses a
 case is preferred to one that flags correct code.
 
+Measured against the [Open Catalog of Test Smells](https://test-smell-catalog.readthedocs.io/) (517 documented smells), only the false-green slice is in scope. What stays out, on purpose: **brittleness / false-red** (sensitive equality, brittle assertions - the opposite axis), **hygiene / maintainability** (assertion roulette, magic numbers, long tests - linter territory, a few surfaced as opt-in diagnostics), and **slow, design, naming, duplication, runtime/culture** (none about whether the test protects). The boundary is deliberate: where a smell has a statically provable false-green form, that form is a code here - uncontrolled `Date.now`/`Math.random` is `C16`, a hard-coded path or URL is `C23`, an assertion that may never run is `C21`/`C20`, and JS-specific forms (focused tests, missing matchers) are the `JS*` codes. See [CREDITS.md](CREDITS.md) for the full cross-walk.
+
 ## References
 
 The catalog is grounded in the test-smell literature. Direct influences: the
 rotten-green-test work that names this whole family (Delplanque et al., ICSE 2019),
 the founding test-smell refactoring catalog (van Deursen et al., XP 2001), the
-JS/TS empirical studies (Jorge, UFCG 2023; Silva, PUC Minas 2022 — the academic
+JS/TS empirical studies (Jorge, UFCG 2023; Silva, PUC Minas 2022 - the academic
 precedent for the focused-test and snapshot codes; Oliveira et al., SBES 2024/2025),
 and the detection-tool baselines (tsDetect, Peruma et al., 2020). Full list and the
 code-to-source mapping in [CREDITS.md](CREDITS.md).
 
 ## Status
 
-`0.1.0`, early. The rule set is a deterministic core; the full JS/TS smell catalog is
-tracked as research in the private audit hub. Issues and PRs welcome.
+The rule set is a deterministic core; the full JS/TS smell catalog is tracked as
+research in the private audit hub. See [STATUS.md](STATUS.md) for the current version
+and rule coverage. Issues and PRs welcome.
 
 ## License
 
@@ -227,7 +286,7 @@ Thanks to the people who keep false-green tests out of real suites ([emoji key](
   <tbody>
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://vinicq.github.io/md-bridge/"><img src="https://avatars.githubusercontent.com/u/78210890?v=4?s=100" width="100px;" alt="Vinicius Queiroz"/><br /><sub><b>Vinicius Queiroz</b></sub></a><br /><a href="https://github.com/vinicq/falsegreen-js/commits?author=vinicq" title="Code">💻</a> <a href="https://github.com/vinicq/falsegreen-js/commits?author=vinicq" title="Documentation">📖</a> <a href="#ideas-vinicq" title="Ideas, Planning, & Feedback">🤔</a> <a href="#maintenance-vinicq" title="Maintenance">🚧</a> <a href="#infra-vinicq" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="https://github.com/vinicq/falsegreen-js/commits?author=vinicq" title="Tests">⚠️</a> <a href="#research-vinicq" title="Research">🔬</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/homesellerq-coder"><img src="https://avatars.githubusercontent.com/u/294912019?v=4?s=100" width="100px;" alt="Home Seller"/><br /><sub><b>Home Seller</b></sub></a><br /><a href="https://github.com/vinicq/falsegreen-js/commits?author=homesellerq-coder" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/homesellerq-coder"><img src="https://avatars.githubusercontent.com/u/294912019?v=4?s=100" width="100px;" alt="Home Seller"/><br /><sub><b>Home Seller</b></sub></a><br /><a href="https://github.com/vinicq/falsegreen-js/commits?author=homesellerq-coder" title="Code">💻</a> <a href="https://github.com/vinicq/falsegreen-js/commits?author=homesellerq-coder" title="Documentation">📖</a> <a href="https://github.com/vinicq/falsegreen-js/commits?author=homesellerq-coder" title="Tests">⚠️</a> <a href="#infra-homesellerq-coder" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a></td>
     </tr>
   </tbody>
 </table>

package/dist/cases.d.ts

@@ -3,14 +3,42 @@
  * the same concept (shared C-codes, so cross-language paper comparison lines up),
  * plus JS/TS-specific codes (JS-prefix) for ecosystem-only patterns.
  *
- * confidence: "high" => blocks (exit 20); "low" => warns (exit 10); "off" => silent.
- * judgment: which semantic question (J1-J6, see falsegreen-skill) the code belongs to.
+ * Each code carries four independent axes (none derived from another or from the
+ * code prefix):
+ *   group       conceptual failure mode (RiskGroup, closed taxonomy).
+ *   severity    how serious the finding is when it fires ("high" | "low").
+ *   defaultOn   whether the default scan emits it (false for the opt-in
+ *               diagnostic group, surfaced only via --diagnostics).
+ *   judgment    which semantic question (J1-J6, see falsegreen-skill) it answers.
+ *
+ * The effective "confidence" used downstream (high/low/off) is derived from
+ * severity + defaultOn by baseConfidence(); the exit code is derived from the
+ * severity of the findings that are actually emitted. Keeping the axes apart is
+ * the point: a finding's taxonomy must not depend on whether it blocks.
  */
 export type Confidence = "high" | "low" | "off";
+export type Severity = "high" | "low";
+/**
+ * Conceptual failure mode — a closed taxonomy condensing the F1-F8 families to
+ * six axes. Driven by the per-code table below (riskGroupOf), never by the code
+ * prefix, and never defaulted: an unknown code is an error, not a guess.
+ *
+ *   effectiveness   no oracle, a trivial oracle, or the wrong oracle (F1/F3/F4).
+ *   execution       the check exists but does not run, or the test vanishes from
+ *                   the count (F2/F5).
+ *   nondeterminism  passes or fails by luck — time, randomness, timers (F6).
+ *   dependency      real I/O or a stand-in for the unit under test: mystery
+ *                   guest, self-mock (isolation, J3/J6).
+ *   structure       size/readability; the test still protects (F8 maintainability).
+ *   diagnostic      opt-in health signal, off by default.
+ */
+export type RiskGroup = "effectiveness" | "execution" | "nondeterminism" | "dependency" | "structure" | "diagnostic";
 export declare const JUDGMENTS: Record<string, string>;
 export interface CaseDef {
     title: string;
-    confidence: Confidence;
+    group: RiskGroup;
+    severity: Severity;
+    defaultOn: boolean;
     judgment: keyof typeof JUDGMENTS;
 }
 export declare const CASES: Record<string, CaseDef>;
@@ -19,6 +47,26 @@ export declare const DIAGNOSTIC_THRESHOLDS: {
     assertionRoulette: number;
     longTest: number;
 };
+/**
+ * Effective default state of a code as a single value: its severity when the
+ * default scan emits it, or "off" when it is opt-in. Derives the legacy
+ * three-valued "confidence" from the independent severity + defaultOn axes, so
+ * the rest of the pipeline (makeFinding, effectiveConf, exit code) keeps working
+ * unchanged while the taxonomy stays separate from the blocking decision.
+ */
+export declare function baseConfidence(code: string): Confidence;
+/**
+ * Primary taxonomy: the conceptual failure mode, read from the closed per-code
+ * table. Rejects an unknown code instead of defaulting, so a typo or a code that
+ * was added to the rules but never classified fails loudly.
+ */
+export declare function riskGroupOf(code: string): RiskGroup;
+/**
+ * Legacy product grouping (false-positive / diagnostic / coupling / project),
+ * kept only as a transition-compat field in the JSON report. New consumers
+ * should read `riskGroup` (riskGroupOf). Prefix-based by design: it mirrors the
+ * pre-0.3 output exactly so downstream filters do not break across the upgrade.
+ */
 export declare function groupOf(code: string): "false-positive" | "diagnostic" | "coupling" | "project";
 /** Test-pyramid level, detected from a file's import roots (see level.ts).
  * `project` is the config-audit layer (--config-audit), not a file level. */