feat: permissive-start + progressive ratchet scaffolding (#211)

mojoatomic · web-flow · commit 2306e3407259 · 2025-11-11T08:34:07.000-06:00
feat: permissive-start preset and init flag - Add --permissive/--permissive-start to init to generate warn-only ESLint config - Export configs['permissive-start'] shareable preset - Include Jest/browser overrides in generator Refs: #210
diff --git a/README.md b/README.md
@@ -242,19 +242,20 @@ See [docs/learn.md](docs/learn.md) for methodology details.
 
 <!-- begin auto-generated rules list -->
 
+⚠️ Configurations set to warn in.\
 🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).\
 💡 Manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
 
-| Name                                                                   | Description                                                                                        | 🔧 | 💡 |
-| :--------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- | :- | :- |
-| [enforce-domain-terms](docs/rules/enforce-domain-terms.md)             | Encourage domain-specific naming using declared project terms                                      |    | 💡 |
-| [enforce-naming-conventions](docs/rules/enforce-naming-conventions.md) | Enforce naming conventions from project config (style, boolean/async prefixes, plural collections) |    | 💡 |
-| [no-equivalent-branches](docs/rules/no-equivalent-branches.md)         | Detect if/else branches that do the same thing                                                     | 🔧 |    |
-| [no-generic-names](docs/rules/no-generic-names.md)                     | Flag generic names; enforce domain-specific naming                                                 |    |    |
-| [no-redundant-calculations](docs/rules/no-redundant-calculations.md)   | Detect redundant calculations that should be computed at compile time                              | 🔧 | 💡 |
-| [no-redundant-conditionals](docs/rules/no-redundant-conditionals.md)   | Simplify redundant conditional expressions                                                         | 🔧 |    |
-| [no-unnecessary-abstraction](docs/rules/no-unnecessary-abstraction.md) | Suggest inlining trivial single-use wrapper functions that add no value                            |    | 💡 |
-| [prefer-simpler-logic](docs/rules/prefer-simpler-logic.md)             | Simplify boolean expressions and remove redundant logic                                            | 🔧 |    |
+| Name                                                                   | Description                                                                                        | ⚠️                          | 🔧 | 💡 |
+| :--------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- | :-------------------------- | :- | :- |
+| [enforce-domain-terms](docs/rules/enforce-domain-terms.md)             | Encourage domain-specific naming using declared project terms                                      | ![badge-permissive-start][] |    | 💡 |
+| [enforce-naming-conventions](docs/rules/enforce-naming-conventions.md) | Enforce naming conventions from project config (style, boolean/async prefixes, plural collections) |                             |    | 💡 |
+| [no-equivalent-branches](docs/rules/no-equivalent-branches.md)         | Detect if/else branches that do the same thing                                                     | ![badge-permissive-start][] | 🔧 |    |
+| [no-generic-names](docs/rules/no-generic-names.md)                     | Flag generic names; enforce domain-specific naming                                                 | ![badge-permissive-start][] |    |    |
+| [no-redundant-calculations](docs/rules/no-redundant-calculations.md)   | Detect redundant calculations that should be computed at compile time                              | ![badge-permissive-start][] | 🔧 | 💡 |
+| [no-redundant-conditionals](docs/rules/no-redundant-conditionals.md)   | Simplify redundant conditional expressions                                                         | ![badge-permissive-start][] | 🔧 |    |
+| [no-unnecessary-abstraction](docs/rules/no-unnecessary-abstraction.md) | Suggest inlining trivial single-use wrapper functions that add no value                            | ![badge-permissive-start][] |    | 💡 |
+| [prefer-simpler-logic](docs/rules/prefer-simpler-logic.md)             | Simplify boolean expressions and remove redundant logic                                            | ![badge-permissive-start][] | 🔧 |    |
 
 <!-- end auto-generated rules list -->
 
diff --git a/docs/rules/enforce-domain-terms.md b/docs/rules/enforce-domain-terms.md
@@ -1,5 +1,7 @@
 # Encourage domain-specific naming using declared project terms (`ai-code-snifftest/enforce-domain-terms`)
 
+⚠️ This rule _warns_ in the `permissive-start` config.
+
 💡 This rule is manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
 
 <!-- end auto-generated rule header -->
diff --git a/docs/rules/no-equivalent-branches.md b/docs/rules/no-equivalent-branches.md
@@ -1,5 +1,7 @@
 # Detect if/else branches that do the same thing (`ai-code-snifftest/no-equivalent-branches`)
 
+⚠️ This rule _warns_ in the `permissive-start` config.
+
 🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
 
 <!-- end auto-generated rule header -->
diff --git a/docs/rules/no-generic-names.md b/docs/rules/no-generic-names.md
@@ -1,5 +1,7 @@
 # Flag generic names; enforce domain-specific naming (`ai-code-snifftest/no-generic-names`)
 
+⚠️ This rule _warns_ in the `permissive-start` config.
+
 <!-- end auto-generated rule header -->
 
 Flags generic identifiers like `data`, `result`, `temp`, or those containing forbidden domain terms (e.g., `song`) based on your project’s `.ai-coding-guide.json` or rule options.
diff --git a/docs/rules/no-redundant-calculations.md b/docs/rules/no-redundant-calculations.md
@@ -1,5 +1,7 @@
 # Detect redundant calculations that should be computed at compile time (`ai-code-snifftest/no-redundant-calculations`)
 
+⚠️ This rule _warns_ in the `permissive-start` config.
+
 🔧💡 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) and manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
 
 <!-- end auto-generated rule header -->
