openqodex 0.1.0

package/docs/github-action.md

@@ -0,0 +1,73 @@
+# GitHub Action
+
+The OpenQodex Action runs `openqodex scan` on a pull request's change. It uploads the findings to GitHub code scanning as SARIF. No model is involved: the Action runs the scanners only.
+
+## Example workflow
+
+Save this as `.github/workflows/openqodex.yml`:
+
+```yaml
+name: OpenQodex
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  security-events: write
+  actions: read
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: openqodex/openqodex@v0
+```
+
+- `fetch-depth: 0` fetches the full history. The scan needs the pull request's base commit, which a shallow checkout does not have.
+- `security-events: write` lets the Action upload SARIF to code scanning.
+- `actions: read` is read by the SARIF upload in a private repository.
+- `contents: read` lets the job check out the code.
+
+## Inputs
+
+- `version`: the `openqodex` version to run. The default is the version the Action was released with.
+- `upload-sarif`: `true` or `false`. The default is `true`. Set it to `false` to skip the code scanning upload.
+
+## What it does
+
+1. Sets up Node 22.
+2. Restores `~/.openqodex/tools` from the Actions cache, keyed on the runner and the `openqodex` version.
+3. Runs `npx -y openqodex@<version> doctor --install`, which installs every scanner and waits.
+4. Runs `npx -y openqodex@<version> scan --base <pull request base commit> --format sarif`. The SARIF goes to a new folder under the runner's temporary folder, never into the checkout.
+5. Uploads that SARIF to code scanning, when `upload-sarif` is `true` and the scan wrote a report.
+6. Fails the job when the scan exited 1 or 2.
+
+The scan exits 1 only when `.openqodex.yaml` sets `review.block_on_severity` and a finding on a changed line meets it. Without that key, the job never fails on findings. A scan that fails for its own reasons exits 2, and the job fails too.
+
+## Config
+
+The Action reads `.openqodex.yaml` from the repository, like every other command. Custom scanners need an approval stored on the machine that runs them. The runner has none, so the Action lists custom scanners as `untrusted` and skips them.
+
+## Pre-commit
+
+The repository also ships a pre-commit hook for the pre-push stage. Add this to `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/openqodex/openqodex
+    rev: v0.1.0
+    hooks:
+      - id: openqodex-scan
+```
+
+Then install the pre-push hook:
+
+```
+pre-commit install --hook-type pre-push
+```
+
+The hook runs `npx -y openqodex@<version> scan` on the commits not yet pushed plus the working tree. It stops the push only when the scan exits 1. A scan that fails for its own reasons never stops the push. The hook needs Node 22, npx and `sh` on your machine.

package/docs/index.md

@@ -0,0 +1,29 @@
+# OpenQodex docs
+
+OpenQodex is open source code review that runs inside your coding agent, before you push.
+
+These pages ship inside the npm package. `npx openqodex guide <topic>` prints one in your terminal, offline. The topic is the file name without `.md`.
+
+## Words used in these pages
+
+- Change: the commits not yet pushed plus everything uncommitted, untracked files included.
+- Changed lines: the lines the change adds or edits. Context lines around them do not count.
+- Scanner: a program that checks code without a model, such as gitleaks or semgrep.
+- Finding: one problem at one place in the code, with a severity.
+- Candidate: a scanner finding on a changed line, waiting for the agent to verify it.
+- Brief: the text `openqodex review --agent` prints for the agent to review from.
+- Report: the result of a scan or a review, written as `report.md`, `report.json` and `report.sarif`.
+- Verdict: `passed` or `blocked`.
+
+## Pages
+
+- `quickstart`: install OpenQodex and run the first review.
+- `cli`: every command, flag and exit code.
+- `config`: every key of `.openqodex.yaml`.
+- `scanners`: the thirteen built-in scanners.
+- `custom-scanners`: add any scanner by its GitHub link.
+- `agents`: what `init` writes for each coding agent.
+- `github-action`: run the scan on pull requests.
+- `security`: what runs, what is sent where, and where files go.
+- `telemetry`: there is none.
+- `faq`: short answers.

