Introducing Perch

Perch on an example order service.

Perch is a semantic linter for identifying bugs and security issues in your code. Perch is powered by TypeSafe’s Jev language model. Perch can be used to lint your code for likely defects, but can also be used to enforce project specific linting rules written in natural language. Perch is designed to run in the terminal, as part of a coding agent workflow, or in CI/CD.

Adding rules

To add your own rules based on project specific requirements, add them to your perch.yaml file. For example, if you had a requirement that an order which was already refunded could not be refunded again, you could add a rule like:

- name: refund-once
  where: refund.py
  each: method
  ensure: Refunded orders cannot be refunded again.

And then run Perch with the command:

perch check refund.py::refund --rules refund-once

An example of this in action is shown below, where we start with code that fails the refund-once rule, then add a guard clause to pass the rule.

Other examples include ensuring all endpoints are authorized, ensuring the CRM is not updated with incomplete information, or ensuring agent generated code has adequate documentation.

Running Perch on your project

To run Perch on your project, simply run:

perch scan

Perch will parse all tracked code in your repository, build a call graph, and evaluate each method with Jev. Results will include the file and method name, the type of issue found, and a confidence score from the model. You can inspect the results with perch issues, or re-run on a file after editing with perch check.

The demo at the top of this page is from a small order service we built and planted with bugs. A fresh scan today (Sep 20) shows 19 findings across 14 methods, including a variety of issues from off-by-one errors to weak crypto. The GIF above highlights a selection of these, the rest are included below. Note that the scores may vary as each request is fresh.

$ perch scan --filter type=defect,security
cart.py
  ID        Line  Severity  Type    Confidence  Problem                     Method
  287bfb9d    10  P1 (1.1)  defect         89%  off_by_one                  subtotal
  287bfb9d    10  P1 (1.1)  defect         86%  does_not_do_what_it_claims  subtotal
  48a02173    17  P1 (1.4)  defect         70%  off_by_one                  apply_discount
  44c8d48a    23  P1 (1.2)  defect         72%  does_not_do_what_it_claims  is_eligible_for_free_sh…
  44c8d48a    23  P1 (1.2)  defect         71%  inverted_condition          is_eligible_for_free_sh…
  80d6ebbb    30  P2 (1.5)  defect         88%  unhandled_null              cheapest
  80d6ebbb    30  P2 (1.5)  defect         77%  does_not_do_what_it_claims  cheapest

inventory.py
  ID        Line  Severity  Type    Confidence  Problem                     Method
  0d0e3f8a     9  P1 (0.9)  defect         89%  wrong_return_value          reserve
  0d0e3f8a     9  P1 (0.9)  defect         81%  does_not_do_what_it_claims  reserve
  0d0e3f8a     9  P1 (0.9)  defect         72%  race_condition              reserve
  225c1645    26  P1 (0.9)  defect         90%  bad_state_change            release_expired

storage.py
  ID        Line  Severity  Type      Confidence  Problem                Method
  5a623390    15  P1 (1.3)  defect           78%  error_ignored          load_order
  5a623390    15  P1 (1.3)  security         71%  missing_authorization  load_order

checkout.py
  ID        Line  Severity  Type    Confidence  Problem                     Method
  bdc67421    15  P1 (0.8)  defect         82%  wrong_order                 place_order
  ddc5c917    25  P1 (0.9)  defect         94%  does_not_do_what_it_claims  can_fulfil
  ddc5c917    25  P1 (0.9)  defect         92%  wrong_return_value          can_fulfil
  4f8bf5dc    31  P1 (0.7)  defect         70%  bad_state_change            refund

auth.py
  ID        Line  Severity  Type      Confidence  Problem         Method
  c3ff1609     7  P1 (0.7)  security         78%  weak_crypto     token_for
  c25aa687    14  P0 (0.4)  defect           73%  unhandled_null  cancel_order

✖ 19 problems in 5 files, all failing

Captured September 20 from Perch’s example order service. The full output records the run.

Using Perch with an agent

To use Perch with an agent, have the agent run Perch after it has made code or documentation changes. The agent can then inspect the results and make corrections as needed before committing the changes. You can also add rules to Perch to be run in CI to ensure future changes adhere to your project’s standards.

This is especially useful for documentation rules, where the agent can be corrected once and then the rule can be added to Perch to ensure future changes adhere to the same standards.

Getting started

Install Perch with:

npm install -g @lakeday/perch

Check out the quick start guide to get started. Perch is open source and available on GitHub. You can also check out the examples to see how Perch can be used to enforce rules for things like refund logic, API permissions, CRM updates, and documentation standards.