config-audit/tests/scanners/plugin-health-scanner.test.mjs

import { describe, it } from 'node:test';
import assert from 'node:assert/strict';
import { resolve, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { resetCounter } from '../../scanners/lib/output.mjs';
import { scan, discoverPlugins } from '../../scanners/plugin-health-scanner.mjs';

const __dirname = fileURLToPath(new URL('.', import.meta.url));
const FIXTURES = resolve(__dirname, '../fixtures');
const TEST_PLUGIN = resolve(FIXTURES, 'test-plugin');
const BROKEN_PLUGIN = resolve(FIXTURES, 'broken-plugin');
const DUP_NAME = resolve(FIXTURES, 'duplicate-plugin-name');
const DUP_CMD = resolve(FIXTURES, 'duplicate-command-name');
const SHADOW = resolve(FIXTURES, 'plugin-shadow-folder');

describe('discoverPlugins', () => {
  it('discovers a single plugin when pointed at plugin dir', async () => {
    const plugins = await discoverPlugins(TEST_PLUGIN);
    assert.equal(plugins.length, 1);
    assert.ok(plugins[0].endsWith('test-plugin'));
  });

  it('discovers multiple plugins in parent dir', async () => {
    const plugins = await discoverPlugins(FIXTURES);
    // Should find test-plugin and broken-plugin (both have .claude-plugin/plugin.json)
    assert.ok(plugins.length >= 2, `Expected >=2, got ${plugins.length}`);
  });

  it('returns empty array for dir with no plugins', async () => {
    const plugins = await discoverPlugins(resolve(FIXTURES, 'empty-project'));
    assert.equal(plugins.length, 0);
  });
});

describe('scan on valid test-plugin', () => {
  it('returns ok status', async () => {
    resetCounter();
    const result = await scan(TEST_PLUGIN);
    assert.equal(result.scanner, 'PLH');
    assert.equal(result.status, 'ok');
  });

  it('finds commands and agents', async () => {
    resetCounter();
    const result = await scan(TEST_PLUGIN);
    assert.ok(result.files_scanned >= 1, 'Should scan at least 1 plugin');
    // Valid plugin should have few or no findings
    const criticals = result.findings.filter(f => f.severity === 'critical');
    assert.equal(criticals.length, 0, 'Valid plugin should have no critical findings');
  });

  it('no findings for missing plugin.json fields', async () => {
    resetCounter();
    const result = await scan(TEST_PLUGIN);
    // Anchor on PLH + a title-substring stable across humanizer rewrites.
    // Raw: "Missing required field in plugin.json: <field>". Humanized: "A plugin's manifest is missing a required field".
    const missingFields = result.findings.filter(f =>
      f.scanner === 'PLH' && /(missing.{0,40}(field|manifest))|(manifest.{0,40}missing)/i.test(f.title || '')
    );
    assert.equal(missingFields.length, 0, 'All required fields present in test-plugin');
  });

  it('no findings for missing CLAUDE.md sections', async () => {
    resetCounter();
    const result = await scan(TEST_PLUGIN);
    // Raw: "CLAUDE.md missing '<name>' section". Humanized: "A plugin's instructions file is missing a recommended section".
    const missingSections = result.findings.filter(f =>
      f.scanner === 'PLH' && /missing.{0,40}section/i.test(f.title || '')
    );
    assert.equal(missingSections.length, 0, 'All sections present in test-plugin CLAUDE.md');
  });
});

describe('scan on broken-plugin', () => {
  it('detects missing plugin.json fields', async () => {
    resetCounter();
    const result = await scan(BROKEN_PLUGIN);
    // CA-PLH-001 (description) and CA-PLH-002 (version) in broken-plugin.
    const missingFields = result.findings.filter(f =>
      f.scanner === 'PLH' && (f.id === 'CA-PLH-001' || f.id === 'CA-PLH-002')
    );
    assert.ok(missingFields.length >= 2, 'Should detect missing description and version');
  });

  it('detects missing CLAUDE.md', async () => {
    resetCounter();
    const result = await scan(BROKEN_PLUGIN);
    // CA-PLH-003 in broken-plugin = Missing CLAUDE.md.
    const missingMd = result.findings.filter(f => f.scanner === 'PLH' && f.id === 'CA-PLH-003');
    assert.equal(missingMd.length, 1, 'Should detect missing CLAUDE.md');
  });

  it('detects command without frontmatter', async () => {
    resetCounter();
    const result = await scan(BROKEN_PLUGIN);
    // CA-PLH-004 in broken-plugin = Command missing frontmatter.
    const noFrontmatter = result.findings.filter(f => f.scanner === 'PLH' && f.id === 'CA-PLH-004');
    assert.equal(noFrontmatter.length, 1, 'Should detect command without frontmatter');
  });

  it('detects agent missing required frontmatter fields', async () => {
    resetCounter();
    const result = await scan(BROKEN_PLUGIN);
    // CA-PLH-005 (missing model) and CA-PLH-006 (missing tools) in broken-plugin.
    const missingAgent = result.findings.filter(f =>
      f.scanner === 'PLH' && (f.id === 'CA-PLH-005' || f.id === 'CA-PLH-006')
    );
    // bad-agent.md has name+description but missing model and tools
    assert.ok(missingAgent.length >= 2, `Should detect missing model and tools, got ${missingAgent.length}: ${missingAgent.map(f => f.id).join(', ')}`);
  });
});

describe('scan with no plugins', () => {
  it('returns info finding for empty directory', async () => {
    resetCounter();
    const result = await scan(resolve(FIXTURES, 'empty-project'));
    assert.equal(result.findings.length, 1);
    // CA-PLH-001 in empty-project = No plugins found.
    assert.equal(result.findings[0].id, 'CA-PLH-001');
    assert.equal(result.findings[0].scanner, 'PLH');
    assert.equal(result.findings[0].severity, 'info');
  });
});

describe('cross-plugin command conflict detection', () => {
  it('scans fixtures dir and reports findings for all plugins', async () => {
    resetCounter();
    const result = await scan(FIXTURES);
    assert.equal(result.scanner, 'PLH');
    assert.ok(result.files_scanned >= 2, 'Should scan multiple plugins');
  });
});

describe('plugin namespace collision detection', () => {
  const COLLISION_RE = /namespace collision/i;

  it('flags two plugins that declare the same name', async () => {
    resetCounter();
    const result = await scan(DUP_NAME);
    const collisions = result.findings.filter(f =>
      f.scanner === 'PLH' && COLLISION_RE.test(f.title || '')
    );
    assert.equal(collisions.length, 1, `Expected exactly one namespace collision, got ${collisions.length}`);
    const f = collisions[0];
    assert.equal(f.severity, 'medium', 'Namespace collision is medium severity');
    assert.equal(f.category, 'plugin-hygiene');
    assert.ok(f.title.includes('dup'), `Title should name the colliding namespace: ${f.title}`);
    assert.ok(f.details && Array.isArray(f.details.namespaces), 'Should carry details.namespaces');
    assert.equal(f.details.namespaces.length, 2, 'Two plugins collide on "dup"');
    for (const ns of f.details.namespaces) {
      assert.equal(ns.name, 'dup');
      assert.ok(ns.source.startsWith('plugin:'), `source should be plugin-scoped: ${ns.source}`);
      assert.ok(ns.path, 'each namespace entry carries a path');
    }
  });

  it('excludes name-less plugins from the collision map', async () => {
    resetCounter();
    const result = await scan(DUP_NAME);
    // gamma + delta declare no name; they must NOT form an undefined/empty collision.
    const collisions = result.findings.filter(f =>
      f.scanner === 'PLH' && COLLISION_RE.test(f.title || '')
    );
    assert.equal(collisions.length, 1, 'Only the real "dup" collision; name-less plugins are ignored');
    assert.ok(
      !collisions.some(f => /undefined|""|''|null/.test(f.title)),
      'No collision finding for an empty/undefined name'
    );
  });

  it('does not flag a single plugin as a collision', async () => {
    resetCounter();
    const result = await scan(TEST_PLUGIN);
    const collisions = result.findings.filter(f =>
      f.scanner === 'PLH' && COLLISION_RE.test(f.title || '')
    );
    assert.equal(collisions.length, 0, 'A single plugin must not collide with itself');
  });
});

describe('cross-plugin command name ambiguity (COL-level)', () => {
  const CMD_RE = /used by multiple plugins/i;

  it('flags a command name shared across different plugin namespaces as low', async () => {
    resetCounter();
    const result = await scan(DUP_CMD);
    const amb = result.findings.filter(f => f.scanner === 'PLH' && CMD_RE.test(f.title || ''));
    assert.equal(amb.length, 1, `Expected one command-ambiguity finding, got ${amb.length}`);
    const f = amb[0];
    assert.equal(f.severity, 'low', 'Namespaced commands are ambiguity (low), not a hard conflict (high)');
    assert.equal(f.category, 'plugin-hygiene');
    assert.ok(f.title.includes('shared-cmd'), `Title should name the command: ${f.title}`);
    assert.ok(f.details && Array.isArray(f.details.namespaces), 'Should carry details.namespaces');
    assert.equal(f.details.namespaces.length, 2);
  });

  it('labels plugins by declared name, not folder basename', async () => {
    resetCounter();
    const result = await scan(DUP_CMD);
    const f = result.findings.find(x => x.scanner === 'PLH' && CMD_RE.test(x.title || ''));
    const sources = f.details.namespaces.map(n => n.source).sort();
    // Folders are one/two; declared names are plugin-one/plugin-two.
    assert.deepEqual(sources, ['plugin:plugin-one', 'plugin:plugin-two']);
  });

  it('does not emit a high-severity command conflict (legacy behavior removed)', async () => {
    resetCounter();
    const result = await scan(DUP_CMD);
    const high = result.findings.filter(f =>
      f.scanner === 'PLH' && /command name conflict/i.test(f.title || '') && f.severity === 'high'
    );
    assert.equal(high.length, 0, 'The old high-severity command-conflict finding must be gone');
  });

  it('does not flag a shared command WITHIN a colliding namespace (namespace-collision covers it)', async () => {
    resetCounter();
    // alpha + beta both declare name "dup" and both ship a "hello" command.
    const result = await scan(DUP_NAME);
    const amb = result.findings.filter(f => f.scanner === 'PLH' && CMD_RE.test(f.title || ''));
    assert.equal(amb.length, 0, 'Same namespace = one /dup:hello; the namespace collision is the right signal');
  });
});

describe('plugin-folder shadowing (CA-PLH-015)', () => {
  // Title set by the scanner: `plugin.json "<field>" path shadows the default <dir>/ folder`.
  const SHADOW_RE = /shadows the default/i;

  it('flags a manifest path that shadows the default commands/ folder', async () => {
    resetCounter();
    const result = await scan(SHADOW);
    const shadows = result.findings.filter(f => f.scanner === 'PLH' && SHADOW_RE.test(f.title || ''));
    assert.equal(shadows.length, 1, `Expected exactly one shadow finding, got ${shadows.length}: ${shadows.map(f => f.title).join(' | ')}`);
    const f = shadows[0];
    assert.equal(f.severity, 'medium', 'Shadowed default folder is medium (dead config)');
    assert.equal(f.category, 'plugin-hygiene');
    assert.ok(f.title.includes('commands'), `Title should name the shadowed field: ${f.title}`);
    assert.ok(/plugin\.json$/.test(f.file || ''), `Finding should point at plugin.json: ${f.file}`);
    assert.ok(f.details && f.details.field === 'commands', 'details.field should be the manifest key');
    assert.ok(f.details.ignoredDir === 'commands', `details.ignoredDir should be the default folder: ${f.details.ignoredDir}`);
  });

  it('does NOT flag a default folder addressed explicitly in the manifest array', async () => {
    resetCounter();
    // agents: ["./agents/", "./more-agents/"] addresses the default agents/ folder → no warning.
    const result = await scan(SHADOW);
    const agentShadows = result.findings.filter(f =>
      f.scanner === 'PLH' && SHADOW_RE.test(f.title || '') && /agents/.test(f.title || '')
    );
    assert.equal(agentShadows.length, 0, 'agents/ is addressed explicitly via ./agents/ → not shadowed');
  });

  it('does NOT flag skills (adds to default, not replace)', async () => {
    resetCounter();
    // skills: "./custom-skills/" ADDS to the default skills/ scan; both load → no shadow.
    const result = await scan(SHADOW);
    const skillShadows = result.findings.filter(f =>
      f.scanner === 'PLH' && SHADOW_RE.test(f.title || '') && /skills/.test(f.title || '')
    );
    assert.equal(skillShadows.length, 0, 'skills adds-to-default; never a shadow');
  });

  it('does NOT flag when the default folder is absent', async () => {
    resetCounter();
    // outputStyles: "./styles/" is declared, but there is no output-styles/ folder → nothing ignored.
    const result = await scan(SHADOW);
    const osShadows = result.findings.filter(f =>
      f.scanner === 'PLH' && SHADOW_RE.test(f.title || '') && /output-styles/.test(f.title || '')
    );
    assert.equal(osShadows.length, 0, 'No default output-styles/ folder exists → no shadow');
  });

  it('does NOT flag a plugin with no component-path keys', async () => {
    resetCounter();
    // test-plugin has commands/ and agents/ folders but declares no custom paths → nothing shadowed.
    const result = await scan(TEST_PLUGIN);
    const shadows = result.findings.filter(f => f.scanner === 'PLH' && SHADOW_RE.test(f.title || ''));
    assert.equal(shadows.length, 0, 'No manifest path keys → no shadow findings');
  });
});

describe('finding format', () => {
  it('findings have standard fields', async () => {
    resetCounter();
    const result = await scan(BROKEN_PLUGIN);
    assert.ok(result.findings.length > 0);
    const f = result.findings[0];
    assert.ok(f.id.startsWith('CA-PLH-'));
    assert.equal(f.scanner, 'PLH');
    assert.ok(['critical', 'high', 'medium', 'low', 'info'].includes(f.severity));
    assert.ok(f.title);
    assert.ok(f.description);
  });
});