cc-pushback 0.1.0__py3-none-any.whl

cc_pushback/__init__.py

@@ -0,0 +1,28 @@
+"""Collect developer pushback signals from existing Claude Code transcripts."""
+
+from __future__ import annotations
+
+from cc_pushback.context import ContextSnapshot, ContextTurn, build_snapshot
+from cc_pushback.detectors import Detector, detect
+from cc_pushback.models import DedupKey, FeedbackCandidate, SourceKind, dedup_key
+from cc_pushback.scan import ScanReport, scan
+from cc_pushback.spec import PUSHBACK_SPEC
+from cc_pushback.store import FeedbackStore
+
+# Not the retired export-control convention: this exists only so great-docs' API
+# reference skips the SourceKind (Literal) and DedupKey (NewType) aliases, which its
+# dynamic walker cannot render ("Cannot handle auto for object kind: TYPE_ALIAS").
+# great-docs documents __all__ when present; keep it in sync with the re-exports above.
+__all__ = [
+    "PUSHBACK_SPEC",
+    "ContextSnapshot",
+    "ContextTurn",
+    "Detector",
+    "FeedbackCandidate",
+    "FeedbackStore",
+    "ScanReport",
+    "build_snapshot",
+    "dedup_key",
+    "detect",
+    "scan",
+]

cc_pushback/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from cc_pushback.cli import main
+
+if __name__ == "__main__":
+    main()

cc_pushback/claude.py

