Skip to content
Back to search

spirolo

Static analyzer for JavaScript and TypeScript test suites: finds tests that can pass without testing anything. Runs locally, never runs your tests.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 21 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/spirolo/spirolo with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/spirolo/spirolo'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/spirolo--spirolo/badge.svg)](/listings/spirolo--spirolo)

HTML

<a href="/listings/spirolo--spirolo"><img src="/api/listings/spirolo--spirolo/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Node 20 or newer, from your project's root:

npm install -D spirolo@alpha
npx spirolo check

No Spirolo config is needed. Install your project's dependencies first so its TypeScript configuration and imports can resolve.

The npm launcher selects a native platform package for Linux or macOS (x64 and arm64), without a postinstall download.

To build from source instead, with the current stable Rust toolchain, from this repository's root:

cargo build --release --locked -p spirolo
./target/release/spirolo check /path/to/your/project

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 217 lines
  1. <p align="center">
  2. <img src="branding/stickers/bug-in-a-jar.webp" alt="Spirolo, a purple millipede, holding a bug in a jar" width="520">
  3. </p>
  4. # Spirolo
  5. English | [简体中文](README.zh-CN.md)
  6. [![CI](https://github.com/spirolo/spirolo/actions/workflows/ci.yml/badge.svg)](https://github.com/spirolo/spirolo/actions/workflows/ci.yml)
  7. [![Licence](https://img.shields.io/github/license/spirolo/spirolo)](LICENSE)
  8. [![npm](https://img.shields.io/npm/v/spirolo)](https://www.npmjs.com/package/spirolo)
  9. Spirolo is a static analyzer for JavaScript and TypeScript test suites.
  10. It reads tests, source code and runner configuration together to find missing setup
  11. guards, untracked skips, duplicate tests and assertions that may pass without
  12. testing anything. Analysis runs locally in a Rust binary, without running your
  13. tests or sending your code anywhere.
  14. ## What Spirolo will not do
  15. - It does not run your tests or execute your code.
  16. - It does not fix or rewrite your source files.
  17. - It does not fail CI by default: findings are advisory until you raise a rule's severity.
  18. - It does not send your code anywhere: analysis needs no network access.
  19. - It covers JavaScript and TypeScript test suites only.
  20. ## Install
  21. Node 20 or newer, from your project's root:
  22. ```sh
  23. npm install -D spirolo@alpha
  24. npx spirolo check
  25. ```
  26. No Spirolo config is needed. Install your project's dependencies first so its
  27. TypeScript configuration and imports can resolve.
  28. The npm launcher selects a native platform package for Linux or macOS (x64 and arm64),
  29. without a postinstall download.
  30. To build from source instead, with the current stable Rust toolchain, from this
  31. repository's root:
  32. ```sh
  33. cargo build --release --locked -p spirolo
  34. ./target/release/spirolo check /path/to/your/project
  35. ```
  36. ## One real run
  37. Captured from the release binary built at Spirolo commit `4a8d80cd`, on
  38. [Kaneo](https://github.com/usekaneo/kaneo) at commit
  39. [`afe97be2473e0cd97fe4a63e526fef9ac4df85b0`](https://github.com/usekaneo/kaneo/tree/afe97be2473e0cd97fe4a63e526fef9ac4df85b0),
  40. with its dependencies already installed. Set `KANEO` to the path of that checkout,
  41. then run from Spirolo's source directory:
  42. ```sh
  43. ./target/release/spirolo check "$KANEO"
  44. ```
  45. Excerpt below: `[...]` marks omitted lines. The timing is from this run, not a
  46. benchmark.
  47. ```text
  48. 1754 files · 351 test files · 1797 tests (1797 vitest) · 4309 expects · 0 handlers · 35 configs · 253ms
  49. Health C (60)
  50. [...]
  51. ● fail-closed-setup (10 files, 19 findings) · advisory: 19/19 (UNADJUDICATED)
  52. apps/api/vitest.config.ts (2)
  53. :0 setup does not guard the console (no throwing console.error/warn spy or fail-on-console package)
  54. :0 setup does not restore mocks between tests (no restoreMocks or afterEach restoreAllMocks)
  55. [...]
  56. 34 findings in 3 of 16 rules · 0 warn · 0 error · 34 info · exit 0
  57. hidden 1226 findings: 1211 experimental (gate-truth 11, unused-mock 3, flake-candidate 1, untested-hotspot 1196), 15 from DROPPED or FAIL rules (weak-assertion 15); spirolo check --all shows them
  58. note no churn input: untested-hotspot ranks by complexity × weakness alone. Save `git log --numstat --format= --since=180.days` to a file and pass it with `--churn <file>` or name it in `inputs.churn`
  59. ```
  60. This run reported missing setup guards, absence-only assertions and a possible
  61. duplicate. It did not execute Kaneo's tests or verify each finding. The command
  62. exited successfully because these findings are advisory. The hidden count includes
  63. experimental hotspot rankings without churn data; it is not a count of confirmed
  64. bugs.
  65. ## What it finds
  66. The default report shows these advisory rules:
  67. | Rule | What to inspect |
  68. | --- | --- |
  69. | `absence-anchor` | A test checks that something is absent without checking that the expected content rendered. |
  70. | `dead-skip` | A test is skipped without a linked issue, or focused so other tests will not run. |
  71. | `duplicate-test` | Test bodies and their modeled setup look equivalent. Check whether they cover different behavior before deleting either. |
  72. | `fail-closed-setup` | Runner setup lacks guards for mock cleanup, console errors or unhandled requests. |
  73. `check --all` also shows experimental rules and rules whose measurements failed or
  74. were dropped. These include merge-gate checks, static flake candidates, unused
  75. mocks and source modules ranked by churn, complexity and test strength. Use
  76. `spirolo explain <rule>` to read a rule's claim and measured status.
  77. ### Why another test tool?
  78. Test lint plugins check patterns in test code. Coverage reports tell you what ran.
  79. Mutation tools such as Stryker check whether tests detect changes to production
  80. code. Spirolo adds a view across tests, imports, setup and runner configuration,
  81. and can read existing coverage, mutation and run reports. Keep running your tests
  82. and using those tools: a static finding answers a different question.
  83. The [tooling comparison](docs/landscape.md) explains that division of work.
  84. ## How far to trust it
  85. **No rule is proven yet.** The measurements below record how often sampled findings
  86. were judged correct, not how many bugs Spirolo can find in your project.
  87. - **Advisory:** shown by default once a rule has at least 15 decided findings and
  88. measured precision of at least 0.80. These findings report at `info`.
  89. - **Experimental:** findings appear only with `--all` unless you opt the rule in.
  90. The evidence is too limited or the measured precision is below the advisory floor.
  91. - **FAIL or DROPPED:** findings appear only with `--all` and never gate, even with
  92. a severity override.
  93. - **Proven:** reserved for a rule that passes the measurement bar and a fresh
  94. held-out check. None has done so.
  95. Today, findings do not fail a command by default. To make a rule gate, set its
  96. severity to `warn` or `error` in `.spirolorc.jsonc`, subject to the rule's allowed
  97. severities. For example:
  98. ```jsonc
  99. { "rules": { "dead-skip": { "severity": "warn" } } }
  100. ```
  101. [Rule tiers](docs/tiers.md) explains the thresholds, labels, exit codes and override
  102. limits. `spirolo rule-status` prints the measurements embedded in your binary.
  103. ### Measured precision
  104. This table is generated from the [embedded measurement data](corpus/rule-status.json),
  105. using public repositories only. A perfect result on a small sample is not proof;
  106. the confidence intervals show the uncertainty. These are measurements at the
  107. recorded commit, not a new evaluation of every later change.
  108. `n/a` means no findings were decided, so there is no precision estimate.
  109. <!-- precision:start -->
  110. Measured at spirolo commit `939f0af519fd50318e092700b74094b71cfeca23` across 40 OSS dev entries.
  111. Advisory: at least 15 decided and shown precision at least 0.80.
  112. | Rule | Tier | Status | True / decided | Precision | 95% Wilson interval | Measured entries |
  113. | --- | --- | --- | ---: | ---: | --- | ---: |
  114. | absence-anchor | advisory | UNADJUDICATED | 28 / 28 | 1.000 | 0.879–1.000 | 16 |
  115. | dead-skip | advisory | UNADJUDICATED | 39 / 39 | 1.000 | 0.910–1.000 | 21 |
  116. | duplicate-test | advisory | UNADJUDICATED | 15 / 18 | 0.833 | 0.608–0.942 | 19 |
  117. | fail-closed-setup | advisory | UNADJUDICATED | 19 / 19 | 1.000 | 0.832–1.000 | 10 |
  118. | flake-candidate | experimental | INSUFFICIENT | 3 / 6 | 0.500 | 0.188–0.812 | 7 |
  119. | gate-truth | experimental | UNADJUDICATED | 12 / 18 | 0.667 | 0.437–0.837 | 8 |
  120. | untested-hotspot | experimental | UNADJUDICATED | 5 / 16 | 0.313 | 0.142–0.556 | 40 |
  121. | unused-mock | experimental | INSUFFICIENT | 0 / 0 | n/a | n/a | 1 |
  122. | data-layer-mock | hidden | DROPPED | 0 / 0 | n/a | n/a | 0 |
  123. | flake-observed | hidden | FAIL | 39 / 52 | 0.750 | 0.618–0.848 | 4 |
  124. | generator-walk | hidden | DROPPED | 0 / 0 | n/a | n/a | 0 |
  125. | handler-drift | hidden | DROPPED | 0 / 0 | n/a | n/a | 0 |
  126. | orphan-test | hidden | DROPPED | 4 / 14 | 0.286 | 0.117–0.546 | 12 |
  127. | redundant-test | hidden | DROPPED | 0 / 12 | 0.000 | 0.000–0.243 | 5 |
  128. | stale-snapshot | hidden | DROPPED | 0 / 0 | n/a | n/a | 3 |
  129. | weak-assertion | hidden | DROPPED | 12 / 34 | 0.353 | 0.215–0.521 | 17 |
  130. <!-- precision:end -->
  131. ## Where it runs
  132. The native package targets are Linux with glibc and macOS, on x64 and arm64.
  133. Windows and Alpine/musl are outside the alpha's targets. The native binary needs
  134. neither Node nor network access for analysis.
  135. The measured scope is JavaScript and TypeScript React projects using Vitest or
  136. Jest. Spirolo also reads Playwright configuration and test patterns; this does not
  137. make every framework or configuration a measured target.
  138. Use the CLI locally, [Markdown summaries or GitHub annotations in CI](docs/ci-reports.md),
  139. or [MCP](docs/mcp.md) in an agent client. JSON and SARIF reports are available with
  140. `--format json` and `--format sarif`. A VS Code extension using the same binary can
  141. be [packaged and installed locally](docs/release.md).
  142. ## Scope
  143. Spirolo does not run tests, launch mutation engines, collect coverage, generate tests
  144. or host run history. It reads artifacts you already have. Missing artifacts are
  145. reported as unverified context, not as evidence that the suite works.
  146. A static flake candidate is not an observed flaky test. A duplicate finding is a
  147. reason to inspect the tests, not permission to delete them. The provisional health
  148. score is a summary of signals, not a guarantee of correctness.
  149. Vue, Cypress, other languages and arbitrary non-React frameworks are outside the
  150. measured scope.
  151. ## Status and limits
  152. **Version `0.1.0-alpha.2`: advisory alpha.** It is on npm as `spirolo@alpha`; the
  153. VS Code extension is not published yet. Before 1.0, any alpha may change commands, output
  154. and rule behaviour; the [changelog](CHANGELOG.md) lists every change.
  155. Static analysis can miss dynamic configuration and patterns it does not model.
  156. If a TypeScript configuration cannot load, Spirolo reports module-resolution problems
  157. and marks affected findings as unreliable. Install missing dependencies and resolve
  158. the configuration warning before relying on those rows.
  159. The human report caps displayed files and findings. `spirolo check --rule <rule> --all`
  160. shows the full report for that rule, including experimental or dropped findings.
  161. Review the evidence before opting a rule into CI.
  162. Contributions are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md).
  163. For vulnerability reports, see [SECURITY.md](SECURITY.md).
  164. ## Licence
  165. [Apache 2.0](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.