package/docs/llms.txt

@@ -0,0 +1,13 @@
+# OpenQodex docs
+
+- [Agents](agents.md)
+- [Commands](cli.md)
+- [Configuration](config.md)
+- [Custom scanners](custom-scanners.md)
+- [FAQ](faq.md)
+- [GitHub Action](github-action.md)
+- [OpenQodex docs](index.md)
+- [Quickstart](quickstart.md)
+- [Scanners](scanners.md)
+- [Security](security.md)
+- [Telemetry](telemetry.md)

package/docs/quickstart.md

@@ -0,0 +1,82 @@
+# Quickstart
+
+## Paste this prompt into your agent
+
+```
+Install the OpenQodex skill with `npx skills add openqodex/openqodex`.
+Then review my current change with openqodex and tell me the verdict and the findings.
+```
+
+The agent installs the skill, runs the review and tells you the result. The steps below do the same by hand.
+
+## Before you start
+
+- Node 22 or newer, and git.
+- macOS or Linux. On Windows, use WSL.
+- A git repository with a change in it.
+
+## 1. Install into your agent
+
+Run this in your own terminal, not inside the agent:
+
+```
+npx openqodex init
+```
+
+`init` finds Claude Code, Cursor, Codex CLI and Cline on your machine. It prints each file it will write, then asks once. `--yes` skips the question. `agents` lists every file for each agent.
+
+`init` also starts the scanner downloads that your repo needs, in the background. Running it outside the agent matters: some agents run commands in a sandbox that cannot download.
+
+Codex only: open Codex, run `/hooks` and trust the OpenQodex hook. Codex runs a new hook only after you trust it.
+
+## 2. Ask for a review
+
+Say to your agent:
+
+```
+review my change with openqodex
+```
+
+The agent runs `openqodex review --agent`. That command works out the change, runs the scanners and prints a brief. The agent verifies each scanner finding, reviews the change itself, and writes its findings to a file. Then it runs `openqodex review --finalize`, which checks those findings without a model and writes the report.
+
+## 3. Read the report
+
+The agent tells you the verdict and the most serious findings. The full report is in `.openqodex/reviews/<time>-<id>/report.md` in your repo. `.openqodex/` ignores itself in git, so `git status` does not change.
+
+The verdict is `passed` unless `.openqodex.yaml` sets `review.block_on_severity` and a finding meets it. With no config, OpenQodex warns and never blocks.
+
+## Try it on the demo repo
+
+```
+npx openqodex demo /tmp/openqodex-demo
+```
+
+`demo` builds a small repo with planted bugs: a secret, a SQL injection, a bad Dockerfile, a vulnerable lockfile, a shell bug and a workflow injection. It scans the change and prints the report. Then open the folder in your agent and ask for a review.
+
+## Without an agent
+
+`openqodex scan` runs the scanners on the change and prints the report:
+
+```
+npx openqodex scan
+```
+
+It is the same check the git hook, the pre-commit hook and the GitHub Action run.
+
+## First run
+
+Scanners download on first use into `~/.openqodex/tools/`. Only the scanners your change needs download. A scanner still installing after 45 seconds keeps going in the background. The report lists it as installing. It joins the next run.
+
+One measured first run: an Apple Silicon Mac, an empty tool folder, a line of 2 MB per second. The first `demo` printed its report in under a minute. That report held the scanners that had finished installing and listed the rest as installing. The next `scan` included all eight scanners the demo needs. They take about 700 MB of disk.
+
+To download every scanner now:
+
+```
+npx openqodex doctor --install
+```
+
+## Next
+
+- `config`: block pushes at a severity, exclude paths, switch scanners off.
+- `custom-scanners`: add any scanner by its GitHub link.
+- `security`: what runs and what is sent where.

