# 🎮 Try the instant interactive simulator in your terminal
pip install slopgate-cli
slopgate demo

💥 The Problem: "Death by a Thousand Slops"

"The telltale signs are always the same: reports that arrive as walls of perfectly formatted text, complete with extensive bullet point lists and flawless English... and debugging information for functions that do not exist. This low-effort, high-impact abuse pattern is a denial-of-service attack on open source."
— Daniel Stenberg, Founder & Maintainer of curl

According to recent open-source ecosystem studies, maintainers now spend over 60% of their engineering capacity on maintenance and triage.

With the explosive rise of AI coding agents, thousands of automated and hallucinated pull requests are submitted daily. These PRs look clean on the surface:

1. They pass CI by weakening tests: Deleting assert statements or changing assert result == expected to assert result is not None or assert True.
2. They hallucinate libraries: Importing non-existent cloud packages or inventing fake methods on standard library objects (json.loads_async, os.mkdir_p).
3. They bury trivial logic in 50 lines of AI docstring buzzwords: Masking unverified code diffs behind walls of AI-generated markdown.

Existing "AI detector" tools try to detect "AI-sounding English text." That is the wrong layer to inspect. It creates false positives on non-native English speakers while letting broken code slip right through.

SlopGate does not judge your English. SlopGate enforces Code & Test Invariants.

⚡ How It Works

SlopGate parses the unified git diff directly into an AST (Abstract Syntax Tree) in < 50 milliseconds:

flowchart TD
    PR["📥 Pull Request Opened / Synchronized"] --> SG["🛡️ SlopGate AST Engine (< 0.05s)"]

    subgraph SG["🛡️ SlopGate Core (Zero Dependencies)"]
        direction TB
        T1["1. Test Tamper Guard<br/>Assertion deletions · Tautology swaps · try-except pass"]
        T2["2. Phantom Symbol Interceptor<br/>Hallucinated imports · Non-existent stdlib methods"]
        T3["3. Reproduction Gate<br/>Verifies if bugfix PR includes a test case"]
        T4["4. Slop Ratio Analyzer<br/>Docstring bloat vs executable AST nodes"]
        T1 --- T2 --- T3 --- T4
    end

    SG -->|"Integrity Intact"| PASS["✅ PASSED<br/>PR Approved for Human Review"]
    SG -->|"Tampered / Hallucinated"| BLOCK["⛔ BLOCKED<br/>GitHub Step Summary + Inline Annotations"]

    style PR fill:#1e293b,stroke:#3b82f6,color:#fff
    style SG fill:#0f172a,stroke:#22c55e,color:#fff
    style PASS fill:#064e3b,stroke:#22c55e,color:#fff
    style BLOCK fill:#450a0a,stroke:#ef4444,color:#fff

🖥️ Live Terminal Simulation

Run slopgate demo to see SlopGate catch 3 real-world scenarios in real-time:

=======================================================
 🎮 SLOPGATE INTERACTIVE AUDIT SIMULATOR v0.1.2
=======================================================

Scenario 1: Rogue AI PR weakens test assertion to pass CI
Simulating: Contributor PR replaces 'assert val == False' with 'assert val is not None'...
=======================================================
 🛡️  SLOPGATE — Code & PR Integrity Shield 
=======================================================
 Diff: 2 files | +2 / -1 | Code: +0 | Tests: +1 | Docs: +1
 Status: [BLOCKED] ⛔ SlopGate Blocked: Found 1 critical integrity violation(s) (test tampering / phantom symbols).

Violations Detected:
  • [SG-ASSERT_WEAKENED] Assert Weakened
    Location: tests/test_auth.py:14
    Details:  Weakened assertion: 'is not None' checks existence instead of value equivalence.
    Snippet:  assert verify_token("expired_xyz") is not None

  • [SG-MISSING_TEST_REPRO] Missing Reproduction Test
    Location: src/auth.py:1
    Details:  PR modifies production logic without adding a trustworthy test case.

-------------------------------------------------------
Scenario 2: AI PR with phantom packages and hallucinated stdlib APIs
Simulating: PR imports 'phantom_ai_driver' and calls 'json.loads_async()'...
=======================================================
 🛡️  SLOPGATE — Code & PR Integrity Shield 
=======================================================
 Diff: 1 files | +3 / -1 | Code: +3 | Tests: +0 | Docs: +0
 Status: [BLOCKED] ⛔ SlopGate Blocked: Found 3 critical integrity violation(s) (test tampering / phantom symbols).

