Loading
Settle the num_context_lines contract for exact code search
What
Amends specs/exact-code-search-result-limits/SPEC.md to state the
num_context_lines contract for exact code search, and removes the
contradiction with specs/advanced-code-search/SPEC.md. Also corrects the
stale row in specs/zoekt-query-grpc-contract/SPEC.md.
Why
Two specs disagreed. exact-code-search-result-limits recorded a flat 1,
read off the hardcoded CONTEXT_LINES_COUNT in the Zoekt client;
advanced-code-search recorded a 0-20 clamp defaulting to 2. The hardcoded
value is the defect gitlab-org/gitlab#599116 reports: the REST API declares
values: 0..MAX_NUM_CONTEXT_LINES and the Zoekt path discards it. Shipping
the fix without settling the contract would leave the corpus contradicting
itself about what the API promises.
The settled contract: both backends admit 0-20; the defaults differ on purpose, 2 for advanced search and 1 for exact code search, which renders a caller-controlled number of chunks per file rather than one snippet.
Two behaviours a reader cannot infer from the API declaration are now
recorded: the webserver returns fewer lines than asked for near the start or
end of a file, and the indexer forces the value to 0 on an aggregation-only
request (internal/search/grpc.go, the AggregatesLanguage branch).
Spec status
- Feature:
specs/exact-code-search-result-limits/SPEC.md - Status in frontmatter:
implemented, except the 0-20 clamp on the Zoekt path, which lands in the follow-upgitlab-org/gitlabmerge request. - Implementation MR: to follow in
gitlab-org/gitlab, citing this spec path and merge sha.
Verification
How the claims were checked
Every citation this diff adds was read from the GitLab API at the live tip of
master (e046d98e)
and asserted to contain the claimed code, rather than resolved against a local
checkout.
scripts/check_specs.py passes over all 70 specs in the corpus.
The claim that the webserver honours a caller-supplied value above 1 was
measured, not assumed: a gitlab-zoekt webserver was run over a purpose-built
one-file index and sent the v2 payload Rails sends, varying only
num_context_lines. Returned context lines either side of a match at line 15
of a 30-line file:
| requested | before | after |
|---|---|---|
| 0 | 0 | 0 |
| 1 | 1 | 1 |
| 2 | 2 | 2 |
| 5 | 5 | 5 |
| 20 | 14 | 15 |
The last row is the file boundary, which is the source of the "fewer than requested" clause.
What I did not verify
The citation pinned @jmason-w2118-zoekt-num-context-lines names code on the
implementation branch, which does not exist on master yet; it resolves once
that merge request merges. The 0-20 clamp for the Zoekt path is specified here
and lands in that merge request, so until it merges the spec describes the
contract rather than shipped behaviour for that one clause. The probe ran
against a locally built single-shard index, not a production corpus.
Edited by John Mason