@bonesofspring/ai-rules 0.2.22 → 0.2.24

package/scripts/check-mavis-adapter-map.mjs

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+/**
+ * Validate presets/mavis/<stack>/adapter-map.json against architecture §3.5.
+ *
+ * Usage:
+ *   node scripts/check-mavis-adapter-map.mjs
+ *   node scripts/check-mavis-adapter-map.mjs --stack next
+ *   node scripts/check-mavis-adapter-map.mjs --self-test
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.join(scriptDirectory, '..');
+const presetsRoot = path.join(packageRoot, 'presets');
+const fixtureDirectory = path.join(scriptDirectory, 'fixtures', 'mavis-adapter-map');
+
+const DISPOSITIONS = new Set([
+  'copy',
+  'transform',
+  'embed-entry',
+  'omit',
+  'fallback',
+]);
+const LOAD_MODES = new Set([
+  'root-entry',
+  'referenced',
+  'native-skill',
+  'native-team',
+  'manual',
+  'not-installed',
+]);
+const PLATFORM_ONLY = new Set(['adapter-map.json']);
+
+function walkFiles(root) {
+  if (!fs.existsSync(root)) {
+    return [];
+  }
+  const files = [];
+  const visit = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        visit(full);
+      } else if (entry.isFile()) {
+        files.push(path.relative(root, full).split(path.sep).join('/'));
+      }
+    }
+  };
+  visit(root);
+  return files.sort();
+}
+
+function sha256(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+function sourceRevision(cursorRoot, mappedSources) {
+  const parts = mappedSources.map((rel) => {
+    const content = fs.readFileSync(path.join(cursorRoot, rel), 'utf8');
+    return `${rel}\t${sha256(content)}`;
+  });
+  parts.sort();
+  return sha256(parts.join('\n'));
+}
+
+export function validateAdapterMap({
+  cursorRoot,
+  mavisRoot,
+  adapterMap,
+  allowMissingMavisDir = false,
+}) {
+  const failures = [];
+  const fail = (message) => {
+    failures.push(message);
+  };
+
+  if (adapterMap === null || typeof adapterMap !== 'object' || Array.isArray(adapterMap)) {
+    return ['adapter-map must be a JSON object'];
+  }
+  if (adapterMap.schemaVersion !== 1) {
+    fail('schemaVersion must be 1');
+  }
+  if (adapterMap.platform !== 'mavis') {
+    fail('platform must be "mavis"');
+  }
+  if (typeof adapterMap.stack !== 'string' || adapterMap.stack.length === 0) {
+    fail('stack must be a non-empty string');
+  }
+  if (adapterMap.semanticSource !== `cursor/${adapterMap.stack}`) {
+    fail(`semanticSource must be "cursor/${adapterMap.stack}"`);
+  }
+  if (!Array.isArray(adapterMap.entries)) {
+    fail('entries must be an array');
+    return failures;
+  }
+
+  for (const [index, item] of adapterMap.entries.entries()) {
+    if (!item || typeof item !== 'object') {
+      fail(`entries[${index}] must be an object`);
+      continue;
+    }
+    if (typeof item.source !== 'string' || !item.source) {
+      fail(`entries[${index}].source is required`);
+    }
+    if (item.target !== null && (typeof item.target !== 'string' || !item.target)) {
+      fail(`entries[${index}].target must be a string or null`);
+    }
+    if (typeof item.category !== 'string' || !item.category) {
+      fail(`entries[${index}].category is required`);
+    }
+    if (!DISPOSITIONS.has(item.disposition)) {
+      fail(`entries[${index}].disposition is invalid`);
+    }
+    if (!LOAD_MODES.has(item.loadMode)) {
+      fail(`entries[${index}].loadMode is invalid`);
+    }
+    if (typeof item.reason !== 'string' || !item.reason.trim()) {
+      fail(`entries[${index}].reason is required`);
+    }
+    if (item.target === null && item.disposition !== 'omit' && item.disposition !== 'fallback') {
+      fail(`entries[${index}] null target requires omit or fallback`);
+    }
+    if (typeof item.source === 'string' && item.source.split(/[\\/]/).includes('claude')) {
+      fail(`entries[${index}] must not derive from Claude`);
+    }
+  }
+
+  const cursorFiles = walkFiles(cursorRoot).filter(
+    (rel) => path.basename(rel) !== 'README.md',
+  );
+  const mapped = adapterMap.entries.map((item) => item.source);
+  const mappedSet = new Set(mapped);
+  if (mapped.length !== mappedSet.size) {
+    fail('adapter-map has duplicate source entries');
+  }
+  for (const source of cursorFiles) {
+    if (!mappedSet.has(source)) {
+      fail(`unmapped Cursor source: ${source}`);
+    }
+  }
+  for (const source of mappedSet) {
+    if (!cursorFiles.includes(source)) {
+      fail(`adapter-map source missing from Cursor tree: ${source}`);
+    }
+  }
+
+  const expectedRevision = sourceRevision(cursorRoot, cursorFiles);
+  if (adapterMap.sourceRevision !== expectedRevision) {
+    fail('sourceRevision does not match Cursor next digest');
+  }
+
+  if (!fs.existsSync(mavisRoot)) {
+    if (!allowMissingMavisDir) {
+      fail(`missing Mavis tree ${mavisRoot}`);
+    }
+    return failures;
+  }
+
+  const mavisFiles = walkFiles(mavisRoot);
+  const targets = new Set(
+    adapterMap.entries.filter((item) => item.target).map((item) => item.target),
+  );
+  for (const item of adapterMap.entries) {
+    if (item.target && !mavisFiles.includes(item.target)) {
+      fail(`mapped target missing: ${item.target}`);
+    }
+    if (item.target && item.source) {
+      const sourceAbs = path.join(cursorRoot, item.source);
+      const targetAbs = path.join(mavisRoot, item.target);
+      if (fs.existsSync(sourceAbs) && fs.existsSync(targetAbs)) {
+        const sourceText = fs.readFileSync(sourceAbs, 'utf8');
+        const targetText = fs.readFileSync(targetAbs, 'utf8');
+        const marker = sourceText.match(/<!--\s*shared-core:\s*([^\s>]+)\s*-->/);
+        if (marker && !targetText.includes(`<!-- shared-core: ${marker[1]} -->`)) {
+          fail(`${item.target} dropped shared-core marker ${marker[1]}`);
+        }
+      }
+    }
+  }
+
+  for (const file of mavisFiles) {
+    if (PLATFORM_ONLY.has(file) || path.basename(file) === 'README.md') {
+      continue;
+    }
+    if (!targets.has(file)) {
+      fail(`orphan Mavis file: ${file}`);
+    }
+  }
+
+  return failures;
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function printFailures(label, failures) {
+  for (const failure of failures) {
+    console.error(`FAIL ${label}: ${failure}`);
+  }
+}
+
+function checkLive(stack) {
+  const cursorRoot = path.join(presetsRoot, 'cursor', stack);
+  const mavisRoot = path.join(presetsRoot, 'mavis', stack);
+  const mapPath = path.join(mavisRoot, 'adapter-map.json');
+  if (!fs.existsSync(mapPath)) {
+    return [`missing ${path.relative(packageRoot, mapPath)}`];
+  }
+  return validateAdapterMap({
+    cursorRoot,
+    mavisRoot,
+    adapterMap: readJson(mapPath),
+  });
+}
+
+function runSelfTest() {
+  let failed = 0;
+  const cases = [
+    { name: 'valid', expectFail: false },
+    { name: 'invalid-unmapped', expectFail: true },
+  ];
+  for (const testCase of cases) {
+    const root = path.join(fixtureDirectory, testCase.name);
+    const failures = validateAdapterMap({
+      cursorRoot: path.join(root, 'cursor'),
+      mavisRoot: path.join(root, 'mavis'),
+      adapterMap: readJson(path.join(root, 'mavis', 'adapter-map.json')),
+    });
+    const didFail = failures.length > 0;
+    if (didFail !== testCase.expectFail) {
+      failed += 1;
+      console.error(
+        `FAIL self-test ${testCase.name}: expected ${
+          testCase.expectFail ? 'invalid' : 'valid'
+        }`,
+      );
+      printFailures(testCase.name, failures);
+    } else {
+      console.log(
+        `ok self-test ${testCase.name} (${didFail ? 'invalid' : 'valid'})`,
+      );
+    }
+  }
+  return failed;
+}
+
+function parseArgs(argv) {
+  const options = { stack: 'next', selfTest: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--self-test') {
+      options.selfTest = true;
+    } else if (arg === '--stack') {
+      options.stack = argv[index + 1];
+      index += 1;
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+  return options;
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  let exitCode = 0;
+  if (options.selfTest) {
+    if (runSelfTest() !== 0) {
+      exitCode = 1;
+    }
+  }
+  if (!options.selfTest || exitCode === 0) {
+    const failures = checkLive(options.stack);
+    if (failures.length > 0) {
+      printFailures(`mavis/${options.stack}`, failures);
+      exitCode = 1;
+    } else {
+      console.log(`ok presets/mavis/${options.stack}/adapter-map.json`);
+    }
+  }
+  process.exit(exitCode);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`FAIL: ${error.message}`);
+    process.exit(1);
+  }
+}

package/scripts/check-mavis-local-overlay.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * Isolated Mavis overlay check. Does not invent alwaysApply / paths: semantics.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadReleasedMavisStacks } from './lib/discover-hooks.mjs';
+
+const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
+const presetsRoot = path.join(scriptDirectory, '..', 'presets');
+const ACK = 'Using .ai.local: <rule-name>';
+const POINTER = 'docs/LOCAL-OVERLAY.md';
+const PROBE = 'ls -la .ai.local';
+
+const stacks = loadReleasedMavisStacks(presetsRoot);
+if (stacks.length === 0) {
+  console.log('ok mavis local-overlay: no released stacks');
+  process.exit(0);
+}
+
+let failed = 0;
+for (const stack of stacks) {
+  const root = path.join(presetsRoot, 'mavis', stack);
+  const files = [
+    path.join(root, 'REPO_AGENTS.md'),
+    path.join(root, 'rules', 'ai-local-overlay.md'),
+  ];
+  for (const filePath of files) {
+    if (!fs.existsSync(filePath)) {
+      console.error(`FAIL missing ${path.relative(presetsRoot, filePath)}`);
+      failed += 1;
+      continue;
+    }
+    const text = fs.readFileSync(filePath, 'utf8');
+    const label = path.relative(presetsRoot, filePath);
+    if (!text.includes(POINTER)) {
+      console.error(`FAIL ${label}: missing ${POINTER}`);
+      failed += 1;
+    }
+    if (filePath.endsWith('ai-local-overlay.md') && !text.includes(ACK)) {
+      console.error(`FAIL ${label}: missing acknowledgement format`);
+      failed += 1;
+    }
+    if (filePath.endsWith('ai-local-overlay.md') && !text.includes(PROBE)) {
+      console.error(`FAIL ${label}: missing probe command`);
+      failed += 1;
+    }
+    if (filePath.endsWith('REPO_AGENTS.md') && !text.includes('Local overlay')) {
+      console.error(`FAIL ${label}: missing Local overlay section`);
+      failed += 1;
+    }
+  }
+}
+
+process.exit(failed === 0 ? 0 : 1);