patchrail 0.1.0__py3-none-any.whl

patchrail/funded_issues/__init__.py

@@ -0,0 +1,138 @@
+"""Read-only funded issue discovery helpers."""
+
+from patchrail.funded_issues.discovery import (
+    CLIENT_PROFILE_SCHEMA_VERSION,
+    COMPETITION_BATCH_SCHEMA_VERSION,
+    COMPETITION_SIGNAL_SCHEMA_VERSION,
+    PAYOUT_EFFORT_BATCH_SCHEMA_VERSION,
+    PAYOUT_EFFORT_SIGNAL_SCHEMA_VERSION,
+    STALENESS_BATCH_SCHEMA_VERSION,
+    STALENESS_SIGNAL_SCHEMA_VERSION,
+    TESTABILITY_BATCH_SCHEMA_VERSION,
+    TESTABILITY_SIGNAL_SCHEMA_VERSION,
+    ClientProfile,
+    FundedIssue,
+    VALID_OPPORTUNITY_STATES,
+    VALID_RISK_LEVELS,
+    assess_bounty_competition,
+    assess_competition_batch,
+    assess_issue_staleness,
+    assess_issue_testability,
+    assess_payout_effort,
+    assess_payout_effort_batch,
+    assess_staleness_batch,
+    assess_testability_batch,
+    cash_actions_funded_issues,
+    client_report_funded_issues,
+    explain_issue,
+    fulfillment_packet_funded_issues,
+    funded_issues_payload,
+    load_client_profile,
+    load_funded_issues,
+    recheck_funded_issues,
+    report_funded_issues,
+    score_funded_issues,
+    shortlist_funded_issues,
+    summarize_issues,
+    validate_funded_issues,
+)
+from patchrail.funded_issues.algora_board import (
+    ALGORA_BOARD_SCHEMA_VERSION,
+    board_issue_records,
+    board_payload,
+    board_url,
+    parse_board_html,
+)
+from patchrail.funded_issues.blocklist import (
+    BLOCKLIST_SCHEMA_VERSION,
+    BLOCKLISTED_OWNERS,
+    is_blocklisted_owner,
+    is_blocklisted_record,
+    purge_blocklisted_entries,
+)
+from patchrail.funded_issues.importers import SUPPORTED_PROVIDERS, import_provider_export
+from patchrail.funded_issues.source_noise import (
+    SOURCE_NOISE_SCHEMA_VERSION,
+    STRONG_NOISE_FLAGS,
+    apply_source_noise_to_store,
+    assess_owner_source_noise,
+    entries_by_owner,
+)
+from patchrail.funded_issues.store import (
+    RECHECK_SUMMARY_SCHEMA_VERSION,
+    STORE_SCHEMA_VERSION,
+    STORE_STATUS_SCHEMA_VERSION,
+    MergeSummary,
+    RecheckSummary,
+    apply_recheck_to_store,
+    empty_store,
+    load_store,
+    merge_into_store,
+    save_store,
+    store_status,
+)
+
+__all__ = [
+    "FundedIssue",
+    "ALGORA_BOARD_SCHEMA_VERSION",
+    "BLOCKLIST_SCHEMA_VERSION",
+    "BLOCKLISTED_OWNERS",
+    "CLIENT_PROFILE_SCHEMA_VERSION",
+    "COMPETITION_BATCH_SCHEMA_VERSION",
+    "COMPETITION_SIGNAL_SCHEMA_VERSION",
+    "PAYOUT_EFFORT_BATCH_SCHEMA_VERSION",
+    "PAYOUT_EFFORT_SIGNAL_SCHEMA_VERSION",
+    "RECHECK_SUMMARY_SCHEMA_VERSION",
+    "SOURCE_NOISE_SCHEMA_VERSION",
+    "STALENESS_BATCH_SCHEMA_VERSION",
+    "STALENESS_SIGNAL_SCHEMA_VERSION",
+    "STORE_SCHEMA_VERSION",
+    "STORE_STATUS_SCHEMA_VERSION",
+    "STRONG_NOISE_FLAGS",
+    "TESTABILITY_BATCH_SCHEMA_VERSION",
+    "TESTABILITY_SIGNAL_SCHEMA_VERSION",
+    "ClientProfile",
+    "MergeSummary",
+    "RecheckSummary",
+    "SUPPORTED_PROVIDERS",
+    "VALID_OPPORTUNITY_STATES",
+    "VALID_RISK_LEVELS",
+    "assess_bounty_competition",
+    "assess_competition_batch",
+    "assess_issue_staleness",
+    "assess_issue_testability",
+    "assess_payout_effort",
+    "assess_payout_effort_batch",
+    "assess_staleness_batch",
+    "assess_testability_batch",
+    "apply_recheck_to_store",
+    "apply_source_noise_to_store",
+    "assess_owner_source_noise",
+    "board_issue_records",
+    "board_payload",
+    "board_url",
+    "cash_actions_funded_issues",
+    "client_report_funded_issues",
+    "empty_store",
+    "entries_by_owner",
+    "explain_issue",
+    "fulfillment_packet_funded_issues",
+    "funded_issues_payload",
+    "import_provider_export",
+    "is_blocklisted_owner",
+    "is_blocklisted_record",
+    "load_client_profile",
+    "load_funded_issues",
+    "load_store",
+    "merge_into_store",
+    "parse_board_html",
+    "purge_blocklisted_entries",
+    "recheck_funded_issues",
+    "report_funded_issues",
+    "save_store",
+    "score_funded_issues",
+    "shortlist_funded_issues",
+    "store_status",
+    "summarize_issues",
+    "validate_funded_issues",
+]

