mneme-code 3.1.0__py3-none-any.whl

mneme_code/__init__.py

@@ -0,0 +1,71 @@
+"""mneme-code: deterministic Python code-failure memory layer.
+
+Design invariants
+-----------------
+* No LLM, no network — pure stdlib + mneme-core + mneme-graph.
+* Redact-before-store — ``mneme_core.privacy.redact`` is applied to
+  ``exc_message``, every ``code_context``, and every ``file_path``
+  *before* any dataclass is constructed or any text is rendered.
+* Provenance on every record — ``content_hash`` (sha256 of canonical
+  redacted rendering), ``observed_at`` (injected by caller; never
+  produced inside library functions), ``trust`` (default ``"user"``),
+  and ``confidence`` (default ``"EXTRACTED"``).
+* Deterministic — same inputs always produce the same ``failure_id``
+  and ``content_hash``; no ``datetime.now()`` or ``random`` inside
+  library functions.
+* Markdown is the ground-truth artifact — ``failure_to_markdown``
+  produces a vault-ready note; the vault is the store.
+
+DEFER (not built in this version)
+----------------------------------
+* Live in-process test-runner plugin (a pytest hook). Console-output parsing
+  of pytest/unittest IS built — see ``testrun``.
+* Branch-aware failure tracking.
+* Repository runbook generation.
+* Non-Python tracebacks (JavaScript, Rust, Go, etc.).
+
+Public API
+----------
+    from mneme_code.stacktrace import Frame, ParsedTraceback, parse_traceback
+    from mneme_code.failure import FailureMemory, failure_from_traceback, failure_to_markdown
+    from mneme_code.resolve import resolve_frames
+    from mneme_code.agents import ProceduralMemory, parse_agents_md, procedural_to_markdown
+    from mneme_code.testrun import (
+        TestFailure, parse_pytest_output, parse_unittest_output, failures_from_test_output,
+    )
+    from mneme_code.trajectory import FixTrajectory, fix_from_failure, fix_to_markdown
+"""
+
+from mneme_code.agents import ProceduralMemory, parse_agents_md, procedural_to_markdown
+from mneme_code.failure import FailureMemory, failure_from_traceback, failure_to_markdown
+from mneme_code.resolve import resolve_frames
+from mneme_code.stacktrace import Frame, ParsedTraceback, parse_traceback
+from mneme_code.testrun import (
+    TestFailure,
+    failures_from_test_output,
+    parse_pytest_output,
+    parse_unittest_output,
+)
+from mneme_code.trajectory import FixTrajectory, fix_from_failure, fix_to_markdown
+
+__version__ = "0.2.0"
+__all__ = [
+    "__version__",
+    "Frame",
+    "ParsedTraceback",
+    "parse_traceback",
+    "FailureMemory",
+    "failure_from_traceback",
+    "failure_to_markdown",
+    "resolve_frames",
+    "ProceduralMemory",
+    "parse_agents_md",
+    "procedural_to_markdown",
+    "TestFailure",
+    "parse_pytest_output",
+    "parse_unittest_output",
+    "failures_from_test_output",
+    "FixTrajectory",
+    "fix_from_failure",
+    "fix_to_markdown",
+]

mneme_code/agents.py

