eslint-plugin-unslop 0.5.0 → 0.5.1

package/README.md

@@ -1,6 +1,6 @@
 # eslint-plugin-unslop
 
-ESLint plugin for architecture enforcement and code quality. Define module boundaries, control imports and exports, catch false sharing, and fix common LLM-generated code smells - all from a single shared configuration.
+ESLint plugin for architecture enforcement and code quality. Define module boundaries, control imports and exports, catch false sharing and single-use constants, and fix common LLM-generated code smells - all from a single shared configuration.
 
 Requires ESLint 9+ (flat config). TypeScript optional but recommended.
 
@@ -12,7 +12,7 @@ npm install --save-dev eslint-plugin-unslop
 
 ## Quick Start
 
-The full config enables the complete rule suite - architecture enforcement plus symbol fixers:
+The `full` config enables the complete rule suite:
 
 ```js
 // eslint.config.mjs
@@ -42,22 +42,19 @@ export default [
 ]
 ```
 
-Architecture rules (`import-control`, `export-control`, `no-false-sharing`) require a reachable
-`tsconfig.json`. Set `compilerOptions.rootDir`, and if you use aliases, configure
-`compilerOptions.paths`.
+Architecture rules (`import-control`, `export-control`, `no-false-sharing`, `no-single-use-constants`) require a reachable `tsconfig.json`. Set `compilerOptions.rootDir`, and if you use aliases, configure `compilerOptions.paths`.
 
-This turns on:
+| Rule                             | What it does                                                           |
+| -------------------------------- | ---------------------------------------------------------------------- |
+| `unslop/import-control`          | Enforces module boundaries and forbids local namespace imports         |
+| `unslop/export-control`          | Restricts export patterns and forbids `export *` in module entrypoints |
+| `unslop/no-false-sharing`        | Flags shared entrypoint symbols with fewer than two consumer groups    |
+| `unslop/no-single-use-constants` | Flags module-scope constants used once or never across the project     |
+| `unslop/no-special-unicode`      | Catches smart quotes, invisible spaces, and other unicode impostors    |
+| `unslop/no-unicode-escape`       | Prefers `"©"` over `"\u00A9"`                                          |
+| `unslop/read-friendly-order`     | Enforces top-down, dependency-friendly declaration order               |
 
-| Rule                         | Severity | What it does                                                           |
-| ---------------------------- | -------- | ---------------------------------------------------------------------- |
-| `unslop/import-control`      | error    | Enforces boundaries and forbids local namespace imports                |
-| `unslop/export-control`      | error    | Restricts export patterns and forbids `export *` in module entrypoints |
-| `unslop/no-false-sharing`    | error    | Flags shared entrypoint symbols with fewer than two consumer groups    |
-| `unslop/no-special-unicode`  | error    | Catches smart quotes, invisible spaces, and other unicode impostors    |
-| `unslop/no-unicode-escape`   | error    | Prefers `"©"` over `"\u00A9"`                                          |
-| `unslop/read-friendly-order` | error    | Enforces top-down, dependency-friendly declaration order               |
-
-The `configs.minimal` config contains only the zero-config symbol fixers (`no-special-unicode` and `no-unicode-escape`). It is included automatically within `configs.full`, or can be used standalone for projects that don't need architecture enforcement:
+The `minimal` config contains only the zero-config symbol fixers (`no-special-unicode` and `no-unicode-escape`) for projects that don't need architecture enforcement:
 
 ```js
 // eslint.config.mjs
@@ -66,13 +63,27 @@ import unslop from 'eslint-plugin-unslop'
 export default [unslop.configs.minimal]
 ```
 
+## Architecture Settings
+
+All architecture rules read from `settings.unslop.architecture`. Each key is a module matcher (path segments, `*` per segment), and each value is a policy object:
+
+```ts
+{
+  imports?: string[]  // module matchers this module may import from; '*' allows all
+  exports?: string[]  // regex patterns symbols exported from index.ts/types.ts must match
+  shared?: boolean    // marks module as shared; enables no-false-sharing
+}
+```
+
+Best match wins by fewest wildcards, then longest matcher, then declaration order. All architecture rules take no options - policy comes entirely from this shared settings block.
+
 ## Rules
 
 ### `unslop/import-control`
 
