patchrail 0.1.0__py3-none-any.whl

patchrail/funded_issues/importers.py

@@ -0,0 +1,316 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from patchrail.funded_issues.discovery import FundedIssue, funded_issues_payload
+
+
+SUPPORTED_PROVIDERS = ("algora", "github", "openpledge", "polar")
+
+_CURRENCY_SYMBOLS = {"$": "USD", "€": "EUR", "£": "GBP", "¥": "JPY"}
+_CURRENCY_CODES = ("USD", "EUR", "GBP", "JPY", "CAD", "AUD")
+_CURRENCY_CODE_PATTERN = re.compile(r"(?i)\b(" + "|".join(_CURRENCY_CODES) + r")\b")
+
+_AMBIGUOUS_SCOPE_TERMS = (
+    "architecture",
+    "broad",
+    "entire",
+    "rewrite",
+    "unclear",
+)
+_SPAM_ATTRACTIVE_LABELS = ("bounty", "reward", "paid")
+_CONTRIBUTION_SIGNAL_LABELS = (
+    "ci",
+    "bug",
+    "good first issue",
+    "good-first-issue",
+    "help wanted",
+    "tests",
+)
+
+
+def import_provider_export(provider: str, source: Path) -> dict[str, Any]:
+    provider = provider.lower()
+    if provider not in SUPPORTED_PROVIDERS:
+        raise ValueError(f"unsupported provider: {provider}")
+    payload = json.loads(source.read_text(encoding="utf-8"))
+    records = _extract_records(payload)
+    issues = [
+        _issue_from_provider_record(provider, record, index) for index, record in enumerate(records)
+    ]
+    return funded_issues_payload(
+        issues,
+        import_source={
+            "provider": provider,
+            "path": str(source),
+            "records_loaded": len(records),
+            "local_file_only": True,
+        },
+    )
+
+
+def _extract_records(payload: Any) -> list[dict[str, Any]]:
+    if isinstance(payload, list):
+        records = payload
+    elif isinstance(payload, dict):
+        for key in ("issues", "items", "bounties", "results", "data"):
+            value = payload.get(key)
+            if isinstance(value, list):
+                records = value
+                break
+        else:
+            records = [payload]
+    else:
+        raise ValueError("provider export must be a JSON object or array")
+    if not all(isinstance(record, dict) for record in records):
+        raise ValueError("provider export records must be objects")
+    return records
+
+
+def _issue_from_provider_record(provider: str, raw: dict[str, Any], index: int) -> FundedIssue:
+    repository = _repository(raw)
+    issue_number = _issue_number(raw)
+    title = _first_string(raw, "title", "name", "summary") or "Untitled funded issue"
+    url = _first_string(raw, "url", "html_url", "issue_url", "github_url") or repository
+    amount, currency = _funding(raw)
+    labels = _labels(raw)
+    contribution_guidelines_url = _first_string(
+        raw,
+        "contribution_guidelines_url",
+        "contributing_url",
+        "guidelines_url",
+    )
+    opportunity_state = _opportunity_state(raw, labels)
+    contribution_signals = _contribution_signals(raw, labels, contribution_guidelines_url)
+    risk_flags = _risk_flags(
+        raw, title, labels, amount, contribution_guidelines_url, opportunity_state
+    )
+    identifier = _first_string(raw, "id", "node_id", "slug") or _stable_id(
+        provider, repository, issue_number, title, index
+    )
+    language = _first_string(raw, "language", "primary_language", "repo_language")
+    return FundedIssue(
+        id=str(identifier),
+        platform=provider,
+        repository=repository,
+        issue_number=issue_number,
+        title=title,
+        url=url,
+        funding_amount=amount,
+        funding_currency=currency,
+        language=language,
+        labels=labels,
+        contribution_signals=contribution_signals,
+        risk_flags=risk_flags,
+        maintainer_permission=str(raw.get("maintainer_permission") or "public_issue_only"),
+        contribution_guidelines_url=contribution_guidelines_url,
+        opportunity_state=opportunity_state,
+    )
+
+
+def _repository(raw: dict[str, Any]) -> str:
+    direct = _first_string(raw, "repository", "repo", "repo_full_name", "full_name")
+    if direct:
+        return direct
+    nested = raw.get("repository")
+    if isinstance(nested, dict):
+        nested_name = _first_string(nested, "full_name", "name")
+        owner = nested.get("owner")
+        if nested_name and "/" in nested_name:
+            return nested_name
+        if isinstance(owner, dict):
+            owner_name = _first_string(owner, "login", "name")
+        else:
+            owner_name = str(owner) if owner else None
+        if owner_name and nested_name:
+            return f"{owner_name}/{nested_name}"
+    owner = _first_string(raw, "owner", "org", "organization")
+    repo_name = _first_string(raw, "repo_name", "project", "name")
+    if owner and repo_name:
+        return f"{owner}/{repo_name}"
+    url = _first_string(raw, "url", "html_url", "issue_url", "github_url") or ""
+    match = re.search(r"github\.com/([^/\s]+/[^/\s#]+)", url)
+    if match:
+        return match.group(1).removesuffix(".git")
+    return "unknown/unknown"
+
+
+def _issue_number(raw: dict[str, Any]) -> int | None:
+    for key in ("issue_number", "number", "github_issue_number", "issue"):
+        value = raw.get(key)
+        if isinstance(value, int):
+            return value
+        if isinstance(value, str) and value.isdigit():
+            return int(value)
+    url = _first_string(raw, "url", "html_url", "issue_url", "github_url") or ""
+    match = re.search(r"/issues/(\d+)", url)
+    return int(match.group(1)) if match else None
+
+
+def _funding(raw: dict[str, Any]) -> tuple[float | None, str | None]:
+    funding = raw.get("funding")
+    if isinstance(funding, dict):
+        raw_amount = funding.get("amount") or funding.get("value") or funding.get("usd")
+        amount = _numeric(raw_amount)
+        currency = _first_string(funding, "currency", "currency_code")
+        return amount, _normalize_currency(currency, raw_amount)
+
+    bounty = raw.get("bounty")
+    if isinstance(bounty, dict):
+        raw_amount = bounty.get("amount") or bounty.get("value") or bounty.get("usd")
+        amount = _numeric(raw_amount)
+        currency = _first_string(bounty, "currency", "currency_code")
+        return amount, _normalize_currency(currency, raw_amount)
+
+    for key in ("amount_usd", "reward_usd", "bounty_usd", "funding_usd"):
+        amount = _numeric(raw.get(key))
+        if amount is not None:
+            return amount, "USD"
+
+    raw_amount = raw.get("amount") or raw.get("reward") or raw.get("bounty_amount")
+    amount = _numeric(raw_amount)
+    currency = _first_string(raw, "currency", "currency_code")
+    return amount, _normalize_currency(currency, raw_amount)
+
+
+def _labels(raw: dict[str, Any]) -> list[str]:
+    labels = raw.get("labels")
+    if not isinstance(labels, list):
+        return []
+    values = []
+    for label in labels:
+        if isinstance(label, dict):
+            value = _first_string(label, "name", "label")
+        else:
+            value = str(label)
+        if value:
+            values.append(value)
+    return values
+
+
+def _contribution_signals(
+    raw: dict[str, Any], labels: list[str], contribution_guidelines_url: str | None
+) -> list[str]:
+    signals = _string_list(raw.get("contribution_signals"))
+    normalized_labels = {label.lower() for label in labels}
+    for label in normalized_labels:
+        if label in _CONTRIBUTION_SIGNAL_LABELS:
+            signals.append(f"label:{label}")
+    body = _first_string(raw, "body", "description") or ""
+    if "reproduction" in body.lower() or "steps to reproduce" in body.lower():
+        signals.append("reproduction included")
+    if contribution_guidelines_url:
+        signals.append("contribution guidelines linked")
+    return sorted(set(signals))
+
+
+def _risk_flags(
+    raw: dict[str, Any],
+    title: str,
+    labels: list[str],
+    amount: float | None,
+    contribution_guidelines_url: str | None,
+    opportunity_state: str,
+) -> list[str]:
+    flags = _string_list(raw.get("risk_flags"))
+    title_lower = title.lower()
+    label_lowers = {label.lower() for label in labels}
+    if any(term in title_lower for term in _AMBIGUOUS_SCOPE_TERMS):
+        flags.append("ambiguous_scope")
+    if any(label in label_lowers for label in _SPAM_ATTRACTIVE_LABELS):
+        flags.append("spam_attractive")
+    if amount is not None and amount >= 1000 and not contribution_guidelines_url:
+        flags.append("spam_attractive")
+    if not contribution_guidelines_url:
+        flags.append("no_contribution_guidelines")
+    if opportunity_state == "stale":
+        flags.append("stale_no_maintainer_signal")
+    if opportunity_state == "closed":
+        flags.append("closed_or_inactive")
+    return sorted(set(flags))
+
+
+def _opportunity_state(raw: dict[str, Any], labels: list[str]) -> str:
+    label_lowers = {label.lower() for label in labels}
+    if "stale" in label_lowers:
+        return "stale"
+    for key in ("opportunity_state", "state", "status", "issue_state"):
+        value = raw.get(key)
+        if isinstance(value, bool):
+            continue
+        if isinstance(value, str) and value.strip():
+            normalized = value.strip().lower().replace("-", "_").replace(" ", "_")
+            if normalized in {"active", "open", "opened", "live", "available"}:
+                return "active"
+            if normalized in {"closed", "completed", "done", "paid", "resolved", "cancelled"}:
+                return "closed"
+            if normalized in {"stale", "inactive", "abandoned", "expired"}:
+                return "stale"
+    for key in ("open", "is_open"):
+        value = raw.get(key)
+        if isinstance(value, bool):
+            return "active" if value else "closed"
+    return "unknown"
+
+
+def _first_string(raw: dict[str, Any], *keys: str) -> str | None:
+    for key in keys:
+        value = raw.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+def _numeric(value: Any) -> float | None:
+    if value is None:
+        return None
+    if isinstance(value, int | float):
+        return float(value)
+    if isinstance(value, str):
+        cleaned = value
+        for symbol in _CURRENCY_SYMBOLS:
+            cleaned = cleaned.replace(symbol, "")
+        cleaned = _CURRENCY_CODE_PATTERN.sub("", cleaned)
+        cleaned = cleaned.replace(",", "").strip()
+        try:
+            return float(cleaned)
+        except ValueError:
+            return None
+    return None
+
+
+def _detect_currency(value: Any) -> str | None:
+    if not isinstance(value, str):
+        return None
+    for symbol, code in _CURRENCY_SYMBOLS.items():
+        if symbol in value:
+            return code
+    match = _CURRENCY_CODE_PATTERN.search(value)
+    if match:
+        return match.group(1).upper()
+    return None
+
+
+def _normalize_currency(explicit: str | None, raw_amount: Any) -> str | None:
+    if explicit:
+        return explicit.upper()
+    return _detect_currency(raw_amount)
+
+
+def _string_list(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [str(item) for item in value if str(item).strip()]
+
+
+def _stable_id(
+    provider: str, repository: str, issue_number: int | None, title: str, index: int
+) -> str:
+    digest = hashlib.sha256(f"{repository}:{issue_number}:{title}:{index}".encode()).hexdigest()[
+        :12
+    ]
+    return f"{provider}-{digest}"

patchrail/funded_issues/source_noise.py

@@ -0,0 +1,349 @@
+"""Owner-level source-noise heuristic for the read-only funded-issues tracker.
+
+The per-issue scoring in :mod:`patchrail.funded_issues.discovery` cannot tell a
+throwaway trap org (a brand-new account spamming near-identical honeypot
+bounties) apart from a credible sponsor running a noisy program -- every issue
+lands at ``risk_level=high`` regardless of *who* posted it. This module adds the
+missing *owner-level* signal: given one owner's already-collected public GitHub
+metadata plus the list of tracker-store entries attributed to that owner, it
+derives a list of ``noise_flags`` and a single ``source_noise`` verdict.
+
+It is pure and fully offline -- callers pass metadata that was gathered
+read-only elsewhere; nothing here performs a network call, and (like the rest of
+the tracker) it never writes to any third party.
+
+Flags
+-----
+Each owner is screened for the following flags (constants below hold the
+thresholds):
+
+* ``new_account`` (strong) -- account younger than
+  :data:`NEW_ACCOUNT_MAX_AGE_DAYS` days.
+* ``no_website`` (strong) -- no public website/blog declared. Absent metadata is
+  treated as "no website": for a noise screen, an unproven signal is a negative
+  one.
+* ``unverifiable_payout`` (strong) -- payout cannot be verified from a primary
+  public source. Absent metadata is likewise treated as unverifiable.
+* ``anomalous_volume`` (strong) -- the owner contributes at least
+  :data:`ANOMALOUS_MIN_VOLUME` tracked entries and at least
+  :data:`ANOMALOUS_DUP_RATIO` of them collapse to one near-identical title
+  signature (the honeypot/aggregator template pattern).
+* ``low_repos`` (supporting) -- at most :data:`LOW_REPO_MAX` public repos.
+* ``few_followers`` (supporting) -- at most :data:`FEW_FOLLOWERS_MAX` followers.
+
+Verdict criterion
+-----------------
+``source_noise`` is ``True`` when the owner trips **at least**
+:data:`STRONG_FLAG_THRESHOLD` *strong* flags (the members of
+:data:`STRONG_NOISE_FLAGS`). Supporting flags add colour to a report but never,
+on their own, flip the verdict -- so a legitimate one-repo sponsor with a
+website and verifiable payouts stays clean, while a new website-less org with
+unverifiable payouts and templated volume is flagged.
+
+Issue-level manual overrides
+----------------------------
+The owner-level pass is necessarily coarse: it condemns or clears *every* issue
+from an owner at once. Sometimes a human needs to override a single issue --
+flag one "Test Bounty" from an otherwise legitimate owner, or clear one issue
+from a flagged owner. :func:`apply_source_noise_to_store` accepts a
+``manual_overrides`` mapping (issue URL -> list of flags) for exactly this. The
+overrides are *issue-level* and always win over the heuristic. Because the
+caller passes them on **every** apply, they survive re-applies of the owner-level
+heuristic that would otherwise reset the entry's ``noise_flags`` -- there is no
+hidden state, just a deterministic re-stamp on each pass.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from typing import Any
+
+SOURCE_NOISE_SCHEMA_VERSION = "patchrail.funded_issues.source_noise.v1"
+
+# Thresholds. Tuned against the 2026-06-10 screening: trap orgs created within
+# the last ~4 weeks with a single repo and a couple of followers.
+NEW_ACCOUNT_MAX_AGE_DAYS = 90
+LOW_REPO_MAX = 1
+FEW_FOLLOWERS_MAX = 5
+ANOMALOUS_MIN_VOLUME = 5
+ANOMALOUS_DUP_RATIO = 0.6
+STRONG_FLAG_THRESHOLD = 2
+
+# Flags that, in sufficient number, flip ``source_noise``. The supporting flags
+# (``low_repos`` / ``few_followers``) are deliberately excluded: weak corporate
+# signals should never condemn an owner on their own.
+STRONG_NOISE_FLAGS = frozenset(
+    {"new_account", "no_website", "unverifiable_payout", "anomalous_volume"}
+)
+
+_TITLE_TOKEN_RE = re.compile(r"[a-z]+")
+# How many leading title tokens form the near-identical signature. Honeypot and
+# aggregator templates share a long fixed prefix; six tokens is enough to cluster
+# them while keeping genuinely distinct issues apart.
+_SIGNATURE_TOKENS = 6
+
+
+def _parse_iso(value: str) -> datetime:
+    text = str(value).strip()
+    if text.endswith("Z"):
+        text = text[:-1] + "+00:00"
+    return datetime.fromisoformat(text)
+
+
+def _account_age_days(metadata: dict[str, Any], now: str | None) -> int | None:
+    """Resolve account age in days, preferring an explicit ``account_age_days``.
+
+    Falls back to ``created_at`` differenced against ``now`` when both are
+    present and parseable. Returns ``None`` when age cannot be established, in
+    which case the ``new_account`` flag is simply not raised.
+    """
+
+    age = metadata.get("account_age_days")
+    if age is not None:
+        try:
+            return int(age)
+        except (TypeError, ValueError):
+            return None
+
+    created_at = metadata.get("created_at")
+    if created_at and now:
+        try:
+            return (_parse_iso(now) - _parse_iso(str(created_at))).days
+        except ValueError:
+            return None
+    return None
+
+
+def _title_signature(title: Any) -> tuple[str, ...]:
+    tokens = _TITLE_TOKEN_RE.findall(str(title).lower())
+    return tuple(tokens[:_SIGNATURE_TOKENS])
+
+
+def _entry_title(entry: dict[str, Any]) -> str:
+    issue = entry.get("issue") or {}
+    return str(issue.get("title") or "")
+
+
+def _is_anomalous_volume(entries: list[dict[str, Any]]) -> bool:
+    """True when the owner posts a high volume of near-identical issue titles.
+
+    Titles are reduced to a leading-token signature; if the largest cluster of
+    identical signatures covers at least :data:`ANOMALOUS_DUP_RATIO` of a
+    sufficiently large batch, the volume is anomalous.
+    """
+
+    total = len(entries)
+    if total < ANOMALOUS_MIN_VOLUME:
+        return False
+    counts: dict[tuple[str, ...], int] = {}
+    for entry in entries:
+        signature = _title_signature(_entry_title(entry))
+        if not signature:
+            continue
+        counts[signature] = counts.get(signature, 0) + 1
+    if not counts:
+        return False
+    largest_cluster = max(counts.values())
+    return largest_cluster / total >= ANOMALOUS_DUP_RATIO
+
+
+_REPOS_URL_OWNER_RE = re.compile(r"/repos/([^/]+)/")
+
+
+def _entry_owner(entry: dict[str, Any]) -> str:
+    """Derive the owning account for a store entry.
+
+    Prefers an explicit ``issue.owner``, then the ``/repos/<owner>/`` segment of
+    ``issue.url`` (the canonical GitHub API reference, always present in stores
+    built by discovery), and finally ``issue.repository`` — which appears both
+    as ``owner/repo`` and as the API-derived ``repos/<owner>`` form.
+    """
+
+    issue = entry.get("issue") or {}
+    owner = issue.get("owner")
+    if owner:
+        return str(owner)
+    match = _REPOS_URL_OWNER_RE.search(str(issue.get("url") or ""))
+    if match:
+        return match.group(1)
+    repository = str(issue.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 repository
+
+
+def assess_owner_source_noise(
+    owner_metadata: dict[str, Any],
+    entries: list[dict[str, Any]],
+    *,
+    now: str | None = None,
+) -> dict[str, Any]:
+    """Screen one owner for source noise from offline public signals.
+
+    ``owner_metadata`` is a mapping of public signals for the owner
+    (``account_age_days`` or ``created_at``, ``public_repos``, ``followers``,
+    ``has_website``, ``payout_verifiable``). ``entries`` is the list of tracker
+    store entries attributed to that owner (used for the volume heuristic).
+
+    Returns a mapping with the sorted ``noise_flags``, the ``strong_flags``
+    subset that drives the verdict, ``strong_flag_count``, the boolean
+    ``source_noise`` verdict (see module docstring for the criterion), and the
+    ``tracked_entries`` count. Performs no network calls.
+    """
+
+    metadata = owner_metadata or {}
+    flags: list[str] = []
+
+    age = _account_age_days(metadata, now)
+    if age is not None and age < NEW_ACCOUNT_MAX_AGE_DAYS:
+        flags.append("new_account")
+
+    public_repos = metadata.get("public_repos")
+    if public_repos is not None and int(public_repos) <= LOW_REPO_MAX:
+        flags.append("low_repos")
+
+    followers = metadata.get("followers")
+    if followers is not None and int(followers) <= FEW_FOLLOWERS_MAX:
+        flags.append("few_followers")
+
+    if not metadata.get("has_website", False):
+        flags.append("no_website")
+
+    if not metadata.get("payout_verifiable", False):
+        flags.append("unverifiable_payout")
+
+    if _is_anomalous_volume(entries):
+        flags.append("anomalous_volume")
+
+    noise_flags = sorted(flags)
+    strong_flags = [flag for flag in noise_flags if flag in STRONG_NOISE_FLAGS]
+    return {
+        "schema_version": SOURCE_NOISE_SCHEMA_VERSION,
+        "noise_flags": noise_flags,
+        "strong_flags": strong_flags,
+        "strong_flag_count": len(strong_flags),
+        "source_noise": len(strong_flags) >= STRONG_FLAG_THRESHOLD,
+        "tracked_entries": len(entries),
+    }
+
+
+def entries_by_owner(store: dict[str, Any]) -> dict[str, list[dict[str, Any]]]:
+    """Group a store's entries by derived owner, preserving entry references."""
+
+    grouped: dict[str, list[dict[str, Any]]] = {}
+    for entry in store.get("entries", {}).values():
+        grouped.setdefault(_entry_owner(entry), []).append(entry)
+    return grouped
+
+
+def _validate_manual_overrides(
+    manual_overrides: dict[str, list[str]] | None,
+) -> dict[str, list[str]]:
+    """Return validated overrides, raising ``ValueError`` on malformed flags.
+
+    Every value must be a list whose members are all non-empty strings. A
+    non-string or empty/blank string is a caller bug, not noise data, so it is
+    rejected loudly rather than silently coerced.
+    """
+
+    overrides = manual_overrides or {}
+    for url, flags in overrides.items():
+        if not isinstance(flags, list):
+            raise ValueError(
+                f"manual_overrides[{url!r}] must be a list of flag strings, "
+                f"got {type(flags).__name__}"
+            )
+        for flag in flags:
+            if not isinstance(flag, str) or not flag.strip():
+                raise ValueError(
+                    f"manual_overrides[{url!r}] contains an invalid flag "
+                    f"{flag!r}: flags must be non-empty strings"
+                )
+    return overrides
+
+
+def apply_source_noise_to_store(
+    store: dict[str, Any],
+    owner_metadata: dict[str, dict[str, Any]] | None = None,
+    *,
+    now: str | None = None,
+    manual_overrides: dict[str, list[str]] | None = None,
+) -> dict[str, Any]:
+    """Stamp the owner-level ``source_noise`` verdict onto store entries in place.
+
+    Entries are grouped by owner; each owner is assessed once via
+    :func:`assess_owner_source_noise` using ``owner_metadata[owner]`` (an empty
+    mapping when absent). Every entry for a *flagged* owner has its
+    ``noise_flags`` set to the owner's flag list; entries for a *clean* owner are
+    reset to ``[]``. This keeps the per-entry ``noise_flags`` an honest mirror of
+    the current owner verdict, so re-applying with refreshed metadata can clear a
+    previously-flagged owner.
+
+    ``manual_overrides`` is an optional, *issue-level* escape hatch mapping an
+    exact ``store["entries"]`` URL key to a list of flag strings. It is applied
+    **after** the owner-level pass and always wins:
+
+    * a non-empty flag list marks the entry as noise -- merged with (and
+      de-duplicated against) any owner-level flags, then sorted -- even when the
+      owner is clean;
+    * an empty list ``[]`` forces the entry clean, overriding a flagged owner.
+
+    Because the caller supplies the overrides on every apply, they persist across
+    re-applies of the heuristic without any stored state. Malformed overrides
+    (non-string or empty flags) raise :class:`ValueError`. Returns a summary of
+    the pass.
+    """
+
+    metadata_by_owner = owner_metadata or {}
+    overrides = _validate_manual_overrides(manual_overrides)
+    summary = {
+        "owners_assessed": 0,
+        "owners_flagged": 0,
+        "owners_without_metadata": [],
+        "entries_flagged": 0,
+        "entries_cleared": 0,
+        "entries_manual_noise": 0,
+        "entries_manual_clean": 0,
+        "manual_urls_not_in_store": [],
+    }
+    entries = store.get("entries", {})
+    for owner, owner_entries in entries_by_owner(store).items():
+        if owner not in metadata_by_owner:
+            # Absent metadata reads as negative signals (see module docstring),
+            # so surface it: a long list here means the caller is screening
+            # owners it never actually looked up.
+            summary["owners_without_metadata"].append(owner)
+        assessment = assess_owner_source_noise(
+            metadata_by_owner.get(owner, {}), owner_entries, now=now
+        )
+        summary["owners_assessed"] += 1
+        flagged = assessment["source_noise"]
+        if flagged:
+            summary["owners_flagged"] += 1
+        for entry in owner_entries:
+            if flagged:
+                entry["noise_flags"] = list(assessment["noise_flags"])
+                summary["entries_flagged"] += 1
+            else:
+                entry["noise_flags"] = []
+                summary["entries_cleared"] += 1
+
+    # Issue-level overrides win over the heuristic. Applied as a second pass over
+    # the store's URL keys so an override on a clean owner's entry still lands.
+    for url, manual_flags in overrides.items():
+        entry = entries.get(url)
+        if entry is None:
+            summary["manual_urls_not_in_store"].append(url)
+            continue
+        if manual_flags:
+            owner_flags = entry.get("noise_flags") or []
+            entry["noise_flags"] = sorted(set(owner_flags) | set(manual_flags))
+            summary["entries_manual_noise"] += 1
+        else:
+            entry["noise_flags"] = []
+            summary["entries_manual_clean"] += 1
+    return summary