From 61c6ca064095a1771ae802f7bcb78d925737a884 Mon Sep 17 00:00:00 2001 From: Foothills Digital Date: Fri, 6 Nov 2026 08:19:05 -0700 Subject: [PATCH 1/2] fix(reports): stop old and already-reviewed reports from hiding an entry on_merge now keeps hidden.json on the stats branch: the entries that are hidden, and when one was last un-hid. A spam or other report only counts toward a hide if it was filed after that un-hide and within the last 30 days. An entry that was hidden at the last hourly look but is visible now counts no reports yet, so the window before on_merge sees the un-hide is covered too. The decide token gets contents: read to fetch hidden.json. --- .github/workflows/reports.yml | 2 ++ GOVERNANCE.md | 2 +- scripts/on_merge.py | 29 +++++++++++++++++++++++- scripts/reports.py | 27 ++++++++++++++++++---- scripts/tests/test_on_merge.py | 41 +++++++++++++++++++++++++++++++++- scripts/tests/test_reports.py | 29 ++++++++++++++++++++++-- 6 files changed, 121 insertions(+), 9 deletions(-) diff --git a/.github/workflows/reports.yml b/.github/workflows/reports.yml index ffd29c2..9563524 100644 --- a/.github/workflows/reports.yml +++ b/.github/workflows/reports.yml @@ -41,6 +41,7 @@ jobs: python-version: "3.12" # Org block reads need an App token; GITHUB_TOKEN can't see them. # actions: read lists recent health checks, so a dead report doesn't queue a repeat. + # contents: read reads hidden.json on the stats branch, so reports from before an un-hide don't count. - id: token uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0 with: @@ -49,6 +50,7 @@ jobs: permission-organization-user-blocking: read permission-issues: read permission-actions: read + permission-contents: read # An API failure exits non-zero with no result file, so nothing is acted on. # It also writes undecided.json, counted below; a rate limit that hasn't reset yet writes nothing. # A dispatched issue that is already handled, or a bot's issue, exits 0 with no result file. diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 5e66af1..e756286 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -22,7 +22,7 @@ When a case doesn't fit the rules, a human looks at it. Anything a bot can't dec ## Moderation -Anyone can [report an entry](https://github.com/devstreamhq/devstream/issues/new?template=report-entry.yml), and every report about a listed repo goes into the review queue. Some reports also act straight away. When 3 established accounts report the same entry as spam, or one established account reports it as malicious, the entry is hidden while I review it. A report that an entry is dead queues a health check. +Anyone can [report an entry](https://github.com/devstreamhq/devstream/issues/new?template=report-entry.yml), and every report about a listed repo goes into the review queue. Some reports also act straight away. When 3 established accounts report the same entry as spam within 30 days, or one established account reports it as malicious, the entry is hidden while I review it. If I un-hide it, only reports filed after that count toward hiding it again. A report that an entry is dead queues a health check. Submissions whose description matches a term in `scripts/blocklist.txt` (SEO, casino, scam and similar spam) are rejected. Everything else is moderated by hand. diff --git a/scripts/on_merge.py b/scripts/on_merge.py index 40a691c..ba4637f 100644 --- a/scripts/on_merge.py +++ b/scripts/on_merge.py @@ -1,6 +1,7 @@ import os import logging import time +from datetime import datetime, timezone from scripts.devstream import entries as entries_mod from scripts.devstream.discussions import ensure_discussion, likes_category, list_discussions @@ -76,8 +77,34 @@ def done(stored): logging.exception("could not write discussions.json or renames.json") +def track_hidden(gh, entries, now: datetime) -> None: + """Keep hidden.json: which entries are hidden, and when a maintainer last un-hid one. + + reports.py ignores reports filed before an un-hide, so the reports already reviewed can't hide it again. + shortcut: an hourly snapshot misses a hide and un-hide inside the same hour; record both from + the hide job if that ever matters. + """ + listed = {normalize_repo(e["repo"]): e["status"] == "hidden" for e in entries} + stamp = now.strftime("%Y-%m-%dT%H:%M:%SZ") + + def mutate(stored): + out = {} + for k, hidden in listed.items(): + was = stored.get(k) or {} + if hidden: + out[k] = {"hidden": True, "unhidden_at": was.get("unhidden_at")} + elif was.get("hidden"): + out[k] = {"hidden": False, "unhidden_at": stamp} + elif was: + out[k] = was + return out + update_json(gh, "hidden.json", mutate, "chore(stats): track hidden entries") + + def main(): - run(GitHub(os.environ["GITHUB_TOKEN"]), entries_mod.load()) + gh, entries = GitHub(os.environ["GITHUB_TOKEN"]), entries_mod.load() + track_hidden(gh, entries, datetime.now(timezone.utc)) + run(gh, entries) if __name__ == "__main__": diff --git a/scripts/reports.py b/scripts/reports.py index 6d1bcf6..fe1bf52 100644 --- a/scripts/reports.py +++ b/scripts/reports.py @@ -23,6 +23,7 @@ from scripts.devstream.entries import DEFAULT_PATH, find, load, normalize_repo, save from scripts.devstream.gh import GitHub from scripts.devstream.issue_form import FormError, _repo, parse_report +from scripts.devstream.stats import read_json from scripts.devstream.trust import ACTIVITY_QUERY, LOGIN_RE, blocked_logins, check_user from scripts.validate_data import validate @@ -48,6 +49,8 @@ ) RATE_LIMIT = "You've hit the daily limit of 5 reports. Try again tomorrow." COUNTED = ("spam", "other") +# A spam or other report counts toward a hide for this long. +REPORT_MAX_AGE = timedelta(days=30) ERROR = "Something went wrong on our side while handling this report. We've been pinged and will sort it out.\n" @@ -122,11 +125,27 @@ def _unedited(gh, numbers: list[int]) -> set[int]: return {n for k, n in enumerate(numbers) if (data.get(f"i{k}") or {"lastEditedAt": "gone"})["lastEditedAt"] is None} -def _reporters(repo: str, open_reports: list[dict], gh) -> set[str]: - """Distinct human logins with an open, unedited spam or other report on repo.""" +def _parse(s: str) -> datetime: + return datetime.fromisoformat(s.replace("Z", "+00:00")) + + +def _counts_since(repo: str, gh, now: datetime) -> datetime: + """Reports filed before this don't count: too old, or already reviewed when a maintainer un-hid the entry.""" + since = now - REPORT_MAX_AGE + rec = (read_json(gh, "hidden.json")[0] or {}).get(normalize_repo(repo)) or {} + if rec.get("hidden"): + # Hidden at on_merge's last look but visible now: un-hidden within the hour, after every report so far. + return now + if rec.get("unhidden_at"): + since = max(since, _parse(rec["unhidden_at"])) + return since + + +def _reporters(repo: str, open_reports: list[dict], gh, since: datetime) -> set[str]: + """Distinct human logins with an open, unedited spam or other report on repo, filed after since.""" found = {} for r in open_reports: - if _is_bot(r) or "pull_request" in r: + if _is_bot(r) or "pull_request" in r or _parse(r["created_at"]) < since: continue try: form = parse_report(r.get("body") or "") @@ -190,7 +209,7 @@ def handle_report(issue: dict, gh, entries: list, open_reports: list[dict], if reason in ("spam", "other"): counted = 0 others = [r for r in open_reports if r.get("number") != issue["number"]] - for who in sorted(_reporters(repo, [issue, *others], gh)): + for who in sorted(_reporters(repo, [issue, *others], gh, _counts_since(repo, gh, now))): if check_user(who, gh, now, excluded) is None and _established(who, gh, now): counted += 1 if counted >= HIDE_AT: diff --git a/scripts/tests/test_on_merge.py b/scripts/tests/test_on_merge.py index 56d4ad8..c618b49 100644 --- a/scripts/tests/test_on_merge.py +++ b/scripts/tests/test_on_merge.py @@ -4,7 +4,9 @@ from pathlib import Path from scripts.devstream.gh import GitHubError -from scripts.on_merge import CAP, run +from datetime import datetime, timezone + +from scripts.on_merge import CAP, run, track_hidden from scripts.tests.fake_gh import FakeGitHub FILE = "/repos/devstreamhq/devstream/contents/discussions.json" @@ -158,6 +160,43 @@ def step_after(text, marker): return text[text.index(marker):] +HIDDEN = "/repos/devstreamhq/devstream/contents/hidden.json" +AT = datetime(2026, 11, 6, 15, 0, tzinfo=timezone.utc) + + +def hidden_gh(stored=None): + routes = {f"PUT {HIDDEN}": {}} + if stored is not None: + routes[f"GET {HIDDEN}"] = {"content": base64.b64encode(json.dumps(stored).encode()).decode(), "sha": "h1"} + return FakeGitHub(routes) + + +class TrackHidden(unittest.TestCase): + def test_records_hidden_entries_only(self): + g = hidden_gh() + track_hidden(g, [entry(1), entry(2, "hidden")], AT) + self.assertEqual(written(g), {"o/r2": {"hidden": True, "unhidden_at": None}}) + + def test_stamps_an_unhide(self): + g = hidden_gh({"o/r1": {"hidden": True, "unhidden_at": None}}) + track_hidden(g, [entry(1)], AT) + self.assertEqual(written(g), {"o/r1": {"hidden": False, "unhidden_at": "2026-11-06T15:00:00Z"}}) + + def test_keeps_the_stamp_and_drops_entries_off_the_list(self): + stamp = {"hidden": False, "unhidden_at": "2026-10-01T00:00:00Z"} + g = hidden_gh({"o/r1": stamp, "o/gone": {"hidden": True, "unhidden_at": None}}) + track_hidden(g, [entry(1)], AT) + self.assertEqual(written(g), {"o/r1": stamp}) + g = hidden_gh({"o/r1": stamp}) + track_hidden(g, [entry(1, "hidden")], AT) + self.assertEqual(written(g), {"o/r1": {"hidden": True, "unhidden_at": "2026-10-01T00:00:00Z"}}) + + def test_no_put_when_unchanged(self): + g = hidden_gh({"o/r2": {"hidden": True, "unhidden_at": None}}) + track_hidden(g, [entry(1), entry(2, "hidden")], AT) + self.assertEqual(puts(g), []) + + class Workflows(unittest.TestCase): """Threads are made by the run that changed the list, while it still holds list-writes.""" diff --git a/scripts/tests/test_reports.py b/scripts/tests/test_reports.py index 62056ce..f9f2be1 100644 --- a/scripts/tests/test_reports.py +++ b/scripts/tests/test_reports.py @@ -1,3 +1,4 @@ +import base64 import io import json import os @@ -33,9 +34,9 @@ def body(entry="https://github.com/alice/tool", reason="Spam or SEO", superseded ) -def report(n=7, login="carol", user_type="User", **kw): +def report(n=7, login="carol", user_type="User", age=timedelta(hours=1), **kw): return {"number": n, "title": "Report: alice/tool", "user": {"login": login, "type": user_type}, - "body": body(**kw), "labels": [{"name": "report"}], "state": "open"} + "body": body(**kw), "labels": [{"name": "report"}], "state": "open", "created_at": iso(NOW - age)} def entry(repo="alice/tool", status="live"): @@ -98,6 +99,11 @@ def edits(v): return FakeGitHub(routes) +def hidden_json(data): + raw = base64.b64encode(json.dumps(data).encode()).decode() + return {f"GET {API}/contents/hidden.json": {"content": raw, "sha": "h1"}} + + def run(i=None, g=None, entries=None, open_reports=()): i = report() if i is None else i return handle_report(i, g or gh(), [entry()] if entries is None else entries, @@ -124,6 +130,25 @@ def test_three_distinct_trusted_hides(self): self.assertIn("needs-review", labels(actions)) self.assertIn("`alice/tool` is hidden", comments(actions)[0]) + def test_old_reports_stop_counting(self): + self.assertNotIn("hide", kinds(run(open_reports=[report(8, "dave"), report(9, "erin", age=timedelta(days=31))]))) + self.assertIn("hide", kinds(run(open_reports=[report(8, "dave"), report(9, "erin", age=timedelta(days=29))]))) + + def test_only_reports_after_an_unhide_count(self): + g = gh(extra=hidden_json({"alice/tool": {"hidden": False, "unhidden_at": iso(NOW - timedelta(hours=2))}})) + before = [report(8, "dave", age=timedelta(hours=3)), report(9, "erin", age=timedelta(hours=3))] + self.assertNotIn("hide", kinds(run(g=g, open_reports=before))) + after = [report(8, "dave"), report(9, "erin")] + self.assertIn("hide", kinds(run(g=g, open_reports=after))) + + def test_unhidden_since_the_last_snapshot_counts_nothing_yet(self): + g = gh(extra=hidden_json({"alice/tool": {"hidden": True, "unhidden_at": None}})) + self.assertNotIn("hide", kinds(run(g=g, open_reports=[report(8, "dave"), report(9, "erin")]))) + + def test_unhide_of_another_entry_does_not_matter(self): + g = gh(extra=hidden_json({"alice/other": {"hidden": True, "unhidden_at": None}})) + self.assertIn("hide", kinds(run(g=g, open_reports=[report(8, "dave"), report(9, "erin")]))) + def test_something_else_counts_the_same_way(self): others = [report(8, "dave"), report(9, "erin")] actions = run(report(reason="Something else"), open_reports=others) From 39ae24e0ac68f913b2038c62b6d67e2a319998af Mon Sep 17 00:00:00 2001 From: Foothills Digital Date: Fri, 6 Nov 2026 08:30:08 -0700 Subject: [PATCH 2/2] fix(reports): keep the sync going and parse hidden.json dates strictly --- scripts/on_merge.py | 11 +++++++++-- scripts/reports.py | 18 +++++++++++++----- scripts/tests/test_on_merge.py | 26 +++++++++++++++++++++----- scripts/tests/test_reports.py | 22 ++++++++++++++++++++-- 4 files changed, 63 insertions(+), 14 deletions(-) diff --git a/scripts/on_merge.py b/scripts/on_merge.py index ba4637f..33ce0d5 100644 --- a/scripts/on_merge.py +++ b/scripts/on_merge.py @@ -81,8 +81,11 @@ def track_hidden(gh, entries, now: datetime) -> None: """Keep hidden.json: which entries are hidden, and when a maintainer last un-hid one. reports.py ignores reports filed before an un-hide, so the reports already reviewed can't hide it again. + seen_at on a hidden record says when this run last saw it hidden. shortcut: an hourly snapshot misses a hide and un-hide inside the same hour; record both from the hide job if that ever matters. + shortcut: records are keyed by name, so a hidden entry renamed by rot loses its record; key by + repo_id if that matters. """ listed = {normalize_repo(e["repo"]): e["status"] == "hidden" for e in entries} stamp = now.strftime("%Y-%m-%dT%H:%M:%SZ") @@ -92,7 +95,7 @@ def mutate(stored): for k, hidden in listed.items(): was = stored.get(k) or {} if hidden: - out[k] = {"hidden": True, "unhidden_at": was.get("unhidden_at")} + out[k] = {"hidden": True, "unhidden_at": was.get("unhidden_at"), "seen_at": stamp} elif was.get("hidden"): out[k] = {"hidden": False, "unhidden_at": stamp} elif was: @@ -103,7 +106,11 @@ def mutate(stored): def main(): gh, entries = GitHub(os.environ["GITHUB_TOKEN"]), entries_mod.load() - track_hidden(gh, entries, datetime.now(timezone.utc)) + try: + track_hidden(gh, entries, datetime.now(timezone.utc)) + except Exception: + # Old reports may count for a while; that mustn't stop the Discussions sync. + logging.exception("could not write hidden.json") run(gh, entries) diff --git a/scripts/reports.py b/scripts/reports.py index fe1bf52..b997b65 100644 --- a/scripts/reports.py +++ b/scripts/reports.py @@ -51,6 +51,9 @@ COUNTED = ("spam", "other") # A spam or other report counts toward a hide for this long. REPORT_MAX_AGE = timedelta(days=30) +# hidden.json saying hidden while the entry is visible means "just un-hidden" only while on_merge is keeping it fresh. +JUST_UNHIDDEN = timedelta(hours=2) +TIMESTAMP = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z") ERROR = "Something went wrong on our side while handling this report. We've been pinged and will sort it out.\n" @@ -125,18 +128,23 @@ def _unedited(gh, numbers: list[int]) -> set[int]: return {n for k, n in enumerate(numbers) if (data.get(f"i{k}") or {"lastEditedAt": "gone"})["lastEditedAt"] is None} -def _parse(s: str) -> datetime: - return datetime.fromisoformat(s.replace("Z", "+00:00")) +def _parse(s) -> datetime: + """Strict UTC timestamp: fromisoformat would take a bare date or a naive time.""" + if not isinstance(s, str) or not TIMESTAMP.fullmatch(s): + raise ValueError(f"bad timestamp: {s!r}") + return datetime.strptime(s, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc) def _counts_since(repo: str, gh, now: datetime) -> datetime: """Reports filed before this don't count: too old, or already reviewed when a maintainer un-hid the entry.""" since = now - REPORT_MAX_AGE + # No hidden.json yet means the plain 30-day window, as before it existed. rec = (read_json(gh, "hidden.json")[0] or {}).get(normalize_repo(repo)) or {} - if rec.get("hidden"): - # Hidden at on_merge's last look but visible now: un-hidden within the hour, after every report so far. + # Hidden at on_merge's last look but visible now: un-hidden since, after every report so far. + # A stale look means on_merge is failing, so fall back rather than block hides indefinitely. + if rec.get("hidden") and now - _parse(rec.get("seen_at")) <= JUST_UNHIDDEN: return now - if rec.get("unhidden_at"): + if rec.get("unhidden_at") is not None: since = max(since, _parse(rec["unhidden_at"])) return since diff --git a/scripts/tests/test_on_merge.py b/scripts/tests/test_on_merge.py index c618b49..441826c 100644 --- a/scripts/tests/test_on_merge.py +++ b/scripts/tests/test_on_merge.py @@ -1,12 +1,13 @@ import base64 import json import unittest +from unittest import mock from pathlib import Path from scripts.devstream.gh import GitHubError from datetime import datetime, timezone -from scripts.on_merge import CAP, run, track_hidden +from scripts.on_merge import CAP, main, run, track_hidden from scripts.tests.fake_gh import FakeGitHub FILE = "/repos/devstreamhq/devstream/contents/discussions.json" @@ -175,7 +176,7 @@ class TrackHidden(unittest.TestCase): def test_records_hidden_entries_only(self): g = hidden_gh() track_hidden(g, [entry(1), entry(2, "hidden")], AT) - self.assertEqual(written(g), {"o/r2": {"hidden": True, "unhidden_at": None}}) + self.assertEqual(written(g), {"o/r2": {"hidden": True, "unhidden_at": None, "seen_at": "2026-11-06T15:00:00Z"}}) def test_stamps_an_unhide(self): g = hidden_gh({"o/r1": {"hidden": True, "unhidden_at": None}}) @@ -189,13 +190,28 @@ def test_keeps_the_stamp_and_drops_entries_off_the_list(self): self.assertEqual(written(g), {"o/r1": stamp}) g = hidden_gh({"o/r1": stamp}) track_hidden(g, [entry(1, "hidden")], AT) - self.assertEqual(written(g), {"o/r1": {"hidden": True, "unhidden_at": "2026-10-01T00:00:00Z"}}) + self.assertEqual(written(g), {"o/r1": {"hidden": True, "unhidden_at": "2026-10-01T00:00:00Z", + "seen_at": "2026-11-06T15:00:00Z"}}) def test_no_put_when_unchanged(self): - g = hidden_gh({"o/r2": {"hidden": True, "unhidden_at": None}}) - track_hidden(g, [entry(1), entry(2, "hidden")], AT) + g = hidden_gh({"o/r2": {"hidden": False, "unhidden_at": "2026-10-01T00:00:00Z"}}) + track_hidden(g, [entry(1), entry(2)], AT) self.assertEqual(puts(g), []) + def test_failed_hidden_write_still_syncs_discussions(self): + g = gh() + + def boom(b): + raise GitHubError(500, "boom") + g.routes[f"PUT {HIDDEN}"] = boom + with mock.patch("scripts.on_merge.GitHub", return_value=g), \ + mock.patch("scripts.on_merge.entries_mod.load", return_value=[entry(1), entry(2, "hidden")]), \ + mock.patch.dict("os.environ", {"GITHUB_TOKEN": "t"}), \ + self.assertLogs(level="ERROR") as logs: + main() + self.assertIn("could not write hidden.json", logs.output[0]) + self.assertEqual(written(g), {"o/r1": 101}) + class Workflows(unittest.TestCase): """Threads are made by the run that changed the list, while it still holds list-writes.""" diff --git a/scripts/tests/test_reports.py b/scripts/tests/test_reports.py index f9f2be1..0bd5e82 100644 --- a/scripts/tests/test_reports.py +++ b/scripts/tests/test_reports.py @@ -142,11 +142,29 @@ def test_only_reports_after_an_unhide_count(self): self.assertIn("hide", kinds(run(g=g, open_reports=after))) def test_unhidden_since_the_last_snapshot_counts_nothing_yet(self): - g = gh(extra=hidden_json({"alice/tool": {"hidden": True, "unhidden_at": None}})) + rec = {"hidden": True, "unhidden_at": None, "seen_at": iso(NOW - timedelta(minutes=50))} + g = gh(extra=hidden_json({"alice/tool": rec})) self.assertNotIn("hide", kinds(run(g=g, open_reports=[report(8, "dave"), report(9, "erin")]))) + def test_stale_snapshot_falls_back_to_the_window(self): + rec = {"hidden": True, "unhidden_at": None, "seen_at": iso(NOW - timedelta(hours=3))} + g = gh(extra=hidden_json({"alice/tool": rec})) + self.assertIn("hide", kinds(run(g=g, open_reports=[report(8, "dave"), report(9, "erin")]))) + + def test_unreadable_hidden_json_raises_and_hides_nothing(self): + raw = base64.b64encode(b"{not json").decode() + g = gh(extra={f"GET {API}/contents/hidden.json": {"content": raw, "sha": "h1"}}) + with self.assertRaises(ValueError): + run(g=g, open_reports=[report(8, "dave"), report(9, "erin")]) + + def test_malformed_or_naive_unhidden_at_raises(self): + for bad in ("2026-11-05", "2026-11-05T10:00:00", "2026-11-05T10:00:00+00:00", "2026-11-05T10:00:00Z", 5): + g = gh(extra=hidden_json({"alice/tool": {"hidden": False, "unhidden_at": bad}})) + with self.assertRaises(ValueError, msg=bad): + run(g=g, open_reports=[report(8, "dave"), report(9, "erin")]) + def test_unhide_of_another_entry_does_not_matter(self): - g = gh(extra=hidden_json({"alice/other": {"hidden": True, "unhidden_at": None}})) + g = gh(extra=hidden_json({"alice/other": {"hidden": True, "unhidden_at": None, "seen_at": iso(NOW)}})) self.assertIn("hide", kinds(run(g=g, open_reports=[report(8, "dave"), report(9, "erin")]))) def test_something_else_counts_the_same_way(self):