@@ -0,0 +1,240 @@
+"""ProceduralMemory dataclass and vault-ready markdown serialization for AGENTS.md.
+
+Parses an AGENTS.md (or any conventions markdown) into structured procedural
+memories, one per level-2 (``##``) heading section.
+
+Design invariants (mirror stacktrace.py / failure.py):
+* Pure, deterministic — no clock, no random, no I/O inside parse functions.
+* Redact-before-store — ``mneme_core.privacy.redact`` is applied to heading
+  text, body text, and fenced-command text before any dataclass field is set.
+* Never raises — ``parse_agents_md`` catches all exceptions and returns ``[]``.
+* Frozen dataclasses for all public types.
+* ``procedural_to_markdown`` accepts ``created: datetime`` injected by caller.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from mneme_core.privacy import redact
+
+# ---------------------------------------------------------------------------
+# Regex helpers
+# ---------------------------------------------------------------------------
+
+# Level-2 heading: "## Some Title"  (with optional trailing whitespace)
+_H2 = re.compile(r"^##\s+(.+?)\s*$", re.MULTILINE)
+
+# Fenced code block: ```[lang]\n...\n```  (DOTALL so body can span lines)
+_FENCE = re.compile(r"```[^\n]*\n(.*?)```", re.DOTALL)
+
+
+# ---------------------------------------------------------------------------
+# Dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ProceduralMemory:
+    """A single procedural-memory record extracted from one ## section.
+
+    All string fields have already been passed through ``redact()`` before
+    construction; callers must not bypass this by constructing
+    ``ProceduralMemory`` directly with raw user content.
+
+    Attributes:
+        memory_id     Deterministic UUID5(NAMESPACE_URL, source_path + NUL + heading).
+        title         Redacted section heading text (without the "## " prefix).
+        content       Redacted section body (prose text, fenced blocks stripped out).
+        commands      Tuple of fenced code-block contents found in the section,
+                      redacted, in document order.
+        source_path   Vault-relative posix path supplied by the caller.
+        content_hash  SHA-256 hex of ``redact(full_file_text)``.
+        trust         Provenance tier; default ``"user"``.
+        confidence    Confidence label; default ``"EXTRACTED"``.
+    """
+
+    memory_id: str
+    title: str
+    content: str
+    commands: tuple[str, ...]
+    source_path: str
+    content_hash: str
+    trust: str = field(default="user")
+    confidence: str = field(default="EXTRACTED")
+
+
+# ---------------------------------------------------------------------------
+# Parser
+# ---------------------------------------------------------------------------
+
+
+def parse_agents_md(text: str, *, source_path: str) -> list[ProceduralMemory]:
+    """Parse *text* into a list of :class:`ProceduralMemory` records.
+
+    Each level-2 (``## ``) heading produces one record.  Content that appears
+    before the first ``## `` heading (including any level-1 ``# `` title line)
+    is discarded — it is typically a document title with no actionable procedure.
+
+    Edge cases:
+    * Empty string or whitespace-only → ``[]``.
+    * No ``##`` headings → ``[]``.
+    * A section with no body text and no commands → ``content=""`` / ``commands=()``.
+    * Never raises; all exceptions are swallowed and return ``[]``.
+
+    Args:
+        text:        Raw AGENTS.md file content (may be empty).
+        source_path: Vault-relative posix path to embed in each record
+                     (used for ``memory_id`` derivation and the frontmatter).
+
+    Returns:
+        Ordered list of :class:`ProceduralMemory`, one per ``##`` section.
+    """
+    try:
+        return _parse_inner(text, source_path=source_path)
+    except Exception:  # noqa: BLE001
+        return []
+
+
+def _parse_inner(text: str, *, source_path: str) -> list[ProceduralMemory]:
+    """Inner parser — may raise; wrapped by ``parse_agents_md``."""
+    if not text or not text.strip():
+        return []
+
+    # content_hash is sha256 of the redacted *full* file text.
+    content_hash = hashlib.sha256(redact(text).encode("utf-8")).hexdigest()
+
+    # Walk lines tracking fenced-code state so a "## " line INSIDE a ``` fence is
+    # treated as code, NOT as a heading (otherwise a bash comment like
+    # "## install deps" would split a phantom section). Collect (heading, body)
+    # pairs; any text before the first heading is preamble and discarded.
+    sections: list[tuple[str, str]] = []
+    current_heading: str | None = None
+    current_body: list[str] = []
+    in_fence = False
+    for line in text.splitlines():
+        if line.lstrip().startswith("```"):
+            in_fence = not in_fence
+            if current_heading is not None:
+                current_body.append(line)
+            continue
+        if not in_fence:
+            heading_match = _H2.match(line)
+            if heading_match is not None:
+                if current_heading is not None:
+                    sections.append((current_heading, "\n".join(current_body)))
+                current_heading = heading_match.group(1).strip()
+                current_body = []
+                continue
+        if current_heading is not None:
+            current_body.append(line)
+    if current_heading is not None:
+        sections.append((current_heading, "\n".join(current_body)))
+
+    if not sections:
+        # No ## headings found.
+        return []
+
+    memories: list[ProceduralMemory] = []
+    for raw_heading, raw_body in sections:
+        # Extract fenced commands before removing them from the prose body.
+        raw_commands: list[str] = [m.group(1) for m in _FENCE.finditer(raw_body)]
+
+        # Prose content: remove fenced blocks, strip leading/trailing whitespace.
+        prose = _FENCE.sub("", raw_body).strip()
+
+        # Redact everything before storing.
+        title = redact(raw_heading)
+        content = redact(prose)
+        commands = tuple(redact(cmd) for cmd in raw_commands)
+
+        # Deterministic UUID5: namespace URL + "source_path\x00heading" (pre-redaction
+        # heading used here so identity is stable across redaction-token changes).
+        key = f"{source_path}\x00{raw_heading}"
+        memory_id = str(uuid.uuid5(uuid.NAMESPACE_URL, key))
+
+        memories.append(
+            ProceduralMemory(
+                memory_id=memory_id,
+                title=title,
+                content=content,
+                commands=commands,
+                source_path=source_path,
+                content_hash=content_hash,
+            )
+        )
+
+    return memories
+
+
+# ---------------------------------------------------------------------------
+# Markdown serializer
+# ---------------------------------------------------------------------------
+
+
+def procedural_to_markdown(mem: ProceduralMemory, *, created: datetime) -> str:
+    """Render a :class:`ProceduralMemory` as a vault-ready markdown note.
+
+    Frontmatter fields (manual construction, no yaml import — mirrors
+    ``failure_to_markdown`` style):
+        id            mem.memory_id
+        type          ``"reference"``
+        created       *created* normalised to tz-aware UTC ISO 8601 w/ microseconds
+        tags          ``["procedure", "agents-md"]``
+        source_path   JSON-encoded (safe for arbitrary vault paths)
+        content_hash  mem.content_hash
+        trust         mem.trust
+
+    Body: ``# {title}``, blank line, prose content, then (if commands are
+    present) a ``## Commands`` section with each command as a fenced block.
+
+    The *created* datetime is injected by the caller; this function never
+    calls ``datetime.now()``.  All content is already redacted upstream.
+
+    Args:
+        mem:     :class:`ProceduralMemory` to render.
+        created: Tz-aware (or naive-UTC) datetime for the ``created`` field.
+
+    Returns:
+        Vault-ready markdown string (trailing newline included).
+    """
+    # Normalise to tz-aware UTC.
+    ts = created.replace(tzinfo=UTC) if created.tzinfo is None else created.astimezone(UTC)
+    created_str = ts.isoformat(timespec="microseconds")
+
+    fm_lines = [
+        "---",
+        f"id: {mem.memory_id}",
+        "type: reference",
+        f"created: {created_str}",
+        "tags:",
+        "  - procedure",
+        "  - agents-md",
+        f"source_path: {json.dumps(mem.source_path)}",
+        f"content_hash: {mem.content_hash}",
+        f"trust: {mem.trust}",
+        "---",
+    ]
+
+    body_lines: list[str] = [
+        f"# {mem.title}",
+        "",
+        mem.content,
+    ]
+
+    if mem.commands:
+        body_lines.append("")
+        body_lines.append("## Commands")
+        body_lines.append("")
+        for cmd in mem.commands:
+            body_lines.append("```")
+            body_lines.append(cmd)
+            body_lines.append("```")
+            body_lines.append("")
+
+    return "\n".join(fm_lines) + "\n" + "\n".join(body_lines) + "\n"

mneme_code/cli.py

@@ -0,0 +1,174 @@
+"""Command-line interface for mneme-code.
+
+Subcommands
+-----------
+parse-trace [--input FILE] [--vault VAULT_ROOT] [--write] [--source LABEL]
+            [--branch NAME | --no-branch]
+    Read a CPython traceback from --input (or stdin), parse it, print a
+    redacted structured summary to stdout.  With --write, write the
+    failure_to_markdown output into
+    ``<vault>/code-failures/<failure_id>.md`` via atomic_write_text.
+    Branch-aware: the note records the vault's current git branch
+    (explicit --branch wins; --no-branch disables auto-detection).
+
+No new dependencies: argparse only (stdlib).
+
+Redaction invariant: all content is redacted by parse_traceback before
+any output or write.  The CLI may call ``datetime.now(UTC)`` — the library
+functions never do.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+
+from mneme_code.failure import failure_from_traceback, failure_to_markdown
+from mneme_code.stacktrace import parse_traceback
+
+
+def _cmd_parse_trace(args: argparse.Namespace) -> int:
+    """Implementation of the ``parse-trace`` subcommand.
+
+    Returns an exit code (0 = success, 1 = not a traceback / error).
+    """
+    # Read input.
+    input_path: str | None = getattr(args, "input", None)
+    if input_path is not None:
+        try:
+            text = Path(input_path).read_text(encoding="utf-8")
+        except OSError as exc:
+            print(f"mneme-code: cannot read input file: {exc}", file=sys.stderr)
+            return 1
+    else:
+        text = sys.stdin.read()
+
+    # Parse (redaction happens inside parse_traceback).
+    parsed = parse_traceback(text)
+    if parsed is None:
+        print("not a recognizable traceback", file=sys.stderr)
+        return 1
+
+    # Inject observed_at at the CLI boundary — the library stays pure.
+    observed_at = datetime.now(UTC)
+    source_label: str | None = getattr(args, "source", None)
+
+    failure = failure_from_traceback(parsed, observed_at=observed_at, source_label=source_label)
+
+    # Print redacted summary.
+    print(f"failure_id:   {failure.failure_id}")
+    print(f"exc_type:     {failure.exc_type}")
+    print(f"exc_message:  {failure.exc_message}")
+    print(f"frames:       {len(failure.frames)}")
+    print(f"content_hash: {failure.content_hash}")
+    if failure.source_label is not None:
+        print(f"source_label: {failure.source_label}")
+    for i, frame in enumerate(failure.frames):
+        print(f"  [{i}] {frame.file_path}:{frame.line} in {frame.function}")
+
+    # Optional vault write.
+    write: bool = getattr(args, "write", False)
+    vault_raw: str | None = getattr(args, "vault", None)
+    if write:
+        if vault_raw is None:
+            print("mneme-code: --write requires --vault", file=sys.stderr)
+            return 1
+        vault_root = Path(vault_raw).resolve()
+        out_dir = vault_root / "code-failures"
+        out_path = out_dir / f"{failure.failure_id}.md"
+        # Branch-aware failure tracking: explicit --branch wins, otherwise
+        # auto-detect from the vault's git checkout. Metadata only — the
+        # failure_id and content_hash stay branch-independent.
+        branch: str | None = getattr(args, "branch", None)
+        if branch is None and not getattr(args, "no_branch", False):
+            branch = _detect_git_branch(vault_root)
+        note = failure_to_markdown(failure, branch=branch)
+        try:
+            from mneme_core.vault.atomic_write import atomic_write_text
+
+            out_dir.mkdir(parents=True, exist_ok=True)
+            atomic_write_text(out_path, note)
+            print(f"written: {out_path}")
+        except Exception as exc:  # noqa: BLE001
+            print(f"mneme-code: write failed: {exc}", file=sys.stderr)
+            return 1
+
+    return 0
+
+
+def _detect_git_branch(vault_root: Path) -> str | None:
+    """Current git branch of *vault_root*, or ``None`` outside a checkout."""
+    import subprocess
+
+    try:
+        proc = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            cwd=str(vault_root),
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    name = proc.stdout.strip()
+    return name if proc.returncode == 0 and name else None
+
+
+def main() -> None:
+    """Entry point for the mneme-code console script."""
+    parser = argparse.ArgumentParser(
+        prog="mneme-code",
+        description="mneme-code: deterministic Python code-failure memory layer.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # parse-trace subcommand
+    pt = subparsers.add_parser(
+        "parse-trace",
+        help="Parse a CPython traceback and print a redacted summary.",
+    )
+    pt.add_argument(
+        "--input",
+        metavar="FILE",
+        default=None,
+        help="Path to a file containing the traceback text (default: stdin).",
+    )
+    pt.add_argument(
+        "--vault",
+        metavar="VAULT_ROOT",
+        default=None,
+        help="Vault root directory (required with --write).",
+    )
+    pt.add_argument(
+        "--write",
+        action="store_true",
+        default=False,
+        help="Write the failure note into <vault>/code-failures/<failure_id>.md.",
+    )
+    pt.add_argument(
+        "--source",
+        metavar="LABEL",
+        default=None,
+        help="Optional source label (e.g. 'ci-run-42').",
+    )
+    pt.add_argument(
+        "--branch",
+        metavar="NAME",
+        default=None,
+        help="Git branch recorded in the note (default: auto-detect).",
+    )
+    pt.add_argument(
+        "--no-branch",
+        action="store_true",
+        default=False,
+        help="Disable branch auto-detection.",
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "parse-trace":
+        sys.exit(_cmd_parse_trace(args))

mneme_code/failure.py

@@ -0,0 +1,175 @@
+"""FailureMemory dataclass and vault-ready markdown serialization.
+
+Provenance invariant: every ``FailureMemory`` carries:
+    failure_id    — deterministic UUID5 derived from exc_type + first frame + source_label.
+    content_hash  — sha256 hex of a canonical redacted text rendering.
+    observed_at   — injected by caller; never produced inside this module.
+    trust         — default ``"user"`` (operator-supplied traceback).
+    confidence    — default ``"EXTRACTED"`` (directly observed, no inference).
+
+All string content on the incoming ``ParsedTraceback`` has already been
+redacted by ``mneme_code.stacktrace.parse_traceback``; this module does
+not re-apply redaction but must not introduce new unredacted content.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from mneme_core.privacy import redact
+
+from mneme_code.stacktrace import Frame, ParsedTraceback
+
+
+@dataclass(frozen=True)
+class FailureMemory:
+    """A provenance-labelled, redacted record of one Python failure.
+
+    Attributes:
+        failure_id    Deterministic UUID5 (namespace URL) derived from
+                      ``exc_type``, first frame coordinates, and
+                      ``source_label``.
+        exc_type      Exception class name (already redacted upstream).
+        exc_message   Redacted exception message.
+        frames        Redacted stack frames, innermost last.
+        observed_at   Tz-aware UTC datetime injected by the caller.
+        source_label  Optional human label identifying the failure source
+                      (e.g. ``"ci-run-42"``).
+        content_hash  SHA-256 hex of a canonical redacted rendering.
+        trust         Provenance tier; default ``"user"``.
+        confidence    Confidence label; default ``"EXTRACTED"``.
+    """
+
+    failure_id: str
+    exc_type: str
+    exc_message: str
+    frames: tuple[Frame, ...]
+    observed_at: datetime
+    source_label: str | None
+    content_hash: str
+    trust: str = field(default="user")
+    confidence: str = field(default="EXTRACTED")
+
+
+def failure_from_traceback(
+    parsed: ParsedTraceback,
+    *,
+    observed_at: datetime,
+    source_label: str | None = None,
+) -> FailureMemory:
+    """Construct a :class:`FailureMemory` from a parsed, redacted traceback.
+
+    Args:
+        parsed:       Already-redacted :class:`ParsedTraceback` from
+                      ``parse_traceback``.
+        observed_at:  Tz-aware UTC datetime for this failure observation.
+                      Must be injected by the caller; this function never
+                      calls ``datetime.now()``.
+        source_label: Optional label for the failure source.
+
+    Returns:
+        A deterministic :class:`FailureMemory` — same inputs always
+        produce the same ``failure_id`` and ``content_hash``.
+    """
+    first_frame = parsed.frames[0] if parsed.frames else Frame("", 0, "", None)
+    label_part = source_label or ""
+
+    # Deterministic UUID5: namespace URL + canonical key.
+    key = f"{parsed.exc_type}\x00{first_frame.file_path}:{first_frame.line}\x00{label_part}"
+    failure_id = str(uuid.uuid5(uuid.NAMESPACE_URL, key))
+
+    # Canonical text for content_hash: all already-redacted fields.
+    canonical = _canonical_text(parsed, source_label)
+    content_hash = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+    return FailureMemory(
+        failure_id=failure_id,
+        exc_type=parsed.exc_type,
+        exc_message=parsed.exc_message,
+        frames=parsed.frames,
+        observed_at=observed_at,
+        source_label=source_label,
+        content_hash=content_hash,
+    )
+
+
+def failure_to_markdown(failure: FailureMemory, *, branch: str | None = None) -> str:
+    """Render a :class:`FailureMemory` as a vault-ready markdown note.
+
+    Frontmatter fields:
+        id            failure.failure_id
+        type          ``"failure"``
+        created       failure.observed_at as tz-aware UTC ISO 8601 with microseconds
+        tags          ``["failure"]``
+        exc_type      failure.exc_type
+        source_label  failure.source_label (omitted when ``None``)
+        branch        caller-supplied git branch (omitted when ``None``);
+                      metadata only — it never participates in failure_id
+                      or content_hash, so determinism is preserved
+
+    Body: redacted summary — exception message followed by frame list
+    (``file:line in func`` format).
+
+    All content is already redacted upstream; this function does not
+    re-apply redaction.
+    """
+    # Build frontmatter manually to control field order and avoid yaml import.
+    # Normalise observed_at to tz-aware UTC so `created` is consistent with the
+    # rest of mneme regardless of the caller's tz (mirrors the temporal layer).
+    observed = failure.observed_at
+    observed = observed.replace(tzinfo=UTC) if observed.tzinfo is None else observed.astimezone(UTC)
+    created_str = observed.isoformat(timespec="microseconds")
+    fm_lines = [
+        "---",
+        f"id: {failure.failure_id}",
+        "type: failure",
+        f"created: {created_str}",
+        "tags:",
+        "  - failure",
+        f"exc_type: {failure.exc_type}",
+    ]
+    if failure.source_label is not None:
+        # JSON-encode so an arbitrary user label stays valid YAML.
+        fm_lines.append(f"source_label: {json.dumps(failure.source_label)}")
+    if branch is not None:
+        # Branch-aware failure tracking: redact then JSON-encode so an
+        # arbitrary branch name stays valid YAML and never leaks a
+        # <private> span embedded in an exotic branch name.
+        fm_lines.append(f"branch: {json.dumps(redact(branch))}")
+    fm_lines.append("---")
+
+    # Body
+    body_lines: list[str] = []
+    body_lines.append(f"# {failure.exc_type}")
+    body_lines.append("")
+    if failure.exc_message:
+        body_lines.append(f"> {failure.exc_message}")
+        body_lines.append("")
+
+    body_lines.append("## Stack frames")
+    body_lines.append("")
+    for frame in failure.frames:
+        body_lines.append(f"- `{frame.file_path}:{frame.line}` in `{frame.function}`")
+
+    return "\n".join(fm_lines) + "\n" + "\n".join(body_lines) + "\n"
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _canonical_text(parsed: ParsedTraceback, source_label: str | None) -> str:
+    """Produce the canonical deterministic text used for content_hash."""
+    parts = [parsed.exc_type, parsed.exc_message]
+    for frame in parsed.frames:
+        parts.append(f"{frame.file_path}:{frame.line}:{frame.function}")
+        if frame.code_context is not None:
+            parts.append(frame.code_context)
+    if source_label is not None:
+        parts.append(source_label)
+    return "\n".join(parts)