AI-SLOP Detector
Find AI-generated code that looks finished but isn't.
Catches what a normal linter passes over: empty functions with real-looking bodies, imports of things that don't exist, copy-pasted logic, unreachable code, and docs that oversell what the code actually does.
Runs fully offline · deterministic core scoring · no API key, no model download, nothing leaves your machine.
How results are checked
|
|
| Deterministic |
The same input gives byte-identical JSON across cache, hash seed, Rust helper and working directory; --read-only writes nothing to the project or the home directory. |
| Says when it measured nothing |
Every project result carries measurement_state (COMPLETE, PARTIAL, NO_MEASUREMENT) and score_valid. When nothing was measured, human reports read NOT EVALUATED instead of a clean verdict, and a scan whose files all failed to analyze fails --fail-threshold. |
| Its own tests are tested |
More than 1,500 tests run in CI on Python 3.8 to 3.12. Behavior changes are checked against deliberately broken copies of the code (mutation testing): in v3.12.0, 21 of 21 breakages of the new rules were caught (v3.11.0: 25 of 25). |
| Rules state their reasons |
Each rule ships with tests that name the code shape it reports and the shapes it leaves alone; the CHANGELOG records every behavior change. |
Linters check form; this checks substance. See why not just a linter.
Release track
- Stable tag:
v3.12.0
- Release candidate:
3.13.0 (on main, not tagged yet)
- Previous stable tag:
v3.11.0
3.13.0 (candidate): null objects, base-class defaults and framework hooks are no longer reported as placeholders, and logged NotImplementedError stubs, constant success reports and discarded results are. See CHANGELOG.md.v3.12.0: catches code that only looks finished: stubs hidden behind logging (return_constant_stub), arguments returned unchanged (return_input_stub), catch-all handlers that return the success result (failure_as_success) and parameters a function never reads (ignored_parameter). See CHANGELOG.md.v3.11.0: one scan engine (ScanService) behind the CLI, MCP and REST, with progress events, cancellation and typed errors; MCP and REST scans write nothing by default (REST history only with "save_history": true), the REST server binds 127.0.0.1, and agent project responses say whether the score measured anything (measurement_state, score_valid, reason). Findings and scores are unchanged. See CHANGELOG.md.v3.10.1: function length counts logical lines and try / with are not nesting levels (far fewer false god_function and nesting findings); UTF-8 files with a byte order mark and single JS/TS/Go files are analyzed instead of scored as parse errors; scans of git repositories under non-ASCII folder names and HTML reports of projects no longer crash; a scan that measured nothing shows NOT EVALUATED and never passes --fail-threshold; an invalid or missing config stops the run before analysis. See CHANGELOG.md.v3.10.0: findings need evidence (declared intent, protocol methods, claim words, mutation evidence), every score discloses what it could not look at, static data modules no longer dilute the project score, and cold scans are 2.6-3x faster. See CHANGELOG.md.v3.9.3 is a precision correction: an elif no longer counts as a level of nesting, @overload signatures are not placeholders, a module with no executable code is not scored as empty logic, a file that fails to analyze is listed and marks the scan incomplete (a hard gate then fails) instead of silently disappearing, --json --js prints one JSON document, and the JS/TS analysis mode (tree-sitter or regex fallback) is disclosed. Scores mostly go down; see docs/RELEASE_NOTES.md.v3.9.2 makes one result mean the same thing everywhere and removes double counting: one set of score bands for files, projects, JS and Go; docstrings count like comments (logic density, god_function); a nested function’s nesting is charged once; exact duplicates compare function bodies only, with one size floor for the same-file and cross-file reports; import evidence follows the scanned project’s root; output is byte-identical across cache, hash seed, Rust helper, and working directory. Self-calibration is now an advisory report that writes nothing, documented configuration keys that nothing read are removed with a warning, and --init <path> writes into <path>. Scores move; see docs/RELEASE_NOTES.md.v3.9.1 makes claim checks count only real claims and real evidence: jargon in import paths, identifiers, and license notices is not a claim; a claim is supported only by code structure (a library named in a comment no longer counts); evidence that one file cannot show, such as tests that live elsewhere, is reported as unmeasured rather than missing. It also flags names a real package does not define (phantom_member) and decides test files and exclusions relative to the project root, so a checkout under a build/ directory is no longer scanned as 0 files. Scores move; see docs/RELEASE_NOTES.md.v3.9.0 closes a security hole (no model is read from the working directory, nothing is unpickled), makes import evidence follow CPython’s resolution rules, and makes async def stubs, --patterns-only, --disable, and the multi-file pre-commit hook work as documented. See docs/RELEASE_NOTES.md.
Navigation:
What Is It? •
Why Not a Linter? •
When Not to Use •
Quick Start •
Verification •
Boundaries •
How It Works •
Document Map •
What It Detects •
Scoring •
Key Features •
Calibration •
Security •
CI/CD •
Config •
VS Code •
Roadmap •
Changelog •
Release Notes •
Schema Validation
What Is AI-SLOP Detector?
AI-SLOP Detector is an evidence-based static analyzer that targets a defect class common in AI-assisted code: structurally plausible code that is functionally empty, disconnected, or misleading. It does not tell whether code was written by an AI; it reports static signals in the code itself.
General linters flag style and convention. This tool flags structural risk.
- 51 checks across Python, JS/TS and Go (the pattern registry) — empty stubs, imports that don’t resolve, unreachable code, copy-paste clones, and buzzword-padded docs
- One 0–100 risk score per file — four measurements are combined so one bad dimension can’t be hidden behind good ones (weighted geometric mean of logic density, jargon inflation, dependency use, and critical severity)
- Keeps local history — every scan is recorded locally with what measured it (detector version, configuration, project root);
--self-calibrate reports what the comparable runs of your project suggest for the weights. The report is advisory: weights change only when you edit .slopconfig.yaml.
- Tells real changes from noise — uses your commit history so a score drifting a point or two isn’t mistaken for a real regression
- Knows your project type —
--init detects the domain (web API, data/ML, numerical, CLI, library, bio, finance, or general; general when the evidence is weak) and sets that domain’s pattern thresholds, printing every change; weights stay the defaults; override with --domain
- Python first, JS/TS and Go optional — install the
[js] or [go] extra to scan those files too
- Drops into CI — soft / hard / quarantine gates, GitHub Actions ready
- VS Code extension — inline warnings as you type, score in the status bar
Why Not Just Use a Linter?
Ruff, pylint, ESLint, and SonarQube primarily check syntax, style, and general static-quality rules. They’ll happily pass code that follows every rule and still does nothing — which is exactly what AI assistants tend to produce. This tool checks the other half: does the code contain structural evidence for what it and its docs claim? Structural evidence is not proof that a claim is true; the tool does not run your code.
| Can it catch… |
ruff / pylint / SonarQube |
AI-SLOP Detector |
| Style, formatting, syntax |
Yes |
No (not its job) |
| An empty function with a real-looking body or fake return |
No |
Yes |
| A module imported but never actually used downstream |
Partial (unused-import) |
Yes (usage ratio) |
| A handler or pipeline that’s defined but never wired in |
No |
Yes |
| Docs or comments that oversell what the code does |
No |
Yes |
| Copy-pasted duplicate functions across files |
Partial |
Partial (exact duplicates) |
| Runs offline, no API key, deterministic core score |
Yes |
Yes |
Use a linter for correctness-of-form. Use this for “is this code real, or just plausible-looking.” The two are complementary — run both.
When NOT to Use This
- You want style or formatting enforcement — use ruff / black / ESLint. This tool ignores style on purpose.
- You need a runtime correctness guarantee — a low score means cleaner structure, not that the code works. Keep your tests.
- Your code isn’t Python, JS/TS, or Go — other languages aren’t analyzed yet.
- You expect thresholds tuned to your repository — weights are the defaults or the values in your
.slopconfig.yaml; nothing tunes them automatically. Treat findings as leads, not verdicts.
60-Second First Run
No project-side config needed. Run it against any folder of Python:
pip install "ai-slop-detector>=3.12.0"
slop-detector --project . --json --output slop.json
python -c "import json; d=json.load(open('slop.json',encoding='utf-8')); print(d['overall_status'], d['weighted_deficit_score'])"
Expected output for a healthy project: clean 0.0 to clean 30.0. clean
describes the weighted deficit band only; inspect finding_summary,
scan_coverage, and ml_scoring before treating it as a complete project
assessment. Modules that hold only static data (literal_data_module) are
analyzed but carry no line weight in the weighted score;
scan_coverage.aggregation_exclusions lists them. The --output
form writes UTF-8 (no BOM) directly to disk, so it is safe under Windows
PowerShell — prefer it to > slop.json redirection.
Quick Start
pip install "ai-slop-detector>=3.12.0"
slop-detector scan . # canonical analysis entry
slop-detector review . --json # canonical changed-code review
slop-detector pulse . --json # canonical repo health view
slop-detector sweep dead-code . --json # canonical cleanup family
# legacy / compatible surface
slop-detector --init # bootstrap baseline .slopconfig.yaml + .gitignore
slop-detector --init --adaptive-init --init-preview
slop-detector --init --adaptive-init --apply-init-suggestions
slop-detector mycode.py # single file
slop-detector --project ./src # entire project
slop-detector --project . --include-tests # include only default-excluded test files
slop-detector --project . --json --output slop.json # machine-readable output (Windows-safe)
slop-detector --project . --ci-mode hard --ci-report # CI gate
# Optional extras
pip install "ai-slop-detector[js]" # JS/TS tree-sitter analysis
pip install "ai-slop-detector[go]" # Go tree-sitter analysis
# npm wrapper (delegates to the Python CLI). With no Python backend installed
# it runs the PyPI release of the same version through uvx or pipx.
npx ai-slop-detector --project .
npm install --save-dev ai-slop-detector
npx ai-slop-detector scan .
npx ai-slop-detector review . --format json
npx ai-slop-detector pulse . --format json
npx ai-slop-detector sweep dead-code . --format json
npx ai-slop-detector mcp
# Typed output contract
import type { ReviewOutput, ScanOutput } from "ai-slop-detector/types"
# Programmatic Node API
import { scanProject, reviewChanges, computeHealth, runCleanupFamily } from "ai-slop-detector"
# Local impact story
slop-detector impact enable .
slop-detector impact .
# Telemetry controls (default: off)
slop-detector telemetry status
slop-detector telemetry inspect --example
# Local wrapper development
cd npm-wrapper
node ./bin/ai-slop-detector.js --version
# No install required
uvx ai-slop-detector mycode.py
npx ai-slop-detector mycode.py # same, through the npm wrapper
The npm surface is intentionally thin:
- it does not reimplement analysis logic
- it delegates into the Python CLI/runtime
- it exists for Node-first teams that want
npx-style entry without changing
product semantics; it is published on npm as ai-slop-detector with the
same version as the PyPI release
- it discovers a backend in this order:
AI_SLOP_DETECTOR_EXECUTABLE ->
active VIRTUAL_ENV -> PATH executables -> python -m slop_detector.cli ->
uvx / pipx running the PyPI release of the wrapper’s own version (uv
can also fetch Python), so npx works without a Python install when uv or
pipx is present
- it ships version-pinned TypeScript interfaces at
ai-slop-detector/types
- it exports a small async Node API for
scanProject, reviewChanges,
computeHealth, and runCleanupFamily
Windows / PowerShell tip: PowerShell > redirection writes UTF-16 LE
or UTF-8 with BOM by default, which breaks json.load(..., encoding='utf-8').
Use --output <path> instead — it writes UTF-8 bytes (no BOM) directly,
skipping the shell.
Verification Path
Use the same verification surface the repository exposes in CI:
pip install -e ".[dev]"
python -m pytest -q
ruff check src tests
python -m build
Governance verification is a separate enforcement gate:
slop-detector verify-governance ./.cr-ep
See docs/GOVERNANCE.md for the artifact contract and
policy checks.
Operational review commands live on the same CLI entry point:
slop-detector review . --json
slop-detector pulse . --json
slop-detector sweep dead-code . --json
slop-detector sweep dupes . --json
slop-detector sweep unused-deps . --json
slop-detector sweep boundary-violations . --json
slop-detector watch . --follow
slop-detector explain dead-code
Legacy command forms such as audit, health, and direct cleanup-family names
remain supported for compatibility, but scan / review / pulse / sweep are the
preferred stable surface.
Cleanup-family semantics are now more operational than a raw candidate list:
dead-code, dupes, unused-deps, stale-suppressions, and
boundary-violations emit confidence, action_class, and evidenceunused-deps includes project-manifest findings such as
manifest_unused_dependency and undeclared_importboundary-violations stays cycle-only by default and only enables layered
boundary review when architecture rules are explicitly configured
Agent tooling can use the same semantics over MCP stdio:
slop-detector mcp
# or
slop-mcp
Adoption and observability surfaces are intentionally separate from scoring:
slop-detector impact tracks local, gitignored repository progress in
.slop-detector/impact.jsonslop-detector telemetry stays default-off and only builds anonymized
payloads; AI_SLOP_DETECTOR_TELEMETRY=inspect prints a real payload without
queueing it
Scope And Boundaries
- This repository measures static code and documentation signals. It does not prove runtime correctness.
- The default scoring path is deterministic; it does not require an LLM or external API.
- JS/TS and Go support are optional extras with language-specific analyzers and fallbacks.
- Optional Rust acceleration is available for file discovery and glob matching when a compiled
rust/slop_scan helper is present; otherwise the Python walker remains the fallback.
- Narrow framework-aware masking is enabled for test boilerplate (pytest no-op hooks, test-harness console/no-op hooks in JS/TS) and never masks
critical findings.
- A low deficit score is evidence of cleaner structure, not a guarantee that the code is complete or safe.
How It Works
flowchart LR
A[📄 Source File] --> R[FileRole\nClassifier]
R --> B[AST Parser]
B --> C[34 Pattern Checks]
B --> D[LDR · ICR · DDC\n+ Purity Metrics]
C --> E[GQG Scorer\nWeighted Geometric Mean]
D --> E
E --> F{deficit_score}
F -->|< 30| G[✅ CLEAN]
F -->|30–50| H[⚠️ SUSPICIOUS]
F -->|50–70| I[🔶 INFLATED_SIGNAL]
F -->|≥ 70| J[🚨 CRITICAL_DEFICIT]
E --> H2[history.db]
H2 --> K[Self-Calibrator\nadvisory report]
Every file goes through four independent measurement axes (LDR, ICR, DDC,
Purity) and 34 pattern checks. Results are combined via a weighted
geometric mean — a near-zero in any single dimension pulls the overall score
down regardless of other dimensions. Every scan is recorded to local history; --self-calibrate
turns that history into an advisory weight report and never writes weights.
Full specification: docs/HOW_IT_WORKS.md · docs/MATH_MODELS.md
Agent usage: docs/AGENT_WORKFLOW.md
Document Map
Use the docs by task, not by chronology:
Core behavior
Verification and operations
Calibration and history
Interfaces
What It Detects
Registry and advanced pattern detectors across structural, placeholder, clone,
dependency, and language-specific signals. Full catalog:
docs/PATTERNS.md
| Category |
Patterns |
Signal |
| Placeholder |
empty_except, not_implemented, pass_placeholder, ellipsis_placeholder, return_none_placeholder, return_constant_stub, return_input_stub, todo_comment, fixme_comment, hack_comment, xxx_comment, interface_only_class |
Unfinished / scaffolded code |
| Structural |
bare_except, mutable_default_arg, star_import, global_statement, failure_as_success, ignored_parameter |
Anti-patterns |
| Cross-Language |
js_push, java_equals, ruby_each, go_println, csharp_length, php_strlen |
Wrong-language syntax |
| Python Advanced |
god_function, dead_code, deep_nesting, nested_complexity, lint_escape, exact_duplicate_pair, function_clone_cluster, placeholder_variable_naming |
Structural complexity + evasion |
| Phantom |
phantom_import, phantom_member |
Hallucinated packages, and names an installed package does not define |
Four metric axes per file:
| Metric |
What it measures |
| LDR (Logic Density Ratio) |
logic_lines / total_lines — code vs. whitespace/comments |
| ICR (Inflation Check) |
jargon_density × complexity_modifier — buzzword weight |
| DDC (Dependency Check) |
used_imports / total_imports — import utilization |
| Purity |
exp(-0.5 × n_critical_patterns) — AND-gate on critical pattern severity |
Scoring Model
purity = exp(-0.5 × n_critical_patterns)
quality (GQG) = exp( Σ wᵢ·ln(max(1e-4, dimᵢ)) / Σ wᵢ ) — weighted geometric mean
deficit_score = 100 × (1 − quality) + pattern_penalty
max(1e-4, ...) prevents log(0) = -inf from collapsing the entire score (v3.7.2 __post_init__ guards enforce upstream range invariants on metric results).
| Score |
Status |
| ≥ 70 |
CRITICAL_DEFICIT |
| ≥ 50 |
INFLATED_SIGNAL |
| ≥ 30 |
SUSPICIOUS |
| < 30 |
CLEAN |
Default weights: ldr=0.40 · inflation=0.30 · ddc=0.20 · purity=0.10 — sum is 1.00; GQG divides by total_w so exact normalization is not required (all four appear in the advisory --self-calibrate report)
Project aggregation uses SR9 conservative weighting: 0.6 × min + 0.4 × mean
Full specification: docs/MATH_MODELS.md
Readable, actionable output
Scores are not a black box. Every project and file report renders each metric
with its value, healthy direction, and a one-line what it means, plus
a deficit-band legend:
Project Metrics
Metric Value Healthy What It Means
Average Deficit Score 6.1/100 Lower Mean file risk; 0 is clean, 100 is severe.
Logic Density Ratio (LDR) 95.36% Higher Share of code lines that contain real implementation.
Inflation-to-Code Ratio (ICR) 0.00x Lower Unjustified jargon vs. average cyclomatic complexity.
Dependency Usage Ratio (DDC) 86.00% Higher Imported libraries referenced by runtime code.
Deficit bands: CLEAN <30 | SUSPICIOUS 30-50 | INFLATED 50-70 | CRITICAL >=70
Each report ends with deterministic Next Steps — the top concern, the
recommended sweep command, and the highest-priority file to open — so analysis
turns directly into action. The same wording is shared by the rich, text, and
markdown renderers.
Per-file deficit_breakdown (v3.7.6)
Every per-file result in the JSON output also carries a deficit_breakdown
that attributes the score back to its source dimensions. This answers
“why is my clean-status file not 0.0?” without drilling into raw findings:
| Field |
Meaning |
ldr_penalty |
Points of deficit attributable to low logic density |
inflation_penalty |
Points from unsupported claim words (docstring inflation is reported separately and is not scored) |
ddc_penalty |
Points from low import-usage ratio |
purity_penalty |
Points from critical-severity pattern hits via GQG |
pattern_hits |
Additive pattern penalty (post-cap) |
total |
Equals deficit_score (sum of the above when not capped at 100) |
GQG-dimension shares are computed via log-loss attribution — the sum of the
five penalty fields equals total within 0.01 when deficit_score < 100.
Structural Coherence Level
coherence_level in project-level JSON output reports how the
structural_coherence value was derived:
| Value |
Meaning |
When emitted |
vr_structural |
Vietoris-Rips H0 persistence over file DCFs (MST max edge) |
At least two parsed Python files with non-empty DCFs |
vr_structural_approx |
Deterministic approximation of the same signal above the exact topology ceiling |
At least two parsed Python files, with file count above advanced.exact_topology_ceiling |
none |
No coherence computed |
Empty project, single file, or all files unparseable |
mst_persistence and not_applicable are not emitted — they were
proposed in the v3.7.5 audit but never wired in. Verify the actual value
from the JSON output rather than guessing.
Key Features
Bootstrap — domain-aware, one command to start
slop-detector --init # auto-detect domain, generate .slopconfig.yaml
slop-detector path/to/repo --init # same, for another directory (must exist)
slop-detector --init --domain web/api # explicit domain override
slop-detector --init --adaptive-init --init-preview
slop-detector --init --adaptive-init --apply-init-suggestions
--init detects your project domain from the imports of your own non-test
Python files (8 built-in profiles: general, scientific/ml,
scientific/numerical, web/api, library/sdk, cli/tool, bio,
finance). Common stacks (numpy, scipy, matplotlib, argparse) do not decide
the domain, and a tie is general. The profile sets pattern thresholds and
--init prints each threshold it changes; every profile keeps the default
weights. Also secures .slopconfig.yaml in .gitignore by default.
Adaptive init is now a separate safety layer:
--init --adaptive-init --init-preview
- scans the repository
- prints evidence-backed config suggestions
- writes nothing
--init --adaptive-init --apply-init-suggestions
- opt-in merge path
- keeps your file as written (keys and comments) and adds only new ignore
lines; a file it cannot extend in place is rewritten with a warning
- suggests ignoring only directories that hold code and are not excluded yet
- lists complex functions for review; it never writes an override that
would exempt them
JS/TS Analysis — optional tree-sitter path
pip install "ai-slop-detector[js]"
slop-detector --project ./src # now includes .js/.jsx/.ts/.tsx files
Activates JSAnalyzer v2.8.0 with tree-sitter AST (regex fallback when not installed).
Results appear under js_file_results in ProjectAnalysis and JSON output.
The regex fallback cannot measure god functions, dead code or complexity;
scan_coverage.analysis_modes lists those checks as not_measured, and the
text, rich and markdown reports say so in one line.
Go Analysis — regex-based, optional tree-sitter-go path
pip install "ai-slop-detector[go]"
slop-detector --project ./src # now includes .go files
Activates GoAnalyzer v1.0.0. Detects: empty function stubs, panic() as error handling,
fmt.Println/Printf debug prints, _ = ignored errors, TODO/FIXME comments, god functions
(> 60 lines). Results appear under go_file_results in JSON output.
Self-Calibration — advisory weight report (Calibration v2)
slop-detector . --self-calibrate # advisory: what this project's history suggests
Learns ldr / inflation / ddc (purity is held) from the comparable runs of the
scanned project root only: same detector, engine and configuration. An
improvement needs a changed file whose metric-only score fell from the
SUSPICIOUS band; a flagged file left unchanged counts once. Pattern penalties
are never learned as weights. The report is advisory only: scans never
run it, and --apply-calibration is disabled (it writes nothing and exits 2).
History recorded before v3.10 has no measurement provenance and is reported as
legacy, not evidence (on one real database v1 learned 79% of its
“improvements” from files that had not changed).
docs/SELF_CALIBRATION.md → · Validation boundary →
History Tracking — longitudinal quality analysis
slop-detector mycode.py --show-history # per-file trend
slop-detector --history-trends # 7-day project aggregate
slop-detector --export-history data.jsonl
Every run auto-recorded to ~/.slop-detector/history.db. The history database is
the repository-local signal source for operational calibration and trend review.
docs/HISTORY_TRACKING.md →
Claude Code Integration
cp -r claude-skills/slop-detector ~/.claude/skills/
# restart Claude Code, then use the canonical review surfaces below
Adds a persistent JSON-first review loop inside Claude Code:
review → inspect evidence → apply bounded fixes → pulse/sweep → human handoff.
| Command |
What it does |
slop-detector review . --format json |
Changed-code review with verdict, attribution, targets, actions, and findings |
slop-detector pulse . --format json |
Health summary plus hotspot prioritization |
slop-detector sweep <family> . --format json |
Cleanup planning for dead code, duplication, deps, stale suppressions, or boundaries |
slop-detector scan . --format json |
Full baseline analysis when the agent needs the complete core report |
slop-detector verify-governance <artifact> |
Governance artifact verification kept separate from score output |
Recommended use:
- start with
review for PR-like work
- use
pulse to decide what to fix next
- use
sweep only for bounded cleanup families
- re-run after each patch instead of assuming the first diagnosis still holds
- escalate to a human with evidence, not just a score
Skill source → · Full docs →
Local Calibration
AI-SLOP Detector can report how its weights would change from the history of
one project root. This is a local operational aid: it is not a
multi-repository data collection channel, a global profile injector, or
evidence that the score is externally validated.
The report is bounded by comparable evidence (same measurement, same project
root), per-class minimums, a confidence gap, and the configuration boundary:
it never writes weights. Review a recommendation before changing
.slopconfig.yaml for a team workflow. See
docs/SELF_CALIBRATION.md for the supported flow and
docs/VALIDATION.md for the validation boundary.
Security Considerations
.slopconfig.yaml sensitivity
Your .slopconfig.yaml contains domain_overrides — a precise map of which functions
are exempt from complexity rules. This is effectively a codebase weakness surface:
it reveals which areas are too complex to refactor right now.
Best practice:
- Run
slop-detector --init to generate .slopconfig.yaml and auto-add it to .gitignore
- To share governance config with your team, explicitly remove
.slopconfig.yaml from .gitignore
- Open-source repos committing it is fine (transparency over obscurity — see this project’s own
.slopconfig.yaml)
history.db
History is stored at ~/.slop-detector/history.db (your home directory, outside all repos).
It is never committed and accumulates across all projects you scan.
Adversarial Validation (SPAR-Code) — ground-truth regression guard
fhval spar # 3-layer adversarial check
fhval spar --layer a # known-pattern anchors
fhval spar --layer c # existence probes
Verifies each metric is measuring what it claims. Catches calibration drift
before it reaches production.
Structural Coherence — project-level signal
project = detector.analyze_project("./src")
print(project.structural_coherence) # 0.0 – 1.0
Experimental. Use for longitudinal comparison within a project, not as an
absolute gate. Exact MST topology is used up to
advanced.exact_topology_ceiling (default 300 files); above that the engine
switches to a deterministic approximation and reports
coherence_level = "vr_structural_approx". docs/ARCHITECTURE.md →
Source held in memory
from slop_detector.core import SlopDetector
detector = SlopDetector()
result = detector.analyze_code_string(code) # no location
result = detector.analyze_code_string(code, "pkg/mod.py", project_root=".") # as that file
Without project_root the filename is only a label: no sibling module,
project root or dependency declaration is read, and an import the installed
environment cannot resolve (it may be local code) is listed in
unverified_imports instead of being reported. With project_root the
source is analyzed as analyze_file(project_root/filename, root=project_root)
would analyze it.
CI/CD Integration
pre-commit (runs on every commit):
# .pre-commit-config.yaml
repos:
- repo: https://github.com/flamehaven01/AI-SLOP-Detector
rev: v3.7.3
hooks:
- id: slop-detector # hard gate — fails on CRITICAL_DEFICIT >= 70
# - id: slop-detector-warn # soft mode — reports only, never blocks
# - id: slop-detector-patterns # fast per-file pattern scan
GitHub Actions (runs on every PR):
# .github/workflows/quality-gate.yml
- name: AI-SLOP Gate
run: |
pip install "ai-slop-detector>=3.7.3"
slop-detector --project . --ci-mode hard --ci-report
Enforcement modes:
--ci-mode soft # informational, never fails build
--ci-mode hard # fails: deficit_score >= 70, critical_patterns >= 3, inflation >= 1.5, ddc < 0.5
--ci-mode quarantine # escalates repeat offenders after 3 violations
Full CI/CD Integration Guide →
Configuration
# .slopconfig.yaml
weights:
ldr: 0.40
inflation: 0.30
ddc: 0.20
purity: 0.10
patterns:
god_function:
domain_overrides:
- function_pattern: "check_node" # AST walker — complex by design
complexity_threshold: 30
lines_threshold: 200
ignore:
- "tests/**"
- "**/__init__.py"
advanced:
exact_topology_ceiling: 300
topology_mode_above_ceiling: deterministic_approximate
analysis_cache_enabled: true
analysis_cache_db: ""
churn_commit_window: 200
coverage_data_file: ".coverage"
hotspot_limit: 10
hotspot_weights:
deficit: 0.50
churn: 0.30
coverage_gap: 0.20
architecture:
enabled: true
preset: layered
layers: []
Full Configuration Guide → · Config Examples →
Inline Suppression
Use inline suppression when a specific local exception is intentional and should
remain visible in audit output:
# slop-disable-next-line bare_except
except:
pass
# slop-disable all
def compatibility_layer():
...
# slop-enable all
# slop-disable-next-line <pattern_id|all># slop-disable <pattern_id|all># slop-enable <pattern_id|all>
Suppressed findings are removed from scoring, but they are still recorded in the
suppression ledger so reviewers can see which lines were muted.
Repeated-Run Cache
Repeated Python-file analysis can reuse prior results through the SQLite-backed
metadata cache:
advanced:
analysis_cache_enabled: true
analysis_cache_db: "" # empty = default user cache under ~/.slop-detector/
- Cache keys include file path, size,
mtime, content hash, engine version, and config fingerprint.
- A changed file or changed config invalidates only the affected entries.
- Current scope is Python file analysis reuse; project aggregation still recomputes from the live file set.
Priority Hotspots
Project scans now rank repair order instead of only printing static scores.
The hotspot layer combines:
- deficit score
- recent git churn
- coverage gap from
.coverage
When present, the report highlights files that are both sloppy and risky to
change because they churn often or remain under-tested. If git metadata or
coverage data is missing, the prioritization layer degrades gracefully instead
of failing the scan.
Agent Surface
The FastAPI server exposes an agent-native contract alongside the existing
human-oriented /analyze/* routes:
GET /agent/schemaPOST /agent/filePOST /agent/project
These routes return structured snapshots with summary metrics, suppression
metadata, hotspot ranking, and the raw analysis payload so tools can consume
the results without scraping text output.
VS Code Extension
Real-time inline diagnostics, debounced lint-on-type, ML score and purity signal in status bar. v3.7.1 rebuilt from a single 855-line monolith into eight focused modules.
What you see:
| Surface |
Detail |
| Status bar |
$(error) SLOP 45.2 — severity icon + deficit score, updates on save |
| Inline diagnostics |
Pattern issues with line references — phantom imports, god functions, lint escapes |
| TreeView sidebar |
Activity bar panel: files sorted by deficit score, metric rows (LDR/DDC/Purity/Inflation), issue list with click-to-navigate |
| CodeLens |
Line 0: file summary (SLOP 45.2 — 3 CRITICAL); per-function: top severity icon + pattern IDs |
| QuickFix (CodeAction) |
Lightbulb on phantom_import/god_function/lint_escape diagnostics — show output or add to .slopconfig.yaml ignore |
| ML signal |
ML: 73% [slop] in summary diagnostic when [ml] extra is installed |
Commands (Ctrl+Shift+P > “SLOP”):
| Command |
Description |
| Analyze Current File |
On-demand single-file scan |
| Analyze Workspace |
Project-wide scan, populates TreeView |
| Show 4D Breakdown |
Webview: penalty attribution — why a file is not 0.0 |
| Show Cleanup Plan |
Webview: confidence-ranked sweep family (safe/needs/unsafe) |
| Show Pulse Dashboard |
Webview: project health + priority hotspots |
| Show Changed-Code Review |
Webview: diff-aware review, new-vs-inherited slop |
| Auto-Fix Detected Issues |
Apply (or dry-run preview) auto-fixable patterns |
| Show Gate Decision (SNP) |
PASS/HALT with sr9/di2/jsd/ove metrics |
| Run Cross-File Analysis |
Dependency + clone graph across project |
| Show File History |
Per-file deficit score trend |
| Show History Trends |
7-day project-wide daily trend table |
| Export History to JSONL |
Dump history.db records for external analysis |
| Bootstrap .slopconfig.yaml |
Domain-aware config generation (--init) |
| Run Self-Calibration |
Advisory 4D weight report (weights are not applied) |
Install from the VS Code Marketplace
or build locally:
cd vscode-extension
npm install
npx vsce package # produces vscode-slop-detector-3.7.3.vsix
code --install-extension vscode-slop-detector-3.7.3.vsix
Settings (slopDetector.*): pythonPath, lintOnSave, lintOnType,
failThreshold (default 50), warnThreshold (default 30), recordHistory, enableCodeLens (default true).
Release Highlights
| Version |
Highlights |
| 3.13.0 (candidate) |
precision and detection release: declared defaults (null objects, named bases, registered hooks, declared no-ops) are no longer placeholders; logged NotImplementedError stubs, constant success reports and discarded results are; known limits listed in the release notes; npm wrapper with provenance |
| v3.12.0 |
detection release: stubs behind logging, unchanged-argument stubs, catch-all handlers returning the success result, ignored parameters; balanced parallel test runner for development |
| v3.11.0 |
one engine release: CLI, MCP and REST run the same ScanService (CLI output unchanged over 70 compared cases); MCP and REST are read-only by default, REST history is opt-in, the REST server binds 127.0.0.1; agent responses carry measurement_state / score_valid / reason; findings and scores unchanged |
| v3.10.1 |
correctness release: god_function counts logical lines and nesting rises only for if/for/while/except; BOM files and single JS/TS/Go files analyzed; crashes fixed for git repositories under non-ASCII folders and project HTML reports; scan_coverage.measurement_state / score_valid / reason, NOT EVALUATED in human reports, --fail-threshold fails when every file failed; strict config validation before the run; working pre-commit hook installer; --inspector-read-only alias of --read-only |
| v3.10.0 |
scan coverage counts unanalyzed code files, custom-rule exclusions, unevaluated tests and partially measured files, and names the checks a fallback analyzer could not run; --init keeps default weights, never writes overrides, merges without losing comments, detects the domain from project code only; import evidence reads Poetry, setup.py, setup.cfg, Pipfile, conda and nested declarations plus script-directory packages; Calibration v2 learns only from comparable, provenance-stamped history; placeholder, clone and inflation findings need evidence (declared intent, protocol methods, claim words only); one finding per bare except: pass, mutable_default_arg CRITICAL only with mutation evidence; static data modules leave the project line weight; analyze_code_string reads no implicit file system context; JS callback-hell locations and declarator names; one project walk and one AST walk per module (cold scans 2.6-3x faster); cache analysis-cache-v30. See CHANGELOG.md |
| v3.9.3 |
precision correction: elif is not nesting (deep_nesting, nested_complexity); @overload / @typing.overload are not placeholders; no_executable_code modules skip LDR/DDC instead of scoring 97.49; failed analyses are counted in scan_coverage.failed with complete: false and a hard gate fails closed; one JS pass and valid --json --js output; scan_coverage.analysis_modes; cache analysis-cache-v25 |
| v3.9.2 |
consistency and correctness release: one band set (CLEAN <30 / SUSPICIOUS / INFLATED_SIGNAL / CRITICAL_DEFICIT >=70) for files, projects, JS and Go; dependency_noise and parse_error are flags; docstrings count like comments in LDR and god_function; deep_nesting under nested_complexity charged once; exact duplicates by function body with an 8-node floor, shared by same-file and cross-file; import evidence from the scan root; byte-identical output across cache, hash seed, Rust helper and cwd; advisory-only self-calibration; unread config keys removed with a warning; --init <path> honoured; cache analysis-cache-v24 |
| v3.9.1 |
claim and path checkpoint: jargon counted only in comments and strings, never in import paths, identifiers, or leading license notices; claim evidence states structural / weak / absent / unmeasured with a per-claim support_level; justification only by structural library use; test evidence unmeasured outside test files; --ci-claims-strict keeps failing unmeasured integration evidence; root-relative path facts (fixes 0-file scans under a build/ checkout); phantom_member pattern |
| v3.9.0 |
security and evidence release: no model is read from the working directory and nothing is unpickled; JSON ML model contract with one feature extractor for training and scoring; scan --read-only; import resolution that follows CPython (src layouts, namespace packages) with structure_evidence; async def placeholder findings; working --patterns-only / --disable and multi-file pre-commit hook; unimplemented API routes answer 501 |
| v3.8.9 |
trust-and-measurement release: finding/severity summaries, coverage and ML capability disclosure, explicit --include-tests, root-relative Rust discovery parity checks, strictness-corpus controls, and no aggregate accuracy claim from dogfooding |
| v3.8.8 |
packaging metadata cleanup plus VS Code workflow tightening: SPDX string license metadata, real workspace re-scan from Refresh Issues, stale sidebar results cleared on re-analysis, exact-path issue selection, and Quick Fix writes for ignore / phantom_import_allowlist with duplicate protection |
| v3.8.7 |
false-positive reduction pack: default .claude/** ignore, runtime-only DDC accounting, quoted vocabulary tables no longer counted as inflation, monorepo + alias-aware phantom import detection, clique+size clone grouping with property-accessor exemption, JS/TS fallback callback-hell no longer confused by JSX/object literals, tiny helper docstrings ignored, and self-dogfood weighted deficit improved from 9.3892 to 6.4186 |
| v3.8.6 |
strictness stabilization + coherence cleanup: same-file exact duplicates now surface in cleanup output, four-function clone clusters no longer evade detection, dead-code cleanup requires real dead-code evidence, operations.py is split into payload/cleanup/architecture helpers, and Claude skill/docs now match the canonical scan / review / pulse / sweep surface |
| v3.8.5 |
dual-audience output: human summaries hide internal algorithm names while JSON / agent / MCP output gains deterministic next_steps and metric_guide; no breaking JSON key changes |
| v3.8.4 |
plain-language documentation entry point: benefit-first README, honest “Why Not Just Use a Linter?” / “When NOT to Use This”, acronym glossary in HOW_IT_WORKS, and plain-meaning config guidance without changing code or contracts |
| v3.8.3 |
human-friendly metric output (value / healthy direction / what it means + deficit bands) and deterministic Next Steps across rich/text/markdown; VS Code webview surfaces (4D breakdown, cleanup plan, pulse, diff-aware review); fixes for dead-code semantics, adaptive-init config preservation, and unused-deps stdlib / dev-tool false positives |
| v3.8.2 |
adaptive --init adds bounded repo-signal suggestions and preview/merge flows; npm wrapper adds typed contracts, Node API, and agent workflow docs; local impact tracking and opt-in telemetry become first-class observability surfaces |
| v3.8.1 |
cleanup-family outputs become confidence-ranked action plans; unused-deps grows manifest hygiene for pyproject.toml / package.json; boundary-violations gains opt-in layered architecture review with explicit rule evidence |
| v3.7.9 |
Governance gate: verify-governance fail-closed CLI, deterministic governance-record verification, and a formal split between scoring math and enforcement |
| v3.7.3 |
Hotfix: pydantic import wrapped in try/except ImportError — package imports cleanly in stripped environments; test_api_models.py guard corrected to fastapi; CI Docker login continue-on-error, quality gate pinned to >=3.7.3 |
| v3.7.2 |
Core schema validation: config.py Pydantic guards catch bad .slopconfig.yaml at load time (wrong weight types, domain_overrides non-int thresholds); LDRResult / DDCResult / InflationResult __post_init__ clamps protect GQG math.log(); HistoryEntry sanitises all LEDA calibration inputs + validates fired_rules JSON; VS Code: schema.ts ISlopReport interfaces + parseSlopReport() handwritten discriminated-union guard — schema mismatch surfaces exact field path before silent NaN |
| v3.7.1 |
LintEscapePattern docstring FP fix; self-scan avg_deficit 13.85 → 9.80; global_injector.py Patch 1 removed; .slopconfig.yaml domain_overrides expanded; Skill: 3-Phase Pipeline (Triage → Deep-Dive → Action Plan), /slop-delta before/after comparison, Confidence Routing by status band, → Next: guidance per command; VS Code: P1 monolith → 8 focused modules, P2 SlopCodeActionProvider (QuickFix for phantom_import/god_function/lint_escape), P3 TreeView sidebar (3-level hierarchy), P4 SlopCodeLensProvider (file summary + per-function hints) |
| v3.7.0 |
Dogfooding calibration + SKILL.md OSOT repair (10 violations); cli_renderer.py split (730 lines → 4 renderer modules); python_advanced.py split (1150 lines → 5 modules); BUG-1 ddc weight 0.30→0.20; BUG-2 findings filter threshold fix; BUG-3 AST-accurate test counts; BUG-5 block-scoped YAML rewrite in self_calibrator; 314 tests GREEN |
| v3.6.0 |
Claude Code Skill (/slop, /slop-file, /slop-gate, /slop-spar); CI gate bugfix (--ci-mode hard now exits non-zero without --ci-report); pre-commit hooks rewritten (python -m entry, 3 hook variants); VS Code Extension v3.6.0 VSIX; docs: Purity row, weight normalization note, [go] extra; 311 tests GREEN |
| v3.5.0 |
Domain-aware --init (8 profiles, --domain flag); JS/TS analysis via JSAnalyzer v2.8.0 + [js]; Go analysis via GoAnalyzer v1.0.0 + [go]; self-calibration patches: project-scoped history (project_id), re-scan milestone trigger, domain-anchored grid search (±0.15), CalibrationResult.warnings (drift > 0.25); 308 tests GREEN |
| v3.4.1 |
FileRole.STUB (Protocol/ABC stubs skip ldr+patterns); auto-discover .slopconfig.yaml; Python 3.8 CI compat; mypy attr-defined fix |
| v3.4.0 |
Per-rule FP rate tracking (LEDA Phase 2A); purity weight ceiling MAX_PURITY_WEIGHT=0.25 (Phase 2B) |
| v3.3.0 |
File role classifier (SOURCE/INIT/RE_EXPORT/TEST/MODEL/CORPUS); DDC annotation-only import fix; # noqa: F401 + __all__ re-export recognition |
| v3.2.1 |
Auto-calibration at every 10-scan milestone (no manual cmd); P2 git noise filter; P3 per-class thresholds (5+5); calibrate() min_events bugfix; 11/11 e2e GREEN |
| v3.2.0 |
4D calibration (purity dimension); --init bootstrap; auto-calibration hints; 44/44 self-scan CLEAN |
| v3.1.2 |
data_collector refactor; slopconfig gap fill; 43/43 self-scan CLEAN |
| v3.1.1 |
Clone Detection in Core Metrics table; table style unification; VS Code UX |
| v3.1.0 |
3 new adversarial patterns (function_clone_cluster, placeholder_variable_naming, return_constant_stub); GQG calibrator alignment; fhval SPAR-Code |
| v3.0.2 |
Phantom import 3-tier classification; __init__.py LDR fix; god_function LOW demotion |
| v3.0.0 |
Geometric mean scorer (GQG); purity dimension; DCF per-file; structural coherence |
| v2.9.3 |
Self-calibration engine; weight grid-search from usage history |
| v2.9.0 |
phantom_import CRITICAL detection; history auto-tracking |
Full Release Notes → · Changelog →
Development
git clone https://github.com/flamehaven01/AI-SLOP-Detector.git
cd AI-SLOP-Detector
pip install -e ".[dev]"
pytest tests/ -v --cov
black src/ tests/
ruff check src/ tests/
Development Guide →
Download Stats
Chart updated weekly via GitHub Actions. Monthly installs: pypistats.org (mirrors excluded). Total: pepy.tech (incl. mirrors)
License
MIT — see LICENSE.
Flamehaven Labs •
Issues •
Discussions •
Docs
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)
评论