refactor(xref/headings): pre-index headings by ID at scrape time

Per sidvishnoi's review: index headings by ID during scraping rather than
at store load time. Removes the redundant indexHeadings() runtime function.

Author: marcoscaceres

routes/xref/lib/scraper.ts

@@ -51,7 +51,7 @@ export interface HeadingEntry {
 }
 
 export interface HeadingsBySpec {
-  [shortname: string]: HeadingEntry[];
+  [shortname: string]: { [id: string]: HeadingEntry };
 }
 
 interface HeadingsJSON {
@@ -251,7 +251,7 @@ async function readJSON<T = unknown>(filePath: string): Promise<T> {
 
 /**
  * Read all headings data from webref's ed/headings/ directory.
- * Returns { shortname: HeadingEntry[] }. Indexed by id in the Store.
+ * Returns { shortname: { id: HeadingEntry } } — pre-indexed for O(1) lookup.
  */
 async function readAllHeadings(
   headingsDir: string,
@@ -271,14 +271,17 @@ async function readAllHeadings(
       const data = await readJSON<HeadingsJSON>(path.join(headingsDir, file));
       // Shortname derived from filename (webref doesn't include it in the JSON)
       const shortname = file.replace(/\.json$/, "").toLowerCase();
-      const headings: HeadingEntry[] = (data.headings || []).map(h => ({
-        id: h.id,
-        href: h.href,
-        title: h.title,
-        number: h.number,
-        level: h.level,
-      }));
-      result[shortname] = headings;
+      const byId: { [id: string]: HeadingEntry } = Object.create(null);
+      for (const h of data.headings || []) {
+        byId[h.id] = {
+          id: h.id,
+          href: h.href,
+          title: h.title,
+          number: h.number,
+          level: h.level,
+        };
+      }
+      result[shortname] = byId;
     } catch (error) {
       console.error(`Error reading headings from ${file}:`, error);
     }

routes/xref/lib/store.ts

@@ -1,15 +1,10 @@
 import path from "path";
-import { readFileSync, existsSync } from "fs";
+import { readFileSync } from "fs";
 
 import { env } from "../../../utils/misc.js";
 import { DataEntry } from "./search.js";
 import { HeadingEntry, HeadingsBySpec } from "./scraper.js";
 
-/** Headings indexed by id for O(1) lookup. */
-type HeadingsIndex = {
-  [shortname: string]: { [id: string]: HeadingEntry };
-};
-
 export class Store {
   version = -1;
   bySpec: { [shortname: string]: DataEntry[] } = {};
@@ -21,8 +16,8 @@ export class Store {
       title: string;
     };
   } = {};
-  /** Headings indexed by spec shortname, then by fragment id. */
-  headings: HeadingsIndex = {};
+  /** Headings pre-indexed by spec shortname, then by fragment id. */
+  headings: HeadingsBySpec = {};
   /** Reverse lookup: shortname → spec title. */
   private specTitleByShortname: Map<string, string> = new Map();
 
@@ -35,8 +30,7 @@ export class Store {
     this.byTerm = readJson("xref.json");
     this.bySpec = readJson("specs.json");
     this.specmap = readJson("specmap.json");
-    const rawHeadings: HeadingsBySpec = readJsonOptional("headings.json");
-    this.headings = indexHeadings(rawHeadings);
+    this.headings = readJsonOptional("headings.json");
     this.specTitleByShortname = buildSpecTitleMap(this.specmap);
     this.version = Date.now();
   }
@@ -81,19 +75,6 @@ function readJsonOptional(filename: string) {
   }
 }
 
-/** Index headings arrays by id for O(1) lookup per spec. */
-function indexHeadings(raw: HeadingsBySpec): HeadingsIndex {
-  const indexed: HeadingsIndex = Object.create(null);
-  for (const [shortname, headings] of Object.entries(raw)) {
-    const byId: { [id: string]: HeadingEntry } = Object.create(null);
-    for (const h of headings) {
-      byId[h.id] = h;
-    }
-    indexed[shortname] = byId;
-  }
-  return indexed;
-}
-
 /** Build a shortname → title map from the specmap for O(1) title lookup. */
 function buildSpecTitleMap(specmap: Store["specmap"]): Map<string, string> {
   const result = new Map<string, string>();