feat(plh): flag plugin namespace collisions (same declared name)

Two plugins that declare the same `name` in plugin.json collapse into one
component namespace (/name:command, name:skill, agent "name"). Resolution
between two installed same-name plugins is undocumented, so one plugin's
commands/skills/agents are silently shadowed and unreachable. PLH now flags
this at medium severity, keying on the declared `name` (not folder basename,
via new declaredName on scanSinglePlugin) with a COL-shaped details.namespaces
payload. Name-less plugins are excluded from the collision map.

Search-first (code.claude.com/docs/en/plugins): plugin components are
namespaced by the declared name, so a plugin component can never shadow a
user/project one — only a same-name collision loses components. This refutes
the original "plugin vs user vs project shadowing" framing in the backlog.

Adds humanizer pattern, fixture (duplicate-plugin-name: 2 colliding + 2
name-less), and 3 tests. Suite 929->932. self-audit A 97 / A 100, scanners 13.
This commit is contained in:
Kjell Tore Guttormsen 2026-06-19 15:13:19 +02:00
commit c6c5f17752
11 changed files with 182 additions and 3 deletions

View file

@ -0,0 +1,5 @@
{
"name": "dup",
"description": "Alpha plugin that declares the namespace 'dup'",
"version": "1.0.0"
}

View file

@ -0,0 +1,12 @@
# Dup Plugin
## Commands
| Command | Description |
|---------|-------------|
| `/dup:hello` | say hello |
## Agents
(none)
## Hooks
(none)

View file

@ -0,0 +1,5 @@
{
"name": "dup",
"description": "Beta plugin that declares the SAME namespace 'dup' — collides with alpha",
"version": "2.0.0"
}

View file

@ -0,0 +1,12 @@
# Dup Plugin
## Commands
| Command | Description |
|---------|-------------|
| `/dup:hello` | say hello |
## Agents
(none)
## Hooks
(none)

View file

@ -0,0 +1,4 @@
{
"description": "Plugin with NO name field — must be excluded from the namespace-collision map",
"version": "1.0.0"
}

View file

@ -0,0 +1,4 @@
{
"description": "Plugin with NO name field — must be excluded from the namespace-collision map",
"version": "1.0.0"
}

View file

@ -9,6 +9,7 @@ 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');
describe('discoverPlugins', () => {
it('discovers a single plugin when pointed at plugin dir', async () => {
@ -128,6 +129,53 @@ describe('cross-plugin command conflict detection', () => {
});
});
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('finding format', () => {
it('findings have standard fields', async () => {
resetCounter();