stacktrace-cli 0.0.1__py3-none-any.whl → 0.2.0__py3-none-any.whl

stacktrace_cli/__init__.py

@@ -1,3 +1,3 @@
 """Placeholder CLI package for Stacktrace.ai."""
 
-__version__ = "0.0.1"
+__version__ = "0.2.0"

stacktrace_cli/__main__.py

@@ -1,24 +1,16 @@
-"""Entry point for the ``stacktrace`` command."""
+"""Entry point for the ``stacktrace`` command.
 
-from __future__ import annotations
-
-import argparse
-
-from . import __version__
-
-HOMEPAGE = "https://stacktrace.ai"
+`[project.scripts]` still names `stacktrace_cli.__main__:main`, which now
+resolves to the Click group in `stacktrace_cli.cli`, so both the console script
+and `python -m stacktrace_cli` reach the same object and the published
+entry-point string does not change between releases.
+"""
 
+from __future__ import annotations
 
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(
-        prog="stacktrace",
-        description=f"Stacktrace.ai CLI (pre-alpha). See {HOMEPAGE}",
-    )
-    parser.add_argument("--version", action="version", version=f"stacktrace {__version__}")
-    parser.parse_args(argv)
-    print(f"stacktrace {__version__} — pre-alpha placeholder. See {HOMEPAGE}")
-    return 0
+from .cli import main
 
+__all__ = ["main"]
 
 if __name__ == "__main__":
-    raise SystemExit(main())
+    main()

stacktrace_cli/analysis.py

