eslint-plugin-kerfjs 4.4.1 → 5.0.0-beta.3

package/README.md

@@ -83,7 +83,7 @@ npm install
 npm test
 ```
 
-The AST rules' test suites use ESLint's `RuleTester` with `@typescript-eslint/parser`. The `ai-assistant-configs` tests are filesystem-driven — they build temp project roots with fixture `node_modules/kerfjs/ai/` bundles and drive the rule's classifier directly, since `RuleTester` doesn't simulate the filesystem.
+The AST rules' test suites use ESLint's `RuleTester` with `@typescript-eslint/parser`. The `ai-assistant-configs` tests are filesystem-driven — they build temp project roots with fixture `node_modules/kerfjs/ai/` bundles, drive the classifier directly, and use the real ESLint API to prove plain lint is read-only while explicit `--fix` performs the external write.
 
 ## License
 

package/docs/rules/ai-assistant-configs.md

@@ -18,7 +18,7 @@ The rule resolves `kerfjs/ai/manifest.json` from the consumer's installed `kerfj
 A triggered file is then classified into one of three reported states (a fourth, "up-to-date," is silent):
 
 - **Missing** — the consumer's `dest` doesn't exist.
-- **Stale** — exists, parses cleanly, but its `kerf-skill-version` line is older than the bundle's.
+- **Stale** — exists, parses cleanly, its `kerf-skill-version` line is older than the bundle's, and its canonical-section hash matches that version in the manifest's history.
 - **Forked** — the consumer's file no longer matches the canonical layout: marker is missing, marker appears more than once, `kerf-skill-version` line is missing, or the content above the marker has been edited.
 
 ## ❌ Reported
@@ -46,7 +46,7 @@ For **missing** files, `--fix` copies the bundled canonical (`node_modules/kerfj
 
 For **stale** files, `--fix` replaces only the content **above and including the `KERF-APP-CANONICAL-END` marker**. Everything below the marker — the consumer's append zone — is preserved byte-for-byte. This is the "versioned-section preservation" strategy from the design doc.
 
-The `fix()` callback writes to a file OTHER than the linted source — unusual for an ESLint rule. ESLint only invokes `fix()` under `--fix`, so the side effect is opt-in by definition; plain `eslint` will report the warning without touching disk.
+The `fix()` callback writes to a file OTHER than the linted source — unusual for an ESLint rule. ESLint evaluates fix callbacks during ordinary lint too, so the callback gates this external write on an explicit CLI `--fix` flag. Plain `eslint` reports the warning without touching disk; `eslint --fix` opts into installation or update.
 
 ## ❗ Forked — no auto-fix
 
@@ -55,7 +55,8 @@ If the consumer has edited the file in a way that breaks the canonical/append-zo
 - **No marker present.** The file pre-dates the marker convention, the consumer deleted the marker, or the file is a hand-written variant. Auto-fixing would either clobber legitimate customizations or leave the file in an ambiguous state.
 - **Multiple markers.** A well-formed file has exactly one. Auto-fix would have to guess which boundary is real.
 - **No `kerf-skill-version` line.** The staleness signal is missing; we can't tell what's there.
-- **Content above the marker has been edited.** The contract is "above the marker is kerf's; below is yours." Above-the-marker edits are a deliberate fork.
+- **Content above the marker has been edited.** The contract is "above the marker is kerf's; below is yours." The rule checks stale files against the historical canonical hash for their own version, so an edited old section is preserved as a deliberate fork rather than overwritten.
+- **Canonical history unavailable.** An old version absent from the shipped manifest history cannot be proven untouched, so the rule conservatively refuses to overwrite it.
 
 Resolution: either restore the canonical layout (move customizations below a freshly-inserted marker, delete extras, re-add the version line) or disable the rule for this project — `'kerfjs/ai-assistant-configs': 'off'` in `eslint.config.js`.
 

package/index.js

@@ -8,7 +8,7 @@ import requireDataKeyInEach from './lib/rules/require-data-key-in-each.js';
 import requireDelegateDisposer from './lib/rules/require-delegate-disposer.js';
 
 const plugin = {
-  meta: { name: 'eslint-plugin-kerfjs', version: '0.13.0' },
+  meta: { name: 'eslint-plugin-kerfjs', version: '5.0.0-beta.3' },
   rules: {
     'no-inline-jsx-event-handlers': noInlineJsxEventHandlers,
     'no-raw-with-dynamic-arg': noRawWithDynamicArg,

package/lib/rules/ai-assistant-configs.js

@@ -8,9 +8,10 @@
  * `KERF-APP-CANONICAL-END` marker; the consumer's append zone below the
  * marker is preserved byte-for-byte (the "option 2" strategy from KF-217).
  *
- * Unusual for an ESLint rule: the `fix()` callback writes to a file
- * OTHER than the linted source. ESLint only invokes `fix()` when
- * `--fix` is enabled, so the side effect is opt-in by definition.
+ * Unusual for an ESLint rule: the `fix()` callback writes to a file OTHER than
+ * the linted source. ESLint evaluates fix callbacks during ordinary lint too,
+ * so the callback must explicitly gate that side effect on the CLI's `--fix`
+ * flag.
  */
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
@@ -118,12 +119,23 @@ export function classifyFile(file, bundleDir, cwd) {
   }
 
   const cmp = compareSemver(consumerVersion, file.version);
+  const consumerCanonicalHash = sha256(consumerCanonical);
   if (cmp === 0) {
     // Same version. Above-marker section should match the bundled sha256.
-    if (sha256(consumerCanonical) === file.sha256) return { state: 'ok' };
+    if (consumerCanonicalHash === file.sha256) return { state: 'ok' };
     return { state: 'forked', reason: 'content above marker has been edited' };
   }
   if (cmp < 0) {
+    const historicalHash = file.history?.[consumerVersion];
+    if (!historicalHash) {
+      return {
+        state: 'forked',
+        reason: `canonical hash for version ${consumerVersion} is unavailable`,
+      };
+    }
+    if (consumerCanonicalHash !== historicalHash) {
+      return { state: 'forked', reason: 'content above marker has been edited' };
+    }
     return {
       state: 'stale',
       consumerVersion,
@@ -210,9 +222,9 @@ const meta = {
     forked:
       '{{tool}} drop-in at `{{dest}}` is forked: {{reason}}. Restore the canonical layout (one `KERF-APP-CANONICAL-END` marker, no edits above it) or disable this rule with `\'kerfjs/ai-assistant-configs\': \'off\'`.',
   },
