GitHub App that scores pull requests for spam likelihood and posts a Coveralls-style commit status. PRs scoring ≥ 70% fail the check until a maintainer overrides.

Phase 3 status

• PR comment with score breakdown (upsert via <!-- pr-spam-checker -->)
• Repo-rules analyzer (issue refs, sections, forbidden phrases/paths)
• Comments on medium+ risk PRs (warn_threshold or always_comment)

Phase 2 status

• Types, Zod config loader, weighted scorer
• Analyzers: reputation, description, diff, AI patterns
• Pipeline runs analyzers in parallel and posts tiered status
• Unit tests for scorer, description analyzer, and score thresholds

Phase 1 status

• Probot + TypeScript scaffold
• pull_request webhook handler (opened, synchronize, reopened)
• Pending → success commit status (pr-spam-checker/status)
• GitHub App registered and installed on a test repo

Quick start (local)

1. Install dependencies

npm install
npm run build

2. Create a GitHub App

Option A — Probot setup (recommended for local dev)

npm run dev

Probot prints a URL to create and configure the app from app.yml. Follow the prompts.

Option B — Manual registration

1. Go to github.com/settings/apps/new
2. Set webhook URL to your tunnel endpoint + /api/github/webhooks
3. Webhook secret: generate one and save it
4. Permissions:
   • Pull requests: Read & write
   • Commit statuses: Read & write
   • Contents: Read-only
   • Issues: Read & write
   • Metadata: Read-only
5. Subscribe to events: Pull request, Issue comment
6. Generate a private key and note the App ID

3. Configure environment

Copy .env.example to .env and fill in:

4. Forward webhooks locally

In a second terminal:

npx smee -u $WEBHOOK_PROXY_URL -t http://localhost:3000

Or use Cloudflare Tunnel:

cloudflared tunnel --url http://localhost:3000

Paste the public URL into your GitHub App webhook settings as https://<host>/api/github/webhooks.

5. Install the app on a test repo

GitHub App settings → Install App → select a repository.

6. Verify

Open a pull request on the test repo. You should see:

1. Pending — PR Spam Check: analyzing...
2. Success — PR Spam Check: passed (0%)

Branch protection (required to block merges in later phases)

Repo Settings → Branches → Add rule:

• Require status check: pr-spam-checker/status

Scripts

Project layout

src/
  index.ts          # Webhook handlers
  pipeline.ts         # Analysis orchestration
  report/status.ts    # Commit status posting
  constants.ts        # Shared constants

License

MIT