feat(docs): phase 16 - the RunicNPC subgroup, its API carried in full and drift-checked

PLAN.md §16 phase 16, with the org lead's D72-D74 (count of record 74).

- Eight pages nested in the Rust group at /docs/rust/runicnpc/ (D72): the
  overview, Install RunicNPC, Commands, NPC profiles, NPC placements, Cost and
  caps, Profile fields (the one field reference the editor, rnpc.profile set,
  the data file and the API all share) and The API.
- The API page carries every call, hook and data shape (D62), in the site's
  own words, with no decision numbers and no per-call version history (D74).
  Signatures print from src/data/runicnpc.mjs through Signature.astro.
- checkReference.mjs gains two sections. Against docs main:runicnpc/API.md:
  the API version, 24 call and 10 hook signatures, and the field names of the
  profile, RunicNpc_List rows, placements, routes and owners (D73), plus
  exactly one <Signature> per call on api.mdx. Against runicnpc-rust
  main:plugin/RunicNPC.cs: console verbs, permissions, place options and
  config keys. Six planted drifts all failed before it was trusted.
- checkSidebar and checkTerms read nested sidebar groups via flatLabels().
- The Rust overview, Events zones and rewards, and Canonical documents link
  the new pages; the canonical documents gain the four runicnpc/ docs.

Both NPC admin screens were walked on the walk site first (D36); nothing was
saved. npm run verify is green.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY

scripts/checkReference.mjs

@@ -48,6 +48,19 @@ import {
   rustPluginConfig,
   rustEventKinds,
 } from '../src/data/reference.mjs';
+import {
+  runicnpcOwners,
+  runicnpcCalls,
+  runicnpcHooks,
+  runicnpcListKeys,
+  runicnpcPlacementKeys,
+  runicnpcRouteKeys,
+  runicnpcProfileFields,
+  runicnpcCommands,
+  runicnpcPermissions,
+  runicnpcPlaceOptions,
+  runicnpcConfig,
+} from '../src/data/runicnpc.mjs';
 
 const ROOT = fileURLToPath(new URL('..', import.meta.url));
 const platform = JSON.parse(readFileSync(path.join(ROOT, 'src/data/platform.json'), 'utf8'));
@@ -150,6 +163,196 @@ function frozenListOf(source, name) {
   return [...code.matchAll(/'([^'\n]+)'/g)].map((x) => x[1]);
 }
 
