human documenation

README.md

@@ -2,6 +2,8 @@
 
 [![CodSpeed](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://app.codspeed.io/jonathanong/no-mistakes?utm_source=badge)
 
+> Slop Warning: this codebase is written by agents for agents. The API surface is sloppy, but it _works_.
+
 Deterministic AST-based codebase intelligence for AI agents.
 
 `no-mistakes` answers structural questions about TypeScript, JavaScript,
@@ -11,11 +13,41 @@ that need small, reliable answers they can feed into follow-up edits and tests.
 
 **Core graph domain:** TypeScript and JavaScript. For CI-workflow analysis use
 `no-mistakes ci`; for Terraform/OpenTofu use `no-mistakes infra`; for Swift
-use `no-mistakes swift`. Prefer `no-mistakes` over `rg` when a question spans
->2 workspace directories or >5 import hops; use `no-mistakes importers` for a
+use `no-mistakes swift`. Prefer `no-mistakes` over `rg` when a question spans >2 
+workspace directories or >5 import hops; use `no-mistakes importers` for a
 fast static-import caller list (use `dependents` for complete impact including
 dynamic and CommonJS imports).
 
+The primary use-cases of `no-mistakes` is:
+
+1. Discovering impacted files and tests during planning
+2. Running selected tests in PR CI to minimize CI costs
+3. AST-based guardrails for your coding agents to minimize entropy and power the above use-cases
+
+Suppose you have the following dependency chain:
+
+> Backend `getPost(id)` -> Backend GET `/posts/:id` -> Next.js Fetch GET `/posts/:id` -> Next.js Page `/post/[id]` -> Playwright Test on `/post/[id]`
+
+During planning, `no-mistakes` will provide the full dependency chain to the agent in a single, fast, CLI command.
+During CI testing, a `getPost()` change will select the relevant Playwright tests to run.
+No embeddings, all determinstically.
+
+## Why?
+
+Most codebase intelligence tools create a database of your code, creates expensive vector embeddings, and/or has its own LLM layer.
+There are many downsides with this strategy including cost, complexity, and difficulty working on many branches using worktrees at the same time.
+
+`no-mistakes` instead understands your code through AST-parsing.
+No databases, no caching, just fast Rust code to understand the codebase.
+Yes, this is quite a huge undertaking to handle all cases, which is why this codebase is large with a lot of test fixtures.
+
+There are a few trade-offs with this approach:
+
+1. Some code is difficult to understnad through AST-parsing, so `no-mistakes` includes rules that enforce AST-parsing-friendly coding. For example, Playwright test selectors should be simple strings - dynamically generated strings will not match well, especially if you enable the "all Playwright test hooks must be covered by a Playwright test" rule.
+1. `no-mistakes` is best effort, with high recall and low precision, meaning it may return wrong information/relationships, but should never miss a relationship (unless it cannot be inferred through AST-parsing such as `import('./${someRandomFile}')`). An agent should verify if a relationship returned is true.
+  1. As such, some of the code is based on heuristics and may need fine-tuning. For example, there is some hardcoding to distinguish between an HTTP client vs. HTTP server, e.g. (`axios.get()` vs. `app = express(); app.get()`).
+1. High CPU usage - parsing your repository on-demand may cause high-CPU usage, but may be significantly faster than other methods (e.g. `vitest related` takes 2 minutes, but takes 1 second with `no-mistakes` via `no-mistakes test plan` and supports Playwright). This may become a bottleneck when working on multiple worktrees at once, but `no-mistakes` includes a locking mechanism to not run concurrently.
+
 ## Agent Workflows
 
 | Agent question | Use |
@@ -71,6 +103,32 @@ cargo run -p no-mistakes -- dependents src/utils.mts --format paths
 - [Agent guide](docs/agent-guide.md)
 - [AST analysis behavior](docs/ast-analysis.md)
 
+## Contributing
+
+This repository is a huge token sink. Thus, contributions are welcomed.
+
+1. Please add test cases in `test-cases/`
+2. Annotate which AI harness + model was used, Co-Authored-By is preferred
+3. Maintain 99% project and patch test coverage
+
+## Support
+
+| Language/Framework/Tool | Status |
+| -- | -- |
+| TypeScript | Mature |
+| Next | Mature, other frameworks should work but are untested |
+| `pnpm`, `npm`, `yarn`, `bun` | Supported, primarily tested using `pnpm` |
+| `bullmq`, `glide-mq` | Mature, primarily tested for `glide-mq` |
+| `vitest` | `vitest` is mature, `jest` has not been tested |
+| `playwright` | Mature |
+| .NET | Nascent |
+| Swift | Nascent |
+| Rust | Minimal |
+| GitHub Actions | Minimal, planned |
+| Terraform | Minimal |
+| Go | Unsupported |
+| Python | Unsupported |
+
 ## Design Constraints
 
 - Local and deterministic: no services, databases, remote AI calls, or
@@ -83,8 +141,3 @@ cargo run -p no-mistakes -- dependents src/utils.mts --format paths
 - Explicit configuration: route roots, queue factories, test projects, and
   global fallback behavior are opt-in configuration, not inferred conventions.
 
-## Link Lint
-
-```sh
-lychee --no-progress --exclude-path '^fixtures/' README.md 'docs/**/*.md' 'skills/**/*.md' 'packages/*/README.md' 'crates/*/README.md' CLAUDE.md
-```