feat(launchpad): ProjectIndexer producing Symbol records for buzz-core

[serina-mcfall]

Summary

Implements all 8 steps of #206's plan: a ProjectIndexer that maps RepoQL's own Functions view
and git history/blame into the Symbol record schema from launchpad/Research/project- intelligence-layer-design.md, for one crate (buzz-core), rather than writing a second parser.

Related issue

Closes #206

Issue type

Task

---

Agent provenance

Field	Value
Harness / provider	Claude Code
Model	claude-sonnet-5
Session reference	N/A - harness does not expose a session/run URL
Initiating human	@serina-mcfall

Objective

Build a ProjectIndexer that parses one target crate into Symbol records matching the design
doc's schema, per #206.

Impacted components

launchpad/project-intelligence/symbol.py
launchpad/project-intelligence/indexer.py
launchpad/project-intelligence/test_symbol.py

Approach and rejected alternatives

Chosen: a thin Python adapter over RepoQL's existing structural index (rql query/rql read
CLI), rather than a from-scratch AST parser -- RepoQL already exposes qualified names,
signatures, declaring types, line ranges, and git history/blame for this exact repo.

Chosen: launchpad/project-intelligence/ (Python), not a new Rust crate registered into the
root Cargo.toml. Rejected the Rust-crate option because this repo's own AGENTS.md #1 states
"we operate Buzz, we do not develop Buzz," and launchpad/review-agent/ is the established
precedent for substantial cohort-authored agent tooling living outside the Cargo workspace.
Registering a new crate for this would have been exactly the "developing Buzz" this fork's rules
say isn't what it does, and would touch an upstream-owned file (Cargo.toml) for no reason tied
to a fork-specific problem.

