A search rule is globally limited to 400 units

[jbrown9513]

MAX_UNITS = 400, applied in two places in src/units.js:

// searchUnits
const units = rank(rule, selectUnits(rule, {...}).slice(0, MAX_UNITS));

// askUnits, for ordinary file rules
for (const unit of selectUnits(rule, {...}).slice(0, MAX_UNITS)) {

Nothing reports the truncation.

An ensure_present rule over more than 400 units reads 400 and reports that nothing has the thing, even when unit 401 has it. An ensure rule over more than 400 files checks 400 and passes on the rest. This repository has 416 methods, so a method rule over the whole tree is already at the line.

Say when it stops

A rule that stops at a limit has not searched its scope, so it cannot report the same answer as one that did. It should say it stopped, and perch doctor should list it the way it lists a rule that covered nothing.

Let a rule set its own limit

The global 400 is arbitrary. A search is the most expensive thing perch does: ensure_absent over src/**/*.js with each: method asks about every method in src before it can say nothing has the thing, which is what a clean codebase hits every run. Three such rules account for most of a scan here.

- name: no-dead-command
  where: "src/**/*.js"
  each: method
  search_limit: 50
  ensure_absent: A command or flag that is parsed and then never used.

Units are already ranked before a search reads them, so a limit takes the top N rather than an arbitrary N.

Worth deciding with it: what the default should be, and whether it should be lower than 400.

[MrJev]

Two things from re-testing this at eaa137b, both about the shape of the fix rather than the limit itself.

ensure_absent is the direction that ends in a green build. The issue names ensure_present reporting absence and ensure passing on the rest; the same cut also lets a rule pass while the repository contains exactly what the rule forbids.

451 files, one rule, the planted credential in the file that sorts last:

rules:
  - name: no-hardcoded-credentials
    where: "**/*.js"
    ensure_absent: >
      A hardcoded password or API key in the source.

$ perch scan --filter rule=no-hardcoded-credentials
✓ nothing to report
capfix at commit f4ba8ff: 451 methods, read 0
400 requests  4k tokens in / 400 out
EXIT=0

src/zz-planted.js holds DB_PASSWORD = 'planted-credential-marker-9c41'. We counted the marker on the wire against a local stand-in: zero requests carried it, and 400 of the 451 files were named across the run. The rule did not decide the file was fine; it never saw it. Exit 0 either way.

The cap does not take the top N. The issue says "Units are already ranked before a search reads them, so a limit takes the top N rather than an arbitrary N." In searchUnits the slice runs before rank:

const units = rank(rule, selectUnits(rule, { scan, graph, files, tree, inScope }).slice(0, MAX_UNITS));

So the 400 are the first 400 in selectUnits order — the git tree, alphabetically — and rank only orders what survived. Whether a file is searched depends on its path, which is why a marker in src/zz-*.js is reliably invisible and one in src/aa-*.js is reliably read. If search_limit is meant to take the top N, rank has to move ahead of the slice; otherwise a smaller default makes the path dependence sharper.

Method for both: Node 24 in Docker, PERCH_BASE_URL pointed at a local stand-in that answers every question and logs every request, no Jev calls.

[jbrown9513]

Ensure_absent also short circuits after the first positive finding.

This can be quite frustrating for users/agents who fix the triggered issue, scan again, get another issue from same rule.