-Think of this as customs control for your modules - you declare which modules are allowed to import from which, and anything undeclared gets turned away at the border.
+Customs control for your modules: you declare which modules are allowed to import from which, and anything undeclared gets turned away at the border.
 
-The rule reads from a shared policy in `settings.unslop.architecture`. It's deny-by-default for cross-module imports, which means forgetting to declare a dependency is a loud error rather than a silent free-for-all. It also enforces:
+Deny-by-default for cross-module imports, so forgetting to declare a dependency is a loud error rather than a silent free-for-all. It also enforces:
 
 - cross-module imports must arrive through the public gate (`index.ts` or `types.ts`)
 - local cross-module namespace imports are forbidden (`import * as X from '<local-module>'`)
@@ -81,80 +92,30 @@ The rule reads from a shared policy in `settings.unslop.architecture`. It's deny
 
 Alias imports are resolved via `compilerOptions.paths` from `tsconfig.json`.
 
-#### Configuration
-
-```js
-// eslint.config.mjs
-import unslop from 'eslint-plugin-unslop'
-
-export default [
-  {
-    plugins: { unslop },
-    settings: {
-      unslop: {
-        architecture: {
-          utils: { shared: true },
-          'repository/*': {
-            imports: ['utils', 'models/*'],
-            exports: ['^create\\w+Repo$', '^Repository[A-Z]\\w+$'],
-          },
-          'models/*': {
-            imports: ['utils'],
-          },
-          app: {
-            imports: ['*'],
-          },
-        },
-      },
-    },
-    rules: {
-      'unslop/import-control': 'error',
-      'unslop/export-control': 'error',
-      'unslop/no-false-sharing': 'error',
-    },
-  },
-]
-```
-
 ### `unslop/export-control`
 
 The customs declaration form for the other direction: what are you actually exporting from your module's public entrypoints?
 
-When a module defines `exports` regex patterns in `settings.unslop.architecture`, every symbol exported from that module's `index.ts` or `types.ts` must match at least one pattern - otherwise it's stopped at the gate with an error at the export site. Modules without `exports` are waved through by default, so you can adopt this gradually. Regardless of module policy, `export * from ...` is rejected in `index.ts` and `types.ts` so symbol provenance stays explicit.
+When a module defines `exports` regex patterns, every symbol exported from its `index.ts` or `types.ts` must match at least one pattern - otherwise it's stopped at the gate. Modules without `exports` are waved through by default, so you can adopt this gradually. Regardless of module policy, `export * from ...` is rejected in public entrypoints so symbol provenance stays explicit.
 
 ### `unslop/no-false-sharing`
 
-The "shared" folder anti-pattern detector. LLMs (and some humans also) love creating shared APIs that are only used by one consumer - or worse, by nobody at all. This rule evaluates symbols exported from shared module entrypoints (`index.ts` and `types.ts`) and requires each exported symbol to be imported by at least two separate directory-level consumer groups. If a symbol is used in only one place, it's not shared - it's misplaced.
-
-#### Configuration
+The "shared" folder anti-pattern detector. LLMs (and some humans) love creating shared APIs that are only used by one consumer - or worse, by nobody at all. This rule evaluates symbols exported from shared module entrypoints and requires each to be imported by at least two separate directory-level consumer groups. If a symbol is used in only one place, it's not shared - it's misplaced.
 
-Shared modules are declared via `shared: true` on module policies in
-`settings.unslop.architecture`:
+Mark a module as shared via `shared: true`:
 
 ```js
-// eslint.config.mjs
-import unslop from 'eslint-plugin-unslop'
-
-export default [
-  unslop.configs.full,
-  {
-    settings: {
-      unslop: {
-        architecture: {
-          utils: { shared: true },
-          'shared/*': { shared: true },
-        },
-      },
+settings: {
+  unslop: {
+    architecture: {
+      utils: { shared: true },
+      'shared/*': { shared: true },
     },
   },
-]
+}
 ```
 
-The rule takes no options - all configuration comes from the shared architecture settings, consistent with `import-control` and `export-control`.
-
-Consumer counting is always at the directory level: the importer file path relative to the source root derived from `tsconfig.json`, minus filename. Both value imports and `import type` imports count as consumers, and alias imports configured in `compilerOptions.paths` are resolved the same as relative imports.
-
-#### What it catches
+Consumer counting is at the directory level: the importer file path relative to the source root derived from `tsconfig.json`, minus filename. Both value imports and `import type` imports count, and alias imports from `compilerOptions.paths` are resolved the same as relative imports.
 
 ```
 src/shared/index.ts
@@ -168,11 +129,28 @@ src/shared/types.ts
   -> error: symbol "LegacyOptions" has 0 consumer group(s) (no consumers found)
 ```
 
