testpulse 0.1.0__py3-none-any.whl

testpulse/__init__.py

@@ -0,0 +1,110 @@
+"""TestPulse — time your tests, optimize your outcomes."""
+
+from testpulse.api import (
+    VERSION,
+    AggregatedCiStats,
+    CiUploadError,
+    ConfidenceBand,
+    DurationPercentiles,
+    ExcludedTestRisk,
+    FlakinessEstimate,
+    HistoryCitation,
+    LLMCompletionError,
+    LLMConfig,
+    OpenAICompatibleClient,
+    RegretHit,
+    ReportFilter,
+    ReportSnapshot,
+    RiskLevel,
+    SkipRiskReport,
+    TestDecisionExplanation,
+    aggregate_risk_level,
+    beta_smoothed_pass_rate,
+    build_aggregated_ci_stats,
+    build_report_snapshot,
+    build_test_explanation,
+    client_from_env,
+    compute_skip_risk_report,
+    confidence_band,
+    distribution_name,
+    enhance_explanations_with_llm,
+    estimate_from_counts,
+    explain_recommendation,
+    explain_with_optional_llm,
+    export_ci_stats_json,
+    flakiness_estimates,
+    flakiness_for_nodeid,
+    flaky_probability,
+    format_explanations_text,
+    gather_citations,
+    hash_nodeid,
+    import_package_name,
+    llm_config_from_env,
+    matches_filter,
+    nodeid_class,
+    recommend_pytest_command,
+    regret_hits,
+    regret_risk,
+    render_report_view,
+    run_interactive_report,
+    tagline,
+    upload_ci_stats,
+    upload_ci_stats_from_env,
+    write_ci_stats_file,
+)
+
+__all__ = [
+    "VERSION",
+    "__version__",
+    "AggregatedCiStats",
+    "CiUploadError",
+    "ConfidenceBand",
+    "DurationPercentiles",
+    "ExcludedTestRisk",
+    "FlakinessEstimate",
+    "HistoryCitation",
+    "LLMCompletionError",
+    "LLMConfig",
+    "OpenAICompatibleClient",
+    "RegretHit",
+    "ReportFilter",
+    "ReportSnapshot",
+    "RiskLevel",
+    "SkipRiskReport",
+    "TestDecisionExplanation",
+    "aggregate_risk_level",
+    "beta_smoothed_pass_rate",
+    "build_aggregated_ci_stats",
+    "build_report_snapshot",
+    "build_test_explanation",
+    "client_from_env",
+    "confidence_band",
+    "compute_skip_risk_report",
+    "distribution_name",
+    "enhance_explanations_with_llm",
+    "estimate_from_counts",
+    "explain_recommendation",
+    "explain_with_optional_llm",
+    "export_ci_stats_json",
+    "flaky_probability",
+    "flakiness_estimates",
+    "flakiness_for_nodeid",
+    "format_explanations_text",
+    "gather_citations",
+    "hash_nodeid",
+    "import_package_name",
+    "llm_config_from_env",
+    "matches_filter",
+    "nodeid_class",
+    "recommend_pytest_command",
+    "regret_hits",
+    "regret_risk",
+    "render_report_view",
+    "run_interactive_report",
+    "tagline",
+    "upload_ci_stats",
+    "upload_ci_stats_from_env",
+    "write_ci_stats_file",
+]
+
+__version__ = VERSION

testpulse/_distribution.py

@@ -0,0 +1,3 @@
+"""Baked-in distribution name (set at build time)."""
+
+BUILTIN_DISTRIBUTION_NAME = 'testpulse'

testpulse/_entry.py

@@ -0,0 +1,13 @@
+"""Console script entry that bootstraps deployment env before running CLI commands."""
+
+from __future__ import annotations
+
+from testpulse.config import ensure_pypi_package_name_env
+
+
+def cli() -> None:
+    """``testtime`` entry point: ensure ``PYPI_PACKAGE_NAME`` then run the CLI."""
+    ensure_pypi_package_name_env()
+    from testpulse.cli import cli as run_cli
+
+    run_cli()

testpulse/api.py

