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

spring_runtime_mcp/adapters/source_catalog.py

@@ -0,0 +1,119 @@
+"""Validate bounded source evidence without reading or executing source files."""
+
+import json
+import re
+from collections.abc import Mapping
+from pathlib import PurePosixPath
+from types import MappingProxyType
+from typing import Any
+
+from ..models.common import AnalysisBudget, NormalizationError
+from ..models.source_catalog import SourceCatalog, SourceProducer, TypeFact
+from ..transport.bounded_json import validate_tree
+
+_ID = re.compile(r"[A-Za-z_$][A-Za-z0-9_.$]*(?:#[A-Za-z_$][A-Za-z0-9_$]*)?\Z")
+
+
+def _text(value: Any) -> str:
+    if not isinstance(value, str) or len(value) > 256 or not _ID.fullmatch(value):
+        raise NormalizationError("INVALID_SOURCE_CATALOG")
+    return value
+
+
+def _strings(value: Any) -> tuple[str, ...]:
+    if not isinstance(value, list) or len(value) > 1000:
+        raise NormalizationError("INVALID_SOURCE_CATALOG")
+    return tuple(_text(v) for v in value)
+
+
+def load_source_catalog(
+    payload: Mapping[str, Any], *, target_id: str, budget: AnalysisBudget
+) -> SourceCatalog:
+    validate_tree(dict(payload), max_bytes=262144)
+    if (
+        set(payload) - {"targetId", "sourceRevision", "types", "producers"}
+        or payload.get("targetId") != target_id
+    ):
+        raise NormalizationError("SOURCE_TARGET_MISMATCH")
+    if len(json.dumps(payload, ensure_ascii=False).encode()) > 262144:
+        raise NormalizationError("SOURCE_CATALOG_TOO_LARGE")
+    rows, producers = payload.get("types", []), payload.get("producers", [])
+    if (
+        not isinstance(rows, list)
+        or not isinstance(producers, list)
+        or len(rows) + len(producers) > 1000
+    ):
+        raise NormalizationError("INVALID_SOURCE_CATALOG")
+    types: dict[str, TypeFact] = {}
+    for row in rows:
+        budget.consume()
+        if not isinstance(row, dict) or set(row) != {"name", "directSupertypes"}:
+            raise NormalizationError("INVALID_SOURCE_CATALOG")
+        name = _text(row["name"])
+        if name in types:
+            raise NormalizationError("DUPLICATE_SOURCE_TYPE")
+        types[name] = TypeFact(name, _strings(row["directSupertypes"]))
+    parsed = []
+    keys = {
+        "contextId",
+        "beanName",
+        "aliases",
+        "declaredType",
+        "implementationType",
+        "configurationClass",
+        "factoryMethod",
+        "conditionSources",
+        "sourceFile",
+        "sourceLine",
+    }
+    for i, row in enumerate(producers):
+        budget.consume()
+        if not isinstance(row, dict) or set(row) != keys:
+            raise NormalizationError("INVALID_SOURCE_CATALOG")
+        file = row["sourceFile"]
+        if (
+            not isinstance(file, str)
+            or file in ("", ".")
+            or len(file) > 256
+            or "\\" in file
+            or ":" in file
+            or any(ord(c) < 32 for c in file)
+            or PurePosixPath(file).is_absolute()
+            or ".." in PurePosixPath(file).parts
+        ):
+            raise NormalizationError("INVALID_SOURCE_PATH")
+        line = row["sourceLine"]
+        if type(line) is not int or line < 1:
+            raise NormalizationError("INVALID_SOURCE_LINE")
+
+        current = row
+
+        def optional(key: str, record: dict[str, Any] = current) -> str | None:
+            return None if record[key] is None else _text(record[key])
+
+        parsed.append(
+            SourceProducer(
+                f"source_producer_{i}",
+                _text(row["contextId"]),
+                _text(row["beanName"]),
+                _strings(row["aliases"]),
+                _text(row["declaredType"]),
+                optional("implementationType"),
+                _text(row["configurationClass"]),
+                optional("factoryMethod"),
+                _strings(row["conditionSources"]),
+                file,
+                line,
+                (f"source_evidence_{i}",),
+            )
+        )
+    revision = payload.get("sourceRevision")
+    if revision is not None and (
+        not isinstance(revision, str)
+        or len(revision) > 128
+        or any(ord(c) < 32 for c in revision)
+    ):
+        raise NormalizationError("INVALID_SOURCE_REVISION")
+    return SourceCatalog(
+        target_id, revision, MappingProxyType(types), tuple(parsed), ()
+    )

