mneme-code 3.1.0__py3-none-any.whl

mneme_code/resolve.py

@@ -0,0 +1,116 @@
+"""Frame-to-graph resolution: match stack frames against mneme-graph nodes.
+
+Design constraints
+------------------
+* No hard import of ``mneme_graph`` types — the dependency is optional at
+  runtime (the store may be ``None``) and hard coupling would break mypy
+  ``--strict`` when ``mneme_graph`` stubs are absent.
+* A local ``typing.Protocol`` pair (``_NodeLike`` / ``_StoreLike``) defines
+  the minimal structural interface required for matching.  Any object that
+  satisfies the protocol works — including a real ``GraphStore``.
+* Clean fallback: if ``graph_store`` is ``None`` or its ``.nodes`` sequence
+  is empty, every frame maps to ``(frame, None)`` with no error.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Protocol, runtime_checkable
+
+from mneme_code.stacktrace import Frame
+
+# ---------------------------------------------------------------------------
+# Structural protocols (no mneme_graph import required)
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class _NodeLike(Protocol):
+    """Minimal interface for a graph node used by :func:`resolve_frames`."""
+
+    name: str
+    source_path: str
+    kind: str
+
+
+@runtime_checkable
+class _StoreLike(Protocol):
+    """Minimal interface for a graph store used by :func:`resolve_frames`."""
+
+    @property
+    def nodes(self) -> Sequence[_NodeLike]:
+        """Ordered sequence of graph nodes."""
+        ...  # pragma: no cover
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def resolve_frames(
+    parsed: object,
+    graph_store: object | None,
+) -> list[tuple[Frame, object | None]]:
+    """Match each frame in *parsed* against nodes in *graph_store*.
+
+    Matching criteria: a node matches a frame when ``node.kind == "function"``,
+    ``node.name == frame.function``, and the frame's (normalised) absolute
+    ``file_path`` equals or ends with ``/<node.source_path>``. The suffix test
+    bridges absolute traceback paths and vault-relative graph ``source_path``.
+
+    Args:
+        parsed:      A :class:`~mneme_code.stacktrace.ParsedTraceback` (or
+                     any object with a ``.frames`` attribute that is a
+                     sequence of :class:`Frame`).  Accepted as ``object``
+                     to avoid a circular import; the attribute is accessed
+                     via ``getattr``.
+        graph_store: A :class:`~mneme_graph.store.GraphStore` or any object
+                     satisfying :class:`_StoreLike`, or ``None``.  When
+                     ``None`` or empty, every frame maps to ``(frame, None)``.
+
+    Returns:
+        A list of ``(frame, node_or_none)`` pairs in frame order.
+        Each pair contains the original :class:`Frame` and either the
+        matching node object or ``None`` if no match was found.
+    """
+    # Extract frames from parsed; tolerate any object with .frames.
+    frames_raw = getattr(parsed, "frames", ())
+    frames: list[Frame] = [f for f in frames_raw if isinstance(f, Frame)]
+
+    # Fast path: no store or no nodes.
+    if graph_store is None:
+        return [(frame, None) for frame in frames]
+
+    # Attempt to read .nodes from the store via the protocol.
+    nodes_seq: Sequence[object] = ()
+    if isinstance(graph_store, _StoreLike):
+        try:
+            nodes_seq = graph_store.nodes
+        except Exception:  # noqa: BLE001
+            nodes_seq = ()
+
+    if not nodes_seq:
+        return [(frame, None) for frame in frames]
+
+    # Traceback file paths are absolute while graph source_paths are
+    # vault-relative, so match by function name plus a path-suffix test rather
+    # than exact equality (which would never match a real traceback).
+    func_nodes: list[_NodeLike] = []
+    for node in nodes_seq:
+        if isinstance(node, _NodeLike) and node.kind == "function" and node.source_path:
+            func_nodes.append(node)
+
+    result: list[tuple[Frame, object | None]] = []
+    for frame in frames:
+        normalised = frame.file_path.replace("\\", "/")
+        match: object | None = None
+        for node in func_nodes:
+            if node.name != frame.function:
+                continue
+            if normalised == node.source_path or normalised.endswith("/" + node.source_path):
+                match = node
+                break
+        result.append((frame, match))
+
+    return result

mneme_code/stacktrace.py

@@ -0,0 +1,191 @@
+"""Deterministic CPython traceback parser with redact-before-store invariant.
+
+Parses the standard CPython traceback format::
+
+    Traceback (most recent call last):
+      File "PATH", line N, in FUNC
+        code line
+    ExcType: message
+
+Redaction invariant (C4): ``mneme_core.privacy.redact`` is applied to
+``exc_message``, every ``code_context``, and every ``file_path`` *before*
+the dataclasses are constructed.  No raw user content ever reaches a field.
+
+``parse_traceback`` returns ``None`` for any input that is not a recognisable
+CPython traceback and never raises.
+"""
+
+from __future__ import annotations
+
+import keyword
+import re
+from dataclasses import dataclass
+
+from mneme_core.privacy import redact
+
+# ---------------------------------------------------------------------------
+# Regex patterns
+# ---------------------------------------------------------------------------
+
+# Opening line of a standard CPython traceback.
+_TRACEBACK_HEADER = re.compile(r"^Traceback \(most recent call last\):\s*$", re.MULTILINE)
+
+# Each frame header: '  File "PATH", line N, in FUNC'
+# Captures: path (group 1), line number (group 2), function name (group 3).
+_FRAME_HEADER = re.compile(
+    r'^\s{2}File "([^"]+)", line (\d+), in (.+?)\s*$',
+    re.MULTILINE,
+)
+
+# Trailing exception line: 'ExcType: message' or just 'ExcType' (no message).
+# Dotted types are supported (e.g. 'pkg.mod.Error').
+_EXC_LINE = re.compile(
+    r"^([\w][\w.]*(?:[\w]+)?)(?::\s*(.*))?\s*$",
+)
+
+
+# ---------------------------------------------------------------------------
+# Dataclasses
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Frame:
+    """A single stack frame extracted from a CPython traceback.
+
+    All string fields have already been passed through ``redact()``
+    before construction; callers must not bypass this by constructing
+    ``Frame`` directly with raw user content.
+    """
+
+    file_path: str
+    line: int
+    function: str
+    code_context: str | None
+
+
+@dataclass(frozen=True)
+class ParsedTraceback:
+    """The parsed, redacted representation of a CPython traceback.
+
+    Attributes:
+        exc_type    Exception class name (may be dotted, e.g. ``pkg.Error``).
+        exc_message Redacted exception message (empty string if none).
+        frames      Tuple of :class:`Frame` objects, innermost last.
+    """
+
+    exc_type: str
+    exc_message: str
+    frames: tuple[Frame, ...]
+
+
+# ---------------------------------------------------------------------------
+# Parser
+# ---------------------------------------------------------------------------
+
+
+def parse_traceback(text: str) -> ParsedTraceback | None:
+    """Parse a standard CPython traceback text into a :class:`ParsedTraceback`.
+
+    Returns ``None`` if *text* is not a recognisable CPython traceback.
+    Never raises.
+
+    Redaction invariant: ``redact()`` is applied to ``exc_message``,
+    every ``code_context``, and every ``file_path`` before any dataclass
+    is constructed.
+
+    Args:
+        text: Raw traceback text (may include leading/trailing whitespace
+              or surrounding log lines; the parser searches for the
+              ``Traceback (most recent call last):`` header).
+    """
+    try:
+        return _parse_traceback_inner(text)
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _parse_traceback_inner(text: str) -> ParsedTraceback | None:
+    """Inner parser — may raise; wrapped by ``parse_traceback``."""
+    # Must contain the standard header.
+    header_match = _TRACEBACK_HEADER.search(text)
+    if header_match is None:
+        return None
+
+    # Work only with text from the header onwards.
+    body = text[header_match.start():]
+    lines = body.splitlines()
+
+    # Collect frame header positions.
+    # Each frame header is '  File "PATH", line N, in FUNC'.
+    # The optional next line (indented more) is the code context.
+    frames: list[Frame] = []
+    i = 1  # skip the 'Traceback ...' header line itself
+    while i < len(lines):
+        fh = _FRAME_HEADER.match(lines[i])
+        if fh is None:
+            i += 1
+            continue
+
+        raw_path = fh.group(1)
+        raw_line = int(fh.group(2))
+        raw_func = fh.group(3).strip()
+
+        # Optional next line: code context (must be indented by >= 4 spaces).
+        code_ctx: str | None = None
+        if i + 1 < len(lines):
+            candidate = lines[i + 1]
+            # Code context lines are indented with at least 4 spaces and are
+            # NOT themselves frame headers.
+            if candidate.startswith("    ") and not _FRAME_HEADER.match(candidate):
+                code_ctx = redact(candidate.strip()) or None
+                i += 2
+            else:
+                i += 1
+        else:
+            i += 1
+
+        frames.append(
+            Frame(
+                file_path=redact(raw_path),
+                line=raw_line,
+                function=raw_func,
+                code_context=code_ctx,
+            )
+        )
+
+    if not frames:
+        return None
+
+    # The exception line is the last non-blank, NON-INDENTED line of the body.
+    # Code-context lines are indented (>= 4 spaces) and the real exception line
+    # sits at column 0, so skipping indented lines stops a truncated traceback
+    # (which ends in an indented code line like ``pass``) from being misread as
+    # the exception. A bare Python keyword is also rejected — no exception class
+    # is named after a keyword.
+    exc_type = ""
+    exc_message = ""
+    for raw_line_text in reversed(lines):
+        if raw_line_text[:1] in (" ", "\t"):
+            continue
+        stripped = raw_line_text.strip()
+        if not stripped:
+            continue
+        if _FRAME_HEADER.match(raw_line_text):
+            continue
+        if stripped.startswith("Traceback (most recent call last)"):
+            continue
+        m = _EXC_LINE.match(stripped)
+        if m and m.group(1) not in keyword.kwlist:
+            exc_type = m.group(1)
+            exc_message = redact(m.group(2) or "")
+            break
+
+    if not exc_type:
+        return None
+
+    return ParsedTraceback(
+        exc_type=exc_type,
+        exc_message=exc_message,
+        frames=tuple(frames),
+    )

mneme_code/testrun.py

@@ -0,0 +1,293 @@
+"""Test-runner output parser: pytest and unittest console output → FailureMemory.
+
+Parses pytest / unittest console output into :class:`TestFailure` records by
+re-using :func:`~mneme_code.stacktrace.parse_traceback` and
+:func:`~mneme_code.failure.failure_from_traceback`.  Pure, deterministic,
+never raises.
+
+Design invariants (mirror stacktrace.py / failure.py):
+* No clock, no random, no I/O inside parsing functions.
+* Redaction is inherited from ``parse_traceback`` — every ``ParsedTraceback``
+  field is already redacted before it reaches a ``TestFailure`` or
+  ``FailureMemory``.
+* ``failures_from_test_output`` accepts ``observed_at: datetime`` injected by
+  the caller; it never calls ``datetime.now()``.
+* Never raises — every public entry point catches all exceptions and returns
+  ``[]``.
+* Frozen dataclasses for all public types.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import datetime
+
+from mneme_core.privacy import redact
+
+from mneme_code.failure import FailureMemory, failure_from_traceback
+from mneme_code.stacktrace import ParsedTraceback, parse_traceback
+
+# ---------------------------------------------------------------------------
+# Regex patterns
+# ---------------------------------------------------------------------------
+
+# pytest: separator banner around each failing test block.
+# e.g. "________ TestFoo.test_bar ________" or "________ test_bar ________"
+_PYTEST_BANNER = re.compile(r"^_{4,}\s+(.+?)\s+_{4,}\s*$", re.MULTILINE)
+
+# pytest: failures section header
+_PYTEST_FAILURES_HDR = re.compile(r"=+\s*FAILURES\s*=+", re.IGNORECASE)
+
+# pytest: short-test-summary lines  ("FAILED tests/x.py::C::m - ...")
+# Requires the test ID to look like a path (contains "/" or "::") so bare
+# unittest footers like "FAILED (failures=1)" are not matched.
+_PYTEST_SUMMARY_LINE = re.compile(r"^FAILED\s+(\S*(?:/|::)\S*)", re.MULTILINE)
+
+# unittest: "FAIL: test_x (mod.TestClass)" or "ERROR: test_x (mod.TestClass)"
+_UNITTEST_HDR = re.compile(
+    r"^(?:FAIL|ERROR):\s+(.+?)\s*$",
+    re.MULTILINE,
+)
+
+# Rule separators used by unittest (lines of "=" or "-", >= 10 chars)
+_RULE_LINE = re.compile(r"^[=\-]{10,}\s*$", re.MULTILINE)
+
+# Traceback start sentinel
+_TB_START = re.compile(r"Traceback \(most recent call last\):", re.MULTILINE)
+
+
+# ---------------------------------------------------------------------------
+# Dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class TestFailure:
+    """A single test failure with optional parsed traceback.
+
+    Attributes:
+        test_id    Human-readable test identifier.
+                   pytest style:    ``"tests/test_x.py::TestY::test_z"``
+                   unittest style:  ``"test_z (mod.TestY)"``
+        traceback  :class:`~mneme_code.stacktrace.ParsedTraceback` parsed from
+                   the failure's traceback block, or ``None`` if no parseable
+                   traceback was found.
+    """
+
+    test_id: str
+    traceback: ParsedTraceback | None
+
+
+# ---------------------------------------------------------------------------
+# pytest parser
+# ---------------------------------------------------------------------------
+
+
+def parse_pytest_output(text: str) -> list[TestFailure]:
+    """Parse *text* as pytest console output into :class:`TestFailure` records.
+
+    Strategy:
+    1. Locate the ``=== FAILURES ===`` section (or fall back to the full text).
+    2. Use ``_______ <test-id> _______`` banners to delimit per-test blocks.
+    3. For each block, call :func:`~mneme_code.stacktrace.parse_traceback` on
+       the block text.
+    4. Fall back to short-test-summary ``FAILED ...`` lines for test IDs that
+       had no banner-delimited block.
+
+    Args:
+        text: Raw pytest stdout/stderr output.
+
+    Returns:
+        Ordered list of :class:`TestFailure`, one per failing test.
+        Returns ``[]`` if nothing parseable is found or on any error.
+    """
+    try:
+        return _parse_pytest_inner(text)
+    except Exception:  # noqa: BLE001
+        return []
+
+
+def _parse_pytest_inner(text: str) -> list[TestFailure]:
+    """Inner pytest parser — may raise; wrapped by ``parse_pytest_output``."""
+    if not text or not text.strip():
+        return []
+
+    # Locate the FAILURES section; restrict parsing to that region when present.
+    hdr_match = _PYTEST_FAILURES_HDR.search(text)
+    body = text[hdr_match.start() :] if hdr_match else text
+
+    # Split on banner lines to get (banner_text, block_text) pairs.
+    banners = list(_PYTEST_BANNER.finditer(body))
+    if not banners:
+        # No banner-delimited blocks; try summary lines only (no tracebacks).
+        return _pytest_summary_fallback(text)
+
+    failures: list[TestFailure] = []
+    for idx, banner in enumerate(banners):
+        # B5: redact the test_id before it becomes source_label. A parametrized
+        # test name can carry secret-like text (e.g. test_x[<private>tok</private>]);
+        # failure.py assumes source_label is already clean, so redact at the source.
+        test_id = redact(banner.group(1).strip())
+        block_start = banner.end()
+        block_end = banners[idx + 1].start() if idx + 1 < len(banners) else len(body)
+        block_text = body[block_start:block_end]
+        parsed = parse_traceback(block_text)
+        failures.append(TestFailure(test_id=test_id, traceback=parsed))
+
+    return failures
+
+
+def _pytest_summary_fallback(text: str) -> list[TestFailure]:
+    """Return TestFailures from FAILED summary lines when no banners exist."""
+    return [
+        TestFailure(test_id=redact(m.group(1)), traceback=None)
+        for m in _PYTEST_SUMMARY_LINE.finditer(text)
+    ]
+
+
+# ---------------------------------------------------------------------------
+# unittest parser
+# ---------------------------------------------------------------------------
+
+
+def parse_unittest_output(text: str) -> list[TestFailure]:
+    """Parse *text* as unittest console output into :class:`TestFailure` records.
+
+    Strategy:
+    1. Find ``FAIL:`` / ``ERROR:`` header lines.
+    2. For each header, extract the block that follows (from the next rule line
+       to the subsequent rule line or the next FAIL/ERROR header).
+    3. Within that block, locate the ``Traceback (most recent call last):`` and
+       parse it with :func:`~mneme_code.stacktrace.parse_traceback`.
+
+    Args:
+        text: Raw unittest stdout/stderr output.
+
+    Returns:
+        Ordered list of :class:`TestFailure`.
+        Returns ``[]`` if nothing parseable is found or on any error.
+    """
+    try:
+        return _parse_unittest_inner(text)
+    except Exception:  # noqa: BLE001
+        return []
+
+
+def _parse_unittest_inner(text: str) -> list[TestFailure]:
+    """Inner unittest parser — may raise; wrapped by ``parse_unittest_output``."""
+    if not text or not text.strip():
+        return []
+
+    hdrs = list(_UNITTEST_HDR.finditer(text))
+    if not hdrs:
+        return []
+
+    failures: list[TestFailure] = []
+    for idx, hdr in enumerate(hdrs):
+        # B5: redact the test_id before it becomes source_label (see parse_pytest).
+        test_id = redact(hdr.group(1).strip())
+        block_start = hdr.end()
+        # Block ends at the start of the next header or end of text.
+        block_end = hdrs[idx + 1].start() if idx + 1 < len(hdrs) else len(text)
+        block_text = text[block_start:block_end]
+        parsed = parse_traceback(block_text)
+        failures.append(TestFailure(test_id=test_id, traceback=parsed))
+
+    return failures
+
+
+# ---------------------------------------------------------------------------
+# Unified entry point
+# ---------------------------------------------------------------------------
+
+
+def failures_from_test_output(
+    text: str,
+    *,
+    observed_at: datetime,
+    runner: str = "auto",
+) -> list[FailureMemory]:
+    """Convert test-runner console output into :class:`FailureMemory` records.
+
+    Auto-detection heuristic (``runner="auto"``):
+    * pytest  — text contains ``"=== FAILURES ==="`` (case-insensitive) *or*
+                ``"short test summary"`` *or* a ``"FAILED "`` summary line *or*
+                a ``"______"`` banner line.
+    * unittest — text contains a ``"FAIL:"`` / ``"ERROR:"`` header followed by
+                 a traceback block.
+    * Falls back to pytest if detection is ambiguous.
+
+    Only :class:`TestFailure` records whose ``.traceback`` is not ``None`` are
+    converted; failures with no parseable traceback are silently skipped.
+
+    Args:
+        text:        Raw test-runner output.
+        observed_at: Tz-aware UTC datetime for each :class:`FailureMemory`.
+                     Must be injected by the caller; this function never calls
+                     ``datetime.now()``.
+        runner:      ``"pytest"``, ``"unittest"``, or ``"auto"`` (default).
+
+    Returns:
+        List of :class:`FailureMemory`, one per test with a parseable
+        traceback.  Returns ``[]`` on any error or if nothing is parseable.
+    """
+    try:
+        return _failures_inner(text, observed_at=observed_at, runner=runner)
+    except Exception:  # noqa: BLE001
+        return []
+
+
+def _failures_inner(
+    text: str,
+    *,
+    observed_at: datetime,
+    runner: str,
+) -> list[FailureMemory]:
+    """Inner implementation — may raise; wrapped by ``failures_from_test_output``."""
+    if not text or not text.strip():
+        return []
+
+    effective_runner = runner if runner != "auto" else _detect_runner(text)
+
+    if effective_runner == "unittest":
+        test_failures = parse_unittest_output(text)
+    else:
+        test_failures = parse_pytest_output(text)
+
+    results: list[FailureMemory] = []
+    for tf in test_failures:
+        if tf.traceback is None:
+            continue
+        fm = failure_from_traceback(
+            tf.traceback,
+            observed_at=observed_at,
+            source_label=tf.test_id,
+        )
+        results.append(fm)
+
+    return results
+
+
+def _detect_runner(text: str) -> str:
+    """Return ``"pytest"`` or ``"unittest"`` based on text heuristics.
+
+    Unittest signals are checked first because they are more specific
+    (``FAIL:``/``ERROR:`` headers are unambiguous).  Pytest signals that
+    can appear in unittest output (e.g. the word ``FAILED``) are only
+    consulted when the unittest pattern is absent.
+    """
+    # unittest signals: FAIL:/ERROR: header + traceback — check first, more specific
+    if _UNITTEST_HDR.search(text) and _TB_START.search(text):
+        return "unittest"
+    # pytest signals
+    lower = text.lower()
+    if (
+        "=== failures ===" in lower
+        or "short test summary" in lower
+        or _PYTEST_SUMMARY_LINE.search(text)
+        or _PYTEST_BANNER.search(text)
+    ):
+        return "pytest"
+    # Default to pytest
+    return "pytest"