slopfence 0.1.0__tar.gz

slopfence-0.1.0/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,json,toml,md}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

slopfence-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,6 @@
+# Default owner for everything in the repo.
+# Owners are automatically requested for review on pull requests.
+* @syedmuhdahmad
+
+# Repo settings, CI and community files
+/.github/ @syedmuhdahmad

slopfence-0.1.0/.github/ISSUE_TEMPLATE/1-bug_report.yml

@@ -0,0 +1,42 @@
+name: 🐛 Bug report
+description: slopfence crashed or behaved incorrectly
+labels: ["bug", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting! If slopfence flagged code it shouldn't have, use the **False positive** template instead.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you expect, and what happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Minimal code and the exact command you ran.
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: output
+    attributes:
+      label: Output / traceback
+      render: shell
+  - type: input
+    id: version
+    attributes:
+      label: slopfence version
+      placeholder: "slopfence --version"
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: OS and Python version
+      placeholder: "Ubuntu 24.04, Python 3.12"
+    validations:
+      required: true

slopfence-0.1.0/.github/ISSUE_TEMPLATE/2-false_positive.yml

@@ -0,0 +1,35 @@
+name: 🎯 False positive
+description: slopfence flagged code that is actually fine
+labels: ["false-positive", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        False positives are the #1 thing we want to fix, so thank you!
+  - type: input
+    id: rule
+    attributes:
+      label: Rule ID
+      placeholder: "SLOP020"
+    validations:
+      required: true
+  - type: textarea
+    id: code
+    attributes:
+      label: Code that was flagged
+      description: The smallest snippet that reproduces it. Remove anything private.
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: why-ok
+    attributes:
+      label: Why is this code correct?
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: slopfence version
+    validations:
+      required: true

slopfence-0.1.0/.github/ISSUE_TEMPLATE/3-detector_proposal.yml

@@ -0,0 +1,39 @@
+name: 💡 Detector proposal
+description: Propose a new pattern for slopfence to detect
+labels: ["detector", "enhancement", "needs-triage"]
+body:
+  - type: textarea
+    id: pattern
+    attributes:
+      label: What pattern should be detected?
+      description: Describe the junk pattern in one or two sentences.
+    validations:
+      required: true
+  - type: textarea
+    id: should-flag
+    attributes:
+      label: Code that SHOULD be flagged
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: should-not-flag
+    attributes:
+      label: Similar code that should NOT be flagged
+      description: Helps us avoid false positives.
+      render: python
+  - type: dropdown
+    id: severity
+    attributes:
+      label: Suggested severity
+      options:
+        - High (security risk or broken behaviour)
+        - Medium (misleading or incomplete code)
+        - Low (noise or style)
+    validations:
+      required: true
+  - type: textarea
+    id: why
+    attributes:
+      label: Why does this matter?
+      description: Real-world impact, links, or how often you see it.

slopfence-0.1.0/.github/ISSUE_TEMPLATE/4-ai_junk_example.yml

@@ -0,0 +1,36 @@
+name: 🤖 AI junk example
+description: Share a real example of junk an AI coding tool produced
+labels: ["example", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Real examples are the most valuable input for designing detectors. Please remove anything private or proprietary.
+  - type: input
+    id: tool
+    attributes:
+      label: Which AI tool produced it? (optional)
+      placeholder: "Copilot, Claude, Cursor, …"
+  - type: dropdown
+    id: language
+    attributes:
+      label: Language
+      options:
+        - Python
+        - JavaScript / TypeScript
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: code
+    attributes:
+      label: The code
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: What's wrong with it?
+    validations:
+      required: true

slopfence-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 Questions & ideas
+    url: https://github.com/syedmuhdahmad/slopfence/discussions
+    about: Ask questions and discuss ideas in GitHub Discussions.
+  - name: 🔒 Report a security vulnerability
+    url: https://github.com/syedmuhdahmad/slopfence/security/advisories/new
+    about: Please report security issues privately, never in a public issue.

slopfence-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,27 @@
+## What does this PR do?
+
+<!-- A short summary of the change and why it's needed. -->
+
+Closes #
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] False-positive fix
+- [ ] New detector
+- [ ] New feature
+- [ ] Documentation
+- [ ] Refactor / chore
+- [ ] Breaking change
+
+## How was it tested?
+
+<!-- Commands you ran, test cases you added. For detectors: include cases that SHOULD and SHOULD NOT be flagged. -->
+
+## Checklist
+
+- [ ] I read [CONTRIBUTING.md](../CONTRIBUTING.md)
+- [ ] The PR title is clear (it becomes the squash-commit message)
+- [ ] Tests added or updated for behaviour changes
+- [ ] Docs / README updated if behaviour changed
+- [ ] `CHANGELOG.md` updated under **Unreleased** (if user-facing)

slopfence-0.1.0/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    labels:
+      - dependencies
+    commit-message:
+      prefix: chore
+    groups:
+      actions:
+        patterns: ["*"]
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    labels:
+      - dependencies
+    commit-message:
+      prefix: chore

slopfence-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  merge_group:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+      - run: pip install -e '.[dev]'
+      - name: Ruff
+        run: |
+          ruff check .
+          ruff format --check .
+      - name: slopfence checks itself
+        run: slopfence src tests
+      - name: Lint Markdown
+        uses: DavidAnson/markdownlint-cli2-action@v24
+        with:
+          globs: "**/*.md"
+
+  test:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        include:
+          - os: macos-latest
+            python-version: "3.13"
+          - os: windows-latest
+            python-version: "3.13"
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e '.[dev]'
+      - run: pytest -q
+
+  # Single required status check that gates merging into main.
+  ci:
+    if: always()
+    needs: [lint, test]
+    runs-on: ubuntu-latest
+    steps:
+      - name: All checks passed
+        if: ${{ !(contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')) }}
+        run: echo "All checks passed"
+      - name: Some checks failed
+        if: ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}
+        run: exit 1

slopfence-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,81 @@
+name: Release
+
+# Publishes to PyPI when a GitHub release is published (tag vX.Y.Z).
+# Uses PyPI Trusted Publishing: no API tokens are stored anywhere.
+on:
+  release:
+    types: [published]
+
+permissions: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+      - name: Check the tag matches the package version
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          version=$(python -c "import re,pathlib; print(re.search(r'__version__ = \"(.+)\"', pathlib.Path('src/slopfence/__init__.py').read_text()).group(1))")
+          if [ "$TAG" != "v$version" ]; then
+            echo "::error::Release tag $TAG does not match package version v$version"
+            exit 1
+          fi
+      - name: Build
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check --strict dist/*
+      - name: Smoke-test the wheel
+        run: |
+          python -m venv /tmp/smoke
+          /tmp/smoke/bin/pip install dist/*.whl
+          /tmp/smoke/bin/slopfence --version
+          /tmp/smoke/bin/slopfence src --offline
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/slopfence/${{ github.event.release.tag_name }}
+    permissions:
+      id-token: write  # Trusted Publishing; also signs PEP 740 attestations
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  attach-to-release:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Upload wheel and sdist to the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.event.release.tag_name }}
+        run: gh release upload "$TAG" dist/* --repo "$GITHUB_REPOSITORY" --clobber

slopfence-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.slopfence-cache/
+.DS_Store

slopfence-0.1.0/.markdownlint-cli2.yaml

@@ -0,0 +1,9 @@
+config:
+  default: true
+  MD013: false  # line length: prose is wrapped by editors
+  MD033: false  # inline HTML
+  MD041: false  # first line heading (templates)
+  MD060: false  # table column style
+ignores:
+  - "CODE_OF_CONDUCT.md"  # upstream Contributor Covenant text, kept verbatim
+  - "node_modules/**"

slopfence-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,8 @@
+- id: slopfence
+  name: slopfence
+  description: Find the junk AI coding assistants leave behind.
+  entry: slopfence
+  language: python
+  types_or: [python, toml, text]
+  files: (\.py|requirements.*\.txt|pyproject\.toml)$
+  require_serial: true

slopfence-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-02
+
+### Added
+
+- Published to PyPI as `slopfence` (the project was originally named slopcheck, but that PyPI name belongs to an unrelated project)
+- `slopfence` CLI with `--diff`, `--format text|json|sarif`, `--select`, `--ignore`, `--offline` and `--exit-zero`
+- `SLOP001`: dependencies and imports that don't exist on PyPI, with a local cache
+- `SLOP010`: placeholder comments left in finished-looking code
+- `SLOP020`: tests that only assert on their own mocks
+- `SLOP021`: tests whose only assertions are always true
+- `SLOP022`: tests whose assertions are swallowed by try/except
+- `SLOP051`: leftover AI chat text in comments and docstrings
+- `# slopfence: ignore[...]` and `# slopfence: ignore-file` directives
+- GitHub Action (`action.yml`) and pre-commit hook
+
+### Project setup
+
+- Project README describing the problem, design principles, planned detectors and roadmap
+- Community health files: Code of Conduct, Contributing guide, Security policy, Support, Governance
+- Issue templates, pull request template, CODEOWNERS, Dependabot and CI
+
+[Unreleased]: https://github.com/syedmuhdahmad/slopfence/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/syedmuhdahmad/slopfence/releases/tag/v0.1.0

slopfence-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+syed.muhd.ahmad@gmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

slopfence-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,96 @@
+# Contributing to slopfence
+
+Thanks for your interest in slopfence! This project is at an early stage, which is the best time to shape it. Every kind of contribution helps: code, detector ideas, real-world examples, docs, and bug reports.
+
+By participating, you agree to follow our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Ways to contribute
+
+| You want to… | Do this |
+|---|---|
+| Share an example of AI-generated junk | Open an issue with the **AI junk example** template |
+| Report a false positive | Open an issue with the **False positive** template |
+| Propose a new detector | Open an issue with the **Detector proposal** template |
+| Report a bug | Open an issue with the **Bug report** template |
+| Ask a question or discuss an idea | Start a [Discussion](https://github.com/syedmuhdahmad/slopfence/discussions) |
+| Report a security vulnerability | **Don't open an issue.** See [SECURITY.md](SECURITY.md) |
+| Fix something or add a feature | Read on |
+
+New here? Look for issues labelled [`good first issue`](https://github.com/syedmuhdahmad/slopfence/labels/good%20first%20issue) or [`help wanted`](https://github.com/syedmuhdahmad/slopfence/labels/help%20wanted).
+
+## Before you start coding
+
+- **Small fixes** (typos, docs, obvious bugs): open a pull request directly.
+- **Anything bigger** (new detectors, new features, behaviour changes): open an issue first and wait for a maintainer to agree on the approach. This avoids wasted work.
+- Comment on an issue to say you're working on it, so others don't duplicate effort.
+
+## Development workflow
+
+`main` is protected: **nobody pushes to it directly**, maintainers included. All changes go through pull requests.
+
+1. **Fork** the repository and clone your fork.
+2. **Create a branch** from `main` with a descriptive name:
+   - `feat/slop001-pypi-lookup`
+   - `fix/false-positive-mock-assert`
+   - `docs/contributing-typo`
+3. **Make your changes.** Keep each pull request focused on one thing.
+4. **Add tests** for any behaviour change. Detectors need both:
+   - cases that **should** be flagged, and
+   - similar-looking cases that **should not** be flagged (false-positive guards).
+5. **Run checks locally** (see below) and make sure they pass.
+6. **Push** to your fork and **open a pull request** against `main`. Fill in the template.
+
+### What happens to your pull request
+
+- CI must pass.
+- At least **one maintainer approval** is required.
+- All review conversations must be resolved.
+- Pull requests are **squash-merged**, so `main` has a clean, linear history with one commit per pull request. The pull request title becomes the commit message, so make it clear.
+- Your branch is deleted automatically after merge.
+
+## Local checks
+
+```bash
+python -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+pip install -e '.[dev]'
+
+pytest                           # tests
+ruff check . && ruff format --check .
+slopfence src tests              # slopfence must pass on its own code
+npx markdownlint-cli2 "**/*.md" "!.venv/**"
+```
+
+### Adding a detector
+
+1. Add the rule to `RULES` in `src/slopfence/models.py`.
+2. Write the detector in `src/slopfence/detectors/` and register it in `detectors/__init__.py`.
+3. Add tests with **both** flagged and not-flagged cases. Real-world code that must stay quiet is the most valuable test.
+4. Run it against a large codebase (for example your Python install's standard library) and check for false positives before opening the pull request.
+
+## Commit and pull request style
+
+- Use the imperative mood: "Add PyPI lookup cache", not "Added" or "Adds".
+- Pull request titles follow [Conventional Commits](https://www.conventionalcommits.org/) style where it fits:
+  - `feat: add SLOP010 placeholder comment detector`
+  - `fix: ignore mocks used as fixtures in SLOP020`
+  - `docs: clarify ignore comment syntax`
+  - `chore: bump actions/checkout`
+- Reference related issues: `Closes #12`.
+
+## Writing a good detector
+
+A detector is only useful if people trust it. Before proposing or writing one, check:
+
+1. **Is it objective?** Could two reviewers agree on whether a given snippet matches?
+2. **Is it high-confidence?** It's better to miss some cases than to flag correct code.
+3. **Is it actionable?** The message should tell the user what's wrong and how to fix it.
+4. **Is it about the pattern, not the author?** slopfence never tries to guess whether AI wrote the code.
+
+## Licensing of contributions
+
+By submitting a pull request, you agree that your contribution is licensed under the [MIT License](LICENSE), the same license as the project.
+
+## Recognition
+
+All contributors are credited in release notes. Thank you for helping make AI-assisted code better!