sniff-qa 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/LICENSE +172 -0
  2. package/README.md +581 -0
  3. package/dist/accessibility-UNJB57T6.js +93 -0
  4. package/dist/accessibility-UNJB57T6.js.map +1 -0
  5. package/dist/anthropic-api-MRDZ7BJA.js +33 -0
  6. package/dist/anthropic-api-MRDZ7BJA.js.map +1 -0
  7. package/dist/chunk-623BAIU2.js +73 -0
  8. package/dist/chunk-623BAIU2.js.map +1 -0
  9. package/dist/chunk-CBDOJUXB.js +157 -0
  10. package/dist/chunk-CBDOJUXB.js.map +1 -0
  11. package/dist/chunk-IXDUD2UG.js +14 -0
  12. package/dist/chunk-IXDUD2UG.js.map +1 -0
  13. package/dist/chunk-MMISGY2Q.js +52 -0
  14. package/dist/chunk-MMISGY2Q.js.map +1 -0
  15. package/dist/chunk-ZM6MGWO4.js +49 -0
  16. package/dist/chunk-ZM6MGWO4.js.map +1 -0
  17. package/dist/ci-2MVD2ISE.js +52 -0
  18. package/dist/ci-2MVD2ISE.js.map +1 -0
  19. package/dist/claude-code-F722EIIC.js +42 -0
  20. package/dist/claude-code-F722EIIC.js.map +1 -0
  21. package/dist/claude-exploration-provider-QJH6IPYU.js +126 -0
  22. package/dist/claude-exploration-provider-QJH6IPYU.js.map +1 -0
  23. package/dist/cli/index.d.ts +1 -0
  24. package/dist/cli/index.js +72 -0
  25. package/dist/cli/index.js.map +1 -0
  26. package/dist/cross-reference-MHNPSLEN.js +218 -0
  27. package/dist/cross-reference-MHNPSLEN.js.map +1 -0
  28. package/dist/element-extractor-OZTFBVKZ.js +250 -0
  29. package/dist/element-extractor-OZTFBVKZ.js.map +1 -0
  30. package/dist/errors-RFEOR527.js +7 -0
  31. package/dist/errors-RFEOR527.js.map +1 -0
  32. package/dist/flakiness-OVC7KGN2.js +11 -0
  33. package/dist/flakiness-OVC7KGN2.js.map +1 -0
  34. package/dist/formatter-HC3LT3VH.js +146 -0
  35. package/dist/formatter-HC3LT3VH.js.map +1 -0
  36. package/dist/framework-detector-ISSM2Q2I.js +95 -0
  37. package/dist/framework-detector-ISSM2Q2I.js.map +1 -0
  38. package/dist/generator-OZY3HMJW.js +7 -0
  39. package/dist/generator-OZY3HMJW.js.map +1 -0
  40. package/dist/index.d.ts +212 -0
  41. package/dist/index.js +13 -0
  42. package/dist/index.js.map +1 -0
  43. package/dist/init-75MMIW4A.js +66 -0
  44. package/dist/init-75MMIW4A.js.map +1 -0
  45. package/dist/json-YDWEB33Q.js +8 -0
  46. package/dist/json-YDWEB33Q.js.map +1 -0
  47. package/dist/junit-GL44ATRR.js +52 -0
  48. package/dist/junit-GL44ATRR.js.map +1 -0
  49. package/dist/loader-QII5CZSX.js +161 -0
  50. package/dist/loader-QII5CZSX.js.map +1 -0
  51. package/dist/mcp/server.d.ts +3 -0
  52. package/dist/mcp/server.js +171 -0
  53. package/dist/mcp/server.js.map +1 -0
  54. package/dist/model-SRPWXU63.js +92 -0
  55. package/dist/model-SRPWXU63.js.map +1 -0
  56. package/dist/page-hooks-DOZWXF7Z.js +13 -0
  57. package/dist/page-hooks-DOZWXF7Z.js.map +1 -0
  58. package/dist/page-state-extractor-GYYLYRFR.js +75 -0
  59. package/dist/page-state-extractor-GYYLYRFR.js.map +1 -0
  60. package/dist/performance-FBUGBRB3.js +134 -0
  61. package/dist/performance-FBUGBRB3.js.map +1 -0
  62. package/dist/persistence-RHUFBQAY.js +86 -0
  63. package/dist/persistence-RHUFBQAY.js.map +1 -0
  64. package/dist/prompt-builder-D3FBH534.js +53 -0
  65. package/dist/prompt-builder-D3FBH534.js.map +1 -0
  66. package/dist/provider-7IHXYR6V.js +13 -0
  67. package/dist/provider-7IHXYR6V.js.map +1 -0
  68. package/dist/registry-NB5CZB6W.js +43 -0
  69. package/dist/registry-NB5CZB6W.js.map +1 -0
  70. package/dist/repo-analyzer-4OURSITY.js +49 -0
  71. package/dist/repo-analyzer-4OURSITY.js.map +1 -0
  72. package/dist/report-E2JZMQED.js +61 -0
  73. package/dist/report-E2JZMQED.js.map +1 -0
  74. package/dist/response-parser-PUGNWF7S.js +46 -0
  75. package/dist/response-parser-PUGNWF7S.js.map +1 -0
  76. package/dist/route-discoverer-QBZCRQLJ.js +304 -0
  77. package/dist/route-discoverer-QBZCRQLJ.js.map +1 -0
  78. package/dist/runner-MS2SNTMR.js +153 -0
  79. package/dist/runner-MS2SNTMR.js.map +1 -0
  80. package/dist/runner-Z4I2YVVM.js +237 -0
  81. package/dist/runner-Z4I2YVVM.js.map +1 -0
  82. package/dist/source-D5KLH46F.js +896 -0
  83. package/dist/source-D5KLH46F.js.map +1 -0
  84. package/dist/unified-CQU7PSNJ.js +275 -0
  85. package/dist/unified-CQU7PSNJ.js.map +1 -0
  86. package/dist/update-baselines-MDTCFO2U.js +71 -0
  87. package/dist/update-baselines-MDTCFO2U.js.map +1 -0
  88. package/dist/visual-ZSQPDE7A.js +125 -0
  89. package/dist/visual-ZSQPDE7A.js.map +1 -0
  90. package/dist/workflow-template-3KFPCVIC.js +119 -0
  91. package/dist/workflow-template-3KFPCVIC.js.map +1 -0
  92. package/package.json +95 -0
