katalyst-plugin-context 0.1.1a1__py3-none-any.whl

katalyst_plugin_context/domain/policy.py

@@ -0,0 +1,345 @@
+"""Context policy: layered controls that can only narrow what an agent is given.
+
+Layers fold in order: built-in → wing → kind → node (``spec.extensions.context``) →
+profile (the plugin's config, then the active profile's section and its matching rules).
+Each control narrows in its own way:
+
+=================  ===========================================================
+``paths.allow``    the steps visible are those every layer's allow list matches
+``paths.deny``     a step any layer denies is hidden
+``max_depth``      the smallest declared
+``detail``         the levels every layer allows (``refs`` is always allowed)
+``budget.max``     the smallest declared
+``inheritance``    off once any layer turns it off
+``always_include`` the first declaring layer sets it; later layers intersect
+=================  ===========================================================
+
+A layer that tries to widen is not an error. Its declaration has no effect, and the
+effective policy records a note saying which layer limited it. Defaults (``depth``,
+``detail``, ``budget``, ``inherit``) are not limits: a later layer's default replaces an
+earlier one, and the result is clamped into the policy.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any, cast
+
+from katalyst_plugin_context.domain.paths import Step, parse_step
+
+__all__ = [
+    "BUILTIN",
+    "DETAIL_LEVELS",
+    "Layer",
+    "Policy",
+    "fold",
+]
+
+REFS, SUMMARY, FULL = "refs", "summary", "full"
+DETAIL_LEVELS: tuple[str, ...] = (REFS, SUMMARY, FULL)
+
+BUILTIN = "builtin"
+_BUILTIN_MAX_DEPTH = 4
+_BUILTIN_BUDGET_MAX = 32000
+_BUILTIN_DEPTH = 1
+_BUILTIN_BUDGET = 4000
+
+
+@dataclass(frozen=True, slots=True)
+class Layer:
+    """One source of policy: its label (``kind:<kind>``) and what it declares."""
+
+    label: str
+    policy: Mapping[str, Any] = field(default_factory=lambda: dict[str, Any]())
+    defaults: Mapping[str, Any] = field(default_factory=lambda: dict[str, Any]())
+
+
+@dataclass
+class Policy:
+    """The effective policy for one node, and how it came about."""
+
+    allow: list[tuple[str, tuple[Step, ...]]] = field(
+        default_factory=lambda: list[tuple[str, tuple[Step, ...]]]()
+    )
+    deny: list[tuple[str, Step]] = field(default_factory=lambda: list[tuple[str, Step]]())
+    max_depth: int = _BUILTIN_MAX_DEPTH
+    max_depth_by: str = BUILTIN
+    detail: tuple[str, ...] = DETAIL_LEVELS
+    detail_by: dict[str, str] = field(default_factory=lambda: dict[str, str]())
+    budget_max: int = _BUILTIN_BUDGET_MAX
+    budget_by: str = BUILTIN
+    inheritance: bool = True
+    inheritance_by: str = BUILTIN
+    always: tuple[str, ...] | None = None
+    always_by: str = ""
+    default_depth: int = _BUILTIN_DEPTH
+    default_detail: str | None = None
+    default_budget: int = _BUILTIN_BUDGET
+    default_inherit: bool = True
+    layers: list[str] = field(default_factory=lambda: [BUILTIN])
+    notes: list[dict[str, Any]] = field(default_factory=lambda: list[dict[str, Any]]())
+
+    # ── visibility ──────────────────────────────────────────────────────
+
+    def hidden_by(self, rel: str, direction: str, kind: str) -> str | None:
+        """The layer that hides traversing *rel* *direction* to a *kind*, or ``None``."""
+        for label, patterns in self.allow:
+            if not any(p.matches(rel, direction, kind) for p in patterns):
+                return label
+        for label, pattern in self.deny:
+            if pattern.matches(rel, direction, kind):
+                return label
+        return None
+
+    def visible(self, rel: str, direction: str, kind: str) -> bool:
+        return self.hidden_by(rel, direction, kind) is None
+
+    def step_hidden_by(self, step: Step) -> str | None:
+        """The layer that hides every traversal *step* could make, or ``None``.
+
+        A step is hidden when an allow list has nothing overlapping it, or a deny pattern
+        covers it entirely (same or wider relationship, direction and kinds).
+        """
+        for label, patterns in self.allow:
+            if not any(p.overlaps(step) for p in patterns):
+                return label
+        for label, pattern in self.deny:
+            if _covers(pattern, step):
+                return label
+        return None
+
+    # ── clamping a request ──────────────────────────────────────────────
+
+    def clamp_depth(self, requested: int | None) -> tuple[int, dict[str, Any] | None]:
+        wanted = self.default_depth if requested is None else requested
+        if wanted > self.max_depth:
+            return self.max_depth, _clamp("depth", wanted, self.max_depth, self.max_depth_by)
+        return max(wanted, 0), None
+
+    def clamp_detail(
+        self, requested: str | None, fallback: str
+    ) -> tuple[str, dict[str, Any] | None]:
+        wanted = requested or self.default_detail or fallback
+        if wanted in self.detail:
+            return wanted, None
+        allowed = [
+            level for level in DETAIL_LEVELS[: DETAIL_LEVELS.index(wanted)] if level in self.detail
+        ]
+        effective = allowed[-1] if allowed else REFS
+        return effective, _clamp("detail", wanted, effective, self.detail_by.get(wanted, BUILTIN))
+
+    def clamp_budget(self, requested: int | None) -> tuple[int, dict[str, Any] | None]:
+        wanted = min(self.default_budget, self.budget_max) if requested is None else requested
+        if wanted > self.budget_max:
+            return self.budget_max, _clamp("budget", wanted, self.budget_max, self.budget_by)
+        return max(wanted, 1), None
+
+    def clamp_inherit(self, requested: bool | None) -> tuple[bool, dict[str, Any] | None]:
+        wanted = self.default_inherit if requested is None else requested
+        if wanted and not self.inheritance:
+            return False, _clamp("inherit", True, False, self.inheritance_by)
+        return wanted, None
+
+    def describe(self) -> dict[str, Any]:
+        """The effective policy, as a payload."""
+        return {
+            "layers": list(self.layers),
+            "paths": {
+                "allow": [
+                    {"source": label, "patterns": [p.text for p in patterns]}
+                    for label, patterns in self.allow
+                ],
+                "deny": [{"source": label, "pattern": p.text} for label, p in self.deny],
+            },
+            "maxDepth": self.max_depth,
+            "detail": list(self.detail),
+            "budget": {
+                "default": min(self.default_budget, self.budget_max),
+                "max": self.budget_max,
+            },
+            "inheritance": self.inheritance,
+            "alwaysInclude": list(self.always or ()),
+            "notes": list(self.notes),
+        }
+
+
+def _clamp(control: str, requested: object, effective: object, by: str) -> dict[str, Any]:
+    return {"control": control, "requested": requested, "effective": effective, "limitedBy": by}
+
+
+def _covers(wide: Step, narrow: Step) -> bool:
+    return (
+        wide.rel in ("*", narrow.rel)
+        and (wide.direction is None or wide.direction == narrow.direction)
+        and (not wide.kinds or (bool(narrow.kinds) and narrow.kinds <= wide.kinds))
+    )
+
+
+def _note(
+    layer: str, control: str, declared: object, effective: object, by: str, text: str
+) -> dict[str, Any]:
+    return {
+        "source": layer,
+        "control": control,
+        "declared": declared,
+        "effective": effective,
+        "limitedBy": by,
+        "text": text,
+    }
+
+
+def _strings(value: object) -> list[str]:
+    return [str(v) for v in cast("list[object]", value)] if isinstance(value, list) else []
+
+
+def fold(layers: Sequence[Layer], *, views: Sequence[str] = ()) -> Policy:
+    """The effective policy *layers* give, in order, after the built-in one.
+
+    *views* are the names of the views the node's kind declares, the only names
+    ``always_include`` may hold.
+    """
+    policy = Policy()
+    declared_views = set(views)
+    for layer in layers:
+        declares = bool(layer.policy) or bool(layer.defaults)
+        if declares:
+            policy.layers.append(layer.label)
+        _fold_paths(policy, layer)
+        _fold_limits(policy, layer, declared_views)
+        _fold_defaults(policy, layer)
+    return policy
+
+
+def _fold_paths(policy: Policy, layer: Layer) -> None:
+    paths = cast("Mapping[str, Any]", layer.policy.get("paths") or {})
+    if "allow" in paths:
+        patterns = tuple(parse_step(text) for text in _strings(paths["allow"]))
+        for pattern in patterns:
+            for label, earlier in policy.allow:
+                if not any(p.overlaps(pattern) for p in earlier):
+                    policy.notes.append(
+                        _note(
+                            layer.label,
+                            "paths.allow",
+                            pattern.text,
+                            None,
+                            label,
+                            f"{layer.label} allows {pattern.text}; {label} does not, so it stays hidden",
+                        )
+                    )
+                    break
+        policy.allow.append((layer.label, patterns))
+    for text in _strings(paths.get("deny")):
+        policy.deny.append((layer.label, parse_step(text)))
+
+
+def _fold_limits(policy: Policy, layer: Layer, declared_views: set[str]) -> None:
+    declared = layer.policy
+    if "max_depth" in declared:
+        depth = int(declared["max_depth"])
+        if depth < policy.max_depth:
+            policy.max_depth, policy.max_depth_by = depth, layer.label
+        elif depth > policy.max_depth:
+            policy.notes.append(
+                _note(
+                    layer.label,
+                    "max_depth",
+                    depth,
+                    policy.max_depth,
+                    policy.max_depth_by,
+                    f"{layer.label} asks max_depth {depth}; {policy.max_depth_by} caps it at {policy.max_depth}",
+                )
+            )
+    if "detail" in declared:
+        levels = set(_strings(declared["detail"])) | {REFS}
+        for level in levels - set(policy.detail):
+            policy.notes.append(
+                _note(
+                    layer.label,
+                    "detail",
+                    level,
+                    None,
+                    policy.detail_by.get(level, BUILTIN),
+                    f"{layer.label} allows detail {level!r}; "
+                    f"{policy.detail_by.get(level, BUILTIN)} does not",
+                )
+            )
+        for level in set(policy.detail) - levels:
+            policy.detail_by[level] = layer.label
+        policy.detail = tuple(
+            level for level in DETAIL_LEVELS if level in policy.detail and level in levels
+        )
+    budget = cast("Mapping[str, Any]", declared.get("budget") or {})
+    if "max" in budget:
+        cap = int(budget["max"])
+        if cap < policy.budget_max:
+            policy.budget_max, policy.budget_by = cap, layer.label
+        elif cap > policy.budget_max:
+            policy.notes.append(
+                _note(
+                    layer.label,
+                    "budget.max",
+                    cap,
+                    policy.budget_max,
+                    policy.budget_by,
+                    f"{layer.label} asks budget max {cap}; {policy.budget_by} caps it at {policy.budget_max}",
+                )
+            )
+    if "inheritance" in declared:
+        if not declared["inheritance"]:
+            if policy.inheritance:
+                policy.inheritance, policy.inheritance_by = False, layer.label
+        elif not policy.inheritance:
+            policy.notes.append(
+                _note(
+                    layer.label,
+                    "inheritance",
+                    True,
+                    False,
+                    policy.inheritance_by,
+                    f"{layer.label} turns inheritance on; {policy.inheritance_by} turned it off",
+                )
+            )
+    if "always_include" in declared:
+        names = _strings(declared["always_include"])
+        for name in names:
+            if name not in declared_views:
+                policy.notes.append(
+                    _note(
+                        layer.label,
+                        "always_include",
+                        name,
+                        None,
+                        layer.label,
+                        f"{layer.label} always includes {name!r}, which is not a declared view",
+                    )
+                )
+            elif policy.always is not None and name not in policy.always:
+                policy.notes.append(
+                    _note(
+                        layer.label,
+                        "always_include",
+                        name,
+                        None,
+                        policy.always_by,
+                        f"view {name!r} is not always included by {policy.always_by}",
+                    )
+                )
+        kept = tuple(n for n in names if n in declared_views)
+        policy.always = (
+            kept if policy.always is None else tuple(n for n in policy.always if n in kept)
+        )
+        policy.always_by = layer.label
+
+
+def _fold_defaults(policy: Policy, layer: Layer) -> None:
+    defaults = layer.defaults
+    if "depth" in defaults:
+        policy.default_depth = int(defaults["depth"])
+    if "detail" in defaults:
+        policy.default_detail = str(defaults["detail"])
+    if "budget" in defaults:
+        policy.default_budget = int(defaults["budget"])
+    if "inherit" in defaults:
+        policy.default_inherit = bool(defaults["inherit"])

katalyst_plugin_context/domain/settings.py

@@ -0,0 +1,92 @@
+"""What a wing or kind declares in its ``context`` settings section: views and item hints.
+
+The section's shape is the plugin's ``settings_schema``
+(:data:`katalyst_plugin_context.schema.SETTINGS_SCHEMA`). Views declared by a wing apply to
+every member kind, and a kind's view of the same name replaces the wing's. Item hints
+(``title_field``, ``summary_fields``, ``priority``) are taken key by key, the kind's over
+the wing's.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, cast
+
+from katalyst_plugin_context.domain.paths import Step, parse_path, path_text
+
+__all__ = ["ItemHints", "View", "item_hints", "views_from"]
+
+
+@dataclass(frozen=True, slots=True)
+class View:
+    """A named set of paths a wing or kind declares."""
+
+    name: str
+    title: str
+    description: str
+    paths: tuple[tuple[Step, ...], ...]
+    inherit: bool = True
+    detail: str = "summary"
+    priority: int = 0
+    blocking_first: bool = False
+    declared_by: str = ""
+
+    @property
+    def path_texts(self) -> list[str]:
+        return [path_text(p) for p in self.paths]
+
+
+@dataclass(frozen=True, slots=True)
+class ItemHints:
+    """How a kind is shown when it is a result item."""
+
+    title_field: str | None = None
+    summary_fields: tuple[str, ...] | None = None
+    priority: int = 0
+
+
+def _section(settings: Mapping[str, Any] | None) -> Mapping[str, Any]:
+    return settings or {}
+
+
+def views_from(
+    wing: Mapping[str, Any] | None,
+    kind: Mapping[str, Any] | None,
+    *,
+    wing_label: str,
+    kind_label: str,
+) -> dict[str, View]:
+    """The views a kind has: its wing's, then its own (replacing same-named ones)."""
+    views: dict[str, View] = {}
+    for label, settings in ((wing_label, _section(wing)), (kind_label, _section(kind))):
+        declared = cast("Mapping[str, Mapping[str, Any]]", settings.get("views") or {})
+        for name, view in declared.items():
+            views[name] = View(
+                name=name,
+                title=str(view.get("title") or name),
+                description=str(view.get("description") or ""),
+                paths=tuple(
+                    parse_path(str(p)) for p in cast("list[object]", view.get("paths") or [])
+                ),
+                inherit=bool(view.get("inherit", True)),
+                detail=str(view.get("detail") or "summary"),
+                priority=int(view.get("priority") or 0),
+                blocking_first=view.get("order") == "blocking-first",
+                declared_by=label,
+            )
+    return views
+
+
+def item_hints(wing: Mapping[str, Any] | None, kind: Mapping[str, Any] | None) -> ItemHints:
+    """A kind's item hints: each key from the kind, else from its wing."""
+    merged = {**_section(wing), **_section(kind)}
+    summary = merged.get("summary_fields")
+    title = merged.get("title_field")
+    return ItemHints(
+        title_field=str(title) if title else None,
+        summary_fields=tuple(str(f) for f in cast("list[object]", summary))
+        if isinstance(summary, list)
+        else None,
+        priority=int(merged.get("priority") or 0),
+    )

