Beagle SCM

SPOT-001: shared/spot.js — the ONE file-location resolver (fragment anchors, symbols, needles)

Superseded by SPOT-002: fragment grammar re-ruled 2026-07-18 (#L123 line, #needle substr, #/re/, #'tok pattern'; symbol forms dropped).

Input

Context

Several consumers need "find a location in a file" and each is about to roll its own: why: fragment scoping (/todo/WHY/WHY-002), the planned spot-view rebuild (today's views/spot/search.js + match.js, JAB-021), and later cat:/diff: scoped hunks. The C side already fixed the vocabulary: HUNKu8sMakeURI emits #L42 / #sym / #sym:L42 / #'quoted body':L42 (dog/HUNK.c:60), HUNKu8sFragSplit extracts, and symbols are the tokenizer's N-def tags (CAPOFindFunc, spot/CAPO.c:579).

• One resolver, many callers: the utility returns byte spans; paging/hunking/rendering stays with the caller.
• Adopt the C fragment conventions VERBATIM — do not invent a second grammar (#function foo is out; #authorIdent / #authorIdent:L41 is the form).

Goals

shared/spot.js: parse a locator string, resolve it over (source bytes, ext) to match spans.

• parse(frag) → a typed locator; find(loc, src, ext, toks?) → ascending [{lo, hi, line, col}] byte spans (toks optional: caller may pass a pre-parsed token buffer, else tok.parse inside).
• Locator syntaxes, ONE grammar shared with hunk URIs:
  1. L42, L42-60 — line / line range;
  2. 42.7-43.2 — line.col span (the why-runs form, so a why-runs row is itself a valid locator);
  3. sym — a symbol, matched at an N-def token;
  4. sym:L42 — symbol with a line hint (nearest def to the hint wins — tolerant to drift);
  5. 'quoted body' — structural SPOT needle (a-z bind one token, A-Z a block, two-space gap), percent-unescaped per hunk_frag_esc;
  6. /re/ — regex needle (the search view's regex matcher).
• Reuse, not re-roll: lift views/spot/match.js matchers (grep/regex/structural) into or under shared/spot.js; the rebuilt spot view and search scaffold consume THIS module.

Constraints

• Hashlets win: a 6..40-hex fragment resolves via resolve_hash FIRST — spot.js never sees it; non-hex (or :L-suffixed) strings are locators. Policy note in resolve_hash.js, not a fork of it.
• NO manual parsing beyond the locator grammar itself; source matching rides tok.parse / TokStream / the existing matchers.
• KNOWN GAP (search.js parity caveat): the S→N DEF retag has NO JS binding — tok.parse is lexer-only. Symbol locators need either the new binding (MUST-ASK) or an explicit v1 heuristic; the choice is a design decision below, not an accident.
• Spans are byte-truth; line/col are derived in the same walk (no second scan).

WIP

Design decisions

• spot's substrate is the HUNK, not raw bytes: find/window take (text, toks) and skip hidden tags (U=20, O=14) in matching AND line/col math; spans return in hunk byte space. Raw-file callers tok.parse first — one code path, a why/diff hunk never re-tokenizes.
• Scoping = clipping, not per-view gating: clip(text, toks, lo, hi) (HUNKu32sClip twin, CAPOBuildHunk's own move) cuts a sub-hunk — views build their FULL hunk once, then hunks() windows+clips it. Clip boundaries snap to token edges; a hidden O sticks to its visible predecessor (never split a [visible][O] pair).
• Gutter line numbers come from the PRE-clip count — absolute file lines survive scoping.
• Any emitted hunk is valid input — the pager gets in-view search/jump (/sym) from the SAME find.
• v1 symbol heuristic (until the DEF binding lands): match the symbol bytes as a whole identifier token at column-0-anchored context (line starts a declaration-shaped run); sym:L42 needs only nearest-line disambiguation, so the heuristic bar is low.
• find returns ALL matches; callers pick (first / nearest-to-hint / all) — the resolver does not guess caller policy.
• The module is store-blind and URI-blind: hunk + locator in, spans/sub-hunks out; URI/fragment splitting stays with resolve_hash + the caller (HUNKu8sFragSplit twin lives here only as parse).

TODOs

• shared/spot.js: parse + find over (text, toks), line/line.col/symbol/needle/regex locators
• clip (HUNKu32sClip twin) + window/hunks — sub-hunk cutting, O-pair-safe
• lift match.js matchers to shared (search scaffold re-pointed, no behavior change)
• percent-unescape for quoted bodies (hunk_frag_esc twin)
• repro: table-driven golden — each syntax over a fixture file, incl. hex-fragment NON-capture
• decide the DEF binding: ask for tok DEF-pass export vs ship v1 heuristic (/todo/WHY/WHY-002 blocks on symbol anchors only)

Blockers and bummers

• S→N DEF retag has no JS binding (JAB-021 parity caveat) — symbol precision capped until resolved.

Outcome

(pending)