[quality] data overlays cannot patch a root-level JSON array, so catalog.json and projects-born.json are outside the e2e fixture mechanism #1086

Finding

tests/tools/e2e-data-fixtures.cjs is the project's documented way to put a
data shape in front of a component that reads @site/data/*.json at build
time. It cannot address a data file whose root is a JSON array, so two
such files are permanently outside the mechanism:

parentOf() (tests/tools/e2e-data-fixtures.cjs:122-147) rejects an array at
every step, so there is no dotted path that reaches into one. Probed directly
at dfbb892:

$ node -e "const f=require('./tests/tools/e2e-data-fixtures.cjs'); ..."
THROW {"description":"append to root array","append":{"":[...]}}
      -> probe: "" has no object to patch in the real data
THROW {"description":"append via numeric index","append":{"0.industries":[]}}
      -> probe: "0.industries" is not an object in the real data
THROW {"description":"set root index","set":{"0":{"id":"z"}}}
      -> probe: "0" has no object to patch in the real data

This is not an accident — tests/e2e-data-fixtures.test.mjs:85-91
("setting a leaf whose parent is an array is rejected") pins the behaviour. The
consequence for root-array files looks unintended, though, and is what this
issue is about.

What it costs

ArchitectureCard renders

// src/components/ReferenceArchitectures/index.js:66
{industries.join(' · ') || 'Reference architecture'}

Every one of the eight catalog entries carries a non-empty industries array
(adobe 3, allianz 2, cern-scientific-computing 2, colopl 1,
flipkart-chaos-engineering 3, swisscom-cloud-native-telco 2,
swisscom-kubernetes-service 4, zeiss 2), so the || fallback never
renders against shipped data, and the one mechanism for supplying the missing
shape cannot patch the file it lives in.

The fixture-docs instance added in #1083 does not help either:
ReferenceArchitectures takes no props and imports the catalog itself, so a
fixture MDX page cannot hand it different data.

Evidence and provenance

• Unit: npm run test:unit:coverage
  (TZ=UTC node tests/tools/coverage-report.mjs, node v26.10.0) run locally at
  dfbb892. src files 100.00% lines / 99.84% regions;
  src/components/ReferenceArchitectures/index.js is at 100%/100%. The only
  sub-100% file under src/ or scripts/ is
  scripts/lib/svg-active-content.mjs (97.67% regions, lines 457 465 475 637 —
  the four known-unreachable ?? '' fallbacks). The gap below is therefore
  e2e-only.
• E2E: CI artifact e2e-coverage id 11346609952, from run
  37313638186,
  job End-to-end coverage, branch quality/test-cncf-project-card-meta-e2e
  at d56a49e (base 900592b). report.txt:
  src/components/ReferenceArchitectures/index.js | 100.00 | 78.57 | | 13 17 22 34 66
  and src files | 100.00 | 81.29 | 2099/2099 lines | 378/465 regions.
  Line 66 is the fallback above. (Lines 13/17/22/34 are SyncStatus's
  document-level arms, which belong to [quality] e2e region union does not fold single-line '||' fallback arms across the real and variant builds, so correct variant tests lower the gate #1066, not here.)

Recommendation

Let an overlay address a record inside a root-level array, without weakening
the "every path must already exist" guarantee that makes a regenerated data
file fail the build instead of silently dropping its coverage.

Prefer patching an existing record over appending a new one: onBrokenLinks
is 'throw' (docusaurus.config.js:100), and ArchitectureCard links to
/architectures/<id>, so an appended catalog entry would need a matching page
under docs/architectures/ or it fails the build.

Positional indices (set: {"0.industries": []}) would work but are fragile —
data/architectures/catalog.json is regenerated by
npm run import:architectures and entry order is not stable. An
identifier-keyed form such as

{
  "description": "one architecture with no industries, so the eyebrow fallback renders",
  "setWhere": { "id=allianz": { "industries": [] } }
}

keeps the fail-loud property: the overlay names a record that must exist, and a
regenerated catalog that drops allianz fails the build rather than quietly
losing the branch.

Completion criteria

• An overlay can patch a record inside a data file whose root is a JSON array, failing loudly when the record it names is absent
• data/architectures/catalog.json and data/projects-born.json are both reachable by the mechanism
• tests/e2e-data-fixtures.test.mjs:85-91 is updated or complemented so the new form is pinned and leaf-under-array addressing stays rejected where it should be
• A spec drives ReferenceArchitectures line 66 and the region leaves the uncovered list

Coordination

• The change lands in tests/tools/e2e-data-fixtures.cjs and
  tests/e2e-data-fixtures.test.mjs. No open PR touches the .cjs module,
  but test: cover PeopleFreshness's no-data arms in the e2e coverage build #1034 and test: pin parentOf's empty-prefix fallback in the overlay machinery #1078 are both editing tests/e2e-data-fixtures.test.mjs.
  I have deliberately not opened a PR for that reason: anything I pushed
  would collide in that test file with two PRs already waiting on review.
  This should be picked up once test: cover PeopleFreshness's no-data arms in the e2e coverage build #1034 and test: pin parentOf's empty-prefix fallback in the overlay machinery #1078 land.
• Distinct from [quality] e2e region union does not fold single-line '||' fallback arms across the real and variant builds, so correct variant tests lower the gate #1066 and [quality] e2e region union still counts three demonstrably-executed single-line arms uncovered; their covered twin differs in START column, which #1066's proposed key would miss #1079, which are about region attribution in
  tests/tools/e2e-coverage-report.mjs. This one is about a shape the browser
  genuinely never renders.
• No workflow file is involved; --check-source-regions only needs re-deriving
  if the number moves past the floor.

Priority

• Impact: medium (one e2e region today, but it closes off the overlay mechanism for two data files entirely)
• Effort: medium

🐝 Hive Agent: quality | Instance: hosted-available-lke648397-260827-5n31 | SHA: dfbb892

— hive: agent=quality backend=copilot model=claude-opus-5 copilot=1.0.88