runspec-logops-core 0.1.0__tar.gz

runspec_logops_core-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+env/
+.env
+pip-wheel-metadata/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover
+
+# Node
+node_modules/
+dist/
+*.js.map
+.npm
+
+# Go
+*.exe
+*.test
+*.out
+vendor/
+
+# IDE
+.idea/
+.vscode/
+*.iml
+*.iws
+*.ipr
+.DS_Store
+Thumbs.db
+
+# Docs
+site/
+
+# Misc
+*.log
+*.tmp
+
+# External reference repos (cloned locally, not committed)
+chainlit-docs/
+.chainlit/
+
+# Claude Code local config (machine-specific)
+.claude/launch.json
+
+# Stray committed test venv (removed from tracking)
+.venv-test/

runspec_logops_core-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# runspec-logops-core Changelog
+
+## [0.1.0] — 2026-06-18
+
+Initial release.
+
+The pure-Python logic core behind `runspec-logops`. Provides log-condensing and
+code-mapping helpers as plain importable functions — **no dependency on
+`runspec`, no `runspec.toml`, no console-script entry points** — so a package can
+`from runspec_logops_core import summarize_log` (and the rest) without surfacing
+any runnables in the venv or in `runspec local` / `runspec serve` discovery. This
+is the corporate-facing deliverable: wrap it in a private package, bake in
+corporate defaults as plain params, and ship your own runnables.
+
+Each function returns plain data and *raises* on failure (`SourceNotFoundError`
+when an input path is missing); wrappers catch these and render the JSON/exit
+behaviour.
+
+Exports:
+
+- **Signatures** — `normalize_line`, `error_signature`, `detect_level` (pure
+  line/event shaping for cheap clustering)
+- **Digest** — `summarize_log` (streams a log, clusters by signature, returns a
+  bounded top-N digest whose size is independent of input size)
+- **Code map** — `map_trace_to_sources` (resolves a stack trace / signature to the
+  few relevant source snippets in a checkout)
+- **Bundle** — `build_bundle` (zips digest + snippets + manifest for transfer)
+- **Errors** — `LogopsCoreError`, `SourceNotFoundError`

runspec_logops_core-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: runspec-logops-core
+Version: 0.1.0
+Summary: Pure-Python log-condensing + code-mapping helpers — the importable core behind runspec-logops (no runspec dependency, no runnables)
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'

runspec_logops_core-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runspec-logops-core"
+version = "0.1.0"
+requires-python = ">=3.10"
+description = "Pure-Python log-condensing + code-mapping helpers — the importable core behind runspec-logops (no runspec dependency, no runnables)"
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "ruff",
+    "mypy",
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+
+[tool.ruff]
+line-length = 200
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

runspec_logops_core-0.1.0/runspec_logops_core/__init__.py

@@ -0,0 +1,35 @@
+"""runspec-logops-core — pure-Python log-condensing + code-mapping helpers.
+
+This package has **no dependency on runspec** and ships **no runspec.toml and no
+entry points**, so installing it exposes the helper functions for import without
+surfacing any runnables (it is invisible to ``runspec local`` / ``runspec serve``
+discovery). ``runspec-logops`` depends on it and wraps each helper in a runnable;
+a private (e.g. Nexus-hosted) package can instead import these helpers directly,
+bake in corporate defaults/paths as plain params, and ship its own runnables —
+so only the wrapped runnables ever surface in the venv.
+
+Each function returns plain data and *raises* on failure (see
+``runspec_logops_core.errors``).
+"""
+
+from runspec_logops_core.bundle import build_bundle
+from runspec_logops_core.codemap import map_trace_to_sources
+from runspec_logops_core.digest import summarize_log
+from runspec_logops_core.errors import LogopsCoreError, SourceNotFoundError
+from runspec_logops_core.signatures import detect_level, error_signature, normalize_line
+
+__all__ = [
+    # errors
+    "LogopsCoreError",
+    "SourceNotFoundError",
+    # signatures
+    "normalize_line",
+    "error_signature",
+    "detect_level",
+    # digest
+    "summarize_log",
+    # codemap
+    "map_trace_to_sources",
+    # bundle
+    "build_bundle",
+]

runspec_logops_core-0.1.0/runspec_logops_core/bundle.py

