falsegreen-js 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-22
+
+### Added
+
+- Initial release. Deterministic AST scanner for false-green test smells in JS/TS.
+- More false-green codes: C9 (broad `toThrow`), C37 (duplicate `it.each` case),
+  JS13 (loose RTL query never asserted).
+- Opt-in maintainability group (default off, enable with `--diagnostics` or config
+  `severity`): D1 (assertion roulette), D3 (duplicate assert), D4 (`it.each` without
+  titled cases), D6 (`console.*` in a test), D7 (anonymous test), M2 (long test body).
+- Parser via the TypeScript compiler API, covering `.js`, `.jsx`, `.ts`, `.tsx`,
+  `.mjs`, `.cjs`, `.mts`, `.cts`.
+- Runner-agnostic assertion/test vocabulary: Jest, Vitest, Mocha + Chai, Jasmine, AVA,
+  `node:test`, tap, Cypress, Playwright, Testing Library (jest-dom matchers).
+- Detection codes:
+  - Shared concept with `falsegreen` (Python): C2, C2b, C5, C7, C8, C16, CC.
+  - Shared, additional: C18 (sensitive equality on a stringified value), C21 (every
+    assertion is conditional).
+  - JS/TS-specific: JS1 (focused test), JS2 (expect with no matcher), JS3 (snapshot-only),
+    JS4 (skipped test), JS5 (async query/event not awaited), JS6 (empty describe),
+    JS7 (assertion in a non-awaited timer/then callback), JS9 (assertion in a dead literal
+    branch), JS11 (try/catch swallows the assertion).
+- Custom assertion helpers (`assert*`/`expect*` naming, e.g. `util.assertEqual`) are
+  recognized as assertions, reducing C2b false positives.
+- CLI: paths, `--staged`, `--json`, `--disable`, `--version`, `--help`. Exit codes
+  0/10/20. Inline suppression `// falsegreen: ignore[CODE]`. Config via `falsegreen.json`,
+  `.falsegreenrc.json`, or a `falsegreen` key in `package.json`.
+- 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.1.0...HEAD
+[0.1.0]: https://github.com/vinicq/falsegreen-js/releases/tag/v0.1.0

package/CREDITS.md

