lakeday-org/perch: Semantic code linting with Jev

perchscan.com  ·  docs

Semantic code linting with Jev.

!Writing a rule, and perch catching this README with it

Getting started

npm install -g @lakeday/perch
export PERCH_API_KEY=...

$ perch scan
checkout.py
  ID        Line  Severity  Type    Confidence  Problem                     Method
  bdc67421    14  P1 (0.8)  defect         81%  wrong_order                 place_order
  ddc5c917    24  P1 (0.8)  defect         92%  inverted_condition          can_fulfil
cart.py
  ID        Line  Severity  Type    Confidence  Problem             Method
  287bfb9d     9  P1 (1.0)  defect         90%  off_by_one          subtotal
  80d6ebbb    29  P1 (1.4)  defect         89%  unhandled_null      cheapest
✖ 20 problems in 5 files, all failing

perch issues lists them worst first. perch issues opens one up. perch check asks again after a fix, and records what it finds nowhere.

Agent skills

perch setup claude-code   # .claude/skills/perch/SKILL.md
perch setup codex         # .codex/skills/perch/SKILL.md
perch setup pi            # .pi/skills/perch/SKILL.md
perch setup cursor        # .cursor/rules/perch.mdc

Semantic linting

Extend perch with custom rules, in perch.yaml:

- name: env-read-once
  where: "src/*/.js"
  each: method
  min: 70
  ensure: >
    This method takes its configuration as arguments. Reading process.env is the
    command line's job.

Documentation

| | | | --- | --- | | Getting started | Install, the key, the first scan. | | Reading issues | The list, the filters, closing what does not matter. | | Semantic linting | where, each, sees, min, gate, and the longhand grammar. | | Checking a change | perch check on work in progress. | | perch in CI | What a build can gate on, and what it cannot. | | Command reference | Every command, its flags, and what each exit code means. | | Inside a scan | The graph walk, the questions, and how probabilities turn into a ranking. |

Perch files

| Location | Contents | | --- | --- | | .perch/ | Generated scan results and cache files, alongside the committed files below. Use --out to choose another results location. | | .perch/rules/ | Custom rules split across .yaml and .yml files. Commit these files. | | .perch/closed.jsonl | Dismissed findings and their reasons. Commit this file. | | perch.yaml | Custom rules. Updated by perch rules add, edit, and remove. | | .claude/, .codex/, .pi/, .cursor/ | Instructions installed for the selected assistant by perch setup . |

Development

npm run check     # lint, typecheck, test
npm run build     # bundle src/cli.js into dist/cli.mjs

From a checkout: npm install && npm run build && npm link puts perch on the path.