katalyst-plugin-context 0.2.1a3__tar.gz → 0.2.1a5__tar.gz

{katalyst_plugin_context-0.2.1a3 → katalyst_plugin_context-0.2.1a5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: katalyst-plugin-context
-Version: 0.2.1a3
+Version: 0.2.1a5
 Summary: Katalyst context plugin — the right context from the taxonomy for an agent working on a node
 Author: eSimplicity
 License: Proprietary

{katalyst_plugin_context-0.2.1a3 → katalyst_plugin_context-0.2.1a5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "katalyst-plugin-context"
-version = "0.2.1a3"
+version = "0.2.1a5"
 description = "Katalyst context plugin — the right context from the taxonomy for an agent working on a node"
 license = { text = "Proprietary" }
 requires-python = ">=3.12"

{katalyst_plugin_context-0.2.1a3 → katalyst_plugin_context-0.2.1a5}/src/katalyst_plugin_context/adapters/runtime_graph.py

@@ -10,7 +10,7 @@ another.
 
 from __future__ import annotations
 
-from collections.abc import Iterable
+from collections.abc import Callable, Iterable, Sequence
 from typing import Any, cast
 
 from katalyst_engine.model.node import Node
@@ -20,11 +20,16 @@ from katalyst_taxonomy.engine.accessors import (
     get_node_backend,
 )
 from katalyst_taxonomy.engine.identity import split_backend_prefix
+from katalyst_taxonomy.engine.qualification import split_kind_selector
 from katalyst_taxonomy.ports.backend import TaxonomyBackend
 
 from katalyst_plugin_context.domain.graph import Edge, Graph, GraphNode
 
-__all__ = ["build_graph", "graph_from"]
+__all__ = ["Carriers", "build_graph", "graph_from"]
+
+#: What a kind can carry: the relationship types it holds, each with the kinds it may point at
+#: (empty: any kind).
+Carriers = Callable[[str], Sequence[tuple[str, frozenset[str]]]]
 
 
 def _graph_node(doc: Node, backend: str, key: str) -> GraphNode:
@@ -47,10 +52,16 @@ def graph_from(
     relationships: Iterable[tuple[str, str, str, str]],
     *,
     hidden: Iterable[tuple[str, str]] = (),
+    carriers: Carriers | None = None,
 ) -> Graph:
     """A graph over *documents* (``(holder backend, node)``) and *relationships*
     (``(holder backend, source fqtn, rel, target fqtn)``).
 
+    An edge names its ends by qualified name, so a name two kinds share is ambiguous. With
+    *carriers* the edge is placed by identity: the source is the node of a kind that carries
+    the relationship, the target one that kind may point at. An edge that still fits several
+    nodes, or none, is dropped rather than guessed.
+
     An edge to an address in *hidden* (``(backend, fqtn)`` of nodes the profile's filters
     hide) is left out silently. Any other edge that reaches no node is counted as dropped.
     Nothing about a hidden node is counted.
@@ -64,39 +75,72 @@ def graph_from(
         fqn = doc.fqn or doc.name
         pending.append((backend, fqn, doc))
         by_address.setdefault((backend, fqn), []).append(doc.kind)
-    for backend, fqn, doc in pending:
+
+    def key_of(backend: str, fqn: str, kind: str) -> str:
         shared = len(by_address[(backend, fqn)]) > 1
-        key = f"{backend}:{fqn}#{doc.kind}" if shared else f"{backend}:{fqn}"
-        nodes.append(_graph_node(doc, backend, key))
-
-    def key_of(holder: str, address: str) -> str | None:
-        prefix, rest = split_backend_prefix(address)
-        backend = prefix or holder
-        kinds = by_address.get((backend, rest))
-        if kinds is None or len(kinds) != 1:
+        return f"{backend}:{fqn}#{kind}" if shared else f"{backend}:{fqn}"
+
+    nodes.extend(
+        _graph_node(doc, backend, key_of(backend, fqn, doc.kind)) for backend, fqn, doc in pending
+    )
+
+    def ends_of(holder: str, source: str, rel: str, target: str) -> tuple[str, str] | None:
+        source_backend, source_fqn = _address(holder, source)
+        target_backend, target_fqn = _address(holder, target)
+        sources = _of_kind(by_address.get((source_backend, source_fqn), []), source)
+        targets = _of_kind(by_address.get((target_backend, target_fqn), []), target)
+        if len(sources) == 1 and len(targets) == 1:
+            return (
+                key_of(source_backend, source_fqn, sources[0]),
+                key_of(target_backend, target_fqn, targets[0]),
+            )
+        if carriers is None or not sources or not targets:
             return None
-        return f"{backend}:{rest}"
+        placed = {
+            (source_kind, target_kind)
+            for source_kind in sources
+            for carried_rel, accepted in carriers(source_kind)
+            if carried_rel == rel
+            for target_kind in targets
+            if not accepted or target_kind in accepted
+        }
+        if len(placed) != 1:
+            return None
+        source_kind, target_kind = next(iter(placed))
+        return (
+            key_of(source_backend, source_fqn, source_kind),
+            key_of(target_backend, target_fqn, target_kind),
+        )
 
     edges: list[Edge] = []
     dropped = 0
     for holder, source, rel, target in relationships:
-        source_key, target_key = key_of(holder, source), key_of(holder, target)
-        if source_key is None or target_key is None:
-            ends = (_address(holder, source), _address(holder, target))
-            if not any(end in hidden_addresses for end in ends):
+        ends = ends_of(holder, source, rel, target)
+        if ends is None:
+            addresses = (_address(holder, source), _address(holder, target))
+            if not any(end in hidden_addresses for end in addresses):
                 dropped += 1
             continue
-        edges.append(Edge(rel=rel, source=source_key, target=target_key))
+        edges.append(Edge(rel=rel, source=ends[0], target=ends[1]))
     return Graph(nodes, edges, dropped=dropped)
 
 
 def _address(holder: str, value: str) -> tuple[str, str]:
-    prefix, rest = split_backend_prefix(value)
+    prefix, rest = split_backend_prefix(split_kind_selector(value)[0])
     return (prefix or holder, rest)
 
 
+def _of_kind(kinds: list[str], address: str) -> list[str]:
+    """The kinds at an address, narrowed to its ``#kind`` when it names one."""
+    selected = split_kind_selector(address)[1]
+    return kinds if selected is None else [kind for kind in kinds if kind == selected]
+
+
 def build_graph(
-    sources: Iterable[tuple[str, TaxonomyBackend]], *, profile: str | None = None
+    sources: Iterable[tuple[str, TaxonomyBackend]],
+    *,
+    profile: str | None = None,
+    carriers: Carriers | None = None,
 ) -> Graph:
     """Read every backend in *sources* once and build the graph the profile may see.
 
@@ -123,4 +167,5 @@ def build_graph(
         ((holder, doc) for holder, doc in loaded if id(doc) in visible),
         relationships,
         hidden=list(hidden),
+        carriers=carriers,
     )

{katalyst_plugin_context-0.2.1a3 → katalyst_plugin_context-0.2.1a5}/src/katalyst_plugin_context/composition.py

@@ -15,7 +15,7 @@ from katalyst_engine.schema.registry import SchemaRegistry
 from katalyst_taxonomy.ports.backend import TaxonomyBackend
 
 from katalyst_plugin_context.adapters.runtime_graph import build_graph
-from katalyst_plugin_context.service import NAMESPACE, ContextService
+from katalyst_plugin_context.service import NAMESPACE, ContextService, RegistrySchema
 
 __all__ = ["plugin_config", "service_for"]
 
@@ -45,5 +45,6 @@ def service_for(
 ) -> ContextService:
     """The service over what *sources* hold, under the profile named *profile*."""
     config, active = plugin_config(profile)
-    graph = build_graph(sources, profile=active)
+    schema = RegistrySchema(registry)
+    graph = build_graph(sources, profile=active, carriers=schema.carried)
     return ContextService(registry, graph, config=config, profile=active)

{katalyst_plugin_context-0.2.1a3 → katalyst_plugin_context-0.2.1a5}/src/katalyst_plugin_context/domain/context.py

@@ -27,6 +27,7 @@ __all__ = [
     "build_result",
     "content_size",
     "estimate_tokens",
+    "more_routes",
 ]
 
 #: How much of a description ``summary`` shows, and of each summary field's value.
@@ -120,6 +121,7 @@ def _walk(
     policy: Policy,
     *,
     exclude: frozenset[str],
+    open_to_named: frozenset[str] = frozenset(),
     inherited: bool,
     parent_rel: str,
     collect_every_level: bool,
@@ -127,8 +129,10 @@ def _walk(
     """Every node reached from *start* by following *steps*, with the hops that reached it.
 
     A node never appears twice on one branch (cycles stop). *exclude* (the focus node and
-    its ancestors) is never reached. From an ancestor, its structural parent edges are
-    never followed: they would only reach siblings.
+    its ancestors) is never reached, except that a step which names its relationship
+    (not ``*``) may reach the nodes of *open_to_named*: asking for ``CHILD_OF:out`` is
+    asking for the ancestors. From an ancestor, its structural parent edges are never
+    followed: they would only reach siblings.
     """
     frontier: list[tuple[str, tuple[_Hop, ...]]] = [(start, ())]
     arrivals: list[_Arrival] = []
@@ -140,7 +144,11 @@ def _walk(
                 if inherited and index == 0 and neighbour.rel == parent_rel:
                     continue
                 other = graph.nodes[neighbour.other]
-                if neighbour.other in exclude or neighbour.other in on_branch:
+                if neighbour.other in on_branch:
+                    continue
+                if neighbour.other in exclude and not (
+                    step.rel != "*" and neighbour.other in open_to_named
+                ):
                     continue
                 if not step.matches(neighbour.rel, neighbour.direction, other.kind):
                     continue
@@ -246,7 +254,7 @@ def _item_payload(
 ) -> dict[str, Any]:
     node = entry.node
     hints = schema.hints(node.kind)
-    whys = sorted(entry.whys, key=lambda w: w[0])
+    whys = sorted(entry.whys, key=lambda w: (len(w[1].hops), w[0]))
     payload: dict[str, Any] = {
         "qualifiedName": node.key,
         "kind": node.kind,
@@ -310,16 +318,25 @@ def _text(value: object) -> str:
     return value if isinstance(value, str) else json.dumps(value, default=str, ensure_ascii=False)
 
 
+def more_routes(count: int) -> str:
+    """The note that *count* further routes reach an item."""
+    return f"(+{count} more route{'' if count == 1 else 's'})"
+
+
 def content_size(item: Mapping[str, Any]) -> int:
     """The item's content in estimated tokens, whatever format the answer is given in.
 
-    Counts what a reader reads: the qualified name, kind and title, each ``why``, each
-    blocking value, the description, the fields, and at ``full`` the spec and the body.
-    No keys, punctuation or markup, so a JSON and a markdown answer hold the same items
-    for the same budget.
+    Counts what a reader reads: the qualified name, kind and title, the ``why`` (the
+    shortest route and a note of the others, or every route at ``full``), each blocking
+    value, the description, the fields, and at ``full`` the spec and the body. No keys,
+    punctuation or markup, so a JSON and a markdown answer hold the same items for the same
+    budget.
     """
     parts: list[str] = [str(item["qualifiedName"]), str(item["kind"]), str(item["title"])]
-    parts.extend(str(why["text"]) for why in item.get("why") or ())
+    routes = [str(why["text"]) for why in item.get("why") or ()]
+    if item.get("detail") != FULL and len(routes) > 1:
+        routes = [routes[0], more_routes(len(routes) - 1)]
+    parts.extend(routes)
     blocking = item.get("blocking")
     entries = cast(
         "list[Mapping[str, Any]]",
@@ -491,7 +508,8 @@ def _collect(
     """Every item *sources* reach, at its best rank, and each view's and path's members.
 
     The ancestors are never items of a source that inherits, or of any source when the
-    call inherits; otherwise (inheritance off) they can be.
+    call inherits, unless a step names the relationship that reaches them; otherwise
+    (inheritance off) they can be.
     """
     entries: dict[str, _Entry] = {}
     group_members: dict[tuple[str | None, str], set[str]] = {}
@@ -508,6 +526,7 @@ def _collect(
                 steps,
                 policy,
                 exclude=exclude,
+                open_to_named=frozenset(ancestors),
                 inherited=start != focus,
                 parent_rel=schema.parent_rel,
                 collect_every_level=source.repeat > 1,

{katalyst_plugin_context-0.2.1a3 → katalyst_plugin_context-0.2.1a5}/src/katalyst_plugin_context/domain/markdown.py

@@ -10,6 +10,8 @@ from __future__ import annotations
 from collections.abc import Mapping, Sequence
 from typing import Any, cast
 
+from katalyst_plugin_context.domain.context import more_routes
+
 __all__ = ["item_block", "render_map", "render_result"]
 
 
@@ -27,32 +29,99 @@ def _blocking_marker(item: Mapping[str, Any]) -> str:
     return "_advisory_ · "
 
 
+def _text(value: object) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return "null" if value is None else str(value)
+
+
+def _empty(value: object) -> bool:
+    return value is None or value == "" or (isinstance(value, (list, dict)) and not value)
+
+
+def _entry(label: str | None, value: object, indent: int) -> list[str]:
+    """One value as a bullet at *indent*: lists as bullets, mappings as nested bullets.
+
+    A multi-line text sits under its label, one line per line. A list element that is a
+    mapping is one bullet of its plain values, with any longer value nested under it.
+    """
+    pad = " " * indent
+    lead = f"{label}: " if label is not None else ""
+    if isinstance(value, Mapping):
+        members = {
+            str(key): member
+            for key, member in cast("Mapping[object, object]", value).items()
+            if not _empty(member)
+        }
+        if label is None:
+            plain = [f"{k}: {_text(v)}" for k, v in members.items() if _inline(v)]
+            rest = [
+                line
+                for k, v in members.items()
+                if not _inline(v)
+                for line in _entry(k, v, indent + 2)
+            ]
+            return [f"{pad}- " + " · ".join(plain) if plain else f"{pad}-", *rest]
+        inner = [line for k, v in members.items() for line in _entry(k, v, indent + 2)]
+        return [f"{pad}- {label}:", *inner]
+    if isinstance(value, (list, tuple)):
+        inner = [
+            line
+            for member in cast("Sequence[object]", value)
+            for line in _entry(None, member, indent + 2)
+        ]
+        return [f"{pad}- {label}:", *inner] if label is not None else inner
+    text = _text(value).strip()
+    if "\n" in text:
+        body = [f"{pad}  {line}".rstrip() for line in text.splitlines()]
+        return [f"{pad}- {lead.rstrip()}".rstrip(), *body]
+    return [f"{pad}- {lead}{text}"]
+
+
+def _inline(value: object) -> bool:
+    return isinstance(value, (str, int, float, bool)) and "\n" not in str(value)
+
+
+def _routes(item: Mapping[str, Any]) -> list[str]:
+    routes = [str(why["text"]) for why in cast("list[Mapping[str, Any]]", item.get("why") or [])]
+    if item.get("detail") != "full" and len(routes) > 1:
+        return [f"{routes[0]} {more_routes(len(routes) - 1)}"]
+    return routes
+
+
 def item_block(item: Mapping[str, Any]) -> str:
-    """One item as a markdown list entry."""
+    """One item as a markdown list entry: what the JSON item holds, in the same words.
+
+    At ``full`` every spec field (long text whole); at ``summary`` the declared summary
+    fields; both with lists as bullets and mappings as nested bullets.
+    """
     head = f"- {_blocking_marker(item)}**{item['title']}** `{item['qualifiedName']}`"
     fields = cast("Mapping[str, Any]", item.get("fields") or {})
-    shown = [f"{k}: {v}" for k, v in fields.items() if not isinstance(v, (list, dict))]
-    lines = [head + (" · " + " · ".join(shown) if shown else "")]
+    full = item.get("detail") == "full"
+    spec = cast("Mapping[str, Any]", item.get("spec") or {})
     description = item.get("description")
+    shown = {k: v for k, v in fields.items() if _inline(v) and not (full and spec.get(k, v) != v)}
+    lines = [head + (" · " + " · ".join(f"{k}: {v}" for k, v in shown.items()) if shown else "")]
     if description:
         length = int(item.get("descriptionLength") or 0)
         more = (
             f" _({length:,} chars; detail=full for all)_"
-            if item.get("detail") != "full" and length > len(str(description))
+            if not full and length > len(str(description))
             else ""
         )
         lines.append(f"  {str(description).strip()}{more}")
-    for why in cast("list[Mapping[str, Any]]", item.get("why") or []):
-        lines.append(f"  why: {why['text']}")
-    if item.get("detail") == "full":
-        spec = cast("Mapping[str, Any]", item.get("spec") or {})
-        extra = {k: v for k, v in spec.items() if k not in fields}
-        for key, value in extra.items():
-            lines.append(f"  {key}: {value}")
-        body = item.get("body")
-        if body:
-            lines.append("")
-            lines.extend(f"  {line}" for line in str(body).strip().splitlines())
+    lines.extend(f"  why: {route}" for route in _routes(item))
+    held = spec if full else fields
+    for key, value in held.items():
+        if key in shown or _empty(value):
+            continue
+        if full and value in (item.get("title"), description):
+            continue
+        lines.extend(_entry(key, value, 2))
+    body = item.get("body")
+    if full and body:
+        lines.append("")
+        lines.extend(f"  {line}" for line in str(body).strip().splitlines())
     return "\n".join(lines)
 
 

{katalyst_plugin_context-0.2.1a3 → katalyst_plugin_context-0.2.1a5}/tests/context_support.py

@@ -27,6 +27,7 @@ from katalyst_engine.schema.registry import SchemaRegistry
 from katalyst_plugin_context.adapters.runtime_graph import graph_from
 from katalyst_plugin_context.domain.graph import Graph
 from katalyst_plugin_context.service import ContextService
+from katalyst_taxonomy.engine.relationships import carriers_of
 
 GOVERNANCE: dict[str, Any] = {
     "title": "Governing decisions",
@@ -103,7 +104,7 @@ def registry(
         WingDefinition(
             identity=Identity(kind="wing_definition", name="craft"),
             describes_kind="craft",
-            member_kinds=("decision", "rule", "guide", "gadget", "method", "bundle"),
+            member_kinds=("decision", "rule", "guide", "gadget", "method", "bundle", "checklist"),
             plugin_settings={"context": {"title_field": "title"}},
         )
     )
@@ -145,6 +146,21 @@ def registry(
             },
         )
     )
+    reg.register_node(
+        _kind(
+            "checklist",
+            wing="craft",
+            fields=(
+                *titled,
+                FieldSpec(name="checks", field_type="list"),
+                FieldSpec(name="violations", field_type="list"),
+                FieldSpec(name="rules", field_type="list"),
+                FieldSpec(name="rationale"),
+                FieldSpec(name="notes"),
+            ),
+            settings={"summary_fields": ["checks", "violations"]},
+        )
+    )
     mode = FieldSpec(
         name="mode",
         default="must",
@@ -225,6 +241,26 @@ DOCUMENTS: tuple[Node, ...] = (
     node("method", "m-strict", title="Strict", mode="must", gadgets=["hammer"]),
     node("method", "m-loose", title="Loose", mode="may", gadgets=["hammer"]),
     node("bundle", "b-all", title="All", methods=["m-strict", "m-loose"]),
+    node(
+        "checklist",
+        "c-hygiene",
+        title="Hygiene",
+        status="required",
+        checks=["Runs inside its worktree", "Leaves no stray files"],
+        violations=[
+            {"pattern": "rm -rf /", "severity": "error", "message": "Never delete the root"},
+            {"pattern": "git push --force", "severity": "warn", "message": "Force pushes"},
+        ],
+        rules=[
+            {
+                "id": "stay-put",
+                "title": "Stay in the worktree",
+                "body": "Write only inside the run worktree.\nNever outside it.",
+            }
+        ],
+        rationale="Because isolation matters. " * 12,
+        notes="Short note",
+    ),
 )
 
 #: (source, rel, target) within backend "repo", as list_relationships would give them.
@@ -241,15 +277,20 @@ EDGES: tuple[tuple[str, str, str], ...] = (
     ("m-loose", "USES_GADGET", "hammer"),
     ("b-all", "INCLUDES_METHOD", "m-strict"),
     ("b-all", "INCLUDES_METHOD", "m-loose"),
+    ("m-strict", "FOLLOWS_CHECKLIST", "c-hygiene"),
 )
 
 
 def graph(
-    documents: tuple[Node, ...] = DOCUMENTS, edges: tuple[tuple[str, str, str], ...] = EDGES
+    documents: tuple[Node, ...] = DOCUMENTS,
+    edges: tuple[tuple[str, str, str], ...] = EDGES,
+    reg: SchemaRegistry | None = None,
 ) -> Graph:
+    schema = reg or registry()
     return graph_from(
         (("repo", doc) for doc in documents),
         (("repo", source, rel, target) for source, rel, target in edges),
+        carriers=lambda kind: [(c.rel_type, c.target_kinds) for c in carriers_of(schema, kind)],
     )
 
 
@@ -257,7 +298,11 @@ def service(
     reg: SchemaRegistry | None = None,
     *,
     documents: tuple[Node, ...] = DOCUMENTS,
+    edges: tuple[tuple[str, str, str], ...] = EDGES,
     config: Mapping[str, Any] | None = None,
     profile: str | None = None,
 ) -> ContextService:
-    return ContextService(reg or registry(), graph(documents), config=config or {}, profile=profile)
+    schema = reg or registry()
+    return ContextService(
+        schema, graph(documents, edges, schema), config=config or {}, profile=profile
+    )

{katalyst_plugin_context-0.2.1a3 → katalyst_plugin_context-0.2.1a5}/tests/test_context.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from typing import Any
 
 import pytest
-from context_support import DOCUMENTS, GOVERNANCE, node, registry, service
+from context_support import DOCUMENTS, EDGES, GOVERNANCE, node, registry, service
 from katalyst_plugin_context.adapters.runtime_graph import graph_from
 from katalyst_plugin_context.domain.context import ContextError, ContextRequest
 from katalyst_plugin_context.domain.paths import PathSyntaxError, Step, parse_path, parse_step
@@ -184,6 +184,43 @@ def test_an_always_view_keeps_its_inheritance_when_the_request_turns_it_off() ->
     assert "repo:d-region" in _names(result, view="governance")
 
 
+def test_a_path_that_names_the_parent_relationship_returns_the_ancestors_by_default() -> None:
+    """#303: the ancestors were items only with inheritance off; the default made the path dead."""
+    result = service().query(UNIT, ContextRequest(paths=("CHILD_OF:out",), depth=2))
+    assert result["effective"]["inherit"] is True
+    assert set(_names(result, view=None)) == {"repo:north.east", "repo:north"}
+    parent = next(i for i in result["items"] if i["qualifiedName"] == "repo:north.east")
+    assert (parent["path"], parent["inheritedFrom"]) == ("CHILD_OF:out", None)
+
+
+def test_a_declared_view_path_on_the_parent_relationship_returns_the_ancestors() -> None:
+    parents = {"title": "Parents", "paths": ["CHILD_OF:out"], "inherit": True}
+    settings = {
+        "views": {"governance": GOVERNANCE, "parents": parents},
+        "policy": {"always_include": ["governance"]},
+    }
+    result = service(registry(unit_settings=settings)).query(
+        UNIT, ContextRequest(views=("parents",))
+    )
+    assert set(_names(result, view="parents")) == {"repo:north.east"}
+
+
+def test_a_wildcard_step_never_returns_the_ancestors_with_inheritance_on() -> None:
+    result = service().query(UNIT, ContextRequest(paths=("*:out",)))
+    assert not {"repo:north.east", "repo:north"} & set(_names(result, view=None))
+    assert not {"repo:north.east", "repo:north"} & set(_names(result))
+
+
+def test_the_map_row_and_the_items_of_the_parent_path_agree() -> None:
+    mapped = service().map(UNIT)
+    row = next(
+        r for r in mapped["relationships"] if r["path"] == "CHILD_OF:out" and not r.get("inherited")
+    )
+    assert row["count"] == 1
+    items = service().query(UNIT, ContextRequest(paths=("CHILD_OF:out",)))["items"]
+    assert [i["qualifiedName"] for i in items if i["path"] == "CHILD_OF:out"] == ["repo:north.east"]
+
+
 def test_policy_can_take_an_always_view_out_and_says_which_layer() -> None:
     config: dict[str, Any] = {"policy": {"always_include": []}}
     svc = service(config=config)
@@ -452,6 +489,86 @@ def test_edges_to_hidden_nodes_are_left_out_without_being_counted() -> None:
     assert list(graph.neighbours("a:north")) == [] and graph.dropped == 1
 
 
+def test_a_name_two_kinds_share_is_walked_by_its_own_edges() -> None:
+    shared = (*DOCUMENTS, node("decision", "hammer", title="Hammer decision"))
+    svc = service(documents=shared)
+    gadget = svc.query("repo:hammer#gadget", ContextRequest())
+    assert gadget["node"]["qualifiedName"] == "repo:hammer#gadget"
+    assert {"repo:m-strict", "repo:m-loose", UNIT} <= set(_names(gadget))
+    decision = svc.query("repo:hammer#decision", ContextRequest(detail="refs"))
+    assert _names(decision) == []
+    assert (
+        svc.query(UNIT, ContextRequest(paths=("USES_GADGET:out",)))["items"][-1]["qualifiedName"]
+        == "repo:hammer#gadget"
+    )
+
+
+def test_a_source_that_shares_its_name_keeps_its_own_edges() -> None:
+    shared = (*DOCUMENTS, node("rule", "m-strict", title="Same name"))
+    svc = service(documents=shared)
+    method = svc.query("repo:m-strict#method", ContextRequest(paths=("USES_GADGET:out",)))
+    assert _names(method, view=None) == ["repo:hammer"]
+    rule = svc.query("repo:m-strict#rule", ContextRequest(paths=("USES_GADGET:out",)))
+    assert _names(rule, view=None) == []
+
+
+def test_an_edge_the_schema_cannot_place_between_shared_names_is_dropped_not_guessed() -> None:
+    shared = (*DOCUMENTS, node("decision", "c-hygiene", title="Same name"))
+    graph = service(documents=shared)._graph  # pyright: ignore[reportPrivateUsage]
+    assert list(graph.neighbours("repo:c-hygiene#checklist")) == []
+    assert graph.dropped == 1
+
+
+# ── one item, many routes ───────────────────────────────────────────────
+
+SHORT = "USES_GADGET:out/USES_GADGET:in"
+LONG_ROUTE = "USES_GADGET:out/USES_GADGET:in/INCLUDES_METHOD:in"
+SECOND_ROUTE = (*EDGES, ("b-all", "USES_GADGET", "hammer"))
+
+
+def _bundle(result: dict[str, Any]) -> dict[str, Any]:
+    return next(i for i in result["items"] if i["qualifiedName"] == "repo:b-all")
+
+
+def test_the_shortest_route_comes_first_and_the_json_keeps_every_route() -> None:
+    svc = service(edges=SECOND_ROUTE)
+    result = svc.query(UNIT, ContextRequest(paths=(LONG_ROUTE, SHORT), views=()))
+    bundle = _bundle(result)
+    assert [len(w["hops"]) for w in bundle["why"]] == [2, 3, 3]
+
+
+def test_markdown_prints_the_shortest_route_and_counts_the_others() -> None:
+    svc = service(edges=SECOND_ROUTE)
+    request = ContextRequest(paths=(LONG_ROUTE, SHORT), format="markdown")
+    text = svc.markdown_for_result(UNIT, svc.query(UNIT, request))
+    block = text[text.index("**All**") :].split("\n- ")[0]
+    assert block.count("why:") == 1 and "(+2 more routes)" in block
+    assert text.count("more route") == 1
+
+
+def test_markdown_lists_every_route_at_full() -> None:
+    svc = service(edges=SECOND_ROUTE)
+    request = ContextRequest(paths=(LONG_ROUTE, SHORT), detail="full", format="markdown")
+    text = svc.markdown_for_result(UNIT, svc.query(UNIT, request))
+    block = text[text.index("**All**") :].split("\n- ")[0]
+    assert block.count("why:") == 3 and "more route" not in block
+
+
+def test_an_item_with_many_routes_is_counted_once_in_the_budget() -> None:
+    from katalyst_plugin_context.domain.context import content_size
+
+    svc = service(edges=SECOND_ROUTE)
+    asked = ContextRequest(paths=(LONG_ROUTE, SHORT), detail="refs", budget=32000)
+    bundle = _bundle(svc.query(UNIT, asked))
+    assert len(bundle["why"]) == 3
+    one_route = {**bundle, "why": bundle["why"][:1]}
+    # Collapsed: the shortest route and the "(+2 more routes)" note, never the others.
+    assert content_size(bundle) - content_size(one_route) <= 4
+    assert content_size({**bundle, "detail": "full"}) > content_size(bundle) + 8
+    full = ContextRequest(paths=(LONG_ROUTE, SHORT), detail="full", budget=32000)
+    assert content_size(_bundle(svc.query(UNIT, full))) > content_size(bundle)
+
+
 # ── markdown ────────────────────────────────────────────────────────────
 
 
@@ -466,3 +583,63 @@ def test_markdown_groups_by_view_and_kind_and_reports_cuts() -> None:
     blocking = svc.markdown_for_result("repo:hammer", svc.query("repo:hammer", ContextRequest()))
     assert "⛔ blocking" in blocking and "_advisory_" in blocking
     assert "## Relationships" in svc.markdown_for_map(svc.map(UNIT))
+
+
+# ── markdown shows a node's fields ──────────────────────────────────────
+
+CHECKLIST = "FOLLOWS_CHECKLIST:out"
+METHOD = "repo:m-strict"
+
+
+def _markdown(detail: str, budget: int | None = None) -> str:
+    svc = service()
+    request = ContextRequest(paths=(CHECKLIST,), detail=detail, budget=budget, format="markdown")
+    return svc.markdown_for_result(METHOD, svc.query(METHOD, request))
+
+
+def test_markdown_at_full_renders_lists_as_bullets_and_mappings_as_nested_bullets() -> None:
+    text = _markdown("full")
+    assert "  - checks:\n    - Runs inside its worktree\n    - Leaves no stray files" in text
+    assert (
+        "  - violations:\n"
+        "    - pattern: rm -rf / · severity: error · message: Never delete the root\n"
+        "    - pattern: git push --force · severity: warn · message: Force pushes" in text
+    )
+    assert "    - id: stay-put · title: Stay in the worktree\n      - body:\n" in text
+    assert "['" not in text and "{'" not in text
+
+
+def test_markdown_at_full_keeps_long_text_and_multiline_text() -> None:
+    text = _markdown("full")
+    assert "Because isolation matters. " * 12 in text.replace("\n", " ").replace("  ", " ")
+    assert "…" not in text
+    assert "Write only inside the run worktree." in text and "Never outside it." in text
+
+
+def test_markdown_at_summary_renders_only_the_declared_summary_fields() -> None:
+    text = _markdown("summary")
+    assert "  - checks:\n    - Runs inside its worktree" in text
+    assert "    - pattern: rm -rf / · severity: error" in text
+    assert "rationale" not in text and "stay-put" not in text and "Short note" not in text
+
+
+def test_markdown_at_refs_renders_no_fields() -> None:
+    text = _markdown("refs")
+    assert "Hygiene" in text and "checks" not in text and "Runs inside" not in text
+
+
+@pytest.mark.parametrize("detail", ["refs", "summary", "full"])
+@pytest.mark.parametrize("budget", [1, 40, 120, 300, 32000])
+def test_fields_in_markdown_stay_within_the_budget_json_measures(detail: str, budget: int) -> None:
+    svc = service()
+
+    def answer(fmt: str) -> dict[str, Any]:
+        request = ContextRequest(paths=(CHECKLIST,), detail=detail, budget=budget, format=fmt)
+        return svc.query(METHOD, request)
+
+    as_json, as_markdown = answer("json"), answer("markdown")
+    assert _names(as_json) == _names(as_markdown)
+    assert as_json["used"] == as_markdown["used"] <= budget
+    text = svc.markdown_for_result(METHOD, as_markdown)
+    for item in as_json["items"]:
+        assert ("Runs inside its worktree" in text) == ("checks" in item.get("fields", {}))

katalyst_plugin_context-0.2.1a5/tests/test_shared_names.py

@@ -0,0 +1,57 @@
+"""An edge to a name two kinds share is placed by the kind the listing names (#308)."""
+
+from __future__ import annotations
+
+from katalyst_engine.core.identity import Identity
+from katalyst_engine.model.node import Node
+from katalyst_plugin_context.adapters.runtime_graph import graph_from
+from katalyst_plugin_context.domain.graph import OUT, Graph
+
+
+def _node(kind: str, name: str) -> tuple[str, Node]:
+    return "local", Node(identity=Identity(kind=kind, name=name), spec={})
+
+
+def _edges(graph: Graph) -> set[tuple[str, str, str]]:
+    return {
+        (n.rel, key, n.other)
+        for key in graph.nodes
+        for n in graph.neighbours(key)
+        if n.direction == OUT
+    }
+
+
+DOCUMENTS = [_node("tool", "just"), _node("runner", "just"), _node("job", "build")]
+
+
+def test_an_edge_to_a_shared_name_lands_on_the_kind_it_names() -> None:
+    graph = graph_from(
+        DOCUMENTS,
+        [("local", "build", "USES_TOOL", "just#tool"), ("local", "build", "USES", "just#runner")],
+    )
+
+    assert _edges(graph) == {
+        ("USES_TOOL", "local:build", "local:just#tool"),
+        ("USES", "local:build", "local:just#runner"),
+    }
+    assert graph.dropped == 0
+
+
+def test_an_edge_from_a_shared_name_lands_on_the_kind_it_names() -> None:
+    graph = graph_from(DOCUMENTS, [("local", "just#runner", "RUNS", "build")])
+
+    assert _edges(graph) == {("RUNS", "local:just#runner", "local:build")}
+
+
+def test_an_edge_to_a_shared_name_nothing_places_is_counted_as_dropped() -> None:
+    graph = graph_from(DOCUMENTS, [("local", "build", "USES", "just")])
+
+    assert _edges(graph) == set()
+    assert graph.dropped == 1
+
+
+def test_an_edge_to_a_kind_that_is_not_at_the_name_is_counted_as_dropped() -> None:
+    graph = graph_from(DOCUMENTS, [("local", "build", "USES", "just#job")])
+
+    assert _edges(graph) == set()
+    assert graph.dropped == 1