perch README

The project's README from github.com/lakeday-org/perch. As one markdown file: README.md.

perch

npm ci node license perch

perchscan.com  ·  docs

Semantic code linting with Jev.

Writing a rule, and perch catching this README with it

Getting started

Create an API key at console.typesafe.ai and set it as PERCH_API_KEY.

npm install -g @lakeday/perch
export PERCH_API_KEY=<your TypeSafe 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 <id> opens one up. perch check <id> 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 <directory> 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 <assistant>.

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.

perch (lakeday-org/perch)

Searching Database…

353 ·GitHub
Perch
Что это?Perch — это семантический линтер кода для командной строки, который ищет в кодовой базе реальные проблемы с помощью Decision Models, а не простых синтаксических правил, и ранжирует найденное от худшего к лучшему.
Это инструмент CLI или он работает внутри моего редактора?Это прежде всего инструмент CLI (perch issues, perch check), но он также устанавливает «агентские навыки», чтобы ассистенты для кодинга вроде Claude Code, Codex, Cursor и pi могли использовать его напрямую.
Как его запустить?Создайте API-ключ на console.typesafe.ai, задайте его как переменную окружения PERCHAPIKEY, затем выполните perch issues, чтобы увидеть результаты первого сканирования.
Нужен ли API-ключ, прежде чем что-то сканировать?Да, perch обращается к хостинговому сервису и требует PERCHAPIKEY, сгенерированный на console.typesafe.ai, прежде чем сможет запуститься.
Ранжирование проблем — это жёсткая проверка по правилам или скорее оценочное суждение?Сканирование работает как обход графа вопросов с превращением вероятностей в рейтинг, поэтому результаты ближе к взвешенному суждению, чем к детерминированному совпадению по правилам.
В чём разница между perch issues и perch check?perch issues выводит все находки от худших к лучшим и позволяет открыть одну из них; perch check повторно сканирует работу в процессе после исправления и записывает, что всё ещё находит.
Что хранится в .perch/closed.jsonl?Там фиксируются отклонённые вами находки вместе с указанными вами причинами; файл задуман для коммита вместе с правилами.
С какими агентами для кодинга может интегрироваться perch?perch setup устанавливает инструкции в папки .claude/, .codex/, .pi/ или .cursor/, охватывая Claude Code, Codex, pi и Cursor.
What are similar projects?openqodex, jevlint, knip, jev-code-reviewer, ast-grep, oc, GitNexus, react-doctor
Which topics is it in?tree-sitter, code-analysis, linter, devtools, code-quality, code-review, static-analysis, ci, cli-tool, cursor, command-line, agent-skills
Creator
lakeday-org
Size
40.4 MB
Stars
353
Updated
CommitOct 18Releasev0.4.3Oct 11
Age
1mo
Commits · 90 Days