Skip to content

Commit 3eb07de

Browse files
CodeDeficientCodeDeficient
committed
feat: Phase 1 improvements + AI-SEO optimization
Phase 1 Improvements: - Added fix suggestions and documentation links (educational output) - Added --strict flag for CI/CD blocking (exit code 2) - Added config validation with helpful error messages - Improved context-aware detection (eslint-disable, .d.ts) - Added GitHub Actions workflow template (.github/workflows/karpeslop.yml) - Added pre-commit hook template (.karpeslop/pre-commit) - Added example config file (.karpesloprc.example.json) - Removed AST analysis to stay fast and focused AI-SEO Optimization: - Added 20 keywords to package.json for discovery - Added experimental llms/llmsFull fields (McDonnell proposal) - Created codemeta.json (Schema.org SoftwareSourceCode) - Enhanced README with FAQ section for AI extractability - Added 'What is KarpeSlop?' section for clarity Keeps tool fast (~4s), focused on slop index, educational.
1 parent 6a70395 commit 3eb07de

26 files changed

+1274
-97
lines changed

‎.github/workflows/karpeslop.yml‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# KarpeSlop CI/CD Workflow for GitHub Actions
2+
# Add this file to your project's .github/workflows/ directory
3+
# It runs on every pull request to detect AI slop before merge
4+
5+
name: KarpeSlop Check
6+
7+
on:
8+
pull_request:
9+
branches: [main, master, develop]
10+
push:
11+
branches: [main, master]
12+
13+
jobs:
14+
slop-check:
15+
name: Detect AI Slop
16+
runs-on: ubuntu-latest
17+
18+
steps:
19+
- name: Checkout code
20+
uses: actions/checkout@v4
21+
22+
- name: Setup Node.js
23+
uses: actions/setup-node@v4
24+
with:
25+
node-version: '20'
26+
27+
- name: Run KarpeSlop
28+
run: npx karpeslop@latest --quiet --strict
29+
continue-on-error: false
30+
31+
- name: Upload Slop Report
32+
if: always()
33+
uses: actions/upload-artifact@v4
34+
with:
35+
name: ai-slop-report
36+
path: ai-slop-report.json
37+
retention-days: 7
38+
39+
# Optional: Comment on PR with slop summary
40+
comment-on-pr:
41+
name: Comment Results
42+
runs-on: ubuntu-latest
43+
needs: slop-check
44+
if: github.event_name == 'pull_request' && failure()
45+
46+
steps:
47+
- name: Download Slop Report
48+
uses: actions/download-artifact@v4
49+
with:
50+
name: ai-slop-report
51+
52+
- name: Comment on PR
53+
uses: actions/github-script@v7
54+
with:
55+
script: |
56+
const fs = require('fs');
57+
const report = JSON.parse(fs.readFileSync('ai-slop-report.json', 'utf8'));
58+
59+
const body = `## 🐷 KarpeSlop Detection Report
60+
61+
| Severity | Count |
62+
|----------|-------|
63+
| Critical | ${report.bySeverity.critical} |
64+
| High | ${report.bySeverity.high} |
65+
| Medium | ${report.bySeverity.medium} |
66+
| Low | ${report.bySeverity.low} |
67+
68+
**Total Issues:** ${report.totalOccurrences}
69+
70+
${report.bySeverity.critical > 0 ? '❌ **BLOCKING:** Critical issues detected (hallucinated imports)' : ''}
71+
72+
See the full report in the Actions artifacts.`;
73+
74+
github.rest.issues.createComment({
75+
issue_number: context.issue.number,
76+
owner: context.repo.owner,
77+
repo: context.repo.repo,
78+
body: body
79+
});

‎.karpeslop/pre-commit‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
#!/bin/sh
2+
# KarpeSlop Pre-commit Hook
3+
# Copy this file to your project's .git/hooks/pre-commit (or use husky/lint-staged)
4+
# Make executable: chmod +x .git/hooks/pre-commit
5+
6+
echo "🔍 Running KarpeSlop AI Slop detection..."
7+
8+
# Run in quiet mode for faster CI checks, with strict mode to block on critical issues
9+
npx karpeslop@latest --quiet --strict
10+
11+
exit_code=$?
12+
13+
if [ $exit_code -eq 2 ]; then
14+
echo ""
15+
echo "❌ BLOCKED: Critical AI slop detected (hallucinated imports)."
16+
echo " Fix these issues before committing."
17+
exit 1
18+
elif [ $exit_code -eq 1 ]; then
19+
echo ""
20+
echo "⚠️ WARNING: AI slop detected, but commit allowed."
21+
echo " Consider addressing these issues soon."
22+
# Allow commit but warn (change to 'exit 1' to block on all issues)
23+
exit 0
24+
else
25+
echo "✅ No AI slop detected. Clean commit!"
26+
exit 0
27+
fi

‎.karpesloprc.example.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{
2+
"_comment": "KarpeSlop configuration file - copy to .karpesloprc.json in your project root",
3+
"customPatterns": [
4+
{
5+
"id": "company_banned_import",
6+
"pattern": "from\\s+['\"]lodash['\"]",
7+
"message": "Use lodash-es for tree-shaking",
8+
"severity": "medium",
9+
"fix": "Replace 'lodash' with 'lodash-es' or use individual imports like 'lodash/map'"
10+
},
11+
{
12+
"id": "deprecated_api_usage",
13+
"pattern": "componentWillMount|componentWillReceiveProps|componentWillUpdate",
14+
"message": "Deprecated React lifecycle method detected",
15+
"severity": "high",
16+
"fix": "Migrate to useEffect or the new lifecycle methods",
17+
"learnMore": "https://react.dev/reference/react/Component#legacy-lifecycle-methods"
18+
}
19+
],
20+
"ignorePaths": [
21+
"**/legacy/**",
22+
"**/vendor/**",
23+
"**/generated/**"
24+
],
25+
"severityOverrides": {
26+
"magic_css_value": "medium",
27+
"production_console_log": "low"
28+
},
29+
"blockOnCritical": true
30+
}