Chosen: calls[]/config_dependencies[] as best-effort regex scans of each symbol's own source
lines, not a real parser -- explicitly scoped this way in the plan (LEFT OUT: full call-graph
precision belongs to #207/ProjectGraph).

Chosen: git_ownership applied selectively (one symbol at a time via enrich_git_ownership()),
not eagerly for all 453 indexed symbols -- each rql read call costs roughly a second, and
batching/parallelizing that is a real performance concern out of this task's scope.

Verification

Command run:

$ python3 -m unittest test_symbol

Raw output:

..
----------------------------------------------------------------------
Ran 2 tests in 0.000s

OK

Command run:

$ python3 indexer.py buzz-core

Raw output:

Indexed 453 symbols from crates/buzz-core

Symbol: is_shared_gated_kind
Defined: crates/buzz-core/src/kind.rs:219-221 (WORKING)
Signature: pub fn is_shared_gated_kind(kind: u32) -> bool
Calls: contains
Called by: tests::shared_gated_kinds_membership, is_unshared_gated_event
Tests: tests::shared_gated_kinds_membership
Config dependencies: (none found)
Documentation: (none found)
Primary authors: Will Pfleger
Git history:
  114d40d 2026-07-30 Will Pfleger | feat(relay): gate kind 30178 team-catalog reads behind the shared tag (#3358)
  ab3af82 2026-07-25 Will Pfleger | feat(relay): add author-only-unless-shared read gate for kind 30175 (#2768)

Every field independently cross-checked by hand at the step that introduced it (see commit
messages for each): calls/signature against RepoQL's own read() of the same symbol;
called_by against a manual grep for real call sites; git_ownership against raw
git log -L 219,221:crates/buzz-core/src/kind.rs directly (not just RepoQL's own derived view);
config_dependencies against a different real symbol (service_resource in buzz-relay,
verified against crates/buzz-relay/src/telemetry.rs:208, since buzz-core has no env-var
reads); documentation_links against a third real symbol (is_private_ip, verified against
ARCHITECTURE.md:355,740).

• Tests or checks were run and the raw output is pasted above
• The diff is confined to the scope of the linked issue
• No secrets, keys, tokens or hostnames were added to tracked files

Not verified

Did not run this against any crate other than buzz-core (plan's own scope: prove the schema
and pipeline once, not cover the whole repo) or any language other than Rust. Did not measure
performance at the whole-repo scale -- enrich_git_ownership()'s one-call-per-symbol cost is
noted as a concern for later, not solved here. Did not verify behavior on a file the rql host
hasn't indexed yet, or on a crate with zero functions.

Security implications

N/A - a read-only tool over already-indexed structural data and git history; no code, config,
network, or trust-boundary changes. Shells out to rql (already trusted, already on PATH in
this environment) and reads local files under the repo root only.

Escalations

The plan flagged three OPEN items; this PR resolves two of them by implementation choice
(stated above, not silently): where the code lives, and the RepoQL mechanism for finding
callers (a name-match text search, not a related()-style relationship the plan wasn't sure
existed). The third -- which crate/language to target first -- was resolved by following the
plan's own recommendation (buzz-core), not an independent decision.

[serina-mcfall]

Codex's independent review confirmed 4 of 5 findings — fixed in the follow-up commit:

• Refuted (P1, git ownership for every symbol): checked against task: build a ProjectIndexer producing Symbol records for one target #206's own Definition of done ("checked by hand for at least one symbol"), not a defect against the actual scoped task — but added an explicit docstring note so build_index() can't be misread as complete-with-ownership again.
• Fixed (P1, calls[]/called_by[] representation): calls[] held bare short names while called_by[] held qualified names. with_called_by() now resolves both to the same representation.
• Fixed (P2, structured commit history): added CommitSummary(hash, date, author, message) instead of pre-formatted strings.
• Fixed (P2, doc links by file too): with_documentation_links() now matches by file path as well as symbol name — verified: is_shared_gated_kind now correctly shows ARCHITECTURE.md (which discusses kind.rs by file at line 142, not this specific function).
• Fixed (P2, missing identity fields): the CLI now prints symbol_id and kind.
• Also addressed the review's fifth observation (test_symbol.py doesn't exercise the indexer) by adding test_indexer.py — 7 real unit tests for with_called_by()/with_tests()'s actual logic.

Also hit and resolved an unrelated RepoQL host lock conflict along the way (a stale process from a prior session holding the DuckDB lock) — noted in the fix commit's message, not something this PR's diff touches.

[benmitchell11]

Reviewed the actual code, not just the PR body's claims. Both subprocess.run calls (run_rql_query, _rql_read_json) use list-form arguments with no shell=True, so the security claim ('shells out to rql... no trust-boundary changes') holds up — symbol names and queries flowing into those calls can't reach a shell regardless of their content. re.escape() is used correctly when building regex patterns from symbol names in the documentation-link matcher, which is an easy thing to get wrong and didn't get gotten wrong here.

The per-field verification is real, not asserted — each enrichment (calls/signature against RepoQL's own read(), called_by against manual grep, git_ownership against raw git log -L, config_dependencies and documentation_links against separately-chosen real symbols since buzz-core doesn't exercise those fields) was cross-checked against independent ground truth, not just against the tool's own output. Living outside the Cargo workspace (per AGENTS.md #1, 'we operate Buzz, we do not develop Buzz') is the right call and correctly precedented against launchpad/review-agent/.

[tucktuck101]

Review: approve

This fulfills #206's Definition of done point by point — Symbol record with every design-doc field, a real run against buzz-core (453 symbols), called_by[] materialized as a true inverse index at index time, git ownership hand-verified against git log -L, and a CLI printing the worked-example shape. The prior review round (calls/called_by representation, structured CommitSummary, file-path doc matching, identity fields, indexer tests) is genuinely addressed in the diff, not just claimed. Scope discipline is good: known imprecision is documented in docstrings rather than hidden, and the expensive per-symbol rql read is deliberately opt-in. Recommend merge; the notes below are follow-up-sized, none blocking.

Suggestions (non-blocking)

1. Sanitize crate_name before SQL interpolation (indexer.py index_crate). It comes from sys.argv and lands inside f"WHERE file LIKE '%crates/{crate_name}/%'" — a quote or % breaks/distorts the query. A re.fullmatch(r"[A-Za-z0-9_-]+", crate_name) guard is one line. (subprocess list-form already prevents shell injection — good.)

2. Unit-test the pure regex helpers. test_indexer.py's header says the untested functions all shell out to rql, but _best_effort_calls and _best_effort_config_deps are pure string functions — and they hold the most fragile logic in the file (_NOT_A_CALL filtering, method calls like .contains(, env::var_os). A handful of hermetic cases would lock them down cheaply.

3. _read_body error handling: only OSError is caught; a non-UTF-8 file raises UnicodeDecodeError and aborts the whole crate index. Consider read_text(errors="ignore"), matching what with_documentation_links already does. Relatedly, an rql failure currently surfaces as a bare CalledProcessError with stderr swallowed by capture_output=True — worth re-raising with stderr attached.

4. Performance nits for the whole-repo follow-up (not this task's scope, just marking the spots): index_crate re-reads the same source file once per symbol (cache per file), and with_documentation_links is O(symbols × docs) full-text regex scans.

5. Schema deviations to carry into #207: the design doc types calls[]/called_by[] as symbol_ids, but this PR stores qualified names, with unresolved externals as bare short names in the same field (distinguishable only by missing ::). Documented, and fine as a bridge — but ProjectGraph should normalize to symbol_id so consumers can join without redoing the short-name mapping. Likewise documentation_links[] lacks the #section fragment and temporal_state is hardcoded "WORKING"; both are stated limitations, just don't let them silently ossify.

6. primary_authors naming: it currently returns all blame authors sorted by line count. Either truncate (top-N or a threshold) or note in the field docstring that "primary" means "ordered by blame weight", so consumers don't treat a one-line contributor as an owner.

One CI observation: all required checks pass, but no workflow executes the new Python tests — they were run locally per the PR body. If launchpad/project-intelligence/ grows past this proof stage, a small CI job (like whatever launchpad/review-agent/ uses) would keep the suite honest.