spring-runtime-mcp 0.2.0__py3-none-any.whl

spring_runtime_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Bounded, read-only Spring Boot diagnostic analysis."""
+
+__version__ = "0.2.0"

spring_runtime_mcp/adapters/__init__.py

@@ -0,0 +1 @@
+"""Convert bounded Actuator observations into diagnostic facts."""

spring_runtime_mcp/adapters/beans.py

@@ -0,0 +1,159 @@
+"""Normalize Actuator beans without inventing absent container facts."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, TypeGuard
+
+from ..models.bean_graph import Bean, BeanGraph, BeanKey, Context, ContextKey
+from ..models.common import (
+    AnalysisBudget,
+    AnalysisLimit,
+    Fact,
+    NormalizationError,
+    ParsedObservation,
+)
+
+
+def _text(value: Any) -> TypeGuard[str]:
+    return isinstance(value, str) and 0 < len(value) <= 4096
+
+
+def _fact(record: Mapping[str, Any], name: str) -> Fact[str]:
+    value = record.get(name)
+    if _text(value):
+        return Fact("known", value, None)
+    return Fact("notReported", None, "FIELD_NOT_REPORTED")
+
+
+def normalize_beans(
+    observation: ParsedObservation, *, budget: AnalysisBudget
+) -> BeanGraph:
+    """Build all local name indices before resolving any dependency edges."""
+    body = observation.body
+    if not isinstance(body, Mapping) or not isinstance(body.get("contexts"), Mapping):
+        raise NormalizationError("INVALID_BEANS_STRUCTURE")
+    contexts: dict[ContextKey, Context] = {}
+    beans: dict[BeanKey, Bean] = {}
+    names: dict[ContextKey, dict[str, tuple[BeanKey, ...]]] = {}
+    canonical: dict[BeanKey, tuple[str, ...]] = {}
+    gaps: set[str] = set()
+    try:
+        for context_id, raw_context in sorted(
+            body["contexts"].items(), key=lambda item: str(item[0])
+        ):
+            budget.consume()
+            if not _text(context_id):
+                gaps.add("INVALID_CONTEXT_NAME")
+                continue
+            key = ContextKey(observation.target_id, observation.snapshot_id, context_id)
+            names[key] = {}
+            if not isinstance(raw_context, Mapping):
+                contexts[key] = Context(
+                    key, Fact("unknown", None, "INVALID_CONTEXT"), False
+                )
+                gaps.add("INVALID_CONTEXT")
+                continue
+            parent_id = raw_context.get("parentId")
+            if "parentId" not in raw_context:
+                # Boot reports parentId only for child contexts; omitting it
+                # means this is a root context, not unobserved hierarchy.
+                parent: Fact[ContextKey | None] = Fact("known", None, None)
+            elif parent_id is None:
+                parent = Fact("known", None, None)
+            elif _text(parent_id):
+                parent = Fact(
+                    "known", ContextKey(key.target_id, key.snapshot_id, parent_id), None
+                )
+            else:
+                parent = Fact("unknown", None, "INVALID_PARENT_CONTEXT")
+                gaps.add("INVALID_PARENT_CONTEXT")
+            raw_beans = raw_context.get("beans")
+            contexts[key] = Context(key, parent, isinstance(raw_beans, Mapping))
+            if not isinstance(raw_beans, Mapping):
+                gaps.add("BEAN_INDEX_INCOMPLETE")
+                continue
+            for name, raw in sorted(raw_beans.items(), key=lambda item: str(item[0])):
+                budget.consume()
+                if not _text(name) or not isinstance(raw, Mapping):
+                    contexts[key] = Context(key, parent, False)
+                    gaps.add("BEAN_INDEX_INCOMPLETE")
+                    continue
+                bean_key = BeanKey(key, name)
+                aliases_raw = raw.get("aliases")
+                if not isinstance(aliases_raw, list) or not all(
+                    _text(alias) for alias in aliases_raw
+                ):
+                    aliases = ()
+                    contexts[key] = Context(key, parent, False)
+                    gaps.add("ALIASES_NOT_REPORTED")
+                else:
+                    aliases = tuple(sorted(set(aliases_raw)))
+                dependencies_raw = raw.get("dependencies")
+                if not isinstance(dependencies_raw, list) or not all(
+                    _text(dep) for dep in dependencies_raw
+                ):
+                    dependencies = ()
+                    gaps.add("DEPENDENCIES_NOT_REPORTED")
+                else:
+                    dependencies = tuple(sorted(set(dependencies_raw)))
+                # Opaque ordinals never encode or hash untrusted labels.
+                identifier = f"bean_{len(beans) + 1:06d}"
+                beans[bean_key] = Bean(
+                    bean_key,
+                    identifier,
+                    aliases,
+                    _fact(raw, "type"),
+                    _fact(raw, "scope"),
+                    _fact(raw, "resource"),
+                    dependencies,
+                    (observation.observation_id,),
+                )
+                all_names = tuple(sorted({name, *aliases}))
+                canonical[bean_key] = all_names
+                for local_name in all_names:
+                    budget.consume()
+                    names[key][local_name] = tuple(
+                        sorted((*names[key].get(local_name, ()), bean_key))
+                    )
+    except AnalysisLimit:
+        gaps.add("GRAPH_LIMIT_REACHED")
+        # Any interrupted index may have omitted names; no ancestor fallback is safe.
+        contexts = {
+            key: Context(key, ctx.parent, False) for key, ctx in contexts.items()
+        }
+    for context in contexts.values():
+        if (
+            context.parent.state == "known"
+            and context.parent.value is not None
+            and context.parent.value not in contexts
+        ):
+            gaps.add("PARENT_CONTEXT_UNOBSERVED")
+    checked: set[ContextKey] = set()
+    try:
+        for start in contexts:
+            current: ContextKey | None = start
+            path: set[ContextKey] = set()
+            while current is not None and current not in checked:
+                budget.consume()
+                if current in path:
+                    gaps.add("CONTEXT_CYCLE")
+                    break
+                path.add(current)
+                ancestor = contexts.get(current)
+                if ancestor is None or ancestor.parent.state != "known":
+                    break
+                current = ancestor.parent.value
+            checked.update(path)
+    except AnalysisLimit:
+        gaps.add("GRAPH_LIMIT_REACHED")
+    return BeanGraph(
+        contexts,
+        beans,
+        names,
+        canonical,
+        {},
+        {},
+        "partial" if gaps else "complete",
+        tuple(sorted(gaps)),
+    )