spring_runtime_mcp/adapters/startup.py

@@ -0,0 +1,202 @@
+"""Normalize ApplicationStartup timelines without posting to the startup endpoint."""
+
+from __future__ import annotations
+
+import re
+from decimal import Decimal
+from typing import Any
+
+from ..models.common import AnalysisBudget
+from ..models.timestamps import parse_rfc3339
+
+from ..contracts.definitions import glob_matches
+
+_DURATION = re.compile(r"PT(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?\Z")
+
+
+def _nanos(text: str) -> int | None:
+    matched = _DURATION.fullmatch(text)
+    if matched is None or not any(matched.groups()):
+        return None
+    hours = Decimal(matched.group(1) or 0)
+    minutes = Decimal(matched.group(2) or 0)
+    seconds = Decimal(matched.group(3) or 0)
+    return int((hours * 3600 + minutes * 60 + seconds) * Decimal(1_000_000_000))
+
+
+def _timestamp(value: Any) -> str | None:
+    return (
+        value if isinstance(value, str) and parse_rfc3339(value) is not None else None
+    )
+
+
+def _bottleneck(name: str) -> str:
+    if "beans.instantiate" in name:
+        return "BEAN_INSTANTIATION"
+    if "base-packages.scan" in name or "component-scan" in name:
+        return "PACKAGE_SCAN"
+    if "auto-config" in name or "autoconfigure" in name:
+        return "AUTO_CONFIGURATION"
+    return "OTHER" if name else "UNKNOWN"
+
+
+def normalize_startup(
+    body: Any,
+    *,
+    step_name_pattern: str | None,
+    bean_name_pattern: str | None,
+    min_duration_ms: float,
+    max_depth: int,
+) -> tuple[str | None, int | float | None, str, bool, list[dict[str, Any]], list[str]]:
+    if not isinstance(body, dict) or not isinstance(body.get("timeline"), dict):
+        raise ValueError("INVALID_STARTUP_SHAPE")
+    events = body["timeline"].get("events")
+    if not isinstance(events, list):
+        raise ValueError("INVALID_STARTUP_SHAPE")
+    version = body.get("springBootVersion")
+    version = version if isinstance(version, str) and len(version) <= 64 else None
+    gaps: set[str] = set()
+    budget = AnalysisBudget()
+    records: dict[str, dict[str, Any]] = {}
+    order: list[str] = []
+    for event in events:
+        budget.consume()
+        if len(order) >= 500:
+            gaps.add("STARTUP_NODE_LIMIT")
+            break
+        if not isinstance(event, dict) or not isinstance(
+            event.get("startupStep"), dict
+        ):
+            gaps.add("STARTUP_EVENT_UNREADABLE")
+            continue
+        step = event["startupStep"]
+        raw_id = step.get("id")
+        if type(raw_id) is not int or raw_id < 0:
+            gaps.add("STARTUP_EVENT_UNREADABLE")
+            continue
+        step_id = str(raw_id)
+        if step_id in records:
+            gaps.add("STARTUP_DUPLICATE_STEP")
+            records[step_id]["relationState"] = "duplicate"
+            continue
+        nanos = (
+            _nanos(event["duration"])
+            if isinstance(event.get("duration"), str)
+            else None
+        )
+        if nanos is None:
+            gaps.add("STARTUP_DURATION_UNPARSED")
+        parent = step.get("parentId")
+        parent_id = str(parent) if type(parent) is int and parent >= 0 else None
+        tags = []
+        raw_tags = step.get("tags", [])
+        if isinstance(raw_tags, list):
+            if len(raw_tags) > 10:
+                gaps.add("STARTUP_TAG_LIMIT")
+            for tag in raw_tags[:10]:
+                if not isinstance(tag, dict) or not isinstance(tag.get("key"), str):
+                    continue
+                value = tag.get("value")
+                tags.append(
+                    {
+                        "key": tag["key"][:128],
+                        "value": value[:256] if isinstance(value, str) else None,
+                    }
+                )
+        name = step.get("name") if isinstance(step.get("name"), str) else ""
+        raw_started = event.get("startTime")
+        started_at = _timestamp(raw_started)
+        if isinstance(raw_started, str) and started_at is None:
+            gaps.add("STARTUP_TIMING_UNOBSERVED")
+        records[step_id] = {
+            "stepId": step_id,
+            "parentStepId": parent_id,
+            "name": name[:256],
+            "startedAt": started_at,
+            "durationNanos": None if nanos is None else str(nanos),
+            "durationMs": None if nanos is None else nanos / 1_000_000,
+            "tags": tags,
+            "bottleneckCode": _bottleneck(name),
+            "relationState": "resolved",
+        }
+        order.append(step_id)
+    for step_id, row in records.items():
+        parent = row["parentStepId"]
+        if parent is None:
+            continue
+        if parent not in records:
+            row["relationState"] = "orphan"
+            gaps.add("STARTUP_ORPHAN_STEP")
+            continue
+        seen = {step_id}
+        cursor = parent
+        while cursor is not None:
+            budget.consume()
+            if cursor in seen:
+                row["relationState"] = "cycle"
+                gaps.add("STARTUP_CYCLE")
+                break
+            seen.add(cursor)
+            cursor = records.get(cursor, {}).get("parentStepId")
+    items: list[dict[str, Any]] = []
+    for step_id in order:
+        row = records[step_id]
+        ancestors: list[str] = []
+        cursor = row["parentStepId"]
+        visited: set[str] = set()
+        while cursor and cursor not in visited and len(ancestors) < 16:
+            visited.add(cursor)
+            ancestors.append(cursor)
+            cursor = records.get(cursor, {}).get("parentStepId")
+        if len(ancestors) > max_depth:
+            gaps.add("STARTUP_DEPTH_LIMIT")
+            continue
+        if step_name_pattern and not glob_matches(step_name_pattern, row["name"]):
+            continue
+        if bean_name_pattern and not any(
+            tag["key"] == "beanName"
+            and isinstance(tag["value"], str)
+            and glob_matches(bean_name_pattern, tag["value"])
+            for tag in row["tags"]
+        ):
+            continue
+        duration = row["durationMs"]
+        if duration is not None and duration < min_duration_ms:
+            continue
+        row["ancestorIds"] = ancestors
+        items.append(row)
+    items.sort(
+        key=lambda row: (
+            -(row["durationMs"] if isinstance(row["durationMs"], (int, float)) else -1),
+            row["stepId"],
+        )
+    )
+    total: int | float | None = None
+    try:
+        starts = [parse_rfc3339(event["startTime"]) for event in events]
+        ends = [parse_rfc3339(event["endTime"]) for event in events]
+        if not starts or any(date is None for date in [*starts, *ends]):
+            raise ValueError("STARTUP_TIMING_UNOBSERVED")
+        valid_starts = [date for date in starts if date is not None]
+        valid_ends = [date for date in ends if date is not None]
+        raw_start = body["timeline"].get("startTime")
+        start = (
+            parse_rfc3339(raw_start)
+            if "startTime" in body["timeline"]
+            else min(valid_starts)
+        )
+        if start is None:
+            raise ValueError("STARTUP_TIMING_UNOBSERVED")
+        if any(
+            end < begin or begin < start
+            for begin, end in zip(valid_starts, valid_ends, strict=True)
+        ):
+            raise ValueError("STARTUP_TIMING_UNOBSERVED")
+        if any(date.leap for date in [start, *valid_starts, *valid_ends]):
+            raise ValueError("STARTUP_TIMING_UNOBSERVED")
+        total = max(valid_ends).milliseconds_since(start)
+    except (ValueError, TypeError, KeyError, AttributeError):
+        gaps.add("STARTUP_TIMING_UNOBSERVED")
+    complete = not gaps
+    basis = "timelineSpan" if total is not None else "unknown"
+    return version, total, basis, complete, items, sorted(gaps)

