Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/reports.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion GOVERNANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
36 changes: 35 additions & 1 deletion scripts/on_merge.py
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -76,8 +77,41 @@ 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.
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")

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"), "seen_at": stamp}
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()
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)


if __name__ == "__main__":
Expand Down
35 changes: 31 additions & 4 deletions scripts/reports.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -48,6 +49,11 @@
)
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)
# 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"


Expand Down Expand Up @@ -122,11 +128,32 @@ 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) -> 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 {}
# 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") is not None:
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 "")
Expand Down Expand Up @@ -190,7 +217,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:
Expand Down
57 changes: 56 additions & 1 deletion scripts/tests/test_on_merge.py
Original file line number Diff line number Diff line change
@@ -1,10 +1,13 @@
import base64
import json
import unittest
from unittest import mock
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, main, run, track_hidden
from scripts.tests.fake_gh import FakeGitHub

FILE = "/repos/devstreamhq/devstream/contents/discussions.json"
Expand Down Expand Up @@ -158,6 +161,58 @@ 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, "seen_at": "2026-11-06T15:00:00Z"}})

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",
"seen_at": "2026-11-06T15:00:00Z"}})

def test_no_put_when_unchanged(self):
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."""

Expand Down
47 changes: 45 additions & 2 deletions scripts/tests/test_reports.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import base64
import io
import json
import os
Expand Down Expand Up @@ -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"):
Expand Down Expand Up @@ -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,
Expand All @@ -124,6 +130,43 @@ 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):
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, "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):
others = [report(8, "dave"), report(9, "erin")]
actions = run(report(reason="Something else"), open_reports=others)
Expand Down
Loading