unslop-ci 0.1.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 cj-vana
+
+The detection rules in this project are a TypeScript port of the scanners from
+"vibecoded-design-tells" by J. Carter Johnson
+(https://github.com/JCarterJohnson/vibecoded-design-tells), MIT licensed, which
+grounds every rule in a large-scale Reddit analysis of what people actually
+name as a giveaway of AI-generated code, prose, and design.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,232 @@
+# unslop-ci
+
+[![CI](https://github.com/cj-vana/unslop-ci/actions/workflows/ci.yml/badge.svg)](https://github.com/cj-vana/unslop-ci/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/unslop-ci.svg)](https://www.npmjs.com/package/unslop-ci)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+**A diff-aware CI gate for AI slop.** It scans only the lines a change adds
+for the tells that make code, prose, and UI read as AI-generated, and fails
+the build when a strong tell lands. Lines that already existed never block,
+so you can adopt it on a codebase of any age without a cleanup project first.
+
+```bash
+npx unslop-ci diff --base origin/main
+```
+
+Three scanners run over the added lines, each routed by file type:
+
+- **code** (`.ts`, `.py`, `.go`, `.sql`, 26 more) catches leftover chat
+  artifacts ("Here's the updated code"), placeholder stubs (`// rest of your
+code`), swallowed errors (`catch (e) {}`), emoji in source, narrating
+  comments, and generic names like `process_data`.
+- **text** (`.md`, `.mdx`, `.txt`, `.rst`, `.html`) catches the em dash, the
+  "not just X, it's Y" cadence, assistant boilerplate and sign-offs,
+  sycophantic openers, the `delve`/`leverage` diction cluster, listicle
+  scaffolding, and the "In conclusion" closer.
+- **ui** (`.tsx`, `.css`, `.vue`, `.svelte`, more) catches untouched shadcn
+  defaults, the AI purple/indigo band, gradient heading text, the cream+serif
+  "tasteful default", emoji-as-icons, and unprompted neon glow.
+
+The rules are a TypeScript port of the scanners from
+[vibecoded-design-tells](https://github.com/JCarterJohnson/vibecoded-design-tells)
+(MIT), which grounds every rule in a large-scale Reddit analysis of what
+people actually name as a giveaway. Severity follows those measured shares,
+not vibes. The port is behavior-identical: on a 606-file corpus all three
+scanners produce the same per-rule counts as the originals.
+
+## Why diff-aware
+
+Run any slop scanner over a mature repo and you get thousands of findings
+nobody will ever fix; gate CI on that and every PR is red on day one. The
+useful contract is narrower: **the lines you are adding right now should not
+carry fresh slop.** unslop-ci parses `git diff -U0` against the merge base,
+scans only files the change touches, and keeps only findings whose line the
+diff added. Everything else in the file is invisible to the gate.
+
+## GitHub Actions
+
+```yaml
+jobs:
+  unslop:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0 # the diff needs history back to the merge base
+      - uses: cj-vana/unslop-ci@v1
+```
+
+On `pull_request` events the base resolves automatically from the event
+payload; the same is true for `merge_group` and `push`. Blocking findings
+show up as `::error` annotations on the exact changed lines, warnings as
+`::warning`, and a summary table lands in the step summary.
+
+Action inputs (all optional): `base`, `head`, `config`, `fail-on`,
+`scanners`, `working-directory`, `annotations`, `summary`, `report-file`.
+Outputs: `blocking-count`, `finding-count`, `added-lines`.
+
+Pin the action to a commit sha on self-hosted runners, same as you would any
+third-party action.
+
+## CLI
+
+```bash
+npm install --save-dev unslop-ci
+
+npx unslop-ci diff --base origin/main     # gate your branch's added lines
+npx unslop-ci diff                        # in CI, base resolves from the event
+npx unslop-ci diff --base HEAD            # gate your uncommitted changes
+npx unslop-ci scan src/                   # audit a whole tree (everything, not just new lines)
+npx unslop-ci diff --base origin/main --json > report.json
+```
+
+Flags: `--base <ref>`, `--head <ref>`, `--no-merge-base`, `--config <path>`,
+`--fail-on <level>`, `--scanners code,text,ui`, `--max <n>`, `--json`,
+`--no-annotations`, `--no-summary`, `--no-color`, `--cwd <dir>`.
+
+Exit codes: `0` clean, `1` blocking findings, `2` usage or environment error.
+
+## What blocks
+
+Every rule carries two independent axes. **Severity** (high, medium, low) is
+how loudly the finding reads as AI-generated. **Class** (`bug` or `cosmetic`)
+is whether the code is actually wrong: a swallowed error eats the one clue
+you needed, and a placeholder stub means the file shipped unfinished.
+
+The default gate is `high+bugs`: high-severity findings block, and bug-class
+findings block at any severity. Everything else surfaces as a warning. Set
+`fail-on` to `high`, `medium`, or `any` to move the line.
+
+An intentional line keeps the gate honest instead of fighting it:
+
+```ts
+console.log('🚀 launch banner'); // unslop-ignore
+```
+
+`unslop-ignore` skips that line; `unslop-ignore-next-line` on the line above
+skips the next one (for lines that cannot carry a comment).
+
+## Configuration
+
+`unslop.config.json` at the repo root is picked up automatically:
+
+```json
+{
+  "failOn": "high+bugs",
+  "exclude": ["**/generated/**", "**/*.snap"],
+  "disableRules": ["verbose-naming"],
+  "rules": {
+    "chat-artifact": "medium",
+    "em-dash": "off"
+  },
+  "scanners": {
+    "code": {
+      "exclude": ["supabase/migrations/**"],
+      "disableRules": ["narrating-comment"]
+    },
+    "text": { "include": ["docs/**", "*.md"] },
+    "ui": false
+  }
+}
+```
+
+- `failOn` sets the gate level (`high+bugs`, `high`, `medium`, `any`).
+- `exclude` removes paths globally; per-scanner `include`/`exclude` narrow a
+  single scanner. Globs support `*`, `**`, `?`, and `{a,b}`.
+- `disableRules` (global or per-scanner) removes rules; `rules` overrides a
+  rule's severity or turns it `off` everywhere.
+- Setting a scanner to `false` disables it entirely.
+
+## Rule catalog
+
+### code
+
+| rule                                                                                | severity | class    |
+| ----------------------------------------------------------------------------------- | -------- | -------- |
+| `chat-artifact` leftover assistant text or markdown fences in source                | high     | cosmetic |
+| `placeholder-comment` ellipsis stubs like `// rest of your code`                    | high     | bug      |
+| `emoji-in-code` emoji in code, strings, or logs                                     | medium   | cosmetic |
+| `swallowed-errors` bare `except:`, empty `catch`, empty `if err != nil`             | medium   | bug      |
+| `narrating-comment` comments that restate the next line                             | medium   | cosmetic |
+| `generic-naming` `process_data`, `handleData`, `doStuff`                            | medium   | cosmetic |
+| `verbose-naming` sentence-length identifiers                                        | low      | cosmetic |
+| `boilerplate-marker` `lorem ipsum`, `YOUR_API_KEY`, `John Doe`, "Successfully" logs | low      | cosmetic |
+
+### text
+
+| rule                                                                      | severity |
+| ------------------------------------------------------------------------- | -------- |
+| `em-dash` the single most-cited AI tell                                   | high     |
+| `not-just-x-y` the negate-then-assert cadence                             | high     |
+| `assistant-boilerplate` "as an AI language model", cutoff lines, refusals | high     |
+| `sycophancy-opener` "Great question!", "I'd be happy to"                  | high     |
+| `bolded-lead-in` `**Label:**` then a sentence                             | high     |
+| `assistant-offer` "Would you like me to", "I hope this helps"             | high     |
+| `ai-diction` `delve`, `tapestry`, `leverage`, `seamless`                  | medium   |
+| `dive-in` "deep dive", "let's dive in"                                    | medium   |
+| `listicle-scaffold` "5 ways to", "7 signs"                                | medium   |
+| `fast-paced-opener` "In today's fast-paced world"                         | medium   |
+| `unlock-potential` "unlock the full potential"                            | medium   |
+| `emoji-decoration` emoji bullets and headings                             | medium   |
+| `in-conclusion` the signposted recap closer                               | medium   |
+| `transition-stack` "Moreover", "Furthermore", "Firstly"                   | low      |
+| `generic-diction` `utilize`, `comprehensive`, `robust`                    | low      |
+| `hype-marketing` "revolutionary", "say goodbye to"                        | low      |
+| `hedge-cliche` "it depends", "on one hand"                                | low      |
+| `note-hedge` "it's worth noting"                                          | low      |
+| `hr-divider` rule lines between every section                             | low      |
+| `honestly-opener` "Honestly,", "let's be real"                            | low      |
+
+The text scanner lints your own prose: quoted material, inline code, fenced
+blocks, and YAML frontmatter are skipped, so quoting a cliche to discuss it
+is fine. The em dash is the one exception; it is flagged everywhere.
+
+### ui
+
+| rule                                                     | severity |
+| -------------------------------------------------------- | -------- |
+| `shadcn-default-card` untouched shadcn card/theme tokens | high     |
+| `ai-purple` indigo/violet/purple as primary              | high     |
+| `gradient-text` gradient-filled headings                 | high     |
+| `purple-blue-gradient` the rainbow hero gradient         | high     |
+| `claude-default-look` cream background + display serif   | high     |
+| `hero-three-cards` the centered hero + 3-card grid       | medium   |
+| `rounded-everything` pill radius on everything           | medium   |
+| `fade-in-animations` boilerplate scroll/hover motion     | medium   |
+| `neon-glow` unprompted glow shadows                      | medium   |
+| `emoji-as-icons` emoji standing in for an icon set       | medium   |
+| `generic-font` Inter/Geist/Roboto as the only choice     | medium   |
+| `hype-copy` template marketing copy                      | low      |
+| `stock-illustration` undraw-style blob art               | low      |
+
+## What it deliberately cannot see
+
+The loudest tells in the underlying study are structural: tutorial-shaped
+boilerplate, hallucinated APIs, over-engineering, and code that ignores the
+surrounding repo. No regex sees those. Build, type-check, and run the code
+for the hallucinated calls; read the diff for the rest. This gate removes
+the mechanical tells so review time goes where a human is actually needed.
+
+## Related
+
+- [buttonmash](https://github.com/cj-vana/buttonmash) is this project's
+  sibling: a CI chaos monkey that crawls your running app, mashes every
+  control, and fails the build on crashes. buttonmash tests what the app
+  does; unslop-ci gates what the diff says.
+- [vibecoded-design-tells](https://github.com/JCarterJohnson/vibecoded-design-tells)
+  is the upstream research and the original Python scanners, including the
+  Claude skills for interactive unslopping.
+
+## Development
+
+```bash
+npm install
+npm test            # vitest, includes an end-to-end suite against a temp git repo
+npm run lint
+npm run typecheck
+npm run build       # tsup; dist/ is committed because the action runs from it
+```
+
+MIT. Rule research and original scanners by
+[J. Carter Johnson](https://github.com/JCarterJohnson); port and CI gate by
+[cj-vana](https://github.com/cj-vana).