spring_runtime_mcp/analyzers/__init__.py

@@ -0,0 +1 @@
+"""Deterministic diagnostic algorithms, with no network access."""

spring_runtime_mcp/analyzers/bean_graph.py

@@ -0,0 +1,172 @@
+"""Deterministic alias-aware dependency resolution and breadth-first slices."""
+
+from __future__ import annotations
+
+from collections import deque
+
+from ..models.bean_graph import (
+    BeanGraph,
+    BeanKey,
+    ContextKey,
+    DependencyEdge,
+    GraphSlice,
+    Resolution,
+)
+from ..models.common import AnalysisBudget, AnalysisLimit
+
+
+def resolve_bean_reference(
+    graph: BeanGraph, defining_context: ContextKey, requested_name: str
+) -> Resolution:
+    current: ContextKey | None = defining_context
+    seen: set[ContextKey] = set()
+    while current is not None:
+        if current in seen:
+            return Resolution("unresolved", (), "CONTEXT_CYCLE")
+        seen.add(current)
+        context = graph.contexts.get(current)
+        if context is None:
+            return Resolution("unresolved", (), "PARENT_CONTEXT_UNOBSERVED")
+        if not context.complete:
+            return Resolution("unresolved", (), "BEAN_INDEX_INCOMPLETE")
+        candidates = graph.names.get(current, {}).get(requested_name, ())
+        if len(candidates) > 1:
+            return Resolution("ambiguous", candidates, "ALIAS_AMBIGUOUS")
+        if candidates:
+            return Resolution("resolved", candidates, None)
+        if context.parent.state != "known":
+            return Resolution("unresolved", (), "PARENT_CONTEXT_UNOBSERVED")
+        current = context.parent.value
+    return Resolution("unresolved", (), "NOT_FOUND_IN_COMPLETE_VISIBLE_HIERARCHY")
+
+
+def build_dependency_graph(graph: BeanGraph, *, budget: AnalysisBudget) -> BeanGraph:
+    forward: dict[BeanKey, list[DependencyEdge]] = {key: [] for key in graph.beans}
+    reverse: dict[BeanKey, list[DependencyEdge]] = {key: [] for key in graph.beans}
+    gaps = set(graph.gaps)
+    try:
+        for key, bean in sorted(graph.beans.items()):
+            budget.consume()
+            for requested in bean.requested_dependencies:
+                budget.consume()
+                resolution = resolve_bean_reference(graph, key.context, requested)
+                edge = DependencyEdge(key, requested, resolution, bean.evidence_ids)
+                forward[key].append(edge)
+                if resolution.state == "resolved":
+                    reverse[resolution.candidates[0]].append(edge)
+                else:
+                    gaps.add(resolution.reason_code or "DEPENDENCY_UNRESOLVED")
+    except AnalysisLimit:
+        gaps.add("GRAPH_LIMIT_REACHED")
+    return BeanGraph(
+        graph.contexts,
+        graph.beans,
+        graph.names,
+        graph.canonical_to_names,
+        {key: tuple(edges) for key, edges in forward.items()},
+        {key: tuple(edges) for key, edges in reverse.items()},
+        "partial" if gaps else "complete",
+        tuple(sorted(gaps)),
+    )
+
+
+def visible_beans(
+    graph: BeanGraph, start: ContextKey, *, budget: AnalysisBudget | None = None
+) -> tuple[BeanKey, ...] | None:
+    """List type-query candidates with the same shadowing rules as name lookup."""
+    budget = budget or AnalysisBudget()
+    current: ContextKey | None = start
+    seen: set[ContextKey] = set()
+    occupied: set[str] = set()
+    selected: list[BeanKey] = []
+    while current is not None:
+        budget.consume()
+        if current in seen:
+            return None
+        seen.add(current)
+        context = graph.contexts.get(current)
+        if context is None or not context.complete or context.parent.state != "known":
+            return None
+        for key in sorted(graph.beans):
+            if key.context == current:
+                budget.consume()
+                if key.canonical_name not in occupied:
+                    selected.append(key)
+        # A local alias can also hide an ancestor's canonical name.
+        occupied.update(graph.names.get(current, {}))
+        current = context.parent.value
+    return tuple(selected)
+
+
+def slice_dependencies(
+    graph: BeanGraph,
+    roots: tuple[BeanKey, ...],
+    *,
+    direction: str,
+    max_depth: int,
+    budget: AnalysisBudget,
+) -> GraphSlice:
+    if direction not in (
+        "dependencies",
+        "dependents",
+        "both",
+    ) or not 0 <= max_depth <= min(16, budget.max_depth):
+        raise ValueError("INVALID_GRAPH_QUERY")
+    gaps = set(graph.gaps)
+    selected: dict[tuple[BeanKey, str], tuple[DependencyEdge, int]] = {}
+    cut = False
+    # Separate traversals avoid interpreting a zig-zag in 'both' as a dependency chain.
+    directions = ("dependencies", "dependents") if direction == "both" else (direction,)
+    try:
+        for traversal in directions:
+            queue = deque((key, 0) for key in sorted(set(roots)))
+            seen = set(roots)
+            index = graph.forward if traversal == "dependencies" else graph.reverse
+            while queue:
+                key, depth = queue.popleft()
+                budget.consume()
+                edges = index.get(key, ())
+                if depth >= max_depth:
+                    # Cycles already inside the visited set do not imply a hidden closure.
+                    if any(
+                        (
+                            edge.resolution.candidates[0]
+                            if traversal == "dependencies"
+                            and edge.resolution.state == "resolved"
+                            else edge.from_key
+                            if traversal == "dependents"
+                            else None
+                        )
+                        not in seen
+                        for edge in edges
+                    ):
+                        cut = True
+                    continue
+                for edge in edges:
+                    budget.consume()
+                    identity = (edge.from_key, edge.requested_name)
+                    previous = selected.get(identity)
+                    if previous is None or depth + 1 < previous[1]:
+                        selected[identity] = (edge, depth + 1)
+                    next_key = (
+                        edge.resolution.candidates[0]
+                        if traversal == "dependencies"
+                        and edge.resolution.state == "resolved"
+                        else edge.from_key
+                        if traversal == "dependents"
+                        else None
+                    )
+                    if next_key is not None and next_key not in seen:
+                        seen.add(next_key)
+                        queue.append((next_key, depth + 1))
+    except AnalysisLimit:
+        cut = True
+    if cut:
+        gaps.add("GRAPH_LIMIT_REACHED")
+    edges_result = tuple(
+        sorted(
+            selected.values(),
+            key=lambda pair: (pair[1], pair[0].from_key, pair[0].requested_name),
+        )
+    )
+    return GraphSlice(tuple(sorted(set(roots))), edges_result, cut, tuple(sorted(gaps)))