Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions MANIFEST.sha256
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
8 changes: 6 additions & 2 deletions kb_data/edge_types.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
28 changes: 25 additions & 3 deletions make_source.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
4 changes: 3 additions & 1 deletion make_source.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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: []
63 changes: 54 additions & 9 deletions mcp-server/server.py
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down Expand Up @@ -1005,16 +1027,26 @@ 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.

Compared to standard search:
- 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))
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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)),
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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)
Expand All @@ -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 "")
Expand Down Expand Up @@ -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),
Expand All @@ -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
Expand All @@ -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))
Expand Down Expand Up @@ -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 "")
Expand All @@ -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())))
Expand Down
9 changes: 6 additions & 3 deletions mcp-server/server.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
47 changes: 47 additions & 0 deletions tests/test_tools/test_edge_types_doc.py
Original file line number Diff line number Diff line change
@@ -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",
}
Loading
Loading