Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

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.py
index 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 PurePosixPath
from typing import Any
from 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 points
logger.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 = tour
except 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* from
barrel 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 - defensive
betweenness = {}
- 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:
continue
path = 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_tags
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)))
- 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):
continue
pf = 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) -> l
def _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 fills
structural_reasons: dict[str, str] = {}
+ hotspot_added: str | None = None # churn hotspot given a reserved slot
if 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_LAYERS
and 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] = rep
seen_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.depth
reason = step.reason
diff --git a/packages/core/src/repowise/core/generation/editor_files/data.py b/packages/core/src/repowise/core/generation/editor_files/data.py
index 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: int
title: str
primary_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.py
index 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.py
new file mode 100644
index 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.j2
index 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.py
index 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 dataclass
from pathlib import PurePosixPath
from typing import Any
+from repowise.core.generation.entry_points import is_glue_leaf
from repowise.core.generation.layers import ADJACENT_LAYERS, infer_layer, is_support_path
from 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 rule
flagged 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_LANGUAGES
and infer_layer(path, language) not in ADJACENT_LAYERS
and 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.py
index 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.py
new file mode 100644
index 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 regardless
diff --git a/tests/unit/generation/test_kg_claude_md_onboarding.py b/tests/unit/generation/test_kg_claude_md_onboarding.py
index 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 rendered
def 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 rendered
assert "3 more steps" in rendered
diff --git a/tests/unit/generation/test_tour.py b/tests/unit/generation/test_tour.py
index 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 dataclass
from 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
# ---------------------------------------------------------------------------