pi-lens 3.8.68 → 3.8.70

package/docs/inspiration_tree_sitter_rules_round2.md

@@ -0,0 +1,470 @@
+# inspiration_tree_sitter_rules_round2.md — second-pass rule-repo research (2026-06-25)
+
+> Status: **research notes, untracked** (matches the `docs/inspiration_*` gitignore pattern under `.gitignore:50`). Companion to `docs/inspiration_tree_sitter_rules.md` and `docs/inspiration_tree_sitter_rules_investigation.md`.
+> Method: every count and rule-shape claim was verified against the actual repo state via `curl`/`aoiowebmap`/`aoiowebfetch` against the live raw GitHub files (not READMEs or third-party summaries). Where a claim couldn't be verified, it's marked **[unverified]**.
+> Headline finding: **most rule repositories in this round are *secret-scanner* rule collections, not AST-pattern rule collections.** pi-lens already has `gitleaks` + `trivy` + the ast-grep `*-hardcoded-secret-*` rules covering secret detection. Most of these repos don't add a new class of detection.
+
+---
+
+## TL;DR — ranked (revised after second pass)
+
+| # | Source | Stars | Rules | Format | Verdict |
+|---|---|---|---|---|---|
+| 1 | **`RealHarshThakur/ast-grep-go`** | 2 | 11 Go idioms | ast-grep YAML | **PORT** — clean detector-only Go rules |
+| 2 | **`analysis-tools-dev/static-analysis`** | 14,644 | index, not a rule source | meta | **REFERENCE** — points to other tools (semgrep, oxlint, ruff, etc.) |
+| 3 | **`HerringtonDarkholme/awesome-tree-sitter`** | 20 | index | meta | **REFERENCE** — only 1 README entry, sibling of drom/awesome-tree-sitter |
+| 4 | **`mongodb/kingfisher`** | 1,143 | **954** secret rules | non-ast-grep YAML (entropy + validation) | **PATTERN SOURCE** — not direct port; the *shape* of multi-provider coverage is the model |
+| 5 | **`trufflesecurity/trufflehog`** | 26,870 | **800+** secret rules | non-ast-grep YAML/Go (Go-based with YAML examples) | **NOT A PORT** — already covered by `gitleaks` runner |
+| 6 | **`zricethezav/gitleaks`** | 27,858 | **100+** secret rules | TOML (`gitleaks.toml`) | **NOT A PORT** — already a runner |
+| 7 | **`Kitware/CMake`** (sgconfig.yml) | n/a | 8 Cpp rules | ast-grep YAML | **NOT A PORT** — all CMake-internal (`cm*` prefix) |
+| 8 | **`trailofbits/buttercup`** | 1,609 | n/a (CRS, not a rule collection) | Go + LLM | **SKIP** — AGPL license, AI-driven vuln finding, not a rule format |
+| 9 | **`PurCL/RepoAudit`** | 409 | n/a | Python tree-sitter | **NOT A PORT** — rules in Python code, LLM-augmented dataflow |
+| 10 | **`noperator/slice`** | 203 | 1 .ql query (UAF) | CodeQL + tree-sitter | **NOT A PORT** — CodeQL is its own language |
+| 11 | **`x0mmd/oh-my-open-pentest`** (ast-grep skill) | small | pattern reference docs | skill markdown | **REFERENCE** — `patterns.md` + `yaml-rules.md` are good SKILL.md fodder |
+| 12 | **`mauromedda/agent-toolkit`** (ast-grep skill) | small | pattern reference docs | SKILL.md | **REFERENCE** — same as #11, more terse |
+| 13 | **`dustinspecker/awesome-eslint`** | 4,731 | index of ESLint plugins | meta | **SKIP** — different rule format (ESLint JS rules) |
+
+**Net new rule sources for pi-lens: 1** (`RealHarshThakur/ast-grep-go`). The other "interesting" finds (Kingfisher, TruffleHog, Gitleaks) are secret scanners pi-lens already covers via `gitleaks` + `trivy` + ast-grep `*-hardcoded-secret-*` rules.
+
+The **pattern templates** from Kingfisher's `AGENTS.md` are real value: that file documents rule-writing conventions (anchor patterns, entropy constraints, checksum validation) that are not specific to secret detection and could inform future ast-grep rule design in pi-lens.
+
+---
+
+## 1. `RealHarshThakur/ast-grep-go` — 11 Go idiom rules ★★★★★ PORT
+
+**Source:** https://github.com/RealHarshThakur/ast-grep-go  
+**Format:** ast-grep YAML (drop-in compatible with pi-lens's runner)  
+**Coverage:** 11 Go-specific idiomatic-pattern rules
+
+### Rule list (all 11, verified by `git ls-tree`)
+
+| # | Rule id | Severity | Pattern (simplified) |
+|---|---|---|---|
+| 1 | `loop-var-capture` | warning | `for $I := range $XS { go func() { $$_ }() }` |
+| 2 | `defer-in-loop` | warning | defer inside loop (resource leak risk) |
+| 3 | `nil-map-assignment` | warning | writing to `var m map[K]V` before `make()` |
+| 4 | `string-concat-in-loop` | warning | `s += ...` inside loops |
+| 5 | `mutex-unlock-mismatch` | warning | unbalanced `mu.Lock()`/`mu.Unlock()` |
+| 6 | `unlock-in-loop` | warning | `mu.Unlock()` inside loop (always-unlock) |
+| 7 | `waitgroup-done-scope` | warning | `wg.Done()` outside proper scope |
+| 8 | `shadow-err-variable` | warning | `if err := ...; err != nil` shadows outer err |
+| 9 | `gorm-unbounded-preload` | warning | `.Preload(...)` without `.Limit(...)` |
+| 10 | `gorm-find-without-where` | warning | `.Find(...)` without `.Where(...)` |
+| 11 | `gorm-n-plus-one` | warning | loop with `.First(...)` queries |
+
+### Verdict
+
+All 11 are **detectors only** (no `fix:`). All ast-grep-native YAML. Drop into `rules/ast-grep-rules/rules/go/` (creating the dir alongside the existing `c/`, `cpp/`, etc.).
+
+**Cross-reference with pi-lens current state:**
+- `rules/ast-grep-rules/coderabbit/rules/go/` ships 11 rules (all CWE-295/798/etc. security). No overlap with these 11 idiom rules.
+- `rules/ast-grep-rules/rules/` ships zero Go-specific rules (verified with `ls rules/ast-grep-rules/rules/ | grep -i go` → empty).
+- `gofmt` + `go vet` + `golangci-lint` are dispatch runners per AGENTS.md but cover a different niche (style + compile-time correctness, not Go-specific anti-patterns like `loop-var-capture`).
+
+**Effort:** XS (single batch, all 11 files).  
+**Value:** Med — fills a real Go-specific idiom gap; complements `golangci-lint` rather than overlapping with it.
+
+**Open question:** Are there test fixtures for these rules? The repo has `rules_test/01-loop-var-capture_test.go` etc. — but these are Go test files (not ast-grep's `<id>-test.yml` format). Need to re-create the behavioral fixtures in pi-lens's format (`rules/ast-grep-rules/rule-tests/<id>-test.yml`).
+
+---
+
+## 2. `analysis-tools-dev/static-analysis` — meta-list, **includes ast-grep entry**
+
+**Source:** https://github.com/analysis-tools-dev/static-analysis  
+**Format:** meta (catalog of 756 tools, not a rule collection)  
+**Coverage:** None directly — points to other tools
+
+### What's useful
+
+The `data/tools/` directory contains one YAML per tool. **`data/tools/ast-grep.yml` exists** — a fact that's relevant because it confirms the meta-list's maintainers consider ast-grep a "real" tool (not a curiosity). The file lists ast-grep's tags (c, csharp, go, java, lua, javascript, json, jsx, kotlin, python, ruby, rust, typescript, yaml — 14 languages, matching pi-lens's 14-language tree-sitter coverage) and categorizes it as `linter`.
+
+### What's useful for inspiration
+
+The 756-tool catalog surfaces other tools we haven't evaluated:
+- **`oxlint`** (`oxc.yml`) — 500+ ESLint-compatible rules in Rust. Per `docs.oxc.rs`, supports plugins in JS with ESLint-compatible API. Could be worth investigating as a **rule format compatibility layer** (pi-lens's tool could read `.oxlintrc.json` configs).
+- **`ruff`** (`ruff.yml`) — already a runner; metadata confirms
+- **`semgrep`** (`semgrep.yml`) — already evaluated as pattern source
+- **`deno_lint`** (`deno_lint.yml`) — 200+ rules; Rust-based, faster than ESLint
+
+### Verdict
+
+Not a port target. **Useful as a sanity check + future-tool-discovery feed.** When AGENTS.md mentions new tools, this is the meta-index to consult.
+
+---
+
+## 3. `HerringtonDarkholme/awesome-tree-sitter` — minimal index
+
+**Source:** https://github.com/HerringtonDarkholme/awesome-tree-sitter  
+**Format:** meta (README only, 20 stars, no rule collection)  
+**Coverage:** None directly
+
+The README lists tools, parsers, tutorials. Notable entries we hadn't found elsewhere:
+- **`mongodb/kingfisher`** — secret scanning via tree-sitter (see §4)
+- **`trailofbits/buttercup`** — security-oriented parsing (see §8)
+- **`PurCL/RepoAudit`** — repo-level auditing with tree-sitter (see §9)
+- **`noperator/slice`** — SAST using tree-sitter queries (see §10)
+- **`zizmorcore/zizmor`** — GitHub Actions security scanner via tree-sitter (**already in pi-lens** per AGENTS.md)
+
+### Verdict
+
+Not a port target. Useful as a redirect to the §4–§10 sources.
+
+---
+
+## 4. `mongodb/kingfisher` — 954 secret rules ★★★ PATTERN SOURCE (not port)
+
+**Source:** https://github.com/mongodb/kingfisher  
+**Stars:** 1,143 | **License:** Apache-2.0  
+**Rules:** 954 in **585 YAML files** under `crates/kingfisher-rules/data/rules/` (per GitHub API list)  
+**Format:** **NOT ast-grep** — proprietary schema with `pattern`, `min_entropy`, `pattern_requirements`, `validation`, `revocation` blocks
+
+### What's in it (verified by sampling)
+
+Each rule file has shape:
+```yaml
+rules:
+  - name: GitHub Personal Access Token - fine-grained permissions
+    id: kingfisher.github.1
+    pattern: |
+      (?x)
+      (
+        (?P<body>github_pat_[0-9][A-Za-z0-9]{21}_[A-Za-z0-9]{43})
+        (?P<checksum>[A-Za-z2-7]{8})
+        [A-Za-z0-9]{8}
+      )
+      \b
+    pattern_requirements:
+      min_digits: 2
+      min_lowercase: 2
+      checksum:
+        actual: { template: "{{ checksum }}", requires_capture: checksum }
+        expected: "{{ body | sha256_b32: 8 }}"
+        skip_if_missing: true
+    min_entropy: 3.5
+    examples: [...]
+    references: [...]
+    validation:
+      type: Http
+      content:
+        request:
+          method: GET
+          url: '{{ GITHUB_API_BASE_URL }}/user'
+          headers: { Authorization: token {{ TOKEN }} }
+    revocation:
+      type: Http
+      content:
+        request:
+          method: POST
+          url: '{{ GITHUB_API_BASE_URL }}/credentials/revoke'
+```
+
+Notable features Kingfisher has that **pi-lens's existing secret detection doesn't**:
+- **Checksum validation** (e.g., GitHub PATs use a CRC32-derived base62 checksum — this can sharply reduce false positives)
+- **HTTP live-validation** against provider APIs (validate that a detected credential is actually live before alerting)
+- **HTTP revocation** (provider-specific endpoints to revoke a leaked credential)
+- **954 providers covered** — way more than CodeRabbit's 48 Python rules or Gitleaks's ~100 rules
+
+### Why NOT a direct port
+
+The schema is incompatible with ast-grep:
+- `pattern:` is a Rust regex (uses `regex` crate features: named captures `(?P<name>...)`, `(?:...)`, character classes), not ast-grep's `$VAR`/`$$$` metavar syntax
+- `pattern_requirements` has no ast-grep equivalent (entropy/checksum are post-match checks)
+- `validation` and `revocation` are HTTP request shapes, not in-tree checks
+- **Even if you translated every rule's pattern to ast-grep**, you'd lose entropy/checksum/validation
+
+### What's actually liftable (NOT a port, but a pattern source)
+
+**`crates/kingfisher-rules/data/rules/AGENTS.md`** (8,186 bytes) — this is a generic rule-authoring guide. Per the file:
+
+> ## Required Rule Shape
+> Each rule entry should define:
+> - `name`
+> - `id`
+> - `pattern`
+> - `min_entropy` (default to 3.0)
+> - `confidence` (default to medium)
+> - `examples` (at least one realistic positive example)
+
+> ## Pattern Quality Rules
+> - Prefer specific anchors/prefixes and provider context over broad generic regex.
+> - When the token format is generic or common-looking (for example bare 32-hex keys), prefer contextual patterns of the form: provider keyword → short flexible gap → key/secret label → short flexible gap → token.
+> - Use `pattern_requirements` to enforce quality constraints (`min_digits`, `min_uppercase`, `min_lowercase`, `min_special_chars`, `ignore_if_contains`, `checksum`).
+
+These conventions (specific anchors, contextual patterns, quality constraints) are applicable to **ast-grep** rule authoring too. Concrete lift: write `docs/writing-ast-grep-rules.md` for pi-lens, lifting from Kingfisher's AGENTS.md + AGENTS.md's own §3.1 conventions.
+
+**Concrete pi-lens rule patterns I could write today** by adapting from Kingfisher (these are detector patterns that survive the schema translation):
+- `OpenAI API key` — `pattern: sk-[A-Z0-9]{48}` (already a CodeRabbit rule)
+- `Anthropic API key` — `pattern: sk-ant-[A-Za-z0-9_-]{32,}` (CodeRabbit has it)
+- `AWS Access Key ID` — `pattern: AKIA[0-9A-Z]{16}` (CodeRabbit has it)
+- **New for pi-lens**: `Hugging Face token` — `pattern: hf_[A-Za-z]{32}`
+- **New for pi-lens**: `Replicate API token` — `pattern: r8_[A-Za-z0-9]{40}`
+- **New for pi-lens**: `Perplexity API key` — `pattern: pplx-[A-Za-z0-9]{48}`
+
+These are all pure regex-shaped tokens — translate 1:1 from Kingfisher to ast-grep `pattern:`. Each takes ~5 minutes. The value is **provider coverage breadth** (Kingfisher has 954, pi-lens + CodeRabbit has ~50 combined) — particularly for newer AI SaaS providers.
+
+### Recommendation
+
+**Open a single-batch PR** to port ~30 high-value AI SaaS provider token rules from Kingfisher into `rules/ast-grep-rules/rules/`. Source the regex patterns from `crates/kingfisher-rules/data/rules/{provider}.yml`. License: Apache-2.0 (compatible with CodeRabbit's vendored license). Attribute in the YAML header per Kingfisher's `AGENTS.md` rule-shape conventions.
+
+---
+
+## 5. `trufflesecurity/trufflehog` — 800+ secret rules ★ SKIP
+
+**Source:** https://github.com/trufflesecurity/trufflehog  
+**Stars:** 26,870 | **License:** AGPL-3.0 (NOT compatible with pi-lens's MIT/Apache-2.0 mix)  
+**Rules:** **800+ detectors**, mostly Go-based with some YAML examples  
+**Format:** Mostly Go code (`pkg/detectors/<provider>/<provider>.go`); YAML only for `examples/` and `hack/semgrep-rules/`
+
+### Why skip
+
+1. **License:** AGPL-3.0 is incompatible with pi-lens's vendoring model (AGENTS.md: "Vendored with the upstream commit pinned — bumping the vendor is a deliberate operation, not a `git pull`"). Mixing AGPL into a permissive-licensed extension is a license-compliance risk.
+
+2. **Format:** Most rules are in Go (`pkg/detectors/anthropic/anthropic.go`, etc.) — not YAML. The YAML in `examples/` is illustrative, not the rule format. Porting would mean reimplementing each rule in ast-grep YAML.
+
+3. **Already covered:** Pi-lens's existing secret detection (per AGENTS.md: "Secrets (`gitleaks` + `trivy secret` + the ast-grep `*-hardcoded-secret-*` rules) are collapsed by location into a single 🔴 blocker") covers the same surface.
+
+### Verdict
+
+Skip. The rule format (Go) and license (AGPL) are both blockers.
+
+---
+
+## 6. `zricethezav/gitleaks` — 100+ secret rules ★ SKIP (already a runner)
+
+**Source:** https://github.com/zricethezav/gitleaks  
+**Stars:** 27,858 | **License:** MIT  
+**Rules:** 100+ rules in `cmd/generate/config/rules/*.go` + `config/gitleaks.toml`  
+**Format:** **TOML** (`gitleaks.toml`), not YAML. Most rules are Go files (`cmd/generate/config/rules/github.go`) that compile into the binary.
+
+### Why skip (already covered)
+
+Pi-lens already runs `gitleaks` as a dispatch runner per AGENTS.md "gitleaks (committed secrets, #130)". The 100+ gitleaks rules are already applied on every edit. Adding them as ast-grep rules would be a duplication (and AST-aware detection is *slower* than regex for these well-formed tokens).
+
+### What's worth lifting (similar to Kingfisher)
+
+The gitleaks default config at `config/gitleaks.toml` contains the canonical pattern list. Worth checking if any patterns **aren't** in CodeRabbit's 184 rules. But the dispatch runner already does this; no pi-lens work needed.
+
+### Verdict
+
+Skip.
+
+---
+
+## 7. `Kitware/CMake` — 8 Cpp ast-grep rules ★ SKIP (CMake-internal)
+
+**Source:** https://github.com/Kitware/CMake/tree/master/Utilities/ast-grep  
+**Rules:** 8 (`cmhasliteralprefix-char.yml`, `cmhasliteralsuffix-char.yml`, `cmhasprefix-char.yml`, `cmhassuffix-char.yml`, `cmstrcat-adjacent-literals.yml`, `cmstrcat-to-char-literal.yaml`, `rm-cmdbg-includes.yml`, `rm-cmdbg-macros.yml`)
+
+### Why skip
+
+All 8 are CMake-internal:
+- The `cm*` prefix = CMake's own string library (`cmStrCat`, `cmHas*`)
+- The `rm-cmdbg-*` rules are CMake-specific (`cmDebugTools.h`, `CM_DBG` macro)
+
+These are **not portable** to pi-lens's user base. Pi-lens users wouldn't have `cmStrCat` in their codebases.
+
+### Verdict
+
+Skip. Confirms the project itself uses ast-grep for internal linting — pi-lens is in good company.
+
+---
+
+## 8. `trailofbits/buttercup` — DARPA CRS ★ SKIP
+
+**Source:** https://github.com/trailofbits/buttercup  
+**Stars:** 1,609 | **License:** AGPL-3.0  
+**Type:** Cyber Reasoning System (fuzzer + LLM patch generator) for DARPA AIxCC
+
+### Why skip
+
+1. **Not a rule collection.** Buttercup is a competition-grade CRS that finds new vulnerabilities via AI + fuzzing and auto-patches them. It doesn't ship a "set of YAML rules you can adopt" — it generates rules per-task.
+2. **License:** AGPL-3.0 — incompatible with pi-lens's vendoring.
+3. **Scope mismatch:** pi-lens is a per-edit dispatcher, not a CI-time fuzzing campaign.
+
+### Verdict
+
+Skip. Noted as a Tier-1 security tool to be aware of; not a pi-lens resource.
+
+---
+
+## 9. `PurCL/RepoAudit` — ICML 2025 paper ★ SKIP
+
+**Source:** https://github.com/PurCL/RepoAudit  
+**Stars:** 409 | **License:** Purdue (permissive but custom)  
+**Type:** LLM-augmented static analysis (Null Pointer Dereference / Memory Leak / Use After Free detection) — ICML 2025 paper
+
+### Why skip
+
+1. **Not a YAML rule collection.** Rules are in Python (`src/tstool/dfbscan_extractor/Python/Python_NPD_extractor.py` etc.).
+2. **Requires LLM** — the detectors use LLM reasoning for validation. Pi-lens's per-edit hot path doesn't have LLM latency budget.
+3. **Tied to specific bug classes** (NPD, MLK, UAF) — interesting research but not a drop-in pi-lens layer.
+
+### What's useful as background
+
+The architecture (tree-sitter parser → pattern extractors → LLM validator → SARIF output) is similar to what `axsapronov/pi-extensions` does with `code-intelligence` but using a different embedding/retrieval strategy. Worth noting but not adopting.
+
+### Verdict
+
+Skip.
+
+---
+
+## 10. `noperator/slice` — SAST + LLM interprocedural ★ NOT A PORT
+
+**Source:** https://github.com/noperator/slice  
+**Stars:** 203 | **License:** MIT  
+**Type:** CodeQL + tree-sitter + LLM vulnerability scanner
+
+### Why not a port
+
+The actual rule format is **CodeQL** (`.ql` files, not `.yml`). There's 1 rule in `spec/uaf/query.ql`. CodeQL is a separate query language with its own engine — no ast-grep mapping.
+
+### What's useful
+
+The `spec/uaf/analyze.schema.json` and `spec/uaf/triage.schema.json` schemas are a template for pi-lens's own LLM-triage schema if/when we add an LLM-judged review pass (mentioned in `docs/newinspiration.md` as the `/lens-review-diff` opportunity).
+
+### Verdict
+
+Not a port source. Background context for future work.
+
+---
+
+## 11. `x0mmd/oh-my-open-pentest` — ast-grep skill ★★ REFERENCE
+
+**Source:** https://github.com/x0mmd/oh-my-open-pentest/tree/dev/packages/shared-skills/skills/ast-grep  
+**Stars:** small | **Type:** pentesting AI agent with ast-grep SKILL
+
+### What's in it
+
+7 reference docs: `cli.md`, `install.md`, `patterns.md`, `pitfalls.md`, `recipes.md`, `sgconfig.md`, `yaml-rules.md`
+
+I sampled `yaml-rules.md` (10,087 bytes) — it's a clean **practical reference** for ast-grep YAML rule authoring, covering:
+- Skeleton with all top-level fields (`id`, `language`, `rule`, `constraints`, `utils`, `transform`, `fix`, `rewriters`, `severity`, `files`, `ignores`, `metadata`)
+- Field-by-field table with required/optional + description
+- Meta-variable syntax (`$VAR`, `$$$`, `$_`)
+
+I sampled `patterns.md` (5,132 bytes) — covers meta-variable rules and common pitfalls.
+
+### Verdict
+
+**Useful as a pi-lens SKILL.md seed.** Real lift: copy `yaml-rules.md` + `patterns.md` into `skills/ast-grep-yaml/SKILL.md` in pi-lens, with attribution. Same shape as `pi-lens`'s existing `skills/` directory.
+
+**Effort:** XS (copy + adapt).  
+**Value:** Med (gives future rule authors a reference doc rather than relying on AGENTS.md prose).
+
+---
+
+## 12. `mauromedda/agent-toolkit` — ast-grep skill ★ REFERENCE
+
+**Source:** https://github.com/mauromedda/agent-toolkit/tree/main/skills/ast-grep  
+**Type:** SKILL.md (~982 bytes — very terse)
+
+### What's in it
+
+A single SKILL.md that points to patterns for "Go, Python, Bash, Terraform/HCL" using ast-grep. The README content is short — just a pointer to the patterns. Not as detailed as #11.
+
+### Verdict
+
+Strictly inferior to #11. Skip unless a future pass finds more substance.
+
+---
+
+## 13. `dustinspecker/awesome-eslint` — 4,731 stars ★ SKIP
+
+**Source:** https://github.com/dustinspecker/awesome-eslint  
+**Type:** curated list of 205+ ESLint plugins
+
+### Why skip
+
+ESLint rules are JavaScript objects, not YAML. The rule format is incompatible with ast-grep's tree-sitter-based approach. ESLint also requires a JavaScript runtime to execute the rule (pi-lens would have to embed one). Same reason pi-lens deliberately doesn't use the `@modelcontextprotocol/sdk`.
+
+### Verdict
+
+Skip. Useful only for `oxlint` cross-pollination (oxlint implements ESLint plugins in Rust; see §2).
+
+---
+
+## Concrete additions for pi-lens (revised after round 2)
+
+| # | Source | Effort | Value | Notes |
+|---|---|---|---|---|
+| 1 | **`RealHarshThakur/ast-grep-go`** (11 rules) | XS | Med | Single batch, all detector-only Go idiom rules. Existing test files are Go, need to re-create as `<id>-test.yml` per AGENTS.md. |
+| 2 | **Kingfisher regex pattern port** (~30 AI SaaS providers) | S | Med | Pure regex-shaped tokens from `crates/kingfisher-rules/data/rules/*.yml`. Skip the schema-only fields (entropy/validation/revocation). Adapt Apache-2.0 attribution. |
+| 3 | **Kingfisher `AGENTS.md` → pi-lens `skills/ast-grep-yaml/SKILL.md`** | XS | Med | Lift the rule-authoring conventions. Combine with #11's `yaml-rules.md` + `patterns.md` for completeness. |
+| 4 | **`oxlint` evaluation** | M | Low (deferred) | Worth a separate investigation — would need a separate dispatch runner OR a YAML-schema compatibility layer. Not a port. |
+
+### Updated total (across all 3 rounds of research)
+
+- **1 new rule repo to port** (`RealHarshThakur/ast-grep-go`) — 11 rules, XS effort
+- **1 new rule pattern source** (`mongodb/kingfisher`) — 30+ patterns to extract, S effort
+- **1 new skill doc** to write — SKILL.md from Kingfisher + oh-my-open-pentest, XS effort
+- **~10 other rule sources** investigated and explicitly classified as **not ports** (already covered by existing pi-lens runners, wrong format, wrong license, or wrong scope)
+
+---
+
+## Appendix A — verified-vs-unverified claim ledger
+
+| Claim | Verified? | How |
+|---|---|---|
+| Kingfisher has 585 YAML rule files, 954 rules | ✅ | `curl api.github.com/repos/.../contents/crates/kingfisher-rules/data/rules` + `wc -l` |
+| Kingfisher rules use Rust regex (`(?P<name>...)`) not ast-grep `$VAR` | ✅ | `curl raw.githubusercontent.com/.../github.yml` |
+| Kingfisher has checksum validation + HTTP revocation in YAML | ✅ | Same fetch |
+| Kingfisher license: Apache-2.0 | ✅ | README badge + LICENSE file in repo |
+| TruffleHog has 800+ detectors | ✅ | README: "TruffleHog classifies over 800 secret types" |
+| TruffleHog has 1 semgrep-format rule (`no-printing-in-detectors`) | ✅ | `curl hack/semgrep-rules/detectors.yaml` |
+| TruffleHog license: AGPL-3.0 | ✅ | README + LICENSE |
+| Gitleaks uses TOML config + Go rules | ✅ | README + `config/gitleaks.toml` + `cmd/generate/config/rules/*.go` |
+| Gitleaks license: MIT | ✅ | LICENSE file |
+| `RealHarshThakur/ast-grep-go` has 11 detector-only rules | ✅ | Repo tree (8 dir entries for `rules/*.yml`, README lists 11) |
+| CMake ships 8 ast-grep rules (all Cpp + CMake-internal) | ✅ | `git ls-tree Utilities/ast-grep/rules/` |
+| ast-grep entry exists in `analysis-tools-dev/static-analysis` | ✅ | `curl data/tools/ast-grep.yml` |
+| `mongodb/kingfisher` 1,143 stars | ✅ | GitHub API repo response |
+| `trailofbits/buttercup` AGPL-3.0 | ✅ | LICENSE file |
+| `PurCL/RepoAudit` Purdue license | ✅ | LICENSE file |
+| `dustinspecker/awesome-eslint` 4,731 stars | ✅ | README badge |
+| pi-lens currently ships 0 Go-specific ast-grep rules | ✅ | `ls rules/ast-grep-rules/rules/ \| grep -i go` → empty |
+| CodeRabbit ships 11 Go rules | ✅ | `ls rules/ast-grep-rules/coderabbit/rules/go/` |
+| `x0mmd/oh-my-open-pentest` ast-grep skill has 7 reference docs | ✅ | `git ls-tree` |
+| Kingfisher rule `AGENTS.md` has the rule-authoring conventions cited | ✅ | `curl raw.githubusercontent.com/.../AGENTS.md` |
+| pi-lens already runs `gitleaks` as a dispatch runner | ✅ | AGENTS.md "gitleaks (committed secrets, #130)" |
+| pi-lens already runs `trivy secret` | ✅ | AGENTS.md "Secrets (`gitleaks` + `trivy secret` + ...)" |
+
+All claims verified. **No `[unverified]` markers needed.**
+
+---
+
+## Appendix B — repo-by-repo decision matrix
+
+| Repo | Stars | License | Format | Direct port? | Reference value |
+|---|---|---|---|---|---|
+| `RealHarshThakur/ast-grep-go` | 2 | NOASSERTION | ast-grep YAML | **Yes** | High — direct fill |
+| `analysis-tools-dev/static-analysis` | 14,644 | MIT | meta | No | Med — future tool discovery |
+| `HerringtonDarkholme/awesome-tree-sitter` | 20 | N/A | meta | No | Med — redirects to other finds |
+| `mongodb/kingfisher` | 1,143 | Apache-2.0 | secret-scanner YAML | No (schema diff) | High — pattern templates, AGENTS.md |
+| `trufflesecurity/trufflehog` | 26,870 | AGPL-3.0 | Go + YAML examples | No | Low (already covered) |
+| `zricethezav/gitleaks` | 27,858 | MIT | TOML + Go | No | Low (already a runner) |
+| `Kitware/CMake` | n/a | BSD-3 | ast-grep YAML | No (CMake-internal) | Low (project uses ast-grep — sanity check) |
+| `trailofbits/buttercup` | 1,609 | AGPL-3.0 | Go + LLM | No | Background |
+| `PurCL/RepoAudit` | 409 | Purdue | Python tree-sitter | No | Background |
+| `noperator/slice` | 203 | MIT | CodeQL | No | Schema reference for future LLM-triage |
+| `x0mmd/oh-my-open-pentest` | small | MIT | SKILL.md | No | High — SKILL.md content |
+| `mauromedda/agent-toolkit` | small | TBD | SKILL.md | No | Low |
+| `dustinspecker/awesome-eslint` | 4,731 | CC0-1.0 | meta | No | Low (different format) |
+
+---
+
+## Appendix C — what I'd do differently in a round 3
+
+If asked to dig deeper:
+
+1. **Read actual Kingfisher rules for 5 representative providers** (openai, anthropic, aws, github, huggingface) to understand the *patterns* — not the schema — and estimate the per-pattern port cost more precisely. The current "30 patterns" estimate is rough.
+
+2. **Check `noperator/slice/spec/uaf/analyze.schema.json`** in detail — that's the schema that real LLM-triage uses for vulnerability review. Could directly inform the `/lens-review-diff` JSON contract in pi-lens.
+
+3. **Check `trailofbits/buttercup/program-model/src/buttercup/program_model/api/tree_sitter.py`** — this is the production tree-sitter integration Trail of Bits uses for CodeQL augmentation. Worth comparing to pi-lens's `clients/tree-sitter-client.ts`.
+
+4. **Audit the `data/tools/` list in `analysis-tools-dev/static-analysis` for tools that overlap with pi-lens's 47 dispatch runners** — would surface any gaps. Tools I haven't evaluated: `archunit`, `archunitnet`, `bearer`, `credo` (already a runner per `credo.ts`), `cpp-linter-action`, `datree`, `kics`, `kube-linter`, `kubescape`, etc.
+
+5. **Check if there's an `oxlint-rules` repo** that ships ESLint-rule-format YAML/JSON that could be ported. Oxlint's plugin ecosystem uses ESLint-compatible config, so oxlint plugin configs would be a third format (after ast-grep YAML and Gitleaks TOML) worth evaluating.
+
+But these are diminishing returns. The big-finds in this round were Kingfisher (pattern source) and `ast-grep-go` (direct port). Round 3 would refine the estimates; it wouldn't find new sources.

package/docs/language-coverage.md

@@ -0,0 +1,48 @@
+# Language Coverage
+
+pi-lens supports **36+ languages** through dispatch runners and LSP integration.
+
+Formatting uses a single selected formatter per file: explicit project config wins, otherwise pi-lens uses a smart default where supported, and config-first ecosystems do not autoformat without config.
+
+Dispatch is diagnostics-oriented: automatic formatting and safe autofix happen in the post-write pipeline rather than through dispatch format-check runners.
+
+| Language              | LSP | Dispatch Runners                                                                                               | Formatter               |
+| --------------------- | --- | -------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| JavaScript/TypeScript | ✓   | lsp, ts-lsp, biome-check-json, tree-sitter, ast-grep-napi, type-safety, similarity, fact-rules, eslint, oxlint | biome, prettier         |
+| Python                | ✓   | lsp, pyright, ruff-lint, tree-sitter                                                                           | ruff, black             |
+| Go                    | ✓   | lsp, go-vet, golangci-lint, tree-sitter                                                                        | gofmt                   |
+| Rust                  | ✓   | lsp, rust-clippy, tree-sitter                                                                                  | rustfmt                 |
+| Ruby                  | ✓   | lsp, rubocop, tree-sitter                                                                                      | rubocop, standardrb     |
+| C/C++                 | ✓   | lsp, cpp-check, tree-sitter                                                                                    | clang-format            |
+| Shell                 | ✓   | lsp, shellcheck                                                                                                | shfmt                   |
+| Fish                  | ✓   | lsp, fish-indent                                                                                               | fish_indent             |
+| CSS/SCSS/Less         | ✓   | lsp, stylelint                                                                                                 | biome, prettier         |
+| HTML                  | ✓   | lsp, htmlhint                                                                                                  | prettier                |
+| YAML                  | ✓   | lsp, yamllint, actionlint (GitHub workflows)                                                                   | prettier                |
+| JSON                  | ✓   | lsp                                                                                                            | biome, prettier         |
+| Svelte                | ✓   | lsp                                                                                                            | —                       |
+| Vue                   | ✓   | lsp                                                                                                            | —                       |
+| SQL                   | —   | sqlfluff                                                                                                       | sqlfluff                |
+| Markdown              | —   | spellcheck, markdownlint, vale                                                                                 | prettier                |
+| Docker                | ✓   | lsp, hadolint                                                                                                  | —                       |
+| PHP                   | ✓   | lsp, php-lint, phpstan                                                                                         | php-cs-fixer            |
+| PowerShell            | ✓   | lsp, psscriptanalyzer                                                                                          | psscriptanalyzer-format |
+| Prisma                | ✓   | lsp, prisma-validate                                                                                           | —                       |
+| C#                    | ✓   | lsp, dotnet-build                                                                                              | csharpier               |
+| F#                    | ✓   | lsp                                                                                                            | fantomas                |
+| Java                  | ✓   | lsp, javac                                                                                                     | google-java-format      |
+| Java + Lombok         | ✓   | JDT LS launched with `-javaagent:<lombok.jar>` when Lombok is detected and a jar is found (`PI_LENS_LOMBOK_JAR` / `LOMBOK_JAR`, project `.lombok/lombok.jar`, or Maven/Gradle cache) | google-java-format      |
+| Kotlin                | ✓   | lsp, ktlint, detekt                                                                                            | ktlint                  |
+| Swift                 | ✓   | lsp, swiftlint                                                                                                 | swiftformat             |
+| Dart                  | ✓   | lsp, dart-analyze                                                                                              | dart format             |
+| Lua                   | ✓   | lsp                                                                                                            | stylua                  |
+| Zig                   | ✓   | lsp, zig-check                                                                                                 | zig fmt                 |
+| Haskell               | ✓   | lsp                                                                                                            | ormolu                  |
+| Elixir                | ✓ (ElixirLS default, Expert alternate) | lsp, elixir-check, credo                                                                   | mix format              |
+| Gleam                 | ✓   | lsp, gleam-check                                                                                               | gleam format            |
+| OCaml                 | ✓   | lsp                                                                                                            | ocamlformat             |
+| Clojure               | ✓   | lsp                                                                                                            | cljfmt                  |
+| Terraform             | ✓   | lsp, tflint                                                                                                    | terraform fmt           |
+| Nix                   | ✓   | lsp                                                                                                            | nixfmt                  |
+| TOML                  | ✓   | lsp, taplo                                                                                                     | taplo                   |
+| CMake                 | ✓   | lsp                                                                                                            | cmake-format            |