Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(kg): rank orientation entry points by execution-start, surface churn hotspots in the tour (#574)
Raghav Chamadiya7ca26874e5b3
diff --git a/packages/core/src/repowise/core/analysis/kg_curation.py b/packages/core/src/repowise/core/analysis/kg_curation.pyindex fb64e57c6..88e770868 100644--- a/packages/core/src/repowise/core/analysis/kg_curation.py+++ b/packages/core/src/repowise/core/analysis/kg_curation.py@@ -32,6 +32,11 @@ from pathlib import PurePosixPathfrom typing import Anyfrom repowise.core.analysis.knowledge_graph import KnowledgeGraphResult, _slugify+from repowise.core.generation.entry_points import (+ GLUE_STEMS,+ is_glue_leaf,+ rank_entry_points,+)from repowise.core.generation.layers import (ADJACENT_LAYERS,compute_layer_order,@@ -43,6 +48,7 @@ from repowise.core.generation.tour import (DEFAULT_MAX_STOPS,build_tour,score_entry_points,+ select_hotspot_stop,)from repowise.core.ingestion.languages.registry import REGISTRY as _LANG_REGISTRY@@ -56,6 +62,15 @@ _FIXTURE_CAMEL_RES = _LANG_REGISTRY.camel_fixture_res_by_extension()# Test-project dir suffixes (.Tests/.Specs) — when present, the suite's# face must come from inside one._TEST_PROJECT_DIR_SUFFIXES: tuple[str, ...] = _LANG_REGISTRY.test_dir_suffixes()+# Config/markup/data + infra languages — a server.json or a Dockerfile+# describes or wires the system, it is never where execution starts, so it+# never belongs on the orientation entry-point list.+_NON_CODE_ENTRY_LANGUAGES: frozenset[str] = (+ _LANG_REGISTRY.config_languages() | _LANG_REGISTRY.infra_languages()+)+# Conventional execution-start filename stems (main/app/cli/manage/…) minus+# the dispatch-glue stems (index/mod) — drives the entry-point name ranking.+_CONVENTIONAL_ENTRY_STEMS: frozenset[str] = _LANG_REGISTRY.entry_filename_stems() - GLUE_STEMS# Honest-degradation thresholds. Density = (imports + tested_by)# edges per dominant-language file — the same definition the validation@@ -192,6 +207,7 @@ def curate_knowledge_graph(graph_builder: Any,repo_structure: Any,community_info: Any,+ git_meta_map: dict[str, dict] | None = None,enabled: bool = False,defer_summary_floor: bool = False,) -> KnowledgeGraphResult:@@ -244,8 +260,17 @@ def curate_knowledge_graph(except Exception: # pragma: no cover - defensive; keep skeleton entry pointslogger.exception("kg_curation._curate_entry_points failed; keeping raw entry points")+ # Genuine churn hotspots (a constantly-edited file off the hot import path)+ # earn a tour stop on this signal alone. Only flagged hotspots with recent+ # commits qualify; repos without git history pass an empty map and the tour+ # is unchanged.+ hotspot_commits = {+ path: int(meta.get("commit_count_90d", 0) or 0)+ for path, meta in (git_meta_map or {}).items()+ if meta.get("is_hotspot")+ }try:- tour = _curate_tour(kg, parsed_files, graph_builder)+ tour = _curate_tour(kg, parsed_files, graph_builder, hotspot_commits=hotspot_commits)if tour is not None:kg.tour = tourexcept Exception: # pragma: no cover - defensive; keep skeleton/LLM tour@@ -827,11 +852,15 @@ def _curate_entry_points(Mutates only the presentation view: drops the ``entry_point`` *tag* frombarrel nodes (and adds a ``barrel`` tag) without touching the AST graph's``is_entry_point`` flag (the dead-code pass relies on it). Survivors are- ranked by ``pagerank + betweenness``; ``project.entry_points`` holds the top- few, ``project.entry_candidates`` the full ranked list. When ingestion- flagged no entries at all, the strong :func:`score_entry_points` scorers- (entry-style filenames) fill in, so the orientation panel never opens empty- on repos without a detectable main.+ ranked by :func:`rank_entry_points` — execution-start evidence (a+ conventional entry name, shallow path) first, centrality only as a tiebreak+ — so a deeply-nested resolver ``index.py`` cannot outrank the real+ ``main.py``. Config/data files (``server.json``) and generic-glue leaves+ (a resolver's deep ``index.py``) are dropped from candidacy outright.+ ``project.entry_points`` holds the top few, ``project.entry_candidates`` the+ full ranked list. When ingestion flagged no entries at all, the strong+ :func:`score_entry_points` scorers (entry-style filenames) fill in, so the+ orientation panel never opens empty on repos without a detectable main."""pf_by_path = {pf.file_info.path: pf for pf in parsed_files if getattr(pf, "file_info", None)}lang_by_path = {n["filePath"]: (n.get("language") or "").lower() for n in _file_nodes(kg)}@@ -841,7 +870,14 @@ def _curate_entry_points(except Exception: # pragma: no cover - defensivebetweenness = {}- survivors: list[tuple[float, str]] = []+ def _not_an_execution_start(path: str, language: str) -> bool:+ # Config/data files (server.json) describe the system and deep+ # generic-glue leaves (a resolver's index.py) dispatch within it —+ # neither is where a reader enters. Barrel demotion is handled+ # separately (it mutates tags), so this covers only candidacy.+ return language in _NON_CODE_ENTRY_LANGUAGES or is_glue_leaf(path)++ candidates: list[tuple[str, float, float]] = []for node in kg.nodes:nid = node.get("id", "")if not (isinstance(nid, str) and nid.startswith("file:")):@@ -850,7 +886,8 @@ def _curate_entry_points(if "entry_point" not in tags:continuepath = node.get("filePath", "")- if infer_layer(path, node.get("language")) in ADJACENT_LAYERS or is_support_path(path):+ language = (node.get("language") or "").lower()+ if infer_layer(path, language) in ADJACENT_LAYERS or is_support_path(path):# Test fixtures (a wsgi.py inside tests/) and sample programs# (examples/*/main.go) may carry the ingestion flag, but they are# not where a reader enters the system.@@ -862,27 +899,28 @@ def _curate_entry_points(new_tags.append("barrel")node["tags"] = new_tagscontinue- score = pagerank.get(path, 0.0) + betweenness.get(path, 0.0)- survivors.append((score, path))+ if _not_an_execution_start(path, language):+ continue+ candidates.append((path, pagerank.get(path, 0.0), betweenness.get(path, 0.0)))- if not survivors:+ if not candidates:# No ingestion-flagged entries (or all were barrels): fall back to the# strong filename scorers the tour seeds from (score >= 3 means an# entry-style name or flag, never just shallow/high-PageRank).for s, path in score_entry_points(parsed_files, pagerank):if s < 3.0:continue- if infer_layer(path, lang_by_path.get(path)) in ADJACENT_LAYERS or is_support_path(path):+ language = lang_by_path.get(path, "")+ if infer_layer(path, language) in ADJACENT_LAYERS or is_support_path(path):continuepf = pf_by_path.get(path)if pf is not None and _is_barrel(pf):continue- score = pagerank.get(path, 0.0) + betweenness.get(path, 0.0)- survivors.append((score, path))+ if _not_an_execution_start(path, language):+ continue+ candidates.append((path, pagerank.get(path, 0.0), betweenness.get(path, 0.0)))- # Highest score first; path as a stable, deterministic tie-break.- survivors.sort(key=lambda sp: (-sp[0], sp[1]))- ranked = [path for _, path in survivors]+ ranked = rank_entry_points(candidates, _CONVENTIONAL_ENTRY_STEMS)kg.project["entry_points"] = ranked[:_MAX_ENTRY_POINTS]kg.project["entry_candidates"] = ranked@@ -1099,7 +1137,10 @@ def _drop_extra_barrels(paths: list[str], barrels: set[str], keep: int = 1) -> ldef _curate_tour(- kg: KnowledgeGraphResult, parsed_files: list[Any], graph_builder: Any+ kg: KnowledgeGraphResult,+ parsed_files: list[Any],+ graph_builder: Any,+ hotspot_commits: dict[str, int] | None = None,) -> list[dict] | None:"""Build one canonical, execution-flow tour over the curated layers.@@ -1274,6 +1315,7 @@ def _curate_tour(budget = max(0, DEFAULT_MAX_STOPS - len(overview) - len(closing_paths) - len(infra))swapped_depth: dict[str, int] = {} # rep path -> depth of the slot it fillsstructural_reasons: dict[str, str] = {}+ hotspot_added: str | None = None # churn hotspot given a reserved slotif graph_mode == "structural":# Structure, not flow: evidence-ranked anchor + one face per@@ -1300,9 +1342,27 @@ def _curate_tour(and file_layers.get(s.target_path) not in ADJACENT_LAYERSand not is_support_path(s.target_path)]+ # A genuine churn hotspot off the hot import path (a constantly-edited+ # pipeline file buried in a large catch-all layer) earns one reserved+ # slot — picked from the whole code universe, not just build_tour's+ # selection, and only when it is not already a stop. Repos without git+ # history pass an empty map, so the reserve is a no-op there.+ hotspot_path: str | None = None+ if hotspot_commits:+ hotspot_pool = [+ p+ for p in walk_universe+ if p not in barrels+ and file_layers.get(p) not in ADJACENT_LAYERS+ and type_by_path.get(p) not in {"config", "document"}+ ]+ hotspot_path = select_hotspot_stop(hotspot_pool, hotspot_commits)+ budgeted = _drop_extra_barrels(walk_all, barrels)[:budget]+ reserve = 1 if (hotspot_path is not None and hotspot_path not in budgeted) else 0+# One re-export barrel earns a stop; the rest are demoted so real code# fills the budget instead of a run of identical "public surface" hubs.- walk = _drop_extra_barrels(walk_all, barrels)[:budget]+ walk = _drop_extra_barrels(walk_all, barrels)[: max(0, budget - reserve)]# --- Diversify for layer coverage (swap slots, never re-sort) -----seen_layers: set[str] = set()@@ -1358,6 +1418,11 @@ def _curate_tour(walk[pos] = repseen_layers.add(layer)+ # Spend the reserved slot last so layer-coverage swaps keep priority.+ if reserve and hotspot_path is not None and hotspot_path not in walk:+ walk.append(hotspot_path)+ hotspot_added = hotspot_path+# --- Assemble the exported tour --------------------------------------tour: list[dict] = []order_n = 0@@ -1385,6 +1450,12 @@ def _curate_tour(elif p in swapped_depth:depth = swapped_depth[p]reason = f"The {layer} layer's anchor — its most depended-on file."+ elif p == hotspot_added:+ depth = 0+ reason = (+ "A top churn hotspot — one of the most frequently changed files "+ "in the repo; worth understanding early."+ )elif step is not None:depth = step.depthreason = step.reasondiff --git a/packages/core/src/repowise/core/generation/editor_files/data.py b/packages/core/src/repowise/core/generation/editor_files/data.pyindex 96569b942..150ca4997 100644--- a/packages/core/src/repowise/core/generation/editor_files/data.py+++ b/packages/core/src/repowise/core/generation/editor_files/data.py@@ -74,6 +74,7 @@ class KGTourStepSummary:order: inttitle: strprimary_file: str+ reason: str = ""@dataclass(frozen=True)diff --git a/packages/core/src/repowise/core/generation/editor_files/fetcher.py b/packages/core/src/repowise/core/generation/editor_files/fetcher.pyindex 9018ff04f..e06ebefab 100644--- a/packages/core/src/repowise/core/generation/editor_files/fetcher.py+++ b/packages/core/src/repowise/core/generation/editor_files/fetcher.py@@ -394,6 +394,7 @@ class EditorFileDataFetcher:order=s.get("order") or len(tour) + 1,title=s.get("title") or "",primary_file=s.get("target_path") or "",+ reason=s.get("reason") or "",))if not tour:diff --git a/packages/core/src/repowise/core/generation/entry_points.py b/packages/core/src/repowise/core/generation/entry_points.pynew file mode 100644index 000000000..491ea0ec9--- /dev/null+++ b/packages/core/src/repowise/core/generation/entry_points.py@@ -0,0 +1,106 @@+"""Pure ranking and candidacy rules for orientation entry points.++The orientation entry-point list answers one question: *where does execution+start?* That is not the same as *what is most central?* Centrality signals+(PageRank, betweenness) reward fan-in — a widely-imported resolver hub scores+high precisely because everything depends on it, which makes it a sink, the+opposite of a front door. Ranking by centrality therefore floats infrastructure+glue (a language resolver's ``index.py``) above the real ``main.py``.++This module ranks candidates by execution-start evidence instead — a+conventional entry filename and a shallow path — and uses centrality only to+break ties. It is deliberately free of any DB/graph/LLM dependency so the+ordering can be unit-tested directly.+"""++from __future__ import annotations++from pathlib import PurePosixPath++# Generic module stems that *dispatch or re-export* rather than start a program.+# ``index`` (a JS/TS barrel or a per-language resolver shell) and ``mod`` (a Rust+# module root) gather siblings; they are glue, not a control-flow front door.+# Distinct from the registry's broader generic-entry set (main/app/server/cli/…),+# which are genuine execution starts.+GLUE_STEMS: frozenset[str] = frozenset({"index", "mod"})++# A glue-stem file is only plausibly a real entry when it sits at or very near a+# package root. Buried deeper, it is a dispatch/re-export leaf (a resolver's+# ``index.py`` nested under ``ingestion/resolvers/dotnet/``), never where a+# reader enters the system.+SHALLOW_ENTRY_DEPTH = 1+++def entry_point_depth(path: str) -> int:+ """Directory depth — 0 for a root file, 1 for one level deep, etc."""+ return max(0, len(PurePosixPath(path).parts) - 1)+++def is_glue_leaf(path: str) -> bool:+ """True for a generic-glue stem nested below the shallow band.++ These define real symbols (so :func:`_is_barrel` keeps them) yet are+ dispatch/re-export leaves, not execution entry points — excluded from the+ orientation entry-point list and never seeded as a tour entry point.+ """+ return (+ PurePosixPath(path).stem.lower() in GLUE_STEMS+ and entry_point_depth(path) > SHALLOW_ENTRY_DEPTH+ )+++def _name_bucket(path: str, conventional_stems: frozenset[str]) -> int:+ """0 = conventional entry name, 1 = neutral, 2 = generic glue stem."""+ stem = PurePosixPath(path).stem.lower()+ if stem in GLUE_STEMS:+ return 2+ if stem in conventional_stems:+ return 0+ return 1+++def entry_point_rank_key(+ path: str,+ *,+ pagerank: float = 0.0,+ betweenness: float = 0.0,+ conventional_stems: frozenset[str] = frozenset(),+) -> tuple[int, int, float, str]:+ """Sort key for an entry-point candidate (ascending tuple = better entry).++ Most significant component first:++ 1. **name bucket** — a conventional entry name (``main``/``app``/``cli``/+ ``manage``/…) never loses to a generic glue stem (``index``/``mod``),+ and glue never outranks a real entry.+ 2. **path depth** — shallower first; a front door sits near its package+ root, so a deeply-nested module cannot outrank a shallow real entry.+ 3. **centrality** (``pagerank + betweenness``), negated — a tiebreak only,+ since centrality rewards fan-in (backwards for an entry point).+ 4. **path** — deterministic final tiebreak.+ """+ return (+ _name_bucket(path, conventional_stems),+ entry_point_depth(path),+ -(pagerank + betweenness),+ path,+ )+++def rank_entry_points(+ candidates: list[tuple[str, float, float]],+ conventional_stems: frozenset[str],+) -> list[str]:+ """Rank ``(path, pagerank, betweenness)`` candidates, best entry first."""+ return [+ path+ for path, _pr, _bt in sorted(+ candidates,+ key=lambda c: entry_point_rank_key(+ c[0],+ pagerank=c[1],+ betweenness=c[2],+ conventional_stems=conventional_stems,+ ),+ )+ ]diff --git a/packages/core/src/repowise/core/generation/templates/claude_md.j2 b/packages/core/src/repowise/core/generation/templates/claude_md.j2index 4858cd510..362a25f8e 100644--- a/packages/core/src/repowise/core/generation/templates/claude_md.j2+++ b/packages/core/src/repowise/core/generation/templates/claude_md.j2@@ -59,7 +59,7 @@ Last indexed: {{ data.indexed_at }}{% if data.indexed_commit %} (commit {{ data.### Guided Tour ({{ data.kg_tour | length }} steps){% for step in data.kg_tour[:6] %}-{{ step.order }}. **{{ step.title }}**{% if step.primary_file %} — `{{ step.primary_file }}`{% endif %}+{{ step.order }}. `{{ step.primary_file or step.title }}`{% if step.reason %} — {{ step.reason }}{% endif %}{% endfor %}{% if data.kg_tour | length > 6 %}diff --git a/packages/core/src/repowise/core/generation/tour.py b/packages/core/src/repowise/core/generation/tour.pyindex 2d2bf3f61..bf1ca95dc 100644--- a/packages/core/src/repowise/core/generation/tour.py+++ b/packages/core/src/repowise/core/generation/tour.py@@ -35,6 +35,7 @@ from dataclasses import dataclassfrom pathlib import PurePosixPathfrom typing import Any+from repowise.core.generation.entry_points import is_glue_leaffrom repowise.core.generation.layers import ADJACENT_LAYERS, infer_layer, is_support_pathfrom repowise.core.ingestion.languages.registry import REGISTRY as _LANG_REGISTRY@@ -118,8 +119,10 @@ def score_entry_points(Both entry bonuses are withheld from doc/data languages — ``docs/index.md``must never outrank a real ``main.py``, even when ingestion's stem ruleflagged it — from test files (``tests/testserver/server.py`` is a fixture,- not where a reader enters the system), and from example/demo dirs (every- ``examples/*/main.go`` is an entry by *name*; none is the system).+ not where a reader enters the system), from example/demo dirs (every+ ``examples/*/main.go`` is an entry by *name*; none is the system), and from+ deep generic-glue leaves (a resolver's nested ``index.py`` dispatches, it+ does not start the program).Returns ``[(score, path), ...]`` sorted by score then path for stability.Only files with a positive score are returned.@@ -140,6 +143,7 @@ def score_entry_points(language not in _NON_CODE_LANGUAGESand infer_layer(path, language) not in ADJACENT_LAYERSand not is_support_path(path)+ and not is_glue_leaf(path))if entry_eligible and getattr(fi, "is_entry_point", False):score += 3.0@@ -155,6 +159,32 @@ def score_entry_points(return scored+def select_hotspot_stop(+ candidates: Iterable[str],+ commit_count: Mapping[str, int],+ *,+ min_commits: int = 1,+) -> str | None:+ """Pick the single most actively-changed file worth a churn-based stop.++ The execution-flow walk follows the import graph, so a file that the whole+ team edits constantly but that sits *off* the hot import path (a pipeline+ orchestrator buried in a large catch-all layer) never earns a stop on+ structure alone. This surfaces exactly one such file: the highest 90-day+ commit count among *candidates*, path as a deterministic tiebreak.++ *candidates* should already be code files flagged as genuine hotspots.+ Returns ``None`` when none has recent activity, so repos without git+ history (and the parsed-only fixture matrix) get no hotspot stop and the+ tour is unchanged.+ """+ ranked = sorted(+ (p for p in candidates if commit_count.get(p, 0) >= min_commits),+ key=lambda p: (-commit_count.get(p, 0), p),+ )+ return ranked[0] if ranked else None++def tour_landmark_paths(parsed_files: Sequence[Any],pagerank: Mapping[str, float],diff --git a/packages/core/src/repowise/core/pipeline/orchestrator.py b/packages/core/src/repowise/core/pipeline/orchestrator.pyindex 2f6e2e5f9..aded586ea 100644--- a/packages/core/src/repowise/core/pipeline/orchestrator.py+++ b/packages/core/src/repowise/core/pipeline/orchestrator.py@@ -560,6 +560,7 @@ async def run_pipeline(graph_builder=graph_builder,repo_structure=repo_structure,community_info=graph_builder.community_info(),+ git_meta_map=git_meta_map,enabled=curation_enabled(),defer_summary_floor=will_generate,)diff --git a/tests/unit/generation/test_entry_points.py b/tests/unit/generation/test_entry_points.pynew file mode 100644index 000000000..1982ca238--- /dev/null+++ b/tests/unit/generation/test_entry_points.py@@ -0,0 +1,90 @@+"""Tests for the pure entry-point ranking/candidacy rules (generation.entry_points)."""++from __future__ import annotations++from repowise.core.generation.entry_points import (+ GLUE_STEMS,+ entry_point_depth,+ entry_point_rank_key,+ is_glue_leaf,+ rank_entry_points,+)++# A representative conventional-entry stem set (registry-derived in production).+_CONV = frozenset({"main", "app", "server", "cli", "run", "manage", "wsgi", "asgi"})+++def test_entry_point_depth_counts_directories():+ assert entry_point_depth("main.py") == 0+ assert entry_point_depth("src/main.py") == 1+ assert entry_point_depth("a/b/c/d/main.py") == 4+++def test_glue_stems_are_index_and_mod():+ assert set(GLUE_STEMS) == {"index", "mod"}+++def test_is_glue_leaf_only_for_deep_generic_stems():+ # A deeply-nested resolver index.py is a dispatch leaf.+ assert is_glue_leaf("packages/core/ingestion/resolvers/dotnet/index.py")+ assert is_glue_leaf("a/b/mod.rs")+ # Shallow generic stems may still be a real package entry.+ assert not is_glue_leaf("index.ts")+ assert not is_glue_leaf("src/index.ts")+ # Non-generic stems are never glue leaves, however deep.+ assert not is_glue_leaf("a/b/c/d/main.py")+++def test_glue_leaf_never_outranks_a_real_entry():+ # The .NET resolver index.py is highly central (high pagerank+betweenness)+ # but must rank below a shallow, conventionally-named main.py.+ candidates = [+ ("packages/core/ingestion/resolvers/dotnet/index.py", 0.9, 0.9),+ ("packages/cli/src/main.py", 0.1, 0.0),+ ]+ ranked = rank_entry_points(candidates, _CONV)+ assert ranked[0] == "packages/cli/src/main.py"+ assert ranked[-1].endswith("dotnet/index.py")+++def test_conventional_name_outranks_neutral_at_same_depth():+ candidates = [+ ("pkg/sub/helper.py", 0.9, 0.9), # neutral name, very central+ ("pkg/sub/app.py", 0.0, 0.0), # conventional entry name+ ]+ ranked = rank_entry_points(candidates, _CONV)+ assert ranked[0] == "pkg/sub/app.py"+++def test_shallower_entry_wins_within_a_bucket():+ candidates = [+ ("a/b/c/d/main.py", 0.5, 0.5),+ ("a/main.py", 0.0, 0.0),+ ]+ ranked = rank_entry_points(candidates, _CONV)+ assert ranked[0] == "a/main.py"+++def test_centrality_only_breaks_ties():+ # Same name bucket and depth: the more central file wins.+ candidates = [+ ("pkg/main.py", 0.2, 0.1),+ ("lib/main.py", 0.9, 0.5),+ ]+ ranked = rank_entry_points(candidates, _CONV)+ assert ranked[0] == "lib/main.py"+++def test_rank_is_deterministic_on_full_ties():+ candidates = [+ ("z/main.py", 0.0, 0.0),+ ("a/main.py", 0.0, 0.0),+ ]+ ranked = rank_entry_points(candidates, _CONV)+ assert ranked == ["a/main.py", "z/main.py"] # path tiebreak+++def test_rank_key_orders_bucket_then_depth_then_centrality():+ conv = entry_point_rank_key("a/app.py", pagerank=0.0, conventional_stems=_CONV)+ glue = entry_point_rank_key("a/index.py", pagerank=1.0, conventional_stems=_CONV)+ assert conv < glue # conventional name beats central glue regardlessdiff --git a/tests/unit/generation/test_kg_claude_md_onboarding.py b/tests/unit/generation/test_kg_claude_md_onboarding.pyindex 45aee99a8..4b0cd3da8 100644--- a/tests/unit/generation/test_kg_claude_md_onboarding.py+++ b/tests/unit/generation/test_kg_claude_md_onboarding.py@@ -97,14 +97,20 @@ class TestClaudeMdKGSection:architecture_summary="",kg_layers=[KGLayerSummary(name="Core", file_count=5, description="Core")],kg_tour=[- KGTourStepSummary(order=1, title="Entry Point", primary_file="src/main.py"),+ KGTourStepSummary(+ order=1,+ title="Entry Point",+ primary_file="src/main.py",+ reason="An entry point — execution starts here.",+ ),KGTourStepSummary(order=2, title="Graph Building", primary_file="src/graph.py"),],)rendered = tmpl.render(data=data)assert "### Guided Tour (2 steps)" in rendered- assert "**Entry Point**" in rendered+ # The package-qualified path is the step identifier; the reason follows.assert "`src/main.py`" in rendered+ assert "An entry point — execution starts here." in rendereddef test_key_modules_owner_column_dropped_when_no_owners(self, jinja_env):from repowise.core.generation.editor_files.data import KeyModule@@ -169,8 +175,8 @@ class TestClaudeMdKGSection:kg_tour=steps,)rendered = tmpl.render(data=data)- assert "**Step 6**" in rendered- assert "**Step 7**" not in rendered+ assert "`f6.py`" in rendered+ assert "`f7.py`" not in renderedassert "3 more steps" in rendereddiff --git a/tests/unit/generation/test_tour.py b/tests/unit/generation/test_tour.pyindex 6391754e2..605502825 100644--- a/tests/unit/generation/test_tour.py+++ b/tests/unit/generation/test_tour.py@@ -2,12 +2,13 @@from __future__ import annotations-from dataclasses import dataclass, field+from dataclasses import dataclassfrom repowise.core.generation.tour import (DEFAULT_MAX_STOPS,build_tour,score_entry_points,+ select_hotspot_stop,tour_landmark_paths,)@@ -60,6 +61,42 @@ def test_score_entry_points_withholds_stem_bonus_from_docs():assert scored.get("docs/index.md", 0.0) < 3.0+def test_score_entry_points_withholds_bonus_from_deep_glue_leaf():+ # A deeply-nested resolver index.py defines real symbols (not a barrel) but+ # dispatches; it must not earn the entry bonuses that would seed the walk+ # and label it "an entry point".+ files = [+ _PF(_FI(path="core/ingestion/resolvers/dotnet/index.py", is_entry_point=True)),+ _PF(_FI(path="src/main.py")),+ ]+ pr = {"core/ingestion/resolvers/dotnet/index.py": 0.9, "src/main.py": 0.5}+ scored = {p: s for s, p in score_entry_points(files, pr)}+ assert scored["src/main.py"] >= 3.0+ assert scored.get("core/ingestion/resolvers/dotnet/index.py", 0.0) < 3.0+++# ---------------------------------------------------------------------------+# Hotspot stop selection+# ---------------------------------------------------------------------------+++def test_select_hotspot_stop_picks_highest_commit_count():+ candidates = ["a/orchestrator.py", "b/walker.py", "c/quiet.py"]+ commits = {"a/orchestrator.py": 36, "b/walker.py": 17, "c/quiet.py": 0}+ assert select_hotspot_stop(candidates, commits) == "a/orchestrator.py"+++def test_select_hotspot_stop_returns_none_without_activity():+ # No git history (the fixture matrix): nothing qualifies, tour unchanged.+ assert select_hotspot_stop(["a/x.py", "b/y.py"], {}) is None+ assert select_hotspot_stop(["a/x.py"], {"a/x.py": 0}) is None+++def test_select_hotspot_stop_is_deterministic_on_ties():+ commits = {"z/a.py": 5, "a/b.py": 5}+ assert select_hotspot_stop(["z/a.py", "a/b.py"], commits) == "a/b.py"++# ---------------------------------------------------------------------------# Landmarks# ---------------------------------------------------------------------------