-  // Mark as fixable so ESLint runs the `fix()` callback under `--fix`.
-  // The callback writes to a separate file and returns null, so ESLint
-  // applies no edit to the linted source itself — see file header.
+  // Mark as fixable so the CLI exposes this rule under `--fix`. The callback
+  // writes to a separate file and returns null, so ESLint applies no edit to
+  // the linted source itself — see file header.
   fixable: 'code',
 };
 
@@ -225,10 +237,7 @@ function create(context) {
       const claudeEnabled = options.claude !== false;
       const cursorEnabled = options.cursor !== false;
       // ESLint v9: `context.cwd` is a string. ESLint v8: `context.getCwd()`.
-      const cwd =
-        (typeof context.cwd === 'string' && context.cwd)
-        || (typeof context.getCwd === 'function' && context.getCwd())
-        || process.cwd();
+      const cwd = contextCwd(context);
       const checked = runCheck(cwd);
       CACHED_RESULT = checked;
       if (!checked) return;
@@ -248,7 +257,7 @@ function create(context) {
             messageId: 'missing',
             data,
             fix() {
-              applyFix(file, checked.bundleDir, cwd, '');
+              if (isFixCliRun()) applyFix(file, checked.bundleDir, cwd, '');
               return null;
             },
           });
@@ -262,7 +271,9 @@ function create(context) {
               bundledVersion: result.bundledVersion,
             },
             fix() {
-              applyFix(file, checked.bundleDir, cwd, result.appendZone);
+              if (isFixCliRun()) {
+                applyFix(file, checked.bundleDir, cwd, result.appendZone);
+              }
               return null;
             },
           });
@@ -278,4 +289,16 @@ function create(context) {
   };
 }
 
+function contextCwd(context) {
+  return (
+    (typeof context.cwd === 'string' && context.cwd)
+    || (typeof context.getCwd === 'function' && context.getCwd())
+    || process.cwd()
+  );
+}
+
+function isFixCliRun() {
+  return process.argv.includes('--fix');
+}
+
 export default { meta, create };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-kerfjs",
-  "version": "4.4.1",
+  "version": "5.0.0-beta.3",
   "description": "ESLint rules that enforce kerf's hard rules — catches AI-shaped bugs at edit time.",
   "type": "module",
   "license": "MIT",