diff --git a/docs/rules/no-redundant-conditionals.md b/docs/rules/no-redundant-conditionals.md
@@ -1,5 +1,7 @@
 # Simplify redundant conditional expressions (`ai-code-snifftest/no-redundant-conditionals`)
 
+⚠️ This rule _warns_ in the `permissive-start` config.
+
 🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
 
 <!-- end auto-generated rule header -->
diff --git a/docs/rules/no-unnecessary-abstraction.md b/docs/rules/no-unnecessary-abstraction.md
@@ -1,5 +1,7 @@
 # Suggest inlining trivial single-use wrapper functions that add no value (`ai-code-snifftest/no-unnecessary-abstraction`)
 
+⚠️ This rule _warns_ in the `permissive-start` config.
+
 💡 This rule is manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
 
 <!-- end auto-generated rule header -->
diff --git a/docs/rules/prefer-simpler-logic.md b/docs/rules/prefer-simpler-logic.md
@@ -1,5 +1,7 @@
 # Simplify boolean expressions and remove redundant logic (`ai-code-snifftest/prefer-simpler-logic`)
 
+⚠️ This rule _warns_ in the `permissive-start` config.
+
 🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
 
 <!-- end auto-generated rule header -->
diff --git a/lib/commands/init/index.js b/lib/commands/init/index.js
@@ -69,6 +69,12 @@ const external = shouldEnableExternalConstants(args);
   }
   // Merge fingerprint signals into config (domains + constantResolution)
   applyFingerprintToConfig(cwd, cfg);
+
+  // Optional: start with permissive ESLint (progressive ratcheting)
+  if (args && (args.permissive || String(args['permissive-start']).toLowerCase() === 'true')) {
+    cfg.eslintMode = 'permissive';
+  }
+
   if (external && (!allowlist || allowlist.length === 0)) {
     console.warn('Warning: --external used without allowlist; consider adding --allowlist to limit npm scope.');
   }
diff --git a/lib/eslint-presets/permissive-start.js b/lib/eslint-presets/permissive-start.js
@@ -0,0 +1,30 @@
+'use strict';
+
+// Permissive start preset: measure-only rules for progressive ratcheting
+module.exports = {
+  rules: {
+    // Baseline – measure only
+    'no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+    'no-undef': 'warn',
+    'no-empty': ['warn', { allowEmptyCatch: true }],
+    'eqeqeq': ['warn', 'always'],
+    'camelcase': ['warn', { properties: 'never', ignoreDestructuring: true, ignoreImports: true }],
+
+    // Architecture – measure only
+    'complexity': ['warn', 10],
+    'max-lines': ['warn', 250],
+    'max-lines-per-function': ['warn', 50],
+    'max-depth': ['warn', 4],
+    'max-params': ['warn', 4],
+    'max-statements': ['warn', 30],
+
+    // Plugin – measure only (domain/structure)
+    'ai-code-snifftest/no-redundant-calculations': 'warn',
+    'ai-code-snifftest/no-equivalent-branches': 'warn',
+    'ai-code-snifftest/prefer-simpler-logic': 'warn',
+    'ai-code-snifftest/no-redundant-conditionals': 'warn',
+    'ai-code-snifftest/no-unnecessary-abstraction': 'warn',
+    'ai-code-snifftest/no-generic-names': 'warn',
+    'ai-code-snifftest/enforce-domain-terms': 'warn'
+  }
+};
diff --git a/lib/index.js b/lib/index.js
@@ -21,6 +21,12 @@ module.exports = {
   },
   rules: requireIndex(__dirname + '/rules'),
   // Lightweight, additive presets intended for wizard composition
-  presets: requireIndex(__dirname + '/eslint-presets')
+  presets: requireIndex(__dirname + '/eslint-presets'),
+  // Provide shareable configs for flat config users
+  configs: {
+    'permissive-start': require(__dirname + '/eslint-presets/permissive-start'),
+    'baseline': require(__dirname + '/eslint-presets/baseline'),
+    'ai-friendly': require(__dirname + '/eslint-presets/ai-friendly')
+  }
 };
 
diff --git a/package.json b/package.json
@@ -11,11 +11,15 @@
   "main": "./lib/index.js",
   "exports": "./lib/index.js",
   "files": [
-    "lib",
-    "bin"
+    "bin/",
+    "lib/",
+    "scripts/ratchet.js",
+    "README.md",
+    "LICENSE"
   ],
   "bin": {
-    "eslint-plugin-ai-code-snifftest": "./bin/cli.js"
+    "eslint-plugin-ai-code-snifftest": "./bin/cli.js",
+    "eslint-plugin-ai-code-snifftest-ratchet": "./scripts/ratchet.js"
   },
   "scripts": {
     "lint": "npm-run-all \"lint:*\"",
diff --git a/scripts/ratchet.js b/scripts/ratchet.js

Original file line number	Diff line number	Diff line change
`@@ -69,6 +69,12 @@ const external = shouldEnableExternalConstants(args);`
`69`	`69`	`}`
`70`	`70`	`// Merge fingerprint signals into config (domains + constantResolution)`
`71`	`71`	`applyFingerprintToConfig(cwd, cfg);`
	`72`	`+`
	`73`	`+ // Optional: start with permissive ESLint (progressive ratcheting)`
	`74`	`+ if (args && (args.permissive \|\| String(args['permissive-start']).toLowerCase() === 'true')) {`
	`75`	`+ cfg.eslintMode = 'permissive';`
	`76`	`+ }`
	`77`	`+`
`72`	`78`	`if (external && (!allowlist \|\| allowlist.length === 0)) {`
`73`	`79`	`console.warn('Warning: --external used without allowlist; consider adding --allowlist to limit npm scope.');`
`74`	`80`	`}`