fix: enforce architecture documentation contracts

scripts/verify-portal.mjs

@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict';
 import {existsSync, readFileSync, readdirSync} from 'node:fs';
 import {join} from 'node:path';
+import {XMLValidator} from 'fast-xml-parser';
 
 const root = process.cwd();
 const read = (path) => readFileSync(join(root, path), 'utf8');
@@ -66,13 +67,14 @@ for (const route of ['/', 'architecture-high-level', 'projects', 'teams', 'membe
 }
 
 const architectureSidebar = read('sidebars/architecture-high-level.ts');
-const architectureItems = ['Context', 'Overview', 'Overview Channels', 'Overview Repositories'];
-let architectureCursor = -1;
-for (const label of architectureItems) {
-  const next = architectureSidebar.indexOf(`label: '${label}'`, architectureCursor + 1);
-  assert.ok(next > architectureCursor, `Architecture High Level sidebar is missing or out of order: ${label}`);
-  architectureCursor = next;
-}
+const architectureEntries = [...architectureSidebar.matchAll(/\{type:\s*'doc',\s*id:\s*'([^']+)',\s*label:\s*'([^']+)'\}/g)]
+  .map((match) => ({id: match[1], label: match[2]}));
+assert.deepEqual(architectureEntries, [
+  {id: 'context', label: 'Context'},
+  {id: 'overview', label: 'Overview'},
+  {id: 'overview-channels', label: 'Overview Channels'},
+  {id: 'overview-repositories', label: 'Overview Repositories'},
+], 'Architecture High Level sidebar must contain exactly the four requested documents in order');
 const architecturePages = {
   context: read('docs/architecture-high-level/context.mdx'),
   overview: read('docs/architecture-high-level/overview.mdx'),
@@ -92,6 +94,8 @@ for (const [name, markers] of Object.entries({
   'repositories.drawio': ['CORP V1 — ORGANIZATIONS, REPOSITORIES & DELIVERY', 'PROJECT ORGANIZATION', 'SKILLS ORGANIZATION', 'GITEA ACTIONS'],
 })) {
   const diagram = read(`docs/architecture-high-level/diagrams/${name}`);
+  const xmlResult = XMLValidator.validate(diagram);
+  assert.equal(xmlResult, true, `${name} is malformed XML: ${JSON.stringify(xmlResult)}`);
   assert.match(diagram, /<mxfile[\s>]/, `${name} is not a Draw.io source file`);
   for (const marker of markers) assert.ok(diagram.includes(marker), `${name} is missing: ${marker}`);
 }