@dalzoubi/dev-agents-sync 1.0.26 → 2.0.1

package/tests/checkClaudeMd.test.mjs

@@ -0,0 +1,656 @@
+/**
+ * tests/checkClaudeMd.test.mjs
+ *
+ * Tests for CLAUDE.md routing-section drift detection in the `check` subcommand.
+ *
+ * The `check` command must detect drift in the fenced auto-route block that
+ * `init` / `update` inject into the consumer's CLAUDE.md.
+ *
+ * Fenced block format:
+ *   <!-- dev-agents:auto-route:start managed-by: dev-agents-sync vX.Y.Z -->
+ *   ...routing content from claude/skills/auto-route.md at the resolved version...
+ *   <!-- dev-agents:auto-route:end -->
+ *
+ * Success criteria (all must be RED until check.mjs gains CLAUDE.md logic):
+ *   1. exit 1 + CLAUDE.md named in drift report when fenced section is absent
+ *   2. exit 1 + CLAUDE.md named when fenced section is present but stale
+ *   3. exit 0 when fenced section is present and current
+ *   4. exit 1 when CLAUDE.md does not exist (absence = drift)
+ *   5. exit 1 when block is malformed (start marker present, end marker absent)
+ */
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  existsSync,
+  rmSync,
+  readdirSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runCheck } from '../src/commands/check.mjs';
+import { writeLockfile } from '../src/lockfile.mjs';
+import {
+  buildFencedBlock,
+  START_MARKER_PREFIX,
+  END_MARKER,
+} from '../src/claudeMd.mjs';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const FIXTURE_DIR = path.join(__dirname, 'fixtures', 'release-v1.0.0');
+
+// The CLI package version drives the version written into the start marker.
+const CLI_VERSION = JSON.parse(
+  readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'),
+).version;
+
+// Routing content used for the auto-route skill in the fixture fetcher.
+// Tests are anchored to this deterministic string so they never snapshot dates.
+const SAMPLE_ROUTING_CONTENT = '## Auto-routing\n\nRoute `fix` → `implement`.';
+
+// A routing content string that differs from SAMPLE_ROUTING_CONTENT, used to
+// simulate stale / updated content between CLI versions.
+const UPDATED_ROUTING_CONTENT = '## Auto-routing\n\nRoute `fix` → `implement`.\nRoute `test` → `test`.';
+
+// ---------------------------------------------------------------------------
+// Fixture helpers
+// ---------------------------------------------------------------------------
+
+function collectFiles(baseDir, currentDir, map, prefix) {
+  const entries = readdirSync(currentDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      collectFiles(baseDir, full, map, prefix);
+    } else {
+      const rel = path.relative(baseDir, full).replace(/\\/g, '/');
+      map[`${prefix}/${rel}`] = readFileSync(full, 'utf8');
+    }
+  }
+}
+
+function buildFixtureFileMap(targets = ['claude']) {
+  const map = {};
+  for (const t of targets) {
+    const targetDir = path.join(FIXTURE_DIR, t);
+    if (!existsSync(targetDir)) continue;
+    collectFiles(targetDir, targetDir, map, t);
+  }
+  return map;
+}
+
+/**
+ * Builds a fetcher that returns the standard fixture file map plus a synthetic
+ * `claude/skills/auto-route.md` with `routingContent`.
+ */
+function makeFixtureFetcherWithAutoRoute(routingContent = SAMPLE_ROUTING_CONTENT) {
+  return async (_repo, _tag, _token) => {
+    const base = buildFixtureFileMap(['claude']);
+    base['claude/skills/auto-route.md'] = routingContent;
+    return base;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Consumer-dir helpers
+// ---------------------------------------------------------------------------
+
+function makeTmpDir() {
+  return mkdtempSync(path.join(tmpdir(), 'das-check-claudemd-'));
+}
+
+/**
+ * Writes the lockfile and all managed `.claude/` files so that the check
+ * command sees them as fully in-sync. CLAUDE.md drift is the only variable
+ * under test in this file, so every other managed file must be written with
+ * content that exactly matches the corresponding fetcher output.
+ *
+ * The fetcher in these tests injects `claude/skills/auto-route.md` which
+ * check will resolve to `.claude/skills/auto-route.md`. That file must exist
+ * locally and match exactly; otherwise it would produce a spurious exit-1
+ * unrelated to the CLAUDE.md block being tested.
+ *
+ * `claudeMdContent` controls what (if anything) is written to CLAUDE.md:
+ *   - string  → writes that exact content to <consumerDir>/CLAUDE.md
+ *   - 'omit'  → does not create CLAUDE.md (CLAUDE.md is absent)
+ */
+function setupConsumerRepo(consumerDir, opts = {}) {
+  const {
+    resolvedVersion = '1.2.0',
+    targets = ['claude'],
+    claudeMdContent = 'omit',
+    // Content the fetcher will return for claude/skills/auto-route.md.
+    // Must match so the skills file does not appear as drifted itself.
+    routingContentForSkillsFile = SAMPLE_ROUTING_CONTENT,
+  } = opts;
+
+  writeLockfile(consumerDir, {
+    source: 'github:dalzoubi/dev-agents',
+    range: '^1',
+    resolvedVersion,
+    targets,
+    lastUpdated: '2026-04-01T00:00:00Z',
+  });
+
+  // Write all managed claude fixture files so the standard file-map check
+  // passes cleanly and CLAUDE.md drift is the only variable under test.
+  if (targets.includes('claude')) {
+    const agentsDir = path.join(consumerDir, '.claude', 'agents');
+    mkdirSync(agentsDir, { recursive: true });
+
+    writeFileSync(
+      path.join(agentsDir, 'define.md'),
+      readFileSync(path.join(FIXTURE_DIR, 'claude', 'agents', 'define.md'), 'utf8'),
+      'utf8',
+    );
+    writeFileSync(
+      path.join(agentsDir, 'test.md'),
+      readFileSync(path.join(FIXTURE_DIR, 'claude', 'agents', 'test.md'), 'utf8'),
+      'utf8',
+    );
+
+    const commandsDir = path.join(consumerDir, '.claude', 'commands');
+    mkdirSync(commandsDir, { recursive: true });
+    writeFileSync(
+      path.join(commandsDir, 'preflight.md'),
+      readFileSync(path.join(FIXTURE_DIR, 'claude', 'commands', 'preflight.md'), 'utf8'),
+      'utf8',
+    );
+
+    // Write .claude/skills/auto-route.md matching the fetcher's output so
+    // check does not report that file as drifted. Its content must equal
+    // whatever the fetcher returns for claude/skills/auto-route.md.
+    const skillsDir = path.join(consumerDir, '.claude', 'skills');
+    mkdirSync(skillsDir, { recursive: true });
+    writeFileSync(
+      path.join(skillsDir, 'auto-route.md'),
+      routingContentForSkillsFile,
+      'utf8',
+    );
+  }
+
+  // CLAUDE.md
+  if (typeof claudeMdContent === 'string' && claudeMdContent !== 'omit') {
+    writeFileSync(path.join(consumerDir, 'CLAUDE.md'), claudeMdContent, 'utf8');
+  }
+}
+
+// Convenience: build the "current" fenced block the check command should expect.
+function currentFencedBlock(routingContent = SAMPLE_ROUTING_CONTENT) {
+  return buildFencedBlock(CLI_VERSION, routingContent);
+}
+
+// ---------------------------------------------------------------------------
+// Criterion 4 — CLAUDE.md absent entirely → exit 1
+// ---------------------------------------------------------------------------
+
+describe('check — CLAUDE.md absent (no file) → exit 1', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+    // Do NOT write CLAUDE.md at all; all other managed files are in-sync.
+    setupConsumerRepo(consumerDir, { claudeMdContent: 'omit' });
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('exits 1 when CLAUDE.md does not exist', async () => {
+    // Precondition: ensure the file is genuinely absent.
+    const claudeMdPath = path.join(consumerDir, 'CLAUDE.md');
+    assert.ok(!existsSync(claudeMdPath), 'precondition: CLAUDE.md must not exist');
+
+    let exitCode;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcherWithAutoRoute(),
+        availableTags: ['v1.2.0'],
+      });
+      exitCode = 0;
+    } catch (err) {
+      exitCode = err.exitCode;
+    }
+
+    assert.equal(exitCode, 1, 'expected exit code 1 when CLAUDE.md is absent');
+  });
+
+  it('drift error names CLAUDE.md when the file is absent', async () => {
+    let errorMessage = '';
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcherWithAutoRoute(),
+        availableTags: ['v1.2.0'],
+      });
+    } catch (err) {
+      errorMessage = err.message ?? '';
+    }
+
+    assert.ok(
+      errorMessage.includes('CLAUDE.md'),
+      `drift error must name CLAUDE.md when the file is absent, got: ${errorMessage}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 1 — fenced block absent (CLAUDE.md exists but has no block) → exit 1
+// ---------------------------------------------------------------------------
+
+describe('check — CLAUDE.md exists but fenced block is absent → exit 1', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+    // Write a CLAUDE.md that has prose but no fenced block at all.
+    setupConsumerRepo(consumerDir, {
+      claudeMdContent: '# My Project\n\nThis is my CLAUDE.md. No routing section yet.',
+    });
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('exits 1 when CLAUDE.md exists but the fenced routing section is absent', async () => {
+    let exitCode;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcherWithAutoRoute(),
+        availableTags: ['v1.2.0'],
+      });
+      exitCode = 0;
+    } catch (err) {
+      exitCode = err.exitCode;
+    }
+
+    assert.equal(
+      exitCode,
+      1,
+      'expected exit code 1 when fenced routing section is absent from CLAUDE.md',
+    );
+  });
+
+  it('drift error names CLAUDE.md when the fenced block is absent', async () => {
+    let errorMessage = '';
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcherWithAutoRoute(),
+        availableTags: ['v1.2.0'],
+      });
+    } catch (err) {
+      errorMessage = err.message ?? '';
+    }
+
+    assert.ok(
+      errorMessage.includes('CLAUDE.md'),
+      `drift error must name CLAUDE.md when fenced block is absent, got: ${errorMessage}`,
+    );
+  });
+
+  it('drifted array on the thrown error includes CLAUDE.md', async () => {
+    let drifted;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcherWithAutoRoute(),
+        availableTags: ['v1.2.0'],
+      });
+    } catch (err) {
+      drifted = err.drifted;
+    }
+
+    assert.ok(
+      Array.isArray(drifted),
+      'expected err.drifted to be an array',
+    );
+    assert.ok(
+      drifted.some((d) => d.includes('CLAUDE.md')),
+      `expected err.drifted to include an entry mentioning CLAUDE.md, got: ${JSON.stringify(drifted)}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 2 — fenced block present but stale (wrong version or content) → exit 1
+// ---------------------------------------------------------------------------
+
+describe('check — CLAUDE.md fenced block is stale → exit 1', () => {
+  let consumerDir;
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('exits 1 when the block version is older than the current CLI version', async () => {
+    const staleBlock = buildFencedBlock('0.1.0', SAMPLE_ROUTING_CONTENT);
+    consumerDir = makeTmpDir();
+    setupConsumerRepo(consumerDir, {
+      claudeMdContent: `# My Project\n\n${staleBlock}\n`,
+    });
+
+    let exitCode;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcherWithAutoRoute(),
+        availableTags: ['v1.2.0'],
+      });
+      exitCode = 0;
+    } catch (err) {
+      exitCode = err.exitCode;
+    }
+
+    assert.equal(
+      exitCode,
+      1,
+      'expected exit code 1 when block version is stale (older than CLI version)',
+    );
+  });
+
+  it('drift error names CLAUDE.md when block version is stale', async () => {
+    const staleBlock = buildFencedBlock('0.1.0', SAMPLE_ROUTING_CONTENT);
+    consumerDir = makeTmpDir();
+    setupConsumerRepo(consumerDir, {
+      claudeMdContent: `# My Project\n\n${staleBlock}\n`,
+    });
+
+    let errorMessage = '';
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcherWithAutoRoute(),
+        availableTags: ['v1.2.0'],
+      });
+    } catch (err) {
+      errorMessage = err.message ?? '';
+    }
+
+    assert.ok(
+      errorMessage.includes('CLAUDE.md'),
+      `drift error must name CLAUDE.md when block version is stale, got: ${errorMessage}`,
+    );
+  });
+
+  it('exits 1 when the block routing content has changed (same version, different content)', async () => {
+    // Block has the current CLI version but uses outdated routing content.
+    const staleBlock = buildFencedBlock(CLI_VERSION, 'Old routing rules that have since changed.');
+    consumerDir = makeTmpDir();
+    // routingContentForSkillsFile must match what the fetcher returns so
+    // .claude/skills/auto-route.md itself is not the source of drift.
+    setupConsumerRepo(consumerDir, {
+      claudeMdContent: `# My Project\n\n${staleBlock}\n`,
+      routingContentForSkillsFile: UPDATED_ROUTING_CONTENT,
+    });
+
+    let exitCode;
+    try {
+      await runCheck(consumerDir, {
+        // Fetcher returns UPDATED_ROUTING_CONTENT — different from what's in the block.
+        fetcher: makeFixtureFetcherWithAutoRoute(UPDATED_ROUTING_CONTENT),
+        availableTags: ['v1.2.0'],
+      });
+      exitCode = 0;
+    } catch (err) {
+      exitCode = err.exitCode;
+    }
+
+    assert.equal(
+      exitCode,
+      1,
+      'expected exit code 1 when block routing content differs from current versioned content',
+    );
+  });
+
+  it('drifted array on the thrown error includes CLAUDE.md when block is stale', async () => {
+    const staleBlock = buildFencedBlock('0.1.0', SAMPLE_ROUTING_CONTENT);
+    consumerDir = makeTmpDir();
+    setupConsumerRepo(consumerDir, {
+      claudeMdContent: staleBlock,
+    });
+
+    let drifted;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcherWithAutoRoute(),
+        availableTags: ['v1.2.0'],
+      });
+    } catch (err) {
+      drifted = err.drifted;
+    }
+
+    assert.ok(
+      Array.isArray(drifted),
+      'expected err.drifted to be an array',
+    );
+    assert.ok(
+      drifted.some((d) => d.includes('CLAUDE.md')),
+      `expected err.drifted to include an entry mentioning CLAUDE.md, got: ${JSON.stringify(drifted)}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 3 — fenced block present and current → exit 0
+// ---------------------------------------------------------------------------
+
+describe('check — CLAUDE.md fenced block is current → exit 0', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+    // Write CLAUDE.md with the exact block check should expect.
+    const block = currentFencedBlock(SAMPLE_ROUTING_CONTENT);
+    setupConsumerRepo(consumerDir, {
+      claudeMdContent: `# My Project\n\n${block}\n`,
+    });
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('exits 0 when the fenced block version and content are current', async () => {
+    let exitCode = 0;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcherWithAutoRoute(),
+        availableTags: ['v1.2.0'],
+      });
+    } catch (err) {
+      exitCode = err.exitCode ?? 2;
+    }
+
+    assert.equal(
+      exitCode,
+      0,
+      'expected exit code 0 when fenced block is present and matches current versioned content',
+    );
+  });
+
+  it('returns { inSync: true } when the fenced block is current', async () => {
+    let result;
+    try {
+      result = await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcherWithAutoRoute(),
+        availableTags: ['v1.2.0'],
+      });
+    } catch (_err) {
+      // Should not throw — test the assertion below regardless.
+    }
+
+    assert.ok(
+      result && result.inSync === true,
+      `expected { inSync: true } when block is current, got: ${JSON.stringify(result)}`,
+    );
+  });
+
+  it('exit 0 holds even when CLAUDE.md has prose above the block', async () => {
+    // Re-setup with prose before and after the block.
+    rmSync(consumerDir, { recursive: true, force: true });
+    consumerDir = makeTmpDir();
+    const block = currentFencedBlock(SAMPLE_ROUTING_CONTENT);
+    const claudeMdContent = `# My Full Project\n\nSome existing prose.\n\n${block}\n\nTrailing notes.`;
+    setupConsumerRepo(consumerDir, { claudeMdContent });
+
+    let exitCode = 0;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcherWithAutoRoute(),
+        availableTags: ['v1.2.0'],
+      });
+    } catch (err) {
+      exitCode = err.exitCode ?? 2;
+    }
+
+    assert.equal(
+      exitCode,
+      0,
+      'expected exit code 0 when block is current (prose surrounding the block must not affect result)',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 5 — malformed block (start present, end missing) → exit 1
+// ---------------------------------------------------------------------------
+
+describe('check — CLAUDE.md has malformed block (start present, end absent) → exit 1', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+    // Write CLAUDE.md with a dangling start marker and no end marker.
+    const startMarker = `${START_MARKER_PREFIX}${CLI_VERSION} -->`;
+    const malformedContent = `# My Project\n\n${startMarker}\nRouting content with no closing marker.`;
+    setupConsumerRepo(consumerDir, { claudeMdContent: malformedContent });
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('exits 1 when the start marker is present but the end marker is missing', async () => {
+    let exitCode;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcherWithAutoRoute(),
+        availableTags: ['v1.2.0'],
+      });
+      exitCode = 0;
+    } catch (err) {
+      exitCode = err.exitCode;
+    }
+
+    assert.equal(
+      exitCode,
+      1,
+      'expected exit code 1 when start marker is present but end marker is missing (malformed block)',
+    );
+  });
+
+  it('drift error names CLAUDE.md for a malformed block', async () => {
+    let errorMessage = '';
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcherWithAutoRoute(),
+        availableTags: ['v1.2.0'],
+      });
+    } catch (err) {
+      errorMessage = err.message ?? '';
+    }
+
+    assert.ok(
+      errorMessage.includes('CLAUDE.md'),
+      `drift error must name CLAUDE.md for a malformed block, got: ${errorMessage}`,
+    );
+  });
+
+  it('drifted array on the thrown error includes CLAUDE.md for a malformed block', async () => {
+    let drifted;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcherWithAutoRoute(),
+        availableTags: ['v1.2.0'],
+      });
+    } catch (err) {
+      drifted = err.drifted;
+    }
+
+    assert.ok(
+      Array.isArray(drifted),
+      'expected err.drifted to be an array',
+    );
+    assert.ok(
+      drifted.some((d) => d.includes('CLAUDE.md')),
+      `expected err.drifted to include CLAUDE.md for malformed block, got: ${JSON.stringify(drifted)}`,
+    );
+  });
+
+  it('does not exit 2 (tooling error) for a malformed block — malformed is drift, not a crash', async () => {
+    let exitCode;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFixtureFetcherWithAutoRoute(),
+        availableTags: ['v1.2.0'],
+      });
+      exitCode = 0;
+    } catch (err) {
+      exitCode = err.exitCode;
+    }
+
+    assert.notEqual(
+      exitCode,
+      2,
+      'malformed block must be treated as drift (exit 1), not a tooling error (exit 2)',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Guard — CLAUDE.md check must not affect the tooling-error (exit 2) path
+// ---------------------------------------------------------------------------
+
+describe('check — CLAUDE.md drift does not interact with tooling errors (exit 2)', () => {
+  it('still exits 2 on fetcher auth failure regardless of CLAUDE.md state', async () => {
+    const consumerDir = makeTmpDir();
+    try {
+      // No CLAUDE.md — would normally be drift — but fetcher errors first.
+      setupConsumerRepo(consumerDir, { claudeMdContent: 'omit' });
+
+      const authFailFetcher = async () => {
+        const err = new Error('Authentication failed: bad credentials');
+        err.type = 'auth';
+        throw err;
+      };
+
+      let exitCode;
+      try {
+        await runCheck(consumerDir, {
+          fetcher: authFailFetcher,
+          availableTags: ['v1.2.0'],
+        });
+        exitCode = 0;
+      } catch (err) {
+        exitCode = err.exitCode;
+      }
+
+      assert.equal(
+        exitCode,
+        2,
+        'auth failure must produce exit code 2 even when CLAUDE.md is missing',
+      );
+    } finally {
+      rmSync(consumerDir, { recursive: true, force: true });
+    }
+  });
+});