c7a228e941
The CAP 1 slot shot doxa-vision-card, which is not a single element: it ships doxa-vision-card.instances.json with two instances, so discover.mjs types it parameterized and manifest.json records "parameterized" — capability 2. The same error had already been found and fixed in verify-5-capabilities.mjs, whose own comment records that it had been sampling cap-2 twice and cap-1 never. That fix landed in the gate and never reached the README: two artifacts encoding one fact, with nothing forcing agreement. Fixing one copy was not fixing the fact. all-people-groups is a genuine cap-1 — one .vue, no instances file, manifest type single. The README now also says what decides the tier, since the folder's apparent simplicity is the trap: doxa-vision-card looks like the lightest thing in the repo. check:capability-citations compares every README capability claim against the manifest, blocking in CI. Its first matcher used \Z, which is not JavaScript, so it matched zero sections while still reporting a citation count — a gate reporting a number it had not verified. It now splits on headings and the count reflects real matches.
129 lines
6.4 KiB
JavaScript
129 lines
6.4 KiB
JavaScript
#!/usr/bin/env node
|
|
/**
|
|
* check-capability-citations.mjs — a doc that names a bundle as "capability N" must match the manifest.
|
|
*
|
|
* THE BUG THIS EXISTS TO PREVENT (real, and found TWICE in two different artifacts)
|
|
* README.md captioned `doxa-vision-card` as "Capability 1 — a single-element plugin". It is not one:
|
|
* it ships doxa-vision-card.instances.json with TWO instances, so discover.mjs types it
|
|
* PARAMETERIZED and manifest.json records type "parameterized" — capability 2.
|
|
*
|
|
* ★ THE SAME ERROR HAD ALREADY BEEN FOUND AND FIXED SOMEWHERE ELSE. internal/verify-5-capabilities.mjs
|
|
* carries its own note: it "had been reporting '5/5 capability levels' while sampling cap-2 TWICE and
|
|
* cap-1 NEVER", and switched its cap-1 representative to all-people-groups. That fix landed in the
|
|
* GATE and never reached the README. Two artifacts encoding one fact, with nothing forcing agreement
|
|
* — the same shape as the .dsm-loading CSS pair, the writer-vs-client token path, and the doc that
|
|
* quotes package.json. Fixing one copy is not fixing the fact.
|
|
*
|
|
* WHY THE MANIFEST IS THE AUTHORITY
|
|
* `capability = 5 - PROFILE_TIER`, and the tier is what the BUILD computed from the folder's real
|
|
* shape (an *.instances.json makes it parameterized; a meta.json `type` declares tiers 3/4/5).
|
|
* manifest.json is that computation's output, so it cannot disagree with what ships. Prose can.
|
|
*
|
|
* ★ WHY A FOLDER'S APPARENT SIMPLICITY IS THE TRAP: doxa-vision-card looks like the lightest thing in
|
|
* the repo — no map engine, mounts instantly, one small .vue. Everything about it reads "cap-1"
|
|
* EXCEPT the one file that decides the tier. The gate looks at that file's consequence, not the vibe.
|
|
*
|
|
* WHAT IT CHECKS
|
|
* Every `![Capability N — ... (bundle-name)]` caption and every "CAP N" section that names a
|
|
* `plugin-designs/<bundle>/` path, resolved against manifest.json's declared type.
|
|
*
|
|
* NEGATIVE-TESTED: pointing the cap-1 caption back at doxa-vision-card makes this FAIL naming the
|
|
* bundle, its claimed tier and its real one; restoring all-people-groups returns PASS. A run that
|
|
* parses fewer than MIN_EXPECTED citations FAILS rather than passing vacuously.
|
|
*/
|
|
import { readFileSync, existsSync } from 'node:fs'
|
|
import { resolve, dirname, join } from 'node:path'
|
|
import { fileURLToPath } from 'node:url'
|
|
|
|
const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
|
|
const README = join(ROOT, 'README.md')
|
|
const MANIFEST = join(ROOT, 'public', 'doxa-maps', 'manifest.json')
|
|
|
|
if (!existsSync(README) || !existsSync(MANIFEST)) {
|
|
console.log('CAPABILITY-CITATIONS: SKIP — README.md or manifest.json not present.')
|
|
process.exit(0)
|
|
}
|
|
|
|
// capability = 5 - PROFILE_TIER (internal/plugin-gallery/discover.mjs). Machine key -> capability.
|
|
const CAP_OF_TYPE = {
|
|
'single': 1,
|
|
'parameterized': 2, 'preset-element': 2,
|
|
'monolithic': 3, 'multi-view-element': 3,
|
|
'nested-elements-mfe': 4, 'composite-element': 4,
|
|
'nested-mfe-spa': 5, 'app-shell': 5,
|
|
}
|
|
|
|
const mf = JSON.parse(readFileSync(MANIFEST, 'utf8'))
|
|
// A bundle's capability = the HIGHEST tier any of its profiles declares (a composite bundle may
|
|
// also ship its plain leaves; the bundle is cited by its top tier).
|
|
const capOfBundle = new Map()
|
|
for (const b of (mf.bundles || [])) {
|
|
let best = 0
|
|
for (const p of (b.profiles || [])) {
|
|
const c = CAP_OF_TYPE[p.type]
|
|
if (c && c > best) best = c
|
|
}
|
|
if (best) capOfBundle.set(b.bundle, best)
|
|
}
|
|
|
|
const doc = readFileSync(README, 'utf8')
|
|
|
|
// `` — the caption form that names its subject in parentheses.
|
|
const CAPTION = /!\[Capability\s+(\d)\s*[—-][^\]]*\(([a-z0-9-]+)\)\]/gi
|
|
|
|
// `### CAP N — …` down to the next `### ` heading, then every `plugin-designs/<bundle>/` inside it.
|
|
// ★ SPLIT RATHER THAN REGEX-SCAN. The first version used /^###\s+CAP\s+(\d)\b([\s\S]*?)(?=^###\s|\Z)/gim
|
|
// and matched ZERO sections — `\Z` is not JavaScript (that is Python/PCRE), and under the `m` flag
|
|
// the fallback `$` matches every LINE end, so each section body truncated to its first line. The
|
|
// run still printed "5 citation(s) parsed" because the count included entries the matcher never
|
|
// resolved. ★ A GATE THAT REPORTS A NUMBER IT DID NOT VERIFY is the exact failure this file's
|
|
// MIN_EXPECTED guard exists to prevent, so the guard has to count REAL matches.
|
|
const sections = doc.split(/^###\s+/m).slice(1)
|
|
|
|
const citations = []
|
|
for (const m of doc.matchAll(CAPTION)) citations.push({ claimed: +m[1], bundle: m[2], where: 'caption' })
|
|
for (const body of sections) {
|
|
const head = body.match(/^CAP\s+(\d)\b/)
|
|
if (!head) continue
|
|
const claimed = +head[1]
|
|
for (const p of body.matchAll(/plugin-designs\/([a-z0-9-]+)\//g)) {
|
|
citations.push({ claimed, bundle: p[1], where: `CAP ${claimed} section` })
|
|
}
|
|
}
|
|
|
|
// A matcher that finds almost nothing reads exactly like a clean pass (see check-quoted-scripts).
|
|
const MIN_EXPECTED = 5
|
|
console.log(`CAPABILITY-CITATIONS: ${citations.length} citation(s) parsed from README.md; ` +
|
|
`${capOfBundle.size} bundle(s) typed in manifest.json.`)
|
|
if (citations.length < MIN_EXPECTED) {
|
|
console.error(`\nCAPABILITY-CITATIONS: FAIL — only ${citations.length} parsed (expected >= ${MIN_EXPECTED}).`)
|
|
console.error(' The MATCHER is broken, not the README. Fix the regex before trusting this result.')
|
|
process.exit(1)
|
|
}
|
|
|
|
const wrong = [], unknown = []
|
|
for (const c of citations) {
|
|
const actual = capOfBundle.get(c.bundle)
|
|
if (actual === undefined) { unknown.push(c); continue }
|
|
if (actual !== c.claimed) wrong.push({ ...c, actual })
|
|
}
|
|
|
|
for (const u of unknown) {
|
|
console.log(` i not a built bundle, skipped: ${u.bundle} (cited as cap-${u.claimed} in ${u.where})`)
|
|
}
|
|
|
|
if (wrong.length) {
|
|
console.error(`\nCAPABILITY-CITATIONS: FAIL — ${wrong.length} citation(s) disagree with the manifest:`)
|
|
for (const w of wrong) {
|
|
console.error(` ✗ ${w.bundle} cited as CAPABILITY ${w.claimed} (${w.where}) ` +
|
|
`but the manifest types it capability ${w.actual}`)
|
|
}
|
|
console.error(
|
|
'\n The manifest is what the BUILD computed from the folder\'s real shape — an *.instances.json\n' +
|
|
' makes a bundle parameterized (cap-2) however simple it looks, and a meta.json `type` declares\n' +
|
|
' tiers 3/4/5. Prose can drift from that; the manifest cannot. Update the DOC.\n' +
|
|
' (This exact error was fixed once in verify-5-capabilities.mjs and never reached the README.)'
|
|
)
|
|
process.exit(1)
|
|
}
|
|
console.log('CAPABILITY-CITATIONS: PASS — every cited capability matches the manifest.')
|