Metadata-Version: 2.4
Name: ai-slopcheck
Version: 1.0.0
Summary: Deterministic scanner for AI-style code failures. 72 rules for Python, JS/TS, Go, C/C++, SQL.
Author-email: Euraika <info@euraika.net>
License: MIT
Project-URL: Homepage, https://git.euraika.net/euraika/slopcheck
Project-URL: Documentation, https://git.euraika.net/euraika/slopcheck/-/wikis/home
Project-URL: Repository, https://git.euraika.net/euraika/slopcheck
Project-URL: Changelog, https://git.euraika.net/euraika/slopcheck/-/blob/develop/CHANGELOG.md
Keywords: static-analysis,linter,ai-code,code-quality,security,github-actions
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.8
Requires-Dist: PyYAML>=6.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Provides-Extra: ast
Requires-Dist: tree-sitter>=0.23; extra == "ast"
Provides-Extra: github
Requires-Dist: requests>=2.32; extra == "github"
Dynamic: license-file

# slopcheck

A deterministic, GitHub-first scanner for catching AI-style code failures without using an LLM in the product.

**42 rules. 463 tests. Multi-language. Tree-sitter optional. SARIF output.**

## What this project is

`slopcheck` is a deterministic reviewer for pull requests:

- local-first, no backend, no database, no SaaS dependency
- no LLM calls in the product path
- runs in GitHub Actions: checkout → scan → findings.json → annotations + exit code
- covers Python, JavaScript, TypeScript, Go, and cross-language patterns

The point is not to detect whether code was generated by AI. The point is to catch failure modes that show up often in AI-generated or rushed code:

- AI artifacts committed as source (conversational bleed, identity refusals, hallucinated placeholders)
- stub function bodies and omission comments
- sloppy error handling (bare except, ignored Go errors, unhandled promises)
- hardcoded secrets, insecure defaults, weak hashes
- language-specific antipatterns (React, TypeScript, Go, Python)
- architectural boundary violations

## Current working slice

- 42 rules across 8 categories (AI detection, security, JS/Node, Go, Python, cross-language, structural, repo)
- 463 tests
- threaded scanning (up to 8 workers, auto-detected)
- diff-only mode (`--changed-files git` or `--changed-files @file.txt`)
- inline suppression (`# slopcheck: ignore[rule_id]`)
- baseline suppression (`create-baseline` command)
- confidence filtering (`--min-confidence medium`)
- SARIF v2.1.0 output for GitHub Security tab
- tree-sitter integration (optional; graceful fallback when not installed)
- GitHub workflow annotations and Markdown step summary

## Design principles

1. **Deterministic first.** Checks are explainable, stable, and testable.
2. **GitHub first.** The first production target is GitHub pull requests.
3. **No backend for v1.** CLI plus GitHub Actions is enough.
4. **Vertical slices.** Each milestone produces something runnable.
5. **Rule quality over rule count.** A noisy scanner dies fast.
6. **Docs are part of the product.** Agents should not need tribal knowledge.

## Quick start

### With `uv`

```bash
uv venv
source .venv/bin/activate
uv pip install -e .[dev]
pytest
ruff check .
```

### With standard Python tooling

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .[dev]
pytest
ruff check .
```

### Optional: tree-sitter grammars

```bash
pip install tree-sitter tree-sitter-python tree-sitter-javascript \
            tree-sitter-typescript tree-sitter-go
```

## Try the scanner

```bash
# Scan the included fixture repo
python -m slopcheck scan . --repo-root tests/fixtures/sample_repo \
    --output /tmp/findings.json --fail-on none

# Render outputs
python -m slopcheck summary /tmp/findings.json
python -m slopcheck github-annotations /tmp/findings.json
python -m slopcheck sarif /tmp/findings.json

# Create a baseline to suppress existing findings
python -m slopcheck create-baseline /tmp/findings.json --output .slopcheck/baseline.json

# Scan only changed files (CI diff mode)
python -m slopcheck scan . --repo-root . --changed-files git --output /tmp/findings.json
```

## CLI reference

| Command | Purpose |
|---------|---------|
| `scan [paths]` | Scan files and write `findings.json` |
| `summary <findings>` | Print Markdown summary |
| `github-annotations <findings>` | Print `::warning/error::` annotations |
| `sarif <findings>` | Print SARIF v2.1.0 JSON |
| `create-baseline <findings>` | Write baseline of current fingerprints |

Key `scan` options:

| Option | Default | Description |
|--------|---------|-------------|
| `--repo-root` | `.` | Repository root for config lookup and relative paths |
| `--output` | `findings.json` | Output path (use `-` for stdout) |
| `--fail-on` | `error` | Exit 1 when findings reach this severity: `none`/`note`/`warning`/`error` |
| `--min-confidence` | `low` | Filter findings below this confidence: `low`/`medium`/`high` |
| `--baseline` | — | Suppress fingerprints in this baseline file |
| `--changed-files` | — | Diff-only mode: `git` or `@file.txt` |
| `--jobs` | auto | Thread count (0 = auto, 1 = sequential) |
| `--config` | — | Explicit config file path |

## Repository layout

```text
.agent/PLANS.md                Codex-style execution plan instructions
.claude/rules/                 Claude Code scoped rules
docs/                          Architecture, roadmap, security, and authoring docs
  adr/                         Architecture Decision Records
examples/workflows/            Example GitHub workflows
prompts/                       Ready-to-use prompts for Codex and Claude Code
slopcheck/                     Python package
  engine/                      Scanner, file discovery, suppression, context filter
  parsers/                     Tree-sitter adapter (optional)
  rules/generic/               41 cross-repo rules
  rules/repo/                  1 architecture-specific rule
  output/                      Annotation, Markdown, SARIF renderers
  state/                       Baseline store
tests/                         463 unit tests and fixtures
AGENTS.md                      Codex instructions
CLAUDE.md                      Claude Code instructions
code_review.md                 Shared review rubric
```

## Rule overview

**42 rules** in 8 categories. Rules marked opt-in are `enabled: false` by default due to noise at scale.

| Category | Count | Notes |
|----------|-------|-------|
| AI detection (Tier 1) | 7 | Stub bodies, instruction comments, bare except — all on |
| AI smoking guns (Tier 2) | 3 | Conversational bleed, identity refusals, hallucinated placeholders — all on |
| Quality / supplementary | 5 | Placeholder tokens, dead code comments, incomplete errors; 2 opt-in |
| Security | 5 | Secrets, SQL injection, insecure defaults, weak hashes; 1 opt-in |
| JavaScript / Node | 11 | Async/await, promises, React, TypeScript, regex — all on |
| Go | 3 | Ignored errors, missing defer, error wrapping — all on |
| Python | 1 | Mutable default arguments — on |
| Cross-language / structural | 5 | Idiom mismatches, SELECT *, nesting/size (3 opt-in) |
| Repo-specific | 1 | Forbidden import edges (configured per-repo) |
| Meta | 1 | Unused suppression directives — on |

See `docs/architecture.md` for the full table. See `docs/rule-authoring.md` to add a rule.

## Suggested reading order

1. `AGENTS.md`
2. `code_review.md`
3. `docs/architecture.md`
4. `docs/implementation-roadmap.md`
5. `docs/security-model.md`
6. `docs/github-integration.md`
7. `docs/rule-authoring.md`

Claude Code users should also read `CLAUDE.md` and `.claude/rules/`.

## Agent entry points

- Start Codex with `prompts/codex-first-prompt.md`
- Start Claude Code with `prompts/claude-first-prompt.md`

## License

MIT