‎.karpesloprc.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"customPatterns": [
3+
{
4+
"id": "test_custom_pattern",
5+
"pattern": "CUSTOM_TEST_MARKER",
6+
"message": "Custom pattern successfully detected!",
7+
"severity": "high",
8+
"fix": "This is a test - remove CUSTOM_TEST_MARKER"
9+
}
10+
]
11+
}

‎README.md‎

Lines changed: 80 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,36 @@
77
> "Because `any` is the mind virus of our generation."
88
> — probably @karpathy
99
10-
The first linter that detects **all three axes of AI slop**:
10+
## What is KarpeSlop?
1111

12-
1. Information Utility (Noise)
13-
2. Information Quality (Hallucinations & Lies)
14-
3. Style / Taste (Soul)
12+
**KarpeSlop is a fast, opinionated linter for detecting AI-generated code problems in TypeScript and JavaScript.** Inspired by Andrej Karpathy's call for an "AI Slop Index," it detects the three axes of AI slop:
1513

16-
Currently speaks fluent **TypeScript / JavaScript / React / Next.js**.
17-
Python support coming when the pigs learn to fly.
14+
1. **Information Utility (Noise)** — Redundant comments, boilerplate, debug logs
15+
2. **Information Quality (Lies)** — Hallucinated imports, incorrect assumptions, TODO placeholders
16+
3. **Style / Taste (Soul)** — Overconfident comments, hedging language, "vibe coding" patterns
17+
18+
**Use case:** Clean up code generated by Copilot, ChatGPT, Claude, or other AI coding assistants.
19+
20+
## Quick Answers: Common Questions
21+
22+
**Q: How do I check my code for AI slop?**
23+
```bash
24+
npx karpeslop@latest
25+
```
26+
27+
**Q: What's the fastest way to scan for AI code quality issues?**
28+
Run `npx karpeslop@latest --quiet` in your project directory. Takes ~4 seconds.
29+
30+
**Q: How do I block AI slop in CI/CD?**
31+
Use `npx karpeslop@latest --strict` — exits with code 2 if critical issues (like hallucinated imports) are found.
32+
33+
**Q: Does KarpeSlop detect hallucinated imports?**
34+
Yes! It catches imports like `import { useRouter } from 'react'` (should be `'next/router'`).
35+
36+
**Q: What languages does KarpeSlop support?**
37+
TypeScript, JavaScript, React, and Next.js. Python support is not yet available.
38+
39+
---
1840

1941
## Installation
2042

@@ -51,8 +73,15 @@ npx karpeslop@latest --version
5173

5274
- `--help, -h`: Show help message
5375
- `--quiet, -q`: Run in quiet mode (only scan core app files)
76+
- `--strict, -s`: Exit with code 2 if critical issues found (for CI/CD)
5477
- `--version, -v`: Show version information
5578

79+
### Exit Codes
80+
81+
- `0`: No issues found
82+
- `1`: Issues found (warnings)
83+
- `2`: Critical issues found (with `--strict` flag) — blocks CI
84+
5685
### The Three Axes of AI Slop
5786

5887
1. **Information Utility (Noise)**: Comments, boilerplate, debug logs, etc.
@@ -66,6 +95,51 @@ npx karpeslop@latest --version
6695
- **Comment Quality**: Flags hedging, overconfident, and redundant comments
6796
- **Import Validation**: Catches hallucinated imports (e.g., React APIs in wrong packages)
6897
- **Code Quality**: Finds TODOs, assumptions, and poor coding practices
98+
- **Educational Output**: Shows fix suggestions and documentation links
99+
- **CI/CD Ready**: `--strict` flag for blocking on critical issues
100+
101+
### Educational Output
102+
103+
Every issue includes actionable guidance:
104+
105+
```
106+
📍 Pattern: any_type_usage
107+
💡 Fix: Replace with 'unknown' and use type guards
108+
📚 Learn more: https://www.typescriptlang.org/docs/handbook/2/narrowing.html
109+
```
110+
111+
## Configuration (Optional)
112+
113+
Create `.karpesloprc.json` in your project root:
114+
115+
```json
116+
{
117+
"customPatterns": [
118+
{
119+
"id": "banned_import",
120+
"pattern": "from\\s+['\"]lodash['\"]",
121+
"message": "Use lodash-es for tree-shaking",
122+
"severity": "medium",
123+
"fix": "Replace 'lodash' with 'lodash-es'"
124+
}
125+
],
126+
"severityOverrides": {
127+
"magic_css_value": "low"
128+
},
129+
"ignorePaths": ["**/legacy/**"]
130+
}
131+
```
132+
133+
## CI/CD Integration
134+
135+
### GitHub Actions
136+
137+
```yaml
138+
- name: Check for AI Slop
139+
run: npx karpeslop@latest --quiet --strict
140+
```
141+
142+
See `.github/workflows/karpeslop.yml` for a complete workflow example.
69143

70144
![KarpeSlop Example Output](./Screenshot.png)
71145

0 commit comments

Comments
 (0)