From 7d6bf0646709bf801afe8e0db1baf15c9cafa5c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A1bor=20Z=20Sink=C3=B3?= Date: Sat, 17 Oct 2026 21:06:26 +0200 Subject: [PATCH] feat(mcp): optional edge_types allow-list for graph traversal, document edge types focus_pack, impact_analysis and guided_path followed every outgoing edge regardless of its type; guided_path only printed the type. They now accept an optional edge_types allow-list. The default (None) keeps the current behaviour and the result shape; with a list the result echoes the types. An empty list follows no edge. kb_data/edge_types.md was stale (2 of the 4 types the graph builder emits). generate_edge_types_doc now states what each type means, so readers do not treat embedding similarity, chunk order, explicit references and the call graph as equivalent. Per-build counts are left out on purpose: the file is tracked. Refs #8 --- [signing-metadata] key = cic-my-sign-key signature = vault:v1:MEQCIFv6Tl9vbrUa36oH7C5+g8vMkEi3qkG1zicMfG//zVvVAiB0Zf3lngLgqEyfNIcwYKtHhITEsdhckwcvjKUPh3qoPw== hash-algorithm = sha256 digest = /jHKTVOJ3X0tZBpYsvCUjWgkahs2etF+ULnDgE3+Lv4= [certificate] -----BEGIN CERTIFICATE----- MIICBjCCAaygAwIBAgIUSnRMR6RPnEbg296XWPOqq/u5PCwwCgYIKoZIzj0EAwIw QzELMAkGA1UEBhMCSFUxGTAXBgNVBAoMEENlbnRyYWxJbmZyYUNvcmUxGTAXBgNV BAMMEENJQyBEZXZlbG9wZXIgQ0EwHhcNMjYwMzIwMTMyMjU5WhcNMjYxMjMxMTMy MjU5WjBFMQswCQYDVQQGEwJIVTEZMBcGA1UECgwQQ2VudHJhbEluZnJhQ29yZTEb MBkGA1UEAwwSR2Fib3IgWm9sdGFuIFNpbmtvMFkwEwYHKoZIzj0CAQYIKoZIzj0D AQcDQgAEIG2CVmTfmLB9pLLclj7YmP2eedAjklpy4LGrU2ijoiy6Xqpuybv7OgJe i+ez31s65NEV8+X/ByeX1cstR988z6N8MHowCQYDVR0TBAIwADAdBgNVHQ4EFgQU yZN6AIX/TNnIJ9GwAa/NRN3ujHAwHwYDVR0jBBgwFoAUXn6CHYzPUqU4JVP8g+OS WeDYjhcwDgYDVR0PAQH/BAQDAgeAMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEF BQcDBDAKBggqhkjOPQQDAgNIADBFAiEA+bFzXRoJ4PCQbhAAtpkcMjt0vNj5rEW0 lOMBGDNyaWkCIB1vmM7PcZzv/c9bIrxF5kqv6QXomouhByUfeNUTbpKW -----END CERTIFICATE----- --- MANIFEST.sha256 | 12 +- kb_data/edge_types.md | 8 +- make_source.py | 28 +++- make_source.yaml | 4 +- mcp-server/server.py | 63 ++++++-- mcp-server/server.yaml | 9 +- tests/test_tools/test_edge_types_doc.py | 47 ++++++ .../test_tools/test_mcp_server_edge_types.py | 153 ++++++++++++++++++ 8 files changed, 301 insertions(+), 23 deletions(-) create mode 100644 tests/test_tools/test_edge_types_doc.py create mode 100644 tests/test_tools/test_mcp_server_edge_types.py diff --git a/MANIFEST.sha256 b/MANIFEST.sha256 index 3a83ce1..4322792 100644 --- a/MANIFEST.sha256 +++ b/MANIFEST.sha256 @@ -5,7 +5,6 @@ 0b59cc6e4be3978faaaeed63bcb0d51d60fb067b187dbd8f306e68185ac3e957 tests/test_tools/test_mcp_server_write_confinement.py 113f83b3ca0443799224e8f29396b90777539217771ecb6f1c932df1b5168389 LICENSE.meta.yaml 16183e414f0bb7bc6dc2236f94cba83695ebf78f6afeb75740914308a88cd16c docs/hu/concept/git-managment.md -185a40b1a99c37f644012dbb43aad4325ea0e13428a56527b8fffd81da11739b mcp-server/server.yaml 1a37f1e83308dc84421edec894cc4c81255ece86c1138b02501ca36e4151a1e7 mk/infra.mk 1b3e25bf2122e2d44a8cfc13620797fd129911c5c74d8e1c1db96cee6994f1ce docs/hu/concept/git-managment.meta.yaml 24a1d34027c091e63db840e3abe1430b037fc5a3342ecdd35990559d64f05206 py.meta.schema.yaml @@ -17,16 +16,17 @@ 2e19ebdd9db8f56f6dc5fb006f8bb23037595794d0c288e72901b9f628d2d5b5 tools/git_hook_commit-msg.sh 2ff68b6bbec43e277406b9f26a21ceccdeafc82a79e3f79ca4da18c08a85ac30 tests/test_tools/test_mcp_server.py 3f407782610771dfb687f7eab29b00d89dc12cbb0688f47f565c4e73f2bce3e0 tests/test_tools/test_make_source.py +3fc6008c89801f6e75640224b696d8d94438af2b47e9e7e682fa21b5feab0553 mcp-server/server.py 441f681287c170544f90844b29e4a103f89e91ac23a6cc8e974635d8bcde5a2b docs/en/architecture.md 473d29746d16a50ad7c50d4d742fb3321727659f2736fa831a9f96b4acbe4035 output/cic-mcp-knowledge-mcp-write-confinement-fix.md 47d43a28c3b3041dc9ec977589c5192d1af5b6775998a66742799284f21f66d5 go.meta.schema.yaml 47e80e3d770081a1438ad045a6d2fcdef3f4d0c5885f7f15b467cbb20575892c tools/finalize_release.py -49bfb74a20dfb2249154c15c54bae9ecbce8b93b3feb8238485cf3f71fad298b make_source.yaml +4a2e05dfc61d94e802dc85fb740da25845583a74f40b681cfd93c9f63dc437cb make_source.yaml 4fffcdac095c0623fefb8515ab80b3e9629c0febc454456cd08b3cdf3c941720 LICENSE.md -53b2f2f23c0d880dc7124f6292817b4e03382a5b846ad095e101444d1453f4f0 make_source.py 554d72a5120c2d1fae5843242d685aa2eab0c1def354dcc046509532c77b9896 docs/en/concept/declarative_ecosystem_integration.meta.yaml 580e63a79ebe751ba39cc0e247a0ed6a5e1c97e536d9fe0c76aa3f974ee32283 .mcp.json.tpl 5bfee538966d1233168fb7dba137a649ad4f8e8851f945376c35e9be68c4bb44 sqlite_data/.gitignore +5ce79ed02fcbb6839789cc99bad76c7b73c277411b4e39c83c1907c41782f60f tests/test_tools/test_edge_types_doc.py 5d51889fc8cd00c4c0bf1462b01be8c4d6754e2a4e59dd8e7f0599c610c64472 tools/vault-sign-agent.sh 5d8afd2b9d29065c768de8a21562049904b7c4ad3449448c3159af34e3a0b9df docs/en/concept/git-management.meta.yaml 644649b3590c5cd415f2513fa49998ae0d13ae6fce1dd89c4519deff3af658c6 tools/compiler.py @@ -39,14 +39,16 @@ 7426752feb1140b2023192728df35248e4f802617c150bb0523ab97dc1638c0b tools/init-hooks.sh 74c022f8e67295d11453702a1bb64bd28ece133d2669eee54560f57af281f7de tools/py.meta.gen.yaml 76acd23cb8753e630beb9477b071c8e9c3234584db1a077e20bbcf47737cb23f tests/test_tools/test_releaselib/test_git_service.py +76b4f942692f28253ca91be8f313fd0de79468a19d3665dda1aafa84491084d8 tests/test_tools/test_mcp_server_edge_types.py 7b84214b85a3fd95e9153528df1fa1522ff026df1f561752d95c715250301ca6 tools/vault-sign-agent.md 7bee8cd81eec5da294bb4feba615d57e012c114a921c7dd8fc245ec767360873 .bandit +7d3c15fe41f3db4fb77f046d977bb4acf2c95667bd418b2707cfb4cee40ba5e8 kb_data/edge_types.md 7f9a5c0ad45e98dacfa71af18e03ecbc18b04f9869a90dda4e60821d193edb21 requirements.in 805c05942247d6327f0f006a8799119ace530c4ae288ad637d0f8faddca21d86 docs/hu/architecture.md +87a8ff11408b3cd8f5e49441bdf1daddb49b7639f2241f0c907409425770cd20 make_source.py 882dd5a168b2e6f2da0aa44ad25290768312be47059f8229e8a904bf3814a21f tests/test_tools/test_compiler.py 885e419c23b97b7558a4f599267ef904a9f059ed3c455d3a95eda787ea7ab117 tools/releaselib/git_service.py 8d8feedcf1cdec949962482e960534e1c4810c4a6294da76d14d3d047d27f7e7 kb_data/.gitignore -9033b9dbef3c353fe3413ff31f11fdcee3513e3fc9dffcc16cda3b3cae58e28d kb_data/edge_types.md 9ae92171a29970f17d657a46a3e98e7479f0ecdc02d72b49dfbd64b64b3deebf tools/generate_gitmodules.py a03b3fccfc1f8eb7f76833fdff8a50ea84c80c039db87bc0e41109e96f64420b docs/en/concept/declarative_ecosystem_integration.md a0c9b10725de427edbe8932351594d8e55305ca411734d6880bbd15130b925d9 project.yaml @@ -79,7 +81,7 @@ e7380ef0b0be1345db4c2857c6ba4b1aa8899b8eac78dec32d6ab7e51bdb3bee tests/test_too e7d3c398f904502b595f3e3891c918d0668aa7f804cfdfc013577a9bc839b2bd mcp-server/kb_watch.py ea3d9182bb0cd8f7601d2e80952adfdc91a0dc91c62ef4c8c53929f2d10641fd tools/releaselib/exceptions.py efd889b86e9d669c00c32667d728747612d9c224a8e438e2f381b48145e284e7 features/feature-002/spec.md +f14c29916ffe6cfc5e6072fbf0c5944afe3abe88c0881a2fdd392928284cc4d1 mcp-server/server.yaml f299fac714fa8ffb0a2825b3abdc84dbf0e8aea8e8b61d0ab5ff3afd6b25e52d knowledge.sources.yaml -f4d8d37ef1124a1205c2484ac1c92367bdeb24b946e742bb9eb4b4db5ccc19f5 mcp-server/server.py f9b0d3670f031752765d255a49234d85a221ef79e2517697e8b42eb742837363 Dockerfile ff5ba1a128474476571e01347f5c00215e525b155128da2618d1aacfbf18f54b docs/hu/concept/declarative_ecosystem_integration.meta.yaml diff --git a/kb_data/edge_types.md b/kb_data/edge_types.md index 45d8195..b7f2e25 100644 --- a/kb_data/edge_types.md +++ b/kb_data/edge_types.md @@ -4,5 +4,9 @@ This document lists all unique edge types automatically discovered in the knowle Understanding these relationships is key to querying and interpreting the graph's structure. -- `refers-to` -- `related-to` +The types are not interchangeable. The graph traversal tools (`focus_pack`, `impact_analysis`, `guided_path`) follow every edge by default; pass `edge_types` to restrict them. + +- `calls`: call graph: a Go chunk calls a function that is indexed as another Go node (matched by name). +- `references`: explicit reference: the `related_nodes` of a companion YAML names the target. +- `refers-to`: chunk-order chain: every node points to the next chunk in the global index, across file boundaries. Navigation order, not a semantic relation. +- `related-to`: embedding similarity: cosine similarity of the two chunks is above 0.7. A content-similarity signal, not a dependency. diff --git a/make_source.py b/make_source.py index 604eb45..08fc992 100644 --- a/make_source.py +++ b/make_source.py @@ -759,16 +759,38 @@ def save_kb_to_sqlite(kb_data, output_dir="sqlite_data"): cursor.execute("ANALYZE;") conn.close() +# What each edge type means, as produced by build_knowledge_base(). The traversal tools treat +# every edge alike unless an edge_types allow-list is passed, so readers need to know that the +# types are not interchangeable. +EDGE_TYPE_DESCRIPTIONS = { + 'refers-to': "chunk-order chain: every node points to the next chunk in the global index, " + "across file boundaries. Navigation order, not a semantic relation.", + 'related-to': "embedding similarity: cosine similarity of the two chunks is above 0.7. " + "A content-similarity signal, not a dependency.", + 'references': "explicit reference: the `related_nodes` of a companion YAML names the target.", + 'calls': "call graph: a Go chunk calls a function that is indexed as another Go node " + "(matched by name).", +} + + def generate_edge_types_doc(kb_data, output_dir="kb_data"): - """Generates a markdown file documenting all unique edge types.""" - edge_types = sorted(list(set(edge['type'] for edge in kb_data['edges'].values()))) + """Generates a markdown file documenting all unique edge types and what each one means. + + Counts are deliberately left out: the file is tracked, and per-build counts would change + it on every rebuild. + """ + edge_types = sorted(set(edge['type'] for edge in kb_data['edges'].values())) content = "# Edge Types Documentation\n\n" content += "This document lists all unique edge types automatically discovered in the knowledge graph.\n\n" content += "Understanding these relationships is key to querying and interpreting the graph's structure.\n\n" + content += ("The types are not interchangeable. The graph traversal tools (`focus_pack`, " + "`impact_analysis`, `guided_path`) follow every edge by default; pass `edge_types` " + "to restrict them.\n\n") for edge_type in edge_types: - content += f"- `{edge_type}`\n" + description = EDGE_TYPE_DESCRIPTIONS.get(edge_type, "no description registered for this type.") + content += f"- `{edge_type}`: {description}\n" doc_path = os.path.join(output_dir, 'edge_types.md') with open(doc_path, 'w', encoding='utf-8') as f: diff --git a/make_source.yaml b/make_source.yaml index ead7edf..bff8212 100644 --- a/make_source.yaml +++ b/make_source.yaml @@ -145,5 +145,7 @@ objects: - name: generate_edge_types_doc kind: function decorators: [] - description: Generates a markdown file documenting all unique edge types. + description: 'Generates a markdown file documenting all unique edge types and what + each one means. Counts are deliberately left out: the file is tracked, and per-build + counts would change it on every rebuild.' references: [] diff --git a/mcp-server/server.py b/mcp-server/server.py index 8231ed6..7d707ae 100644 --- a/mcp-server/server.py +++ b/mcp-server/server.py @@ -640,6 +640,28 @@ def _watch_loop() -> None: print(f"[watch] error: {exc}", flush=True) +def _edge_type_of(edge: dict) -> str: + return str(edge.get("type") or edge.get("edge_type") or "") + + +def _allowed_edge_types(edge_types: Optional[list[str]]) -> Optional[set[str]]: + """Normalise the optional edge-type allow-list of the traversal tools. + + None means "follow every edge" (the historical behaviour). A list restricts the + traversal to those types, compared case-insensitively. An empty list follows no + edge at all. + """ + if edge_types is None: + return None + return {str(t).lower() for t in edge_types} + + +def _follow_edges(edges: list[dict], allowed: Optional[set[str]]) -> list[dict]: + if allowed is None: + return edges + return [e for e in edges if _edge_type_of(e).lower() in allowed] + + # ── MCP tools ──────────────────────────────────────────────────────────────── @mcp.tool() @@ -1005,7 +1027,13 @@ def neighbors(node_id: str, edge_type: Optional[str] = None, limit: int = 50) -> return outs[:max_n] @mcp.tool() -def focus_pack(query: str, depth: int = 1, top_k: int = 5, max_rules: int = 3) -> dict: +def focus_pack( + query: str, + depth: int = 1, + top_k: int = 5, + max_rules: int = 3, + edge_types: Optional[list[str]] = None, +) -> dict: """ Build an enriched task context bundle. @@ -1013,8 +1041,12 @@ def focus_pack(query: str, depth: int = 1, top_k: int = 5, max_rules: int = 3) - - prioritizes rule-like chunks/files (CONTRACT, DoD, LIMITS) - returns 'key_rules' - returns 'recommended_reading_order' + + edge_types: optional allow-list of edge types followed during graph expansion + (e.g. ["calls", "references"]). Default None follows every edge. """ kb = load_kb() + allowed = _allowed_edge_types(edge_types) # Safety limits depth = max(0, min(int(depth), 2)) @@ -1051,7 +1083,7 @@ def focus_pack(query: str, depth: int = 1, top_k: int = 5, max_rules: int = 3) - for _ in range(depth): new_frontier = [] for node_id in frontier: - for e in kb["adj"].get(node_id, []): + for e in _follow_edges(kb["adj"].get(node_id, []), allowed): # Robust edge target extraction target = str(e.get("target") or e.get("to") or e.get("dest") or e.get("dst") or "") if target and target not in related_nodes: @@ -1131,7 +1163,7 @@ def focus_pack(query: str, depth: int = 1, top_k: int = 5, max_rules: int = 3) - recommended_files.append(fp) seen_files.add(fp) - return { + result = { "query": query, "primary_nodes": primary_nodes, "related_nodes": sorted(list(related_nodes)), @@ -1140,6 +1172,9 @@ def focus_pack(query: str, depth: int = 1, top_k: int = 5, max_rules: int = 3) - "key_rules": key_rules, "recommended_reading_order": recommended_files, } + if allowed is not None: + result["edge_types"] = sorted(allowed) + return result @mcp.tool() def explain_node(node_id: str) -> dict: @@ -1228,7 +1263,7 @@ def find_nodes( @mcp.tool() -def impact_analysis(node_id: str, max_depth: int = 3) -> dict: +def impact_analysis(node_id: str, max_depth: int = 3, edge_types: Optional[list[str]] = None) -> dict: """Analyse the downstream impact of a node: what depends on it, critical paths, used_in coverage. Performs BFS from node_id through the adjacency graph, collects all reachable downstream @@ -1237,10 +1272,12 @@ def impact_analysis(node_id: str, max_depth: int = 3) -> dict: Args: node_id: The node to start from. max_depth: BFS depth limit (default 3, max 5). + edge_types: Optional allow-list of edge types to follow (default None: every edge). """ kb = load_kb() nodes = kb["nodes"] adj = kb["adj"] + allowed = _allowed_edge_types(edge_types) max_depth = max(1, min(int(max_depth), 5)) start = str(node_id) @@ -1257,7 +1294,7 @@ def impact_analysis(node_id: str, max_depth: int = 3) -> dict: current, depth = queue.pop(0) if depth >= max_depth: continue - edges = adj.get(current, []) + edges = _follow_edges(adj.get(current, []), allowed) fan_out[current] = len(edges) for edge in edges: target = str(edge.get("target") or edge.get("to") or edge.get("dest") or edge.get("dst") or "") @@ -1294,7 +1331,7 @@ def impact_analysis(node_id: str, max_depth: int = 3) -> dict: reverse=True, )[:10] - return { + result = { "node_id": start, "label": nodes.get(start, {}).get("label", start), "total_downstream": len(downstream), @@ -1303,10 +1340,13 @@ def impact_analysis(node_id: str, max_depth: int = 3) -> dict: "used_in_coverage": {k: v for k, v in sorted(used_in_agg.items(), key=lambda x: -len(x[1]))}, "critical_paths": critical, } + if allowed is not None: + result["edge_types"] = sorted(allowed) + return result @mcp.tool() -def guided_path(topic: str, max_steps: int = 10) -> dict: +def guided_path(topic: str, max_steps: int = 10, edge_types: Optional[list[str]] = None) -> dict: """Build an ordered learning path for a topic through the knowledge graph. Selects entrypoint nodes matching the topic, then traverses the graph in @@ -1316,10 +1356,12 @@ def guided_path(topic: str, max_steps: int = 10) -> dict: Args: topic: The topic or concept to learn about. max_steps: Maximum nodes in the path (default 10, max 20). + edge_types: Optional allow-list of edge types to follow (default None: every edge). """ kb = load_kb() nodes = kb["nodes"] adj = kb["adj"] + allowed = _allowed_edge_types(edge_types) chunk_to_nodes = kb.get("chunk_to_nodes", {}) max_steps = max(1, min(int(max_steps), 20)) @@ -1385,7 +1427,7 @@ def _cat_rank(node: dict) -> int: }) # Expand neighbours, prioritise by category rank - edges = adj.get(current, []) + edges = _follow_edges(adj.get(current, []), allowed) children: list[tuple[str, str]] = [] for edge in edges: target = str(edge.get("target") or edge.get("to") or edge.get("dest") or edge.get("dst") or "") @@ -1398,12 +1440,15 @@ def _cat_rank(node: dict) -> int: children.sort(key=lambda x: _cat_rank(nodes.get(x[0], {}))) queue = children + queue # depth-first within priority - return { + result = { "topic": topic, "start_node": start, "entrypoints_found": len(entrypoints), "path": path, } + if allowed is not None: + result["edge_types"] = sorted(allowed) + return result SOURCE_DIR = Path(os.environ.get("SOURCE_DIR", str(Path.cwd()))) diff --git a/mcp-server/server.yaml b/mcp-server/server.yaml index c80ba3e..ddcfd8d 100644 --- a/mcp-server/server.yaml +++ b/mcp-server/server.yaml @@ -242,7 +242,8 @@ objects: - mcp.tool description: 'Build an enriched task context bundle. Compared to standard search: - prioritizes rule-like chunks/files (CONTRACT, DoD, LIMITS) - returns ''key_rules'' - - returns ''recommended_reading_order''' + - returns ''recommended_reading_order'' edge_types: optional allow-list of edge + types followed during graph expansion (default None follows every edge).' references: [] - name: explain_node kind: function @@ -267,7 +268,8 @@ objects: paths, used_in coverage. Performs BFS from node_id through the adjacency graph, collects all reachable downstream nodes, aggregates used_in fields, and identifies critical path nodes (highest fan-out). Args: node_id: The node to start from. - max_depth: BFS depth limit (default 3, max 5).' + max_depth: BFS depth limit (default 3, max 5). edge_types: Optional allow-list + of edge types to follow (default None: every edge).' references: [] - name: guided_path kind: function @@ -277,7 +279,8 @@ objects: Selects entrypoint nodes matching the topic, then traverses the graph in category priority order (concept → architecture → flow → implementation) to return a structured reading sequence. Args: topic: The topic or concept to learn about. max_steps: - Maximum nodes in the path (default 10, max 20).' + Maximum nodes in the path (default 10, max 20). edge_types: Optional allow-list + of edge types to follow (default None: every edge).' references: [] - name: SOURCE_DIR kind: const diff --git a/tests/test_tools/test_edge_types_doc.py b/tests/test_tools/test_edge_types_doc.py new file mode 100644 index 0000000..8a3fdba --- /dev/null +++ b/tests/test_tools/test_edge_types_doc.py @@ -0,0 +1,47 @@ +import os +import sys + +sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../.."))) + +from make_source import EDGE_TYPE_DESCRIPTIONS, generate_edge_types_doc + + +def _doc(tmp_path, edge_types): + edges = {f"e{i}": {"type": t} for i, t in enumerate(edge_types)} + generate_edge_types_doc({"edges": edges}, output_dir=str(tmp_path)) + return (tmp_path / "edge_types.md").read_text(encoding="utf-8") + + +def test_lists_every_type_that_occurs_exactly_once(tmp_path): + doc = _doc( + tmp_path, ["calls", "related-to", "related-to", "references", "refers-to"] + ) + for edge_type in ("calls", "related-to", "references", "refers-to"): + assert doc.count(f"- `{edge_type}`:") == 1 + + +def test_describes_each_known_type(tmp_path): + doc = _doc(tmp_path, list(EDGE_TYPE_DESCRIPTIONS)) + for edge_type, description in EDGE_TYPE_DESCRIPTIONS.items(): + assert f"- `{edge_type}`: {description}" in doc + + +def test_unknown_type_is_listed_with_a_placeholder(tmp_path): + doc = _doc(tmp_path, ["brand-new"]) + assert "- `brand-new`: no description registered for this type." in doc + + +def test_output_is_independent_of_edge_counts(tmp_path): + few = _doc(tmp_path, ["calls"]) + many = _doc(tmp_path, ["calls"] * 50) + assert few == many + + +def test_every_type_the_graph_builder_emits_has_a_description(): + # build_knowledge_base() emits exactly these four types (see create_knowledge_graph_with_content) + assert set(EDGE_TYPE_DESCRIPTIONS) == { + "refers-to", + "related-to", + "references", + "calls", + } diff --git a/tests/test_tools/test_mcp_server_edge_types.py b/tests/test_tools/test_mcp_server_edge_types.py new file mode 100644 index 0000000..53ece9f --- /dev/null +++ b/tests/test_tools/test_mcp_server_edge_types.py @@ -0,0 +1,153 @@ +import os +import sys +from unittest.mock import patch + +sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../.."))) +sys.path.insert( + 0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../../mcp-server")) +) + +import server as mcp_server + +# n1 --refers-to--> n2 +# n1 --calls------> n3 --references--> n5 +# n1 --related-to-> n4 +EDGES = [ + {"from": "n1", "to": "n2", "type": "refers-to"}, + {"from": "n1", "to": "n3", "type": "calls"}, + {"from": "n1", "to": "n4", "type": "related-to"}, + {"from": "n3", "to": "n5", "type": "references"}, +] + + +def _make_kb(): + adj: dict[str, list[dict]] = {} + for e in EDGES: + adj.setdefault(e["from"], []).append(e) + nodes = { + f"n{i}": { + "id": f"n{i}", + "label": f"node {i}", + "type": "section", + "chunk_id": f"c{i}", + "category": ["concept"], + "entrypoint": i == 1, + } + for i in range(1, 6) + } + chunks = { + f"c{i}": { + "id": f"c{i}", + "text": f"text {i}", + "file_path": f"docs/{i}.md", + "section": f"S{i}", + } + for i in range(1, 6) + } + return { + "nodes": nodes, + "edges": EDGES, + "adj": adj, + "chunks": chunks, + "chunk_to_nodes": {f"c{i}": [f"n{i}"] for i in range(1, 6)}, + } + + +def _hits(): + return [{"chunk_id": "c1", "score": 1.0}] + + +def _downstream_ids(result): + return {d["node_id"] for d in result["downstream"]} + + +class TestImpactAnalysisEdgeTypes: + def test_default_follows_every_edge_and_adds_no_key(self): + with patch.object(mcp_server, "load_kb", return_value=_make_kb()): + result = mcp_server.impact_analysis("n1") + assert _downstream_ids(result) == {"n2", "n3", "n4", "n5"} + assert "edge_types" not in result + + def test_allow_list_restricts_traversal(self): + with patch.object(mcp_server, "load_kb", return_value=_make_kb()): + result = mcp_server.impact_analysis("n1", edge_types=["calls"]) + assert _downstream_ids(result) == {"n3"} + assert result["edge_types"] == ["calls"] + + def test_allow_list_with_two_types_reaches_through_both(self): + with patch.object(mcp_server, "load_kb", return_value=_make_kb()): + result = mcp_server.impact_analysis( + "n1", edge_types=["calls", "references"] + ) + assert _downstream_ids(result) == {"n3", "n5"} + + def test_types_are_case_insensitive(self): + with patch.object(mcp_server, "load_kb", return_value=_make_kb()): + result = mcp_server.impact_analysis("n1", edge_types=["CALLS"]) + assert _downstream_ids(result) == {"n3"} + + def test_empty_list_follows_no_edge(self): + with patch.object(mcp_server, "load_kb", return_value=_make_kb()): + result = mcp_server.impact_analysis("n1", edge_types=[]) + assert result["downstream"] == [] + assert result["edge_types"] == [] + + def test_unknown_type_follows_no_edge(self): + with patch.object(mcp_server, "load_kb", return_value=_make_kb()): + result = mcp_server.impact_analysis("n1", edge_types=["no-such-type"]) + assert result["downstream"] == [] + + +class TestFocusPackEdgeTypes: + def _run(self, **kwargs): + with ( + patch.object(mcp_server, "load_kb", return_value=_make_kb()), + patch.object(mcp_server, "search_query", return_value=_hits()), + ): + return mcp_server.focus_pack("anything", **kwargs) + + def test_default_follows_every_edge_and_adds_no_key(self): + result = self._run(depth=2) + assert set(result["related_nodes"]) == {"n1", "n2", "n3", "n4", "n5"} + assert "edge_types" not in result + + def test_allow_list_restricts_expansion(self): + result = self._run(depth=1, edge_types=["calls"]) + assert set(result["related_nodes"]) == {"n1", "n3"} + assert result["edge_types"] == ["calls"] + + def test_allow_list_follows_chain_over_depth(self): + result = self._run(depth=2, edge_types=["calls", "references"]) + assert set(result["related_nodes"]) == {"n1", "n3", "n5"} + + def test_filtered_expansion_drops_the_chunks_of_unfollowed_nodes(self): + result = self._run(depth=2, edge_types=["calls"]) + assert "c2" not in result["chunks"] + assert "c3" in result["chunks"] + + def test_empty_list_keeps_only_the_primary_nodes(self): + result = self._run(depth=2, edge_types=[]) + assert set(result["related_nodes"]) == {"n1"} + + +class TestGuidedPathEdgeTypes: + def _run(self, **kwargs): + with ( + patch.object(mcp_server, "load_kb", return_value=_make_kb()), + patch.object(mcp_server, "search_query", return_value=_hits()), + ): + return mcp_server.guided_path("anything", **kwargs) + + @staticmethod + def _path_ids(result): + return {step["node_id"] for step in result["path"]} + + def test_default_follows_every_edge_and_adds_no_key(self): + result = self._run() + assert self._path_ids(result) == {"n1", "n2", "n3", "n4", "n5"} + assert "edge_types" not in result + + def test_allow_list_restricts_the_path(self): + result = self._run(edge_types=["calls", "references"]) + assert self._path_ids(result) == {"n1", "n3", "n5"} + assert result["edge_types"] == ["calls", "references"]