sloplinter 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,11 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 an1zy
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files, to deal in the Software
7
+ without restriction, including without limitation the rights to use, copy,
8
+ modify, merge, publish, distribute, sublicense, and/or sell copies of the
9
+ Software, subject to the condition that the above copyright notice and this
10
+ permission notice shall be included in all copies or substantial portions of
11
+ the Software.
@@ -0,0 +1,80 @@
1
+ Metadata-Version: 2.4
2
+ Name: sloplinter
3
+ Version: 0.1.0
4
+ Summary: Zero-bloat CLI linter that detects AI-generated code slop across Python, JS/TS, Rust, C/C++, C#, Go, and Java
5
+ License: MIT
6
+ Project-URL: Homepage, https://github.com/an1zy/slopcheck
7
+ Project-URL: Repository, https://github.com/an1zy/slopcheck
8
+ Keywords: linter,ast,cli,ai,code-quality
9
+ Requires-Python: >=3.11
10
+ Description-Content-Type: text/markdown
11
+ License-File: LICENSE
12
+ Requires-Dist: rich>=13.0.0
13
+ Dynamic: license-file
14
+
15
+ # slopcheck
16
+
17
+ ![Slop Score](https://img.shields.io/badge/slop_score-0%25-brightgreen)
18
+ ![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)
19
+
20
+ Fast CLI linter that detects AI-generated code slop and calculates a Slop Score (deep AST analysis for Python + polyglot scanner for JS/TS, Rust, C/C++, C#, Go, Java).
21
+
22
+ <!-- DEMO_SCREENSHOT -->
23
+
24
+ ## Install
25
+
26
+ ```bash
27
+ pip install sloplinter
28
+ ```
29
+
30
+ Or run ephemerally with `uvx`:
31
+
32
+ ```bash
33
+ uvx sloplinter .
34
+ ```
35
+
36
+ ## Usage
37
+
38
+ Run a scan against the current repository or a specific directory:
39
+
40
+ ```bash
41
+ slopcheck .
42
+ ```
43
+
44
+ Enforce quality gates in CI (exit code 1 if score exceeds threshold):
45
+
46
+ ```bash
47
+ slopcheck . --max-score 20
48
+ ```
49
+
50
+ Generate a Markdown badge for your repository `README.md`:
51
+
52
+ ```bash
53
+ slopcheck . --badge
54
+ ```
55
+
56
+ Score thresholds:
57
+ - 0-10%: `CLEAN`
58
+ - 11-35%: `SUSPICIOUS`
59
+ - 36-65%: `VIBE-CODED`
60
+ - 66-100%: `PURE SLOP`
61
+
62
+ ## Rules
63
+
64
+ | Rule | Weight | Languages | What it catches |
65
+ | :--- | :---: | :--- | :--- |
66
+ | `silent-except` | 15 | Python | Catch handler containing only `pass`, `...`, or lone `print` |
67
+ | `silent-catch` | 15 | JS/TS, C++, C#, Java | Empty or suppressed catch blocks |
68
+ | `ai-cliche` | 12 | All supported | Markers like `TODO: implement`, `placeholder`, `in a real-world`, `for brevity` |
69
+ | `emoji-slop` | 10 | All supported | Decorative emojis in comments and log/print statements |
70
+ | `deep-nesting` | 10 | Python | Control structure nesting depth >= 4 (ignoring `elif`) |
71
+ | `debug-print` | 8 | All supported | Print calls with debug prefixes (`debug`, `here`, `test`, `asdf`, etc.) |
72
+ | `wildcard-import` | 8 | Python | `from ... import *` imports |
73
+ | `bloat-docstring` | 8 | Python | Docstrings larger than the actual function body |
74
+ | `useless-wrapper` | 7 | Python | Thin wrappers forwarding exact arguments without modification |
75
+ | `captain-comment` | 6 | All supported | Standalone comment echoing identifiers on the line directly below |
76
+ | `redundant-boolean` | 6 | Python | Comparisons with `True`/`False` or `if/else` returning boolean literals |
77
+
78
+ ## License
79
+
80
+ MIT
@@ -0,0 +1,66 @@
1
+ # slopcheck
2
+
3
+ ![Slop Score](https://img.shields.io/badge/slop_score-0%25-brightgreen)
4
+ ![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)
5
+
6
+ Fast CLI linter that detects AI-generated code slop and calculates a Slop Score (deep AST analysis for Python + polyglot scanner for JS/TS, Rust, C/C++, C#, Go, Java).
7
+
8
+ <!-- DEMO_SCREENSHOT -->
9
+
10
+ ## Install
11
+
12
+ ```bash
13
+ pip install sloplinter
14
+ ```
15
+
16
+ Or run ephemerally with `uvx`:
17
+
18
+ ```bash
19
+ uvx sloplinter .
20
+ ```
21
+
22
+ ## Usage
23
+
24
+ Run a scan against the current repository or a specific directory:
25
+
26
+ ```bash
27
+ slopcheck .
28
+ ```
29
+
30
+ Enforce quality gates in CI (exit code 1 if score exceeds threshold):
31
+
32
+ ```bash
33
+ slopcheck . --max-score 20
34
+ ```
35
+
36
+ Generate a Markdown badge for your repository `README.md`:
37
+
38
+ ```bash
39
+ slopcheck . --badge
40
+ ```
41
+
42
+ Score thresholds:
43
+ - 0-10%: `CLEAN`
44
+ - 11-35%: `SUSPICIOUS`
45
+ - 36-65%: `VIBE-CODED`
46
+ - 66-100%: `PURE SLOP`
47
+
48
+ ## Rules
49
+
50
+ | Rule | Weight | Languages | What it catches |
51
+ | :--- | :---: | :--- | :--- |
52
+ | `silent-except` | 15 | Python | Catch handler containing only `pass`, `...`, or lone `print` |
53
+ | `silent-catch` | 15 | JS/TS, C++, C#, Java | Empty or suppressed catch blocks |
54
+ | `ai-cliche` | 12 | All supported | Markers like `TODO: implement`, `placeholder`, `in a real-world`, `for brevity` |
55
+ | `emoji-slop` | 10 | All supported | Decorative emojis in comments and log/print statements |
56
+ | `deep-nesting` | 10 | Python | Control structure nesting depth >= 4 (ignoring `elif`) |
57
+ | `debug-print` | 8 | All supported | Print calls with debug prefixes (`debug`, `here`, `test`, `asdf`, etc.) |
58
+ | `wildcard-import` | 8 | Python | `from ... import *` imports |
59
+ | `bloat-docstring` | 8 | Python | Docstrings larger than the actual function body |
60
+ | `useless-wrapper` | 7 | Python | Thin wrappers forwarding exact arguments without modification |
61
+ | `captain-comment` | 6 | All supported | Standalone comment echoing identifiers on the line directly below |
62
+ | `redundant-boolean` | 6 | Python | Comparisons with `True`/`False` or `if/else` returning boolean literals |
63
+
64
+ ## License
65
+
66
+ MIT
@@ -0,0 +1,27 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "sloplinter"
7
+ version = "0.1.0"
8
+ description = "Zero-bloat CLI linter that detects AI-generated code slop across Python, JS/TS, Rust, C/C++, C#, Go, and Java"
9
+ readme = "README.md"
10
+ license = { text = "MIT" }
11
+ requires-python = ">=3.11"
12
+ keywords = ["linter", "ast", "cli", "ai", "code-quality"]
13
+ dependencies = [
14
+ "rich>=13.0.0",
15
+ ]
16
+
17
+ [project.urls]
18
+ Homepage = "https://github.com/an1zy/slopcheck"
19
+ Repository = "https://github.com/an1zy/slopcheck"
20
+
21
+ [project.scripts]
22
+ slopcheck = "slopcheck.cli:main"
23
+ sloplinter = "slopcheck.cli:main"
24
+
25
+ [tool.setuptools.packages.find]
26
+ where = ["."]
27
+ include = ["slopcheck*"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,14 @@
1
+ from slopcheck.core import (
2
+ Issue,
3
+ calculate_score,
4
+ iter_python_files,
5
+ iter_source_files,
6
+ )
7
+
8
+ __all__ = [
9
+ "Issue",
10
+ "calculate_score",
11
+ "iter_python_files",
12
+ "iter_source_files",
13
+ ]
14
+ __version__ = "0.1.0"
@@ -0,0 +1,149 @@
1
+ import argparse
2
+ import ast
3
+ from pathlib import Path
4
+ import sys
5
+ import time
6
+
7
+ from rich.console import Console
8
+
9
+ from slopcheck.core import Issue, calculate_score, iter_source_files
10
+ from slopcheck.polyglot import check_polyglot
11
+ from slopcheck.rules import ALL_RULES
12
+
13
+ RULE_COLORS = {
14
+ "silent-except": "red",
15
+ "silent-catch": "red",
16
+ "bloat-docstring": "magenta",
17
+ "ai-cliche": "yellow",
18
+ "captain-comment": "cyan",
19
+ "emoji-slop": "yellow",
20
+ "debug-print": "red",
21
+ "redundant-boolean": "yellow",
22
+ "deep-nesting": "red",
23
+ "wildcard-import": "magenta",
24
+ "useless-wrapper": "cyan",
25
+ }
26
+
27
+
28
+ def get_verdict(score: int) -> tuple[str, str]:
29
+ if score <= 10:
30
+ return "CLEAN", "green"
31
+ if score <= 35:
32
+ return "SUSPICIOUS", "yellow"
33
+ if score <= 65:
34
+ return "VIBE-CODED", "magenta"
35
+ return "PURE SLOP", "red"
36
+
37
+
38
+ def get_badge_color(score: int) -> str:
39
+ if score <= 10:
40
+ return "brightgreen"
41
+ if score <= 35:
42
+ return "yellow"
43
+ if score <= 65:
44
+ return "orange"
45
+ return "red"
46
+
47
+
48
+ def main() -> None:
49
+ parser = argparse.ArgumentParser(
50
+ prog="slopcheck",
51
+ description="Linter for code slop, bloated docstrings, and cargo-cult comments.",
52
+ )
53
+ parser.add_argument(
54
+ "path",
55
+ nargs="?",
56
+ default=".",
57
+ type=Path,
58
+ help="Directory or file to scan (default: .)",
59
+ )
60
+ parser.add_argument(
61
+ "--max-score",
62
+ type=int,
63
+ default=100,
64
+ help="Maximum acceptable slop score (default: 100)",
65
+ )
66
+ parser.add_argument(
67
+ "--badge",
68
+ action="store_true",
69
+ help="Print a shields.io markdown badge instead of the full report",
70
+ )
71
+ args = parser.parse_args()
72
+
73
+ start_time = time.perf_counter()
74
+ files = list(iter_source_files(args.path))
75
+ total_lines = 0
76
+ all_issues: list[Issue] = []
77
+ file_issues: dict[Path, list[Issue]] = {}
78
+
79
+ for file_path in files:
80
+ try:
81
+ source = file_path.read_text(encoding="utf-8", errors="replace")
82
+ except OSError:
83
+ continue
84
+
85
+ total_lines += len(source.splitlines())
86
+ current_issues: list[Issue] = []
87
+
88
+ if file_path.suffix == ".py":
89
+ try:
90
+ tree = ast.parse(source, filename=str(file_path))
91
+ except SyntaxError:
92
+ tree = None
93
+
94
+ for rule in ALL_RULES:
95
+ current_issues.extend(rule(file_path, source, tree))
96
+ else:
97
+ current_issues.extend(check_polyglot(file_path, source))
98
+
99
+ if current_issues:
100
+ current_issues.sort(key=lambda i: (i.line, i.rule))
101
+ file_issues[file_path] = current_issues
102
+ all_issues.extend(current_issues)
103
+
104
+ elapsed = time.perf_counter() - start_time
105
+ score = calculate_score(all_issues, total_lines)
106
+
107
+ if args.badge:
108
+ badge_color = get_badge_color(score)
109
+ print(f"![Slop Score](https://img.shields.io/badge/slop_score-{score}%25-{badge_color})")
110
+ if score > args.max_score:
111
+ sys.exit(1)
112
+ return
113
+
114
+ verdict, color = get_verdict(score)
115
+ console = Console(highlight=False)
116
+
117
+ if file_issues:
118
+ console.print()
119
+ for file_path, issues in file_issues.items():
120
+ try:
121
+ display_path = file_path.relative_to(Path.cwd())
122
+ except ValueError:
123
+ display_path = file_path
124
+ console.print(f"[bold white]{display_path}[/]")
125
+ for issue in issues:
126
+ rule_color = RULE_COLORS.get(issue.rule, "white")
127
+ console.print(
128
+ f" [dim]{issue.line:>4}[/] [{rule_color}]{issue.rule:<18}[/] [dim]+{issue.weight:<2}[/] {issue.message}"
129
+ )
130
+ console.print()
131
+
132
+ bar_width = 30
133
+ filled = int(round(bar_width * (score / 100)))
134
+ empty = bar_width - filled
135
+ bar = f"[{color}]{'█' * filled}[/][bright_black]{'░' * empty}[/]"
136
+
137
+ console.print(f" [bold white]Slop Score[/] [{color} bold]{score:>3}%[/] {bar} [{color} bold]{verdict}[/]")
138
+ console.print(f" [dim]Scanned {len(files)} files ({total_lines:,} lines) in {elapsed:.3f}s[/dim]")
139
+ console.print()
140
+
141
+ if score > args.max_score:
142
+ console.print(
143
+ f"[bold red]FAILED:[/] Slop score {score} exceeds maximum allowed threshold of {args.max_score}\n"
144
+ )
145
+ sys.exit(1)
146
+
147
+
148
+ if __name__ == "__main__":
149
+ main()
@@ -0,0 +1,86 @@
1
+ import os
2
+ from dataclasses import dataclass
3
+ from pathlib import Path
4
+ from typing import Iterator
5
+
6
+ SKIP_DIRS = frozenset({
7
+ ".git",
8
+ ".venv",
9
+ "venv",
10
+ "__pycache__",
11
+ "node_modules",
12
+ "build",
13
+ "dist",
14
+ "target",
15
+ "bin",
16
+ "obj",
17
+ ".next",
18
+ "out",
19
+ "vendor",
20
+ })
21
+
22
+ SKIP_FILE_SUFFIXES = (".min.js", ".bundle.js", ".d.ts")
23
+
24
+ SUPPORTED_EXTENSIONS = frozenset({
25
+ ".py",
26
+ ".js",
27
+ ".jsx",
28
+ ".ts",
29
+ ".tsx",
30
+ ".rs",
31
+ ".c",
32
+ ".cpp",
33
+ ".cc",
34
+ ".h",
35
+ ".hpp",
36
+ ".cs",
37
+ ".go",
38
+ ".java",
39
+ })
40
+
41
+
42
+ @dataclass(frozen=True)
43
+ class Issue:
44
+ path: Path
45
+ line: int
46
+ rule: str
47
+ message: str
48
+ weight: int
49
+
50
+
51
+ def _is_skipped_file(name: str) -> bool:
52
+ lower_name = name.lower()
53
+ return any(lower_name.endswith(sfx) for sfx in SKIP_FILE_SUFFIXES)
54
+
55
+
56
+ def iter_source_files(root: Path) -> Iterator[Path]:
57
+ if not root.exists():
58
+ return
59
+
60
+ if root.is_file():
61
+ if root.suffix in SUPPORTED_EXTENSIONS and not _is_skipped_file(root.name):
62
+ yield root
63
+ return
64
+
65
+ for dirpath, dirnames, filenames in os.walk(root):
66
+ # Pruning in-place prevents descending into ignored directory trees
67
+ dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
68
+ for filename in filenames:
69
+ if _is_skipped_file(filename):
70
+ continue
71
+ if Path(filename).suffix in SUPPORTED_EXTENSIONS:
72
+ yield Path(dirpath, filename)
73
+
74
+
75
+ # Backwards compatibility alias
76
+ iter_python_files = iter_source_files
77
+
78
+
79
+ def calculate_score(issues: list[Issue], total_lines: int) -> int:
80
+ if total_lines <= 0 or not issues:
81
+ return 0
82
+
83
+ total_weight = sum(issue.weight for issue in issues)
84
+ # Increased sensitivity (~3.5x) so ~20 major issues per 3500 lines yield ~25-35%
85
+ score = int(round((total_weight / total_lines) * 350))
86
+ return min(100, max(0, score))
@@ -0,0 +1,194 @@
1
+ from pathlib import Path
2
+ import re
3
+
4
+ from slopcheck.core import Issue
5
+ from slopcheck.rules import (
6
+ _count_word_matches,
7
+ _extract_words,
8
+ _match_ai_cliche,
9
+ AI_EMOJIS,
10
+ DEBUG_MARKERS,
11
+ )
12
+
13
+ TOKEN_SPEC = re.compile(
14
+ r'(?P<BLOCK_COMMENT>/\*.*?\*/)'
15
+ r'|(?P<LINE_COMMENT>//[^\n]*)'
16
+ r'|(?P<STRING_DOUBLE>"(\\.|[^"\\])*")'
17
+ r'|(?P<STRING_SINGLE>\'(\\.|[^\'\\])*\')'
18
+ r'|(?P<STRING_BACKTICK>`(\\.|[^`\\])*`)',
19
+ re.DOTALL
20
+ )
21
+
22
+ CALL_PATTERN = re.compile(
23
+ r"\b(?P<call>console\.log|println!|Console\.WriteLine|printf|fmt\.Println|System\.out\.println)\s*\((?P<args>[^)]*)\)"
24
+ r"|"
25
+ r"\b(?P<cout>(?:std::)?cout)\s*<<\s*(?P<cout_args>[^;]+);",
26
+ re.MULTILINE
27
+ )
28
+
29
+ CATCH_PATTERN = re.compile(
30
+ r"\bcatch\s*(?:\([^{]*\))?\s*\{(?:\s*|(?:\s*;\s*))\}",
31
+ re.MULTILINE
32
+ )
33
+
34
+ STR_EXTRACT_PATTERN = re.compile(
35
+ r'"((?:\\.|[^"\\])*)"|\'((?:\\.|[^\'\\])*)\'|`((?:\\.|[^`\\])*)`'
36
+ )
37
+
38
+
39
+ def _extract_c_strings(text: str) -> list[str]:
40
+ strings: list[str] = []
41
+ for m in STR_EXTRACT_PATTERN.finditer(text):
42
+ for g in m.groups():
43
+ if g is not None:
44
+ strings.append(g)
45
+ break
46
+ return strings
47
+
48
+
49
+ def _is_captain_comment(comment_text: str, next_line: str) -> bool:
50
+ if not next_line or next_line.startswith(("//", "/*", "*")):
51
+ return False
52
+ c_words = _extract_words(comment_text)
53
+ code_words = _extract_words(next_line)
54
+ if len(c_words) < 2 or not code_words:
55
+ return False
56
+ return _count_word_matches(c_words, code_words) >= 2
57
+
58
+
59
+ def _extract_c_tokens(source: str) -> tuple[list[dict], str]:
60
+ comments: list[dict] = []
61
+
62
+ def repl(m: re.Match) -> str:
63
+ kind = m.lastgroup
64
+ start = m.start()
65
+ prev_nl = source.rfind('\n', 0, start)
66
+ prefix = source[prev_nl + 1:start]
67
+ line = source[:start].count('\n') + 1
68
+
69
+ if kind == "LINE_COMMENT":
70
+ comments.append({
71
+ "type": "line",
72
+ "text": m.group(0),
73
+ "line": line,
74
+ "standalone": prefix.strip() == "",
75
+ })
76
+ return " " * len(m.group(0))
77
+
78
+ if kind == "BLOCK_COMMENT":
79
+ comments.append({
80
+ "type": "block",
81
+ "text": m.group(0),
82
+ "line": line,
83
+ "standalone": prefix.strip() == "",
84
+ })
85
+ return "".join('\n' if c == '\n' else ' ' for c in m.group(0))
86
+
87
+ return m.group(0)
88
+
89
+ clean_code = TOKEN_SPEC.sub(repl, source)
90
+ return comments, clean_code
91
+
92
+
93
+ def _check_comments(path: Path, comments: list[dict], lines: list[str]) -> list[Issue]:
94
+ issues: list[Issue] = []
95
+ for c in comments:
96
+ text, line, is_standalone = c["text"], c["line"], c["standalone"]
97
+
98
+ matched = _match_ai_cliche(text)
99
+ if matched:
100
+ issues.append(
101
+ Issue(
102
+ path=path,
103
+ line=line,
104
+ rule="ai-cliche",
105
+ message=f"AI cliché comment detected: '{matched}'",
106
+ weight=12,
107
+ )
108
+ )
109
+
110
+ if any(e in text for e in AI_EMOJIS):
111
+ issues.append(
112
+ Issue(
113
+ path=path,
114
+ line=line,
115
+ rule="emoji-slop",
116
+ message="AI emoji detected in comment",
117
+ weight=10,
118
+ )
119
+ )
120
+
121
+ if c["type"] == "line" and is_standalone and line < len(lines):
122
+ next_line = lines[line].strip()
123
+ if _is_captain_comment(text, next_line):
124
+ issues.append(
125
+ Issue(
126
+ path=path,
127
+ line=line,
128
+ rule="captain-comment",
129
+ message=f"Comment duplicates code on line {line + 1}",
130
+ weight=6,
131
+ )
132
+ )
133
+ return issues
134
+
135
+
136
+ def _check_output_calls(path: Path, clean_code: str) -> list[Issue]:
137
+ issues: list[Issue] = []
138
+ for m in CALL_PATTERN.finditer(clean_code):
139
+ args_text = m.group("args") if m.group("call") else m.group("cout_args")
140
+ strs = _extract_c_strings(args_text)
141
+ line = clean_code[:m.start()].count('\n') + 1
142
+
143
+ if any(any(e in s for e in AI_EMOJIS) for s in strs):
144
+ issues.append(
145
+ Issue(
146
+ path=path,
147
+ line=line,
148
+ rule="emoji-slop",
149
+ message="AI emoji detected in output call",
150
+ weight=10,
151
+ )
152
+ )
153
+
154
+ if strs:
155
+ head = strs[0].strip().lower()
156
+ if any(head == marker or head.startswith(marker) for marker in DEBUG_MARKERS):
157
+ issues.append(
158
+ Issue(
159
+ path=path,
160
+ line=line,
161
+ rule="debug-print",
162
+ message=f"Debug print statement detected: '{strs[0][:20]}'",
163
+ weight=8,
164
+ )
165
+ )
166
+ return issues
167
+
168
+
169
+ def _check_silent_catch(path: Path, clean_code: str) -> list[Issue]:
170
+ issues: list[Issue] = []
171
+ for m in CATCH_PATTERN.finditer(clean_code):
172
+ line = clean_code[:m.start()].count('\n') + 1
173
+ issues.append(
174
+ Issue(
175
+ path=path,
176
+ line=line,
177
+ rule="silent-catch",
178
+ message="Empty or suppressed catch block",
179
+ weight=15,
180
+ )
181
+ )
182
+ return issues
183
+
184
+
185
+ def check_polyglot(path: Path, source: str) -> list[Issue]:
186
+ comments, clean_code = _extract_c_tokens(source)
187
+ lines = source.splitlines()
188
+
189
+ issues: list[Issue] = []
190
+ issues.extend(_check_comments(path, comments, lines))
191
+ issues.extend(_check_output_calls(path, clean_code))
192
+ issues.extend(_check_silent_catch(path, clean_code))
193
+ issues.sort(key=lambda i: (i.line, i.rule))
194
+ return issues