@voidh4x0r/slopgate 0.0.0-stage → 0.1.1
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.
- package/CHANGELOG.md +82 -0
- package/LICENSE +21 -0
- package/README.md +304 -2
- package/dist/ast.d.ts +29 -0
- package/dist/ast.js +3 -0
- package/dist/baseline.d.ts +33 -0
- package/dist/baseline.js +104 -0
- package/dist/cli.d.ts +9 -0
- package/dist/cli.js +487 -0
- package/dist/config.d.ts +25 -0
- package/dist/config.js +91 -0
- package/dist/data/python-stdlib.d.ts +21 -0
- package/dist/data/python-stdlib.js +92 -0
- package/dist/deps.d.ts +8 -0
- package/dist/deps.js +491 -0
- package/dist/diff.d.ts +30 -0
- package/dist/diff.js +217 -0
- package/dist/engine.d.ts +15 -0
- package/dist/engine.js +169 -0
- package/dist/files.d.ts +33 -0
- package/dist/files.js +214 -0
- package/dist/mcp.d.ts +41 -0
- package/dist/mcp.js +226 -0
- package/dist/parser.d.ts +3 -0
- package/dist/parser.js +45 -0
- package/dist/reporters/github.d.ts +2 -0
- package/dist/reporters/github.js +44 -0
- package/dist/reporters/json.d.ts +10 -0
- package/dist/reporters/json.js +36 -0
- package/dist/reporters/pretty.d.ts +12 -0
- package/dist/reporters/pretty.js +103 -0
- package/dist/reporters/sarif.d.ts +2 -0
- package/dist/reporters/sarif.js +75 -0
- package/dist/rules/helpers.d.ts +53 -0
- package/dist/rules/helpers.js +178 -0
- package/dist/rules/index.d.ts +3 -0
- package/dist/rules/index.js +4 -0
- package/dist/rules/python.d.ts +2 -0
- package/dist/rules/python.js +632 -0
- package/dist/rules/typescript.d.ts +2 -0
- package/dist/rules/typescript.js +563 -0
- package/dist/suppress.d.ts +12 -0
- package/dist/suppress.js +52 -0
- package/dist/types.d.ts +95 -0
- package/dist/types.js +1 -0
- package/grammars/README.md +28 -0
- package/grammars/tree-sitter-python.wasm +0 -0
- package/grammars/tree-sitter-tsx.wasm +0 -0
- package/grammars/tree-sitter-typescript.wasm +0 -0
- package/package.json +61 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
4
|
+
|
|
5
|
+
## [Unreleased]
|
|
6
|
+
|
|
7
|
+
### Planned
|
|
8
|
+
- Duplicate-block detection across files.
|
|
9
|
+
- Go and Rust grammars.
|
|
10
|
+
- VS Code diagnostics.
|
|
11
|
+
|
|
12
|
+
## [0.1.1] - 2026-11-22
|
|
13
|
+
|
|
14
|
+
### Fixed
|
|
15
|
+
- `.pyi` type stubs and deliberate no-op shim modules (for example `multiprocessing/dummy`) are no longer reported as unfinished stubs.
|
|
16
|
+
- `pyproject.toml` parsing now understands `[project.optional-dependencies]`, `[dependency-groups]` (PEP 735, including `include-group`), `[tool.uv] dev-dependencies`, and every `[tool.poetry.group.<name>.dependencies]` group.
|
|
17
|
+
- Import-name to distribution-name mapping now covers `docx`, `pptx`, `grpc`, `git`, `nacl`, `jose`, `fitz`, `ldap`, `rest_framework` and others, and resolves dotted prefixes (`google.protobuf`) without mapping every `google.*` import to `protobuf`.
|
|
18
|
+
- `ts/noop-test` recognises `node:assert` method assertions (`assert.strictEqual`, `assert.ok`, `assert.deepStrictEqual`, `assert.match`, …), `t.ok`/`t.assert.*`, and no longer mistakes `test.valid.forEach(...)` for a test declaration.
|
|
19
|
+
- `py/swallowed-exception` counts explanatory comments between the `try` body and `except`; comment detection now uses real comment nodes instead of scanning for `#`/`//` in strings.
|
|
20
|
+
- `conftest.py`, `noxfile.py` and `docs/conf.py` are treated as test/build infrastructure, so their imports are demoted instead of failing CI.
|
|
21
|
+
- Imports under `sys.platform` / `platform.system()` guards are ignored (platform-specific modules).
|
|
22
|
+
- `confidence: "toString"` (or any other `Object.prototype` key) is rejected instead of silently hiding every finding.
|
|
23
|
+
- Scanning zero files exits 2 with a message instead of reporting a clean run.
|
|
24
|
+
- `--fail-on medium` (or `low`) no longer acts as a no-op when `--confidence` is higher: the display threshold is lowered so failing findings are visible.
|
|
25
|
+
- A `.js`/`.mjs`/`.cjs` file is parsed with the TSX grammar, so JSX in `.js` no longer forces every finding down to `medium`.
|
|
26
|
+
- The unified-diff parser tracks hunk state, so a content line such as `++ x;` can no longer be mistaken for a `+++` file header.
|
|
27
|
+
- A UTF-8 BOM is stripped before parsing, so line 1 columns are no longer off by one.
|
|
28
|
+
- Glob patterns support `{a,b}` alternatives (including nesting), so `**/*.{ts,tsx}` works.
|
|
29
|
+
- SARIF artifact URIs are percent-encoded (spaces, `#`, non-ASCII).
|
|
30
|
+
- `--write-baseline` records all current findings even when `--diff` is also set.
|
|
31
|
+
- A failed grammar load is no longer cached forever, and ignored directories no longer inflate `stats.skipped`.
|
|
32
|
+
- `slopgate init` pins the installed version instead of `@latest`, and reports relative paths consistently.
|
|
33
|
+
|
|
34
|
+
### Changed
|
|
35
|
+
- 166 tests, including regression fixtures for every fix above.
|
|
36
|
+
- Benchmark re-run after the fixes: **26 high-confidence findings across 991,705 lines of CPython, 96.2% labeled precision (25/26), 14/14 seeded defects detected, 0 high findings across 601 JavaScript files.** The labels now cover every high finding, stale labels are zero, and the results carry a corpus digest so the run can be verified without absolute paths.
|
|
37
|
+
- Docs now state that `--diff` and MCP `scan_diff` invoke `git` (and therefore need a sandbox that permits child processes), that labels are per fingerprint and come from a development set, and that the benchmark has no minimum-sample exclusion.
|
|
38
|
+
|
|
39
|
+
## [0.1.0] - 2026-11-22
|
|
40
|
+
|
|
41
|
+
### Added
|
|
42
|
+
- 14 AST-based rules:
|
|
43
|
+
- Python: `phantom-import`, `noop-test`, `tautological-assert`, `stub-body`, `swallowed-exception`, `dead-branch`, `unreachable`
|
|
44
|
+
- TypeScript/JavaScript: `phantom-import`, `noop-test`, `tautological-assert`, `stub-function`, `swallowed-exception`, `dead-branch`, `unreachable`
|
|
45
|
+
- Confidence tiers (`high` / `medium` / `low`) with machine-readable evidence for every finding. Only `high` is shown by default and fails CI.
|
|
46
|
+
- Dependency awareness: `pyproject.toml`, `requirements*.txt`, `setup.py`, `setup.cfg`, `Pipfile`, `package.json`, `tsconfig` path aliases, npm workspaces, installed `node_modules`.
|
|
47
|
+
- CLI with `pretty`, `json`, `sarif` and `github` output, stable exit codes, and `--fail-on` thresholds.
|
|
48
|
+
- `--format github` emits GitHub Actions workflow-command annotations, so findings appear inline on a pull request without code scanning.
|
|
49
|
+
- Adoption tools: `--write-baseline` + `.slopgate-baseline.json`, and `--diff <ref>` for pull-request-only scanning.
|
|
50
|
+
- Inline suppression: `slopgate-ignore-next-line`, `slopgate-ignore-line`, `slopgate-disable-file` — only honoured inside real comments.
|
|
51
|
+
- `slopgate init` writes a config file and a GitHub Actions workflow.
|
|
52
|
+
- MCP server (`slopgate mcp`) with `scan_diff`, `scan_path` and `list_rules` tools, so coding agents can lint their own changes before finishing. Respects `.slopgate.json` and the baseline.
|
|
53
|
+
- Bundled tree-sitter WASM grammars for Python, TypeScript and TSX; no Python or TypeScript toolchain needed at scan time.
|
|
54
|
+
- Reproducible precision benchmark: `scripts/benchmark.mjs`, `benchmark/labels.json`, `benchmark/report.md`.
|
|
55
|
+
- Animated terminal demo GIF (`docs/demo.gif`) generated from `scripts/demo-frame.mjs` by `scripts/make-demo-gif.mjs` (optional `sharp` + `gifenc`).
|
|
56
|
+
- `scripts/check-links.mjs` verifies every relative markdown link in CI.
|
|
57
|
+
- `slopgate path/to/file.py` scans a single file instead of walking its parent directory.
|
|
58
|
+
- 136 tests, including negative tests for every rule.
|
|
59
|
+
|
|
60
|
+
### Changed
|
|
61
|
+
- Default `--confidence` is now `high`; medium findings are opt-in.
|
|
62
|
+
- Precision pass against 991,705 lines of CPython: high findings reduced from 10,000 to 35 (91.4% labeled precision), 14/14 seeded defects still detected. A second corpus of 601 JavaScript files produces 0 high findings.
|
|
63
|
+
- Rules skip test files where the scaffolding is intentional (`dead-branch`, `unreachable`, `stub-body`, `swallowed-exception`, `phantom-import` handles them at medium confidence instead).
|
|
64
|
+
- Findings in files with syntax errors are demoted to `medium`.
|
|
65
|
+
- `ts/swallowed-exception` reports `medium` by design: empty `catch` is idiomatic JavaScript.
|
|
66
|
+
- `ts/stub-function` reports an empty body at `medium`; only an explicit `throw new Error("not implemented")` is `high`. No-op conventions (`noop`, `noOp`, `ignore`) and `@abstract` JSDoc are skipped.
|
|
67
|
+
- `ts/phantom-import` ignores URL specifiers (`https://…`), optional `require` calls inside `try`, and asset imports.
|
|
68
|
+
- `py/noop-test` is restricted to real test modules and test classes, and lowers confidence for likely helper functions.
|
|
69
|
+
- Config, manifests and baselines tolerate a UTF-8 BOM (common on Windows).
|
|
70
|
+
- `--diff` handles file names containing spaces or non-ASCII characters, and scans started from a subdirectory of the repository.
|
|
71
|
+
- `--diff` rejects refs that look like git options (for example `--output=file`) instead of passing them through.
|
|
72
|
+
- `--baseline` records how many findings share a fingerprint, so a newly added identical finding is still reported; older baselines without the count keep working.
|
|
73
|
+
- Passing more than one path exits 2 instead of silently scanning only the first one.
|
|
74
|
+
- A missing path or an unknown `--rule` id exits 2 with a message instead of silently reporting nothing.
|
|
75
|
+
- `slopgate init` writes a four-key config instead of a full dump of defaults.
|
|
76
|
+
- The published tarball no longer ships the demo GIF (the README uses an absolute raw URL after `scripts/set-repo.mjs`).
|
|
77
|
+
- The CLI accepts an injected output writer (`main(argv, io)`), so tests no longer replace `process.stdout`. Replacing it corrupted Node's test-runner protocol in CI, which made one test fail and hid 16 others.
|
|
78
|
+
- An explicitly requested `--baseline` file that does not exist now exits 2 instead of silently disabling the baseline.
|
|
79
|
+
- Scanning zero files prints a warning (empty `include` list, wrong path, or everything ignored).
|
|
80
|
+
- `slopgate mcp` refuses a root that is not a directory, and `scan_path` refuses symlinks that escape the repository.
|
|
81
|
+
- `slopgate init` creates the target directory when it does not exist.
|
|
82
|
+
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 slopgate contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,305 @@
|
|
|
1
|
-
#
|
|
1
|
+
# slopgate
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**The slop gate for AI-written code.**
|
|
4
|
+
|
|
5
|
+
AI writes code that *looks* right. `slopgate` finds the parts that only look right: imports of packages that do not exist, tests that cannot fail, functions that are stubs, errors that vanish without a trace.
|
|
6
|
+
|
|
7
|
+