patchrail/funded_issues/algora_board.py

@@ -0,0 +1,240 @@
+"""Parse a saved Algora organization bounty-board page into funded issues.
+
+Algora renders each organization's public bounty board at
+``https://algora.io/<org>/bounties``. The initial server-rendered HTML carries
+the board's open/completed totals and a table of open bounties with the four
+public facts the tracker needs and that generic issue scraping cannot provide:
+
+* the **funder-stated USD amount** (the board is the funding organization's own
+  listing, so the amount is primary-source evidence, not aggregator hearsay);
+* the GitHub issue URL and reference;
+* the posting age shown on the board;
+* the number of **claims** (declared solve attempts) on the bounty.
+
+This module is a pure, offline parser for a *locally saved copy* of that page:
+save the board with your browser or any HTTP client, then run
+``patchrail funded-issues import-algora-board``. Keeping the fetch outside the
+toolkit preserves the tracker's no-network rule (network access requires
+explicit opt-in) and keeps tests hermetic. Nothing here claims, comments, or
+writes to any third party.
+
+Honesty note: the server-rendered table contains only the first page of open
+bounties (about ten rows); the board's ``open_count`` is still the true total,
+so the payload reports both and never pretends the visible subset is complete.
+"""
+
+from __future__ import annotations
+
+import html as html_lib
+import re
+from typing import Any
+
+from patchrail.funded_issues.discovery import (
+    BLOCKED_ACTIONS,
+    COMPETITION_THRESHOLDS,
+    CONTESTED_BOUNTY_FLAG,
+    FundedIssue,
+    score_funded_issues,
+)
+
+ALGORA_BOARD_SCHEMA_VERSION = "patchrail.funded_issues.algora_board.v1"
+
+# Stable markers in the board's server-rendered markup. The page is a LiveView
+# app, but these classes/attributes have been stable across organizations; the
+# parser fails loudly (ValueError) when the board scaffolding is absent so a
+# login redirect or an unrelated page is never silently parsed as zero bounties.
+_BOARD_MARKER = 'phx-value-tab="open"'
+_ROW_SPLIT_RE = re.compile(r"<tr\b")
+_AMOUNT_RE = re.compile(r"font-extrabold text-emerald-300[^\"]*\">\s*\$([\d,]+(?:\.\d{1,2})?)")
+_ISSUE_LINK_RE = re.compile(
+    r"<a href=\"https://github\.com/([^/\"]+)/([^/\"]+)/issues/(\d+)\"[^>]*class=\"group/issue"
+)
+_TITLE_RE = re.compile(r"line-clamp-2[^\"]*\">\s*(.*?)\s*</p>", re.S)
+_AGE_RE = re.compile(r"text-xs text-gray-400\">\s*([^<]+?)\s*</p>")
+_CLAIMS_RE = re.compile(r">\s*([\d,]+)\s+claims?\s*<")
+_TAB_COUNT_RE_TEMPLATE = r"{label}</div>\s*<span[^>]*>\s*([\d,]+)\s*</span>"
+_AGE_TEXT_RE = re.compile(r"(\d+)\s+(minute|hour|day|week|month|year)s?\s+ago")
+
+_AGE_UNIT_DAYS = {
+    "minute": 0.0,
+    "hour": 1.0 / 24.0,
+    "day": 1.0,
+    "week": 7.0,
+    "month": 30.0,
+    "year": 365.0,
+}
+
+
+def board_url(org: str) -> str:
+    """Public URL of an organization's Algora bounty board."""
+
+    return f"https://algora.io/{org}/bounties"
+
+
+def _to_int(text: str) -> int:
+    return int(text.replace(",", ""))
+
+
+def _tab_count(html: str, label: str) -> int | None:
+    match = re.search(_TAB_COUNT_RE_TEMPLATE.format(label=label), html, re.S)
+    return _to_int(match.group(1)) if match else None
+
+
+def approximate_age_days(text: str) -> int | None:
+    """Approximate days from a board age label like ``"3 weeks ago"``.
+
+    Months count as 30 days and years as 365; sub-day labels round to 0. Returns
+    ``None`` for labels the board has not been observed to use -- an unknown
+    label must read as "age unknown", never as "brand new".
+    """
+
+    match = _AGE_TEXT_RE.search(text.strip().lower())
+    if not match:
+        return None
+    value, unit = int(match.group(1)), match.group(2)
+    return int(value * _AGE_UNIT_DAYS[unit])
+
+
+def _clean_text(value: str) -> str:
+    return re.sub(r"\s+", " ", html_lib.unescape(value)).strip()
+
+
+def parse_board_html(html: str, org: str) -> dict[str, Any]:
+    """Parse one saved board page into a normalized board mapping.
+
+    Returns ``org``, ``source_url``, the board's true ``open_count`` /
+    ``completed_count`` (when rendered), and the visible ``bounties``: each with
+    ``amount_usd``, ``repository`` (GitHub ``owner/repo``, which may differ from
+    the Algora org handle), ``issue_number``, ``url``, ``title``, ``age``
+    (board label plus ``approx_days``), and ``attempt_count`` (declared claims).
+    Rows missing an amount or issue link are skipped rather than guessed.
+    Raises ``ValueError`` when ``html`` is not an Algora bounty board (for
+    example a login redirect).
+    """
+
+    if _BOARD_MARKER not in html:
+        raise ValueError(
+            "source is not a server-rendered Algora bounty board page "
+            "(expected the open-bounties tab marker)"
+        )
+    bounties: list[dict[str, Any]] = []
+    for chunk in _ROW_SPLIT_RE.split(html)[1:]:
+        amount_match = _AMOUNT_RE.search(chunk)
+        link_match = _ISSUE_LINK_RE.search(chunk)
+        if not amount_match or not link_match:
+            continue
+        owner, repo, number = link_match.group(1), link_match.group(2), link_match.group(3)
+        title_match = _TITLE_RE.search(chunk)
+        age_match = _AGE_RE.search(chunk)
+        claims_match = _CLAIMS_RE.search(chunk)
+        age_text = _clean_text(age_match.group(1)) if age_match else None
+        bounties.append(
+            {
+                "amount_usd": float(amount_match.group(1).replace(",", "")),
+                "repository": f"{owner}/{repo}",
+                "issue_number": int(number),
+                "url": f"https://github.com/{owner}/{repo}/issues/{number}",
+                "title": _clean_text(title_match.group(1)) if title_match else "Untitled bounty",
+                "age": {
+                    "text": age_text,
+                    "approx_days": approximate_age_days(age_text) if age_text else None,
+                },
+                "attempt_count": _to_int(claims_match.group(1)) if claims_match else 0,
+            }
+        )
+    return {
+        "schema_version": ALGORA_BOARD_SCHEMA_VERSION,
+        "org": org,
+        "source_url": board_url(org),
+        "open_count": _tab_count(html, "Open"),
+        "completed_count": _tab_count(html, "Completed"),
+        "bounties": bounties,
+        "visible_usd_total": round(sum(b["amount_usd"] for b in bounties), 2),
+        # The server renders only the first page of open bounties; open_count is
+        # the true total, so consumers can see exactly how partial the table is.
+        "server_rendered_rows_only": True,
+    }
+
+
+def board_issue_records(
+    board: dict[str, Any], *, retrieved_at: str | None = None
+) -> list[dict[str, Any]]:
+    """Convert a parsed board into scored, store-ready issue records.
+
+    Each record is a normalized :class:`FundedIssue` mapping (so risk flags,
+    readiness score, and the read-only contract match every other tracker
+    source) extended with the board evidence: ``funding.verified`` /
+    ``funding.evidence_url`` (the funder's own public board), ``attempt_count``,
+    ``posted`` age, and the ``board`` provenance. A bounty whose declared claims
+    reach the contested threshold carries the existing ``contested_bounty``
+    flag. The records feed ``merge_into_store`` directly.
+    """
+
+    contested_at = COMPETITION_THRESHOLDS["distinct_claimants_contested"]
+    issues = []
+    for bounty in board["bounties"]:
+        risk_flags = ["no_contribution_guidelines", "spam_attractive"]
+        if bounty["attempt_count"] >= contested_at:
+            risk_flags.append(CONTESTED_BOUNTY_FLAG)
+        issues.append(
+            FundedIssue(
+                id=f"algora-board-{bounty['repository']}#{bounty['issue_number']}",
+                platform="algora",
+                repository=bounty["repository"],
+                issue_number=bounty["issue_number"],
+                title=bounty["title"],
+                url=bounty["url"],
+                funding_amount=bounty["amount_usd"],
+                funding_currency="USD",
+                labels=["bounty"],
+                risk_flags=sorted(risk_flags),
+                opportunity_state="active",
+            )
+        )
+    by_url = {bounty["url"]: bounty for bounty in board["bounties"]}
+    records: list[dict[str, Any]] = []
+    for row in score_funded_issues(issues)["scores"]:
+        record = dict(row["issue"])
+        record["score"] = row["score"]
+        bounty = by_url[record["url"]]
+        record["funding"] = {
+            **record["funding"],
+            "verified": True,
+            "evidence_url": board["source_url"],
+        }
+        record["attempt_count"] = bounty["attempt_count"]
+        record["posted"] = dict(bounty["age"])
+        record["board"] = {
+            "org": board["org"],
+            "source": "algora_board",
+            "retrieved_at": retrieved_at,
+        }
+        records.append(record)
+    return records
+
+
+def board_payload(
+    board: dict[str, Any], records: list[dict[str, Any]], *, retrieved_at: str | None = None
+) -> dict[str, Any]:
+    """Wrap parsed board records in the standard read-only payload envelope."""
+
+    return {
+        "schema_version": ALGORA_BOARD_SCHEMA_VERSION,
+        "org": board["org"],
+        "source_url": board["source_url"],
+        "retrieved_at": retrieved_at,
+        "open_count": board["open_count"],
+        "completed_count": board["completed_count"],
+        "visible_rows": len(records),
+        "visible_usd_total": board["visible_usd_total"],
+        "server_rendered_rows_only": board["server_rendered_rows_only"],
+        "read_only": True,
+        "blocked_actions": list(BLOCKED_ACTIONS),
+        "requirements": {
+            "network_required": False,
+            "github_write_permission_required": False,
+            "external_model_required": False,
+            "billing_required": False,
+        },
+        "issues": records,
+    }