spring_runtime_mcp/adapters/conditions.py

@@ -0,0 +1,333 @@
+"""Bounded, conservative adapters for known Actuator condition grammars."""
+
+import re
+from dataclasses import replace
+from types import MappingProxyType
+from typing import Any, Literal, cast
+
+from ..models.bean_graph import ContextKey
+from ..models.common import AnalysisBudget, Fact, NormalizationError, ParsedObservation
+from ..models.conditions import Condition, ConditionReport, Outcome, Search
+
+_IDENT = r"[A-Za-z_$][A-Za-z0-9_.$]*"
+_SOURCE = re.compile(_IDENT + r"(?:#[A-Za-z_$][A-Za-z0-9_$]*)?\Z")
+_NESTED = re.compile(
+    r"(AnyNestedCondition|AllNestedConditions|NoneNestedConditions) (\d{1,4}) matched (\d{1,4}) did not\Z"
+)
+_BEAN = re.compile(
+    r"@ConditionalOn(OnMissingBean|Bean)"
+)  # dispatch uses explicit spelling below
+
+
+def combine(operator: str, values: tuple[Outcome, ...], complete: bool) -> Outcome:
+    if operator == "any" and "matched" in values:
+        return "matched"
+    if (
+        operator in ("all", "none")
+        and ("notMatched" if operator == "all" else "matched") in values
+    ):
+        return "notMatched"
+    if not complete:
+        return "unknown"
+    if operator == "any":
+        return "notMatched" if all(v == "notMatched" for v in values) else "unknown"
+    if operator == "all":
+        return "matched" if all(v == "matched" for v in values) else "unknown"
+    if operator == "none":
+        return "matched" if all(v == "notMatched" for v in values) else "unknown"
+    return "unknown"
+
+
+def _leaf(
+    message: str,
+) -> tuple[Search, tuple[str, ...], tuple[str, ...], Fact[str], str, bool, Outcome]:
+    unknown: Fact[str] = Fact("notReported", None, "NOT_REPORTED")
+    bean = re.fullmatch(
+        r"@ConditionalOn(Bean|MissingBean) \((types|names): ([A-Za-z0-9_.$, ]+); SearchStrategy: (all|current|parents)\) (.+)",
+        message,
+    )
+    if bean:
+        kind, selector, entries, strategy, suffix = bean.groups()
+        required = tuple(s.strip() for s in entries.split(","))
+        if not required or any(not _SOURCE.fullmatch(s) for s in required):
+            return (
+                "unknown",
+                (),
+                (),
+                unknown,
+                "UNKNOWN_CONDITION_GRAMMAR",
+                False,
+                "unknown",
+            )
+        missing = re.fullmatch(
+            r"did not find any beans(?: of type " + _IDENT + ")?", suffix
+        )
+        found = re.fullmatch(r"found bean '[A-Za-z0-9_.$]+'", suffix)
+        if missing or found:
+            outcome: Outcome = (
+                "matched"
+                if (bool(missing) == (kind == "MissingBean"))
+                else "notMatched"
+            )
+            return (
+                cast(Search, strategy.upper()),
+                required if selector == "types" else (),
+                required if selector == "names" else (),
+                unknown,
+                "REQUIRED_BEAN_MISSING"
+                if missing and kind == "Bean"
+                else "CONDITION_MATCH"
+                if outcome == "matched"
+                else "BEAN_PRESENT",
+                True,
+                outcome,
+            )
+    prop = re.fullmatch(
+        r"@ConditionalOnProperty \(([A-Za-z0-9_.-]+)=([A-Za-z0-9_.-]+)\) did not find property '([A-Za-z0-9_.-]+)'",
+        message,
+    )
+    if prop and (prop[1] == prop[3] or prop[1].endswith("." + prop[3])):
+        return (
+            "unknown",
+            (),
+            (),
+            Fact("known", prop[1], None),
+            "PROPERTY_NOT_FOUND",
+            True,
+            "notMatched",
+        )
+    mismatch = re.fullmatch(
+        r'@ConditionalOnProperty \(([A-Za-z0-9_.-]+)=([A-Za-z0-9_.-]+)\) found different value in property [\'"]([A-Za-z0-9_.-]+)[\'"]',
+        message,
+    )
+    if mismatch and (
+        mismatch[1] == mismatch[3] or mismatch[1].endswith("." + mismatch[3])
+    ):
+        return (
+            "unknown",
+            (),
+            (),
+            Fact("known", mismatch[1], None),
+            "PROPERTY_VALUE_MISMATCH",
+            True,
+            "notMatched",
+        )
+    return "unknown", (), (), unknown, "UNKNOWN_CONDITION_GRAMMAR", False, "unknown"
+
+
+def normalize_conditions(
+    observation: ParsedObservation, *, budget: AnalysisBudget
+) -> ConditionReport:
+    body = observation.body
+    if not isinstance(body, dict) or not isinstance(body.get("contexts"), dict):
+        raise NormalizationError("INVALID_CONDITIONS_SHAPE")
+    nodes: dict[str, Condition] = {}
+    roots: dict[tuple[ContextKey, str], tuple[str, ...]] = {}
+    gaps: set[str] = set()
+
+    def parse(
+        context: ContextKey,
+        source: str,
+        condition_type: Any,
+        message: Any,
+        reported: Outcome,
+        depth: int = 0,
+    ) -> str:
+        budget.consume()
+        node_id = f"condition_{len(nodes)}"
+        base = Condition(
+            node_id,
+            context,
+            source,
+            condition_type
+            if isinstance(condition_type, str)
+            and len(condition_type) <= 256
+            and _SOURCE.fullmatch(condition_type)
+            else None,
+            "leaf",
+            reported,
+            "unknown",
+            "unknown",
+            (),
+            (),
+            Fact("notReported", None, "NOT_REPORTED"),
+            (),
+            False,
+            "UNKNOWN_CONDITION_GRAMMAR",
+            (observation.observation_id,),
+        )
+        nodes[node_id] = base
+        if not isinstance(message, str) or len(message.encode()) > 8192 or depth >= 16:
+            gaps.add("UNKNOWN_CONDITION_GRAMMAR")
+            return node_id
+        segments = re.split(r"; NestedCondition on ", message)
+        nested = _NESTED.fullmatch(segments[0])
+        if nested:
+            operator = {
+                "AnyNestedCondition": "any",
+                "AllNestedConditions": "all",
+                "NoneNestedConditions": "none",
+            }[nested[1]]
+            entries: list[tuple[str, str]] = []
+            valid = True
+            for segment in segments[1:]:
+                name, sep, text = segment.partition(" ")
+                if not sep or not _SOURCE.fullmatch(name):
+                    valid = False
+                    continue
+                entries.append((name, text))
+            # A qualified nested class is a parent only if explicitly present.
+            if len({name for name, _ in entries}) != len(entries):
+                valid = False
+            direct = [
+                (n, t)
+                for n, t in entries
+                if not any(n.startswith(p + ".") for p, _ in entries if p != n)
+            ]
+            children = []
+            for name, text in direct:
+                descendants = [(n, t) for n, t in entries if n.startswith(name + ".")]
+                child_message = text + "".join(
+                    "; NestedCondition on " + n + " " + t for n, t in descendants
+                )
+                child_id = parse(
+                    context, source, name, child_message, "unknown", depth + 1
+                )
+                child = nodes[child_id]
+                nodes[child_id] = replace(child, reported_outcome=child.derived_outcome)
+                children.append(child_id)
+            complete = (
+                valid
+                and len(children) == int(nested[2]) + int(nested[3])
+                and all(nodes[c].children_complete for c in children)
+            )
+            values = tuple(nodes[c].derived_outcome for c in children)
+            counts_match = values.count("matched") == int(nested[2]) and values.count(
+                "notMatched"
+            ) == int(nested[3])
+            complete = complete and counts_match
+            derived = combine(operator, values, complete)
+            reason = "NESTED_CONDITION" if complete else "UNKNOWN_CONDITION_GRAMMAR"
+            nodes[node_id] = replace(
+                base,
+                operator=cast(Literal["any", "all", "none"], operator),
+                derived_outcome=derived,
+                child_ids=tuple(children),
+                children_complete=complete,
+                reason_code=reason,
+            )
+        else:
+            search, types, names, prop, reason, complete, derived = _leaf(message)
+            # Annotation text alone cannot establish which Condition implementation ran.
+            expected = (
+                "OnBeanCondition"
+                if types or names
+                else "OnPropertyCondition"
+                if prop.state == "known"
+                else None
+            )
+            if (
+                expected
+                and depth == 0
+                and (
+                    not isinstance(condition_type, str)
+                    or len(condition_type) > 256
+                    or not _SOURCE.fullmatch(condition_type)
+                    or condition_type.rsplit(".", 1)[-1] != expected
+                )
+            ):
+                complete, derived, reason = (
+                    False,
+                    "unknown",
+                    "UNKNOWN_CONDITION_GRAMMAR",
+                )
+            nodes[node_id] = replace(
+                base,
+                derived_outcome=derived,
+                search=search,
+                required_types=types,
+                required_names=names,
+                property_key=prop,
+                reason_code=reason,
+                children_complete=complete,
+            )
+        node = nodes[node_id]
+        if (
+            reported != "unknown"
+            and node.derived_outcome != "unknown"
+            and reported != node.derived_outcome
+        ):
+            nodes[node_id] = replace(
+                node, children_complete=False, reason_code="CONDITION_PARSE_CONFLICT"
+            )
+            gaps.add("CONDITION_PARSE_CONFLICT")
+        elif not node.children_complete:
+            gaps.add("UNKNOWN_CONDITION_GRAMMAR")
+        return node_id
+
+    for context_id, value in sorted(
+        body["contexts"].items(), key=lambda item: str(item[0])
+    ):
+        budget.consume()
+        if (
+            not isinstance(context_id, str)
+            or len(context_id) > 256
+            or not isinstance(value, dict)
+        ):
+            gaps.add("INVALID_CONDITIONS_CONTEXT")
+            continue
+        context = ContextKey(observation.target_id, observation.snapshot_id, context_id)
+        for branch in ("positiveMatches", "negativeMatches"):
+            entries = value.get(branch)
+            if not isinstance(entries, dict):
+                gaps.add("CONDITIONS_BRANCH_UNOBSERVED")
+                continue
+            for source, matches in sorted(
+                entries.items(), key=lambda item: str(item[0])
+            ):
+                if (
+                    not isinstance(source, str)
+                    or len(source) > 256
+                    or not _SOURCE.fullmatch(source)
+                ):
+                    gaps.add("INVALID_CONDITION_SOURCE")
+                    continue
+                groups = (
+                    [("matched", matches)]
+                    if branch == "positiveMatches"
+                    else list(matches.items())
+                    if isinstance(matches, dict)
+                    else []
+                )
+                if branch == "negativeMatches" and (
+                    not isinstance(matches, dict)
+                    or set(matches) != {"matched", "notMatched"}
+                ):
+                    gaps.add("CONDITIONS_BRANCH_UNOBSERVED")
+                for outcome, rows in groups:
+                    if outcome not in ("matched", "notMatched") or not isinstance(
+                        rows, list
+                    ):
+                        gaps.add("INVALID_CONDITION_ENTRY")
+                        continue
+                    ids = list(roots.get((context, source), ()))
+                    for row in rows:
+                        if not isinstance(row, dict):
+                            gaps.add("INVALID_CONDITION_ENTRY")
+                            continue
+                        ids.append(
+                            parse(
+                                context,
+                                source,
+                                row.get("condition"),
+                                row.get("message"),
+                                cast(Outcome, outcome),
+                            )
+                        )
+                    roots[context, source] = tuple(ids)
+    return ConditionReport(
+        MappingProxyType(nodes),
+        MappingProxyType(roots),
+        "partial" if gaps else "complete",
+        tuple(sorted(gaps)),
+    )