@@ -0,0 +1,46 @@
+"""A thin shell-out to the ``claude`` CLI for a single headless completion.
+
+Argv construction and envelope parsing come from the shared ``spawnllm`` library;
+the spawn stays local (``anyio.run_process``). It uses the user's existing Claude
+Code auth (no API key), so the package stays offline unless ``claude`` is
+actually on the path.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+import anyio
+from spawnllm import ClaudeCliBackend, parse_result_envelope
+
+CLAUDE_TIMEOUT = 180
+
+
+def claude_available() -> bool:
+    """Returns whether the ``claude`` CLI is on ``PATH``."""
+    return shutil.which("claude") is not None
+
+
+async def run_claude(prompt: str, *, system: str, model: str) -> str:
+    """Runs one headless ``claude`` turn and returns its text result.
+
+    Args:
+        prompt: The user message to send.
+        system: The system prompt.
+        model: The model to run, for example ``claude-sonnet-4-6``.
+
+    Returns:
+        The assistant's text response — the ``result`` field of the JSON output.
+
+    Raises:
+        subprocess.SubprocessError: If ``claude`` exits non-zero, times out, or
+            reports an error in its JSON envelope.
+    """
+    argv = ClaudeCliBackend.cc_sentiment(system_prompt=system).build_argv(prompt, model=model)
+    try:
+        with anyio.fail_after(CLAUDE_TIMEOUT):
+            result = await anyio.run_process(argv, check=True)
+    except TimeoutError as exc:
+        raise subprocess.TimeoutExpired(argv, CLAUDE_TIMEOUT) from exc
+    return parse_result_envelope(result.stdout, argv=argv, stderr=result.stderr)

cc_pushback/cli.py

@@ -0,0 +1,138 @@
+"""The ``cc-pushback`` command-line interface: scan, stats, list, and view-samples."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+
+import anyio
+import click
+from cc_transcript import CLAUDE_PROJECTS_DIR
+
+from cc_pushback.models import PUSHBACK_SOURCE_KINDS, SourceKind
+from cc_pushback.report import Sample, build_summary, render_html
+from cc_pushback.scan import scan as run_scan
+from cc_pushback.serve import serve
+from cc_pushback.store import FeedbackStore
+
+SOURCE_KINDS = [*PUSHBACK_SOURCE_KINDS]
+
+
+def coro[**P, R](fn: Callable[P, Awaitable[R]]) -> Callable[P, R]:
+    """Adapts an async command body into the sync callback Click expects."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        return anyio.run(functools.partial(fn, *args, **kwargs))
+
+    return wrapper
+
+
+@click.group()
+@click.version_option(package_name="cc-pushback")
+def main() -> None:
+    """Collect developer pushback signals from existing Claude Code transcripts."""
+
+
+@main.command()
+@click.option(
+    "--transcripts",
+    "transcripts",
+    multiple=True,
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    help="Transcript directories to scan. Defaults to ~/.claude/projects.",
+)
+@click.option("--full", is_flag=True, help="Re-scan every transcript, ignoring recorded mtimes.")
+@click.option(
+    "--db",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Database path. Defaults to ~/.cc-pushback/feedback.db.",
+)
+@coro
+async def scan(transcripts: tuple[Path, ...], full: bool, db: Path | None) -> None:
+    """Scan transcripts for feedback, incrementally.
+
+    Each transcript is parsed only when new or modified since the last scan, and
+    every candidate is inserted with ``INSERT OR IGNORE`` keyed by a content
+    digest, so re-running ``scan`` over unchanged inputs is a no-op. Recording a
+    file and inserting its candidates commit in one transaction.
+    """
+    roots = transcripts or (CLAUDE_PROJECTS_DIR,)
+    async with await FeedbackStore.open(db or FeedbackStore.default_path()) as store:
+        report = await run_scan(store, roots, full=full)
+    click.echo(f"scanned {report.scanned} files, {report.inserted} new rows")
+
+
+@main.command()
+@click.option(
+    "--db",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Database path. Defaults to ~/.cc-pushback/feedback.db.",
+)
+@coro
+async def stats(db: Path | None) -> None:
+    """Print ingestion counts by source kind and the scanned-file count."""
+    async with await FeedbackStore.open(db or FeedbackStore.default_path()) as store:
+        report = await store.stats()
+    click.echo(f"total: {report.total}  files: {report.files}")
+    for kind, count in report.by_source.items():
+        click.echo(f"  {kind}: {count}")
+
+
+@main.command(name="list")
+@click.option(
+    "--source",
+    "source",
+    type=click.Choice(SOURCE_KINDS),
+    default=None,
+    help="Restrict to one source kind.",
+)
+@click.option("--limit", type=int, default=20, show_default=True, help="Maximum events to show.")
+@click.option(
+    "--db",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Database path. Defaults to ~/.cc-pushback/feedback.db.",
+)
+@coro
+async def list_(source: SourceKind | None, limit: int, db: Path | None) -> None:
+    """List recent feedback events, newest first."""
+    async with await FeedbackStore.open(db or FeedbackStore.default_path()) as store:
+        rows = await store.recent(source_kind=source, limit=limit)
+    for row in rows:
+        click.echo(f"[{row['source_kind']}] {row['occurred_at']}  {str(row['text'])[:200]}")
+
+
+@main.command(name="view-samples")
+@click.option(
+    "--db",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Database path. Defaults to ~/.cc-pushback/feedback.db.",
+)
+@click.option(
+    "--llm/--no-llm",
+    default=True,
+    show_default=True,
+    help="Summarize with the claude CLI when it is on PATH, else use heuristics.",
+)
+@click.option("--model", default="claude-sonnet-4-6", show_default=True, help="Model for the claude CLI summary.")
+@click.option("--port", type=int, default=0, show_default=True, help="Port to serve on; 0 picks a free one.")
+@click.option("--open", "open_", is_flag=True, help="Open the page in a browser once serving.")
+@coro
+async def view_samples(db: Path | None, llm: bool, model: str, port: int, open_: bool) -> None:
+    """Render every collected sample into one HTML page and serve it locally.
+
+    The page leads with a corpus summary and highlights, then lists every sample
+    with a kind filter, a free-text search, and an expandable context window. It is
+    built in memory and served over a transient HTTP server whose URL is printed;
+    press Ctrl-C to stop. The summary is written by the ``claude`` CLI when ``--llm``
+    is set and ``claude`` is installed, falling back to deterministic heuristics.
+    """
+    async with await FeedbackStore.open(db or FeedbackStore.default_path()) as store:
+        samples = [Sample.from_row(row) for row in await store.events()]
+    summary = await build_summary(samples, use_llm=llm, model=model)
+    await serve(render_html(samples, summary).encode("utf-8"), port=port, open_browser=open_)

cc_pushback/context.py

@@ -0,0 +1,11 @@
+"""Re-exports the conversational-window primitive from the mining domain.
+
+Deprecated: import these names from :mod:`cc_transcript.domains.mining`. This shim
+keeps cc-pushback's historical import paths working for at least one release.
+"""
+
+from __future__ import annotations
+
+from cc_transcript.domains.mining import ContextSnapshot, ContextTurn, build_snapshot, trigger_for, turn_for
+
+__all__ = ["ContextSnapshot", "ContextTurn", "build_snapshot", "trigger_for", "turn_for"]

cc_pushback/detectors.py

@@ -0,0 +1,138 @@
+"""cc-pushback's detector policy: map neutral mining facts to feedback candidates.
+
+The fact-recognition mechanism lives in :mod:`cc_transcript.domains.mining`; this
+module injects cc-pushback's policy — its filter spec, its trigger-absence
+disqualification, and its review formats — and maps each surviving
+:class:`MiningSignal` to a :class:`FeedbackCandidate`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from cc_transcript import keep
+from cc_transcript.domains.mining import (
+    FeedbackCandidate,
+    build_snapshot,
+    dedup_key,
+    iter_interrupt_marker_signals,
+    iter_plan_reentry_signals,
+    iter_plan_rejection_signals,
+    iter_review_comment_signals,
+    iter_tool_denial_signals,
+    iter_user_message_signals,
+)
+
+from cc_pushback.formats import formats
+from cc_pushback.spec import PUSHBACK_SPEC
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterator, Mapping, Sequence
+    from pathlib import Path
+    from typing import Any
+
+    from cc_transcript.domains.mining import MiningSignal
+    from cc_transcript.models import TranscriptEvent
+
+type Detector = Callable[[Path, Sequence[TranscriptEvent]], Iterator[FeedbackCandidate]]
+
+SPEC_DETECTORS = frozenset({"transcript_message", "plan_reentry", "review_comment"})
+
+
+def survives(events: Sequence[TranscriptEvent], sig: MiningSignal) -> bool:
+    if sig.detector in SPEC_DETECTORS and not keep(events[sig.event_index], PUSHBACK_SPEC):
+        return False
+    return not (sig.detector == "transcript_message" and sig.trigger_index is None)
+
+
+def parts(sig: MiningSignal) -> tuple[str, ...]:
+    match sig.detector:
+        case "transcript_message":
+            return (sig.session_id, "transcript_message", sig.text)
+        case "exit_plan_rejection":
+            return (sig.session_id, "plan_review", "exit_plan", sig.text)
+        case "plan_reentry":
+            return (sig.session_id, "plan_review", "plan_reentry", sig.text)
+        case "denial" | "interrupt":
+            return (sig.session_id, "interrupt_rejection", sig.text)
+        case "review_comment":
+            return (
+                sig.session_id,
+                "review_comment",
+                sig.evidence["file"] or "",
+                str(sig.evidence["line_start"] or ""),
+                str(sig.evidence["line_end"] or ""),
+                sig.text,
+            )
+    raise AssertionError(sig.detector)
+
+
+def payload_of(sig: MiningSignal) -> Mapping[str, Any] | None:
+    match sig.detector:
+        case "transcript_message":
+            return None
+        case "exit_plan_rejection" | "plan_reentry" | "interrupt":
+            return {"detector": sig.detector}
+        case "denial":
+            return dict(sig.evidence) or None
+        case "review_comment":
+            return {key: sig.evidence[key] for key in ("format", "file", "line_start", "line_end")}
+    raise AssertionError(sig.detector)
+
+
+def to_candidate(path: Path, events: Sequence[TranscriptEvent], sig: MiningSignal) -> FeedbackCandidate:
+    return FeedbackCandidate(
+        dedup_key=dedup_key(*parts(sig)),
+        source_kind=sig.kind,
+        occurred_at=sig.occurred_at,
+        text=sig.text,
+        context=build_snapshot(events, sig.event_index, lower_bound=sig.lower_bound),
+        session_id=sig.session_id,
+        origin_path=path,
+        origin_uuid=sig.event_uuid,
+        cc_version=sig.cc_version,
+        payload=payload_of(sig),
+        signal=sig.signal,
+    )
+
+
+def candidates_from(
+    path: Path, events: Sequence[TranscriptEvent], *streams: Iterator[MiningSignal]
+) -> Iterator[FeedbackCandidate]:
+    return (to_candidate(path, events, sig) for stream in streams for sig in stream if survives(events, sig))
+
+
+def transcript_messages(path: Path, events: Sequence[TranscriptEvent]) -> Iterator[FeedbackCandidate]:
+    return candidates_from(path, events, iter_user_message_signals(events))
+
+
+def plan_reviews(path: Path, events: Sequence[TranscriptEvent]) -> Iterator[FeedbackCandidate]:
+    return candidates_from(path, events, iter_plan_rejection_signals(events), iter_plan_reentry_signals(events))
+
+
+def interrupt_rejections(path: Path, events: Sequence[TranscriptEvent]) -> Iterator[FeedbackCandidate]:
+    return candidates_from(path, events, iter_tool_denial_signals(events), iter_interrupt_marker_signals(events))
+
+
+def detect(path: Path, events: Sequence[TranscriptEvent]) -> list[FeedbackCandidate]:
+    """Runs every detector over one transcript's events.
+
+    Args:
+        path: The transcript file the events came from.
+        events: The transcript's full ordered event stream.
+
+    Returns:
+        Every feedback candidate the detectors found, in detector order.
+    """
+    return list(
+        candidates_from(
+            path,
+            events,
+            iter_user_message_signals(events),
+            iter_plan_rejection_signals(events),
+            iter_plan_reentry_signals(events),
+            iter_tool_denial_signals(events),
+            iter_interrupt_marker_signals(events),
+            iter_review_comment_signals(events, formats()),
+        )
+    )