package/docs/scanners.md

@@ -0,0 +1,148 @@
+# Scanners
+
+OpenQodex has thirteen built-in scanners. Each one runs only when the change holds a file it reads. Every downloaded scanner is pinned to one version. OpenQodex never uses a copy of a built-in scanner from your `PATH`.
+
+Pinned versions do not make findings identical on every machine. semgrep fetches its registry rule packs at run time, and OpenQodex does not pin their version.
+
+Every scanner reads the whole changed file. OpenQodex keeps only the findings on changed lines.
+
+## Where scanners come from
+
+Scanners download on first use into `~/.openqodex/tools/<scanner>/<version>/`. `OPENQODEX_HOME` moves that folder.
+
+- GitHub release files are checked against the sha256 pinned in the package before they are unpacked.
+- semgrep and bandit install from PyPI through uv, into one Python 3.11 that OpenQodex manages. uv comes from your `PATH` when present. Otherwise OpenQodex downloads a pinned uv.
+- oxlint installs from npm, with the npm that ships beside your Node. Package install scripts are switched off.
+- brakeman and rubocop install from RubyGems with your Ruby's `gem` command.
+
+A scanner install that takes longer than 45 seconds keeps going in the background. The report lists that scanner as installing. The scanner joins the next run. `openqodex doctor --install` installs every scanner and waits.
+
+Installed scanners take more disk than their downloads. The eight scanners the demo needs take about 700 MB of disk on an Apple Silicon Mac. semgrep with its Python takes about 440 MB of that.
+
+OpenQodex does not install Ruby or Go. Without them, the report lists the scanners that need them as not installed, with the reason.
+
+## Status in the report
+
+The report lists every selected scanner with one status. A scanner left out with `--only` or `--skip` is not listed.
+
+- `ran`: it ran.
+- `no_matching_files`: the change holds no file it reads.
+- `installing`: it is downloading for the first time. It joins the next run.
+- `not_installed`: it could not be installed here. The reason says why.
+- `failed`: it ran and broke. The reason holds its error.
+- `disabled`: `scanners.disable` names it, or `--offline` skipped it.
+- `untrusted`: a custom scanner you have not approved.
+
+A scanner problem never changes the exit code.
+
+## semgrep
+
+- Version: 1.94.0.
+- Runs when: any file changed.
+- Needs: Python 3.11, which OpenQodex downloads through uv. About 86 MB with uv and bandit, measured on Apple Silicon.
+- Rules: the registry packs `p/default`, `p/security-audit` and `p/secrets`.
+- Sends: semgrep fetches those rule packs from the Semgrep registry on each run. It runs with its metrics switched off. The rules are never bundled in the OpenQodex package.
+- `--offline` skips it. The report lists it as disabled.
+
+## gitleaks
+
+- Version: 8.21.2.
+- Runs when: any file changed.
+- Needs: nothing. 2.9 MB on Apple Silicon, 3.0 MB on Linux x64.
+- Writes: links the changed files into a temporary folder outside the repo and scans that folder. It reads the repo's `.gitleaks.toml` or `gitleaks.toml` when present.
+- gitleaks writes its raw report to a temporary file outside the repo. That file holds the matched secrets. OpenQodex deletes it when the run ends.
+- Sends: nothing.
+- Secrets it finds are redacted from the brief, every report file and the terminal. No file OpenQodex keeps holds the secret.
+
+## bandit
+
+- Version: 1.9.4.
+- Runs when: a `.py` or `.pyi` file changed.
+- Needs: the same Python as semgrep.
+- Sends: nothing.
+
+## ruff
+
+- Version: 0.8.4.
+- Runs when: a `.py` or `.pyi` file changed.
+- Needs: nothing. 9.9 MB on Apple Silicon, 11.2 MB on Linux x64.
+- Reads the repo's own ruff settings. It runs with fixes and its cache switched off, so it changes no file.
+- Sends: nothing.
+
+## oxlint
+
+- Version: 1.71.0.
+- Runs when: a `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`, `.mts` or `.cts` file changed.
+- Needs: npm, which ships with Node. About 7.3 MB on Apple Silicon, 8.2 MB on Linux x64.
+- Uses OpenQodex's own settings. A config file in the repo is not loaded.
+- Sends: nothing.
+
+## osv-scanner
+
+- Version: 1.9.2.
+- Runs when: one of these lockfiles changed: `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `Cargo.lock`, `go.mod`, `go.sum`, `requirements.txt`, `Pipfile.lock`, `poetry.lock`, `Gemfile.lock`, `composer.lock`, `pom.xml`, `gradle.lockfile`, `pubspec.lock`, `mix.lock`, `conan.lock`.
+- Needs: network access to osv.dev. 31.8 MB on Apple Silicon, 32.1 MB on Linux x64.
+- Sends: the names and versions of the dependencies in those lockfiles, to osv.dev. It never sends code.
+- `--offline` skips it. The report lists it as disabled.
+
+## actionlint
+
+- Version: 1.7.7.
+- Runs when: a `.yml` or `.yaml` file under `.github/workflows/` changed.
+- Needs: nothing. 2.0 MB on Apple Silicon, 2.1 MB on Linux x64.
+- Sends: nothing.
+
+## hadolint
+
+- Version: 2.15.1.
+- Runs when: a Dockerfile changed: `Dockerfile`, `Dockerfile.<name>` or `<name>.dockerfile`.
+- Needs: nothing. 102.6 MB on Apple Silicon, 55.7 MB on Linux x64.
+- Sends: nothing.
+
+## shellcheck
+
+- Version: 0.10.0.
+- Runs when: a `.sh` or `.bash` file changed.
+- Needs: `xz` to unpack the download. 7.2 MB on Apple Silicon, 2.4 MB on Linux x64.
+- Sends: nothing.
+
+## golangci-lint
+
+- Version: 2.12.2. Its name in `.openqodex.yaml` is `golangci`.
+- Runs when: a `.go` file changed. It checks the packages that hold the changed files.
+- Needs: Go on your `PATH`. 14.4 MB on Apple Silicon, 15.0 MB on Linux x64.
+- Uses OpenQodex's own settings, with gosec switched on. A `.golangci.yml` in the repo is not loaded. It never rewrites `go.mod` or `go.sum`.
+- golangci-lint 2.12.2 is built with Go 1.26. With a newer Go on your PATH it cannot check the code. The report then lists golangci as failed, with the reason.
+- Runs with the Go module proxy off. The modules the repo needs must already be in your Go module cache. Nothing is downloaded.
+- Sends: nothing.
+
+## brakeman
+
+- Version: 6.2.1.
+- Runs when: a Ruby or Rails file changed, and the repo has a `Gemfile` and an `app/` folder. The files are `.rb`, `.rake`, `.gemspec`, `.erb`, `.haml`, `.slim`, `Gemfile`, `Rakefile` and `config.ru`.
+- Needs: Ruby 2.7 or newer. It installs from RubyGems.
+- Uses OpenQodex's own settings. The repo's brakeman config is not loaded.
+- Sends: nothing.
+- Licence: the Brakeman Public Use License, which is not an open source licence. OpenQodex does not bundle brakeman. It downloads brakeman at run time onto your machine. Read the licence before you use it, or switch it off with `scanners.disable: [brakeman]`.
+
+## rubocop
+
+- Version: 1.69.2, with rubocop-rails 2.28.0 and rubocop-performance 1.23.0.
+- Runs when: a `.rb`, `.rake` or `.gemspec` file, a `Gemfile` or a `Rakefile` changed.
+- Needs: Ruby 2.7 or newer. It installs from RubyGems.
+- Uses OpenQodex's own settings. A `.rubocop.yml` in the repo is not loaded, because it can load Ruby code.
+- Sends: nothing.
+
+## sqllint
+
+- Version: part of OpenQodex.
+- Runs when: a `.sql` file changed.
+- Needs: nothing. It runs inside OpenQodex and downloads nothing.
+- Checks Postgres migrations for common mistakes, such as a privileged function left callable by every role.
+- Sends: nothing.
+
+## Choosing scanners
+
+- `scanners.disable` in `.openqodex.yaml` switches built-in scanners off.
+- `--only` and `--skip` on `scan` and `review` pick scanners for one run.
+- `custom-scanners` explains how to add any other scanner.

package/docs/security.md

@@ -0,0 +1,74 @@
+# Security
+
+This page says what OpenQodex runs, what it sends where, and what it writes. Report a vulnerability through GitHub's private vulnerability reporting on the openqodex/openqodex repository. Never open a public issue for one.
+
+## What runs
+
+- The `openqodex` CLI, on your Node.
+- The built-in scanners that fit the change, from `~/.openqodex/tools/`. Each is pinned to one version. A built-in scanner is never taken from your `PATH`.
+- Custom scanners from `.openqodex.yaml` that you approved with `openqodex trust`.
+- git, from your `PATH`.
+
+OpenQodex starts every program with an argument list, never through a shell. Scanners get a small set of environment variables: `PATH`, `HOME`, `TMPDIR`, `LANG`, the `LC_` variables, the proxy variables, and what the scanner itself needs. Your other variables, such as API keys, are not passed on.
+
+A repository can hold config files that make a scanner run code or rewrite files. OpenQodex does not load such files for oxlint, golangci-lint, brakeman and rubocop. It uses its own settings for them. ruff and gitleaks read the repository's own settings for rules only. ruff runs with fixes switched off.
+
+## The trust step
+
+A custom scanner is an arbitrary command. It runs on your machine with your permissions. The config file that names it comes from whatever repository you cloned. So nothing installs or runs a custom scanner until you approve that exact entry:
+
+```
+npx openqodex trust
+```
+
+`trust` downloads the release asset to a quarantine folder before it asks. Nothing is installed or run before your yes. `scan` and `review` never download a custom scanner. `trust` prints the version, the asset, its sha256, the program and the run line, then asks yes or no. The approval covers that repository and that entry only. An edited entry needs a new approval. `scan` and `review` skip an unapproved entry and list it as `untrusted`.
+
+The stored sha256 is checked against the project's checksum file when the project publishes one. Otherwise it is the hash of your first download. `custom-scanners` explains the difference.
+
+Agents that follow the OpenQodex skill are told never to run `openqodex trust` without asking you.
+
+## What is sent where
+
+OpenQodex and the built-in scanners send no code anywhere. The review runs on the model your agent already uses, which sees what the agent reads. A custom scanner you approved does whatever its own command does.
+
+OpenQodex and the built-in scanners use the network for these things only:
+
+- Scanner downloads on first use. GitHub release files are checked against sha256 sums pinned in the package. semgrep and bandit come from PyPI through uv, with a Python 3.11 that uv downloads. oxlint comes from npm. brakeman and rubocop come from RubyGems. These package installs are pinned by version.
+- Semgrep rule packs. semgrep fetches `p/default`, `p/security-audit` and `p/secrets` from the Semgrep registry on each run. Its metrics are off. The rules are never bundled in the package.
+- The dependency check. When the change holds a lockfile, osv-scanner sends the names and versions of the dependencies in it to osv.dev. It never sends code.
+- Custom scanners. `openqodex trust` reads the release from the GitHub API and downloads the asset. After approval, a custom scanner does whatever its own command does.
+
+golangci-lint runs with the Go module proxy off, so it downloads no modules.
+
+`--offline` skips osv-scanner and semgrep, which the report lists as disabled. It also turns scanner downloads off.
+
+OpenQodex sends no telemetry. See `telemetry`.
+
+## Secrets
+
+When gitleaks finds a secret in the change, OpenQodex removes it from the brief, every report file and the terminal. It keeps the length and sha256 of each secret, to redact any text the agent quotes.
+
+gitleaks writes its raw report to a temporary file outside the repository. That file holds the matched secrets. OpenQodex deletes it when the run ends. No file OpenQodex keeps holds the secret.
+
+A secret is redacted only when a scanner matched it. When gitleaks did not run, the brief shows the change as it is.
+
+## Where files are written
+
+In your home folder, under `~/.openqodex/` (`OPENQODEX_HOME` moves it):
+
+- `tools/<scanner>/<version>/`: the scanners.
+- `tools/uv-python/`: the Python 3.11 for semgrep and bandit.
+- `cache/`: the download caches for uv and npm.
+- `runtime/<version>/` and `bin/openqodex`: the copy of the package and the launcher that the hooks call, written by `init`.
+- `install.json`: what `init` and `hook install` wrote, so an uninstall removes only that.
+- `trust.json`: your approvals of custom scanners.
+
+In the repository, under `.openqodex/` only:
+
+- `.gitignore`, holding `*`, so the folder ignores itself and `git status` does not change.
+- `reviews/<time>-<id>/`: one folder per run, holding the brief, the scan result, the agent's findings and the reports. OpenQodex keeps the newest 20.
+- `latest.json`: points at the newest run.
+
+The agent settings and skill files `init` writes are listed in `agents`.
+
+The change itself is worked out without writing inside `.git`. OpenQodex uses a temporary copy of the index and a temporary object folder.

package/docs/telemetry.md

@@ -0,0 +1,9 @@
+# Telemetry
+
+OpenQodex sends no telemetry.
+
+It collects no usage data, no crash reports and no identifiers. It has no switch to turn telemetry on, because there is none to turn on.
+
+semgrep runs with its own metrics switched off.
+
+The network traffic OpenQodex does cause is listed in `security`: scanner downloads, Semgrep rule packs, the osv.dev dependency lookup, and custom scanner downloads you approve.

package/lenses/a11y-icon-only-button-no-aria-label.md

@@ -0,0 +1,51 @@
+---
+name: a11y-icon-only-button-no-aria-label
+description: Icon-only button / clickable that relies on `title` for description without an aria-label
+triggers:
+  files:
+    - "*.tsx"
+    - "*.jsx"
+    - "*.vue"
+    - "*.svelte"
+    - "*.astro"
+    - "**/*.tsx"
+    - "**/*.jsx"
+    - "**/*.vue"
+    - "**/*.svelte"
+    - "**/*.astro"
+  hunk_regex: "<button\\b|<a\\b|role=[\"']button[\"']|onClick=\\{"
+confidence_floor: 0.75
+---
+
+A clickable element renders only an icon (an `<svg>`, an emoji, a
+single character from a font-icon set, an `<img>` whose `alt` is
+empty or omitted) and depends on `title` to convey what it does.
+`title` is hover-only and is NOT reliably announced by screen
+readers, so the control is opaque to assistive-tech users: they
+hear "button" with no context.
+
+Flag when an interactive element added in this diff:
+- has no readable text node as a child (only `<svg>`, an icon
+  component like `<ChevronIcon />`, `<img alt="">`, a single
+  glyph, or pure children-of-children that are themselves icons),
+- has no `aria-label`, `aria-labelledby`, OR a visually-hidden
+  text label (`<span class="sr-only">…</span>`, `<VisuallyHidden>`,
+  Tailwind's `sr-only` utility), AND
+- the element is `<button>`, `<a>`, `[role="button"]`, or has an
+  `onClick`/`onPointerDown`/`onKeyDown` handler.
+
+The `title` attribute alone is NOT a fix; flag those too.
+
+Suppress when:
+- the button already has `aria-label`, `aria-labelledby`, or a
+  visually-hidden text child (`sr-only`, `visually-hidden`,
+  `<VisuallyHidden>`, `screen-reader-text`),
+- the icon itself carries a label (`<svg aria-label="…">` or an
+  icon component whose own implementation injects an aria-label),
+- the project already has a wrapping component like `<IconButton
+  label="…" />` that injects the aria-label,
+- the element has visible text alongside the icon.
+
+Severity: `minor` by default. Bump to `major` for primary CTAs
+(submit / save / delete) where the missing label blocks the user's
+intent, not just degrades it.

package/lenses/array-iteration-missing-key-prop.md

@@ -0,0 +1,31 @@
+---
+name: array-iteration-missing-key-prop
+description: .map() rendering JSX without a stable key prop (or using index as key for mutable lists)
+triggers:
+  files:
+    - "*.tsx"
+    - "*.jsx"
+    - "**/*.tsx"
+    - "**/*.jsx"
+  hunk_regex: "\\.map\\s*\\("
+confidence_floor: 0.7
+---
+
+JSX rendered inside `.map(...)` either has no `key` prop or uses
+the array index as a key. Without a stable key React can't reorder
+children correctly: form inputs lose their internal state on
+re-order, animations replay, and components mounted in the loop
+double-fire effects when items shift positions.
+
+Flag when:
+- the `.map((item) => <Component .../>)` returns JSX with no `key`
+- the `key` is `index` (or any expression that depends only on the
+  loop index) AND the underlying list can reorder / insert / remove
+
+Suppress when:
+- a stable id field is used (`key={item.id}` / `key={item.uuid}`)
+- the list is provably static for the component's lifetime
+  (read-only constants, sorted-once display lists)
+- the index IS the natural key (immutable, append-only)
+- the rendered children are stateless / sideeffect-free and won't
+  notice a reorder

package/lenses/async-await-in-loop-n-plus-one.md

@@ -0,0 +1,42 @@
+---
+name: async-await-in-loop-n-plus-one
+description: await inside a for / map / forEach, N round-trips per row
+triggers:
+  files:
+    - "*.ts"
+    - "*.tsx"
+    - "*.js"
+    - "*.jsx"
+    - "*.mjs"
+    - "*.cjs"
+    - "**/*.ts"
+    - "**/*.tsx"
+    - "**/*.js"
+    - "**/*.jsx"
+    - "**/*.mjs"
+    - "**/*.cjs"
+  hunk_regex: "for\\s*\\(|\\.(forEach|map|reduce)\\s*\\("
+confidence_floor: 0.7
+---
+
+A `for` loop / `for-of` / `.map(async ...)` / `.forEach(async ...)`
+body contains an `await` against a network or database client.
+Sequential awaits multiply latency by row count (100 rows × 30ms
+= 3s) and turn a list view, batch import, or N-of-M lookup into a
+classic N+1.
+
+Flag when:
+- the loop iterates over a list of identifiers / records and the
+  body awaits a fetch / db query / API call **per iteration**
+- the result is collected into an array (a `Promise.all` over the
+  iterable would parallelize cleanly)
+
+Suppress when:
+- ordering matters AND the next iteration's input depends on the
+  previous iteration's result (rate-limited APIs, paged cursors,
+  workflows that build on prior steps)
+- there's an explicit per-iteration delay / rate-limit
+- the loop iterates a known-small fixed set (≤ 3) where
+  parallelization wouldn't change anything material
+- a `.map(async ...)` is followed by `await Promise.all(...)`;
+  that IS the parallel pattern

package/lenses/async-click-double-fire-race.md

@@ -0,0 +1,59 @@
+---
+name: async-click-double-fire-race
+description: Async onClick handler with no in-flight guard / disabled toggle, double-clicks fire duplicate requests
+triggers:
+  files:
+    - "*.tsx"
+    - "*.jsx"
+    - "*.vue"
+    - "*.svelte"
+    - "**/*.tsx"
+    - "**/*.jsx"
+    - "**/*.vue"
+    - "**/*.svelte"
+  hunk_regex: "onClick=|@click=|on:click=|onPress=|onPointerDown="
+confidence_floor: 0.75
+---
+
+A button / link / clickable triggers an async operation
+(`fetch`, `mutate`, an awaited handler) without any guard against
+re-firing while the first request is still in flight. A rapid
+second click queues a duplicate request: a duplicate insert, a
+double-charge, an interleaved state update where the late response
+clobbers the early one. Touchpad users and slow networks hit this
+constantly.
+
+Flag when a handler added in this diff:
+- is `async` OR returns a Promise / calls `await ...` / calls
+  `fetch(...)` / calls a project-specific async helper (mutate,
+  a fetch wrapper, etc.),
+- AND has no `isLoading` / `inFlight` / `pending` boolean checked
+  at the top (early return when true),
+- AND has no `disabled={isLoading}` (or equivalent class swap) on
+  the bound element,
+- AND has no library-level dedup (TanStack Query's `mutate` with
+  the same key is OK; React Query's `useMutation` running through
+  its own queue is OK; a hand-rolled `setX([...])` is NOT).
+
+Examples that should fire:
+- `onClick={async () => { const r = await fetch(...); setState(r); }}`
+  with no disabled / loading guard
+- an expand/collapse toggle that calls `fetchTeamMembers(id)`
+  but doesn't track `loadingTeams.has(id)`
+- `<button onClick={async () => { await save(); navigate(...) }}>`
+  where save can take seconds
+
+Suppress when:
+- the handler is wrapped by `useMutation` / `useAction` /
+  `useTransition` / similar library primitive that owns the
+  in-flight tracking,
+- the bound element has `disabled={isLoading}` /
+  `aria-disabled={isLoading}` / a CSS class swap that prevents
+  pointer events,
+- the handler is genuinely idempotent (PATCH against a known
+  resource state, GET-only, etc.); call out the idempotency
+  guarantee when you suppress.
+
+Severity: `minor` for read-only / idempotent paths, `major` for
+writes / mutations / billable actions (the duplicate insert and
+the double-charge cases).

package/lenses/async-floating-promise.md

@@ -0,0 +1,40 @@
+---
+name: async-floating-promise
+description: An async function is called without await / .catch, silent rejection
+triggers:
+  files:
+    - "*.ts"
+    - "*.tsx"
+    - "*.js"
+    - "*.jsx"
+    - "*.mjs"
+    - "*.cjs"
+    - "**/*.ts"
+    - "**/*.tsx"
+    - "**/*.js"
+    - "**/*.jsx"
+    - "**/*.mjs"
+    - "**/*.cjs"
+  hunk_regex: "\\basync\\b|\\.then\\("
+confidence_floor: 0.7
+---
+
+An async function is invoked from synchronous code (or from another
+async fn) without `await`, without `.then(...).catch(...)`, and
+without `void`. The returned promise floats: a rejection becomes an
+unhandled rejection (process warning, eventual crash on newer Node
+versions, swallowed entirely in browsers) and the caller has no
+ordering guarantee with subsequent statements.
+
+Flag a call to an `async fn` (or a fn that demonstrably returns a
+promise: `.then` chains, fetch wrappers, db client calls) whose
+return value is **discarded**: not assigned, not returned, not
+awaited, not chained with `.catch`, and not preceded by the explicit
+`void` keyword.
+
+Suppress when:
+- the call is intentionally fire-and-forget AND prefixed with `void`
+  (the documented "I know" marker)
+- the outer scope wraps in `Promise.all([...])` / `Promise.allSettled`
+- the call is on a logger / telemetry / metrics method where dropped
+  rejections are explicitly acceptable