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
fix(generation): make wiki page ids stable across runs (#974)
Raghav Chamadiyad35c2005b9db
diff --git a/packages/core/src/repowise/core/analysis/communities.py b/packages/core/src/repowise/core/analysis/communities.pyindex 499847baf..d607c1c6d 100644--- a/packages/core/src/repowise/core/analysis/communities.py+++ b/packages/core/src/repowise/core/analysis/communities.py@@ -144,7 +144,8 @@ def _partition(G: nx.Graph) -> tuple[dict, str]:log.warning("louvain_failed_using_directory_fallback", error=str(exc))# Final fallback: directory-based grouping- return _directory_fallback(list(G.nodes())), "directory"+ # Sorted: _directory_fallback numbers directories in first-seen order.+ return _directory_fallback(sorted(G.nodes())), "directory"# ---------------------------------------------------------------------------@@ -401,7 +402,7 @@ def _assign_tests_to_communities(prod_assignment: dict[str, int],graph: nx.DiGraph,) -> dict[str, int]:- """Assign each test file to the community of its most-imported production file.+ """Assign each test file to the community of a production file it links to.Falls back to a catch-all "tests" community when no import link exists."""@@ -410,22 +411,14 @@ def _assign_tests_to_communities(test_community_id = next_cid # shared fallbackfor test_path in test_nodes:- # Find which production file this test imports most- best_prod: str | None = None- best_weight = 0- for _, target, d in graph.out_edges(test_path, data=True):- if target in prod_assignment:- w = 1- best_prod = target if w > best_weight else best_prod- best_weight = max(best_weight, w)- for source, _, d in graph.in_edges(test_path, data=True):- if source in prod_assignment:- w = 1- best_prod = source if w > best_weight else best_prod- best_weight = max(best_weight, w)-- if best_prod is not None:- result[test_path] = prod_assignment[best_prod]+ # Production files this test links to, either direction. Every link+ # weighs the same, so the tie is broken on the path. Edge iteration+ # order is graph insertion order and varies between runs.+ linked = {t for _, t in graph.out_edges(test_path) if t in prod_assignment}+ linked |= {s for s, _ in graph.in_edges(test_path) if s in prod_assignment}++ if linked:+ result[test_path] = prod_assignment[min(linked)]else:result[test_path] = test_community_id@@ -504,8 +497,12 @@ def detect_file_communities(# Split oversized communitiessplit_lists = _split_oversized(undirected, raw_communities)- # Re-index by size descending for deterministic ordering- split_lists.sort(key=len, reverse=True)+ # Re-index by size descending. The rank becomes the community id, which+ # becomes a module page's target_path, so it has to be a total order:+ # size alone leaves same-size communities in partition-iteration order,+ # and Leiden (tried before Louvain) returns a partition dict ordered by+ # its own internals rather than by the node list we sorted above.+ split_lists.sort(key=lambda members: (-len(members), min(members)))# Build production file assignmentprod_assignment: dict[str, int] = {}@@ -573,10 +570,13 @@ def detect_symbol_communities(graph: nx.DiGraph) -> dict[str, int]:Returns {symbol_id: community_id}."""- symbol_nodes = [+ # Sorted for the same reason detect_file_communities sorts its node list:+ # insertion order seeds the partition, and the graph's is not stable+ # between runs. This half was left unsorted when the file half was fixed.+ symbol_nodes = sorted(n for n, d in graph.nodes(data=True)if d.get("node_type") == "symbol"- ]+ )if not symbol_nodes:return {}@@ -586,15 +586,14 @@ def detect_symbol_communities(graph: nx.DiGraph) -> dict[str, int]:undirected = nx.Graph()undirected.add_nodes_from(symbol_nodes)- for u, v, d in graph.edges(data=True):- edge_type = d.get("edge_type")- if (- edge_type in _SYMBOL_COMMUNITY_EDGE_TYPES- and u in symbol_set- and v in symbol_set- ):- if not undirected.has_edge(u, v):- undirected.add_edge(u, v)+ community_edges = sorted(+ (u, v)+ for u, v, d in graph.edges(data=True)+ if d.get("edge_type") in _SYMBOL_COMMUNITY_EDGE_TYPES+ and u in symbol_set+ and v in symbol_set+ )+ undirected.add_edges_from(community_edges)# Separate isolatesconnected = [n for n in undirected.nodes() if undirected.degree(n) > 0]@@ -618,8 +617,9 @@ def detect_symbol_communities(graph: nx.DiGraph) -> dict[str, int]:raw[next_cid] = [node]next_cid += 1- # Re-index by size descending- ordered = sorted(raw.values(), key=len, reverse=True)+ # Re-index by size descending, first member breaking ties (same total-order+ # argument as detect_file_communities).+ ordered = sorted(raw.values(), key=lambda members: (-len(members), min(members)))result: dict[str, int] = {}for cid, members in enumerate(ordered):for node in members:diff --git a/packages/core/src/repowise/core/generation/context/assembler.py b/packages/core/src/repowise/core/generation/context/assembler.pyindex a1eb25225..51a7e4cd4 100644--- a/packages/core/src/repowise/core/generation/context/assembler.py+++ b/packages/core/src/repowise/core/generation/context/assembler.py@@ -424,8 +424,11 @@ class ContextAssembler:decision_records: list[dict] | None = None,) -> RepoOverviewContext:"""Assemble context for the repo_overview template."""- # Top files sorted by PageRank descending- sorted_pr = sorted(pagerank.items(), key=lambda x: x[1], reverse=True)+ # Top files sorted by PageRank descending, path breaking ties. Leaf+ # files share a PageRank in bulk, and dict order here is graph+ # insertion order, so without the tiebreak the overview's top-file+ # list is a different list on every run.+ sorted_pr = sorted(pagerank.items(), key=lambda x: (-x[1], x[0]))top_files = [_TopFile(path=p, score=s)for p, s in sorted_pr[:_MAX_TOP_FILES]@@ -449,7 +452,9 @@ class ContextAssembler:"cohesion": round(ci.cohesion, 2),})- communities_list.sort(key=lambda c: c["size"], reverse=True)+ # Id, not label: two same-size communities can carry the same+ # label, so the label is not a total order.+ communities_list.sort(key=lambda c: (-c["size"], c["id"]))communities_list = communities_list[:10]except Exception:pass@@ -500,27 +505,41 @@ class ContextAssembler:max_diagram_nodes = 50max_diagram_edges = 200- # Top-N nodes by PageRank (exclude external nodes)+ # Top-N nodes by PageRank (exclude external nodes). Path breaks the+ # tie, otherwise which 50 nodes make the cut changes between runs and+ # the diagram is not comparable to the one it replaces.top_nodes = set(p- for p, _ in sorted(pagerank.items(), key=lambda x: x[1], reverse=True)[+ for p, _ in sorted(pagerank.items(), key=lambda x: (-x[1], str(x[0])))[:max_diagram_nodes]if not str(p).startswith("external:"))nodes = sorted(top_nodes)- # Only edges between selected nodes- edges = [(src, dst) for src, dst in graph.edges() if src in top_nodes and dst in top_nodes][- :max_diagram_edges- ]+ # Only edges between selected nodes. Ranked by the endpoints' PageRank+ # rather than alphabetically: the cap bites on dense repos, and a plain+ # sort would fill all 200 slots from whichever package sorts first and+ # draw nothing from the rest of the graph. Path breaks the tie.+ edges = sorted(+ ((src, dst) for src, dst in graph.edges() if src in top_nodes and dst in top_nodes),+ key=lambda e: (+ -pagerank.get(e[0], 0.0),+ -pagerank.get(e[1], 0.0),+ str(e[0]),+ str(e[1]),+ ),+ )[:max_diagram_edges]# Community → members mapping (top-10 communities, cap members to 5)raw_communities: dict[int, list[str]] = {}for path, cid in community.items():if not path.startswith("external:"):raw_communities.setdefault(cid, []).append(path)- comm_sorted = sorted(raw_communities.items(), key=lambda x: len(x[1]), reverse=True)[:10]+ comm_sorted = sorted(+ ((cid, sorted(members)) for cid, members in raw_communities.items()),+ key=lambda x: (-len(x[1]), x[0]),+ )[:10]communities: dict[int, list[str]] = {cid: members[:5] for cid, members in comm_sorted}# SCC groups (only non-singleton)diff --git a/packages/core/src/repowise/core/generation/models.py b/packages/core/src/repowise/core/generation/models.pyindex 1c44d80ad..d3da3b625 100644--- a/packages/core/src/repowise/core/generation/models.py+++ b/packages/core/src/repowise/core/generation/models.py@@ -295,6 +295,24 @@ def compute_page_id(page_type: str, target_path: str) -> str:return f"{page_type}:{target_path}"+def scc_page_slug(members: list[str]) -> str:+ """Return the ``target_path`` for a cycle's ``scc_page``, keyed by contents.++ An SCC has no name of its own, so the page id used to be the component's+ position in the list the graph layer handed over. That position moved+ whenever the cycle set changed, or (before the graph layer sorted its+ components) between two runs at the same commit. A moved id means the+ update path deletes and recreates the page instead of updating it, losing+ its history.++ Hashing the sorted member paths ties the id to the one thing that actually+ identifies the cycle. It survives a re-ordering, an unrelated cycle+ appearing or disappearing, and a change of detection algorithm.+ """+ digest = hashlib.sha256("\n".join(sorted(members)).encode("utf-8")).hexdigest()+ return f"scc-{digest[:12]}"++def _parse_datetime(ts: str) -> datetime:"""Parse an ISO-8601 UTC timestamp to a timezone-aware datetime."""ts = ts.replace("Z", "+00:00")diff --git a/packages/core/src/repowise/core/generation/page_generator/helpers.py b/packages/core/src/repowise/core/generation/page_generator/helpers.pyindex 1a0b65f74..155a8a275 100644--- a/packages/core/src/repowise/core/generation/page_generator/helpers.py+++ b/packages/core/src/repowise/core/generation/page_generator/helpers.py@@ -173,7 +173,12 @@ def _select_clone_representatives(for members in clusters.values():if len(members) < min_cluster_size:continue- members.sort(key=lambda p: pagerank.get(p.file_info.path, 0.0), reverse=True)+ # Near-clones usually share a PageRank (often 0.0), so the path breaks+ # the tie. Without it the survivor of each cluster changes between+ # runs, and with it which file gets a page at all.+ members.sort(+ key=lambda p: (-pagerank.get(p.file_info.path, 0.0), p.file_info.path)+ )for loser in members[1:]:drop.add(loser.file_info.path)return dropdiff --git a/packages/core/src/repowise/core/generation/selection/selector.py b/packages/core/src/repowise/core/generation/selection/selector.pyindex cf299382e..72dbdedd9 100644--- a/packages/core/src/repowise/core/generation/selection/selector.py+++ b/packages/core/src/repowise/core/generation/selection/selector.py@@ -16,6 +16,7 @@ import structlogfrom repowise.core.ingestion.languages.registry import REGISTRY as _LANG_REGISTRY+from ..models import scc_page_slugfrom ..tour import DEFAULT_MAX_LANDMARKS, tour_landmark_pathsfrom .budget import (BucketAllocation,@@ -225,7 +226,7 @@ def _build_file_candidates()if s > 0.0:scored.append((s, path))- scored.sort(key=lambda x: x[0], reverse=True)+ scored.sort(key=lambda x: (-x[0], x[1]))return scored@@ -243,7 +244,7 @@ def _build_symbol_candidates(s = score_symbol(sym, file_pr, max_pr)if s > 0.0:scored.append((s, (p.file_info.path, sym.name)))- scored.sort(key=lambda x: x[0], reverse=True)+ scored.sort(key=lambda x: (-x[0], x[1]))# A spotlight page is keyed by ``(file_path, symbol_name)``, but one file# can declare that pair twice: two classes in the same Java file each# with a ``toString``, two Rust impl blocks each with a ``new``. Left in,@@ -385,13 +386,13 @@ def _build_module_groups(inputs: SelectionInputs) -> list[tuple[float, ModuleGrokey=key,display=group_display.get(key, key),language=group_lang.get(key, "unknown"),- file_paths=tuple(p.file_info.path for p in files),+ file_paths=tuple(sorted(p.file_info.path for p in files)),label=group_label.get(key),cohesion=group_cohesion.get(key),),))- scored.sort(key=lambda x: x[0], reverse=True)+ scored.sort(key=lambda x: (-x[0], x[1].key))return scored@@ -401,7 +402,7 @@ def _build_api_candidates(inputs: SelectionInputs) -> list[tuple[float, str]]:if not p.file_info.is_api_contract:continuescored.append((score_api_contract(p), p.file_info.path))- scored.sort(key=lambda x: x[0], reverse=True)+ scored.sort(key=lambda x: (-x[0], x[1]))return scored@@ -411,7 +412,7 @@ def _build_infra_candidates(inputs: SelectionInputs) -> list[tuple[float, str]]:if not _is_infra_file(p):continuescored.append((score_infra(p), p.file_info.path))- scored.sort(key=lambda x: x[0], reverse=True)+ scored.sort(key=lambda x: (-x[0], x[1]))return scored@@ -419,13 +420,15 @@ def _build_scc_candidates(inputs: SelectionInputs,) -> list[tuple[float, tuple[str, list[str]]]]:scored: list[tuple[float, tuple[str, list[str]]]] = []- for i, scc in enumerate(inputs.sccs):- files = list(scc)+ for scc in inputs.sccs:+ files = sorted(scc)s = score_scc(cycle_size=len(files))if s <= 0.0:continue- scored.append((s, (f"scc-{i}", sorted(files))))- scored.sort(key=lambda x: x[0], reverse=True)+ scored.append((s, (scc_page_slug(files), files)))+ # Tie-break on the slug: score alone leaves equal-sized cycles in list+ # order, and the page-id set must not depend on how they got there.+ scored.sort(key=lambda x: (-x[0], x[1][0]))return scoreddiff --git a/packages/core/src/repowise/core/ingestion/graph/_betweenness.py b/packages/core/src/repowise/core/ingestion/graph/_betweenness.pyindex 4a87ac289..dac56324c 100644--- a/packages/core/src/repowise/core/ingestion/graph/_betweenness.py+++ b/packages/core/src/repowise/core/ingestion/graph/_betweenness.py@@ -134,7 +134,12 @@ def betweenness_centrality_fast(log.warning("betweenness_parallel_unavailable", reason="networkx internals moved")return nx.betweenness_centrality(g, normalized=normalized)- nodes = list(g)+ # Sorted, not graph order: the node numbering fixes the order the partial+ # sums are accumulated in, and float addition is not associative. Graph+ # insertion order varies between runs, so an unsorted numbering shifts+ # scores in the last ULP, which is enough to flip every downstream+ # tie-break that ranks on betweenness.+ nodes = sorted(g)index = {node: i for i, node in enumerate(nodes)}edges = [(index[u], index[v]) for u, v in g.edges()]diff --git a/packages/core/src/repowise/core/ingestion/graph/_centrality_cache.py b/packages/core/src/repowise/core/ingestion/graph/_centrality_cache.pyindex 3245921bd..4eb1d2baa 100644--- a/packages/core/src/repowise/core/ingestion/graph/_centrality_cache.py+++ b/packages/core/src/repowise/core/ingestion/graph/_centrality_cache.py@@ -33,7 +33,11 @@ import structloglog = structlog.get_logger(__name__)-_CACHE_VERSION = 1+# Bumped to 2 when betweenness was made order-independent: the signature keys+# on graph structure only, so a warm cache would keep serving the old,+# insertion-order-dependent values and two installs at the same commit would+# still disagree.+_CACHE_VERSION = 2_CACHE_FILENAME = "centrality_cache.pkl"__all__ = ["CentralityCache", "subgraph_signature"]diff --git a/packages/core/src/repowise/core/ingestion/graph/_metrics.py b/packages/core/src/repowise/core/ingestion/graph/_metrics.pyindex b01d805a9..d64be7441 100644--- a/packages/core/src/repowise/core/ingestion/graph/_metrics.py+++ b/packages/core/src/repowise/core/ingestion/graph/_metrics.py@@ -57,7 +57,11 @@ class MetricsMixin:cd = self.community_detection()ind = self.in_degree()outd = self.out_degree()- nodes = set(pr) | set(bc) | set(cd) | set(ind) | set(outd)+ # Sorted: this dict's order becomes the graph_metrics row order, which+ # load_metrics_from_sql then replays into the metric caches. Set+ # iteration order would carry a run's hash seed into the next run's+ # rankings.+ nodes = sorted(set(pr) | set(bc) | set(cd) | set(ind) | set(outd))return {n: {"pagerank": pr.get(n, 0.0),@@ -135,8 +139,20 @@ class MetricsMixin:# ------------------------------------------------------------------def strongly_connected_components(self) -> list[frozenset[str]]:- """Return SCCs as a list of frozensets."""- return [frozenset(scc) for scc in nx.strongly_connected_components(self.file_subgraph())]+ """Return SCCs as a list of frozensets, in a run-stable order.++ NetworkX yields components in graph-iteration order, and the graph's+ node insertion order varies between runs (git-indexer threads finish+ in whatever order they finish). Callers that index into this list, such+ as the wiki's SCC page ids and the repo-overview cycle listing, would+ otherwise name the same cycle differently on two runs at the same+ HEAD. Sorting by size then by first member fixes the order to+ something that depends only on the component contents.+ """+ return sorted(+ (frozenset(scc) for scc in nx.strongly_connected_components(self.file_subgraph())),+ key=lambda scc: (-len(scc), min(scc)),+ )def pagerank(self, alpha: float = 0.85) -> dict[str, float]:"""Return PageRank scores for file nodes only (cached)."""@@ -293,10 +309,21 @@ class MetricsMixin:if n > _LARGE_REPO_THRESHOLD:k = min(500, n)# Seeded: k-sampling is the one randomized kernel left in the- # pipeline — unseeded it made every large-repo index emit a+ # pipeline. Unseeded it made every large-repo index emit a# different betweenness ranking (typst's entry-point order# flapped between runs).- values = nx.betweenness_centrality(g, k=k, normalized=True, seed=42)+ #+ # The seed alone is not enough. NetworkX samples from+ # ``list(G.nodes())``, so a fixed seed over a population in a+ # different order still draws a different 500 nodes, and that is a+ # different ranking rather than a rounding difference. Re-inserting+ # the nodes in sorted order is what makes the sample reproducible.+ # The copy costs one pass over a graph we are about to run 500+ # shortest-path trees on.+ ordered = nx.DiGraph() if g.is_directed() else nx.Graph()+ ordered.add_nodes_from(sorted(g.nodes()))+ ordered.add_edges_from(g.edges())+ values = nx.betweenness_centrality(ordered, k=k, normalized=True, seed=42)else:from ._betweenness import betweenness_centrality_fast@@ -377,7 +404,14 @@ class MetricsMixin:def _build_scc_map(self) -> dict[str, int]:"""Assign a numeric SCC ID to each node."""result: dict[str, int] = {}- for scc_id, scc in enumerate(nx.strongly_connected_components(self.graph())):+ # Sorted for the same reason as strongly_connected_components: the+ # enumerate index is persisted as graph_nodes.scc_id, so it must not+ # depend on graph insertion order.+ components = sorted(+ nx.strongly_connected_components(self.graph()),+ key=lambda scc: (-len(scc), min(scc)),+ )+ for scc_id, scc in enumerate(components):for node in scc:result[node] = scc_idreturn result@@ -400,7 +434,10 @@ class MetricsMixin:"""out: dict[str, dict[str, Any]] = {}- for scc_id, scc in enumerate(nx.strongly_connected_components(self.file_subgraph())):+ # strongly_connected_components() is run-stably ordered, so the+ # scc_id persisted on GraphNodeMembership names the same cycle across+ # runs at the same HEAD.+ for scc_id, scc in enumerate(self.strongly_connected_components()):if len(scc) < 2:continuefor node in scc:diff --git a/packages/core/src/repowise/core/persistence/stores/in_process_graph_store.py b/packages/core/src/repowise/core/persistence/stores/in_process_graph_store.pyindex 7bf6f7517..a6745a001 100644--- a/packages/core/src/repowise/core/persistence/stores/in_process_graph_store.py+++ b/packages/core/src/repowise/core/persistence/stores/in_process_graph_store.py@@ -140,13 +140,17 @@ class InProcessGraphStore(GraphStore):file_subgraph = self._file_subgraph().to_undirected()mapping: dict[str, int] = {}if file_subgraph.number_of_nodes():- # Use NetworkX's greedy modularity communities — deterministic,- # no external dependency, fine quality at this graph size.+ # Use NetworkX's greedy modularity communities: no external+ # dependency, fine quality at this graph size. Deterministic+ # only for a fixed node order, which the graph does not+ # guarantee, so sort the result before numbering it.from networkx.algorithms.community import greedy_modularity_communities- for cid, members in enumerate(- greedy_modularity_communities(file_subgraph)- ):+ components = sorted(+ (sorted(members) for members in greedy_modularity_communities(file_subgraph)),+ key=lambda members: (-len(members), members[0] if members else ""),+ )+ for cid, members in enumerate(components):for node in members:mapping[node] = cidself._communities_cache = mappingdiff --git a/tests/integration/test_generation_determinism.py b/tests/integration/test_generation_determinism.pynew file mode 100644index 000000000..2ef92755c--- /dev/null+++ b/tests/integration/test_generation_determinism.py@@ -0,0 +1,164 @@+"""Two indexes of the same tree must produce the same page ids.++The graph's node and edge insertion order is not stable between runs: files+are parsed in a process pool and co-change edges arrive in git-indexer thread+completion order. Anything that ranks on a score without a tiebreak, or turns+a position in an unsorted list into an id, inherits that instability — and an+id that moves means the update path deletes and recreates the page instead of+updating it, losing its history.++Running the pipeline twice in one process would not catch this: the hash seed+is fixed for the life of the process, so both runs would see the same order.+These tests feed the graph the same files in two different orders instead,+which is what actually varies in production.++Read this file as the end-to-end contract, not as the regression test. The+sample repo is small enough that most of the individual ties never arise in+it, so these pass with several of the fixes reverted. The discriminating+cases live in ``tests/unit/generation/test_selection_determinism.py``, which+constructs the ties deliberately.+"""++from __future__ import annotations++from pathlib import Path++import networkx as nx+import pytest++from repowise.core.generation.context_assembler import ContextAssembler+from repowise.core.generation.models import GenerationConfig, scc_page_slug+from repowise.core.generation.page_generator import PageGenerator+from repowise.core.ingestion.graph import GraphBuilder+from repowise.core.ingestion.models import PackageInfo, ParsedFile, RepoStructure+from repowise.core.ingestion.parser import ASTParser+from repowise.core.ingestion.traverser import FileTraverser+from repowise.core.providers.llm.template import TemplateProvider++SAMPLE_REPO = Path(__file__).parents[1] / "fixtures" / "sample_repo"+++def _parse_sample_repo() -> tuple[list[ParsedFile], dict[str, bytes]]:+ traverser = FileTraverser(SAMPLE_REPO)+ parser = ASTParser()+ parsed_files: list[ParsedFile] = []+ source_map: dict[str, bytes] = {}+ for fi in traverser.traverse():+ try:+ src = Path(fi.abs_path).read_bytes()+ parsed_files.append(parser.parse_file(fi, src))+ source_map[fi.path] = src+ except Exception:+ pass+ return parsed_files, source_map+++async def _generate(parsed_files, source_map, tmp, *, order) -> list:+ """Generate the wiki with files added to the graph in *order*."""+ builder = GraphBuilder()+ for p in order:+ builder.add_file(p)+ builder.build()++ packages = [+ PackageInfo(+ name=d.name, path=d.name, language="unknown", entry_points=[], manifest_file=""+ )+ for d in SAMPLE_REPO.iterdir()+ if d.is_dir()+ ]+ repo_structure = RepoStructure(+ is_monorepo=len(packages) > 1,+ packages=packages,+ root_language_distribution={"python": 0.7, "typescript": 0.3},+ total_files=len(parsed_files),+ total_loc=sum(+ len(source_map.get(p.file_info.path, b"").splitlines()) for p in parsed_files+ ),+ entry_points=[],+ )+ config = GenerationConfig(deterministic=True, max_concurrency=3, jobs_dir=str(tmp / "jobs"))+ generator = PageGenerator(TemplateProvider(), ContextAssembler(config), config)+ return await generator.generate_all(+ parsed_files, source_map, builder, repo_structure, "sample_repo", job_system=None+ )++[email protected](scope="module")+async def two_runs(tmp_path_factory):+ """The same repo generated twice, with opposite graph insertion orders."""+ tmp = tmp_path_factory.mktemp("gen_determinism")+ parsed_files, source_map = _parse_sample_repo()+ forward = await _generate(parsed_files, source_map, tmp / "a", order=parsed_files)+ reverse = await _generate(+ parsed_files, source_map, tmp / "b", order=list(reversed(parsed_files))+ )+ return forward, reverse+++class TestPageIdStability:+ def test_runs_are_not_empty(self, two_runs):+ forward, reverse = two_runs+ assert forward and reverse++ def test_page_id_sets_are_identical(self, two_runs):+ """The headline contract: same tree, same commit, same page ids."""+ forward, reverse = two_runs+ assert {p.page_id for p in forward} == {p.page_id for p in reverse}++ def test_target_paths_are_identical_per_page_type(self, two_runs):+ """A weaker restatement that localises a failure to one page type."""+ forward, reverse = two_runs++ def by_type(pages):+ out: dict[str, set[str]] = {}+ for p in pages:+ out.setdefault(p.page_type, set()).add(p.target_path)+ return out++ assert by_type(forward) == by_type(reverse)++ def test_titles_are_identical(self, two_runs):+ """Titles carry the derived ids (community numbers, cycle slugs), so a+ stable id set with unstable titles still means a churning wiki."""+ forward, reverse = two_runs+ f = {p.page_id: p.title for p in forward}+ r = {p.page_id: p.title for p in reverse}+ assert f == r+++class TestSccSlug:+ """SCC pages motivated the content-derived id. The sample repo has exactly+ one cycle, so its slug is stable whatever the ordering does; these exercise+ the slug's properties directly instead."""++ def test_slug_ignores_member_order(self):+ assert scc_page_slug(["b.py", "a.py"]) == scc_page_slug(["a.py", "b.py"])++ def test_slug_distinguishes_different_cycles(self):+ assert scc_page_slug(["a.py", "b.py"]) != scc_page_slug(["a.py", "c.py"])++ def test_slug_is_page_id_shaped(self):+ slug = scc_page_slug(["a.py", "b.py"])+ assert slug.startswith("scc-")+ # No path separator and no extension: the MCP answer layer uses that+ # shape to keep graph ids out of agent-readable file targets.+ assert "/" not in slug and "." not in slug++ def test_component_order_survives_graph_insertion_order(self):+ """GraphBuilder-level check that the component list itself is stable."""+ from repowise.core.ingestion.graph._metrics import MetricsMixin++ cycles = [("a.py", "b.py"), ("c.py", "d.py"), ("e.py", "f.py")]++ def components(edge_order):+ g = nx.DiGraph()+ for u, v in edge_order:+ g.add_edge(u, v)+ g.add_edge(v, u)+ holder = type("H", (MetricsMixin,), {})()+ holder.graph = lambda: g+ holder.file_subgraph = lambda: g+ return [sorted(c) for c in holder.strongly_connected_components()]++ assert components(cycles) == components(list(reversed(cycles)))diff --git a/tests/unit/generation/test_selection_determinism.py b/tests/unit/generation/test_selection_determinism.pynew file mode 100644index 000000000..f290d5763--- /dev/null+++ b/tests/unit/generation/test_selection_determinism.py@@ -0,0 +1,164 @@+"""Ties must be broken on content, not on iteration order.++Scores collide constantly: every leaf file shares a PageRank, every isolate is+a size-1 community, every same-length cycle scores the same. Python's sort is+stable, so a score-only key leaves tied entries in whatever order they arrived+in — and they arrive in graph insertion order, which varies between runs+because parsing is pooled and co-change edges land in thread-completion order.++The effect is not cosmetic: the allocator slices the sorted candidate list, so+a shuffled tie changes *which pages get generated*, and a shuffled community+list changes the ids that name module pages. These tests feed identical input+in two different orders and require identical output.+"""++from __future__ import annotations++import networkx as nx++from repowise.core.analysis.communities import detect_file_communities+from repowise.core.generation.models import GenerationConfig+from repowise.core.generation.selection import SelectionInputs, select_pages++from .test_selection_budget import FakeFileInfo, FakeParsedFile, FakeSymbol+++def _tied_repo(n_files: int = 60):+ """A repo where every file scores identically — all ties, no signal."""+ parsed = [+ FakeParsedFile(+ file_info=FakeFileInfo(path=f"pkg{i // 20}/module_{i:02d}.py"),+ symbols=[FakeSymbol(name=f"handler_{i:02d}")],+ )+ for i in range(n_files)+ ]+ pagerank = {p.file_info.path: 0.5 for p in parsed}+ betweenness = {p.file_info.path: 0.25 for p in parsed}+ community = {p.file_info.path: 0 for p in parsed}+ return parsed, pagerank, betweenness, community+++def _select(parsed, pagerank, betweenness, community):+ cfg = GenerationConfig(coverage_pct=0.30)+ return select_pages(+ SelectionInputs(+ parsed_files=parsed,+ pagerank=pagerank,+ betweenness=betweenness,+ community=community,+ community_info=None,+ sccs=[],+ git_meta_map=None,+ config=cfg,+ )+ )+++class TestSelectionTies:+ def test_file_pages_survive_input_reordering(self):+ parsed, pr, bet, comm = _tied_repo()+ forward = _select(parsed, pr, bet, comm)+ reverse = _select(list(reversed(parsed)), pr, bet, comm)+ assert set(forward.file_page_paths) == set(reverse.file_page_paths)++ def test_symbol_spotlights_survive_input_reordering(self):+ parsed, pr, bet, comm = _tied_repo()+ forward = _select(parsed, pr, bet, comm)+ reverse = _select(list(reversed(parsed)), pr, bet, comm)+ assert set(forward.symbol_spotlights) == set(reverse.symbol_spotlights)++ def test_budget_actually_drops_some_files(self):+ """Guards the guard: if coverage took everything, the tests above+ would pass no matter how the candidate list was ordered."""+ parsed, pr, bet, comm = _tied_repo()+ sel = _select(parsed, pr, bet, comm)+ assert 0 < len(sel.file_page_paths) < len(parsed)+++class TestCommunityTies:+ def _graph(self, edge_order):+ g = nx.DiGraph()+ for u, v in edge_order:+ g.add_node(u, node_type="file", language="python")+ g.add_node(v, node_type="file", language="python")+ g.add_edge(u, v, edge_type="imports")+ return g++ def test_equal_sized_communities_get_stable_ids(self):+ """Three disconnected pairs: identical size, so the id each pair gets+ is decided entirely by the tiebreak. The community id is a module+ page's target_path, so a shuffled id deletes and recreates the page."""+ edges = [+ ("alpha/a.py", "alpha/b.py"),+ ("bravo/a.py", "bravo/b.py"),+ ("charlie/a.py", "charlie/b.py"),+ ]+ forward, _, _ = detect_file_communities(self._graph(edges))+ reverse, _, _ = detect_file_communities(self._graph(list(reversed(edges))))+ assert forward == reverse++ def test_reindex_is_a_total_order_on_equal_sizes(self):+ """Goes straight at the re-index step, which is where the id is minted.++ The graph-level tests above cannot fail while the partition input+ happens to be sorted upstream, but Leiden (tried before Louvain, and+ absent from CI) returns a partition ordered by its own internals. This+ asserts the property the re-index has to hold on its own."""+ from repowise.core.analysis.communities import detect_file_communities as _detect++ groups = [["b/1.py", "b/2.py"], ["a/1.py", "a/2.py"], ["c/1.py", "c/2.py"]]++ def rank(order):+ g = nx.DiGraph()+ for members in order:+ for p in members:+ g.add_node(p, node_type="file", language="python")+ g.add_edge(members[0], members[1], edge_type="imports")+ return _detect(g)[0]++ # Same three communities, three different arrival orders, one answer.+ assert rank(groups) == rank(list(reversed(groups))) == rank([groups[i] for i in (1, 2, 0)])++ def test_community_labels_are_stable(self):+ edges = [+ ("alpha/a.py", "alpha/b.py"),+ ("bravo/a.py", "bravo/b.py"),+ ("charlie/a.py", "charlie/b.py"),+ ]+ _, forward, _ = detect_file_communities(self._graph(edges))+ _, reverse, _ = detect_file_communities(self._graph(list(reversed(edges))))+ assert {cid: ci.label for cid, ci in forward.items()} == {+ cid: ci.label for cid, ci in reverse.items()+ }++ def test_isolates_get_stable_ids(self):+ """Every isolate is its own size-1 community — the worst tie case."""++ def assign(paths):+ g = nx.DiGraph()+ for p in paths:+ g.add_node(p, node_type="file", language="python")+ return detect_file_communities(g)[0]++ paths = [f"pkg/mod_{i:02d}.py" for i in range(10)]+ assert assign(paths) == assign(list(reversed(paths)))++ def test_test_files_attach_stably(self):+ """A test file linked to two production files must pick the same one+ regardless of which edge the graph happened to store first."""++ def assign(edge_order):+ g = nx.DiGraph()+ for u, v in edge_order:+ g.add_node(u, node_type="file", language="python")+ g.add_node(v, node_type="file", language="python")+ g.add_edge(u, v, edge_type="imports")+ return detect_file_communities(g)[0]["tests/test_thing.py"]++ edges = [+ ("alpha/a.py", "alpha/b.py"),+ ("bravo/a.py", "bravo/b.py"),+ ("tests/test_thing.py", "alpha/a.py"),+ ("tests/test_thing.py", "bravo/a.py"),+ ]+ assert assign(edges) == assign(list(reversed(edges)))