falsegreen-js 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,137 @@ 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
+- New codes: JS21 (matcher referenced but never called, `expect(x).toBe` with no `()`),
+  JS22 (empty `it.each`/`test.each` table), JS17 (commented-out test block), JS18 (`done`
+  callback instead of async/await).
+- supertest / chai-http `.expect()` is recognized as an assertion, so API integration tests
+  built with `request(app).get(...).expect(200)` are no longer flagged C2b.
+- Documented test-pyramid coverage: unit, integration (API and database), and E2E.
+- `--config-audit` mode (project layer): reads the Jest/Vitest config (`package.json` `jest`
+  field, `jest.config.*`, `vitest.config.*`; JSON directly, JS/TS via the TypeScript parser)
+  and reports PL10 (`passWithNoTests`), PL7 (no `coverageThreshold` / `coverage.thresholds`),
+  PL8 (`bail`). Findings carry level `project` and a fix hint. README now recommends Stryker
+  for the mutation-testing layer the static scan cannot reach.
+- Status report output: every finding now carries its pyramid level (unit / integration /
+  e2e, detected from the file's import roots) and a one-line fix hint. The text summary adds
+  a per-level breakdown and the top fixes by frequency; JSON gains `level` and `fix` fields.
+- `--output` flag: write to a file, or pass a directory (e.g. `.falsegreen/`) to get
+  `report.<ext>` for the chosen format. Parent directories are created as needed.
+
+### Added
+- Cross-language parity with the Python scanner: C6 (weak check — toBeTruthy/toBeDefined/length>0),
+  C20 (assertion in dead code after return/throw), C23 (mystery guest — real file at a literal
+  path / hard-coded URL), and JS8 (mocks the unit under test and asserts it directly).
+
+### Added
+- JS3 now covers visual snapshots (Playwright `toHaveScreenshot`/`toMatchScreenshot`): a test whose only check is a visual snapshot is snapshot-only (the baseline comes from the output). Percy `percySnapshot()`/`cy.percySnapshot()` is not a runtime assertion, so a percy-only test surfaces as no-assertion (C2b).
+
+### Fixed
+- Test-file discovery now matches more JS/TS naming conventions: Cypress `.cy.*`,
+  Deno/Go `_test.*`, Jasmine `*Spec.*`, Angular/Protractor `.e2e-spec.*`, and `.e2e.*`
+  (plus the `cypress`/`e2e` directories). Previously only `.test`/`.spec` were
+  discovered, so Cypress/Deno/Jasmine/Angular specs were silently skipped.
+
+### Added
+- Vue/Svelte test-utils coverage: JS5 now flags non-awaited `flushPromises`/`nextTick`/
+  `tick`; JS13 now flags Vue Test Utils `findComponent`/`findAllComponents` and
+  `find`/`findAll` with a string selector used as a loose statement.
+
 ## [0.2.0] - 2026-06-22
 
 ### Added
@@ -45,6 +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.2.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,10 +37,39 @@ 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
 ```
 
+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.
+
 Exit code: `0` clean, `10` low-confidence only, `20` high-confidence present. Wire it
 into CI or a pre-commit hook and let exit `20` block the commit.
 
@@ -44,8 +83,9 @@ expect(x);                     // falsegreen: ignore
 ## Runner coverage
 
 Runner-agnostic. The assertion and test vocabulary spans Jest, Vitest, Mocha + Chai,
-Jasmine, AVA, `node:test`, tap, Cypress, Playwright, and Testing Library
-(`@testing-library/*` with `jest-dom` / `jasmine-dom` matchers and `user-event`).
+Jasmine, AVA, `node:test`, tap, Cypress, Playwright, Testing Library
+(`@testing-library/*` with `jest-dom` / `jasmine-dom` matchers and `user-event`),
+and Vue Test Utils (`mount`/`wrapper.find`/`flushPromises`/`nextTick`).
 `expect().matcher()`, chai `expect().to`, `assert`, `x.should`, and AVA `t.is` all
 count as real assertions, so a Mocha or AVA test is not mistaken for one that never
 checks anything.
@@ -54,6 +94,25 @@ Note: component files (`.vue`, `.svelte`, `.astro`, `.marko`) and templates (`.h
 are not test files. Tests for those frameworks are written in `.spec`/`.test` files in
 the eight extensions above, which is what the scanner reads.
 
+## Test levels (the pyramid)
+
+falsegreen-js scans tests at every level of the pyramid. Discovery is level-agnostic - it
+reads any test file - but a few codes are read in light of the level, so a valid pattern at
+one level is not flagged at another.
+
+- **Unit:** a function or component with its boundaries doubled. The oracle is `expect`.
+- **Integration (API and database):** API tests through supertest / chai-http
+  (`request(app).get("/").expect(200)`, recognized as an assertion) or `fetch`, and database
+  tests through Prisma / TypeORM / Knex against a real datastore. These cross the I/O
+  boundary on purpose, so the response or row IS the verification at that level.
+- **E2E:** Cypress (`.cy.*`) and Playwright (`.e2e.*`). `cy.get().should(...)` and
+  `expect(page).toHaveURL(...)` are the oracle; a visible element is a real check here, not a
+  weak one.
+
+A real API or database call inside a test that claims to be a unit test is itself the smell
+(mystery guest, environment coupling), not the level of the test. C23 flags the hard-coded
+file path or URL form.
+
 ## Case catalog
 
 Codes shared with `falsegreen` (Python) keep the same id, so cross-language results
@@ -64,13 +123,18 @@ line up in the research. `JS*` codes are ecosystem-specific.
 | C2  | high | test with no check at all (empty body) |
 | C2b | low  | test calls code but asserts nothing |
 | 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)`) |
+| 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 |
 | C16 | low  | result depends on `Date.now`, `Math.random`, or a fixed timer |
 | 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 |
@@ -79,17 +143,22 @@ line up in the research. `JS*` codes are ecosystem-specific.
 | JS5 | low  | async query/event not awaited (`findBy*` / `waitFor` / `user-event`) |
 | JS6 | high | empty `describe`/`suite` — the suite is green but runs nothing |
 | JS7 | low  | assertion inside a non-awaited `setTimeout`/`then` callback — may run after the test ends |
+| JS8 | low  | mocks the unit under test (`jest.mock`/`vi.mock` of an imported module asserted directly) |
 | JS9 | high | assertion in a dead branch (`if(false)` / `if(true){}else`) — never runs |
 | JS11 | low | `try/catch` swallows the assertion — a failing `expect` is caught, test stays green |
 | JS13 | low | query (`getBy*`/`queryBy*`) as a loose statement — its result is never asserted |
 | JS15 | low | inappropriate assertion — comparison wrapped in a boolean (`expect(a===b).toBe(true)`), blind failure message |
+| JS17 | low | commented-out test block (`// it(...)` / `// test(...)`) — disabled, no longer runs |
+| 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 |
 
 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.
 
@@ -107,16 +176,34 @@ default. Enable them with `--diagnostics`, or per code via config `severity`. Th
 npx falsegreen-js --diagnostics      # include D*/M* as warnings
 ```
 
-### Roadmap (researched, not yet active)
-
-Tracked in the research hub, pending implementation: JS8 (mocking the unit under test),
-JS10 (async test with no `expect.assertions` and the assertion only in a `catch`), JS12
-(`render(<C/>)`/`mount()` with no query or assertion), JS13 (a `getBy*`/`queryBy*` query
-as a loose statement), and a general Mystery Guest / external-resource code.
+### Deliberately not implemented
+
+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 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 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),
@@ -149,21 +236,51 @@ 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
 
 MIT, Vinicius Queiroz.
+
+## Contributors ✨
+
+Thanks to the people who keep false-green tests out of real suites ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
+
+<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
+[![All Contributors](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)](#contributors-)
+<!-- ALL-CONTRIBUTORS-BADGE:END -->
+
+<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<table>
+  <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> <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>
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+
+<!-- ALL-CONTRIBUTORS-LIST:END -->
+
+New contributors are added automatically; the table also recognizes non-code work (docs, ideas, infrastructure, tests, research) via the [all-contributors](https://allcontributors.org) spec.

package/dist/audit.d.ts

@@ -0,0 +1,5 @@
+import { Finding } from "./types.js";
+/** Read the Jest/Vitest config and report the project-layer PL codes: ways the
+ * suite can report green by configuration. Findings carry level `project`.
+ * Returns [] when no Jest/Vitest config is found. */
+export declare function auditConfig(start?: string): Finding[];

package/dist/audit.js

@@ -0,0 +1,120 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import ts from "typescript";
+import { makeFinding } from "./types.js";
+import { parse } from "./parse.js";
+/** JSON config: package.json `jest` field, or jest.config.json. */
+function readJsonConfig(start) {
+    const pkg = path.join(start, "package.json");
+    if (fs.existsSync(pkg)) {
+        try {
+            const j = JSON.parse(fs.readFileSync(pkg, "utf-8"));
+            if (j && typeof j.jest === "object")
+                return { path: pkg, cfg: j.jest };
+        }
+        catch { /* unreadable */ }
+    }
+    const jcj = path.join(start, "jest.config.json");
+    if (fs.existsSync(jcj)) {
+        try {
+            return { path: jcj, cfg: JSON.parse(fs.readFileSync(jcj, "utf-8")) };
+        }
+        catch { /* unreadable */ }
+    }
+    return null;
+}
+/** JS/TS config (jest.config.*, vitest.config.*, vite.config.*): AST-walk for
+ * the property assignments of interest. A heuristic, not full evaluation. */
+function readAstConfig(start) {
+    const candidates = [
+        "jest.config.ts", "jest.config.js", "jest.config.mjs", "jest.config.cjs",
+        "vitest.config.ts", "vitest.config.js", "vitest.config.mts",
+        "vite.config.ts", "vite.config.js",
+    ];
+    for (const name of candidates) {
+        const p = path.join(start, name);
+        if (!fs.existsSync(p))
+            continue;
+        let text;
+        try {
+            text = fs.readFileSync(p, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const sf = parse(p, text);
+        const props = new Set();
+        let passWithNoTests = false;
+        let bail = false;
+        const visit = (node) => {
+            if (ts.isPropertyAssignment(node) &&
+                (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name))) {
+                const key = node.name.text;
+                props.add(key);
+                const init = node.initializer;
+                if (key === "passWithNoTests" && init.kind === ts.SyntaxKind.TrueKeyword) {
+                    passWithNoTests = true;
+                }
+                if (key === "bail") {
+                    if (init.kind === ts.SyntaxKind.TrueKeyword)
+                        bail = true;
+                    else if (ts.isNumericLiteral(init) && Number(init.text) > 0)
+                        bail = true;
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(sf);
+        return { path: p, props, passWithNoTests, bail };
+    }
+    return null;
+}
+function collect(start) {
+    const json = readJsonConfig(start);
+    const ast = readAstConfig(start);
+    if (!json && !ast)
+        return null;
+    let passWithNoTests = false;
+    let bail = false;
+    let hasCovGate = false;
+    if (json) {
+        const c = json.cfg;
+        if (c.passWithNoTests === true)
+            passWithNoTests = true;
+        if (c.bail === true || (typeof c.bail === "number" && c.bail > 0))
+            bail = true;
+        const cov = c.coverage;
+        if (c.coverageThreshold || c.thresholds || (cov && cov.thresholds))
+            hasCovGate = true;
+    }
+    if (ast) {
+        if (ast.passWithNoTests)
+            passWithNoTests = true;
+        if (ast.bail)
+            bail = true;
+        if (ast.props.has("coverageThreshold") || ast.props.has("thresholds"))
+            hasCovGate = true;
+    }
+    return { where: json?.path ?? ast.path, passWithNoTests, bail, hasCovGate };
+}
+/** Read the Jest/Vitest config and report the project-layer PL codes: ways the
+ * suite can report green by configuration. Findings carry level `project`.
+ * Returns [] when no Jest/Vitest config is found. */
+export function auditConfig(start = process.cwd()) {
+    const sig = collect(start);
+    if (!sig)
+        return [];
+    const findings = [];
+    const mk = (code) => {
+        const f = makeFinding(sig.where, 1, code);
+        f.level = "project";
+        return f;
+    };
+    if (!sig.hasCovGate)
+        findings.push(mk("PL7"));
+    if (sig.bail)
+        findings.push(mk("PL8"));
+    if (sig.passWithNoTests)
+        findings.push(mk("PL10"));
+    return findings;
+}

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,4 +47,33 @@ export declare const DIAGNOSTIC_THRESHOLDS: {
     assertionRoulette: number;
     longTest: number;
 };
-export declare function groupOf(code: string): "false-positive" | "diagnostic" | "coupling";
+/**
+ * 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. */
+export type PyramidLevel = "unit" | "integration" | "e2e" | "project";
+/**
+ * One-line remediation per case: what to change so the test protects something.
+ * Short, imperative, no trailing period. Surfaced in the status report (text +
+ * JSON `fix` field). A code missing here renders no fix line, never throws.
+ */
+export declare const FIX_HINTS: Record<string, string>;