From 2990305f785cb9cf8fad302cd89aa6b34346ed63 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Thu, 25 Jun 2026 17:40:58 -0400 Subject: [PATCH] refactor(#1727): derive NON_CLAUDE_RUNTIMES from the capability registry (ADR-1239 Phase B) (#1728) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * refactor(#1727): derive NON_CLAUDE_RUNTIMES from the capability registry ADR-1239 Phase B (parent #1679). NON_CLAUDE_RUNTIMES was a hand-maintained 15-element literal whose own doc-comment said "keep in sync with bin/install.js and getDirName()" — a parallel source of truth that can drift from the capability registry. Derive it instead: Object.keys(capabilityRegistry.runtimes).filter(id => id !== 'claude').sort() The exported value is byte-identical to the old literal (the registry's runtimes key set minus claude is exactly the 15 entries), so there is no observable behavior change; the list can no longer drift from the registry. capability-registry.cjs is a committed, dependency-free data module (no cycle). Drift-guard test: golden-oracle deepEqual (non-circular) + a role-based cross-check from the registry metadata + every member must have a non-'.claude' getDirName branch (a registry runtime missing a getDirName branch now fails CI). Closes #1727 Co-Authored-By: Claude Opus 4.8 * chore(#1727): backfill changeset PR number (#1728) Co-Authored-By: Claude Opus 4.8 * fix(#1727): put docs-exempt marker on its own line so parse.cjs extracts it DOCS_EXEMPT_RE is line-anchored (^...$ + m flag); the marker only counts on its own line. It was appended to the end of the body text, so it was never extracted and docs-lint failed in CI (fail_docs_missing). Verified via direct parse.cjs extraction (docsExempt now non-empty, marker stripped from body). Co-Authored-By: Claude Opus 4.8 --------- Co-authored-by: Claude Opus 4.8 --- .changeset/kind-lynx-munch.md | 7 ++ src/runtime-artifact-conversion.cts | 18 ++--- ...aude-runtimes-registry-derivation.test.cjs | 81 +++++++++++++++++++ 3 files changed, 97 insertions(+), 9 deletions(-) create mode 100644 .changeset/kind-lynx-munch.md create mode 100644 tests/non-claude-runtimes-registry-derivation.test.cjs diff --git a/.changeset/kind-lynx-munch.md b/.changeset/kind-lynx-munch.md new file mode 100644 index 000000000..d9190ea41 --- /dev/null +++ b/.changeset/kind-lynx-munch.md @@ -0,0 +1,7 @@ +--- +type: Changed +pr: 1728 +--- +**Internal: derive the non-Claude runtime list from the capability registry** — `NON_CLAUDE_RUNTIMES` is now computed from the capability registry instead of a hand-maintained literal, so it can no longer drift from the per-runtime descriptors. No user-visible behavior change (the list is identical). + + diff --git a/src/runtime-artifact-conversion.cts b/src/runtime-artifact-conversion.cts index 77cb11e02..0ebfe5d13 100644 --- a/src/runtime-artifact-conversion.cts +++ b/src/runtime-artifact-conversion.cts @@ -23,6 +23,7 @@ import commandRoster = require('./command-roster.cjs'); const { readGsdCommandNames, transformContentToHyphen } = commandRoster; import runtimeNamePolicy = require('./runtime-name-policy.cjs'); const { getDirName } = runtimeNamePolicy; +import capabilityRegistry = require('./capability-registry.cjs'); // #1383: resolve GSD's version WITHOUT a top-level // `require('../../../package.json')`. That require ran at module load on every @@ -2199,16 +2200,15 @@ function computePathPrefix({ isGlobal, isOpencode, isWindowsHost: _isWindowsHost /** * Canonical list of every non-Claude runtime that gsd-core emits artifacts for. - * Exported so test files can import this single source of truth rather than - * maintaining divergent hand-rolled arrays (#1521). - * - * Keep in sync with the runtime flags in bin/install.js and getDirName(). + * DERIVED from the capability registry (ADR-1239 Phase B, #1679) — the registry's + * `runtimes` map is the single source of truth for runtime identity, so the + * non-Claude set is its key set minus 'claude'. This replaces a hand-maintained + * literal that had to be kept in sync with bin/install.js and getDirName(), and + * can no longer drift from the registry. Exported so tests import one source (#1521). */ -const NON_CLAUDE_RUNTIMES: string[] = [ - 'codex', 'opencode', 'kilo', 'gemini', 'copilot', 'antigravity', - 'cursor', 'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'kimi', - 'codebuddy', 'cline', -]; +const NON_CLAUDE_RUNTIMES: string[] = Object.keys(capabilityRegistry.runtimes) + .filter((id) => id !== 'claude') + .sort(); /** * #1521: Every non-Claude runtime resolves its own runtime identity from a diff --git a/tests/non-claude-runtimes-registry-derivation.test.cjs b/tests/non-claude-runtimes-registry-derivation.test.cjs new file mode 100644 index 000000000..50293358b --- /dev/null +++ b/tests/non-claude-runtimes-registry-derivation.test.cjs @@ -0,0 +1,81 @@ +'use strict'; +/** + * Drift-guard: NON_CLAUDE_RUNTIMES must always be derived from the capability + * registry. Verifies: + * 1. The exported constant equals a hardcoded golden expected list — a pinned + * oracle that catches BOTH formula bugs (derived value diverges from golden) + * AND unintended registry drift (adding/removing a runtime forces a + * deliberate golden-list update). + * 2. Every registry entry with role === 'runtime' and id !== 'claude' appears + * in NON_CLAUDE_RUNTIMES — a cross-check from a different angle than the + * production derivation formula. + * 3. Every member of NON_CLAUDE_RUNTIMES has an explicit getDirName branch that + * does not return '.claude' — guards against adding a runtime to the registry + * without teaching getDirName about it (ADR-1239 Phase B, #1679). + * + * Behavioral tests only: assert on returned values, no source-grep. + */ + +const { test } = require('node:test'); +const assert = require('node:assert/strict'); +const conversion = require('../gsd-core/bin/lib/runtime-artifact-conversion.cjs'); +const registry = require('../gsd-core/bin/lib/capability-registry.cjs'); +const runtimeNamePolicy = require('../gsd-core/bin/lib/runtime-name-policy.cjs'); + +const { NON_CLAUDE_RUNTIMES } = conversion; +const { getDirName } = runtimeNamePolicy; + +// Golden oracle: hardcoded sorted known-good list of all non-Claude runtimes. +// A pinned expected value in a TEST is correct — the test IS the oracle. +// Only PRODUCTION code should derive dynamically from the registry. +// If this list diverges from NON_CLAUDE_RUNTIMES, either the formula is wrong +// OR the registry changed — both require a deliberate golden-list update here. +const EXPECTED = [ + 'antigravity', 'augment', 'cline', 'codebuddy', 'codex', 'copilot', + 'cursor', 'gemini', 'hermes', 'kilo', 'kimi', 'opencode', 'qwen', + 'trae', 'windsurf', +]; + +test('NON_CLAUDE_RUNTIMES matches the golden expected set (sorted)', () => { + assert.deepEqual( + [...NON_CLAUDE_RUNTIMES], + EXPECTED, + `NON_CLAUDE_RUNTIMES diverged from golden list.\n` + + ` actual: [${[...NON_CLAUDE_RUNTIMES].join(', ')}]\n` + + ` expected: [${EXPECTED.join(', ')}]`, + ); + // Explicit readability assertion: 'claude' must never appear. + assert.ok( + !NON_CLAUDE_RUNTIMES.includes('claude'), + 'NON_CLAUDE_RUNTIMES must not contain "claude"', + ); +}); + +test('every registry-declared runtime except claude is present in NON_CLAUDE_RUNTIMES', () => { + // Cross-check from a DIFFERENT angle than the production derivation formula: + // iterate registry entries by their role field rather than by Object.keys().filter(). + // This catches a case where a runtime is added to the registry with role==='runtime' + // but is somehow excluded from NON_CLAUDE_RUNTIMES by a formula bug. + for (const [id, entry] of Object.entries(registry.runtimes)) { + if (entry.role === 'runtime' && id !== 'claude') { + assert.ok( + NON_CLAUDE_RUNTIMES.includes(id), + `Registry declares runtime '${id}' (role==='runtime') but it is missing from NON_CLAUDE_RUNTIMES`, + ); + } + } +}); + +// Forward direction (registry → getDirName coverage) is the load-bearing guard: +// the registry is the authoritative runtime source, so every member of +// NON_CLAUDE_RUNTIMES must have an explicit getDirName branch. +test('DRIFT GUARD: every registry-declared non-Claude runtime has an explicit getDirName branch (not .claude)', () => { + for (const rt of NON_CLAUDE_RUNTIMES) { + const dir = getDirName(rt); + assert.notEqual( + dir, + '.claude', + `getDirName('${rt}') returned '.claude' — runtime '${rt}' is in the registry but missing an explicit getDirName branch`, + ); + } +});