@@ -0,0 +1,48 @@
+"""Bundle a digest + code map + metadata into one small zip for transfer.
+
+The console's existing ``download_file`` agent tool then pulls this single small
+artifact to local — the whole log and whole repo never transit the network.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import zipfile
+from datetime import datetime
+
+
+def build_bundle(digest: dict, code_map: dict | None, *, dest_dir: str, metadata: dict | None = None) -> dict:
+    """Write ``digest.json`` (+ ``snippets.json`` + ``manifest.json``) into one zip.
+
+    Returns the ``backup_files``-style ``{destination, size_bytes, size_mb,
+    contents}``. Creates ``dest_dir`` if needed; propagates :class:`OSError` on
+    write failure.
+    """
+    os.makedirs(dest_dir, exist_ok=True)
+    timestamp = datetime.now().strftime("%Y%m%dT%H%M%S")
+    archive_path = os.path.join(dest_dir, f"logops_digest_{timestamp}.zip")
+
+    manifest = {
+        "generated_at": datetime.now().isoformat(),
+        "log_file": digest.get("file"),
+        "distinct_signatures": digest.get("distinct_signatures"),
+        "has_code_map": code_map is not None,
+        **(metadata or {}),
+    }
+
+    contents = ["digest.json", "manifest.json"]
+    with zipfile.ZipFile(archive_path, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        zf.writestr("digest.json", json.dumps(digest, indent=2))
+        zf.writestr("manifest.json", json.dumps(manifest, indent=2))
+        if code_map is not None:
+            zf.writestr("snippets.json", json.dumps(code_map, indent=2))
+            contents.append("snippets.json")
+
+    size_bytes = os.path.getsize(archive_path)
+    return {
+        "destination": archive_path,
+        "size_bytes": size_bytes,
+        "size_mb": round(size_bytes / 1_048_576, 2),
+        "contents": contents,
+    }

runspec_logops_core-0.1.0/runspec_logops_core/codemap.py

@@ -0,0 +1,158 @@
+"""Map a stack trace (or a digest signature) to the few relevant source snippets.
+
+Given a trace and the local git checkout, ``map_trace_to_sources`` extracts the
+referenced frames, resolves each to a file in the checkout, and returns only the
+±context window around each frame's line — capped at ``max_files`` frames and
+``max_total_lines`` total. The agent gets the handful of lines that matter, never
+the repo. Resolution is plain filesystem (``os.walk``); no ``git`` is required.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+
+from runspec_logops_core.errors import SourceNotFoundError
+
+_IGNORE_DIRS = {".git", "node_modules", "__pycache__", ".venv", "venv", ".mypy_cache", ".tox", "dist", "build", ".idea"}
+
+# Frame shapes across runtimes.
+_PY = re.compile(r'File\s+"([^"]+)",\s+line\s+(\d+),\s+in\s+(\S+)')
+_JAVA = re.compile(r"at\s+([\w.$]+)\(([^()\s:]+):(\d+)\)")
+_JS = re.compile(r"at\s+(?:([\w.$<>]+)\s+)?\(?((?:/|\./|\w:|[\w.\-]+/)[\w./\-]*\.[a-zA-Z]+):(\d+):\d+\)?")
+_GENERIC = re.compile(r"\b([\w./\-]+\.[a-zA-Z]{1,5}):(\d+)\b")
+_CAPWORD = re.compile(r"^[A-Z]\w+$")
+
+
+def _frames_from_trace(trace: str) -> list[tuple[str | None, int | None, str | None]]:
+    """Extract ``(file_hint, lineno, symbol)`` candidates from a raw trace."""
+    out: list[tuple[str | None, int | None, str | None]] = []
+    seen: set[tuple] = set()
+
+    def add(file_hint: str | None, lineno: int | None, symbol: str | None) -> None:
+        # Dedup by (basename, line) when a line is known — so the generic
+        # ``file:line`` catch-all doesn't re-add a frame a typed regex already
+        # captured with its symbol. Symbol-only frames key on the symbol instead.
+        key = ("L", os.path.basename(file_hint) if file_hint else None, lineno) if lineno is not None else ("S", file_hint, symbol)
+        if key not in seen:
+            seen.add(key)
+            out.append((file_hint, lineno, symbol))
+
+    for m in _PY.finditer(trace):
+        add(m.group(1), int(m.group(2)), m.group(3))
+    for m in _JAVA.finditer(trace):
+        add(m.group(2), int(m.group(3)), m.group(1))
+    for m in _JS.finditer(trace):
+        add(m.group(2), int(m.group(3)), m.group(1))
+    for m in _GENERIC.finditer(trace):
+        add(m.group(1), int(m.group(2)), None)
+    return out
+
+
+def _frames_from_signature(trace: str) -> list[tuple[str | None, int | None, str | None]]:
+    """Extract frames from a digest signature like ``Exc@com.acme.OrderSvc.price``."""
+    if "@" not in trace:
+        return []
+    out: list[tuple[str | None, int | None, str | None]] = []
+    for frame in trace.split("@", 1)[1].split(">"):
+        frame = frame.strip()
+        if not frame:
+            continue
+        parts = frame.split(".")
+        cls = next((p for p in reversed(parts) if _CAPWORD.match(p)), None)
+        method = parts[-1] if parts else None
+        out.append((cls, None, method))
+    return out
+
+
+def _find_file(repo_root: str, file_hint: str) -> str | None:
+    """Resolve ``file_hint`` to a path under ``repo_root`` (exact rel path, then basename)."""
+    exact = os.path.join(repo_root, file_hint)
+    if os.path.isfile(exact):
+        return exact
+    target = os.path.basename(file_hint)
+    for dirpath, dirs, files in os.walk(repo_root):
+        dirs[:] = [d for d in dirs if d not in _IGNORE_DIRS]
+        if target in files:
+            return os.path.join(dirpath, target)
+    return None
+
+
+def _find_class_file(repo_root: str, cls: str) -> str | None:
+    """Find a file whose stem equals the class name (e.g. ``OrderSvc`` → OrderSvc.java)."""
+    for dirpath, dirs, files in os.walk(repo_root):
+        dirs[:] = [d for d in dirs if d not in _IGNORE_DIRS]
+        for name in files:
+            if os.path.splitext(name)[0] == cls:
+                return os.path.join(dirpath, name)
+    return None
+
+
+def _symbol_line(lines: list[str], symbol: str) -> int | None:
+    """Return the 1-based line number where ``symbol`` is defined/first referenced."""
+    needles = (f"def {symbol}", f"{symbol}(", f" {symbol} ", f".{symbol}")
+    for i, line in enumerate(lines, start=1):
+        if any(n in line for n in needles):
+            return i
+    return None
+
+
+def _snippet(path: str, lineno: int, context: int) -> list[str]:
+    """Return ``lineno`` ±context as ``"<n>: <text>"`` strings (no trailing newline)."""
+    with open(path, errors="replace") as fh:
+        lines = fh.read().splitlines()
+    start = max(0, lineno - context - 1)
+    end = min(len(lines), lineno + context)
+    return [f"{i + 1}: {lines[i]}" for i in range(start, end)]
+
+
+def map_trace_to_sources(
+    repo_root: str,
+    trace: str,
+    *,
+    context: int = 8,
+    max_files: int = 5,
+    max_total_lines: int = 200,
+) -> dict:
+    """Resolve the frames in ``trace`` to source snippets in ``repo_root``.
+
+    Raises :class:`SourceNotFoundError` if ``repo_root`` is not a directory.
+    """
+    if not os.path.isdir(repo_root):
+        raise SourceNotFoundError(f"repo checkout not found: {repo_root}")
+
+    candidates = _frames_from_trace(trace) or _frames_from_signature(trace)
+
+    frames: list[dict] = []
+    total_lines = 0
+    for file_hint, lineno, symbol in candidates:
+        if len(frames) >= max_files or total_lines >= max_total_lines:
+            break
+
+        path: str | None = None
+        if file_hint and ("/" in file_hint or "." in file_hint and lineno is not None):
+            path = _find_file(repo_root, file_hint)
+        if path is None and file_hint:
+            path = _find_class_file(repo_root, os.path.splitext(os.path.basename(file_hint))[0])
+        if path is None:
+            continue
+
+        resolved_line = lineno
+        if resolved_line is None and symbol:
+            with open(path, errors="replace") as fh:
+                resolved_line = _symbol_line(fh.read().splitlines(), symbol)
+        if resolved_line is None:
+            continue
+
+        snippet = _snippet(path, resolved_line, context)
+        room = max(0, max_total_lines - total_lines)
+        snippet = snippet[:room]
+        total_lines += len(snippet)
+        frames.append({"file": os.path.relpath(path, repo_root), "lineno": resolved_line, "symbol": symbol, "snippet": snippet})
+
+    return {
+        "repo": repo_root,
+        "frames": frames,
+        "files_matched": len(frames),
+        "truncated": len(frames) < len(candidates),
+    }