@@ -0,0 +1,121 @@
+"""Stable public API for TestPulse.
+
+Import from ``testpulse`` or ``testpulse.api``; symbols here remain backward compatible
+across minor releases.
+"""
+
+from __future__ import annotations
+
+from testpulse.ci_stats import (
+    AggregatedCiStats,
+    CiUploadError,
+    DurationPercentiles,
+    build_aggregated_ci_stats,
+    export_ci_stats_json,
+    hash_nodeid,
+    upload_ci_stats,
+    upload_ci_stats_from_env,
+    write_ci_stats_file,
+)
+from testpulse.citations import HistoryCitation, gather_citations
+from testpulse.config import distribution_name, import_package_name
+from testpulse.explanations import (
+    TestDecisionExplanation,
+    build_test_explanation,
+    enhance_explanations_with_llm,
+    explain_recommendation,
+    explain_with_optional_llm,
+    format_explanations_text,
+)
+from testpulse.flakiness import (
+    ConfidenceBand,
+    FlakinessEstimate,
+    beta_smoothed_pass_rate,
+    confidence_band,
+    estimate_from_counts,
+    flakiness_estimates,
+    flakiness_for_nodeid,
+    flaky_probability,
+)
+from testpulse.llm_client import (
+    LLMCompletionError,
+    LLMConfig,
+    OpenAICompatibleClient,
+    client_from_env,
+    llm_config_from_env,
+)
+from testpulse.recommend import recommend_pytest_command
+from testpulse.regret_hits import RegretHit, regret_hits
+from testpulse.report import (
+    ReportFilter,
+    ReportSnapshot,
+    build_report_snapshot,
+    matches_filter,
+    nodeid_class,
+    render_report_view,
+    run_interactive_report,
+)
+from testpulse.risk import (
+    ExcludedTestRisk,
+    RiskLevel,
+    SkipRiskReport,
+    aggregate_risk_level,
+    compute_skip_risk_report,
+    regret_risk,
+)
+
+__all__ = [
+    "VERSION",
+    "AggregatedCiStats",
+    "CiUploadError",
+    "ConfidenceBand",
+    "DurationPercentiles",
+    "ExcludedTestRisk",
+    "FlakinessEstimate",
+    "HistoryCitation",
+    "LLMCompletionError",
+    "LLMConfig",
+    "OpenAICompatibleClient",
+    "RegretHit",
+    "ReportFilter",
+    "ReportSnapshot",
+    "RiskLevel",
+    "SkipRiskReport",
+    "TestDecisionExplanation",
+    "aggregate_risk_level",
+    "beta_smoothed_pass_rate",
+    "build_aggregated_ci_stats",
+    "build_report_snapshot",
+    "build_test_explanation",
+    "client_from_env",
+    "confidence_band",
+    "compute_skip_risk_report",
+    "distribution_name",
+    "enhance_explanations_with_llm",
+    "estimate_from_counts",
+    "explain_recommendation",
+    "explain_with_optional_llm",
+    "export_ci_stats_json",
+    "flaky_probability",
+    "flakiness_estimates",
+    "flakiness_for_nodeid",
+    "format_explanations_text",
+    "gather_citations",
+    "hash_nodeid",
+    "import_package_name",
+    "llm_config_from_env",
+    "matches_filter",
+    "nodeid_class",
+    "recommend_pytest_command",
+    "regret_hits",
+    "regret_risk",
+    "render_report_view",
+    "run_interactive_report",
+    "tagline",
+    "upload_ci_stats",
+    "upload_ci_stats_from_env",
+    "write_ci_stats_file",
+]
+
+VERSION = "0.1.0"
+tagline = "Time your tests, optimize your outcomes."

testpulse/auth_store.py

