eslint-plugin-kerfjs 0.8.2 → 0.9.1

package/README.md

@@ -11,9 +11,9 @@ This plugin sits alongside two other defense layers shipped by [`kerfjs`](https:
 |---|---|---|
 | `tsc --noEmit` with strict typings | Hard Rules 8 (partial-set), most type errors | Build time |
 | Opt-in dev-warns (`KERF_DEV_WARN_*`) | Hard Rules 4 (rebuilt listeners), 7 (untracked signals), 8 (narrow set) | Runtime |
-| **This plugin** | Hard Rules 2, 5, 9, 11 — AST-shaped antipatterns | **Edit time** |
+| **This plugin** | Hard Rules 2, 5, 9, 11 — AST-shaped antipatterns; plus a project-hygiene nudge for the bundled AI-assistant configs | **Edit time** |
 
-The rules are AST-only — no `@typescript-eslint/parser` *service* dependency is required by the plugin (consumers configure their own parser).
+The four Hard-Rule rules are AST-only — no `@typescript-eslint/parser` *service* dependency is required by the plugin (consumers configure their own parser). The fifth rule, `ai-assistant-configs`, reads the filesystem instead of the AST and runs once per lint pass.
 
 ## Install
 
@@ -58,8 +58,9 @@ export default [
 | [`require-data-key-in-each`](docs/rules/require-data-key-in-each.md) | 2 — `data-key` per item | `error` |
 | [`no-nested-mount`](docs/rules/no-nested-mount.md) | 5 — one `mount()` per root | `error` |
 | [`prefer-module-jsx-augmentation`](docs/rules/prefer-module-jsx-augmentation.md) | 11 — augment `kerfjs/jsx-runtime`, not global | `error` |
+| [`ai-assistant-configs`](docs/rules/ai-assistant-configs.md) | — (project hygiene) | `warn` |
 
-The "Hard Rule" column refers to the numbered rules in [`docs/ai/usage-guide.md`](../docs/ai/usage-guide.md) on the main kerf repo.
+The "Hard Rule" column refers to the numbered rules in [`docs/ai/usage-guide.md`](../docs/ai/usage-guide.md) on the main kerf repo. `ai-assistant-configs` doesn't map to a Hard Rule — it checks that the bundled kerf-app Claude Code skill / Cursor rules drop-ins are installed and current in projects that use those tools. See [`docs/12-ai-assistant-configs.md`](../docs/12-ai-assistant-configs.md) on the main kerf repo for the design.
 
 ## Why these four (and not more)?
 
@@ -74,7 +75,7 @@ npm install
 npm test
 ```
 
-The test suite uses ESLint's `RuleTester` with `@typescript-eslint/parser`.
+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.
 
 ## License
 

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

@@ -0,0 +1,80 @@
+# `kerfjs/ai-assistant-configs`
+
+Check that the [kerf-app Claude Code skill](https://github.com/brianwestphal/kerf/blob/main/kerf.claude-skill.md) and [Cursor rules](https://github.com/brianwestphal/kerf/blob/main/kerf.cursorrules) drop-ins are installed in the project and up-to-date with the canonical files bundled inside the consumer's installed `kerfjs` package.
+
+Unlike the four AST-only rules in this plugin, this rule reads the **filesystem**, not source code. It runs once per lint pass and reports project-level hygiene issues rather than per-file code defects. Severity in `kerfjs.configs.recommended` is `warn`, not `error` — a missing skill file shouldn't fail CI.
+
+Maps to design doc [`docs/12-ai-assistant-configs.md`](https://github.com/brianwestphal/kerf/blob/main/docs/12-ai-assistant-configs.md) §12.4.
+
+## What it checks
+
+The rule resolves `kerfjs/ai/manifest.json` from the consumer's installed `kerfjs` (silently no-ops if `kerfjs` isn't a dep). For each bundled file, it picks a trigger heuristic — "is this project using the tool this file is for?" — and only nudges the consumer when the trigger says yes:
+
+| Bundled file | Triggers when | Installed to |
+|---|---|---|
+| `ai/skill.md` (Claude Code) | `.claude/` directory exists at the project root | `.claude/skills/kerf-app/SKILL.md` |
+| `ai/cursorrules` (Cursor) | `.cursorrules` file or `.cursor/` directory exists | `.cursorrules` |
+
+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.
+- **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
+
+```
+$ eslint .
+
+src/index.ts
+  1:1  warning  Claude Code kerf-app skill drop-in at `.claude/skills/kerf-app/SKILL.md`
+               is stale (have 1.0.0, latest is 1.1.0). Run `eslint --fix` to update
+               the canonical section above the `KERF-APP-CANONICAL-END` marker; your
+               customizations below the marker are preserved.
+               kerfjs/ai-assistant-configs
+```
+
+The warning attaches to whichever source file ESLint happens to lint first — it's a project-level report, not a code-level one. The message text makes that clear.
+
+## ✅ Auto-fix
+
+```bash
+$ eslint --fix .
+```
+
+For **missing** files, `--fix` copies the bundled canonical (`node_modules/kerfjs/ai/skill.md` / `node_modules/kerfjs/ai/cursorrules`) to the consumer's `dest` path, creating any missing parent directories.
+
+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.
+
+## ❗ Forked — no auto-fix
+
+If the consumer has edited the file in a way that breaks the canonical/append-zone contract, the rule refuses to auto-fix. It reports the specific shape mismatch instead:
+
+- **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.
+
+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`.
+
+## Options
+
+```js
+// eslint.config.js — disable both checks
+{ rules: { 'kerfjs/ai-assistant-configs': 'off' } }
+
+// Disable only one tool's check
+{ rules: { 'kerfjs/ai-assistant-configs': ['warn', { claude: false }] } }
+{ rules: { 'kerfjs/ai-assistant-configs': ['warn', { cursor: false }] } }
+```
+
+Both `claude` and `cursor` default to `true`. Setting either to `false` makes that specific drop-in silent regardless of trigger state.
+
+## What this rule does NOT do
+
+- It does not install the configs at `npm install` time — there are no postinstall scripts. The first lint pass after `npm install kerfjs` surfaces the recommendation.
+- It does not write to disk under plain `eslint` (no `--fix`). The warning is emitted; nothing changes on disk.
+- It does not push Claude Code or Cursor on consumers who haven't signalled they use them — no `.claude/` or `.cursor*` ⇒ silent.
+- It does not validate the *content* of the canonical files in the bundle. That's the kerf maintainer's responsibility (and the `check:ai-bundle-in-sync` gate in the kerf repo).

package/index.js

@@ -1,37 +1,43 @@
+import aiAssistantConfigs from './lib/rules/ai-assistant-configs.js';
 import noInlineJsxEventHandlers from './lib/rules/no-inline-jsx-event-handlers.js';
 import noNestedMount from './lib/rules/no-nested-mount.js';
 import preferModuleJsxAugmentation from './lib/rules/prefer-module-jsx-augmentation.js';
 import requireDataKeyInEach from './lib/rules/require-data-key-in-each.js';
 
 const plugin = {
-  meta: { name: 'eslint-plugin-kerfjs', version: '0.1.0' },
+  meta: { name: 'eslint-plugin-kerfjs', version: '0.9.0' },
   rules: {
     'no-inline-jsx-event-handlers': noInlineJsxEventHandlers,
     'require-data-key-in-each': requireDataKeyInEach,
     'no-nested-mount': noNestedMount,
     'prefer-module-jsx-augmentation': preferModuleJsxAugmentation,
+    'ai-assistant-configs': aiAssistantConfigs,
   },
   configs: {},
 };
 
-const errorRules = {
+// Most rules ship as `error` in recommended (AST-shaped antipatterns are
+// bugs). `ai-assistant-configs` is `warn` — it's a project-hygiene nudge,
+// not a code defect, and a missing skill file shouldn't fail CI.
+const recommendedRules = {
   'kerfjs/no-inline-jsx-event-handlers': 'error',
   'kerfjs/require-data-key-in-each': 'error',
   'kerfjs/no-nested-mount': 'error',
   'kerfjs/prefer-module-jsx-augmentation': 'error',
+  'kerfjs/ai-assistant-configs': 'warn',
 };
 
 // Flat config (ESLint v9+) — consumers add this object to their config array.
 plugin.configs.recommended = {
   plugins: { kerfjs: plugin },
-  rules: errorRules,
+  rules: recommendedRules,
 };
 plugin.configs.all = plugin.configs.recommended;
 
 // Legacy `.eslintrc` config — consumers extend `'plugin:kerfjs/legacy-recommended'`.
 plugin.configs['legacy-recommended'] = {
   plugins: ['kerfjs'],
-  rules: errorRules,
+  rules: recommendedRules,
 };
 
 export default plugin;

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

@@ -0,0 +1,274 @@
+/**
+ * Check that the kerf-app Claude Code skill / Cursor rules are installed and
+ * up-to-date against the canonical files bundled inside the consumer's
+ * installed `kerfjs` package (`node_modules/kerfjs/ai/manifest.json`).
+ *
+ * Implements §12.4 of kerf's `docs/12-ai-assistant-configs.md`. On
+ * `eslint --fix`, replaces only the canonical section above the
+ * `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.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+const MARKER = '<!-- KERF-APP-CANONICAL-END · your customizations below -->';
+const VERSION_RE = /kerf-skill-version:\s*(\d+\.\d+\.\d+(?:-[\w.]+)?)/;
+const VERSION_SCAN_BYTES = 512;
+
+// Module-level once-per-lint-run guard. ESLint instantiates the rule
+// per-file; we do the project-level filesystem check the first time the
+// `Program` visitor runs and cache the result for the remaining files in
+// the same lint pass.
+let CHECKED = false;
+let CACHED_RESULT = null;
+
+export function _resetForTests() {
+  CHECKED = false;
+  CACHED_RESULT = null;
+}
+
+function resolveManifestPath(cwd) {
+  try {
+    // `createRequire` from a path inside cwd resolves npm deps from there.
+    const req = createRequire(join(cwd, 'noop.js'));
+    return req.resolve('kerfjs/ai/manifest.json');
+  } catch {
+    return null;
+  }
+}
+
+function compareSemver(a, b) {
+  const pa = a.split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = b.split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+  }
+  return 0;
+}
+
+function findMarkerIndex(text) {
+  const first = text.indexOf(MARKER);
+  if (first === -1) return -1;
+  const second = text.indexOf(MARKER, first + MARKER.length);
+  if (second !== -1) return -2; // sentinel for "multiple markers"
+  return first;
+}
+
+function sha256(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+function extractVersion(text) {
+  const m = text.slice(0, VERSION_SCAN_BYTES).match(VERSION_RE);
+  return m ? m[1] : null;
+}
+
+function canonicalEndOffset(text) {
+  const idx = findMarkerIndex(text);
+  if (idx < 0) return idx;
+  // Include the marker line + the trailing newline. If the file ends
+  // exactly at the marker (no newline), use end-of-file.
+  const lineEnd = idx + MARKER.length;
+  if (text.length > lineEnd && text[lineEnd] === '\n') return lineEnd + 1;
+  return lineEnd;
+}
+
+/**
+ * Classify a single bundled file against the consumer's local copy.
+ * Returns one of: { state: 'missing' }, { state: 'ok' },
+ * { state: 'stale', consumerVersion, bundledVersion, appendZone },
+ * { state: 'forked', reason }.
+ *
+ * Exported for tests.
+ */
+export function classifyFile(file, bundleDir, cwd) {
+  const destAbs = join(cwd, file.dest);
+  let consumer;
+  try {
+    consumer = readFileSync(destAbs, 'utf8');
+  } catch {
+    return { state: 'missing' };
+  }
+
+  const markerIdx = findMarkerIndex(consumer);
+  if (markerIdx === -1) return { state: 'forked', reason: 'no canonical-end marker' };
+  if (markerIdx === -2) return { state: 'forked', reason: 'multiple canonical-end markers' };
+
+  const canonicalEnd = canonicalEndOffset(consumer);
+  const consumerCanonical = consumer.slice(0, canonicalEnd);
+  const appendZone = consumer.slice(canonicalEnd);
+
+  const consumerVersion = extractVersion(consumer);
+  if (!consumerVersion) {
+    return { state: 'forked', reason: 'no `kerf-skill-version` line' };
+  }
+
+  const cmp = compareSemver(consumerVersion, file.version);
+  if (cmp === 0) {
+    // Same version. Above-marker section should match the bundled sha256.
+    if (sha256(consumerCanonical) === file.sha256) return { state: 'ok' };
+    return { state: 'forked', reason: 'content above marker has been edited' };
+  }
+  if (cmp < 0) {
+    return {
+      state: 'stale',
+      consumerVersion,
+      bundledVersion: file.version,
+      appendZone,
+    };
+  }
+  // consumer is newer than bundled — treat as ok (consumer is ahead of installed kerfjs).
+  return { state: 'ok' };
+}
+
+function loadBundle(cwd) {
+  const manifestPath = resolveManifestPath(cwd);
+  if (!manifestPath) return null;
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch {
+    return null;
+  }
+  if (!manifest || !Array.isArray(manifest.files)) return null;
+  const bundleDir = dirname(manifestPath);
+  return { manifest, bundleDir };
+}
+
+function isTriggered(name, cwd) {
+  if (name === 'skill') return existsSync(join(cwd, '.claude'));
+  if (name === 'cursorrules') {
+    return existsSync(join(cwd, '.cursorrules')) || existsSync(join(cwd, '.cursor'));
+  }
+  return false;
+}
+
+/**
+ * Run the project-level check. Exported for tests; the rule wraps this
+ * with a once-per-lint-run guard.
+ */
+export function runCheck(cwd) {
+  const bundle = loadBundle(cwd);
+  if (!bundle) return null;
+  const results = [];
+  for (const file of bundle.manifest.files) {
+    if (!isTriggered(file.name, cwd)) continue;
+    results.push({ file, result: classifyFile(file, bundle.bundleDir, cwd) });
+  }
+  return { results, bundleDir: bundle.bundleDir };
+}
+
+/**
+ * Apply the `--fix` for one file: write the bundled canonical to the
+ * consumer's `dest`, appending the consumer's existing append-zone (if
+ * any). Exported for tests.
+ */
+export function applyFix(file, bundleDir, cwd, appendZone) {
+  const bundlePath = join(bundleDir, file.bundle.replace(/^ai\//, ''));
+  const canonical = readFileSync(bundlePath, 'utf8');
+  const dest = join(cwd, file.dest);
+  mkdirSync(dirname(dest), { recursive: true });
+  writeFileSync(dest, canonical + (appendZone || ''));
+}
+
+const meta = {
+  type: 'suggestion',
+  docs: {
+    description:
+      'Check that the kerf-app Claude Code skill / Cursor rules are installed and up-to-date against the canonical files bundled in `kerfjs/ai/`.',
+    url: 'https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/docs/rules/ai-assistant-configs.md',
+  },
+  schema: [
+    {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        claude: { type: 'boolean' },
+        cursor: { type: 'boolean' },
+      },
+    },
+  ],
+  messages: {
+    missing:
+      '{{tool}} drop-in is missing at `{{dest}}`. Run `eslint --fix` to install the bundled `kerfjs/{{bundle}}`. See docs/12-ai-assistant-configs.md.',
+    stale:
+      '{{tool}} drop-in at `{{dest}}` is stale (have {{consumerVersion}}, latest is {{bundledVersion}}). Run `eslint --fix` to update the canonical section above the `KERF-APP-CANONICAL-END` marker; your customizations below the marker are preserved.',
+    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.
+  fixable: 'code',
+};
+
+function create(context) {
+  return {
+    Program(node) {
+      if (CHECKED) return;
+      CHECKED = true;
+      const options = context.options[0] || {};
+      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 checked = runCheck(cwd);
+      CACHED_RESULT = checked;
+      if (!checked) return;
+
+      for (const { file, result } of checked.results) {
+        if (file.name === 'skill' && !claudeEnabled) continue;
+        if (file.name === 'cursorrules' && !cursorEnabled) continue;
+        if (result.state === 'ok') continue;
+
+        const tool = file.name === 'skill' ? 'Claude Code kerf-app skill' : 'Cursor kerf rules';
+        const bundle = file.bundle; // e.g. 'ai/skill.md'
+        const data = { tool, dest: file.dest, bundle };
+
+        if (result.state === 'missing') {
+          context.report({
+            node,
+            messageId: 'missing',
+            data,
+            fix() {
+              applyFix(file, checked.bundleDir, cwd, '');
+              return null;
+            },
+          });
+        } else if (result.state === 'stale') {
+          context.report({
+            node,
+            messageId: 'stale',
+            data: {
+              ...data,
+              consumerVersion: result.consumerVersion,
+              bundledVersion: result.bundledVersion,
+            },
+            fix() {
+              applyFix(file, checked.bundleDir, cwd, result.appendZone);
+              return null;
+            },
+          });
+        } else if (result.state === 'forked') {
+          context.report({
+            node,
+            messageId: 'forked',
+            data: { ...data, reason: result.reason },
+          });
+        }
+      }
+    },
+  };
+}
+
+export default { meta, create };

package/package.json

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