patchrail/funded_issues/blocklist.py

@@ -0,0 +1,112 @@
+"""Permanent source-level blocklist for the read-only funded-issues tracker.
+
+The owner-level heuristic in :mod:`patchrail.funded_issues.source_noise` flags
+suspicious sources *after* they are already in a tracker store. That is the
+wrong layer for sources that have been positively verified as fake: a honeypot
+owner that floods the feed with templated "Test Bounty" issues and unverifiable
+payouts should never be allowed back in, no matter how its metadata looks on a
+later screening pass.
+
+This module is that hard gate. :data:`BLOCKLISTED_OWNERS` holds owners whose
+listings were manually verified as fake bounty postings (templated test issues,
+no payout trail, throwaway accounts). Records attributed to a blocklisted owner
+are dropped at ingest time by :func:`patchrail.funded_issues.store.merge_into_store`,
+and :func:`purge_blocklisted_entries` removes any that predate the blocklist
+from existing stores -- the ``track`` CLI command runs it on every merge so old
+stores self-heal.
+
+Like the rest of the tracker this module is pure and offline: matching is
+string comparison on already-collected records, nothing here performs a network
+call or writes to any third party. The list is intentionally code, not config:
+removing an owner requires a reviewed change, which is the point.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+BLOCKLIST_SCHEMA_VERSION = "patchrail.funded_issues.blocklist.v1"
+
+# Owners verified as fake-bounty sources (2026-06-10 screening: templated
+# honeypot issues, unverifiable payouts, throwaway accounts). Lowercase.
+# Permanent: entries leave this set only via a reviewed code change.
+BLOCKLISTED_OWNERS = frozenset(
+    {
+        "clankernation",
+        "securebananalabs",
+        "xevrion-v2",
+    }
+)
+
+# Owner extraction mirrors source_noise: GitHub API references keep the owner in
+# a ``/repos/<owner>/`` segment, browser URLs in ``github.com/<owner>/``.
+_REPOS_URL_OWNER_RE = re.compile(r"/repos/([^/]+)/")
+_HTML_URL_OWNER_RE = re.compile(r"github\.com/([^/\s]+)/")
+
+
+def is_blocklisted_owner(owner: Any) -> bool:
+    """True when ``owner`` (case-insensitive) is on the permanent blocklist."""
+
+    return str(owner or "").strip().lower() in BLOCKLISTED_OWNERS
+
+
+def record_owner(record: dict[str, Any]) -> str:
+    """Derive the owning account from a normalized issue record.
+
+    Prefers an explicit ``owner``, then the ``/repos/<owner>/`` segment of the
+    canonical URL, then a ``github.com/<owner>/`` browser URL, and finally the
+    leading segment of ``repository`` (skipping the API-style ``repos/`` prefix).
+    Returns ``""`` when no owner can be derived -- unknown owners are never
+    treated as blocklisted.
+    """
+
+    owner = record.get("owner")
+    if owner:
+        return str(owner)
+    url = str(record.get("url") or "")
+    match = _REPOS_URL_OWNER_RE.search(url)
+    if match:
+        return match.group(1)
+    match = _HTML_URL_OWNER_RE.search(url)
+    if match:
+        return match.group(1)
+    repository = str(record.get("repository") or "")
+    segments = [part for part in repository.split("/") if part]
+    if len(segments) >= 2 and segments[0] == "repos":
+        return segments[1]
+    if segments:
+        return segments[0]
+    return ""
+
+
+def is_blocklisted_record(record: dict[str, Any]) -> bool:
+    """True when a normalized issue record belongs to a blocklisted owner."""
+
+    return is_blocklisted_owner(record_owner(record))
+
+
+def purge_blocklisted_entries(store: dict[str, Any]) -> dict[str, Any]:
+    """Remove every blocklisted owner's entries from ``store`` in place.
+
+    Returns a summary with the number of ``removed`` entries and a sorted
+    ``removed_owners`` list of the blocklisted owners that were present. Safe to
+    run repeatedly; a clean store is left untouched.
+    """
+
+    entries = store.get("entries", {})
+    removed_owners: set[str] = set()
+    removed_urls = []
+    for url, entry in entries.items():
+        issue = entry.get("issue") or {}
+        owner = record_owner(issue) or record_owner({"url": url})
+        if is_blocklisted_owner(owner):
+            removed_urls.append(url)
+            removed_owners.add(owner.lower())
+    for url in removed_urls:
+        del entries[url]
+    return {
+        "schema_version": BLOCKLIST_SCHEMA_VERSION,
+        "removed": len(removed_urls),
+        "removed_owners": sorted(removed_owners),
+    }