cc_pushback/formats.py

@@ -0,0 +1,98 @@
+"""cc-pushback's concrete code-review formats over the mining domain's parser infra.
+
+The generic :class:`ReviewComment`/:class:`ReviewFormat` types and the
+format-dispatch live in :mod:`cc_transcript.domains.mining`; this module supplies
+cc-pushback's policy — the three review formats it recognizes — and injects them
+into the domain's :func:`extract_all`.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from cc_transcript.domains.mining import ReviewComment, ReviewFormat
+from cc_transcript.domains.mining import extract_all as domain_extract_all
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+SUPERSET_INLINE_RE = re.compile(
+    r"^In ((?=\S*[./]|\S+?:L)\S+?)(?::L(\d+)(?:-(\d+))?)?: (.+)$", re.MULTILINE
+)
+CONDUCTOR_FINDING_RE = re.compile(
+    r"^- file: (?P<file>\S+?):(?P<line>\d+)\s*$"
+    r"(?:\n- theme: .+$)?"
+    r"(?:\n- claim: (?P<claim>.+)$)?"
+    r"(?:\n- suggestion: (?P<suggestion>.+)$)?",
+    re.MULTILINE,
+)
+CONDUCTOR_WORKSTREAM_HEADER_RE = re.compile(
+    r"^### (?P<id>[A-Z][\w-]*\d*)\s*\[(?P<kind>[A-Z]+)\]\s*—\s*(?P<title>.+)$",
+    re.MULTILINE,
+)
+WORKSTREAM_BODY_RE = re.compile(r"^(?:FIX|Tests): .+$", re.MULTILINE)
+
+
+def extract_superset_inline(text: str) -> tuple[ReviewComment, ...]:
+    return tuple(
+        ReviewComment(
+            file=match.group(1),
+            line_start=int(match.group(2)) if match.group(2) else None,
+            line_end=int(match.group(3)) if match.group(3) else None,
+            comment=match.group(4).strip(),
+        )
+        for match in SUPERSET_INLINE_RE.finditer(text)
+    )
+
+
+def extract_conductor_finding(text: str) -> tuple[ReviewComment, ...]:
+    return tuple(
+        ReviewComment(
+            file=match.group("file"),
+            line_start=int(match.group("line")),
+            line_end=None,
+            comment=" ".join(part.strip() for part in (match.group("claim"), match.group("suggestion")) if part),
+        )
+        for match in CONDUCTOR_FINDING_RE.finditer(text)
+    )
+
+
+def extract_conductor_workstream(text: str) -> tuple[ReviewComment, ...]:
+    headers = list(CONDUCTOR_WORKSTREAM_HEADER_RE.finditer(text))
+    return tuple(
+        ReviewComment(
+            file=None,
+            line_start=None,
+            line_end=None,
+            comment=" ".join(
+                [f"{header.group('id')} [{header.group('kind')}] {header.group('title').strip()}"]
+                + [line.group(0).strip() for line in WORKSTREAM_BODY_RE.finditer(text[header.end() : end])]
+            ),
+        )
+        for header, end in zip(
+            headers,
+            [*(h.start() for h in headers[1:]), len(text)],
+            strict=True,
+        )
+    )
+
+
+def formats() -> tuple[ReviewFormat, ...]:
+    return (
+        ReviewFormat("superset-inline", SUPERSET_INLINE_RE, extract_superset_inline),
+        ReviewFormat("conductor-finding", CONDUCTOR_FINDING_RE, extract_conductor_finding),
+        ReviewFormat("conductor-workstream", CONDUCTOR_WORKSTREAM_HEADER_RE, extract_conductor_workstream),
+    )
+
+
+def extract_all(text: str) -> Iterator[tuple[ReviewFormat, ReviewComment]]:
+    """Yields every ``(format, comment)`` extracted by any of cc-pushback's formats.
+
+    Args:
+        text: The raw review message text.
+
+    Yields:
+        One pair per extracted comment, across all formats whose pattern matches.
+    """
+    return domain_extract_all(text, formats())

cc_pushback/markers.py

@@ -0,0 +1,25 @@
+"""Re-exports the transcript marker constants from the mining domain.
+
+Deprecated: import these names from :mod:`cc_transcript.domains.mining`. This shim
+keeps cc-pushback's historical import paths working for at least one release.
+"""
+
+from __future__ import annotations
+
+from cc_transcript.domains.mining import (
+    DENIAL_PREFIX,
+    EDIT_TOOLS,
+    INTERRUPT_MARKER_RE,
+    REENTRY_LOOKBACK,
+    USER_SAID_MARKER,
+    USER_SAID_TRAILER,
+)
+
+__all__ = [
+    "DENIAL_PREFIX",
+    "EDIT_TOOLS",
+    "INTERRUPT_MARKER_RE",
+    "REENTRY_LOOKBACK",
+    "USER_SAID_MARKER",
+    "USER_SAID_TRAILER",
+]

cc_pushback/models.py

@@ -0,0 +1,15 @@
+"""Re-exports the feedback candidate model from the mining domain.
+
+Deprecated: import :class:`FeedbackCandidate`, :data:`DedupKey`, :func:`dedup_key`,
+and :data:`SourceKind` from :mod:`cc_transcript.domains.mining`. This shim keeps
+cc-pushback's historical import paths working for at least one release.
+"""
+
+from __future__ import annotations
+
+from cc_transcript.domains.mining import DedupKey, FeedbackCandidate, SourceKind, dedup_key
+
+PUSHBACK_SOURCE_KINDS = ("transcript_message", "plan_review", "interrupt_rejection", "review_comment")
+"""The source kinds cc-pushback's detectors emit, for CLI choice lists."""
+
+__all__ = ["PUSHBACK_SOURCE_KINDS", "DedupKey", "FeedbackCandidate", "SourceKind", "dedup_key"]

cc_pushback/nav.py

@@ -0,0 +1,31 @@
+"""Re-exports the transcript navigation helpers from the mining domain.
+
+Deprecated: import these names from :mod:`cc_transcript.domains.mining`. This shim
+keeps cc-pushback's historical import paths working for at least one release.
+"""
+
+from __future__ import annotations
+
+from cc_transcript.domains.mining import (
+    denial_results,
+    denied_tool_payload,
+    embedded_user_text,
+    interrupt_marker,
+    is_bare_interrupt_marker,
+    last_edit_index,
+    marker_in,
+    next_user_message,
+    tool_uses,
+)
+
+__all__ = [
+    "denial_results",
+    "denied_tool_payload",
+    "embedded_user_text",
+    "interrupt_marker",
+    "is_bare_interrupt_marker",
+    "last_edit_index",
+    "marker_in",
+    "next_user_message",
+    "tool_uses",
+]