katalyst_plugin_context/lint.py

@@ -0,0 +1,149 @@
+"""``context-policy``: context settings that are well-formed but don't do what they say.
+
+The plugin's schemas (checked by ``kata tax lint``'s plugin-settings pass) catch a malformed
+section. This rule catches what a schema can't:
+
+- error: an ``always_include`` naming a view the kind doesn't declare;
+- error: a view path naming a relationship type no registered kind carries;
+- warning: a layer that tries to widen what an earlier layer allows (wing → kind → node),
+  which has no effect. The message names the layer that limits it.
+
+Definitions are checked once per repository the rule runs for; nodes only in the
+repository being checked.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, cast
+
+from katalyst_engine.schema.registry import SchemaRegistry
+from katalyst_taxonomy.plugins.extensions import LintFinding, LintSubject
+
+from katalyst_plugin_context.domain.paths import PathSyntaxError
+from katalyst_plugin_context.domain.policy import Layer, fold
+from katalyst_plugin_context.domain.settings import views_from
+from katalyst_plugin_context.service import NAMESPACE, RegistrySchema
+
+__all__ = ["ContextPolicyRule"]
+
+
+class ContextPolicyRule:
+    """Reports context settings that have no effect, or name what doesn't exist."""
+
+    name = "context-policy"
+
+    def __init__(self, registry: SchemaRegistry | None = None) -> None:
+        self._registry = registry
+
+    def _registry_or_default(self) -> SchemaRegistry | None:
+        if self._registry is not None:
+            return self._registry
+        from katalyst_taxonomy.engine.bridge import default_registry_or_none
+
+        return default_registry_or_none()
+
+    def check(self, subject: LintSubject) -> list[LintFinding]:
+        from katalyst_taxonomy.engine.accessors import get_extensions_map, get_source_path
+        from katalyst_taxonomy.engine.relationships import relationship_types_of
+
+        registry = self._registry_or_default()
+        if registry is None:
+            return []
+        schema = RegistrySchema(registry)
+        carried = {
+            rel for kind in registry.all_kinds() for rel in relationship_types_of(registry, kind)
+        }
+        findings: list[LintFinding] = []
+
+        def finding(message: str, severity: str, **detail: str) -> None:
+            findings.append(
+                LintFinding(rule=self.name, message=message, severity=severity, detail=detail)  # pyright: ignore[reportArgumentType]
+            )
+
+        for kind in registry.all_kinds():
+            wing_section, kind_section, wing = schema.sections(kind)
+            if wing_section is None and kind_section is None:
+                continue
+            try:
+                views = views_from(
+                    wing_section, kind_section, wing_label=f"wing:{wing}", kind_label=f"kind:{kind}"
+                )
+                layers = [
+                    _layer(label, section)
+                    for label, section in (
+                        (f"wing:{wing}", wing_section),
+                        (f"kind:{kind}", kind_section),
+                    )
+                    if section is not None
+                ]
+                policy = fold(layers, views=sorted(views))
+            except (PathSyntaxError, ValueError, TypeError) as exc:
+                finding(f"kind {kind!r}: context settings: {exc}", "error", kind=kind)
+                continue
+            for view in views.values():
+                for steps in view.paths:
+                    for step in steps:
+                        if step.rel != "*" and step.rel not in carried:
+                            finding(
+                                f"kind {kind!r}: view {view.name!r} ({view.declared_by}) follows "
+                                f"{step.rel}, which no registered kind carries",
+                                "error",
+                                kind=kind,
+                                view=view.name,
+                            )
+            for note in policy.notes:
+                severity = (
+                    "error"
+                    if note.get("control") == "always_include"
+                    and note.get("limitedBy") == note.get("source")
+                    else "warning"
+                )
+                finding(f"kind {kind!r}: {note['text']}", severity, kind=kind)
+
+        root = subject.root.resolve()
+        for document in subject.taxonomy.documents:
+            own = get_extensions_map(document).get(NAMESPACE)
+            if not isinstance(own, Mapping):
+                continue
+            source = get_source_path(document)
+            if source is None or not source.resolve().is_relative_to(root):
+                continue
+            wing_section, kind_section, wing = schema.sections(document.kind)
+            try:
+                views = views_from(
+                    wing_section,
+                    kind_section,
+                    wing_label=f"wing:{wing}",
+                    kind_label=f"kind:{document.kind}",
+                )
+                layers = [
+                    _layer(label, section)
+                    for label, section in (
+                        (f"wing:{wing}", wing_section),
+                        (f"kind:{document.kind}", kind_section),
+                    )
+                    if section is not None
+                ]
+                label = f"node:{document.fqn}"
+                layers.append(_layer(label, cast("Mapping[str, Any]", own)))
+                policy = fold(layers, views=sorted(views))
+            except (PathSyntaxError, ValueError, TypeError) as exc:
+                finding(
+                    f"{document.fqn}: spec.extensions.{NAMESPACE}: {exc}",
+                    "error",
+                    node=document.fqn,
+                )
+                continue
+            for note in policy.notes:
+                if note.get("source") == label:
+                    finding(f"{document.fqn}: {note['text']}", "warning", node=document.fqn)
+        return findings
+
+
+def _layer(label: str, section: Mapping[str, Any]) -> Layer:
+    return Layer(
+        label=label,
+        policy=cast("Mapping[str, Any]", section.get("policy") or {}),
+        defaults=cast("Mapping[str, Any]", section.get("defaults") or {}),
+    )