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 等编程助手可以直接使用它。
怎么让它跑起来？在 console.typesafe.ai 创建 API 密钥，把它设置为 PERCHAPIKEY 环境变量，然后运行 perch issues 查看首次扫描结果。
扫描之前必须有 API 密钥吗？需要，perch 调用托管服务，必须先有从 console.typesafe.ai 生成的 PERCHAPIKEY 才能运行。
问题的排序是固定的规则检查，还是更偏主观判断？扫描的工作方式是遍历一个问题图并把概率转换成排序，因此结果更接近加权判断，而不是确定性的规则匹配。
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 16Releasev0.4.3Oct 11
Age
1mo
Commits · 90 Days