fix(onboarding): rank Key Concepts by symbol importance and ground citations#813
Merged
Merged
Conversation
…tations Key Concepts chose its "concepts" by file PageRank, so every public symbol in a high-ranked file inherited that file's rank. On this repo that surfaced five methods of one registry class (__init__, get, from_extension, import_support_map) from a single leaf cluster as the whole codebase's core concepts, and leaked pytest fixtures out of the candidate list into the prose. Rank symbols directly instead: cross-file caller count, symbol-level PageRank, and the export marker. Prefer domain-noun kinds (class, interface, enum, struct, ...) over functions and methods, drop dunders, constructors, and trivial accessors, exclude test files, and spread the page across clusters and files with per-file and per-cluster caps so no single corner owns it. Candidates are drawn from the full symbol graph rather than the parsed-files list, so the page stays correct on an incremental update where only changed files are re-parsed. The chosen concepts' real dependency edges are passed to the template, so the "How they connect" section states links that exist instead of inventing them. Add a reusable grounding post-check that strips ungrounded backticked path and symbol citations from onboarding output (demoted to plain text, reported for logging). It runs on fresh and reused content, so a cached page carrying a stale fabrication is cleaned on the next docs update. Add ONBOARDING_GENERATION_VERSION, folded into each onboarding page's cross-run reuse hash through a new source_salt parameter, so a builder or template change forces a one-time regeneration of the collection for existing docs-enabled users.
|
✅ Health: 7.6 (unchanged) 📋 At a glance 🚨 Change risk: high (riskier than 77% of this repo's commits · raw 9.5/10)
🔎 More signals (3)🔥 Hotspots touched (3)
🔗 Hidden coupling (2 files)
💀 Dead code (1 finding)
📊 Full report · ⭐ Star Repowise · 📥 Install bot · Last updated 2026-07-12 13:23 UTC |
swati510
approved these changes
Jul 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The always-generated Key Concepts onboarding page chose its "concepts" by
file PageRank: every public symbol in a high-ranked file inherited that file's
score. On this repo that produced six "core concepts" of
LanguageSpec,LanguageRegistry,__init__,get,import_support_map,from_extension—five of them from a single file, four of them methods, all from one leaf cluster
(
ingestion/languages/). It also leaked pytest fixtures out of the internalcandidate list into the closing prose. A newcomer would conclude the codebase is
about language registries.
Separately, onboarding prose was grounded only by a prompt instruction ("do not
invent file paths or symbol names"), with nothing verifying the model obeyed, so
fabricated citations reached the reader as authoritative backticked references.
Changes
Key Concepts ranking rework. Rank symbols by symbol-graph signals instead of
file rank: cross-file caller count (how many other files depend on it),
symbol-level PageRank, and the export marker. Prefer domain-noun kinds (class,
interface, enum, struct, protocol, ...) over functions and methods; drop dunders,
constructors, and trivial accessors; exclude test files; and spread the page
across clusters and files with per-file and per-cluster caps so no single corner
owns it. Candidates are drawn from the full symbol graph rather than the
parsed-files list, so the page stays correct on an incremental update where only
changed files are re-parsed. The chosen concepts' real dependency edges are
passed into the template, so "How they connect" states links that exist.
Grounding post-check. A reusable helper collects the paths and symbols
present in each onboarding page's context, then strips the backticks off any
backticked path-shaped or symbol-shaped token absent from that payload (demoted
to plain text, never deleting the sentence) and reports what it removed. It runs
on fresh and reused content, so a cached page with a stale fabrication is cleaned
on the next docs update. Conservative by design: only unambiguous shapes are
checked, so lowercase enum values like
full/noneare left alone.Self-heal for existing users. A new
ONBOARDING_GENERATION_VERSIONis foldedinto each onboarding page's cross-run reuse hash through a
source_saltparameter(kept out of the LLM prompt itself), so a builder or template change forces a
one-time regeneration of the collection for existing docs-enabled users.
Verification
ranking, noun preference, cluster spread, grounded relations, test-file
exclusion, the full-graph path on empty parsed-files, the grounding checker
(known-good passes, fabrication caught, reused-page fabrication caught,
lowercase words untouched), and source-hash self-heal.
Concepts now surfaces
GraphBuilder,DeadCodeAnalyzer,FileTraverser,InMemoryVectorStore,FullTextSearch,CrossRepoEnricher— six domain-nounclasses across three architectural layers, with a "How they connect" that
matches real edges. The grounding check fired (dropped a fabricated
*.tsxglob and out-of-payload symbols). Getting Started, Codebase Map, and Active
Landscape still read cleanly; the old wrong
dotnet/index.py"ingestion entrypoint" anchor is gone from Codebase Map.