+/**
+ * One section of a Markdown document: from the line starting with `heading` to the next
+ * heading of the same or a higher level. Null when there is no such heading, which every
+ * caller reports — a section that silently vanished must not read as an empty one.
+ */
+function mdSection(md, heading) {
+  const lines = md.split(/\r?\n/);
+  const start = lines.findIndex((l) => l.startsWith(heading));
+  if (start < 0) return null;
+  const level = heading.match(/^#+/)[0].length;
+  const stop = new RegExp(`^#{1,${level}} `);
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (stop.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start + 1, end).join('\n');
+}
+
+/** The backticked names in the first cell of every table row of a section. */
+function firstCellNames(section) {
+  return section
+    .split('\n')
+    .filter((l) => l.startsWith('| `'))
+    .map((l) => [...l.split('|')[1].matchAll(/`([^`]+)`/g)].map((m) => m[1]));
+}
+
+const collapse = (s) => s.replace(/\s+/g, ' ').trim();
+
+/** The top-level keys of the first ```json block in a section. */
+function jsonKeysOf(section) {
+  const m = section?.match(/```json\s*\n([\s\S]*?)\n```/);
+  if (!m) return null;
+  try {
+    return Object.keys(JSON.parse(m[1]));
+  } catch {
+    return null;
+  }
+}
+
+async function checkRunicNpcApi(md) {
+  const hint = 'docs main:runicnpc/API.md';
+
+  // The version the specification describes, against the one platform.json quotes (and
+  // checkFacts holds to the plugin's own plugin.toml). Together they close the loop.
+  const version = Number(md.match(/\*\*API version (\d+)\*\*/)?.[1]);
+  if (version !== platform.runicnpc.api) {
+    fail('RunicNPC API version', `${hint} describes API ${version || '(none found)'}; platform.json says ${platform.runicnpc.api}`);
+  } else ok(`RunicNPC API version (${version})`);
+
+  // Calls: `### \`RunicNpc_X(params)\` → \`returns\`` headings, compared by whole signature.
+  const theirCalls = new Map(
+    [...md.matchAll(/^### `(RunicNpc_\w+)\(([^)]*)\)` → `([^`]+)`\s*$/gm)].map((m) => [m[1], collapse(`(${m[2]}) → ${m[3]}`)]),
+  );
+  const myCalls = new Map(Object.entries(runicnpcCalls).map(([n, c]) => [n, collapse(`(${c.params}) → ${c.returns}`)]));
+  compareSignatures('RunicNPC call', myCalls, theirCalls, hint);
+
+  // Hooks: the first cell of each row of "Hooks it raises".
+  const hooksSection = mdSection(md, '## Hooks it raises');
+  if (!hooksSection) fail('RunicNPC hooks', `no "## Hooks it raises" section in ${hint}`);
+  else {
+    const theirHooks = new Map(
+      [...hooksSection.matchAll(/^\| `(OnRunicNpc\w+)\(([^)]*)\)` \|/gm)].map((m) => [m[1], collapse(`(${m[2]})`)]),
+    );
+    const myHooks = new Map(Object.entries(runicnpcHooks).map(([n, h]) => [n, collapse(`(${h.params})`)]));
+    compareSignatures('RunicNPC hook', myHooks, theirHooks, hint);
+  }
+
+  // The data shapes, by field name (D73).
+  const shape = (label, heading, mine, read) => {
+    const section = mdSection(md, heading);
+    const theirs = section && read(section);
+    if (!theirs || theirs.length === 0) fail(label, `could not read the "${heading}" section of ${hint}`);
+    else compareSets(label, mine, theirs, `${hint} "${heading.replace(/^#+ /, '')}"`);
+  };
+
+  shape('RunicNPC owner', '## Owners', Object.keys(runicnpcOwners), (s) => firstCellNames(s).flat());
+  shape('RunicNpc_List key', '### `RunicNpc_List', Object.keys(runicnpcListKeys), (s) => firstCellNames(s).flat());
+
+  // A profile's fields. A cell may name several (`hurtByPlayers`, `hurtsPlayers`), and a bare
+  // name after a dotted one shares its prefix (`phases[].damageDealt`, `aimCone`).
+  shape(
+    'RunicNPC profile field',
+    '### A profile',
+    Object.values(runicnpcProfileFields).flatMap((group) => Object.keys(group)),
+    (s) =>
+      firstCellNames(s).flatMap(([first, ...rest]) => {
+        const prefix = first.includes('.') ? first.slice(0, first.lastIndexOf('.') + 1) : '';
+        return [first, ...rest.map((n) => (n.includes('.') ? n : prefix + n))];
+      }),
+  );
+
+  // A placement's keys: the example's, plus the optional ones its bullets introduce.
+  shape('RunicNPC placement key', '### A placement', Object.keys(runicnpcPlacementKeys), (s) => {
+    const keys = jsonKeysOf(s);
+    return keys && [...new Set([...keys, ...[...s.matchAll(/^- `(\w+)`/gm)].map((m) => m[1])])];
+  });
+  shape('RunicNPC route key', '### A route', Object.keys(runicnpcRouteKeys), jsonKeysOf);
+
+  // The page itself: every call has exactly one <Signature call="…" />, so "in full" is held
+  // by the build and not by whoever last edited api.mdx.
+  const page = readFileSync(path.join(ROOT, 'src/content/docs/docs/rust/runicnpc/api.mdx'), 'utf8');
+  const onPage = [...page.matchAll(/<Signature\s+call="(\w+)"/g)].map((m) => m[1]);
+  let covered = true;
+  for (const call of Object.keys(runicnpcCalls)) {
+    const n = onPage.filter((c) => c === call).length;
+    if (n !== 1) {
+      covered = false;
+      fail(`RunicNPC API page: ${call}`, `has ${n} <Signature call="${call}" /> on api.mdx — every call needs exactly one, with its prose`);
+    }
+  }
+  if (covered) ok(`RunicNPC API page covers every call (${onPage.length})`);
+}
+
+/** Compare name → signature maps: both directions by name, then each shared name by signature. */
+function compareSignatures(label, mine, theirs, hint) {
+  compareSets(label, [...mine.keys()], [...theirs.keys()], hint);
+  let same = true;
+  for (const [name, sig] of mine) {
+    if (theirs.has(name) && theirs.get(name) !== sig) {
+      same = false;
+      fail(`${label} ${name}`, `signature differs — here "${sig}", ${hint} "${theirs.get(name)}"`);
+    }
+  }
+  if (same) ok(`${label} signatures (${mine.size})`);
+}
+
+/** The text of a C# method, by brace counting from the first brace after its name. */
+function methodBody(source, name) {
+  const start = source.search(new RegExp(`\\b${name}\\s*\\(`));
+  if (start < 0) return null;
+  const open = source.indexOf('{', start);
+  let depth = 0;
+  for (let i = open; i < source.length; i++) {
+    if (source[i] === '{') depth++;
+    else if (source[i] === '}' && --depth === 0) return source.slice(open + 1, i);
+  }
+  return null;
+}
+
+function checkRunicNpcSource(cs) {
+  const hint = 'runicnpc-rust main:plugin/RunicNPC.cs';
+
+  // The verbs: every `rnpc.<verb>` console command. The chat command answers the same verbs.
+  compareSets(
+    'RunicNPC command',
+    [...new Set(Object.values(runicnpcCommands).flatMap((s) => Object.keys(s)).map((usage) => usage.split(' ')[0]))],
+    [...cs.matchAll(/\[ConsoleCommand\("rnpc\.(\w+)"\)\]/g)].map((m) => m[1]),
+    `${hint} [ConsoleCommand]`,
+  );
+
+  // A command's permission must be one the plugin registers.
+  const perms = [...cs.matchAll(/const\s+string\s+Perm\w+\s*=\s*"(runicnpc\.\w+)"/g)].map((m) => m[1]);
+  compareSets('RunicNPC permission', Object.keys(runicnpcPermissions), perms, `${hint} Perm constants`);
+  for (const [section, commands] of Object.entries(runicnpcCommands)) {
+    for (const [usage, c] of Object.entries(commands)) {
+      if (c.perm.startsWith('runicnpc.') && !perms.includes(c.perm)) {
+        fail(`RunicNPC command ${usage}`, `(${section}) needs "${c.perm}", which the plugin does not register`);
+      }
+    }
+  }
+
+  const options = methodBody(cs, 'ParseOptions');
+  if (!options) fail('RunicNPC place option', `could not find ParseOptions in ${hint}`);
+  else {
+    compareSets(
+      'RunicNPC place option',
+      Object.keys(runicnpcPlaceOptions),
+      [...options.matchAll(/case\s+"(\w+)":/g)].map((m) => m[1]),
+      `${hint} ParseOptions`,
+    );
+  }
+
+  // The config: `[JsonProperty("name")] public Type Field`, and a field whose type is another
+  // config class is a section, its keys written `section.key`.
+  const jsonKeys = (className, prefix = '') => {
+    const body = classBody(cs, className);
+    if (!body) return null;
+    return [...body.matchAll(/\[JsonProperty\("(\w+)"\)\]\s*public\s+(\w+)\s+\w+/g)].flatMap(([, key, type]) => {
+      const nested = /Config$/.test(type) ? jsonKeys(type, `${prefix}${key}.`) : null;
+      return nested ?? [`${prefix}${key}`];
+    });
+  };
+  const configKeys = jsonKeys('PluginConfig');
+  if (!configKeys) fail('RunicNPC.json', `could not find class PluginConfig in ${hint}`);
+  else compareSets('RunicNPC.json', Object.keys(runicnpcConfig), configKeys, `${hint} PluginConfig`);
+}
+
 async function run() {
   if (!TOKEN) {
     console.error('checkReference: GITEA_TOKEN is not set. This check cannot run anonymously.');
@@ -287,6 +490,21 @@ async function run() {
     }
   }
 
+  // ── 10. RunicNPC: the API, against its specification ──────────────────────
+  //
+  // PLAN.md §16, D62 and D73. The one place this site carries a contract in full rather than
+  // linking to it, so the one place it must be held to the contract most tightly: every call
+  // and hook by its whole signature, and every field name of every data shape, both ways.
+  // `docs` `main:runicnpc/API.md` is normative, so it is the authority, not the plugin source.
+  await checkRunicNpcApi(await raw('docs', 'runicnpc/API.md'));
+
+  // ── 11. RunicNPC: the commands, permissions, options and config ───────────
+  //
+  // Names, checked against the plugin's own source the way RunicGateway.json is (check 8):
+  // the console verbs it registers, the permissions it registers, the `key=` options
+  // `place` and `here` parse, and the JSON keys of its config classes.
+  checkRunicNpcSource(await raw('runicnpc-rust', 'plugin/RunicNPC.cs'));
+
   // ── Report ────────────────────────────────────────────────────────────────
   if (failures.length === 0) {
     console.log(`checkReference: ${checked.length} enumeration check(s) passed against their sources.`);