ai-slopcheck 1.0.0

Deterministic scanner for AI-style code failures. 72 rules for Python, JS/TS, Go, C/C++, SQL.

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

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

With standard Python tooling

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

Optional: tree-sitter grammars

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

Try the scanner

# 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

.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