@@ -0,0 +1,375 @@
+"""The read pipeline, in the one place that knows its order.
+
+`run_detector` takes a `CorrelatedView`, not a `SessionView`, so
+sessions -> correlate -> detect is stitched by the caller. It was stitched
+twice — once in `cli.py`'s `detect`, once in `sync_detect.py` — and `monitor`
+would have been the third copy of an order that must not differ between them.
+A page showing different findings from the command, for no reason but a
+divergent call site, is the failure this module exists to prevent.
+
+Both halves of the result travel together because neither is recoverable from
+the other: `run` carries the findings, and `view` carries the component a call
+resolved to and the coverage a reader weighs them against.
+
+This module knows nothing about Click. Every caller renders an error its own
+way — a `ClickException` at the command line, a `SyncError` on the upload path —
+so the failures here are `ValueError`, and the message is the one the upload
+path's tests already pin.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass, replace
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from stacktrace_cli.correlate.orchestrate import Acquired, acquire_correlated_view
+from stacktrace_cli.correlate.project_map import parse_mapping
+from stacktrace_cli.correlate.record import CorrelatedSession, CorrelatedView, Coverage
+from stacktrace_cli.detector.cache import VerdictCache
+from stacktrace_cli.detector.run import (
+    DEFAULT_BUDGET,
+    DEFAULT_SAMPLE_BUDGET,
+    DetectorRun,
+    run_detector,
+)
+from stacktrace_cli.sessions.access import SessionView, collect_sessions
+
+
+@dataclass(frozen=True)
+class Analysis:
+    """One run of the read pipeline, and the window it read."""
+
+    run: DetectorRun
+    #: The correlated record the detector judged. Kept because a consumer needs
+    #: what a call resolved to — `monitor` renders it, `sync detect` counts it —
+    #: and a `Detection` carries neither the resolution nor the coverage.
+    view: CorrelatedView
+    #: `parse_since`'s cutoff, retained. Nothing downstream of session
+    #: selection needed it before, so nothing kept it.
+    window_start: datetime
+    #: `now(UTC)` taken *before* collection, so the window never claims to
+    #: cover a session that arrived while the pipeline was running.
+    window_end: datetime
+    #: Whether correlation has run. `False` only on `analyse_progressively`'s
+    #: preview stages, which carry the sessions and their built-in activity
+    #: before a composition has been built — so a consumer knows that coverage
+    #: is not yet countable and that only calls needing no composition are
+    #: listed. `analyse` is always placed.
+    placed: bool = True
+
+
+def parse_since(value: str) -> datetime:
+    """`7d` or `7` -> an aware UTC cut-off.
+
+    Raises `ValueError`, never a Click or transport exception: this module is
+    below both. The message is the upload path's, which its tests pin.
+    """
+    text = value.strip().lower()
+    try:
+        days = int(text[:-1]) if text.endswith("d") else int(text)
+    except ValueError:
+        raise ValueError(f"--since must be a positive day count, not {value!r}") from None
+    if days <= 0:
+        raise ValueError(f"--since must be a positive day count, not {value!r}")
+    try:
+        return datetime.now(UTC) - timedelta(days=days)
+    except OverflowError:
+        # `timedelta` takes any `int` but overflows past `timedelta.max.days`.
+        # The same user mistake as a non-numeric value, so the same diagnostic.
+        raise ValueError(f"--since must be a positive day count, not {value!r}") from None
+
+
+def _only(view: SessionView, session_ids: tuple[str, ...]) -> SessionView:
+    """The window narrowed to named sessions, or the window itself.
+
+    Narrowed *before* correlation rather than after judgement, because the point
+    is that nothing else can be dispatched: a caller that pays for one named
+    session must not be able to spend that payment on another one the detector
+    happened to rank higher. `unavailable` is carried through unchanged — a
+    reader that failed is still a reader that failed, whichever session was
+    asked for.
+    """
+    if not session_ids:
+        return view
+    wanted = set(session_ids)
+    return replace(view, sessions=tuple(s for s in view.sessions if s.session_id in wanted))
+
+
+def analyse(
+    *,
+    agent_kinds: tuple[str, ...] = (),
+    since: str | datetime = "7d",
+    bom_paths: tuple[Path, ...] = (),
+    project_map: tuple[str, ...] = (),
+    root: Path | None = None,
+    session_ids: tuple[str, ...] = (),
+    escalate: bool = False,
+    budget: int = DEFAULT_BUDGET,
+    sample_budget: int = DEFAULT_SAMPLE_BUDGET,
+    cache: VerdictCache | None = None,
+    attach_advisories: Any = None,
+) -> Analysis:
+    """Read this machine's sessions, correlate them, and judge them.
+
+    `window_end` is taken before collection rather than after: a window that
+    ends when the pipeline finished would claim to cover a session that started
+    while it ran.
+
+    `attach_advisories` is correlation's own seam. A long-lived process passes a
+    cache through it so osv.dev is asked once per component rather than once per
+    pass; a one-shot command passes nothing and gets the default.
+
+    `session_ids` narrows the window to named sessions. Empty means the whole
+    window, which is what every command passes; monitor's escalate button is
+    what needs the narrowing, and needs it to be structural.
+
+    `since` is the window's spelling — `parse_since` reads it — or the cutoff
+    itself, for a caller whose own `--since` spelling is not this one's.
+    """
+    window_end = datetime.now(UTC)
+    window_start = since if isinstance(since, datetime) else parse_since(since)
+    acquired = _correlated(
+        agent_kinds=agent_kinds,
+        window_start=window_start,
+        bom_paths=bom_paths,
+        project_map=project_map,
+        root=root,
+        session_ids=session_ids,
+        attach_advisories=attach_advisories,
+    )
+    run = run_detector(
+        acquired.view,
+        escalate=escalate,
+        budget=budget,
+        sample_budget=sample_budget,
+        cache=cache,
+    )
+    return Analysis(
+        run=run,
+        view=acquired.view,
+        window_start=window_start,
+        window_end=window_end,
+    )
+
+
+#: How far back the first, cheap read goes. Collection scales with the window
+#: on a fixed floor — measured at 0.24s for a minute, 0.33s for an hour and
+#: 1.20s for three days — so reading the newest hour first is what puts rows on
+#: screen in a third of a second instead of one and a half.
+PREVIEW_WINDOW = timedelta(hours=1)
+
+
+def _collected(
+    *,
+    agent_kinds: tuple[str, ...],
+    window_start: datetime,
+    root: Path | None,
+    session_ids: tuple[str, ...],
+) -> SessionView:
+    """Read the window. Its own function so a caller can read twice."""
+    return _only(collect_sessions(list(agent_kinds) or None, window_start, root=root), session_ids)
+
+
+def _acquire(
+    sessions: SessionView,
+    *,
+    bom_paths: tuple[Path, ...],
+    project_map: tuple[str, ...],
+    attach_advisories: Any,
+) -> Acquired:
+    """Correlate what was read."""
+    hook = {} if attach_advisories is None else {"attach_advisories": attach_advisories}
+    return acquire_correlated_view(
+        sessions,
+        bom_paths=bom_paths,
+        project_map=tuple(parse_mapping(mapping) for mapping in project_map),
+        **hook,
+    )
+
+
+def _correlated(
+    *,
+    agent_kinds: tuple[str, ...],
+    window_start: datetime,
+    bom_paths: tuple[Path, ...],
+    project_map: tuple[str, ...],
+    root: Path | None,
+    session_ids: tuple[str, ...],
+    attach_advisories: Any,
+) -> Acquired:
+    """Everything up to the judging, shared by both entry points."""
+    return _acquire(
+        _collected(
+            agent_kinds=agent_kinds,
+            window_start=window_start,
+            root=root,
+            session_ids=session_ids,
+        ),
+        bom_paths=bom_paths,
+        project_map=project_map,
+        attach_advisories=attach_advisories,
+    )
+
+
+def _unplaced(sessions: SessionView, *, window_start: datetime, window_end: datetime) -> Analysis:
+    """The sessions as read, before anything has been correlated or judged.
+
+    Correlation is 2.7s of a 4.4s first paint and it places 0.9% of calls; the
+    other 99% are built-in tools, which need no composition at all. So this
+    carries every session read and lets the render list the calls a
+    composition is not needed for — coverage stays uncounted, and no finding is
+    claimed, because neither is known yet.
+    """
+    return Analysis(
+        run=DetectorRun(
+            collection_failures=run_detector(
+                CorrelatedView(unavailable=sessions.unavailable)
+            ).collection_failures
+        ),
+        view=CorrelatedView(
+            unavailable=sessions.unavailable,
+            sessions=tuple(
+                CorrelatedSession(
+                    session=session,
+                    composition=None,
+                    resolutions={},
+                    coverage=Coverage(total=0, resolved=0, by_outcome={}, by_component_type={}),
+                )
+                for session in sessions.sessions
+            ),
+        ),
+        window_start=window_start,
+        window_end=window_end,
+        placed=False,
+    )
+
+
+def analyse_progressively(
+    *,
+    agent_kinds: tuple[str, ...] = (),
+    since: str | datetime = "7d",
+    bom_paths: tuple[Path, ...] = (),
+    project_map: tuple[str, ...] = (),
+    root: Path | None = None,
+    batch: int = 8,
+    preview: timedelta | None = PREVIEW_WINDOW,
+    cache: VerdictCache | None = None,
+    attach_advisories: Any = None,
+) -> Iterator[Analysis]:
+    """The same pipeline, delivered in instalments.
+
+    `analyse` answers once, which is right for a command that prints and exits
+    and wrong for a page meant to look alive. Measured over 339 real sessions
+    the work splits about 6.6s to collect and correlate, then about 12ms to
+    judge each session — so a caller that waits for the whole run shows nothing
+    for six seconds while already holding the sessions and their activity.
+
+    Three kinds of yield, cheapest first.
+
+    **Preview stages, before correlation** (`placed=False`). Correlation is
+    2.7s of a 4.4s first paint and it places 0.9% of a real window's calls; the
+    other 99% are built-in tools, which `join.py`'s predicates answer for in a
+    millisecond. So the sessions and those calls go out first — the newest
+    `preview` of them, then the whole window — and the page fills in ~0.35s
+    rather than ~4.4s. Pass `preview=None` for attributed data only.
+
+    **Then batches of judged sessions**, newest first, because someone watching
+    a machine cares about what just happened and should not have to scroll for
+    it. Every one of these carries the *whole* session list: the preview
+    already published it, and a later stage carrying fewer would make the count
+    on the page go backwards.
+
+    The last yield equals what `analyse` would have returned. If it did not,
+    the page and the command would disagree, which is the thing one pipeline
+    exists to prevent.
+
+    `cache` is read and never written. A session graded by an earlier
+    `detect --escalate` shows that grade here; this path never commissions one.
+
+    **No `escalate` parameter, deliberately.** Stage 3's budget is per *run*, so
+    judging in batches would give each batch its own budget and spend a multiple
+    of what was authorised. A streaming escalation needs a budget shared across
+    batches; until it has one, this path does not offer the option rather than
+    offering it wrongly.
+    """
+    window_end = datetime.now(UTC)
+    window_start = since if isinstance(since, datetime) else parse_since(since)
+
+    def read(cutoff: datetime) -> SessionView:
+        return _collected(agent_kinds=agent_kinds, window_start=cutoff, root=root, session_ids=())
+
+    if preview is not None:
+        cutoff = window_end - preview
+        # A window already narrower than the preview is read once, not twice.
+        if cutoff > window_start:
+            yield _unplaced(read(cutoff), window_start=window_start, window_end=window_end)
+
+    sessions = read(window_start)
+    if preview is not None:
+        yield _unplaced(sessions, window_start=window_start, window_end=window_end)
+
+    view = _acquire(
+        sessions,
+        bom_paths=bom_paths,
+        project_map=project_map,
+        attach_advisories=attach_advisories,
+    ).view
+
+    def _stage(run: DetectorRun, sessions: tuple[CorrelatedSession, ...]) -> Analysis:
+        """One instalment: every session, and the findings judged so far.
+
+        The whole session list, every time. It grew with the findings until the
+        preview stages existed — the point then was that the feed should not
+        appear all at once — but the preview publishes every session within
+        ~1.6s and a client that paces its own reveal streams them in anyway. A
+        stage carrying fewer sessions than the preview did would make the count
+        on the page go backwards.
+        """
+        return Analysis(
+            run=run,
+            view=replace(view, sessions=sessions),
+            window_start=window_start,
+            window_end=window_end,
+        )
+
+    # The detector derives these from the view, and a stage that has not judged
+    # anything yet still has to carry them: a reader that failed is the one
+    # thing a page must never render as silence.
+    failures = run_detector(CorrelatedView(unavailable=view.unavailable)).collection_failures
+
+    # Stage zero: what could not be read, before a session is judged. A reader
+    # that failed is the one thing a page must never render as silence, and it
+    # is known before the detector has done anything at all. Skipped when a
+    # preview already carried it, since that stage said the same and carried
+    # the sessions too.
+    if preview is None:
+        yield _stage(DetectorRun(collection_failures=failures), ())
+
+    ordered = sorted(
+        view.sessions,
+        key=lambda correlated: correlated.session.started_at or datetime.min.replace(tzinfo=UTC),
+        reverse=True,
+    )
+    step = max(batch, 1)
+    accumulated = DetectorRun(collection_failures=failures)
+    for index in range(0, len(ordered), step):
+        judged = run_detector(
+            CorrelatedView(sessions=tuple(ordered[index : index + step])),
+            # Read, never written, and never escalating: a session an earlier
+            # `detect --escalate` graded renders with that grade here, and this
+            # path commissions nothing (ADR-0026 clause 2).
+            cache=cache,
+        )
+        accumulated = DetectorRun(
+            detections=accumulated.detections + judged.detections,
+            unknowns=accumulated.unknowns + judged.unknowns,
+            sessions=accumulated.sessions + judged.sessions,
+            escalated=accumulated.escalated + judged.escalated,
+            analysed=accumulated.analysed + judged.analysed,
+            cache_hits=accumulated.cache_hits + judged.cache_hits,
+            collection_failures=failures,
+        )
+        yield _stage(accumulated, tuple(ordered))