lakeday-org/perch

perch – AI‑powered semantic code linting

What it is – perch is a command‑line tool that scans source code and reports semantic defects (e.g., wrong‑order calls, off‑by‑one errors, misuse of environment variables). The analysis is driven by a large‑language‑model service from TypeSafe (accessed via an API key). It goes beyond syntactic linters by asking the model to reason about the intent of each method and rank findings by confidence.

How it works

• perch scan walks the project, builds a graph of functions/methods, and sends concise “questions” to the LLM. The model returns a probability that a given pattern is a defect; perch turns that into a severity score (P1, P2, …) and prints a table.
• Results are cached in a hidden .perch/ folder so repeated runs are fast.
• You can query the list (perch issues), drill into a single finding (perch issues <id>), and re‑check after a fix (perch check <id>).

Extending it – Custom rules are written in a simple YAML format (perch.yaml or files under .perch/rules/). A rule specifies:

• where – file glob pattern
• each – the granularity (method, function, etc.)
• min – minimum confidence to surface the issue
• ensure – a natural‑language description of the desired behaviour.

Assistant integration – perch can install “skills” for various LLM assistants (Claude, Codex, Pi, Cursor). The perch setup <assistant> command drops a markdown file with prompts that the assistant can use to suggest fixes.

Getting started

npm install -g @lakeday/perch
export PERCH_API_KEY=$(cat ~/.perch_key)   # obtain from console.typesafe.ai
perch scan

The CLI prints a table of problems, their confidence, and the method where they were found.

Typical workflow

1. Run perch scan locally or in CI.
2. Review the highest‑severity items with perch issues.
3. Fix code, then run perch check <id> to verify the issue is gone.
4. Dismiss false positives by adding entries to .perch/closed.jsonl.

Documentation & ecosystem – Full docs are hosted at https://docs.perchscan.com covering installation, rule language, CI integration, and the internal “graph walk”. The project is published on npm (@lakeday/perch) and includes a CI badge, type‑checking, and unit tests.

Maturity – The repository ships a stable CLI, automated tests, and CI. It requires an external API key, so the core analysis depends on the TypeSafe service, but the surrounding tooling (rule engine, caching, CI integration) is open‑source.

License – MIT (see LICENSE).

---

Perch is a genuine AI‑augmented linting platform aimed at developers who want higher‑level, model‑driven code quality checks without writing their own prompts.