-### `unslop/read-friendly-order`
+### `unslop/no-single-use-constants`
+
+Flags module-scope `const` declarations that are used once or never across the entire project. LLM-generated code loves to extract magic values into constants that are then referenced a single time - adding indirection without improving clarity. If a constant isn't actually reused, inline it or delete it.
+
+Non-exported constants are counted locally via scope analysis. Exported constants are counted project-wide using the TypeScript program, so cross-file usage is detected. Function and class-expression initializers are ignored - only real value constants are checked.
+
+```js
+// Bad - defined once, used once
+const MAX_RETRIES = 3
+function fetchWithRetry() {
+  return retry(MAX_RETRIES)
+}
+
+// Good - inline it
+function fetchWithRetry() {
+  return retry(3)
+}
+```
 
-Enforces a top-down reading order for your code. The idea: when someone opens a file, they should see the important stuff first and the helpers below. LLM-generated code often scatters declarations in random order, making files harder to follow.
+### `unslop/read-friendly-order`
 
-This rule covers three areas:
+Enforces a top-down reading order. The idea: when someone opens a file, they should see the important stuff first and the helpers below. LLM-generated code often scatters declarations in random order, making files harder to follow.
 
 **Top-level ordering** - Public/exported symbols should come before the private helpers they use. Read the API first, implementation details second.
 
@@ -224,9 +202,6 @@ function buildFixture(overrides) {
 it('works', () => {
   /* ... */
 })
-function assertCorrect(value) {
-  expect(value).toBe(1)
-}
 beforeEach(() => {
   buildFixture()
 })
@@ -241,20 +216,17 @@ it('works', () => {
 function buildFixture(overrides) {
   return { id: 1, ...overrides }
 }
-function assertCorrect(value) {
-  expect(value).toBe(1)
-}
 ```
 
 ### `unslop/no-special-unicode`
 
-Disallows special unicode punctuation and whitespace characters in string literals and template literals. LLMs love to sprinkle in smart quotes (`“like this”`), non-breaking spaces, and other invisible gremlins that look fine in a PR review but cause fun bugs at runtime.
+Disallows special unicode punctuation and whitespace characters in string and template literals. LLMs love to sprinkle in smart quotes (`“like this”`), non-breaking spaces, and other invisible gremlins that look fine in a PR review but cause fun bugs at runtime.
 
-Caught characters include: left/right smart quotes (`“” ‘’`), non-breaking space, en/em dash, horizontal ellipsis, zero-width space, and various other exotic whitespace.
+Caught characters include: smart quotes (`“” ‘’`), non-breaking space, en/em dash, horizontal ellipsis, zero-width space, and various other exotic whitespace.
 
 ```js
 // Bad - these contain invisible special characters that look normal
-const greeting = 'Hello World' // a non-breaking space (U+00A0) is hiding between the words
+const greeting = 'Hello World' // a non-breaking space (U+00A0) is hiding between the words
 const quote = 'He said “hello”' // smart double quotes (U+201C, U+201D)
 
 // Good
@@ -262,13 +234,11 @@ const greeting = 'Hello World' // regular ASCII space
 const quote = 'He said "hello"' // plain ASCII quotes
 ```
 
-Note: the bad examples above contain actual unicode characters that may be
-indistinguishable from their ASCII counterparts in your font - that's exactly
-the problem this rule catches.
+Note: the bad examples above contain actual unicode characters that may be indistinguishable from their ASCII counterparts in your font - that's exactly the problem this rule catches.
 
 ### `unslop/no-unicode-escape`
 
-Prefers actual characters over `\uXXXX` escape sequences. If your string says `\u00A9`, just write `©` - your coworkers will thank you. LLM-generated code sometimes encodes characters as escape sequences for no good reason.
+Prefers actual characters over `\uXXXX` escape sequences. If your string says `\u00A9`, just write `©` - your coworkers will thank you.
 
 ```js
 // Bad