Violations Detected:
  • [SG-HALLUCINATED_IMPORT] Hallucinated Import
    Location: src/database.py:5
    Details:  Module 'phantom_ai_driver' is not in stdlib, project dependencies, or local modules.
    Snippet:  symbol: phantom_ai_driver

  • [SG-HALLUCINATED_IMPORT] Hallucinated Import
    Location: src/database.py:6
    Details:  Module 'hallucinated_orm' is not in stdlib, project dependencies, or local modules.
    Snippet:  symbol: hallucinated_orm

  • [SG-HALLUCINATED_STDLIB_METHOD] Hallucinated Stdlib Method
    Location: src/database.py:9
    Details:  json has no async loads method.
    Snippet:  symbol: json.loads_async

  • [SG-MISSING_TEST_REPRO] Missing Reproduction Test
    Location: src/database.py:1
    Details:  PR modifies production logic without adding a trustworthy test case.

-------------------------------------------------------
Scenario 3: Genuine human bugfix with reproduction test case
Simulating: Legitimate PR fixing ZeroDivisionError with reproduction test...
=======================================================
 🛡️  SLOPGATE — Code & PR Integrity Shield 
=======================================================
 Diff: 2 files | +7 / -0 | Code: +2 | Tests: +5 | Docs: +0
 Status: [PASSED] ✅ SlopGate Passed: All test assertions intact, no hallucinated symbols detected.

  ✨ Zero integrity violations found. Clean PR!

-------------------------------------------------------
✓ Simulator completed: 2 rogue AI PR(s) intercepted, 1 clean bugfix approved.

💻 Local CLI Usage

Audit a branch, a saved diff, or a pipe — the same engine the Action runs:

slopgate check                                  # auto-detects the PR/branch diff
slopgate check --fail-on warning                # fail on warnings as well
slopgate check --format json                    # machine-readable report
slopgate check --format github                  # Step Summary markdown + annotations
git diff main...HEAD | slopgate check --diff -  # audit any diff you have

Exit codes are CI-friendly: 0 passed, 1 blocked (or warned, with --fail-on warning). Inside GitHub Actions SlopGate fails closed when it cannot find a diff, so a broken checkout can never report a false pass.

🚀 10-Second GitHub Action Setup

Add .github/workflows/slopgate.yml to your repository:

name: SlopGate PR Integrity Check

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read

jobs:
  slopgate:
    name: SlopGate PR Audit
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Run SlopGate Shield
        uses: Shinraya-Tech-Labs/slopgate@v0
        with:
          fail-on: blocked   # 'blocked' (fails on tamper/hallucinations) or 'warning'

Or install it automatically into your repo:

slopgate install

🛡️ The 4 Invariant Shields

1. Test Tampering & Neutering Guard

Detects when a pull request attempts to pass failing CI by:

• Deleting assert statements in existing test files, or deleting the test file.
• Replacing strict comparisons (assert x == 42) with tautologies (assert True, assert len(x) >= 0, assert x > 0 or True) or an existence check on the same value (assert x is not None).
• Masking a removed value comparison behind a bare truthiness check (assert cart).
• Wrapping failing assertions in silent try: ... except: pass blocks.
• Explicitly adding @pytest.mark.skip, @pytest.mark.skipif(True, ...), raise unittest.SkipTest(...), or xfail to failing tests.

2. Phantom Symbol & Hallucinated Import Detector

• Intercepts newly added import <package> that does not exist in standard library, project manifests (pyproject.toml, requirements.txt), or local modules.
• Intercepts made-up standard library methods (e.g. json.loads_async, os.mkdir_p, re.match_all).
• Warns when the imported package is declared by the same PR — a diff cannot silently whitelist a package it invents.

3. Reproduction Gate

• Checks if a pull request modifies core production logic without adding or updating a test.
• A new test file that defines tests but asserts nothing is a placeholder, not a reproduction: it blocks.
• Reminds the author: "Please supply a reproduction test verifying the bug before this patch."

4. Slop-to-Logic Ratio

• Computes $\frac{\text{Docstring and explanatory comments added}}{\text{Executable AST nodes added}}$.
• Flags PRs that paste 60 lines of AI-generated architectural buzzwords for a 1-line non-functional change.

📊 SlopGate vs Text Detectors

🏷️ Add the Badge to Your README

Show your contributors that your project values code integrity:

[![Protected by SlopGate](https://img.shields.io/badge/PRs-SlopGate_Protected-brightgreen?style=flat-square&logo=github)](https://github.com/Shinraya-Tech-Labs/slopgate)

Preview:

🗺️ Roadmap

• Python AST assertion tamper detection
• Python stdlib & dependency hallucination detector
• Composite GitHub Action with Step Summary output
• Interactive Terminal Simulator (slopgate demo)
• TypeScript / JavaScript AST Invariant Engine (Babel / SWC parser)
• Go AST Invariant Engine
• Automatic PR reply bot with reproduction sandbox runner

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for local development and testing guidelines.

To run tests locally:

git clone https://github.com/Shinraya-Tech-Labs/slopgate.git
cd slopgate
pip install -e ".[dev]"
python -m pytest -q

📄 License

Apache 2.0 — Created by Shinraya Tech Labs and open-source contributors.