@@ -0,0 +1,148 @@
+"""Local user store and password hashing (stdlib only)."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+import secrets
+import sqlite3
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def _auth_db_path() -> Path:
+    override = os.environ.get("TESTPULSE_AUTH_DB", "").strip()
+    if override:
+        return Path(override).expanduser()
+    return Path(".testpulse/auth.sqlite3")
+
+
+def _hash_password(password: str, *, salt: bytes | None = None) -> str:
+    salt_bytes = salt or secrets.token_bytes(16)
+    digest = hashlib.pbkdf2_hmac("sha256", password.encode("utf-8"), salt_bytes, 120_000)
+    return f"{salt_bytes.hex()}:{digest.hex()}"
+
+
+def _verify_password(password: str, stored: str) -> bool:
+    try:
+        salt_hex, digest_hex = stored.split(":", 1)
+    except ValueError:
+        return False
+    salt = bytes.fromhex(salt_hex)
+    expected = bytes.fromhex(digest_hex)
+    actual = hashlib.pbkdf2_hmac("sha256", password.encode("utf-8"), salt, 120_000)
+    return hmac.compare_digest(actual, expected)
+
+
+@dataclass(frozen=True)
+class UserRecord:
+    id: int
+    email: str
+
+
+class AuthStore:
+    """SQLite-backed users for the optional HTTP API."""
+
+    def __init__(self, path: Path | None = None) -> None:
+        self._path = path or _auth_db_path()
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(self._path, check_same_thread=False)
+        self._conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS users (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                email TEXT NOT NULL UNIQUE,
+                password_hash TEXT NOT NULL,
+                created_at REAL NOT NULL
+            )
+            """
+        )
+        self._conn.commit()
+
+    def close(self) -> None:
+        self._conn.close()
+
+    def create_user(self, email: str, password: str) -> UserRecord:
+        normalized = email.strip().lower()
+        if not normalized or not password:
+            msg = "email and password are required"
+            raise ValueError(msg)
+        try:
+            cursor = self._conn.execute(
+                "INSERT INTO users (email, password_hash, created_at) VALUES (?, ?, ?)",
+                (normalized, _hash_password(password), time.time()),
+            )
+        except sqlite3.IntegrityError as exc:
+            msg = "email already registered"
+            raise ValueError(msg) from exc
+        self._conn.commit()
+        row_id = cursor.lastrowid
+        if not isinstance(row_id, int):
+            msg = "failed to create user"
+            raise RuntimeError(msg)
+        return UserRecord(id=row_id, email=normalized)
+
+    def authenticate(self, email: str, password: str) -> UserRecord | None:
+        normalized = email.strip().lower()
+        row = self._conn.execute(
+            "SELECT id, email, password_hash FROM users WHERE email = ?",
+            (normalized,),
+        ).fetchone()
+        if row is None:
+            return None
+        user_id, stored_email, password_hash = row
+        if not _verify_password(password, password_hash):
+            return None
+        return UserRecord(id=int(user_id), email=str(stored_email))
+
+    def get_user(self, user_id: int) -> UserRecord | None:
+        row = self._conn.execute(
+            "SELECT id, email FROM users WHERE id = ?",
+            (user_id,),
+        ).fetchone()
+        if row is None:
+            return None
+        return UserRecord(id=int(row[0]), email=str(row[1]))
+
+
+def jwt_secret() -> str | None:
+    secret = os.environ.get("JWT_SECRET", "").strip()
+    return secret or None
+
+
+def issue_token(user_id: int, *, ttl_seconds: int = 3600) -> str:
+    secret = jwt_secret()
+    if secret is None:
+        msg = "JWT_SECRET is not configured"
+        raise RuntimeError(msg)
+    expires = int(time.time()) + ttl_seconds
+    payload = f"{user_id}:{expires}"
+    signature = hmac.new(
+        secret.encode("utf-8"),
+        payload.encode("utf-8"),
+        hashlib.sha256,
+    ).hexdigest()
+    return f"{payload}:{signature}"
+
+
+def verify_token(token: str) -> int | None:
+    secret = jwt_secret()
+    if secret is None:
+        return None
+    try:
+        user_part, expires_part, signature = token.split(":", 2)
+        payload = f"{user_part}:{expires_part}"
+    except ValueError:
+        return None
+    expected = hmac.new(
+        secret.encode("utf-8"),
+        payload.encode("utf-8"),
+        hashlib.sha256,
+    ).hexdigest()
+    if not hmac.compare_digest(expected, signature):
+        return None
+    if int(expires_part) < int(time.time()):
+        return None
+    return int(user_part)

testpulse/bundled_deployment.env

@@ -0,0 +1 @@
+PYPI_PACKAGE_NAME=testpulse

testpulse/ci_stats.py

