chore(#2124): build canonical phase-id.cts surface (Phase 1 of #2121)

Add the ADR-2121-locked canonical functions to src/phase-id.cts. No consumer
behavior changes — Phases 2-4 migrate the divergent call sites against them.

- parsePhaseFromProse: anchored prose parser. A phase is returned only when the
  STATE.md "Phase:" field VALUE begins with a phase token, so
  "Milestone v0.5 complete" yields { phase: null } instead of "5" (the #2111
  root cause: the old unanchored \b(\d+..)\b mined the minor-version digit).
  Name extraction (parenthetical / em-dash tail, minus status words) unchanged.
- stripConfiguredProjectCodePrefix / isForeignPrefixedPhaseQuery: config-aware
  prefix policy. A foreign prefix (MEM-01 when the configured code is LKML) is
  preserved rather than collapsed to a bare numeric phase — the #2104 fix's
  canonical home (consumed later, outside this epic's critical path).
- roadmapPhaseLookupSources: moved from roadmap-parser.cts so phase-id.cts is
  the single owner of the exact -> numeric -> prefix-tolerant ordering.
  roadmap-parser.cts now imports it (behavior-identical); its two now-unused
  imports (phaseMarkdownRegexSourceExact, OPTIONAL_PROJECT_CODE_PREFIX_SOURCE)
  are dropped.

Tests: subject-named suites in tests/phase-id.test.cjs covering the ADR
boundary set (v0.5, v1.0, MEM-01, AB-29, bare 29, zero-padded 029) plus two
fast-check properties: the #2111 "Milestone vX.Y complete never yields a phase"
invariant and a parse/normalize property.

Extend-never-mutate: the 12 pre-existing phase-id.cts exports are unchanged.

Closes #2124
Refs #2121

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-07-09 16:13:06 -04:00
parent d8782f772a
commit bf25e0b435
3 changed files with 242 additions and 19 deletions

View File

@@ -22,6 +22,7 @@ const { test, describe } = require('node:test');
const assert = require('node:assert/strict');
const phaseId = require('../gsd-core/bin/lib/phase-id.cjs');
const fc = require('fast-check');
// ─── escapeRegex ─────────────────────────────────────────────────────────────
@@ -450,3 +451,153 @@ describe('getPhaseDirFromPhaseId', () => {
assert.ok(!result.endsWith('-'));
});
});
// ─── parsePhaseFromProse (#2121, anchored — fixes #2111) ─────────────────────
describe('parsePhaseFromProse', () => {
test('null / empty input yields null phase and name', () => {
assert.deepEqual(phaseId.parsePhaseFromProse(null), { phase: null, name: null });
assert.deepEqual(phaseId.parsePhaseFromProse(''), { phase: null, name: null });
});
test('#2111: a milestone-completion string carries no phase', () => {
assert.equal(phaseId.parsePhaseFromProse('Milestone v0.5 complete').phase, null);
assert.equal(phaseId.parsePhaseFromProse('Milestone v1.0 complete').phase, null);
assert.equal(phaseId.parsePhaseFromProse('Milestone v2.10 complete').phase, null);
});
test('#2111: a bare version token or stray numeral is not a phase', () => {
assert.equal(phaseId.parsePhaseFromProse('v0.5').phase, null);
assert.equal(phaseId.parsePhaseFromProse('v1.0').phase, null);
assert.equal(phaseId.parsePhaseFromProse('Fixed 12 bugs in v2.3').phase, null);
});
test('a genuine phase value (starting with the token) is parsed', () => {
assert.deepEqual(phaseId.parsePhaseFromProse('3 of 4 (Delta)'), { phase: '3', name: 'Delta' });
assert.deepEqual(phaseId.parsePhaseFromProse('3A — Delta'), { phase: '3A', name: 'Delta' });
assert.equal(phaseId.parsePhaseFromProse('12.1: Setup').phase, '12.1');
assert.equal(phaseId.parsePhaseFromProse('29 of 30').phase, '29');
assert.equal(phaseId.parsePhaseFromProse('029').phase, '029');
});
test('a leading project-code prefix is tolerated but not captured (bare token)', () => {
assert.equal(phaseId.parsePhaseFromProse('MEM-01 — Foo').phase, '01');
assert.equal(phaseId.parsePhaseFromProse('AB-29 of 30').phase, '29');
});
test('an optional leading "Phase" label is tolerated', () => {
assert.equal(phaseId.parsePhaseFromProse('Phase 3A — Delta').phase, '3A');
});
test('a status-word parenthetical is filtered from the name (preserved behavior)', () => {
// parenName wins over the em-dash tail; "executing" is a status word → name null.
assert.deepEqual(phaseId.parsePhaseFromProse('3A — Delta (executing)'), { phase: '3A', name: null });
assert.equal(phaseId.parsePhaseFromProse('3 (complete)').name, null);
});
});
// ─── stripConfiguredProjectCodePrefix (#2121 / #2104, config-aware) ───────────
describe('stripConfiguredProjectCodePrefix', () => {
test('#2104: a foreign prefix is preserved (not collapsed to a bare phase)', () => {
assert.equal(phaseId.stripConfiguredProjectCodePrefix('MEM-01', 'LKML'), 'MEM-01');
});
test('the configured prefix is stripped (case-insensitive)', () => {
assert.equal(phaseId.stripConfiguredProjectCodePrefix('CK-01', 'CK'), '01');
assert.equal(phaseId.stripConfiguredProjectCodePrefix('LKML-29', 'lkml'), '29');
assert.equal(phaseId.stripConfiguredProjectCodePrefix('AB-29', 'AB'), '29');
});
test('a value with no prefix is returned unchanged', () => {
assert.equal(phaseId.stripConfiguredProjectCodePrefix('01', 'CK'), '01');
assert.equal(phaseId.stripConfiguredProjectCodePrefix('029', 'CK'), '029');
});
test('an absent/empty projectCode preserves the value verbatim', () => {
assert.equal(phaseId.stripConfiguredProjectCodePrefix('MEM-01', ''), 'MEM-01');
assert.equal(phaseId.stripConfiguredProjectCodePrefix('MEM-01', null), 'MEM-01');
assert.equal(phaseId.stripConfiguredProjectCodePrefix('MEM-01', undefined), 'MEM-01');
});
});
// ─── isForeignPrefixedPhaseQuery (#2121 / #2056) ─────────────────────────────
describe('isForeignPrefixedPhaseQuery', () => {
test('a prefix that is not the configured code is foreign', () => {
assert.equal(phaseId.isForeignPrefixedPhaseQuery('MEM-01', 'LKML'), true);
});
test('the configured prefix is not foreign (case-insensitive)', () => {
assert.equal(phaseId.isForeignPrefixedPhaseQuery('CK-01', 'CK'), false);
assert.equal(phaseId.isForeignPrefixedPhaseQuery('ck-01', 'CK'), false);
});
test('a value with no prefix is never foreign', () => {
assert.equal(phaseId.isForeignPrefixedPhaseQuery('01', 'CK'), false);
assert.equal(phaseId.isForeignPrefixedPhaseQuery('29', 'AB'), false);
});
test('a prefixed query with no configured code is foreign; a bare one is not', () => {
assert.equal(phaseId.isForeignPrefixedPhaseQuery('MEM-01', ''), true);
assert.equal(phaseId.isForeignPrefixedPhaseQuery('MEM-01', null), true);
assert.equal(phaseId.isForeignPrefixedPhaseQuery('01', ''), false);
});
});
// ─── roadmapPhaseLookupSources (#2121, owned here after the move) ─────────────
describe('roadmapPhaseLookupSources', () => {
const PREFIX_TOLERANT = `${phaseId.OPTIONAL_PROJECT_CODE_PREFIX_SOURCE}0*29`;
test('a bare numeric query yields the numeric then prefix-tolerant sources', () => {
const sources = phaseId.roadmapPhaseLookupSources('29');
assert.deepEqual(sources, ['0*29', PREFIX_TOLERANT]);
});
test('the bare numeric source precedes the prefix-tolerant fallback', () => {
const sources = phaseId.roadmapPhaseLookupSources('29');
assert.ok(sources.indexOf('0*29') < sources.indexOf(PREFIX_TOLERANT));
});
test('a project-code-prefixed query adds the exact source first (3 sources)', () => {
const sources = phaseId.roadmapPhaseLookupSources('AB-29');
assert.equal(sources.length, 3);
assert.equal(sources[0], 'AB-29');
assert.ok(sources.includes('0*29'));
assert.ok(sources.includes(PREFIX_TOLERANT));
});
test('zero-padding is tolerated: 029 resolves the same sources as 29', () => {
assert.deepEqual(phaseId.roadmapPhaseLookupSources('029'), phaseId.roadmapPhaseLookupSources('29'));
});
test('sources are deduplicated', () => {
const sources = phaseId.roadmapPhaseLookupSources('29');
assert.equal(sources.length, new Set(sources).size);
});
});
// ─── #2121 property tests (fast-check) ───────────────────────────────────────
describe('phase-id canonical surface — properties', () => {
test('#2111 invariant: a "Milestone vX.Y complete" string never yields a phase', () => {
fc.assert(
fc.property(fc.nat(999), fc.nat(999), (major, minor) => {
return phaseId.parsePhaseFromProse(`Milestone v${major}.${minor} complete`).phase === null;
}),
);
});
test('parse↔normalize: a "N of M" prose value extracts N, and it normalizes stably', () => {
fc.assert(
fc.property(fc.integer({ min: 1, max: 9999 }), fc.integer({ min: 1, max: 9999 }), (n, m) => {
const parsed = phaseId.parsePhaseFromProse(`${n} of ${m}`);
return (
parsed.phase === String(n) &&
phaseId.normalizePhaseName(parsed.phase) === phaseId.normalizePhaseName(String(n))
);
}),
);
});
});