Beagle SCM

BEE-073: link anchors beyond the line — :'grep', :"snippet", :/regex/, :symbol

Ruled 2026-09-18 (gritzko): links follow Pike's sam/Acme file:address shape, not full URIs. After the target's : comes exactly ONE anchor: a line, a substring '…', a spot snippet "…", a regex /…/, or a bare symbol. Only the line anchor is rev-proofed with a hashlet; the rest resolve in the current tree, first match wins. This umbrella holds the ruled grammar; the work is in the four subs.

Input

Context

• Grammar of record: tok/LINK.rl:88:GG line, tok/LINK.rl:89:GG commit: digits, or digits plus a 2..10 char hashlet (DOG-043).
• Precedent: sam addresses (file:12, file:/re/), which the Plan 9 plumber resolves off plain prose; an index resolves ours.
• Be's URI fragments locate four ways already (SPOT-002): #L123, #needle, #/re/, #'pat'; links differ, see below.
• HUNKu8sMakeURI (HUNK.c:1621) titles hunks path#sym:L42, so the symbol anchor has a twin already.

Goals

• :30, :30:12, :30:LjJu stay as they are; a hashlet always carries a non-digit, an all-digit second code is a column.
• :'Compose URI' is a substring, :/CAPO\w+Grep/ a regex.
• :"ok64 $1 = OK;" is a spot snippet; its variables wear a $ (2026-09-18), so plain code in it is always literal.
• $1..$9 bind exactly ONE token, $a..$z a balanced block of ZERO or more, $A..$Z a block of ONE or more.
• Two spaces stay a gap: unlike a block it may descend into an open bracket and never come back.
• :name symbol: the definition of name in the target, by per-file-type templates ($0($a){$b}); $0 is the name slot.
• A delimited anchor vouches for an ext-less or rooted target as a line does: abc/Makefile:'ragel', DOG-034:'Blockers'.
• A symbol anchor vouches for nothing: it rides a known extension or a ticket code only, or either/or:pick would fuse.
• Search and symbol anchors are never minted into permalinks; the commit hook passes them by.
• SCOPE targets (2026-09-18): .c:/re/, abc/:'grep', abc/.c:"f(x)": an ext family, a subtree, or both (SPOT-004).
• A scope link is a QUERY: it opens the search view on ALL matches, and .c:HUNKu8sMakeURI finds the definition anywhere.
• A scope takes a search or symbol anchor, always; .c:30 is nothing, and a scope is never minted.
• AUTHORITY head (2026-09-18): tok/LINK.rl:88:GG names the repo as Rep: and //name worktrees do; it heads scopes too.

Constraints

• One anchor per link: no ranges, no compounds (12,20 and 1599/re/ are out).
• A body is one line, its delimiter escaped by \; one ragel shape serves all three, no hand parsing anywhere (abc).
• Delimited bodies and symbols outgrow the 10-char anchor cap (DOG-034); they get caps of their own.
• An authority is one seg and wants a path and an anchor after it: //localhost:8080 and https://foo.io/bar.c stay prose.

WIP

Design decisions

• Quotes follow the shell: '…' is verbatim text, "…" is where the variables ($1, $a, $A) bind.
• $ over bare letters: a one-letter name (i, union U) was a variable and could never be matched as itself (BEE-074).
• Arity is the author's choice, not inferred: f($a) takes f(), f($A) does not; uppercase keeps its old meaning exactly.
• A block with no literal after it runs to the end of its bracket level or to ;; two adjacent blocks are a malformed needle.
• The needle's $x are swapped for opaque identifiers BEFORE lexing, in every language alike: Go, Python, Rust cut $ off.
• $$ is a literal $, for the languages where $1 and $i are code (shell, awk, Perl, PHP).
• On a command line a needle goes in SINGLE quotes: "f($1)" is f() to sh, fish and PowerShell alike.
• A replace template is substituted by a function, never handed to JS String.replace, where $1 means something else.
• Backticks were weighed for snippets and dropped: they collide with Markdown code spans, where links mostly live.
• Discrepancy with SPOT-002, where #'pat' is the token pattern and a bare #needle the substring: align, or live with two?
• SPOT-002 dropped symbol forms (2026-07-18); links take the symbol back, resolved by templates and not by N tags.
• A regex ending in * spells */ and closes a C block comment; such a link goes in a // comment or ends in {0,}.
• A double-space gap survives in the source, which is what the index reads, but not an HTML whitespace collapse.
• Stars were weighed for scopes and dropped: **/*.c spells */, dir/*.c spells /* (-Wcomment), * is Markdown emphasis.
• **/ would be redundant anyway: a target is an index-resolved suffix, so .c is any depth and /abc/.c anchors it.
• Open: * INSIDE a basename (test_*.c:'x'); no */ or /* can arise there. Not ruled, not in the subs.
• SPOT-003 rules scope into the path slot; the dir/.ext composition is SPOT-004's proposal and gets ruled here or there.

TODOs

• DOG-050 LINK.rl: the four new anchors, the disjoint hashlet, the caps, the splitter, scope targets, the // head
• QJAB-015 the dog bump, the regenerated twins, tok.link
• BEE-074 resolve and follow: the matcher port, the def-template table, the hook passes by, scope queries, //repo links
• DOC-002 meta/link.mkd and the pages that restate the grammar
• BEE-075 snippet variables wear a $: $1, $a, $A, $0
• DOG-052 //name:anchor is a link: an authority needs no path

Blockers and bummers

Outcome