@@ -0,0 +1,166 @@
+"""Aggregated, de-identified CI stats export and optional upload."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import urllib.error
+import urllib.request
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Literal
+
+from testpulse.flakiness import flakiness_estimates
+from testpulse.store import Store
+
+SCHEMA_VERSION = 1
+
+
+@dataclass(frozen=True)
+class DurationPercentiles:
+    """Aggregate duration percentiles in milliseconds."""
+
+    p50: float
+    p90: float
+    p95: float
+
+
+@dataclass(frozen=True)
+class AggregatedCiStats:
+    """De-identified timing/outcome aggregates safe for CI upload."""
+
+    schema_version: int
+    generated_at: str
+    run_count: int
+    recorded_result_rows: int
+    outcome_totals: dict[str, int]
+    duration_ms: DurationPercentiles
+    flaky_bucket_totals: dict[str, int]
+    unique_tests_hashed: int
+
+
+def _stats_salt() -> str:
+    return os.environ.get("TESTPULSE_STATS_SALT", "testpulse-ci").strip()
+
+
+def hash_nodeid(nodeid: str) -> str:
+    """Return a stable hashed identifier (no raw nodeid)."""
+    digest = hashlib.sha256(f"{_stats_salt()}:{nodeid}".encode()).hexdigest()
+    return digest[:16]
+
+
+def _percentile(values: list[float], pct: float) -> float:
+    if not values:
+        return 0.0
+    ordered = sorted(values)
+    index = int(round((pct / 100.0) * (len(ordered) - 1)))
+    return float(ordered[index])
+
+
+def _flaky_bucket(probability: float) -> Literal["low", "medium", "high"]:
+    if probability < 0.25:
+        return "low"
+    if probability < 0.55:
+        return "medium"
+    return "high"
+
+
+def build_aggregated_ci_stats(store: Store) -> AggregatedCiStats:
+    """Aggregate local store metrics without logs, secrets, or raw nodeids."""
+    runs = store.list_runs()
+    timing = store.timing_stats()
+    durations = [row.avg_duration_ms for row in timing]
+    outcome_totals = {"passed": 0, "failed": 0, "skipped": 0, "other": 0}
+    for row in store.outcome_counts():
+        _ = hash_nodeid(row.nodeid)
+        total = row.passes + row.fails
+        outcome_totals["passed"] += row.passes
+        outcome_totals["failed"] += row.fails
+        if total == 0:
+            outcome_totals["other"] += 1
+
+    flaky_buckets = {"low": 0, "medium": 0, "high": 0}
+    for estimate in flakiness_estimates(store):
+        bucket = _flaky_bucket(estimate.flaky_probability)
+        flaky_buckets[bucket] += 1
+
+    recorded_rows = sum(row.runs for row in timing)
+    return AggregatedCiStats(
+        schema_version=SCHEMA_VERSION,
+        generated_at=datetime.now(tz=UTC).isoformat(),
+        run_count=len(runs),
+        recorded_result_rows=recorded_rows,
+        outcome_totals=outcome_totals,
+        duration_ms=DurationPercentiles(
+            p50=_percentile(durations, 50),
+            p90=_percentile(durations, 90),
+            p95=_percentile(durations, 95),
+        ),
+        flaky_bucket_totals=flaky_buckets,
+        unique_tests_hashed=len(timing),
+    )
+
+
+def export_ci_stats_json(store: Store) -> str:
+    """Serialize de-identified stats for GitHub Actions artifacts or upload."""
+    payload = asdict(build_aggregated_ci_stats(store))
+    return json.dumps(payload, indent=2, sort_keys=True)
+
+
+def write_ci_stats_file(path: Path | str, store: Store) -> Path:
+    """Write de-identified stats JSON to ``path``."""
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(export_ci_stats_json(store), encoding="utf-8")
+    return target
+
+
+class CiUploadError(RuntimeError):
+    """Raised when CI stats upload fails."""
+
+
+def upload_ci_stats(
+    store: Store,
+    *,
+    endpoint_url: str,
+    token: str,
+    timeout_seconds: float = 30.0,
+) -> None:
+    """POST de-identified stats JSON to an HTTPS endpoint (optional GitHub workflow step).
+
+    The caller supplies ``endpoint_url`` and ``token`` (for example repository webhook or
+    GitHub API proxy). No test logs or secrets are included in the payload.
+    """
+    payload = export_ci_stats_json(store).encode("utf-8")
+    request = urllib.request.Request(
+        endpoint_url,
+        data=payload,
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+            "User-Agent": "TestPulse-ci-stats",
+        },
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout_seconds) as response:
+            if response.status >= 300:
+                msg = f"upload failed with status {response.status}"
+                raise CiUploadError(msg)
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")
+        raise CiUploadError(detail or str(exc)) from exc
+    except urllib.error.URLError as exc:
+        raise CiUploadError(str(exc)) from exc
+
+
+def upload_ci_stats_from_env(store: Store) -> bool:
+    """Upload stats when upload URL and token environment variables are set."""
+    url = os.environ.get("TESTPULSE_STATS_UPLOAD_URL", "").strip()
+    token = os.environ.get("TESTPULSE_STATS_UPLOAD_TOKEN", "").strip()
+    if not url or not token:
+        return False
+    upload_ci_stats(store, endpoint_url=url, token=token)
+    return True

testpulse/citations.py

@@ -0,0 +1,115 @@
+"""Local SQLite citation records for explainable recommendations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from testpulse.heuristics import static_pytest_targets
+from testpulse.store import Store
+
+
+@dataclass(frozen=True)
+class HistoryCitation:
+    """Pointer to a single local history record used in an explanation."""
+
+    cite_id: str
+    table: str
+    record_key: str
+    summary: str
+
+
+def nodeid_matches_target(target: str, nodeid: str) -> bool:
+    """Return whether ``nodeid`` equals or lives under pytest target ``target``."""
+    return nodeid == target or nodeid.startswith(f"{target}::")
+
+
+def related_changed_paths(target: str, changed_paths: list[str]) -> list[str]:
+    """Return changed files that statically map to ``target``."""
+    related: list[str] = []
+    for path in changed_paths:
+        if target in static_pytest_targets(path):
+            related.append(path)
+    return related
+
+
+def gather_citations(
+    store: Store,
+    changed_paths: list[str],
+    target: str,
+    *,
+    max_citations: int = 5,
+) -> tuple[HistoryCitation, ...]:
+    """Collect cite-able rows from the SQLite store for one pytest target."""
+    citations: list[HistoryCitation] = []
+    index = 1
+
+    for path in related_changed_paths(target, changed_paths):
+        citations.append(
+            HistoryCitation(
+                cite_id=f"C{index}",
+                table="heuristic",
+                record_key=path,
+                summary=f"Static map from changed file {path!r} to {target!r}",
+            )
+        )
+        index += 1
+
+    linked_nodeids = {target}
+    for nodeid, _score in store.cooccurrence_candidates(changed_paths):
+        if nodeid_matches_target(target, nodeid):
+            linked_nodeids.add(nodeid)
+
+    seen_links: set[str] = set()
+    for nodeid in sorted(linked_nodeids):
+        for path in store.linking_paths_for_test(changed_paths, nodeid):
+            key = f"{path}|{nodeid}"
+            if key in seen_links:
+                continue
+            seen_links.add(key)
+            citations.append(
+                HistoryCitation(
+                    cite_id=f"C{index}",
+                    table="change_test_links",
+                    record_key=key,
+                    summary=f"Learned co-occurrence between {path!r} and {nodeid!r}",
+                )
+            )
+            index += 1
+
+    counts = next(
+        (row for row in store.outcome_counts() if nodeid_matches_target(target, row.nodeid)),
+        None,
+    )
+    if counts is not None:
+        citations.append(
+            HistoryCitation(
+                cite_id=f"C{index}",
+                table="test_results",
+                record_key=counts.nodeid,
+                summary=(
+                    f"Recorded history for {counts.nodeid!r}: "
+                    f"{counts.passes} pass(es), {counts.fails} fail(s)"
+                ),
+            )
+        )
+        index += 1
+
+    timing = next(
+        (row for row in store.timing_stats() if nodeid_matches_target(target, row.nodeid)),
+        None,
+    )
+    if timing is not None:
+        citations.append(
+            HistoryCitation(
+                cite_id=f"C{index}",
+                table="test_results",
+                record_key=f"{target}:timing",
+                summary=(
+                    f"Average duration {timing.avg_duration_ms:.1f} ms "
+                    f"over {timing.runs} run(s)"
+                ),
+            )
+        )
+        index += 1
+
+    return tuple(citations[:max_citations])