@tianjos/eslint-plugin-elegant 0.8.0 → 0.9.0

package/README.md

@@ -63,14 +63,25 @@ export default [
 ];
 ```
 
+Adopting this on a codebase that already exists? Spread
+`elegant.configs.starter` instead — same rules, with the four heaviest demoted
+so the first run gives you a list you can work through. See
+[Adopting on an existing codebase](#adopting-on-an-existing-codebase).
+
 A complete, copy-pasteable example (including test-file overrides) lives in
 [`eslint.config.example.mjs`](./eslint.config.example.mjs).
 
 ## Rules
 
-The `recommended` config enables every custom rule plus two native ones,
-[`max-params`](https://eslint.org/docs/latest/rules/max-params) and
-[`no-else-return`](https://eslint.org/docs/latest/rules/no-else-return).
+The plugin exports two configs, both carrying every rule below plus two native
+ones, [`max-params`](https://eslint.org/docs/latest/rules/max-params) and
+[`no-else-return`](https://eslint.org/docs/latest/rules/no-else-return):
+
+- **`recommended`** — the severities in the table below. What the plugin
+  argues for.
+- **`starter`** — the same rules with the four heaviest demoted, for adopting
+  on a codebase that already exists. See
+  [Adopting on an existing codebase](#adopting-on-an-existing-codebase).
 
 | Rule                                   | Source | What it catches                                                                 | `recommended` |
 | -------------------------------------- | ------ | ------------------------------------------------------------------------------- | ------------- |
@@ -768,19 +779,31 @@ value from the wire format of a database column. `no-type-assertion` counts
 `x as unknown as T` twice, once per assertion, which is arguably correct.
 
 None of that makes them wrong — it makes them rules you adopt on purpose
-rather than inherit. **Enable the preset, then take the top of that table back
-to `warn` or `off` and work down it.** The rules below `no-type-assertion` sum
-to 1.75 per file, which is a starting point you can actually clear:
+rather than inherit. That is what `starter` is: every rule `recommended`
+carries, with those four demoted, leaving the 1.75 per file below them — a
+list somebody can actually work through.
 
 ```js
 rules: {
-  ...elegant.configs.recommended.rules,
+  ...elegant.configs.starter.rules,
+}
+```
 
-  // The four that need a plan of their own. Re-enable one at a time.
-  'elegant/no-comments-in-function-body': 'off',
-  'elegant/no-interpolated-log-message': 'warn',
-  'elegant/no-null': 'warn',
-  'elegant/no-type-assertion': 'warn',
+| | `recommended` | `starter` |
+| --- | --- | --- |
+| `no-comments-in-function-body` | `error` | `off` |
+| `no-interpolated-log-message` | `error` | `warn` |
+| `no-null` | `error` | `warn` |
+| `no-type-assertion` | `error` | `warn` |
+| everything else | unchanged | unchanged |
+
+Promote them back one at a time as you clear them, and switch to
+`recommended` once nothing is left:
+
+```js
+rules: {
+  ...elegant.configs.starter.rules,
+  'elegant/no-null': 'error',   // cleared, so hold the line
 }
 ```
 
@@ -813,7 +836,9 @@ block scoped to your spec globs:
 The package ships a single CommonJS build that is consumable as both
 `require('@tianjos/eslint-plugin-elegant')` and an ESM
 `import elegant from '@tianjos/eslint-plugin-elegant'`. The exported object
-exposes `{ meta, rules, configs }`.
+exposes `{ meta, rules, configs }`, where `configs` holds `recommended` and
+`starter`. All three load paths are exercised against the built output by
+`tests/dist.test.ts`.
 
 ## Prior art
 

package/dist/index.js

@@ -88,5 +88,32 @@ plugin.configs.recommended = {
         'no-else-return': ['error', { allowElseIf: false }],
     },
 };
+/**
+ * The four rules that carry most of the friction on code that already exists.
+ * Each encodes a defensible position whose boundary this plugin cannot see —
+ * a comment that wants to be a function, a logging convention already chosen,
+ * `null` as the wire format of a column, an assertion widening a type — so on
+ * a mature codebase they report by the thousand. `recommended` keeps them at
+ * `error` on purpose; `starter` is the door in.
+ */
+const NOISIEST = {
+    'elegant/no-comments-in-function-body': 'off',
+    'elegant/no-interpolated-log-message': 'warn',
+    'elegant/no-null': 'warn',
+    'elegant/no-type-assertion': 'warn',
+};
+/**
+ * Every rule `recommended` carries, with the four heaviest demoted so the
+ * first run on an existing codebase produces a list somebody can work through.
+ * Promote them back one at a time; see "Adopting on an existing codebase".
+ */
+plugin.configs.starter = {
+    name: 'elegant/starter',
+    plugins: { elegant: plugin },
+    rules: {
+        ...plugin.configs.recommended.rules,
+        ...NOISIEST,
+    },
+};
 plugin.default = plugin;
 module.exports = plugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianjos/eslint-plugin-elegant",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Opinionated ESLint rules for elegant, behavior-rich TypeScript: honest types, encapsulated state, small uncoupled classes, guard-clause flow, and structured logging. Built for NestJS and DDD codebases.",
   "keywords": [
     "eslint",
@@ -43,7 +43,7 @@
     "build": "tsc -p tsconfig.json",
     "lint": "npm run build && eslint .",
     "typecheck": "tsc -p tsconfig.test.json",
-    "test": "jest",
+    "test": "npm run build && jest",
     "release": "standard-version --release-as minor",
     "release:patch": "standard-version --release-as patch",
     "prepublishOnly": "npm run build && npm test"