falsegreen-js 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,98 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [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 +176,8 @@ 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.4.0...HEAD
+[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,8 @@ AST scan, no code execution. Sibling of [`falsegreen`](https://github.com/vinicq
 
 Covers `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`, `.mts`, `.cts`.
 
+**The falsegreen family:** [falsegreen](https://github.com/vinicq/falsegreen) (Python/pytest) · **falsegreen-js** (JS/TS) · [robotframework-falsegreen](https://github.com/vinicq/robotframework-falsegreen) (Robot Framework) · [falsegreen-skill](https://github.com/vinicq/falsegreen-skill) (semantic LLM pass).
+
 ## Why
 
 A test can be green and still protect nothing: an empty body, an assertion that is
@@ -27,7 +37,9 @@ 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)
@@ -36,6 +48,24 @@ npx falsegreen-js --disable C7,JS3
 
 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 +125,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 +134,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 |
@@ -126,7 +158,7 @@ Each code carries a judgment tag (J1-J6) shared with the
 
 ### 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 +181,29 @@ 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.
+- **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),
@@ -193,20 +236,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 +273,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. */

package/dist/cases.js

@@ -3,8 +3,18 @@
  * 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 const JUDGMENTS = {
     J1: "does the assertion actually run?",
@@ -16,56 +26,88 @@ export const JUDGMENTS = {
 };
 export const CASES = {
     // --- shared concept with falsegreen (same code id) -----------------------
-    C2: { title: "test with no check at all (empty body)", confidence: "high", judgment: "J1" },
-    C2b: { title: "test calls things but checks nothing", confidence: "low", judgment: "J1" },
-    C5: { title: "always-true check (expect(true).toBe(true), assert(1))", confidence: "high", judgment: "J2" },
-    C6: { title: "weak check — only verifies something came back (toBeTruthy/toBeDefined, length > 0)", confidence: "low", judgment: "J4" },
-    C7: { title: "compares a thing to itself (expect(x).toBe(x))", confidence: "high", judgment: "J2" },
-    C20: { title: "assertion in dead code after a return/throw — it never runs", confidence: "high", judgment: "J1" },
-    C23: { title: "reads a real file at a literal path or hits a hard-coded URL (mystery guest)", confidence: "low", judgment: "J6" },
-    C8: { title: "exact equality on a float (fails on rounding, not bugs)", confidence: "low", judgment: "J4" },
-    C16: { title: "result depends on time, randomness or a fixed timer", confidence: "low", judgment: "J1" },
-    C18: { title: "compares String()/JSON.stringify()/`${x}` of a value to a literal (checks formatting, not the value)", confidence: "low", judgment: "J2" },
-    C21: { title: "every assertion is conditional — none runs unconditionally", confidence: "low", judgment: "J1" },
-    C9: { title: "expect(...).toThrow() with no error type or message — accepts any error", confidence: "low", judgment: "J4" },
-    C37: { title: "duplicate case in it.each/test.each — the same scenario runs twice", confidence: "low", judgment: "J4" },
-    CC: { title: "commented-out assertion (check switched off)", confidence: "low", judgment: "J1" },
+    C2: { title: "test with no check at all (empty body)", group: "effectiveness", severity: "high", defaultOn: true, judgment: "J1" },
+    C2b: { title: "test calls things but checks nothing", group: "effectiveness", severity: "low", defaultOn: true, judgment: "J1" },
+    C5: { title: "always-true check (expect(true).toBe(true), assert(1))", group: "effectiveness", severity: "high", defaultOn: true, judgment: "J2" },
+    C6: { title: "weak check — only verifies something came back (toBeTruthy/toBeDefined, length > 0)", group: "effectiveness", severity: "low", defaultOn: true, judgment: "J4" },
+    C7: { title: "compares a thing to itself (expect(x).toBe(x))", group: "effectiveness", severity: "high", defaultOn: true, judgment: "J2" },
+    C44: { title: "numeric tautology — a length compared so the result is always true (length >= 0)", group: "effectiveness", severity: "high", defaultOn: true, judgment: "J2" },
+    C20: { title: "assertion in dead code after a return/throw — it never runs", group: "execution", severity: "high", defaultOn: true, judgment: "J1" },
+    C23: { title: "reads a real file at a literal path or hits a hard-coded URL (mystery guest)", group: "dependency", severity: "low", defaultOn: true, judgment: "J6" },
+    C8: { title: "exact equality on a float (fails on rounding, not bugs)", group: "effectiveness", severity: "low", defaultOn: true, judgment: "J4" },
+    C16: { title: "result depends on time, randomness or a fixed timer", group: "nondeterminism", severity: "low", defaultOn: true, judgment: "J1" },
+    C18: { title: "compares String()/JSON.stringify()/`${x}` of a value to a literal (checks formatting, not the value)", group: "effectiveness", severity: "low", defaultOn: true, judgment: "J2" },
+    C21: { title: "every assertion is conditional — none runs unconditionally", group: "execution", severity: "low", defaultOn: true, judgment: "J1" },
+    C9: { title: "expect(...).toThrow() with no error type or message — accepts any error", group: "effectiveness", severity: "low", defaultOn: true, judgment: "J4" },
+    C37: { title: "duplicate case in it.each/test.each — the same scenario runs twice", group: "effectiveness", severity: "low", defaultOn: true, judgment: "J4" },
+    CC: { title: "commented-out assertion (check switched off)", group: "execution", severity: "low", defaultOn: true, judgment: "J1" },
+    C48: { title: "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", group: "execution", severity: "low", defaultOn: true, judgment: "J1" },
     // --- JS/TS ecosystem-specific --------------------------------------------
-    JS1: { title: "focused test (it.only / fit / describe.only) silently skips the rest of the suite", confidence: "high", judgment: "J1" },
-    JS2: { title: "expect(x) with no matcher — the assertion is never executed", confidence: "high", judgment: "J1" },
-    JS3: { title: "snapshot is the only assertion (toMatchSnapshot generated from the output itself)", confidence: "low", judgment: "J2" },
-    JS4: { title: "skipped test (it.skip / xit / xdescribe / it.todo) never runs", confidence: "low", judgment: "J1" },
-    JS5: { title: "async query/event not awaited (findBy* / waitFor / user-event) — the assertion may never settle", confidence: "low", judgment: "J1" },
-    JS6: { title: "empty describe/suite block — the suite reports green but runs nothing", confidence: "high", judgment: "J1" },
-    JS7: { title: "assertion inside a non-awaited setTimeout/setInterval/then callback — it may run after the test ends", confidence: "low", judgment: "J1" },
-    JS8: { title: "mocks the unit under test (jest.mock/vi.mock of an imported module asserted directly) — tests the mock, not the code", confidence: "low", judgment: "J3" },
-    JS9: { title: "assertion in a dead branch (if(false) / if(true){}else) — it never runs", confidence: "high", judgment: "J1" },
-    JS11: { title: "try/catch swallows the assertion — a failing expect is caught and the test stays green", confidence: "low", judgment: "J1" },
-    JS13: { title: "query (getBy*/queryBy*/wrapper.find) as a loose statement — its result is never asserted", confidence: "low", judgment: "J4" },
-    JS15: { title: "inappropriate assertion — the comparison is wrapped in a boolean (expect(a===b).toBe(true)), so the failure message is blind", confidence: "low", judgment: "J4" },
-    JS17: { title: "commented-out test block (// it(...) / // test(...)) — a disabled test that no longer runs", confidence: "low", judgment: "J1" },
-    JS18: { title: "test takes a done callback instead of async/await — a done called too early (or in a floating promise) passes before the assertions run", confidence: "low", judgment: "J1" },
-    JS21: { title: "matcher referenced but never called (expect(x).toBe with no ()) — the assertion never executes", confidence: "high", judgment: "J1" },
-    JS22: { title: "empty it.each/test.each table — the test is generated with zero cases and never runs", confidence: "high", judgment: "J1" },
+    JS1: { title: "focused test (it.only / fit / describe.only) silently skips the rest of the suite", group: "execution", severity: "high", defaultOn: true, judgment: "J1" },
+    JS2: { title: "expect(x) with no matcher — the assertion is never executed", group: "execution", severity: "high", defaultOn: true, judgment: "J1" },
+    JS3: { title: "snapshot is the only assertion (toMatchSnapshot generated from the output itself)", group: "effectiveness", severity: "low", defaultOn: true, judgment: "J2" },
+    JS4: { title: "skipped test (it.skip / xit / xdescribe / it.todo) never runs", group: "execution", severity: "low", defaultOn: true, judgment: "J1" },
+    JS5: { title: "async query/event not awaited (findBy* / waitFor / user-event) — the assertion may never settle", group: "execution", severity: "low", defaultOn: true, judgment: "J1" },
+    JS6: { title: "empty describe/suite block — the suite reports green but runs nothing", group: "execution", severity: "high", defaultOn: true, judgment: "J1" },
+    JS7: { title: "assertion inside a non-awaited setTimeout/setInterval/then callback — it may run after the test ends", group: "execution", severity: "low", defaultOn: true, judgment: "J1" },
+    JS8: { title: "mocks the unit under test (jest.mock/vi.mock of an imported module asserted directly) — tests the mock, not the code", group: "dependency", severity: "low", defaultOn: true, judgment: "J3" },
+    JS9: { title: "assertion in a dead branch (if(false) / if(true){}else) — it never runs", group: "execution", severity: "high", defaultOn: true, judgment: "J1" },
+    JS11: { title: "try/catch swallows the assertion — a failing expect is caught and the test stays green", group: "execution", severity: "low", defaultOn: true, judgment: "J1" },
+    JS13: { title: "query (getBy*/queryBy*/wrapper.find) as a loose statement — its result is never asserted", group: "effectiveness", severity: "low", defaultOn: true, judgment: "J4" },
+    JS15: { title: "inappropriate assertion — the comparison is wrapped in a boolean (expect(a===b).toBe(true)), so the failure message is blind", group: "effectiveness", severity: "low", defaultOn: true, judgment: "J4" },
+    JS17: { title: "commented-out test block (// it(...) / // test(...)) — a disabled test that no longer runs", group: "execution", severity: "low", defaultOn: true, judgment: "J1" },
+    JS18: { title: "test takes a done callback instead of async/await — a done called too early (or in a floating promise) passes before the assertions run", group: "execution", severity: "low", defaultOn: true, judgment: "J1" },
+    JS21: { title: "matcher referenced but never called (expect(x).toBe with no ()) — the assertion never executes", group: "execution", severity: "high", defaultOn: true, judgment: "J1" },
+    JS22: { title: "empty it.each/test.each table — the test is generated with zero cases and never runs", group: "execution", severity: "high", defaultOn: true, judgment: "J1" },
     // --- diagnostic group (maintainability; default off, opt-in via --diagnostics
     // or config severity). These are NOT false-green: the test still protects. They
     // are a "plus" for test-code health, mirroring falsegreen's D/M group. -------
-    D1: { title: "assertion roulette — many assertions in one test; a failure does not say which", confidence: "off", judgment: "J4" },
-    D3: { title: "duplicate assert — the same assertion appears more than once in a test", confidence: "off", judgment: "J4" },
-    D4: { title: "it.each/test.each without titled cases — a failing case is identified only by its index", confidence: "off", judgment: "J4" },
-    D6: { title: "console.* in a test body — a debug artifact that bypasses the oracle", confidence: "off", judgment: "J4" },
-    D7: { title: "anonymous test — empty or missing description", confidence: "off", judgment: "J4" },
-    D8: { title: "magic number in an assertion — a bare numeric literal instead of a named constant", confidence: "off", judgment: "J4" },
-    M2: { title: "test body exceeds the line-count threshold — hard to read and maintain", confidence: "off", judgment: "J5" },
+    D1: { title: "assertion roulette — many assertions in one test; a failure does not say which", group: "diagnostic", severity: "low", defaultOn: false, judgment: "J4" },
+    D3: { title: "duplicate assert — the same assertion appears more than once in a test", group: "diagnostic", severity: "low", defaultOn: false, judgment: "J4" },
+    D4: { title: "it.each/test.each without titled cases — a failing case is identified only by its index", group: "diagnostic", severity: "low", defaultOn: false, judgment: "J4" },
+    D6: { title: "console.* in a test body — a debug artifact that bypasses the oracle", group: "diagnostic", severity: "low", defaultOn: false, judgment: "J4" },
+    D7: { title: "anonymous test — empty or missing description", group: "diagnostic", severity: "low", defaultOn: false, judgment: "J4" },
+    D8: { title: "magic number in an assertion — a bare numeric literal instead of a named constant", group: "diagnostic", severity: "low", defaultOn: false, judgment: "J4" },
+    M2: { title: "test body exceeds the line-count threshold — hard to read and maintain", group: "structure", severity: "low", defaultOn: false, judgment: "J5" },
     // --- project layer (config-audit only; emitted by --config-audit, never by
     // the per-file scan). The suite goes green by configuration, not by a smell
     // inside any one test file. ------------------------------------------------
-    PL7: { title: "no coverage gate (coverageThreshold / coverage.thresholds) - coverage can fall to zero and the suite still passes", confidence: "low", judgment: "J5" },
-    PL8: { title: "bail stops the run early (bail) - the reported test count is incomplete", confidence: "low", judgment: "J5" },
-    PL10: { title: "passWithNoTests lets an empty or fully-filtered suite report green", confidence: "low", judgment: "J1" },
+    PL7: { title: "no coverage gate (coverageThreshold / coverage.thresholds) - coverage can fall to zero and the suite still passes", group: "effectiveness", severity: "low", defaultOn: true, judgment: "J5" },
+    PL8: { title: "bail stops the run early (bail) - the reported test count is incomplete", group: "execution", severity: "low", defaultOn: true, judgment: "J5" },
+    PL10: { title: "passWithNoTests lets an empty or fully-filtered suite report green", group: "execution", severity: "low", defaultOn: true, judgment: "J1" },
 };
 /** Default thresholds for the diagnostic group (overridable later via config). */
 export const DIAGNOSTIC_THRESHOLDS = { assertionRoulette: 5, longTest: 50 };
+/**
+ * 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 function baseConfidence(code) {
+    const c = CASES[code];
+    if (!c)
+        throw new Error(`falsegreen-js: unknown code "${code}" — not in the case catalog`);
+    return c.defaultOn ? c.severity : "off";
+}
+/**
+ * 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 function riskGroupOf(code) {
+    const c = CASES[code];
+    if (!c)
+        throw new Error(`falsegreen-js: unknown code "${code}" — not in the case catalog`);
+    return c.group;
+}
+/**
+ * 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 function groupOf(code) {
     if (code.startsWith("PL"))
         return "project";
@@ -86,6 +128,7 @@ export const FIX_HINTS = {
     C5: "assert the real behaviour, not a constant or tautology",
     C6: "assert the actual value, not just that something came back",
     C7: "compare against an independent expected value, not the subject itself",
+    C44: "assert the actual length, not that it is at least zero (always true)",
     C20: "move the assertion before the return/throw so it runs",
     C23: "use a fixture or temp file instead of a real path or hard-coded URL",
     C8: "use toBeCloseTo() or a tolerance instead of exact float equality",
@@ -95,13 +138,14 @@ export const FIX_HINTS = {
     C9: "pass an error type or message to toThrow()",
     C37: "remove the duplicate it.each/test.each case",
     CC: "restore the commented-out assertion, or delete it",
+    C48: "assert the behaviour a real user hits; don't force the product's test-mode branch from the test",
     JS1: "remove .only (it.only/fit/describe.only) so the whole suite runs",
     JS2: "add a matcher (expect(x).toBe(...)) so the assertion runs",
     JS3: "add a real assertion; don't rely only on a self-generated snapshot",
     JS4: "remove .skip/xit/todo, or implement the test",
     JS5: "await the async query/event before asserting",
     JS6: "add tests to the describe block, or remove it",
-    JS7: "await the promise/timer, or assert synchronously",
+    JS7: "await the promise, or use/flush fake timers, or assert synchronously",
     JS8: "unmock the unit under test; mock only its collaborators",
     JS9: "remove the dead branch so the assertion runs",
     JS11: "let the assertion error propagate; don't catch it",

package/dist/cfg.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Intra-test structured reachability, backing C20 (dead code) and C21 (no
+ * unconditional assertion). JS test bodies are structured (no goto), so this is a
+ * recursive walk over the statement tree, not a full control-flow graph.
+ *
+ * Two questions, both FP-averse (a false positive is worse than a miss):
+ *   assertionsInDeadCode  - assertions at a position control can never reach.
+ *   hasUnconditionalAssertion - is at least one assertion guaranteed to run?
+ *
+ * The assertion predicate and literal-truthiness helper are passed in (they live in
+ * rules.ts) so this module imports nothing from there and there is no cycle.
+ */
+import ts from "typescript";
+type IsAssertion = (n: ts.Node) => boolean;
+type LitTruth = (e: ts.Expression | undefined) => boolean | null;
+/**
+ * Assertions sitting at a position control can never reach (C20). Walk each
+ * statement list keeping `reachable` (true at the head); once a statement does not
+ * fall through, the rest of the list is dead. Recurse into nested lists of a
+ * reachable statement with a fresh reachable=true. Stop at nested functions.
+ */
+export declare function assertionsInDeadCode(body: ts.Block, isAssertion: IsAssertion): ts.Node[];
+/**
+ * Is at least one assertion guaranteed to run (so C21 must NOT fire)? Walks the
+ * "spine" of always-executed positions: top-level statements, blocks on the spine,
+ * the taken branch of an if/?: with a literal-constant condition, finally blocks,
+ * and - conservatively - a try block. A non-const if, any loop, switch, catch, or
+ * short-circuit is not guaranteed. Anything unmodeled is treated as guaranteed
+ * (suppress C21) to stay false-positive-averse.
+ */
+export declare function hasUnconditionalAssertion(body: ts.Block, isAssertion: IsAssertion, litTruth: LitTruth, deadAsserts?: ReadonlySet<ts.Node>): boolean;
+export {};