docs(#1867): ui-consideration-probe reference + docs-parity test (ADPT-02)

Reference doc mirrors edge-probe.md structure but links rather than re-argues;
states the MIXED-axis boundary (closed compiled shape-rooted subset here; open
UX subset - real-time/offline, a11y depth, i18n/RTL - prose-owned in
domain-probes.md). Docs-parity test pins doc taxonomy ids == code UI_TAXONOMY
ids and asserts disjointness from domain-probes.md topics (ADR-456
runtime-contract exemption, see #1867).
This commit is contained in:
Dave
2026-07-02 18:17:15 -04:00
parent cf92eb2cf3
commit 29120ea0aa
2 changed files with 130 additions and 0 deletions

View File

@@ -0,0 +1,57 @@
// allow-test-rule: runtime-contract-is-the-product (see #1867) — the rendered reference doc's taxonomy table IS the runtime contract; this pins its bijection to the code (docs-parity, ADR-456 exception matrix)
// Asserts gsd-core/references/ui-consideration-probe.md keeps its taxonomy id column in
// sync with the source-of-truth UI_TAXONOMY (built .cjs), and that the closed compiled
// taxonomy stays DISJOINT from the open-prose domain-probes.md bank (the mixed-axis boundary,
// ADPT-02). The comparison is on PARSED table ids and PARSED `##` headings, never a raw
// full-text substring match — a reformat that preserves the data does not fail; semantic drift does.
'use strict';
process.env.GSD_TEST_MODE = '1';
const { test, describe } = require('node:test');
const assert = require('node:assert/strict');
const fs = require('node:fs');
const path = require('node:path');
const uc = require(path.join(__dirname, '..', 'gsd-core', 'bin', 'lib', 'ui-consideration-probe.cjs'));
const docPath = path.join(__dirname, '..', 'gsd-core', 'references', 'ui-consideration-probe.md');
const domainPath = path.join(__dirname, '..', 'gsd-core', 'references', 'domain-probes.md');
// Extract the first-column ids from the `## Taxonomy` markdown table (skips the `id` header
// row and the `|----|` separator; an id is a lowercase-hyphen token).
function docTaxonomyIds(md) {
const section = md.split(/^## Taxonomy/m)[1].split(/^## /m)[0];
return section.split('\n')
.filter((l) => l.trim().startsWith('|'))
.map((l) => l.split('|')[1].trim())
.filter((c) => /^[a-z][a-z0-9-]*$/.test(c) && c !== 'id');
}
// The `##` topic headings of the open-prose bank (lower-cased).
function domainTopics(md) {
return md.split('\n')
.filter((l) => /^## /.test(l))
.map((l) => l.replace(/^## /, '').trim().toLowerCase());
}
describe('ui-consideration-probe doc/code parity (ADPT-02)', () => {
test('reference doc exists', () => {
assert.ok(fs.existsSync(docPath), `${docPath} must exist`);
});
test('doc taxonomy ids deep-equal the code UI_TAXONOMY ids, in order (doc == code)', () => {
const md = fs.readFileSync(docPath, 'utf8');
assert.deepEqual(docTaxonomyIds(md), uc.UI_TAXONOMY.map((c) => c.id));
});
test('no taxonomy id overlaps a domain-probes.md open-prose topic (closed/open disjointness)', () => {
const topics = domainTopics(fs.readFileSync(domainPath, 'utf8'));
for (const id of uc.UI_TAXONOMY.map((c) => c.id)) {
assert.ok(!topics.includes(id), `taxonomy id "${id}" must not overlap a domain-probes.md topic`);
}
});
test('the doc names domain-probes.md as the companion open-prose bank (links, does not duplicate)', () => {
const md = fs.readFileSync(docPath, 'utf8');
assert.match(md, /domain-probes\.md/);
});
});