|
|
8
|
+
|
|
9
|
+
[](https://www.npmjs.com/package/@voidh4x0r/slopgate)
|
|
10
|
+
[](https://github.com/VoidH4x0r/slopgate/actions/workflows/ci.yml)
|
|
11
|
+
[](https://github.com/VoidH4x0r/slopgate/blob/main/LICENSE)
|
|
12
|
+
[](https://github.com/VoidH4x0r/slopgate/blob/main/package.json)
|
|
13
|
+
|
|
14
|
+
```console
|
|
15
|
+
$ npx @voidh4x0r/slopgate .
|
|
16
|
+
|
|
17
|
+
slopgate 0.1.0 · 4 files · 39ms
|
|
18
|
+
|
|
19
|
+
app.py
|
|
20
|
+
4:1 error high py/phantom-import `helper` is imported but not declared in any manifest and not present in this repository
|
|
21
|
+
│ from helper import format_value
|
|
22
|
+
· manifests checked: pyproject.toml
|
|
23
|
+
↳ Add it to your manifest, remove the import, or wrap it in try/except ImportError if it is optional.
|
|
24
|
+
|
|
25
|
+
7:1 warning high py/stub-body function `get_user` is a stub (body is `pass`)
|
|
26
|
+
│ def get_user(user_id):
|
|
27
|
+
· body: pass
|
|
28
|
+
↳ Implement it, or raise NotImplementedError with a message so callers fail loudly instead of silently returning None.
|
|
29
|
+
|
|
30
|
+
14:5 warning high py/swallowed-exception `except` swallows the error silently
|
|
31
|
+
│ except Exception:
|
|
32
|
+
↳ Log it, re-raise it, or narrow the exception type and add a comment explaining why it is safe to ignore.
|
|
33
|
+
|
|
34
|
+
22:5 error high py/unreachable code after `return` is unreachable
|
|
35
|
+
│ print("dead code after return")
|
|
36
|
+
↳ Delete the unreachable code, or move it before the exit if it was meant to run.
|
|
37
|
+
|
|
38
|
+
tests/test_users.py
|
|
39
|
+
4:1 warning high py/noop-test test `test_get_user` makes no assertions
|
|
40
|
+
│ def test_get_user():
|
|
41
|
+
↳ Every test should be able to fail. Add an assertion that depends on the behaviour under test.
|
|
42
|
+
|
|
43
|
+
13 findings in 3 files · 4 files scanned in 39ms
|
|
44
|
+
4 error · 9 warning · 0 info (13 high · 0 medium · 0 low confidence)
|
|
45
|
+
hidden: 1 below confidence threshold
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
No API keys. No telemetry. No network calls at runtime. One command, works offline, exits non-zero in CI.
|
|
49
|
+
|
|
50
|
+
## What it catches
|
|
51
|
+
|
|
52
|
+
Models are good at producing code that compiles, imports cleanly in the editor where the package happened to be installed, and passes tests that assert nothing. These failures are boring, repetitive, and invisible to a green CI run:
|
|
53
|
+
|
|
54
|
+
| What the model wrote | What it costs you |
|
|
55
|
+
| --- | --- |
|
|
56
|
+
| `import requests_v2` — the package does not exist | `ModuleNotFoundError` in CI, or a malicious package if that name is ever registered |
|
|
57
|
+
| `def test_create(): service.create()` — no assertion | A green test with zero coverage |
|
|
58
|
+
| `def sync(self): pass` — real signature, empty body | Callers get `None` and the failure surfaces three layers downstream |
|
|
59
|
+
| `except Exception: pass` | The error disappears; the incident does not |
|
|
60
|
+
| `return user` followed by 12 lines of code | Dead code that nobody notices until it rots |
|
|
61
|
+
|
|
62
|
+
`slopgate` is a **precision-first** linter for exactly this class of defect, for Python and TypeScript/JavaScript.
|
|
63
|
+
|
|
64
|
+
It is built for the people who review AI-generated pull requests: the reviewer who cannot read every line, the maintainer who needs CI to say "this is not finished", and the coding agent that should check itself before declaring done.
|
|
65
|
+
|
|
66
|
+
## Does it actually catch anything?
|
|
67
|
+
|
|
68
|
+
Measured on **1,115,177 lines** of real code — the CPython standard library (an adversarial corpus full of test helpers and intentional no-ops) plus nine popular JavaScript packages:
|
|
69
|
+
|
|
70
|
+
| Metric | Result |
|
|
71
|
+
| --- | --- |
|
|
72
|
+
| High-confidence findings | **26** (0.03 per 1,000 lines), in 17 of 1,845 CPython files |
|
|
73
|
+
| Labeled precision of high-confidence findings | **96.2%** (25/26 manually reviewed) |
|
|
74
|
+
| Recall on 14 seeded defects | **14/14** |
|
|
75
|
+
| High-confidence findings on 601 JavaScript files (`eslint`, `express`, `execa`, `semver`, `chalk`, `commander`, `debug`, `yargs`, `glob`) | **0** |
|
|
76
|
+
|
|
77
|
+
The labels, the corpus definition and the harness are in [`benchmark/`](https://github.com/VoidH4x0r/slopgate/tree/main/benchmark) and [`docs/benchmark.md`](https://github.com/VoidH4x0r/slopgate/blob/main/docs/benchmark.md); `node scripts/benchmark.mjs` reproduces the numbers. We publish the false positives instead of hiding them.
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## Why another linter
|
|
82
|
+
|
|
83
|
+
`ruff`, `eslint` and friends check *style and syntax*. They cannot tell you that a package is hallucinated, because that requires reading your manifests. They cannot tell you that a test is theatre, because that requires understanding what an assertion is.
|
|
84
|
+
|
|
85
|
+
`slopgate` complements them. It only ships rules that need **AST + project context** (manifests, imports, test structure), and it optimises for the opposite of most linters: **almost no false positives**, even if that means fewer rules.
|
|
86
|
+
|
|
87
|
+
| | slopgate | style linters (ruff / eslint) | AI-slop regex scanners |
|
|
88
|
+
| --- | --- | --- | --- |
|
|
89
|
+
| Real AST (tree-sitter) | ✅ | ✅ | often regex |
|
|
90
|
+
| Knows your dependency manifests | ✅ | ❌ | partial |
|
|
91
|
+
| Confidence tiers, high by default | ✅ | ❌ | ❌ |
|
|
92
|
+
| `--baseline` so you can adopt it on a legacy repo | ✅ | ⚠️ per-file only | ❌ |
|
|
93
|
+
| `--diff` so CI only fails on new code | ✅ | ❌ | ❌ |
|
|
94
|
+
| MCP server so agents can self-check | ✅ | ❌ | ❌ |
|
|
95
|
+
| SARIF for GitHub code scanning | ✅ | ✅ | rare |
|
|
96
|
+
| Zero configuration to start | ✅ | ✅ | ⚠️ |
|
|
97
|
+
|
|
98
|
+
## Install
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
npx @voidh4x0r/slopgate . # try it without installing
|
|
102
|
+
npm install -D @voidh4x0r/slopgate # or pin it in your project
|
|
103
|
+
npx @voidh4x0r/slopgate init # write .slopgate.json + a GitHub Action
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Requires Node 20+. Python and TypeScript grammars are bundled — no Python or `tsc` needed at scan time.
|
|
107
|
+
|
|
108
|
+
The npm scope is `@voidh4x0r` because the unscoped name `slopgate` was rejected as too similar to the existing `slop-gate` package; the command is still `slopgate`.
|
|
109
|
+
|
|
110
|
+
## Usage
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
slopgate [path] [options]
|
|
114
|
+
|
|
115
|
+
--format pretty|json|sarif|github output format (default: pretty)
|
|
116
|
+
--confidence high|medium|low minimum confidence to report (default: high)
|
|
117
|
+
--fail-on high|medium|low|none minimum confidence that fails CI (default: high)
|
|
118
|
+
(a lower value also lowers what is displayed)
|
|
119
|
+
--baseline [path] ignore findings recorded in a file (default: .slopgate-baseline.json)
|
|
120
|
+
--write-baseline [path] record current findings, then exit 0
|
|
121
|
+
--diff [ref] only report findings on changed lines (default: HEAD)
|
|
122
|
+
--include/--exclude <glob> adjust the file set
|
|
123
|
+
--rule <id> run a single rule
|
|
124
|
+
--no-color --quiet --verbose
|
|
125
|
+
--force overwrite files written by `init`
|
|
126
|
+
-h, --help / -V, --version
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### Configuration
|
|
130
|
+
|
|
131
|
+
`slopgate` reads `.slopgate.json` (or `slopgate.config.json`) from the project root. Every key is optional:
|
|
132
|
+
|
|
133
|
+
```json
|
|
134
|
+
{
|
|
135
|
+
"include": ["src/**", "tests/**"],
|
|
136
|
+
"exclude": ["vendor/**", "migrations/**"],
|
|
137
|
+
"ignoreModules": ["my_private_pkg"],
|
|
138
|
+
"rules": {
|
|
139
|
+
"ts/swallowed-exception": "off",
|
|
140
|
+
"py/stub-body": "warning"
|
|
141
|
+
},
|
|
142
|
+
"confidence": "high",
|
|
143
|
+
"failOn": "high"
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
- `include` / `exclude` — globs relative to the project root; the defaults cover Python and TS/JS sources.
|
|
148
|
+
- `ignoreModules` — top-level modules to always treat as declared (dynamic imports, private packages).
|
|
149
|
+
- `rules` — `"off"` or an explicit severity (`"error"`, `"warning"`, `"info"`).
|
|
150
|
+
- `confidence` / `failOn` — same meaning as the CLI flags; CLI flags win.
|
|
151
|
+
|
|
152
|
+
`slopgate init` writes a minimal config plus a GitHub Actions workflow.
|
|
153
|
+
|
|
154
|
+
### Adopting it on an existing repository
|
|
155
|
+
|
|
156
|
+
This is the part most linters get wrong. A 200k-line repo has 900 findings on day one, so nobody turns it on.
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
# 1. Record what is already there. Nothing fails, nothing is "fixed" blindly.
|
|
160
|
+
npx @voidh4x0r/slopgate . --write-baseline
|
|
161
|
+
|
|
162
|
+
# 2. Commit the baseline. From now on only NEW findings fail CI.
|
|
163
|
+
npx @voidh4x0r/slopgate . --fail-on high
|
|
164
|
+
|
|
165
|
+
# 3. Or gate only the lines a pull request touches:
|
|
166
|
+
npx @voidh4x0r/slopgate . --diff origin/main --fail-on high
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
### Use it from a coding agent (MCP)
|
|
170
|
+
|
|
171
|
+
`slopgate` ships a Model Context Protocol server over stdio, so Claude Code, Codex and other MCP clients can check their own diff **before** saying "done".
|
|
172
|
+
|
|
173
|
+
```json
|
|
174
|
+
{
|
|
175
|
+
"mcpServers": {
|
|
176
|
+
"slopgate": { "command": "npx", "args": ["-y", "@voidh4x0r/slopgate", "mcp"] }
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
| Tool | What the agent gets |
|
|
182
|
+
| --- | --- |
|
|
183
|
+
| `scan_diff` | findings on lines changed since a git ref (default `HEAD`) |
|
|
184
|
+
| `scan_path` | findings in a file or directory |
|
|
185
|
+
| `list_rules` | the rule table, so the agent knows what is checked |
|
|
186
|
+
|
|
187
|
+
Reports are compact text: `file:line:col severity confidence rule-id message`, evidence included, capped at 50 findings per call. The server reads `.slopgate.json` and `.slopgate-baseline.json` like the CLI does, so an agent never re-reports debt you already accepted. It runs locally, makes no network calls, and writes nothing to disk.
|
|
188
|
+
|
|
189
|
+
Full details: [docs/mcp.md](https://github.com/VoidH4x0r/slopgate/blob/main/docs/mcp.md).
|
|
190
|
+
|
|
191
|
+
## In CI
|
|
192
|
+
|
|
193
|
+
`.github/workflows/slopgate.yml` (written by `slopgate init`):
|
|
194
|
+
|
|
195
|
+
```yaml
|
|
196
|
+
name: slopgate
|
|
197
|
+
on: [push, pull_request]
|
|
198
|
+
permissions:
|
|
199
|
+
contents: read
|
|
200
|
+
jobs:
|
|
201
|
+
slopgate:
|
|
202
|
+
runs-on: ubuntu-latest
|
|
203
|
+
steps:
|
|
204
|
+
- uses: actions/checkout@v4
|
|
205
|
+
- uses: actions/setup-node@v4
|
|
206
|
+
with: { node-version: 22 }
|
|
207
|
+
- run: npx --yes @voidh4x0r/slopgate@latest . --fail-on high
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
For GitHub code scanning, use `--format sarif` and upload with `github/codeql-action/upload-sarif`.
|
|
211
|
+
|
|
212
|
+
For inline pull-request annotations **without** code scanning, use `--format github`, which emits [workflow commands](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions):
|
|
213
|
+
|
|
214
|
+
```yaml
|
|
215
|
+
- run: npx --yes @voidh4x0r/slopgate@latest . --format github --fail-on high
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Each finding becomes an `error` / `warning` / `notice` annotation on the exact line, followed by a summary notice.
|
|
219
|
+
|
|
220
|
+
Exit codes: `0` no findings at or above `--fail-on`, `1` findings at or above the threshold, `2` usage or configuration error (missing path, unknown rule id, invalid config, git failure, or zero files matched).
|
|
221
|
+
|
|
222
|
+
### Suppressing a finding
|
|
223
|
+
|
|
224
|
+
```python
|
|
225
|
+
# slopgate-ignore-next-line py/stub-body
|
|
226
|
+
def todo(self):
|
|
227
|
+
pass
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
```ts
|
|
231
|
+
// slopgate-ignore-line ts/swallowed-exception
|
|
232
|
+
try { ... } catch {}
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
`slopgate-disable-file` at the top of a file disables it entirely. Directives only count inside real comments — a mention in a string or a doc is not a suppression.
|
|
236
|
+
|
|
237
|
+
## Rules
|
|
238
|
+
|
|
239
|
+
14 rules across Python and TypeScript/JavaScript. Full reference with examples: [docs/rules.md](https://github.com/VoidH4x0r/slopgate/blob/main/docs/rules.md).
|
|
240
|
+
|
|
241
|
+
| Rule | Catches |
|
|
242
|
+
| --- | --- |
|
|
243
|
+
| `py/phantom-import` · `ts/phantom-import` | import that no manifest declares and, for TS, that is not even installed |
|
|
244
|
+
| `py/noop-test` · `ts/noop-test` | `test_*` / `test()` / `it()` bodies with no assertion |
|
|
245
|
+
| `py/tautological-assert` · `ts/tautological-assert` | `assert True`, `expect(true).toBe(true)`, `x == x` |
|
|
246
|
+
| `py/stub-body` · `ts/stub-function` | function declarations and class methods whose body is only `pass`, `...`, `{}`, or `throw new Error("not implemented")` (empty arrow callbacks are not reported unless they throw) |
|
|
247
|
+
| `py/swallowed-exception` · `ts/swallowed-exception` | `except: pass`, `catch {}` (JS empty catch is medium by design) |
|
|
248
|
+
| `py/dead-branch` · `ts/dead-branch` | `if False:` / `if (false)`, and their always-true twins |
|
|
249
|
+
| `py/unreachable` · `ts/unreachable` | statements after `return` / `raise` / `throw` / `continue` |
|
|
250
|
+
|
|
251
|
+
## Precision is the product
|
|
252
|
+
|
|
253
|
+
Every finding carries a **confidence** derived from evidence, not vibes:
|
|
254
|
+
|
|
255
|
+
- **high** — a fact you can verify by reading the line: the package is not in the manifest, the test has no assertion, the body is empty. This is what runs by default and what fails CI.
|
|
256
|
+
- **medium** — a fact plus a reason it might be intentional: an empty `catch` (idiomatic in JavaScript), an exception swallowed inside a cleanup function, a test method that may delegate its assertions to a helper, any finding in a file that did not parse cleanly.
|
|
257
|
+
- **low** — reserved for heuristics we are not confident about yet.
|
|
258
|
+
|
|
259
|
+
`--confidence medium` shows the middle tier; `--confidence low` shows everything the rules can see. `--verbose` prints the evidence behind each confidence level.
|
|
260
|
+
|
|
261
|
+
We would rather miss a finding than teach you to ignore the tool. That is also why rules skip test files where the scaffolding is intentional, and why a file with syntax errors can never produce a high-confidence finding.
|
|
262
|
+
|
|
263
|
+
## Performance
|
|
264
|
+
|
|
265
|
+
`slopgate` parses with tree-sitter compiled to WebAssembly and reuses one parser per language. Scanning never spawns a subprocess. `--diff` and the MCP `scan_diff` tool invoke `git`, so those two paths need git on `PATH` and a sandbox that permits child processes:
|
|
266
|
+
|
|
267
|
+
- 20 files / ~3k lines: **~125 ms** end to end (Windows laptop, cold start)
|
|
268
|
+
- 1,845 files / 991,705 lines (CPython standard library): **~12 s** in the benchmark run
|
|
269
|
+
- 3 grammar files load once in **~35 ms**
|
|
270
|
+
- Python: ~12 ms per 35 KB file
|
|
271
|
+
|
|
272
|
+
## Roadmap
|
|
273
|
+
|
|
274
|
+
- [x] v0.1 — 14 rules, Python + TS/JS, baseline, diff mode, SARIF, GitHub annotations, MCP server, suppression
|
|
275
|
+
- [ ] v0.2 — duplicate-block detection, Go and Rust grammars, `--fix` for the safe subset
|
|
276
|
+
- [ ] v0.3 — published false-positive benchmark across popular repositories, VS Code diagnostics
|
|
277
|
+
|
|
278
|
+
## Known limitations
|
|
279
|
+
|
|
280
|
+
- `.gitignore` is not read. Generated trees are skipped only through the built-in ignore list and your own `exclude` patterns.
|
|
281
|
+
- Symbolic links are skipped, and files larger than 1 MB are ignored. `--format json` reports the count in `stats.skipped`.
|
|
282
|
+
- A path whose name matches a subcommand (`rules/`, `init/`, `scan/`) is parsed as the subcommand; write `./rules` to scan that directory.
|
|
283
|
+
|
|
284
|
+
## When **not** to use it
|
|
285
|
+
|
|
286
|
+
- You want style, formatting or type checking — use `ruff` / `eslint` / `tsc`.
|
|
287
|
+
- You need whole-program data-flow analysis — that is `semgrep` / CodeQL territory.
|
|
288
|
+
- Your code is not generated or reviewed quickly; the rules still apply, but the value is lower.
|
|
289
|
+
|
|
290
|
+
## Contributing
|
|
291
|
+
|
|
292
|
+
Issues and pull requests are welcome. Start with [CONTRIBUTING.md](https://github.com/VoidH4x0r/slopgate/blob/main/CONTRIBUTING.md); adding a rule is a ~80 line change plus tests.
|
|
293
|
+
|
|
294
|
+
```bash
|
|
295
|
+
git clone https://github.com/VoidH4x0r/slopgate
|
|
296
|
+
cd slopgate
|
|
297
|
+
npm install
|
|
298
|
+
npm test # 166 tests; the tests themselves make no network or child-process calls
|
|
299
|
+
npm run typecheck
|
|
300
|
+
npm run verify # all release gates in one command
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
## License
|
|
304
|
+
|
|
305
|
+
MIT
|
package/dist/ast.d.ts
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import type { Node as TreeSitterNode } from 'web-tree-sitter';
|
|
2
|
+
/**
|
|
3
|
+
* The WASM bindings type `namedChildren` as `(Node | null)[]` and several
|
|
4
|
+
* accessors as nullable, because the C API can return null in edge cases.
|
|
5
|
+
* In practice a parsed tree never contains null children, so we assert the
|
|
6
|
+
* shape once at the parsing boundary instead of checking for null in every
|
|
7
|
+
* rule. If a future tree-sitter release changes this, the cast fails loudly
|
|
8
|
+
* here rather than silently in ten different rules.
|
|
9
|
+
*/
|
|
10
|
+
export interface AstNode {
|
|
11
|
+
readonly type: string;
|
|
12
|
+
readonly text: string;
|
|
13
|
+
readonly startPosition: {
|
|
14
|
+
readonly row: number;
|
|
15
|
+
readonly column: number;
|
|
16
|
+
};
|
|
17
|
+
readonly endPosition: {
|
|
18
|
+
readonly row: number;
|
|
19
|
+
readonly column: number;
|
|
20
|
+
};
|
|
21
|
+
readonly startIndex: number;
|
|
22
|
+
readonly endIndex: number;
|
|
23
|
+
readonly namedChildren: AstNode[];
|
|
24
|
+
readonly children: AstNode[];
|
|
25
|
+
readonly parent: AstNode | null;
|
|
26
|
+
readonly isNamed: boolean;
|
|
27
|
+
childForFieldName(name: string): AstNode | null;
|
|
28
|
+
}
|
|
29
|
+
export declare function asAst(node: TreeSitterNode): AstNode;
|
package/dist/ast.js
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import type { Finding } from './types.ts';
|
|
2
|
+
export interface BaselineEntry {
|
|
3
|
+
fingerprint: string;
|
|
4
|
+
ruleId: string;
|
|
5
|
+
file: string;
|
|
6
|
+
/**
|
|
7
|
+
* How many findings shared this fingerprint when the baseline was written.
|
|
8
|
+
* Optional for backwards compatibility: older baselines implied 1.
|
|
9
|
+
*/
|
|
10
|
+
count?: number;
|
|
11
|
+
}
|
|
12
|
+
export interface BaselineFile {
|
|
13
|
+
version: 1;
|
|
14
|
+
createdAt: string;
|
|
15
|
+
entries: BaselineEntry[];
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Stable across line moves: it is built from the rule, the file and the
|
|
19
|
+
* offending source text, not from the line number.
|
|
20
|
+
*/
|
|
21
|
+
export declare function findingFingerprint(finding: Finding): string;
|
|
22
|
+
export declare function loadBaseline(file: string): Promise<BaselineFile | undefined>;
|
|
23
|
+
export declare function writeBaseline(file: string, findings: readonly Finding[]): Promise<BaselineFile>;
|
|
24
|
+
export interface BaselinePartition {
|
|
25
|
+
fresh: Finding[];
|
|
26
|
+
known: Finding[];
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Matches findings against the baseline by fingerprint **and remaining count**.
|
|
30
|
+
* Without the count, adding a second identical `except: pass` to a file would
|
|
31
|
+
* be silently absorbed by the baseline entry for the first one.
|
|
32
|
+
*/
|
|
33
|
+
export declare function partitionByBaseline(findings: readonly Finding[], baseline: BaselineFile | undefined): BaselinePartition;
|
package/dist/baseline.js
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
2
|
+
import { readFile, writeFile } from 'node:fs/promises';
|
|
3
|
+
function normalizeSnippet(snippet) {
|
|
4
|
+
return snippet.replace(/\s+/g, ' ').trim();
|
|
5
|
+
}
|
|
6
|
+
/**
|
|
7
|
+
* Stable across line moves: it is built from the rule, the file and the
|
|
8
|
+
* offending source text, not from the line number.
|
|
9
|
+
*/
|
|
10
|
+
export function findingFingerprint(finding) {
|
|
11
|
+
const material = `${finding.ruleId}\n${finding.file}\n${normalizeSnippet(finding.snippet)}`;
|
|
12
|
+
return createHash('sha1').update(material).digest('hex').slice(0, 16);
|
|
13
|
+
}
|
|
14
|
+
export async function loadBaseline(file) {
|
|
15
|
+
let text;
|
|
16
|
+
try {
|
|
17
|
+
text = (await readFile(file, 'utf8')).replace(/^\uFEFF/, '');
|
|
18
|
+
}
|
|
19
|
+
catch (error) {
|
|
20
|
+
if (error.code === 'ENOENT')
|
|
21
|
+
return undefined;
|
|
22
|
+
throw error;
|
|
23
|
+
}
|
|
24
|
+
try {
|
|
25
|
+
const parsed = JSON.parse(text);
|
|
26
|
+
if (parsed.version !== 1 || !Array.isArray(parsed.entries)) {
|
|
27
|
+
throw new Error('unexpected shape');
|
|
28
|
+
}
|
|
29
|
+
return {
|
|
30
|
+
version: 1,
|
|
31
|
+
createdAt: typeof parsed.createdAt === 'string' ? parsed.createdAt : new Date(0).toISOString(),
|
|
32
|
+
entries: parsed.entries
|
|
33
|
+
.filter((entry) => typeof entry?.fingerprint === 'string' &&
|
|
34
|
+
typeof entry?.ruleId === 'string' &&
|
|
35
|
+
typeof entry?.file === 'string')
|
|
36
|
+
.map((entry) => ({
|
|
37
|
+
fingerprint: entry.fingerprint,
|
|
38
|
+
ruleId: entry.ruleId,
|
|
39
|
+
file: entry.file,
|
|
40
|
+
...(typeof entry.count === 'number' && entry.count > 0 ? { count: entry.count } : {}),
|
|
41
|
+
})),
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
catch (error) {
|
|
45
|
+
throw new Error(`${file} is not a valid baseline (${error.message})`);
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
export async function writeBaseline(file, findings) {
|
|
49
|
+
const groups = new Map();
|
|
50
|
+
for (const finding of findings) {
|
|
51
|
+
const fingerprint = findingFingerprint(finding);
|
|
52
|
+
const existing = groups.get(fingerprint);
|
|
53
|
+
if (existing) {
|
|
54
|
+
existing.count = (existing.count ?? 1) + 1;
|
|
55
|
+
continue;
|
|
56
|
+
}
|
|
57
|
+
groups.set(fingerprint, {
|
|
58
|
+
fingerprint,
|
|
59
|
+
ruleId: finding.ruleId,
|
|
60
|
+
file: finding.file,
|
|
61
|
+
count: 1,
|
|
62
|
+
});
|
|
63
|
+
}
|
|
64
|
+
const baseline = {
|
|
65
|
+
version: 1,
|
|
66
|
+
createdAt: new Date().toISOString(),
|
|
67
|
+
entries: [...groups.values()],
|
|
68
|
+
};
|
|
69
|
+
await writeFile(file, JSON.stringify(baseline, null, 2) + '\n', 'utf8');
|
|
70
|
+
return baseline;
|
|
71
|
+
}
|
|
72
|
+
function ordered(findings) {
|
|
73
|
+
return [...findings].sort((a, b) => a.file.localeCompare(b.file) ||
|
|
74
|
+
a.start.line - b.start.line ||
|
|
75
|
+
a.start.column - b.start.column ||
|
|
76
|
+
a.ruleId.localeCompare(b.ruleId));
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Matches findings against the baseline by fingerprint **and remaining count**.
|
|
80
|
+
* Without the count, adding a second identical `except: pass` to a file would
|
|
81
|
+
* be silently absorbed by the baseline entry for the first one.
|
|
82
|
+
*/
|
|
83
|
+
export function partitionByBaseline(findings, baseline) {
|
|
84
|
+
if (!baseline)
|
|
85
|
+
return { fresh: [...findings], known: [] };
|
|
86
|
+
const remaining = new Map();
|
|
87
|
+
for (const entry of baseline.entries) {
|
|
88
|
+
remaining.set(entry.fingerprint, (remaining.get(entry.fingerprint) ?? 0) + (entry.count ?? 1));
|
|
89
|
+
}
|
|
90
|
+
const fresh = [];
|
|
91
|
+
const known = [];
|
|
92
|
+
for (const finding of ordered(findings)) {
|
|
93
|
+
const fingerprint = findingFingerprint(finding);
|
|
94
|
+
const left = remaining.get(fingerprint) ?? 0;
|
|
95
|
+
if (left > 0) {
|
|
96
|
+
known.push(finding);
|
|
97
|
+
remaining.set(fingerprint, left - 1);
|
|
98
|
+
}
|
|
99
|
+
else {
|
|
100
|
+
fresh.push(finding);
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
return { fresh, known };
|
|
104
|
+
}
|
package/dist/cli.d.ts
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
export interface CliIo {
|
|
3
|
+
out(text: string): void;
|
|
4
|
+
err(text: string): void;
|
|
5
|
+
isTTY: boolean;
|
|
6
|
+
}
|
|
7
|
+
/** Real process streams. Tests pass their own collector instead. */
|
|
8
|
+
export declare function defaultIo(): CliIo;
|
|
9
|
+
export declare function main(argv: readonly string[], io?: CliIo): Promise<number>;
|