@@ -0,0 +1,59 @@
+# References
+
+falsegreen-js detects false-green test smells in JS/TS. Its catalog draws on the
+academic test-smell literature and on existing detection tools. This file credits
+those sources and maps each to the codes it informs.
+
+## Founding and conceptual
+
+- **van Deursen, Moonen, van den Bergh, Kok (2001).** "Refactoring Test Code." XP 2001.
+  The original catalog of 11 test smells. Source of the general vocabulary.
+- **Delplanque, Ducasse, Polito, Black, Etien (2019).** "Rotten Green Tests." ICSE 2019.
+  Green tests whose assertions never execute. The conceptual origin of the
+  "false-green" framing and of codes JS2, JS6, JS9, JS11 (assertion present but
+  unreachable). Cross-language extension: EMSE 2021.
+
+## JS/TS empirical and tooling
+
+- **Jorge, D. N. (2023).** "Uma investigação sobre Test Smells em códigos de testes
+  JavaScript." PhD thesis, PPGCC/UFCG. Static analysis of 16 test smells over 65 JS
+  projects. Closest sibling study; maps to C2, C2b, C5, C16, JS4.
+- **Silva, A. C. (2022).** "Identificação e Caracterização de Test Smells em JavaScript."
+  PUC Minas. Proposes the JS-specific smells **Only Test** and **Complex Snapshot** —
+  the academic precedent for **JS1** and **JS3**.
+- **Oliveira et al. (2024).** "SNUTS.js: Sniffing Nasty Unit Test Smells in JavaScript."
+  SBES 2024. JS test-smell detector; informs C8 (sensitive equality) scope.
+- **Oliveira et al. (2025).** "Identifying and Addressing Test Smells in JavaScript: A
+  Developer-Centric Study." SBES 2025. Motivation: developers miss subtle smells.
+
+## Detection-tool baselines
+
+- **Peruma, Almalki, Newman, Mkaouer, Ouni, Palomba (2020).** "tsDetect: An Open Source
+  Test Smells Detection Tool." ESEC/FSE 2020. The de facto Java baseline (~96% precision).
+- **marabesi/smelly-test.** JS/TS test-smell detector (TypeScript compiler API), the
+  closest tooling analogue; informs JS6 (empty describe).
+- **Panichella, Panichella, Beller, Zaidman et al. (2022).** "Test Smells 20 Years Later."
+  EMSE. Methodological caution: catalog agreement is not perceived quality.
+
+## React / frontend (scope note)
+
+- **Ferreira & Valente (2023).** "Detecting code smells in React-based Web apps." IST 155.
+  React **production** code smells (ReactSniffer). Cited to mark the boundary:
+  those are not test smells and are out of scope for a test-file scanner.
+
+## Code-to-source map
+
+| Code | Primary source(s) |
+|---|---|
+| C2, C2b | van Deursen 2001; Jorge 2023 (Empty/Unknown Test) |
+| C5, C7 | Redundant Assertion (Jorge 2023; tsDetect) |
+| C8 | Sensitive Equality (SNUTS.js 2024) |
+| C16 | Sleepy Test (Jorge 2023) |
+| JS1 | Only Test (Silva 2022) |
+| JS3 | Complex Snapshot (Silva 2022) |
+| JS2, JS6, JS9, JS11 | Rotten Green Tests (Delplanque 2019) |
+| JS4 | Ignored Test (Jorge 2023; tsDetect) |
+| JS5 | Testing Library async guidance (community practice) |
+| CC | community practice (commented-out assertion) |
+
+Detailed per-source notes and the running research live in a separate private study.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Queiroz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+# falsegreen-js
+
+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)
+(the Python scanner); same contract, JS/TS rule set.
+
+Covers `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`, `.mts`, `.cts`.
+
+## Why
+
+A test can be green and still protect nothing: an empty body, an assertion that is
+never reached, `expect(x).toBe(x)`, `expect(value)` with no matcher, a focused
+`it.only` that silently parks the rest of the suite, a `findByText` that is never
+awaited. AI-generated tests produce these in bulk. This tool flags the mechanical
+patterns a parser can prove, before they reach review.
+
+## Install
+
+```bash
+npm install -D falsegreen-js
+```
+
+## Usage
+
+```bash
+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 --disable C7,JS3
+```
+
+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.
+
+Suppress a single finding inline:
+
+```ts
+expect(user.id).toBe(user.id); // falsegreen: ignore[C7]
+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`).
+`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.
+
+Note: component files (`.vue`, `.svelte`, `.astro`, `.marko`) and templates (`.html`)
+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.
+
+## Case catalog
+
+Codes shared with `falsegreen` (Python) keep the same id, so cross-language results
+line up in the research. `JS*` codes are ecosystem-specific.
+
+| Code | Confidence | What it flags |
+|---|---|---|
+| 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)`) |
+| C7  | high | compares a thing to itself (`expect(x).toBe(x)`) |
+| 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 |
+| 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 |
+| JS3 | low  | snapshot is the only assertion |
+| JS4 | low  | skipped test (`it.skip` / `xit` / `it.todo`) never runs |
+| 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 |
+| 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 |
+
+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
+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.
+
+| Code | Group | What it flags |
+|---|---|---|
+| D1 | diagnostic | assertion roulette — many assertions in one test |
+| D3 | diagnostic | duplicate assert — the same assertion repeated |
+| D4 | diagnostic | `it.each`/`test.each` without titled cases (index-only) |
+| D6 | diagnostic | `console.*` in a test body |
+| D7 | diagnostic | anonymous test — empty or missing description |
+| M2 | coupling | test body exceeds the line-count threshold |
+
+```bash
+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.
+
+### What carries over from falsegreen, what does not
+
+Ported (same concept): C2, C2b, C5, C7, C8, C16, 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),
+sklearn/torch/tensorflow metric and seed codes (C33, parts of C16), xfail (C25), and the
+xunit/`self.assert*` codes. These have no JS equivalent or need a different signal.
+
+JS/TS-only (new here): JS1-JS5 above. The `describe.only`/skip, snapshot, no-matcher,
+and not-awaited patterns are specific to the JS test runners and Testing Library.
+
+## Configuration
+
+Optional. `falsegreen.json`, `.falsegreenrc.json`, or a `"falsegreen"` key in
+`package.json`:
+
+```json
+{
+  "disable": ["C8"],
+  "exclude": ["**/legacy/**"],
+  "severity": { "JS3": "off", "C16": "high" }
+}
+```
+
+Precedence: CLI `--disable` > config `disable`/`severity` > catalog default.
+
+## Scope and honesty
+
+This is a static scanner. It owns what the structure proves. Two things it does not
+decide: whether the expected value contradicts the intended behavior, and whether the
+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.
+
+## 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
+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.
+
+## License
+
+MIT, Vinicius Queiroz.

package/dist/cases.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Case catalog for falsegreen-js. Mirrors falsegreen (Python) where the smell is
+ * 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.
+ */
+export type Confidence = "high" | "low" | "off";
+export declare const JUDGMENTS: Record<string, string>;
+export interface CaseDef {
+    title: string;
+    confidence: Confidence;
+    judgment: keyof typeof JUDGMENTS;
+}
+export declare const CASES: Record<string, CaseDef>;
+/** Default thresholds for the diagnostic group (overridable later via config). */
+export declare const DIAGNOSTIC_THRESHOLDS: {
+    assertionRoulette: number;
+    longTest: number;
+};
+export declare function groupOf(code: string): "false-positive" | "diagnostic" | "coupling";

package/dist/cases.js

@@ -0,0 +1,59 @@
+/**
+ * Case catalog for falsegreen-js. Mirrors falsegreen (Python) where the smell is
+ * 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.
+ */
+export const JUDGMENTS = {
+    J1: "does the assertion actually run?",
+    J2: "is the oracle independent of the code?",
+    J3: "does it exercise the real unit, or a stand-in?",
+    J4: "does it check enough, and the right thing?",
+    J5: "is it coupled to internals it should not see?",
+    J6: "does it pass in isolation, or only via shared state?",
+};
+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" },
+    C7: { title: "compares a thing to itself (expect(x).toBe(x))", confidence: "high", judgment: "J2" },
+    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" },
+    // --- 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" },
+    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" },
+    // --- 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" },
+    M2: { title: "test body exceeds the line-count threshold — hard to read and maintain", confidence: "off", judgment: "J5" },
+};
+/** Default thresholds for the diagnostic group (overridable later via config). */
+export const DIAGNOSTIC_THRESHOLDS = { assertionRoulette: 5, longTest: 50 };
+export function groupOf(code) {
+    if (code.startsWith("D"))
+        return "diagnostic";
+    if (code.startsWith("M"))
+        return "coupling";
+    return "false-positive";
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import { JUDGMENTS, groupOf } from "./cases.js";
+import { scanPaths, scanFile, stagedFiles, loadConfig, } from "./scan.js";
+const VERSION = "0.1.0";
+const TOOL_URI = "https://github.com/vinicq/falsegreen-js";
+const HELP = `falsegreen-js ${VERSION} - find false-positive JS/TS tests (static AST scan)
+
+Usage:
+  falsegreen-js [paths...]        files/dirs; no args = scan cwd
+  falsegreen-js --staged          only test files staged in git
+  falsegreen-js --json            JSON output
+  falsegreen-js --diagnostics     also report the opt-in maintainability group (D*/M*)
+  falsegreen-js --disable C7,JS3  turn off specific codes
+  falsegreen-js --version
+  falsegreen-js --help
+
+Exit codes: 0 clean, 10 low-confidence only, 20 high-confidence present.
+Suppress inline:  expect(x).toBe(x); // falsegreen: ignore[C7]
+Covers: .js .jsx .ts .tsx .mjs .cjs .mts .cts`;
+function parseArgs(argv) {
+    const paths = [];
+    let json = false, staged = false, help = false, version = false, diagnostics = false;
+    const disable = new Set();
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--json")
+            json = true;
+        else if (a === "--staged")
+            staged = true;
+        else if (a === "--diagnostics")
+            diagnostics = true;
+        else if (a === "--help" || a === "-h")
+            help = true;
+        else if (a === "--version" || a === "-V")
+            version = true;
+        else if (a === "--disable") {
+            const v = argv[++i] ?? "";
+            v.split(",").map((s) => s.trim()).filter(Boolean).forEach((c) => disable.add(c));
+        }
+        else if (a.startsWith("--disable=")) {
+            a.slice("--disable=".length).split(",").map((s) => s.trim())
+                .filter(Boolean).forEach((c) => disable.add(c));
+        }
+        else if (a.startsWith("-")) {
+            process.stderr.write(`falsegreen-js: unknown option ${a}\n`);
+            process.exit(2);
+        }
+        else
+            paths.push(a);
+    }
+    return { paths, json, staged, help, version, diagnostics, disable };
+}
+function exitCode(findings) {
+    if (findings.some((f) => f.confidence === "high"))
+        return 20;
+    if (findings.some((f) => f.confidence === "low"))
+        return 10;
+    return 0;
+}
+function renderText(findings) {
+    if (findings.length === 0)
+        return "falsegreen-js: no false-positive patterns found.";
+    const byFile = new Map();
+    for (const f of findings) {
+        (byFile.get(f.file) ?? byFile.set(f.file, []).get(f.file)).push(f);
+    }
+    const lines = [];
+    let high = 0, low = 0;
+    for (const [file, fs_] of byFile) {
+        lines.push(`\n${file}`);
+        for (const f of fs_.sort((a, b) => a.line - b.line)) {
+            const tag = f.confidence === "high" ? "HIGH" : "low ";
+            if (f.confidence === "high")
+                high++;
+            else
+                low++;
+            lines.push(`  ${tag} ${f.code.padEnd(4)} L${f.line}  ${f.title}` +
+                (f.detail ? `\n         ${f.detail}` : ""));
+        }
+    }
+    lines.push(`\n${high} high, ${low} low. ${TOOL_URI}`);
+    return lines.join("\n");
+}
+function main() {
+    const opt = parseArgs(process.argv.slice(2));
+    if (opt.help) {
+        process.stdout.write(HELP + "\n");
+        process.exit(0);
+    }
+    if (opt.version) {
+        process.stdout.write(VERSION + "\n");
+        process.exit(0);
+    }
+    const config = loadConfig();
+    const scanOpts = { config, cliDisable: opt.disable, diagnostics: opt.diagnostics };
+    let findings;
+    if (opt.staged) {
+        findings = stagedFiles().flatMap((f) => scanFile(f, scanOpts));
+    }
+    else {
+        findings = scanPaths(opt.paths.length ? opt.paths : ["."], scanOpts);
+    }
+    if (opt.json) {
+        process.stdout.write(JSON.stringify({
+            tool: "falsegreen-js",
+            version: VERSION,
+            judgments: JUDGMENTS,
+            findings: findings.map((f) => ({ ...f, group: groupOf(f.code) })),
+        }, null, 2) + "\n");
+    }
+    else {
+        process.stdout.write(renderText(findings) + "\n");
+    }
+    process.exit(exitCode(findings));
+}
+main();

package/dist/parse.d.ts

@@ -0,0 +1,7 @@
+import ts from "typescript";
+/** Map a file extension to the TypeScript ScriptKind so JSX/TSX parse correctly. */
+export declare function scriptKindFor(file: string): ts.ScriptKind;
+/** Parse source text into a SourceFile (setParentNodes=true so we can walk up). */
+export declare function parse(file: string, text: string): ts.SourceFile;
+/** 1-based line number of a node's start, from the SourceFile line map. */
+export declare function lineOf(sf: ts.SourceFile, node: ts.Node): number;

package/dist/parse.js

@@ -0,0 +1,31 @@
+import ts from "typescript";
+import * as path from "node:path";
+/** Map a file extension to the TypeScript ScriptKind so JSX/TSX parse correctly. */
+export function scriptKindFor(file) {
+    const ext = path.extname(file).toLowerCase();
+    switch (ext) {
+        case ".tsx":
+            return ts.ScriptKind.TSX;
+        case ".jsx":
+            return ts.ScriptKind.JSX;
+        case ".ts":
+        case ".mts":
+        case ".cts":
+            return ts.ScriptKind.TS;
+        case ".js":
+        case ".mjs":
+        case ".cjs":
+            return ts.ScriptKind.JS;
+        default:
+            return ts.ScriptKind.TS;
+    }
+}
+/** Parse source text into a SourceFile (setParentNodes=true so we can walk up). */
+export function parse(file, text) {
+    return ts.createSourceFile(file, text, ts.ScriptTarget.Latest, 
+    /* setParentNodes */ true, scriptKindFor(file));
+}
+/** 1-based line number of a node's start, from the SourceFile line map. */
+export function lineOf(sf, node) {
+    return sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+}

package/dist/rules.d.ts

@@ -0,0 +1,3 @@
+import ts from "typescript";
+import { Finding } from "./types.js";
+export declare function analyze(sf: ts.SourceFile): Finding[];

package/dist/rules.js

@@ -0,0 +1,499 @@
+import ts from "typescript";
+import { makeFinding } from "./types.js";
+import { DIAGNOSTIC_THRESHOLDS } from "./cases.js";
+import { lineOf } from "./parse.js";
+// --- test framework vocabulary (runner-agnostic) ---------------------------
+// it/test/specify (Jest, Vitest, Mocha, Jasmine, AVA, node:test, Cypress,
+// Playwright, tap). describe/context/suite are suites. fit/fdescribe focus and
+// xit/xdescribe skip come from Jasmine/Mocha.
+const TEST_BLOCK_ROOTS = new Set(["it", "test", "specify"]);
+const SUITE_ROOTS = new Set(["describe", "context", "suite", "fdescribe", "xdescribe", "fcontext", "xcontext"]);
+const FOCUS_NAMES = new Set(["fit", "fdescribe", "fcontext"]);
+const SKIP_NAMES = new Set(["xit", "xdescribe", "xcontext", "xspecify"]);
+// Roots whose `<root>.<method>()` call counts as an assertion across runners:
+// AVA (t), node:test/tap (t), Cypress (cy), chai assert, sinon.assert.
+const ASSERT_ROOTS = new Set(["assert", "t", "cy", "tap", "qunit", "sinon", "chai", "should"]);
+// Assertion method names used by AVA / tap / node:test / chai assert / QUnit.
+const ASSERT_METHODS = new Set([
+    "is", "not", "ok", "notOk", "true", "false", "truthy", "falsy",
+    "equal", "notEqual", "deepEqual", "notDeepEqual", "strictEqual",
+    "same", "notSame", "throws", "notThrows", "throwsAsync", "regex", "notRegex",
+    "pass", "fail", "assert", "expect", "include", "match",
+]);
+const SNAPSHOT_MATCHERS = new Set([
+    "toMatchSnapshot", "toMatchInlineSnapshot",
+    "toThrowErrorMatchingSnapshot", "toThrowErrorMatchingInlineSnapshot",
+]);
+const EQUALITY_MATCHERS = new Set(["toBe", "toEqual", "toStrictEqual"]);
+// --- name helpers ----------------------------------------------------------
+function calleeName(expr) {
+    if (ts.isIdentifier(expr))
+        return expr.text;
+    if (ts.isPropertyAccessExpression(expr)) {
+        const base = calleeName(expr.expression);
+        return base ? base + "." + expr.name.text : expr.name.text;
+    }
+    if (ts.isCallExpression(expr))
+        return calleeName(expr.expression);
+    if (ts.isParenthesizedExpression(expr))
+        return calleeName(expr.expression);
+    return "";
+}
+function literalTruthiness(e) {
+    if (!e)
+        return null;
+    if (e.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    if (e.kind === ts.SyntaxKind.FalseKeyword)
+        return false;
+    if (e.kind === ts.SyntaxKind.NullKeyword)
+        return false;
+    if (ts.isIdentifier(e) && e.text === "undefined")
+        return false;
+    if (ts.isNumericLiteral(e))
+        return Number(e.text) !== 0;
+    if (ts.isStringLiteral(e))
+        return e.text.length > 0;
+    return null;
+}
+function isLiteral(e) {
+    if (!e)
+        return false;
+    return (e.kind === ts.SyntaxKind.TrueKeyword ||
+        e.kind === ts.SyntaxKind.FalseKeyword ||
+        e.kind === ts.SyntaxKind.NullKeyword ||
+        ts.isNumericLiteral(e) ||
+        ts.isStringLiteral(e) ||
+        ts.isNoSubstitutionTemplateLiteral(e));
+}
+/** A value turned into text: String(x), JSON.stringify(x), x.toString(), `${x}`. */
+function isStringify(e) {
+    if (!e)
+        return false;
+    if (ts.isTemplateExpression(e))
+        return true;
+    if (ts.isCallExpression(e)) {
+        const n = calleeName(e.expression);
+        const leaf = n.split(".").pop() ?? "";
+        return leaf === "String" || n === "JSON.stringify" || leaf === "toString" || leaf === "toJSON";
+    }
+    return false;
+}
+const CONDITIONAL_ANCESTORS = new Set([
+    ts.SyntaxKind.IfStatement, ts.SyntaxKind.ForStatement, ts.SyntaxKind.ForOfStatement,
+    ts.SyntaxKind.ForInStatement, ts.SyntaxKind.WhileStatement, ts.SyntaxKind.DoStatement,
+    ts.SyntaxKind.SwitchStatement, ts.SyntaxKind.CatchClause, ts.SyntaxKind.ConditionalExpression,
+]);
+/** True if the function has at least one assertion and every one of them sits under a
+ *  conditional (if/for/while/switch/catch/?:) — so none runs unconditionally (C21). */
+function assertionsAllConditional(fn) {
+    const asserts = [];
+    const walk = (n) => { if (isAssertionNode(n))
+        asserts.push(n); ts.forEachChild(n, walk); };
+    ts.forEachChild(fn, walk);
+    if (asserts.length === 0)
+        return false;
+    for (const a of asserts) {
+        let p = a.parent;
+        let conditional = false;
+        while (p && p !== fn) {
+            if (CONDITIONAL_ANCESTORS.has(p.kind)) {
+                conditional = true;
+                break;
+            }
+            p = p.parent;
+        }
+        if (!conditional)
+            return false;
+    }
+    return true;
+}
+function containsCall(node) {
+    let found = false;
+    const walk = (n) => {
+        if (found)
+            return;
+        if (ts.isCallExpression(n)) {
+            found = true;
+            return;
+        }
+        ts.forEachChild(n, walk);
+    };
+    walk(node);
+    return found;
+}
+/** Decode `expect(subject)[.not][.resolves].matcher(args)` from a CallExpression. */
+function expectChain(call) {
+    if (!ts.isPropertyAccessExpression(call.expression))
+        return null;
+    const matcher = call.expression.name.text;
+    let base = call.expression.expression;
+    let negated = false;
+    while (ts.isPropertyAccessExpression(base)) {
+        if (base.name.text === "not")
+            negated = true;
+        base = base.expression;
+    }
+    if (ts.isCallExpression(base) &&
+        ts.isIdentifier(base.expression) &&
+        base.expression.text === "expect") {
+        return { subject: base.arguments[0], matcher, args: call.arguments, negated };
+    }
+    return null;
+}
+// --- assertion presence ----------------------------------------------------
+function isAssertionNode(node) {
+    if (ts.isCallExpression(node)) {
+        const name = calleeName(node.expression);
+        const parts = name.split(".");
+        const root = parts[0];
+        const leaf = parts[parts.length - 1];
+        // expect(x).matcher(...) — Jest, Vitest, Jasmine, Playwright, jest-dom, chai expect
+        if (root === "expect" && ts.isPropertyAccessExpression(node.expression))
+            return true;
+        if (root === "assert")
+            return true; // node:test, chai assert
+        if (root === "sinon" && name.includes("assert"))
+            return true;
+        // AVA (t.is), node:test/tap (t.ok), Cypress (cy....should), QUnit
+        if (ASSERT_ROOTS.has(root) && ASSERT_METHODS.has(leaf))
+            return true;
+        if (leaf === "should")
+            return true; // x.should() (chai/Cypress as a call)
+        // custom assertion helpers by naming convention: util.assertEqual(...),
+        // assertType(...), expectType(...), checkX(...). Bare expect() is excluded
+        // (that is JS2). Recognizing these avoids C2b false positives in projects
+        // that extract assertions into helpers.
+        if (leaf.startsWith("assert"))
+            return true;
+        if (leaf.startsWith("expect") && leaf !== "expect")
+            return true;
+    }
+    // chai/Cypress fluent: x.should.equal / cy.get().should — the `.should` access
+    if (ts.isPropertyAccessExpression(node) && node.name.text === "should")
+        return true;
+    return false;
+}
+function hasAssertion(scope) {
+    let found = false;
+    const walk = (n) => {
+        if (found)
+            return;
+        if (isAssertionNode(n)) {
+            found = true;
+            return;
+        }
+        ts.forEachChild(n, walk);
+    };
+    ts.forEachChild(scope, walk);
+    return found;
+}
+/** Like hasAssertion but tests the node itself too (for branch/try-block subtrees). */
+function containsAssertion(node) {
+    return isAssertionNode(node) || hasAssertion(node);
+}
+/** True if a catch block does nothing meaningful: empty, or only console.* /
+ *  comments, with no throw, no assertion, and no fail() — so it swallows errors. */
+function isHarmlessCatch(block) {
+    for (const stmt of block.statements) {
+        if (ts.isThrowStatement(stmt))
+            return false;
+        if (containsAssertion(stmt))
+            return false;
+        if (ts.isExpressionStatement(stmt)) {
+            const name = calleeName(ts.isCallExpression(stmt.expression) ? stmt.expression.expression : stmt.expression);
+            const leaf = name.split(".").pop() ?? "";
+            if (name.startsWith("console."))
+                continue;
+            if (leaf === "fail")
+                return false;
+            continue; // other no-op-ish expression: still swallows
+        }
+        // any other statement (return/log/etc.) still does not re-raise
+    }
+    return true;
+}
+/** Matcher names of every expect-chain assertion under scope (for snapshot-only). */
+function matchersUnder(scope) {
+    const out = [];
+    const walk = (n) => {
+        if (ts.isCallExpression(n)) {
+            const chain = expectChain(n);
+            if (chain)
+                out.push(chain.matcher);
+        }
+        ts.forEachChild(n, walk);
+    };
+    ts.forEachChild(scope, walk);
+    return out;
+}
+function getTestCallback(call) {
+    for (const arg of call.arguments) {
+        if (ts.isArrowFunction(arg) || ts.isFunctionExpression(arg))
+            return arg;
+    }
+    return null;
+}
+// --- JS5: async query/event not awaited (Testing Library) ------------------
+const ASYNC_AWAIT_LEAVES = new Set(["waitFor", "waitForElementToBeRemoved"]);
+function isAsyncQueryCall(name) {
+    const parts = name.split(".");
+    const root = parts[0];
+    const leaf = parts[parts.length - 1];
+    if (root === "userEvent")
+        return true;
+    if (leaf.startsWith("findBy") || leaf.startsWith("findAllBy"))
+        return true;
+    return ASYNC_AWAIT_LEAVES.has(leaf);
+}
+// --- C16: nondeterminism ----------------------------------------------------
+function c16Detail(call) {
+    const name = calleeName(call.expression);
+    if (name === "Math.random")
+        return "Math.random() without a fixed seed";
+    if (name === "Date.now" || name === "performance.now")
+        return "reads the system clock";
+    if (name === "setTimeout" || name === "setInterval") {
+        if (call.arguments.length >= 2 && ts.isNumericLiteral(call.arguments[1])) {
+            return "fixed timer delay";
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Main: collect findings from a parsed source file.
+// ---------------------------------------------------------------------------
+export function analyze(sf) {
+    const findings = [];
+    const file = sf.fileName;
+    const text = sf.getFullText();
+    const fakeTimers = /\b(useFakeTimers)\b/.test(text);
+    const push = (line, code, detail = "") => {
+        findings.push(makeFinding(file, line, code, detail));
+    };
+    const visit = (node) => {
+        if (ts.isCallExpression(node)) {
+            const name = calleeName(node.expression);
+            const root = name.split(".")[0];
+            const modifier = name.split(".")[1] ?? "";
+            // JS1 focused / JS4 skipped
+            if (name.endsWith(".only") ||
+                FOCUS_NAMES.has(root) ||
+                (FOCUS_NAMES.has(name))) {
+                push(lineOf(sf, node), "JS1", `focused via ${name}`);
+            }
+            else if (name.endsWith(".skip") ||
+                name.endsWith(".todo") ||
+                SKIP_NAMES.has(root)) {
+                push(lineOf(sf, node), "JS4", `skipped via ${name}`);
+            }
+            // test-level block body checks (C2, C2b, JS3). Only `it`/`test`/`specify`
+            // (and the focus/skip variants) — never `describe`/`suite`, whose body holds
+            // nested tests, not assertions.
+            const isTestBlock = TEST_BLOCK_ROOTS.has(root) || root === "fit" || root === "xit" ||
+                ((TEST_BLOCK_ROOTS.has(root)) && (modifier === "only" || modifier === "skip" || modifier === "each"));
+            if (isTestBlock) {
+                const cb = getTestCallback(node);
+                if (cb && cb.body && ts.isBlock(cb.body)) {
+                    const stmts = cb.body.statements;
+                    const line = lineOf(sf, node);
+                    if (stmts.length === 0) {
+                        push(line, "C2", "test body is empty");
+                    }
+                    else if (!hasAssertion(cb) && containsCall(cb.body)) {
+                        push(line, "C2b", "calls code but never asserts");
+                    }
+                    else if (hasAssertion(cb)) {
+                        const ms = matchersUnder(cb);
+                        if (ms.length > 0 && ms.every((m) => SNAPSHOT_MATCHERS.has(m))) {
+                            push(line, "JS3", "the only assertion is a snapshot");
+                        }
+                        if (assertionsAllConditional(cb)) {
+                            push(line, "C21", "every assertion is guarded by a condition");
+                        }
+                    }
+                    // D7: anonymous test (empty or missing description)
+                    const desc = node.arguments[0];
+                    const emptyStr = (d) => d !== undefined &&
+                        (ts.isStringLiteral(d) || ts.isNoSubstitutionTemplateLiteral(d)) && d.text.trim() === "";
+                    if (desc === cb || desc === undefined || emptyStr(desc)) {
+                        push(line, "D7", "test has no description");
+                    }
+                    // diagnostic group (maintainability; emitted always, filtered when off)
+                    const asserts = [];
+                    const consoles = [];
+                    const walkD = (n) => {
+                        if (isAssertionNode(n))
+                            asserts.push(n);
+                        if (ts.isCallExpression(n) && calleeName(n.expression).startsWith("console."))
+                            consoles.push(n);
+                        ts.forEachChild(n, walkD);
+                    };
+                    ts.forEachChild(cb, walkD);
+                    if (asserts.length >= DIAGNOSTIC_THRESHOLDS.assertionRoulette) {
+                        push(line, "D1", `${asserts.length} assertions in one test`);
+                    }
+                    const seenA = new Set();
+                    for (const a of asserts) {
+                        const t = a.getText(sf).replace(/\s+/g, " ").trim();
+                        if (seenA.has(t)) {
+                            push(line, "D3", "an assertion is repeated");
+                            break;
+                        }
+                        seenA.add(t);
+                    }
+                    for (const c of consoles)
+                        push(lineOf(sf, c), "D6", "console call in a test body");
+                    const startL = sf.getLineAndCharacterOfPosition(cb.body.getStart(sf)).line;
+                    const endL = sf.getLineAndCharacterOfPosition(cb.body.getEnd()).line;
+                    if (endL - startL > DIAGNOSTIC_THRESHOLDS.longTest) {
+                        push(line, "M2", `test body spans ${endL - startL} lines`);
+                    }
+                }
+            }
+            // JS6: empty describe/suite block
+            if (SUITE_ROOTS.has(root) || (SUITE_ROOTS.has(root) && (modifier === "only" || modifier === "skip"))) {
+                const cb = getTestCallback(node);
+                if (cb && cb.body && ts.isBlock(cb.body) && cb.body.statements.length === 0) {
+                    push(lineOf(sf, node), "JS6", "suite body is empty");
+                }
+            }
+            // JS2: bare expect(x) with no matcher
+            if (ts.isIdentifier(node.expression) &&
+                node.expression.text === "expect" &&
+                !ts.isPropertyAccessExpression(node.parent)) {
+                push(lineOf(sf, node), "JS2", "expect(...) is not chained to a matcher");
+            }
+            // assert(literal) -> C5
+            if ((root === "assert" || name === "assert.ok") && literalTruthiness(node.arguments[0]) === true) {
+                push(lineOf(sf, node), "C5", "assert on a constant truthy value");
+            }
+            // expect-chain matchers (C5, C7, C8)
+            const chain = expectChain(node);
+            if (chain && !chain.negated) {
+                const subj = chain.subject;
+                const arg = chain.args[0];
+                // C9 over-broad throw assertion: toThrow() with no error type or message
+                if ((chain.matcher === "toThrow" || chain.matcher === "toThrowError") && chain.args.length === 0) {
+                    push(lineOf(sf, node), "C9", "toThrow() with no error type or message accepts any error");
+                }
+                // C5 always-true
+                if (chain.matcher === "toBeTruthy" && literalTruthiness(subj) === true) {
+                    push(lineOf(sf, node), "C5", "toBeTruthy on a constant truthy literal");
+                }
+                else if ((chain.matcher === "toBeFalsy" || chain.matcher === "toBeNull" || chain.matcher === "toBeUndefined") &&
+                    literalTruthiness(subj) === false) {
+                    push(lineOf(sf, node), "C5", `${chain.matcher} on a constant falsy literal`);
+                }
+                else if (EQUALITY_MATCHERS.has(chain.matcher) && isLiteral(subj) && isLiteral(arg) &&
+                    subj.getText(sf) === arg.getText(sf)) {
+                    push(lineOf(sf, node), "C5", "both sides are the same literal");
+                }
+                else if (EQUALITY_MATCHERS.has(chain.matcher) && subj && arg &&
+                    !isLiteral(subj) && !containsCall(subj) &&
+                    subj.getText(sf) === arg.getText(sf)) {
+                    // C7 self-compare
+                    push(lineOf(sf, node), "C7", "expected value is the same expression as the subject");
+                }
+                else if (EQUALITY_MATCHERS.has(chain.matcher) && arg && ts.isNumericLiteral(arg)) {
+                    // C8 exact float
+                    const v = Number(arg.text);
+                    if (!Number.isInteger(v) && v !== 0 && v !== 1) {
+                        push(lineOf(sf, node), "C8", "exact equality on a float; use toBeCloseTo");
+                    }
+                }
+                else if (EQUALITY_MATCHERS.has(chain.matcher) && isStringify(subj) && arg && ts.isStringLiteral(arg)) {
+                    // C18 sensitive equality: compares the stringified form to a literal
+                    push(lineOf(sf, node), "C18", "compares the stringified form of a value to a literal");
+                }
+            }
+            // C16 nondeterminism
+            if (!fakeTimers) {
+                const detail = c16Detail(node);
+                if (detail)
+                    push(lineOf(sf, node), "C16", detail);
+            }
+            // JS5: Testing Library async query/event used without await
+            if (isAsyncQueryCall(name) && ts.isExpressionStatement(node.parent)) {
+                push(lineOf(sf, node), "JS5", `${name} is not awaited`);
+            }
+            // JS7: assertion inside a non-awaited setTimeout/setInterval/then callback
+            {
+                const leaf = name.split(".").pop() ?? "";
+                const isTimer = name === "setTimeout" || name === "setInterval";
+                const isThen = leaf === "then" || leaf === "catch" || leaf === "finally";
+                if (isTimer || isThen) {
+                    const cb = node.arguments.find((a) => ts.isArrowFunction(a) || ts.isFunctionExpression(a));
+                    if (cb && containsAssertion(cb)) {
+                        const awaitedOrChained = !ts.isExpressionStatement(node.parent);
+                        if (isTimer && !fakeTimers) {
+                            push(lineOf(sf, node), "JS7", `assertion inside a non-awaited ${name}() callback`);
+                        }
+                        else if (isThen && !awaitedOrChained) {
+                            push(lineOf(sf, node), "JS7", `assertion inside a non-awaited .${leaf}() callback`);
+                        }
+                    }
+                }
+            }
+            // JS13: a sync RTL query used as a loose statement (result never asserted)
+            if (ts.isExpressionStatement(node.parent)) {
+                const qleaf = name.split(".").pop() ?? "";
+                if (/^(getBy|getAllBy|queryBy|queryAllBy)/.test(qleaf)) {
+                    push(lineOf(sf, node), "JS13", `${qleaf}() result is not asserted`);
+                }
+            }
+            // C37: duplicate case in it.each/test.each table
+            if (name.endsWith(".each") && node.arguments.length > 0 && ts.isArrayLiteralExpression(node.arguments[0])) {
+                const seen = new Set();
+                for (const el of node.arguments[0].elements) {
+                    const t = el.getText(sf).replace(/\s+/g, " ").trim();
+                    if (seen.has(t)) {
+                        push(lineOf(sf, node), "C37", "duplicate case in the .each table");
+                        break;
+                    }
+                    seen.add(t);
+                }
+            }
+            // D4: it.each/test.each with untitled cases (no %s/%i placeholder)
+            if (ts.isCallExpression(node.expression)) {
+                const innerName = calleeName(node.expression.expression);
+                const innerRoot = innerName.split(".")[0];
+                if (innerName.endsWith(".each") && (TEST_BLOCK_ROOTS.has(innerRoot) || SUITE_ROOTS.has(innerRoot))) {
+                    const title = node.arguments[0];
+                    if (title && ts.isStringLiteral(title) && !title.text.includes("%")) {
+                        push(lineOf(sf, node), "D4", "each cases are not titled");
+                    }
+                }
+            }
+        }
+        // JS9: assertion in a dead branch with a literal condition
+        if (ts.isIfStatement(node)) {
+            const cond = literalTruthiness(node.expression);
+            if (cond === false && containsAssertion(node.thenStatement)) {
+                push(lineOf(sf, node), "JS9", "assertion in an if(false) branch");
+            }
+            else if (cond === true && node.elseStatement && containsAssertion(node.elseStatement)) {
+                push(lineOf(sf, node), "JS9", "assertion in the else of an if(true)");
+            }
+        }
+        // JS11: try block asserts, catch swallows the failure
+        if (ts.isTryStatement(node) && node.catchClause) {
+            if (containsAssertion(node.tryBlock) && isHarmlessCatch(node.catchClause.block)) {
+                push(lineOf(sf, node), "JS11", "a failing assertion in try is swallowed by catch");
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    // CC: commented-out assertion (text scan over single-line comments)
+    // CC: a single-line `//` comment that is a commented-out assertion call.
+    // Requires the call paren (expect(/assert(/assert.x() or a .should chain) so it
+    // does not match JSDoc prose like ` * assert that ...`.
+    const lines = text.split(/\r?\n/);
+    const ccRe = /^\s*\/\/\s*(?:await\s+)?(?:expect\s*\(|assert(?:\.\w+)?\s*\(|[\w.]+\.should\b)/;
+    lines.forEach((ln, i) => {
+        if (ccRe.test(ln))
+            push(i + 1, "CC", "assertion is commented out");
+    });
+    return findings;
+}

package/dist/scan.d.ts

@@ -0,0 +1,20 @@
+import { Confidence } from "./cases.js";
+import { Finding } from "./types.js";
+export declare const TEST_EXTENSIONS: string[];
+export interface Config {
+    disable: Set<string>;
+    exclude: string[];
+    severity: Record<string, Confidence>;
+}
+export interface ScanOptions {
+    config?: Config;
+    cliDisable?: Set<string>;
+    diagnostics?: boolean;
+}
+export declare function isTestFile(file: string): boolean;
+export declare function discover(paths: string[]): string[];
+export declare function stagedFiles(): string[];
+export declare function loadConfig(start?: string): Config;
+export declare function effectiveConf(code: string, opts: ScanOptions): Confidence;
+export declare function scanFile(file: string, opts?: ScanOptions): Finding[];
+export declare function scanPaths(paths: string[], opts?: ScanOptions): Finding[];

package/dist/types.d.ts

@@ -0,0 +1,10 @@
+import { Confidence } from "./cases.js";
+export interface Finding {
+    file: string;
+    line: number;
+    code: string;
+    detail: string;
+    confidence: Confidence;
+    title: string;
+}
+export declare function makeFinding(file: string, line: number, code: string, detail?: string, confidence?: Confidence): Finding;

package/dist/types.js

@@ -0,0 +1,11 @@
+import { CASES } from "./cases.js";
+export function makeFinding(file, line, code, detail = "", confidence) {
+    return {
+        file,
+        line,
+        code,
+        detail,
+        confidence: confidence ?? CASES[code].confidence,
+        title: CASES[code].title,
+    };
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "falsegreen-js",
+  "version": "0.1.0",
+  "description": "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 scanner, sibling of falsegreen (Python).",
+  "keywords": [
+    "jest", "vitest", "mocha", "testing", "test-smells", "false-positive",
+    "static-analysis", "typescript", "javascript", "tsx", "jsx", "code-quality",
+    "ai-generated-tests"
+  ],
+  "license": "MIT",
+  "author": "Vinicius Queiroz",
+  "type": "module",
+  "engines": { "node": ">=18" },
+  "bin": { "falsegreen-js": "dist/cli.js" },
+  "main": "dist/scan.js",
+  "types": "dist/scan.d.ts",
+  "exports": {
+    ".": { "types": "./dist/scan.d.ts", "import": "./dist/scan.js" }
+  },
+  "publishConfig": { "access": "public" },
+  "files": ["dist", "CHANGELOG.md", "CREDITS.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "typescript": "^5.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "vitest": "^1.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vinicq/falsegreen-js.git"
+  },
+  "homepage": "https://github.com/vinicq/falsegreen-js#readme",
+  "bugs": { "url": "https://github.com/vinicq/falsegreen-js/issues" }
+}