package/README.md ADDED
@@ -0,0 +1,581 @@
1
+ <picture>
2
+ <source media="(prefers-color-scheme: dark)" srcset=".github/assets/logo-dark.svg">
3
+ <source media="(prefers-color-scheme: light)" srcset=".github/assets/logo-light.svg">
4
+ <img alt="Sniff - open source AI-powered QA testing tool with source scanning, accessibility audits, visual regression, performance budgets, and AI exploration" src=".github/assets/logo-light.svg" width="100%">
5
+ </picture>
6
+
7
+ <p align="center">
8
+ <a href="https://www.npmjs.com/package/sniff-qa"><img src="https://img.shields.io/npm/v/sniff-qa?color=ef4444&logo=npm&label=npm&style=flat-square" alt="npm"></a>
9
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache_2.0-ef4444?style=flat-square" alt="License"></a>
10
+ <a href="https://github.com/Aboudjem/sniff/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Aboudjem/sniff/ci.yml?style=flat-square&label=CI" alt="CI"></a>
11
+ <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A522-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node"></a>
12
+ <a href="https://github.com/Aboudjem/sniff/stargazers"><img src="https://img.shields.io/github/stars/Aboudjem/sniff?style=flat-square&color=ef4444" alt="Stars"></a>
13
+ </p>
14
+
15
+ <p align="center">
16
+ <b>One command. Eight checks. Zero config.</b><br/>
17
+ <sub>Source bugs, dead links, API endpoints, accessibility, visual regression, performance, AI exploration, and cross-referencing. All in one pass.</sub>
18
+ </p>
19
+
20
+ ---
21
+
22
+ <br/>
23
+
24
+ ## What is this?
25
+
26
+ You ship features. But did you actually *test* them?
27
+
28
+ **sniff** is an AI-powered QA tool that scans your project for real problems: leftover debugger statements, dead links, API endpoint issues, accessibility violations, visual regressions, performance budget breaches, and adversarial edge cases. It runs eight checks in a single command and cross-references source code with browser behavior for high-confidence findings.
29
+
30
+ ```bash
31
+ npx sniff-qa
32
+ ```
33
+
34
+ That's it. No config files. No signup. No API keys. It just works.
35
+
36
+ <br/>
37
+
38
+ ### Key facts
39
+
40
+ - **What:** Open source AI-powered QA testing tool that runs 8 checks in a single command: source scanning (6 rule categories + dead links + API endpoint discovery), accessibility audits, visual regression, performance budgets, AI-driven exploration, and source/browser cross-referencing
41
+ - **Who it's for:** Frontend and full-stack developers who want automated QA without configuring multiple tools
42
+ - **How it works:** Uses Playwright for browser automation, axe-core for WCAG accessibility, Lighthouse for performance, pixelmatch for visual diffs, and Anthropic Claude for adversarial AI exploration
43
+ - **Install:** `npx sniff-qa` (zero config, no signup, no API keys required for base checks)
44
+ - **Comparable to:** Combines Lighthouse CI + Pa11y + BackstopJS into one tool, plus source code scanning and AI-driven edge case discovery that no other tool offers
45
+ - **Unique:** First QA tool with native MCP (Model Context Protocol) integration. Flakiness quarantine system isolates non-deterministic test results automatically
46
+
47
+ <br/>
48
+
49
+ ## Quick start
50
+
51
+ | Step | Action |
52
+ |:----:|:-------|
53
+ | **1** | Run a source scan: `npx sniff-qa` |
54
+ | **2** | Run the full audit: `npx sniff-qa --url http://localhost:3000` |
55
+ | **3** | Read the report and fix what matters |
56
+
57
+ The source scan finishes in seconds. The full audit adds accessibility, visual regression, performance, and AI exploration on top of it.
58
+
59
+ > [!TIP]
60
+ > Drop your URL in `sniff.config.ts` once and you can just run `sniff` for the full audit every time.
61
+
62
+ <br/>
63
+
64
+ ## The three modes
65
+
66
+ ```mermaid
67
+ graph LR
68
+ A["🔍 Quick Scan<br/><sub>npx sniff-qa</sub>"] --> B["Source bugs only<br/><sub>No browser needed</sub>"]
69
+ C["🛡️ Full Audit<br/><sub>npx sniff-qa --url URL</sub>"] --> D["All 8 checks<br/><sub>Source + Browser + Xref</sub>"]
70
+ E["🏗️ CI Mode<br/><sub>npx sniff-qa --url URL --ci</sub>"] --> F["Deterministic<br/><sub>Skips AI explorer</sub>"]
71
+
72
+ style A fill:#fef2f2,stroke:#ef4444,color:#7f1d1d
73
+ style B fill:#fee2e2,stroke:#ef4444,color:#7f1d1d
74
+ style C fill:#fef2f2,stroke:#ef4444,color:#7f1d1d
75
+ style D fill:#fee2e2,stroke:#ef4444,color:#7f1d1d
76
+ style E fill:#fef2f2,stroke:#ef4444,color:#7f1d1d
77
+ style F fill:#fee2e2,stroke:#ef4444,color:#7f1d1d
78
+ ```
79
+
80
+ ```bash
81
+ npx sniff-qa # quick scan (no browser)
82
+ npx sniff-qa --url http://localhost:3000 # full audit (everything)
83
+ npx sniff-qa --url http://localhost:3000 --ci # ci mode (skips AI explorer)
84
+ ```
85
+
86
+ CI mode auto-skips the AI explorer because it is non-deterministic. Everything else runs exactly the same.
87
+
88
+ <br/>
89
+
90
+ ## What it checks
91
+
92
+ | | Check | Example finding | Details |
93
+ |:--|:------|:----------------|:--------|
94
+ | 📄 | **Source code** | `debugger` statement in `handler.ts:42` | Leftover debugger, placeholder text, hardcoded URLs, broken imports, TODO/FIXME |
95
+ | 🔗 | **Dead links** | Broken link `./guide.md` in `README.md:28` | Validates internal file refs, external URLs (HTTP HEAD with retry), and anchor links. Catches 404s before your users do |
96
+ | 🛣️ | **API endpoints** | `POST /users` has no input validation | Discovers routes from Express, Fastify, Hono, Next.js, SvelteKit, tRPC, and GraphQL. Flags missing error handling, auth, and hardcoded secrets |
97
+ | ♿ | **Accessibility** | Missing form label on `/login` | WCAG 2.x violations via [axe-core](https://github.com/dequelabs/axe-core) with exact fix guidance |
98
+ | 🖼 | **Visual regression** | `/pricing` changed 2.3% of pixels | Local pixel diffing via [pixelmatch](https://github.com/mapbox/pixelmatch). Commit baselines to track changes |
99
+ | ⚡ | **Performance** | LCP 4200ms on `/dashboard` (budget: 2500ms) | [Lighthouse](https://developer.chrome.com/docs/lighthouse) budgets for LCP, FCP, TTI |
100
+ | 🤖 | **AI explorer** | XSS in `/signup` email field crashes app | Roams your app, fills forms with adversarial inputs, reports crashes and console errors |
101
+ | 🔀 | **Cross-reference** | `console.log` in source confirmed at runtime | Correlates source findings with browser evidence. Corroborated issues get bumped severity and HIGH confidence tags |
102
+
103
+ <br/>
104
+
105
+ ## How it works
106
+
107
+ <picture>
108
+ <source media="(prefers-color-scheme: dark)" srcset=".github/assets/pipeline-dark.svg">
109
+ <source media="(prefers-color-scheme: light)" srcset=".github/assets/pipeline-light.svg">
110
+ <img alt="Sniff pipeline showing 8 checks flowing through source scanner, browser runner, cross-reference engine, and report output" src=".github/assets/pipeline-light.svg" width="100%">
111
+ </picture>
112
+
113
+ Your code goes in. A report with actionable findings comes out. When you provide a URL, sniff also runs browser checks and cross-references source findings with runtime behavior for high-confidence results. You don't configure anything.
114
+
115
+ <br/>
116
+
117
+ ## Compared to
118
+
119
+ | | **Sniff** | Lighthouse CI | Pa11y | BackstopJS |
120
+ |:--|:--:|:--:|:--:|:--:|
121
+ | Source scanning | ✅ | ❌ | ❌ | ❌ |
122
+ | Dead link checking | ✅ | ❌ | ❌ | ❌ |
123
+ | API endpoint discovery | ✅ | ❌ | ❌ | ❌ |
124
+ | Accessibility | ✅ | partial | ✅ | ❌ |
125
+ | Visual regression | ✅ | ❌ | ❌ | ✅ |
126
+ | Performance | ✅ | ✅ | ❌ | ❌ |
127
+ | AI exploration | ✅ | ❌ | ❌ | ❌ |
128
+ | Cross-reference engine | ✅ | ❌ | ❌ | ❌ |
129
+ | Flakiness quarantine | ✅ | ❌ | ❌ | ❌ |
130
+ | Single command | ✅ | ❌ | ❌ | ❌ |
131
+ | MCP server | ✅ | ❌ | ❌ | ❌ |
132
+ | Zero config | ✅ | ❌ | ❌ | ❌ |
133
+
134
+ > [!IMPORTANT]
135
+ > Sniff is the **first QA tool with native MCP integration**. Your AI editor can trigger scans, read results, and fix issues without you switching context.
136
+
137
+ <br/>
138
+
139
+ ## Source scanning rules
140
+
141
+ Sniff ships 6 rule categories that run on every scan. No browser needed.
142
+
143
+ | Rule | ID | Severity | What it catches |
144
+ |:-----|:---|:---------|:----------------|
145
+ | Debug statements | `debug-console-log`, `debug-debugger` | medium / high | `console.log`, `console.debug`, `debugger` left in production code |
146
+ | Placeholder text | `placeholder-lorem`, `placeholder-todo`, `placeholder-fixme`, `placeholder-tbd` | high / medium | Lorem ipsum, TODO, FIXME, TBD markers |
147
+ | Hardcoded URLs | `hardcoded-localhost`, `hardcoded-127` | medium | `http://localhost:*` and `http://127.0.0.1:*` in non-test files |
148
+ | Broken imports | `broken-import` | medium | Relative imports that don't resolve to a file (with TS extension mapping) |
149
+ | Dead links | `dead-link-internal`, `dead-link-external`, `dead-link-anchor` | high / medium / low | Broken file references, 404 external URLs, missing anchor targets |
150
+ | API endpoints | `api-no-error-handling`, `api-no-validation`, `api-no-auth`, `api-hardcoded-secret` | critical / medium / low | Route handlers missing try/catch, input validation, auth, or containing hardcoded secrets |
151
+
152
+ ### Dead link checker
153
+
154
+ Scans `.md`, `.html`, `.jsx`, `.tsx`, `.vue`, `.svelte`, and `.astro` files for links and validates them:
155
+
156
+ - **Internal links:** Checks the target file exists (with extension resolution and index file fallback)
157
+ - **External links:** Sends HTTP HEAD requests with timeout, retry, and GET fallback for servers that reject HEAD
158
+ - **Anchor links:** Validates `#section` references against markdown headings and HTML `id`/`name` attributes
159
+ - **Smart skipping:** Ignores `mailto:`, `tel:`, `data:`, `javascript:`, and template variables
160
+
161
+ ```
162
+ HIGH README.md:28 Broken internal link: ./missing-guide.md
163
+ MED docs/api.md:15 HTTP 404: https://example.com/old-endpoint
164
+ MED CONTRIBUTING.md:8 Anchor #setup-guide not found in ./README.md
165
+ ```
166
+
167
+ ### API endpoint discovery
168
+
169
+ Automatically discovers API routes from 8 frameworks:
170
+
171
+ | Framework | Detection method |
172
+ |:----------|:----------------|
173
+ | Express | `app.get()`, `router.post()`, etc. |
174
+ | Fastify | `fastify.get()`, `fastify.post()`, etc. |
175
+ | Hono | `app.get()` with `new Hono()` detection |
176
+ | Next.js App Router | `app/**/route.ts` with exported `GET`/`POST` handlers |
177
+ | Next.js Pages Router | `pages/api/**/*.ts` |
178
+ | SvelteKit | `routes/**/+server.ts` |
179
+ | tRPC | `publicProcedure.query()` / `.mutation()` |
180
+ | GraphQL | `type Query { }` / `type Mutation { }` definitions |
181
+
182
+ For each endpoint, sniff checks for:
183
+ - Missing error handling (no try/catch or error middleware)
184
+ - Missing input validation on POST/PUT/PATCH routes (no zod, joi, yup, etc.)
185
+ - Missing auth middleware on non-public routes
186
+ - Hardcoded secrets (API keys, tokens, Stripe keys, GitHub tokens)
187
+
188
+ ```
189
+ CRIT src/routes.ts:12 Hardcoded Stripe key in POST /checkout handler
190
+ MED src/api.ts:5 POST /users has no input validation
191
+ MED src/api.ts:18 GET /admin/data has no error handling
192
+ LOW src/api.ts:25 GET /admin/data has no visible auth middleware
193
+ INFO Discovered 6 API endpoints (express: 4, nextjs-app: 2)
194
+ ```
195
+
196
+ ### Cross-reference engine
197
+
198
+ When you run sniff with `--url`, the cross-reference engine correlates source code findings with browser runtime behavior. Findings confirmed in both layers get bumped severity and a HIGH confidence tag.
199
+
200
+ **5 correlation strategies:**
201
+
202
+ | Source finding | Browser evidence | Correlation |
203
+ |:---------------|:-----------------|:------------|
204
+ | Broken import / dead link | 404 network request | `broken-import-to-404` |
205
+ | `console.log` statement | Console output captured | `console-log-to-runtime` |
206
+ | Hardcoded localhost URL | Network request to that URL | `hardcoded-url-to-network` |
207
+ | Missing label / a11y issue | axe-core violation | `source-a11y-to-axe` |
208
+ | Placeholder text in source | Text visible on page | `placeholder-to-runtime` |
209
+
210
+ ```
211
+ CORROBORATED (source + browser evidence)
212
+ src/handler.ts:42 console.log("debug data")
213
+ Source: debug-console-log rule triggered
214
+ Browser: console.log output captured at /dashboard
215
+ Confidence: HIGH (confirmed in both layers)
216
+ ```
217
+
218
+ <br/>
219
+
220
+ ## Architecture
221
+
222
+ <picture>
223
+ <source media="(prefers-color-scheme: dark)" srcset=".github/assets/architecture-dark.svg">
224
+ <source media="(prefers-color-scheme: light)" srcset=".github/assets/architecture-light.svg">
225
+ <img alt="Sniff architecture showing source scanner, browser runner, cross-reference engine, and report engine" src=".github/assets/architecture-light.svg" width="100%">
226
+ </picture>
227
+
228
+ <br/>
229
+
230
+ ## Example output
231
+
232
+ <picture>
233
+ <source media="(prefers-color-scheme: dark)" srcset=".github/assets/report-dark.svg">
234
+ <source media="(prefers-color-scheme: light)" srcset=".github/assets/report-light.svg">
235
+ <img alt="Sniff terminal output showing source findings, browser results, and cross-referenced corroborated findings" src=".github/assets/report-light.svg" width="100%">
236
+ </picture>
237
+
238
+ <br/>
239
+
240
+ ## Works with your stack
241
+
242
+ No config needed. Sniff auto-detects your framework from `package.json` and source files.
243
+
244
+ <table>
245
+ <tr>
246
+ <td align="center" width="16%"><b>⚛️ React</b></td>
247
+ <td align="center" width="16%"><b>▲ Next.js</b></td>
248
+ <td align="center" width="16%"><b>💚 Vue</b></td>
249
+ <td align="center" width="16%"><b>🔶 Svelte</b></td>
250
+ <td align="center" width="16%"><b>🅰️ Angular</b></td>
251
+ <td align="center" width="16%"><b>🌐 Vanilla</b></td>
252
+ </tr>
253
+ <tr>
254
+ <td align="center">JSX / TSX</td>
255
+ <td align="center">App Router</td>
256
+ <td align="center">SFC</td>
257
+ <td align="center">Components</td>
258
+ <td align="center">Templates</td>
259
+ <td align="center">HTML / CSS</td>
260
+ </tr>
261
+ </table>
262
+
263
+ <br/>
264
+
265
+ ## 🔌 Use with your AI editor
266
+
267
+ Sniff ships an MCP server. Pick your tool and copy the snippet.
268
+
269
+ <details>
270
+ <summary><b>Claude Code</b></summary>
271
+
272
+ ```bash
273
+ claude mcp add sniff-qa npx sniff-qa --mcp
274
+ ```
275
+
276
+ Or `.mcp.json`:
277
+
278
+ ```json
279
+ {
280
+ "mcpServers": {
281
+ "sniff-qa": { "command": "npx", "args": ["sniff-qa", "--mcp"] }
282
+ }
283
+ }
284
+ ```
285
+
286
+ </details>
287
+
288
+ <details>
289
+ <summary><b>Cursor</b></summary>
290
+
291
+ `~/.cursor/mcp.json` or `.cursor/mcp.json`:
292
+
293
+ ```json
294
+ {
295
+ "mcpServers": {
296
+ "sniff-qa": {
297
+ "type": "stdio",
298
+ "command": "npx",
299
+ "args": ["sniff-qa", "--mcp"]
300
+ }
301
+ }
302
+ }
303
+ ```
304
+
305
+ </details>
306
+
307
+ <details>
308
+ <summary><b>Windsurf</b></summary>
309
+
310
+ `~/.codeium/windsurf/mcp_config.json`:
311
+
312
+ ```json
313
+ {
314
+ "mcpServers": {
315
+ "sniff-qa": { "command": "npx", "args": ["sniff-qa", "--mcp"] }
316
+ }
317
+ }
318
+ ```
319
+
320
+ </details>
321
+
322
+ <details>
323
+ <summary><b>Codex CLI</b></summary>
324
+
325
+ ```bash
326
+ codex mcp add sniff-qa -- npx -y sniff-qa --mcp
327
+ ```
328
+
329
+ Or add to `~/.codex/config.toml`:
330
+
331
+ ```toml
332
+ [mcp_servers.sniff-qa]
333
+ command = "npx"
334
+ args = ["-y", "sniff-qa", "--mcp"]
335
+ ```
336
+
337
+ </details>
338
+
339
+ <details>
340
+ <summary><b>Gemini CLI</b></summary>
341
+
342
+ `~/.gemini/mcp_config.json`:
343
+
344
+ ```json
345
+ {
346
+ "mcpServers": {
347
+ "sniff-qa": { "command": "npx", "args": ["sniff-qa", "--mcp"] }
348
+ }
349
+ }
350
+ ```
351
+
352
+ </details>
353
+
354
+ <details>
355
+ <summary><b>Continue.dev</b></summary>
356
+
357
+ `.continue/mcpServers/sniff-qa.yaml`:
358
+
359
+ ```yaml
360
+ mcpServers:
361
+ sniff-qa:
362
+ command: npx
363
+ args: [sniff-qa, --mcp]
364
+ type: stdio
365
+ ```
366
+
367
+ </details>
368
+
369
+ <details>
370
+ <summary><b>VS Code + Copilot</b></summary>
371
+
372
+ Add to `.vscode/mcp.json`:
373
+
374
+ ```json
375
+ {
376
+ "servers": {
377
+ "sniff-qa": {
378
+ "type": "stdio",
379
+ "command": "npx",
380
+ "args": ["-y", "sniff-qa", "--mcp"]
381
+ }
382
+ }
383
+ }
384
+ ```
385
+
386
+ </details>
387
+
388
+ <details>
389
+ <summary><b>OpenClaw</b></summary>
390
+
391
+ ```bash
392
+ clawhub install sniff-qa
393
+ ```
394
+
395
+ Or add to `~/.openclaw/openclaw.json`:
396
+
397
+ ```json
398
+ {
399
+ "mcpServers": {
400
+ "sniff-qa": {
401
+ "command": "npx",
402
+ "args": ["-y", "sniff-qa", "--mcp"]
403
+ }
404
+ }
405
+ }
406
+ ```
407
+
408
+ </details>
409
+
410
+ Once configured, ask: *"Scan this project for issues"* or *"Check accessibility on localhost:3000"*.
411
+
412
+ **MCP tools exposed:** `sniff_scan` (source), `sniff_run` (browser), `sniff_report` (last results).
413
+
414
+ <br/>
415
+
416
+ ## Install
417
+
418
+ ```bash
419
+ npm install -D sniff-qa
420
+ ```
421
+
422
+ ```json
423
+ {
424
+ "scripts": {
425
+ "qa": "sniff --url http://localhost:3000"
426
+ }
427
+ }
428
+ ```
429
+
430
+ Then run `npm run qa`. Requires Node.js 22+. Playwright browsers install automatically the first time.
431
+
432
+ <br/>
433
+
434
+ ## 🏗️ CI integration
435
+
436
+ ```bash
437
+ npx sniff-qa ci
438
+ ```
439
+
440
+ Generates `.github/workflows/sniff.yml` with Playwright caching, JUnit output, flakiness quarantine, and report artifacts.
441
+
442
+ **Flakiness quarantine.** Tests that fail 3 of 5 runs get quarantined. They still run, still appear in reports, but won't block your pipeline.
443
+
444
+ <br/>
445
+
446
+ ## All commands
447
+
448
+ <details>
449
+ <summary><b>📋 Full CLI reference</b></summary>
450
+ <br/>
451
+
452
+ ```
453
+ sniff quick scan (source only)
454
+ sniff --url <url> full audit (everything)
455
+ sniff --url <url> --ci ci mode (no AI explorer)
456
+
457
+ sniff init scaffold sniff.config.ts
458
+ sniff ci generate .github/workflows/sniff.yml
459
+ sniff report show last results
460
+ sniff update-baselines accept current screenshots as baselines
461
+ ```
462
+
463
+ ### Flags (all optional)
464
+
465
+ | Flag | Effect |
466
+ |:--|:--|
467
+ | `--no-explore` | Skip AI explorer in full mode |
468
+ | `--no-browser` | Force source-only even when URL is set |
469
+ | `--max-steps <n>` | Cap exploration steps (default: 50) |
470
+ | `--no-headless` | Show the browser window |
471
+ | `--format html,json,junit` | Choose report formats |
472
+ | `--fail-on critical,high` | Severities that exit non-zero |
473
+ | `--track-flakes` | Enable flakiness detection |
474
+ | `--json` | Machine-readable output |
475
+
476
+ </details>
477
+
478
+ <br/>
479
+
480
+ ## Configuration
481
+
482
+ <details>
483
+ <summary><b>⚙️ sniff.config.ts reference</b></summary>
484
+ <br/>
485
+
486
+ Optional. Drop `sniff.config.ts` in your project root:
487
+
488
+ ```typescript
489
+ import { defineConfig } from 'sniff-qa';
490
+
491
+ export default defineConfig({
492
+ browser: {
493
+ baseUrl: 'http://localhost:3000',
494
+ },
495
+ viewports: [
496
+ { name: 'mobile', width: 375, height: 667 },
497
+ { name: 'desktop', width: 1280, height: 720 },
498
+ ],
499
+ performance: {
500
+ budgets: { lcp: 2500, fcp: 1800, tti: 3800 },
501
+ },
502
+ visual: { threshold: 0.1 },
503
+ exploration: { maxSteps: 50 },
504
+ flakiness: { windowSize: 5, threshold: 3 },
505
+
506
+ // Dead link checker (new in v0.2)
507
+ deadLinks: {
508
+ checkExternal: true, // validate external URLs via HTTP
509
+ timeout: 5000, // ms per request
510
+ retries: 2, // retry failed requests
511
+ ignorePatterns: [], // regex patterns to skip
512
+ maxConcurrent: 10, // parallel HTTP requests
513
+ },
514
+
515
+ // API endpoint discovery (new in v0.2)
516
+ apiEndpoints: {
517
+ checkErrorHandling: true, // flag missing try/catch
518
+ checkValidation: true, // flag missing input validation
519
+ checkAuth: true, // flag missing auth middleware
520
+ checkSecrets: true, // flag hardcoded secrets
521
+ frameworks: [], // empty = auto-detect all
522
+ },
523
+
524
+ // Disable specific rules
525
+ rules: {
526
+ 'debug-console-log': 'off', // example: allow console.log
527
+ 'dead-link-internal': 'off', // example: skip dead link checks
528
+ },
529
+ });
530
+ ```
531
+
532
+ </details>
533
+
534
+ <br/>
535
+
536
+ ## 🔒 Trust and privacy
537
+
538
+ | | |
539
+ |:--|:--|
540
+ | 🚫 | **No telemetry.** Sniff does not phone home. Ever. |
541
+ | 🔑 | **No signup.** No accounts. No API keys for core functionality. |
542
+ | 📦 | **No data collection.** Your code stays on your machine. |
543
+ | 👁️ | **Open source.** Read every line. Apache 2.0. |
544
+
545
+ > [!NOTE]
546
+ > The AI explorer requires an Anthropic API key only if you want the chaos monkey feature. The other seven checks (source scanning, dead links, API endpoints, accessibility, visual regression, performance, cross-referencing) work completely offline with zero external calls. External link checking in the dead link scanner makes HTTP requests to validate URLs, but never sends your code.
547
+
548
+ <br/>
549
+
550
+ ## Built on
551
+
552
+ [Playwright](https://playwright.dev) · [axe-core](https://github.com/dequelabs/axe-core) · [Lighthouse](https://developer.chrome.com/docs/lighthouse) · [pixelmatch](https://github.com/mapbox/pixelmatch) · [Zod](https://zod.dev) · [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) · [Anthropic SDK](https://github.com/anthropics/anthropic-sdk-typescript)
553
+
554
+ <br/>
555
+
556
+ ## Contributing
557
+
558
+ Easiest way in: **add a source rule.** Each rule is a regex pattern with a severity level in `src/scanners/source/rules/`. See [CONTRIBUTING.md](CONTRIBUTING.md).
559
+
560
+ **Good first contributions:**
561
+ - 🔧 Add a new source scanning rule
562
+ - 🐛 Report a false positive
563
+ - 📚 Improve documentation
564
+
565
+ <br/>
566
+
567
+ ## License
568
+
569
+ [Apache 2.0](LICENSE)
570
+
571
+ ---
572
+
573
+ <p align="center">
574
+ <a href="https://www.linkedin.com/in/adam-boudjemaa/"><img src="https://img.shields.io/badge/LinkedIn-0A66C2?style=flat-square&logo=linkedin&logoColor=white" alt="LinkedIn"></a>
575
+ <a href="https://x.com/AdamBoudj"><img src="https://img.shields.io/badge/X-000000?style=flat-square&logo=x&logoColor=white" alt="X"></a>
576
+ <a href="https://adam-boudjemaa.com/"><img src="https://img.shields.io/badge/Website-ef4444?style=flat-square&logo=googlechrome&logoColor=white" alt="Website"></a>
577
+ </p>
578
+
579
+ <p align="center">
580
+ <sub>Built by <a href="https://github.com/Aboudjem">Adam Boudjemaa</a> · Apache 2.0 · No telemetry · No data collection</sub>
581
+ </p>
@@ -0,0 +1,93 @@
1
+ // src/scanners/accessibility/index.ts
2
+ import { performance } from "perf_hooks";
3
+ function mapAxeImpact(impact) {
4
+ switch (impact) {
5
+ case "critical":
6
+ return "critical";
7
+ case "serious":
8
+ return "high";
9
+ case "moderate":
10
+ return "medium";
11
+ case "minor":
12
+ return "low";
13
+ default:
14
+ return "medium";
15
+ }
16
+ }
17
+ function buildFixSuggestion(violation, node) {
18
+ if (violation.id === "color-contrast") {
19
+ const contrastData = node.any?.find((check) => check.id === "color-contrast");
20
+ if (contrastData?.data) {
21
+ const expected = contrastData.data["expected"];
22
+ const actual = contrastData.data["contrastRatio"];
23
+ if (expected && actual !== void 0) {
24
+ return `Expected contrast ratio of at least ${expected}:1, but found ${actual}:1. Increase the color difference between foreground and background.`;
25
+ }
26
+ }
27
+ }
28
+ if (node.failureSummary) {
29
+ return node.failureSummary;
30
+ }
31
+ return `See ${violation.helpUrl} for remediation guidance.`;
32
+ }
33
+ var AccessibilityScanner = class {
34
+ name = "accessibility";
35
+ async scan(ctx) {
36
+ const start = performance.now();
37
+ const { AxeBuilder } = await import("@axe-core/playwright");
38
+ const a11yConfig = ctx.config.accessibility;
39
+ const standard = a11yConfig?.standard ?? "wcag21aa";
40
+ let tags;
41
+ switch (standard) {
42
+ case "wcag2a":
43
+ tags = ["wcag2a"];
44
+ break;
45
+ case "wcag2aa":
46
+ tags = ["wcag2a", "wcag2aa"];
47
+ break;
48
+ case "wcag21aa":
49
+ default:
50
+ tags = ["wcag2a", "wcag2aa", "wcag21aa"];
51
+ break;
52
+ }
53
+ let builder = new AxeBuilder({ page: ctx.page }).withTags(tags);
54
+ if (a11yConfig?.rules) {
55
+ for (const [ruleId, enabled] of Object.entries(a11yConfig.rules)) {
56
+ if (enabled === false) {
57
+ builder = builder.disableRules([ruleId]);
58
+ }
59
+ }
60
+ }
61
+ if (ctx.viewport.name === "mobile") {
62
+ builder = builder.withRules(["target-size"]);
63
+ }
64
+ const results = await builder.analyze();
65
+ const findings = [];
66
+ for (const violation of results.violations) {
67
+ const severity = mapAxeImpact(violation.impact);
68
+ for (const node of violation.nodes) {
69
+ findings.push({
70
+ ruleId: `a11y/${violation.id}`,
71
+ severity,
72
+ message: `${violation.help}. ${violation.description}`,
73
+ filePath: ctx.page.url(),
74
+ line: 0,
75
+ column: 0,
76
+ snippet: node.html,
77
+ url: ctx.page.url(),
78
+ viewport: ctx.viewport.name,
79
+ fixSuggestion: buildFixSuggestion(violation, node)
80
+ });
81
+ }
82
+ }
83
+ return {
84
+ scanner: this.name,
85
+ findings,
86
+ duration: performance.now() - start
87
+ };
88
+ }
89
+ };
90
+ export {
91
+ AccessibilityScanner
92
+ };
93
+ //# sourceMappingURL=accessibility-UNJB57T6.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/scanners/accessibility/index.ts"],"sourcesContent":["import { performance } from 'node:perf_hooks';\n\nimport type { BrowserScanner, BrowserScanContext, ScanResult } from '../types.js';\nimport type { BrowserFinding } from '../../core/types.js';\nimport type { Severity } from '../../core/types.js';\n\nfunction mapAxeImpact(impact: string | null | undefined): Severity {\n switch (impact) {\n case 'critical': return 'critical';\n case 'serious': return 'high';\n case 'moderate': return 'medium';\n case 'minor': return 'low';\n default: return 'medium';\n }\n}\n\nfunction buildFixSuggestion(\n violation: { id: string; helpUrl: string },\n node: { failureSummary?: string; any?: Array<{ id: string; data?: Record<string, unknown> }> },\n): string {\n if (violation.id === 'color-contrast') {\n const contrastData = node.any?.find((check) => check.id === 'color-contrast');\n if (contrastData?.data) {\n const expected = contrastData.data['expected'] as string | undefined;\n const actual = contrastData.data['contrastRatio'] as number | undefined;\n if (expected && actual !== undefined) {\n return `Expected contrast ratio of at least ${expected}:1, but found ${actual}:1. Increase the color difference between foreground and background.`;\n }\n }\n }\n\n if (node.failureSummary) {\n return node.failureSummary;\n }\n\n return `See ${violation.helpUrl} for remediation guidance.`;\n}\n\nexport class AccessibilityScanner implements BrowserScanner {\n name = 'accessibility';\n\n async scan(ctx: BrowserScanContext): Promise<ScanResult> {\n const start = performance.now();\n\n const { AxeBuilder } = await import('@axe-core/playwright');\n\n const a11yConfig = ctx.config.accessibility;\n\n const standard = a11yConfig?.standard ?? 'wcag21aa';\n let tags: string[];\n switch (standard) {\n case 'wcag2a':\n tags = ['wcag2a'];\n break;\n case 'wcag2aa':\n tags = ['wcag2a', 'wcag2aa'];\n break;\n case 'wcag21aa':\n default:\n tags = ['wcag2a', 'wcag2aa', 'wcag21aa'];\n break;\n }\n\n let builder = new AxeBuilder({ page: ctx.page }).withTags(tags);\n\n // Apply custom rule overrides\n if (a11yConfig?.rules) {\n for (const [ruleId, enabled] of Object.entries(a11yConfig.rules)) {\n if (enabled === false) {\n builder = builder.disableRules([ruleId]);\n }\n }\n }\n\n // Enable touch target-size rule on mobile viewports (A11Y-02)\n if (ctx.viewport.name === 'mobile') {\n builder = builder.withRules(['target-size']);\n }\n\n const results = await builder.analyze();\n\n const findings: BrowserFinding[] = [];\n for (const violation of results.violations) {\n const severity = mapAxeImpact(violation.impact);\n for (const node of violation.nodes) {\n findings.push({\n ruleId: `a11y/${violation.id}`,\n severity,\n message: `${violation.help}. ${violation.description}`,\n filePath: ctx.page.url(),\n line: 0,\n column: 0,\n snippet: node.html,\n url: ctx.page.url(),\n viewport: ctx.viewport.name,\n fixSuggestion: buildFixSuggestion(violation, node),\n });\n }\n }\n\n return {\n scanner: this.name,\n findings,\n duration: performance.now() - start,\n };\n }\n}\n"],"mappings":";AAAA,SAAS,mBAAmB;AAM5B,SAAS,aAAa,QAA6C;AACjE,UAAQ,QAAQ;AAAA,IACd,KAAK;AAAY,aAAO;AAAA,IACxB,KAAK;AAAW,aAAO;AAAA,IACvB,KAAK;AAAY,aAAO;AAAA,IACxB,KAAK;AAAS,aAAO;AAAA,IACrB;AAAS,aAAO;AAAA,EAClB;AACF;AAEA,SAAS,mBACP,WACA,MACQ;AACR,MAAI,UAAU,OAAO,kBAAkB;AACrC,UAAM,eAAe,KAAK,KAAK,KAAK,CAAC,UAAU,MAAM,OAAO,gBAAgB;AAC5E,QAAI,cAAc,MAAM;AACtB,YAAM,WAAW,aAAa,KAAK,UAAU;AAC7C,YAAM,SAAS,aAAa,KAAK,eAAe;AAChD,UAAI,YAAY,WAAW,QAAW;AACpC,eAAO,uCAAuC,QAAQ,iBAAiB,MAAM;AAAA,MAC/E;AAAA,IACF;AAAA,EACF;AAEA,MAAI,KAAK,gBAAgB;AACvB,WAAO,KAAK;AAAA,EACd;AAEA,SAAO,OAAO,UAAU,OAAO;AACjC;AAEO,IAAM,uBAAN,MAAqD;AAAA,EAC1D,OAAO;AAAA,EAEP,MAAM,KAAK,KAA8C;AACvD,UAAM,QAAQ,YAAY,IAAI;AAE9B,UAAM,EAAE,WAAW,IAAI,MAAM,OAAO,sBAAsB;AAE1D,UAAM,aAAa,IAAI,OAAO;AAE9B,UAAM,WAAW,YAAY,YAAY;AACzC,QAAI;AACJ,YAAQ,UAAU;AAAA,MAChB,KAAK;AACH,eAAO,CAAC,QAAQ;AAChB;AAAA,MACF,KAAK;AACH,eAAO,CAAC,UAAU,SAAS;AAC3B;AAAA,MACF,KAAK;AAAA,MACL;AACE,eAAO,CAAC,UAAU,WAAW,UAAU;AACvC;AAAA,IACJ;AAEA,QAAI,UAAU,IAAI,WAAW,EAAE,MAAM,IAAI,KAAK,CAAC,EAAE,SAAS,IAAI;AAG9D,QAAI,YAAY,OAAO;AACrB,iBAAW,CAAC,QAAQ,OAAO,KAAK,OAAO,QAAQ,WAAW,KAAK,GAAG;AAChE,YAAI,YAAY,OAAO;AACrB,oBAAU,QAAQ,aAAa,CAAC,MAAM,CAAC;AAAA,QACzC;AAAA,MACF;AAAA,IACF;AAGA,QAAI,IAAI,SAAS,SAAS,UAAU;AAClC,gBAAU,QAAQ,UAAU,CAAC,aAAa,CAAC;AAAA,IAC7C;AAEA,UAAM,UAAU,MAAM,QAAQ,QAAQ;AAEtC,UAAM,WAA6B,CAAC;AACpC,eAAW,aAAa,QAAQ,YAAY;AAC1C,YAAM,WAAW,aAAa,UAAU,MAAM;AAC9C,iBAAW,QAAQ,UAAU,OAAO;AAClC,iBAAS,KAAK;AAAA,UACZ,QAAQ,QAAQ,UAAU,EAAE;AAAA,UAC5B;AAAA,UACA,SAAS,GAAG,UAAU,IAAI,KAAK,UAAU,WAAW;AAAA,UACpD,UAAU,IAAI,KAAK,IAAI;AAAA,UACvB,MAAM;AAAA,UACN,QAAQ;AAAA,UACR,SAAS,KAAK;AAAA,UACd,KAAK,IAAI,KAAK,IAAI;AAAA,UAClB,UAAU,IAAI,SAAS;AAAA,UACvB,eAAe,mBAAmB,WAAW,IAAI;AAAA,QACnD,CAAC;AAAA,MACH;AAAA,IACF;AAEA,WAAO;AAAA,MACL,SAAS,KAAK;AAAA,MACd;AAAA,MACA,UAAU,YAAY,IAAI,IAAI;AAAA,IAChC;AAAA,EACF;AACF;","names":[]}