runspec_logops_core-0.1.0/runspec_logops_core/digest.py

@@ -0,0 +1,167 @@
+"""Condense a noisy log into a small, bounded digest.
+
+``summarize_log`` streams a file line-by-line (it never loads the whole file),
+groups continuation/stack lines into events, clusters events by
+:func:`signatures.error_signature`, and returns only the top-N distinct
+signatures with counts, first/last timestamp and one truncated sample each. The
+returned dict's size is bounded by ``top`` × ``max_sample_lines`` × ``max_bytes``
+— independent of how big the input log is. That bound is the whole point: the
+agent reads the digest, never the log.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from datetime import datetime, timedelta
+
+from runspec_logops_core.errors import SourceNotFoundError
+from runspec_logops_core.signatures import detect_level, error_signature
+
+_LEVEL_FLOOR = {"all": 0, "warning": 2, "error": 3, "critical": 4}
+
+# Leading ISO timestamp captured for window filtering (syslog has no year, so it
+# is intentionally left for the no-op path).
+_ISO_TS = re.compile(r"^\s*\[?(\d{4}-\d{2}-\d{2})[ T](\d{2}:\d{2}:\d{2})(?:[.,]\d+)?")
+_REL = re.compile(r"^\s*(\d+)\s*([a-z]+?)s?(?:\s+ago)?\s*$", re.IGNORECASE)
+_UNIT = {"s": "seconds", "sec": "seconds", "second": "seconds", "m": "minutes", "min": "minutes", "minute": "minutes", "h": "hours", "hour": "hours", "hr": "hours", "d": "days", "day": "days"}
+
+# A line that continues the previous event rather than starting a new one.
+_CONT = re.compile(r"^\s+|^(?:at\s|Caused by:|\.{3}|File\s\")", re.IGNORECASE)
+
+
+def _parse_dt(text: str) -> datetime | None:
+    """Best-effort parse of an ISO-ish ``YYYY-MM-DD[ T]HH:MM:SS`` string (naive)."""
+    try:
+        return datetime.fromisoformat(text)
+    except ValueError:
+        return None
+
+
+def _parse_line_ts(line: str) -> datetime | None:
+    """Extract a leading ISO timestamp from a log line, or None."""
+    m = _ISO_TS.match(line)
+    if not m:
+        return None
+    return _parse_dt(f"{m.group(1)} {m.group(2)}")
+
+
+def _parse_when(value: str | None) -> datetime | None:
+    """Parse a user-supplied window bound: ISO, ``now``, or ``<n> <unit> ago``."""
+    if not value:
+        return None
+    v = value.strip()
+    if v.lower() == "now":
+        return datetime.now()
+    rel = _REL.match(v)
+    if rel:
+        unit = _UNIT.get(rel.group(2).lower())
+        if unit:
+            return datetime.now() - timedelta(**{unit: int(rel.group(1))})
+    iso = _parse_dt(v.replace("Z", "").replace("T", " ").strip())
+    return iso
+
+
+def _is_continuation(line: str) -> bool:
+    return bool(line) and bool(_CONT.match(line))
+
+
+def _iter_events(path: str):
+    """Yield ``(block_lines, first_ts)`` events, streaming the file.
+
+    An event is a leading (non-indented) line plus the indented / stack-frame
+    lines that follow it. ``lines_scanned`` is tracked by the caller.
+    """
+    block: list[str] = []
+    block_ts: datetime | None = None
+    with open(path, errors="replace") as fh:
+        for raw in fh:
+            line = raw.rstrip("\n")
+            if block and _is_continuation(line):
+                block.append(line)
+                continue
+            if block:
+                yield block, block_ts
+            block = [line]
+            block_ts = _parse_line_ts(line)
+    if block:
+        yield block, block_ts
+
+
+def summarize_log(
+    path: str,
+    *,
+    level: str | None = None,
+    since: str | None = None,
+    until: str | None = None,
+    top: int = 10,
+    max_sample_lines: int = 20,
+    max_bytes: int = 200,
+) -> dict:
+    """Return a bounded digest of ``path`` clustered by error signature.
+
+    Raises :class:`SourceNotFoundError` if the file does not exist; propagates
+    :class:`OSError` on other read failures.
+    """
+    if not os.path.exists(path):
+        raise SourceNotFoundError(f"log file not found: {path}")
+
+    floor = _LEVEL_FLOOR.get((level or "all").lower(), 0)
+    since_dt, until_dt = _parse_when(since), _parse_when(until)
+
+    groups: dict[str, dict] = {}
+    lines_scanned = 0
+    total_events = 0
+
+    for block, ts in _iter_events(path):
+        lines_scanned += len(block)
+
+        if (since_dt and ts and ts < since_dt) or (until_dt and ts and ts > until_dt):
+            continue
+
+        sig = error_signature(block)
+        # Event level = highest severity seen on any line; an exception-bearing
+        # event with no explicit level counts as "error".
+        ranks = [_LEVEL_FLOOR.get(detect_level(ln) or "", 0) for ln in block]
+        rank = max(ranks) if ranks else 0
+        if rank == 0 and "@" in sig:
+            rank = 3
+        if rank < floor:
+            continue
+
+        total_events += 1
+        g = groups.get(sig)
+        if g is None:
+            sample = [ln[:max_bytes] for ln in block[:max_sample_lines]]
+            groups[sig] = {"signature": sig, "level_rank": rank, "count": 1, "first_ts": ts, "last_ts": ts, "sample": sample}
+        else:
+            g["count"] += 1
+            g["level_rank"] = max(g["level_rank"], rank)
+            if ts:
+                if g["first_ts"] is None or ts < g["first_ts"]:
+                    g["first_ts"] = ts
+                if g["last_ts"] is None or ts > g["last_ts"]:
+                    g["last_ts"] = ts
+
+    ranked = sorted(groups.values(), key=lambda g: g["count"], reverse=True)
+    rank_name = {0: "info", 2: "warning", 3: "error", 4: "critical"}
+    top_list = [
+        {
+            "signature": g["signature"],
+            "level": rank_name.get(g["level_rank"], "info"),
+            "count": g["count"],
+            "first_ts": g["first_ts"].isoformat() if g["first_ts"] else None,
+            "last_ts": g["last_ts"].isoformat() if g["last_ts"] else None,
+            "sample": g["sample"],
+        }
+        for g in ranked[:top]
+    ]
+
+    return {
+        "file": path,
+        "window": {"since": since, "until": until, "lines_scanned": lines_scanned},
+        "total_events": total_events,
+        "distinct_signatures": len(groups),
+        "truncated": len(groups) > top,
+        "top": top_list,
+    }

runspec_logops_core-0.1.0/runspec_logops_core/errors.py

@@ -0,0 +1,15 @@
+"""Exception types raised by the pure helper functions.
+
+The functions in this package do the work and *raise* on failure; the thin
+runnable wrappers in ``runspec-logops`` (and any private wrapper that imports the
+helpers) catch these and turn them into the JSON error payloads + non-zero exits
+that the CLI/agent surface expects.
+"""
+
+
+class LogopsCoreError(Exception):
+    """Base class for all runspec-logops-core failures."""
+
+
+class SourceNotFoundError(LogopsCoreError):
+    """A required input path (the log file or the repo checkout) does not exist."""

runspec_logops_core-0.1.0/runspec_logops_core/signatures.py

@@ -0,0 +1,138 @@
+"""Pure, I/O-free line normalisation and event-signature extraction.
+
+This is what makes log condensing cheap: collapse the *variable* parts of a log
+line (timestamps, ids, addresses, numbers, quoted literals) into a stable
+"shape" so that thousands of near-identical lines fold onto one signature. For a
+multi-line stack trace, the signature is the exception class plus the top normalised
+frames, so the same failure clusters regardless of the surrounding noise.
+
+Nothing here reads files or the clock — every function is a deterministic pure
+transform, which is what the unit tests pin.
+"""
+
+from __future__ import annotations
+
+import re
+
+# --- pieces of a line that vary run-to-run and must be masked for clustering ---
+_UUID = re.compile(r"\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b")
+_HEX = re.compile(r"\b0x[0-9a-fA-F]+\b")
+_LONGHEX = re.compile(r"\b[0-9a-fA-F]{16,}\b")
+# A hex-ish id (request id, short hash): >=4 chars, mixing at least one digit and
+# one a-f letter — masks ``7f3a``/``0a1b`` while leaving plain words alone.
+_HEXID = re.compile(r"\b(?=[0-9a-fA-F]*[0-9])(?=[0-9a-fA-F]*[a-fA-F])[0-9a-fA-F]{4,}\b")
+_QUOTED = re.compile(r"""(['"]).*?\1""")
+_NUM = re.compile(r"\d+")  # any digit run, incl. unit-glued (412ms) — masked last
+_WS = re.compile(r"\s+")
+
+# A leading timestamp: ISO (``2026-06-18T08:01:11`` / ``... 08:01:11,123``),
+# bracketed (``[2026-06-18 08:01:11]``), or syslog (``Jun 18 08:01:11``).
+_LEADING_TS = re.compile(
+    r"""^\s*
+    (?:
+        \[?\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}(?:[.,]\d+)?(?:Z|[+-]\d{2}:?\d{2})?\]?
+      | [A-Z][a-z]{2}\s+\d{1,2}\s+\d{2}:\d{2}:\d{2}
+    )
+    \s*""",
+    re.VERBOSE,
+)
+
+# Common severity tokens, mapped to an ordered rank.
+_LEVELS = {
+    "DEBUG": 0,
+    "TRACE": 0,
+    "INFO": 1,
+    "NOTICE": 1,
+    "WARN": 2,
+    "WARNING": 2,
+    "ERROR": 3,
+    "ERR": 3,
+    "SEVERE": 3,
+    "CRITICAL": 4,
+    "CRIT": 4,
+    "FATAL": 4,
+}
+_LEVEL_RANK = {"all": 0, "debug": 0, "info": 1, "warning": 2, "error": 3, "critical": 4}
+_LEVEL_TOKEN = re.compile(r"\b(DEBUG|TRACE|INFO|NOTICE|WARN(?:ING)?|ERR(?:OR)?|SEVERE|CRIT(?:ICAL)?|FATAL)\b")
+
+# An exception/error class name, e.g. ``NullPointerException`` / ``ValueError``.
+_EXC = re.compile(r"\b([A-Za-z_][\w.]*(?:Error|Exception|Failure|Fault))\b")
+
+# Stack-frame patterns across common runtimes.
+_FRAME_JAVA = re.compile(r"\bat\s+([\w.$]+)\s*\(")  # at com.acme.Foo.bar(Foo.java:42)
+_FRAME_PY = re.compile(r'File\s+"[^"]+",\s+line\s+\d+,\s+in\s+(\S+)')  # File "x.py", line 5, in foo
+_FRAME_JS = re.compile(r"\bat\s+([\w.$<>]+)\s*\(")  # at Object.fn (/a/b.js:1:2)
+
+
+def strip_timestamp(line: str) -> str:
+    """Remove a leading timestamp prefix from ``line`` (no-op when absent)."""
+    return _LEADING_TS.sub("", line, count=1)
+
+
+def detect_level(line: str) -> str | None:
+    """Return the canonical severity name found in ``line`` (e.g. ``"error"``), or None."""
+    m = _LEVEL_TOKEN.search(line)
+    if not m:
+        return None
+    token = m.group(1).upper()
+    rank = _LEVELS[token]
+    # Map the rank back to a canonical name used by the level filter.
+    for name, r in _LEVEL_RANK.items():
+        if name != "all" and r == rank:
+            return name
+    return None
+
+
+def normalize_line(line: str) -> str:
+    """Collapse the variable parts of a single log line into a stable shape.
+
+    Masks (in order) the leading timestamp, UUIDs, hex addresses, long hex
+    blobs, quoted literals and bare integers, then squeezes whitespace. Two lines
+    that differ only in those volatile parts return the same string.
+    """
+    s = strip_timestamp(line)
+    s = _UUID.sub("<uuid>", s)
+    s = _HEX.sub("<hex>", s)
+    s = _LONGHEX.sub("<hex>", s)
+    s = _HEXID.sub("<hex>", s)
+    s = _QUOTED.sub("<str>", s)
+    s = _NUM.sub("<n>", s)
+    return _WS.sub(" ", s).strip()
+
+
+def _frames(block: list[str], max_frames: int = 3) -> list[str]:
+    """Extract up to ``max_frames`` normalised stack frames from an event block."""
+    out: list[str] = []
+    for raw in block:
+        for pat in (_FRAME_PY, _FRAME_JAVA, _FRAME_JS):
+            m = pat.search(raw)
+            if m:
+                out.append(m.group(1))
+                break
+        if len(out) >= max_frames:
+            break
+    return out
+
+
+def error_signature(block: list[str], max_frames: int = 3) -> str:
+    """Return a short, stable signature for an event (one or more lines).
+
+    For a stack trace: ``<ExceptionClass>@<frame1>>major<frame2>...`` using the
+    first exception class seen and the top normalised frames — so the same crash
+    clusters regardless of message text or addresses. For a plain line with no
+    exception/frames, falls back to the normalised first line (truncated).
+    """
+    if not block:
+        return ""
+    exc: str | None = None
+    for raw in block:
+        m = _EXC.search(raw)
+        if m:
+            exc = m.group(1).rsplit(".", 1)[-1]  # bare class name
+            break
+    frames = _frames(block, max_frames=max_frames)
+    if exc or frames:
+        head = exc or "error"
+        return head + "@" + ">".join(frames) if frames else head
+    # Plain line — normalised shape is the signature.
+    return normalize_line(block[0])[:200]

runspec_logops_core-0.1.0/tests/test_bundle.py

@@ -0,0 +1,28 @@
+"""build_bundle writes one small zip with the expected members."""
+
+import json
+import zipfile
+
+from runspec_logops_core import build_bundle
+
+
+def test_bundle_contains_digest_and_manifest(tmp_path) -> None:
+    digest = {"file": "/var/log/app.log", "distinct_signatures": 3, "top": []}
+    res = build_bundle(digest, None, dest_dir=str(tmp_path), metadata={"host": "prod-1"})
+
+    assert res["destination"].endswith(".zip")
+    assert res["size_bytes"] > 0
+    assert set(res["contents"]) == {"digest.json", "manifest.json"}
+
+    with zipfile.ZipFile(res["destination"]) as zf:
+        assert json.loads(zf.read("digest.json"))["distinct_signatures"] == 3
+        manifest = json.loads(zf.read("manifest.json"))
+        assert manifest["host"] == "prod-1"
+        assert manifest["has_code_map"] is False
+
+
+def test_bundle_includes_snippets_when_code_map_present(tmp_path) -> None:
+    res = build_bundle({"file": "x"}, {"frames": [], "files_matched": 0}, dest_dir=str(tmp_path))
+    assert "snippets.json" in res["contents"]
+    with zipfile.ZipFile(res["destination"]) as zf:
+        assert "snippets.json" in zf.namelist()

runspec_logops_core-0.1.0/tests/test_codemap.py

@@ -0,0 +1,54 @@
+"""map_trace_to_sources resolves frames to bounded source snippets."""
+
+import pytest
+
+from runspec_logops_core import map_trace_to_sources
+from runspec_logops_core.errors import SourceNotFoundError
+
+
+def test_missing_repo_raises(tmp_path) -> None:
+    with pytest.raises(SourceNotFoundError):
+        map_trace_to_sources(str(tmp_path / "nope"), "trace")
+
+
+def test_python_traceback_to_snippet(tmp_path) -> None:
+    src = tmp_path / "app.py"
+    src.write_text("\n".join(f"line {i}" for i in range(1, 21)) + "\n")
+    trace = 'Traceback:\n  File "app.py", line 10, in handler\nValueError: x'
+
+    res = map_trace_to_sources(str(tmp_path), trace, context=2)
+    assert res["files_matched"] == 1
+    frame = res["frames"][0]
+    assert frame["file"] == "app.py"
+    assert frame["lineno"] == 10
+    assert any("10: line 10" in s for s in frame["snippet"])
+    # ±2 context → at most 5 lines.
+    assert len(frame["snippet"]) <= 5
+
+
+def test_basename_search_when_path_not_exact(tmp_path) -> None:
+    pkg = tmp_path / "src" / "acme"
+    pkg.mkdir(parents=True)
+    (pkg / "OrderSvc.java").write_text("\n".join(f"row {i}" for i in range(1, 100)) + "\n")
+    trace = "Exception\n\tat com.acme.OrderSvc.price(OrderSvc.java:42)"
+
+    res = map_trace_to_sources(str(tmp_path), trace, context=1)
+    assert res["files_matched"] == 1
+    assert res["frames"][0]["file"].endswith("OrderSvc.java")
+    assert res["frames"][0]["lineno"] == 42
+
+
+def test_signature_resolves_by_class_and_symbol(tmp_path) -> None:
+    (tmp_path / "OrderSvc.java").write_text("class OrderSvc {\n  int price() {\n    return 0;\n  }\n}\n")
+    res = map_trace_to_sources(str(tmp_path), "NullPointerException@com.acme.OrderSvc.price", context=1)
+    assert res["files_matched"] == 1
+    assert res["frames"][0]["symbol"] == "price"
+
+
+def test_total_lines_capped(tmp_path) -> None:
+    for n in range(4):
+        (tmp_path / f"f{n}.py").write_text("\n".join(str(i) for i in range(1, 200)) + "\n")
+    trace = "\n".join(f'  File "f{n}.py", line 100, in g' for n in range(4))
+    res = map_trace_to_sources(str(tmp_path), trace, context=10, max_total_lines=15)
+    total = sum(len(f["snippet"]) for f in res["frames"])
+    assert total <= 15

runspec_logops_core-0.1.0/tests/test_digest.py

@@ -0,0 +1,81 @@
+"""summarize_log clusters, bounds its output, filters by level and time window."""
+
+import json
+
+import pytest
+
+from runspec_logops_core import summarize_log
+from runspec_logops_core.errors import SourceNotFoundError
+
+
+def _write(tmp_path, lines):
+    p = tmp_path / "app.log"
+    p.write_text("\n".join(lines) + "\n")
+    return str(p)
+
+
+def test_missing_file_raises(tmp_path) -> None:
+    with pytest.raises(SourceNotFoundError):
+        summarize_log(str(tmp_path / "nope.log"))
+
+
+def test_clusters_repeated_errors(tmp_path) -> None:
+    lines = []
+    for i in range(800):
+        lines.append(f"2026-06-18T08:{i % 60:02d}:11Z ERROR NullPointerException: id={i}")
+        lines.append("\tat com.acme.OrderSvc.price(OrderSvc.java:42)")
+    lines.append("2026-06-18T09:00:00Z INFO started ok")
+    path = _write(tmp_path, lines)
+
+    d = summarize_log(path, top=10)
+    assert d["distinct_signatures"] == 2
+    top = d["top"][0]
+    assert top["count"] == 800
+    assert top["signature"].startswith("NullPointerException@")
+    assert top["level"] == "error"
+    assert top["first_ts"] is not None and top["last_ts"] is not None
+
+
+def test_digest_size_is_bounded_regardless_of_input(tmp_path) -> None:
+    # 50k distinct noisy lines, but top=5 and small sample caps keep the digest tiny.
+    lines = [f"2026-06-18T08:00:00Z ERROR Boom{i % 7}Exception: detail {i}" for i in range(50_000)]
+    path = _write(tmp_path, lines)
+
+    d = summarize_log(path, top=5, max_sample_lines=3, max_bytes=80)
+    assert len(d["top"]) <= 5
+    assert d["truncated"] is True
+    assert d["window"]["lines_scanned"] == 50_000
+    # The whole serialised digest stays small no matter the 50k-line input.
+    assert len(json.dumps(d)) < 4000
+    for grp in d["top"]:
+        assert len(grp["sample"]) <= 3
+        assert all(len(s) <= 80 for s in grp["sample"])
+
+
+def test_level_filter_drops_below_floor(tmp_path) -> None:
+    path = _write(
+        tmp_path,
+        [
+            "2026-06-18T08:00:00Z INFO served ok",
+            "2026-06-18T08:00:01Z WARN slow query",
+            "2026-06-18T08:00:02Z ERROR boom ValueError",
+        ],
+    )
+    d = summarize_log(path, level="error")
+    assert d["total_events"] == 1
+    assert d["top"][0]["level"] == "error"
+
+
+def test_time_window_filters(tmp_path) -> None:
+    path = _write(
+        tmp_path,
+        [
+            "2026-06-18T08:00:00Z ERROR early FooException",
+            "2026-06-18T12:00:00Z ERROR mid BarException",
+            "2026-06-18T20:00:00Z ERROR late BazException",
+        ],
+    )
+    d = summarize_log(path, since="2026-06-18T10:00:00", until="2026-06-18T18:00:00")
+    sigs = {g["signature"] for g in d["top"]}
+    assert any("BarException" in s for s in sigs)
+    assert not any("FooException" in s or "BazException" in s for s in sigs)

runspec_logops_core-0.1.0/tests/test_signatures.py

@@ -0,0 +1,65 @@
+"""normalize_line and error_signature are deterministic and cluster correctly."""
+
+from runspec_logops_core import detect_level, error_signature, normalize_line
+from runspec_logops_core.signatures import strip_timestamp
+
+
+def test_normalize_masks_volatile_parts() -> None:
+    a = normalize_line("2026-06-18T08:01:11Z worker-12 handled request id=7f3a in 412ms")
+    b = normalize_line("2026-06-18T09:44:02Z worker-99 handled request id=0a1b in 7ms")
+    # Different timestamps / numbers / ids collapse to the same shape.
+    assert a == b
+    assert "<n>" in a
+
+
+def test_normalize_masks_uuid_and_hex() -> None:
+    s = normalize_line("error at 0xdeadbeef for 550e8400-e29b-41d4-a716-446655440000")
+    assert "<hex>" in s
+    assert "<uuid>" in s
+
+
+def test_strip_timestamp_variants() -> None:
+    assert strip_timestamp("[2026-06-18 08:01:11] hello") == "hello"
+    assert strip_timestamp("Jun 18 08:01:11 hello") == "hello"
+    assert strip_timestamp("no timestamp here") == "no timestamp here"
+
+
+def test_detect_level() -> None:
+    assert detect_level("2026-06-18 ERROR boom") == "error"
+    assert detect_level("WARN something") == "warning"
+    assert detect_level("plain line") is None
+
+
+def test_error_signature_java_stack_clusters() -> None:
+    block1 = [
+        "2026-06-18T08:01:11Z ERROR NullPointerException: discount was null",
+        "\tat com.acme.OrderSvc.price(OrderSvc.java:42)",
+        "\tat com.acme.OrderSvc.checkout(OrderSvc.java:88)",
+    ]
+    block2 = [
+        "2026-06-18T09:00:00Z ERROR NullPointerException: discount was null",
+        "\tat com.acme.OrderSvc.price(OrderSvc.java:42)",
+        "\tat com.acme.OrderSvc.checkout(OrderSvc.java:88)",
+    ]
+    sig = error_signature(block1)
+    assert sig == error_signature(block2)
+    assert sig.startswith("NullPointerException@")
+    assert "OrderSvc.price" in sig
+
+
+def test_error_signature_python_stack() -> None:
+    block = [
+        "Traceback (most recent call last):",
+        '  File "app.py", line 10, in handler',
+        "    do_thing()",
+        "ValueError: bad input",
+    ]
+    sig = error_signature(block)
+    assert sig.startswith("ValueError@")
+    assert "handler" in sig
+
+
+def test_error_signature_plain_line_falls_back_to_shape() -> None:
+    sig = error_signature(["2026-06-18 INFO served 200 in 5ms"])
+    assert "@" not in sig
+    assert "<n>" in sig