slop-police 0.3.7 → 0.3.9

package/README.md

@@ -3,79 +3,70 @@
 <p align="center"><b>Stop LLM crimes in your codebase</b></p>
 
 <p align="center">
-A type-aware TypeScript linter for the dead code and needless indirection AI agents leave behind.
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/readme-dark.webp">
+    <img src="assets/readme-light.webp" alt="slop-police flags an export only used in its own file, a function that just forwards, a variable that is just a rename, and a method that is never called">
+  </picture>
 </p>
 
 ```sh
-pnpm add slop-police
+pnpm add -D slop-police
 # or
-npm i slop-police
+npm i -D slop-police
 ```
 
-Run it with `pnpm exec slop-police` or `npx slop-police`.
+Add a [`slop-police.json`](#configuration) and run `npx slop-police` (or `pnpm exec slop-police`).
 
-Example output:
+## Comparison with other tools
 
-```
-deck-store.ts:42:3  error  unused-methods      Method DeckStore.reset is never used
-links.ts:30:3       error  unused-object-keys  links.privacyPolicy is never read
+|                                            | slop-police | knip | jscpd |
+| ------------------------------------------ | :---------: | :--: | :---: |
+| Unused exports and files                   |      ✓      |  ✓   |       |
+| Unused enum members                        |      ✓      |  ✓   |       |
+| Unused class methods                       |      ✓      |      |       |
+| Unused object keys                         |      ✓      |      |       |
+| Copy-pasted code                           |      ✓      |      |   ✓   |
+| Helpers rewritten instead of reused        |      ✓      |      |       |
+| Pass-through wrappers, getters and aliases |      ✓      |      |       |
+| Flattened errors                           |      ✓      |      |       |
+
+## CI
+
+Make CI fail when something slips through
 
-2 errors, 0 warnings
+```yaml
+- run: npx slop-police
 ```
 
 ## Configuration
 
-slop-police reads `slop-police.json` from the current directory:
+Put a `slop-police.json` in the directory you run it from:
 
 ```json
 {
   "projects": ["packages/api/tsconfig.json", "packages/frontend/tsconfig.app.json"],
-  "ignore": ["**/.next/**"],
-  "testFiles": ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"],
-  "rules": {
-    "unused-methods": ["error", { "includePrivate": true }],
-    "no-identity-type-alias": "warn",
-    "no-single-string-cn": "off"
-  }
+  "testFiles": ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"]
 }
 ```
 
 - `projects`: tsconfig files to analyze. Usages are counted across all of them, so a method used only by another package still counts as used.
 - `ignore`: glob patterns (relative to the config) for files to skip entirely. Files that `.gitignore` ignores are skipped too.
 - `testFiles`: glob patterns for tests. Usages inside tests count, but declarations inside tests are not reported.
-- `rules`: every built-in rule runs as an error with its default options. List a rule here to change that: `"error"`, `"warn"` or `"off"`, or `[severity, options]`. Plugin rules run only when they're listed.
+- `rules`: you usually don't need it, since every built-in rule is already on as an error. It's for rule options, like the stricter `unused-exports` setup below, and for turning on plugin rules. A rule takes `"error"`, `"warn"`, `"off"` or `[severity, options]`.
 - `plugins`: modules with [custom rules](#custom-rules), as paths relative to the config or package names.
 
 Exit code is `1` when there are errors, `2` for an invalid config, `0` otherwise.
 
-slop-police needs your dependencies installed: without their types it can't tell where a method or key is used. When imports in the analyzed files don't resolve (and no `declare module` covers them), it lists them and exits with `1` without linting. Side-effect imports like `import "./styles.css"` don't count.
-
 ## Rules
 
-### unused-methods
+### no-pass-through-wrapper
 
-Class methods, getters and setters that are never referenced anywhere in the analyzed projects.
+A function or method that only returns a call to another function.
 
 ```ts
-class Store {
-  load() {}
-  reset() {} // Method Store.reset is never used
+function loadUser(id: string) {
+  return api.loadUser(id);
 }
-new Store().load();
-```
-
-A member also counts as used when it implements an interface member that is used or that is declared outside the analyzed code (a library calls it), when it's named in `Pick<Class, "name">`, or when an instance is passed to a JSX prop whose type requires it. Options: `includePrivate` and `includeProtected` (both `false` by default).
-
-### unused-object-keys
-
-Keys of a top-level `const` object literal that are never read, as long as every use of the object reads statically known keys (`links.a`, `links["a"]`, `const { a } = links`). Objects that escape (passed to a function, spread, accessed dynamically) are skipped.
-
-```ts
-export const links = {
-  docs: "https://example.com/docs",
-  legacy: "https://example.com/old", // links.legacy is never read
-};
-open(links.docs);
 ```
 
 ### no-identity-type-alias
@@ -84,113 +75,161 @@ A type alias that only renames another type.
 
 ```ts
 type User = { id: string };
-type Member = User; // Type alias Member only renames User
+type Member = User;
 ```
 
-### no-pass-through-getter
+### no-duplicate-code
 
-A getter that only returns another property of `this`.
+Copy-pasted blocks of code. Options: `minLines` (default `11`) and `minTokens` (default `50`).
 
 ```ts
-class Store {
-  private items: Item[] = [];
-  get list() { return this.items; } // Getter list only returns this.items
-}
+// stripe-webhook.ts
+const mailer = await Mailer.connect({
+  host: "smtp.example.com",
+  port: 465,
+  secure: true,
+  user: env.SMTP_USER,
+  password: env.SMTP_PASSWORD,
+});
+await mailer.send({ to: customer.email, subject: "Your license" });
+
+// reset-password.ts
+const mailer = await Mailer.connect({
+  host: "smtp.example.com",
+  port: 465,
+  secure: true,
+  user: env.SMTP_USER,
+  password: env.SMTP_PASSWORD,
+});
+await mailer.send({ to: user.email, subject: "Reset your password" });
 ```
 
-### no-pass-through-wrapper
+### no-duplicate-function
 
-A function or method whose body only returns a call (awaited or not) to a named function, passing its own parameters on as they are.
+The same function written again in several files, with different variable names. Option: `minFiles` (default `3`).
 
 ```ts
-function loadUser(id: string) { // Function loadUser only forwards to api.loadUser
-  return api.loadUser(id);
+// users.ts
+export async function loadUsers(id: string) {
+  const response = await fetchJson("/users/" + id);
+  if (!response.ok) throw new Error("failed to load users");
+  return response.data;
+}
+
+// posts.ts
+export async function loadPosts(postId: string) {
+  const res = await fetchJson("/posts/" + postId);
+  if (!res.ok) throw new Error("failed to load posts");
+  return res.data;
+}
+
+// teams.ts
+export async function loadTeams(teamId: string) {
+  const result = await fetchJson("/teams/" + teamId);
+  if (!result.ok) throw new Error("failed to load teams");
+  return result.data;
 }
 ```
 
-It uses types to skip wrappers that do something:
+### no-pass-through-getter
 
-- the shape is required: a method of a typed object literal (a `Proxy` handler, a Worker's `fetch`), a method that implements or overrides an inherited member, or a function assigned to a variable with a declared type. An override that only calls `super`'s method of the same name is still reported.
-- the wrapper adds types: type parameters, overloads, or parameter and return types declared differently from the callee's, like `t(key: TranslationKey)` around `translate(key: string)`.
-- it delegates to a private or protected member, like `get(key) { return this.items.get(key); }`.
+A getter that only returns another property.
 
-Calls on computed values (`getDay(date).getTime()`, `/^\s*$/.test(text)`) aren't forwarding, so they don't count.
+```ts
+class Store {
+  private items: Item[] = [];
+  get list() { return this.items; }
+}
+```
 
 ### no-redundant-value-alias
 
-A local `const` that only renames another `const`, when using the original directly means the same thing.
+A variable that only renames another variable.
 
 ```ts
 function render() {
   const user = getUser();
-  const current = user; // Local alias current only renames user; use the original binding directly
+  const current = user;
   return current.name;
 }
 ```
 
 ### no-single-string-cn
 
-`cn()` called with a single static class string.
+`cn()` with a single class string.
 
 ```tsx
-<div className={cn("flex gap-2")} /> // Use the class string directly instead of wrapping it in cn()
+<div className={cn("flex gap-2")} />
 ```
 
-### no-placeholder-comment
+### no-stringified-unknown-error
 
-A comment that only promises future work instead of describing the code: "add more validation", "handle more cases", "can be extended in the future", "extend this logic", "customize this behavior", "future enhancement", "implement … here". Ordinary TODOs don't match.
+Turning a caught error into a string with `error instanceof Error ? error.message : String(error)`.
 
 ```ts
-function parse(input: string) {
-  // Add more validation here
-  return JSON.parse(input);
+try {
+  await sendMessage(chatId, text);
+} catch (error) {
+  return { ok: false, error: error instanceof Error ? error.message : String(error) };
 }
 ```
 
-### no-duplicate-code
+### unused-object-keys
 
-Copy-pasted code: at least 50 tokens in a row that repeat earlier code (in the same file or one before it by path) and span at least 11 lines. Tokens are compared by their text, types included, so a renamed variable or a different type ends a copy, but comments, formatting and imports are left out. Test files are neither reported nor compared. `// slop-police-ignore no-duplicate-code` above a statement, class member or object property takes it out of the comparison, so it is not reported as a copy or as the original. Options: `minLines` (default `11`, counting every line a copy spans) and `minTokens` (default `50`).
+Object keys that are never read.
 
 ```ts
-// update-card.ts and delete-card.ts both check the card the same way:
-const userId = ctx.userId;
-assert(userId);
+export const links = {
+  docs: "https://example.com/docs",
+  legacy: "https://example.com/old", // links.legacy is never read
+};
+open(links.docs);
+```
 
-const cards = await getCardsWithDeck(ctx.db, [input.id]);
-if (cards.length === 0) {
-  throw notFound("Card not found");
-}
-const card = cards[0];
-if (card.deckAuthorId !== userId) {
-  throw forbidden("You don't own this card");
+An index with a literal type reads only the keys in that type, so `labels[status]` with `status: "active" | "expired"` leaves a `trial` key unused. An index typed as `string` or `any`, or an object passed elsewhere, could read any key, so the object is skipped.
+
+### unused-enum-members
+
+Enum members that are never used.
+
+```ts
+enum Status {
+  Active,
+  Archived, // Enum member Status.Archived is never used
 }
-// delete-card.ts:6:5  Lines 6-16 duplicate update-card.ts:6-16
+const isActive = (status: Status) => status === Status.Active;
 ```
 
-### no-duplicate-function
+### unused-exports
 
-A function whose body has the same shape as functions in at least two other files: a helper that was rewritten instead of reused. Shapes ignore the names of parameters and locals and the values of literals, but not the names of what the body calls or reads. Bodies with fewer than 2 statements or 16 syntax nodes, and functions in test files, don't count. Option: `minFiles` (default `3`, at least `2`), the number of files a shape has to appear in.
+Exports that nothing imports, or that are only used in their own file.
 
 ```ts
-// users.ts, posts.ts and teams.ts each have:
-export async function loadUsers(id: string) {
-  const response = await fetchJson("/users/" + id);
-  if (!response.ok) throw new Error("failed to load users");
-  return response.data;
-}
-// Function loadUsers has the same body shape as loadPosts (posts.ts:1), loadTeams (teams.ts:1)
+// lib.ts
+export type Options = { strict: boolean }; // Export Options is only used in its own file
+export function parse(text: string, options?: Options) {}
+export function format() {} // Export format is never used
+
+// main.ts
+import { parse } from "./lib";
 ```
 
-### no-stringified-unknown-error
+If you want to be extra strict, list your entry points in the `entry` option. slop-police then also finds whole files that nothing imports from them or from tests. Code used only by such dead files counts as unused too.
 
-`error instanceof Error ? error.message : String(error)` (in either order), which flattens a caught value into a string and drops its type, stack and cause. A plain `instanceof Error` check counts when the variable is named `error`, `err`, `e` or `cause`; an `||` of `instanceof` checks counts for any name. A function that does nothing but this conversion, like `getErrorMessage(error)`, is where it belongs and isn't reported; use it instead of repeating the expression.
+```json
+"unused-exports": ["error", { "entry": ["src/main.tsx", "src/routes/**/*.tsx", "vite.config.ts"] }]
+```
+
+### unused-methods
+
+Class methods that are never called. Here `reset` is unused.
 
 ```ts
-try {
-  await sendMessage(chatId, text);
-} catch (error) {
-  return { ok: false, error: error instanceof Error ? error.message : String(error) }; // Caught value error is flattened into a string
+class Store {
+  load() {}
+  reset() {}
 }
+new Store().load();
 ```
 
 ## Custom rules
@@ -286,7 +325,7 @@ test("no-direct-fetch", () => {
 });
 ```
 
-Plugins need the npm launcher (`npx slop-police` or `pnpm exec slop-police`), which runs them in Node while the linter serves ASTs and types. Published plugin packages must ship JavaScript, since Node doesn't run TypeScript from `node_modules`.
+Plugins work only through the npm launcher (`npx slop-police`).
 
 ## Ignoring findings
 
@@ -302,8 +341,6 @@ class Store {
 export const legacyLinks = { a: "/a", b: "/b" };
 ```
 
-For `no-placeholder-comment`, put the ignore comment on the line directly above the reported comment.
-
 ## Requirements
 
 macOS or Linux on arm64 or x64 (on Windows, use WSL), and Node.js 22.18 or later. The linter bundles its own TypeScript 7 compiler, so your tsconfigs need to work with TypeScript 7.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slop-police",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "Type-aware TypeScript linter for the dead code and needless indirection AI agents leave behind",
   "keywords": [
     "typescript",
@@ -41,9 +41,9 @@
     "node": ">=22.18"
   },
   "optionalDependencies": {
-    "slop-police-darwin-arm64": "0.3.7",
-    "slop-police-darwin-x64": "0.3.7",
-    "slop-police-linux-arm64": "0.3.7",
-    "slop-police-linux-x64": "0.3.7"
+    "slop-police-darwin-arm64": "0.3.9",
+    "slop-police-darwin-x64": "0.3.9",
+    "slop-police-linux-arm64": "0.3.9",
+    "slop-police-linux-x64": "0.3.9"
   }
 }