fix(pi-fff): cap grep total results with pageSize, clamp context (#768)

[gustav-fff]

Closes #768

Root cause

ffgrep / fff-multi-grep pass the documented limit only as maxMatchesPerFile (packages/pi-fff/src/index.ts:774,806,1051 pre-fix), never as pageSize. Per the SDK (packages/fff-node/src/fff-api.ts:439-440, 545-546), maxMatchesPerFile caps matches per file while pageSize caps total matches per page (default 50). So limit: 5 returns up to a full SDK page when matches are spread across files. context was also passed through unbounded — large values multiply output size with no cap.

Fix

Pass the effective limit as pageSize (clamped to 50) alongside maxMatchesPerFile on both grep tools and the fuzzy fallback, so the cap applies to total matches per page; the existing nextCursor still exposes the rest. Clamp context to [0, 20] via a clampContext helper.

Steps to reproduce

Pre-fix, on origin/main:

cargo build --release -p fff-c
bun install

// repro.ts
import { FileFinder } from "./packages/fff-node/src/index.ts";
const r = FileFinder.create({ basePath: "./crates" });
const f = r.value;
await f.waitForIndexReady(15000);
// mimics pi-fff ffgrep { limit: 5 } pre-fix: only maxMatchesPerFile, no pageSize
const g = f.grep("use ", { mode: "plain", smartCase: true, maxMatchesPerFile: 5 });
console.log("returned:", g.value.items.length);   // expect <= 5

bun run repro.ts

Expected: at most 5 matches for limit: 5.
Actual (pre-fix):

returned: 54

54 matches across 14 files for a documented limit of 5.

How verified

Rebuilt fff-node, ran the same grep with the post-fix options (maxMatchesPerFile: 5, pageSize: 5):

total matches returned in ONE page: 8
nextCursor present (excess retrievable): true
page2 matches: 5

Output drops from 54 to a bounded page (page-boundary soft cap) with the remainder reachable via cursor. bunx tsc --noEmit -p packages/pi-fff/tsconfig.json passes clean; biome reports only pre-existing issues (identical on origin/main).

Automated triage via Gustav. Honk-Honk 🪿

Summary by CodeRabbit

• Improvements
  • Limited search result pages to a maximum of 50 items.
  • Restricted surrounding context to 0–20 lines for grep searches.
  • Standardized handling of invalid, negative, fractional, and oversized context values.
  • Fuzzy search now follows the same page-size limit and does not include context.

[coderabbitai]

📝 Walkthrough

Walkthrough

grep, fuzzy grep, and multi-grep now cap page sizes at 50. Context values are normalized to integers from 0 through 20. Schemas document the context limit.

Changes

Grep bounds

Layer / File(s)	Summary
Parameter bounds and schemas packages/pi-fff/src/index.ts	Adds page-size and context limits. Adds clampContext. Updates grep and multi-grep schemas.
Grep and multi-grep execution packages/pi-fff/src/index.ts	Applies capped page sizes to total and per-file results. Applies normalized context values to grep, fuzzy fallback, and multi-grep.

Estimated code review effort: 2 (Simple) | ~10 minutes

Mergeability Score: 🟡 Moderate · up to 90d8d

The change bounds grep output and context, but fuzzy-search pagination can switch behavior on subsequent pages when a cursor is returned, potentially producing missing, duplicate, or changed results. This concrete correctness issue should be fixed or explicitly accepted before merge.

Suggested reviewers: dmtrkovalenko, mrjoedang

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the page-size cap and context clamping implemented in the pull request.
Linked Issues check	✅ Passed	The changes address issue #768 by capping grep pages at 50 and clamping context values to 0–20.
Out of Scope Changes check	✅ Passed	The changes are limited to grep pagination and context validation described in issue #768.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch triage-bot/issue-768

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/pi-fff/src/index.ts`:
- Around line 822-823: Prevent fuzzy fallback results from emitting a cursor
that cannot resume the same fuzzy query: update the pagination flow around the
fuzzy search and cursor construction near maxMatchesPerFile/pageSize to either
persist the fuzzy query and mode in the cursor and restore them on the next
request, or suppress nextCursor for fuzzy results. Add a regression test
covering a paginated fuzzy fallback and verifying subsequent requests do not
switch to the normal exact-query picker.grep path.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 54047dbf-799a-4df3-8564-6486b2438eac

📥 Commits

Reviewing files that changed from the base of the PR and between cc289f0 and 90d8df5.

📒 Files selected for processing (1)

• packages/pi-fff/src/index.ts

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Do not emit a broken fuzzy cursor.

pageSize can now make the fuzzy fallback return nextCursor. The next request skips the fallback because params.cursor is set, then resumes the normal picker.grep path with the exact query and non-fuzzy mode. It does not replay fuzzyQuery with mode: "fuzzy". The native wrapper also forwards only cursor._offset in packages/fff-node/src/finder.ts Lines 368-386.

Store the fuzzy mode and query with the cursor, or suppress cursors for fuzzy results. Add a regression test.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/pi-fff/src/index.ts` around lines 822 - 823, Prevent fuzzy fallback
results from emitting a cursor that cannot resume the same fuzzy query: update
the pagination flow around the fuzzy search and cursor construction near
maxMatchesPerFile/pageSize to either persist the fuzzy query and mode in the
cursor and restore them on the next request, or suppress nextCursor for fuzzy
results. Add a regression test covering a paginated fuzzy fallback and verifying
subsequent requests do not switch to the normal exact-query picker.grep path.