@px-lsp/server 0.1.0

package/src/data/dataFnUsage.ts

@@ -0,0 +1,431 @@
+/**
+ * Vanilla-usage harvest for [ ... ] datafunction expressions: scans the game's
+ * gui/ tree and localization/<language>/ for every bracketed expression and
+ * records what real code does with each name — usage counts, immediate
+ * members, call arities, quoted literal arguments, formatting suffixes and
+ * example sites. This is the "deduce it from how it's used" layer: it covers
+ * names newer than the bundled wiki tables and enriches everything with
+ * ground-truth examples. Cached in the storage dir (one full-text scan of
+ * ~35 MB per game patch is too slow to repeat every start).
+ *
+ * No vscode imports: unit-tested in plain Node.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { listFiles } from "@px-lsp/protocol/fsWalk";
+
+export interface DataFnExample {
+  /** The full bracketed expression, capped for display. */
+  text: string;
+  /** Game-relative file path and 1-based line, for provenance in hovers. */
+  file: string;
+  line: number;
+}
+
+export interface DataFnUsage {
+  /** Chain-start name (PascalCase/ALL_CAPS only) -> number of uses. */
+  starts: Map<string, number>;
+  /** Chain-start name -> immediate `.member` -> count (datacontext-style pairs). */
+  pairs: Map<string, Map<string, number>>;
+  /** Any post-dot segment name -> count, across all chains (unresolved-chain fallback). */
+  memberPool: Map<string, number>;
+  /** Called name -> arity -> count. */
+  argCounts: Map<string, Map<number, number>>;
+  /** Called name -> quoted literal argument -> count. */
+  literals: Map<string, Map<string, number>>;
+  /** `|X` formatting suffix -> count. */
+  formats: Map<string, number>;
+  /** Segment name -> up to MAX_EXAMPLES shortest real expressions using it. */
+  examples: Map<string, DataFnExample[]>;
+  files: number;
+  exprs: number;
+}
+
+export function emptyUsage(): DataFnUsage {
+  return {
+    starts: new Map(),
+    pairs: new Map(),
+    memberPool: new Map(),
+    argCounts: new Map(),
+    literals: new Map(),
+    formats: new Map(),
+    examples: new Map(),
+    files: 0,
+    exprs: 0,
+  };
+}
+
+const MAX_EXAMPLES = 2;
+const MAX_EXAMPLE_LEN = 140;
+const MAX_LITERAL_LEN = 48;
+const MAX_LITERALS_PER_FN = 40;
+
+// ---- expression parsing -----------------------------------------------------
+
+interface Seg {
+  name: string;
+  /** Argument list when called with parens; null when a plain segment. */
+  args: Arg[] | null;
+}
+type Arg = { kind: "literal"; value: string } | { kind: "chain"; segments: Seg[] } | { kind: "number" };
+
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*/;
+
+/**
+ * Tolerant recursive-descent parse of one bracketed expression body (without
+ * the [ ]). Returns the top-level chain plus any nested argument chains, or
+ * null when the text is not a datafunction expression (loc escapes, junk).
+ */
+export function parseDataFnExpr(text: string): { chain: Seg[]; format: string | null } | null {
+  let pos = 0;
+  const skipWs = () => {
+    while (pos < text.length && (text[pos] === " " || text[pos] === "\t")) pos++;
+  };
+
+  function parseChain(): Seg[] | null {
+    const segments: Seg[] = [];
+    for (;;) {
+      skipWs();
+      const m = IDENT.exec(text.slice(pos));
+      if (!m) return null;
+      pos += m[0].length;
+      skipWs();
+      let args: Arg[] | null = null;
+      if (text[pos] === "(") {
+        pos++;
+        args = [];
+        skipWs();
+        if (text[pos] === ")") pos++;
+        else {
+          for (;;) {
+            const arg = parseArg();
+            if (!arg) return null;
+            args.push(arg);
+            skipWs();
+            if (text[pos] === ",") {
+              pos++;
+              continue;
+            }
+            if (text[pos] === ")") {
+              pos++;
+              break;
+            }
+            return null;
+          }
+        }
+      }
+      segments.push({ name: m[0], args });
+      skipWs();
+      if (text[pos] === ".") {
+        pos++;
+        continue;
+      }
+      return segments;
+    }
+  }
+
+  function parseArg(): Arg | null {
+    skipWs();
+    const ch = text[pos];
+    if (ch === "'") {
+      const close = text.indexOf("'", pos + 1);
+      if (close < 0) return null;
+      const value = text.slice(pos + 1, close);
+      pos = close + 1;
+      return { kind: "literal", value };
+    }
+    if (/[0-9-]/.test(ch)) {
+      const m = /^-?[0-9]+(\.[0-9]+)?/.exec(text.slice(pos));
+      if (!m) return null;
+      pos += m[0].length;
+      return { kind: "number" };
+    }
+    const segments = parseChain();
+    return segments ? { kind: "chain", segments } : null;
+  }
+
+  const chain = parseChain();
+  if (!chain) return null;
+  skipWs();
+  let format: string | null = null;
+  if (text[pos] === "|") {
+    format = text.slice(pos + 1).trim();
+    pos = text.length;
+  }
+  skipWs();
+  if (pos < text.length) return null;
+  return { chain, format };
+}
+
+// ---- recording ---------------------------------------------------------------
+
+function bump<K>(map: Map<K, number>, key: K): void {
+  map.set(key, (map.get(key) ?? 0) + 1);
+}
+
+function addExample(usage: DataFnUsage, name: string, ex: DataFnExample): void {
+  let list = usage.examples.get(name);
+  if (!list) usage.examples.set(name, (list = []));
+  if (list.some((e) => e.text === ex.text)) return;
+  if (list.length < MAX_EXAMPLES) {
+    list.push(ex);
+    return;
+  }
+  // Prefer the shortest examples: they read best in a hover.
+  let longest = 0;
+  for (let i = 1; i < list.length; i++) if (list[i].text.length > list[longest].text.length) longest = i;
+  if (ex.text.length < list[longest].text.length) list[longest] = ex;
+}
+
+function recordChain(usage: DataFnUsage, chain: Seg[], ex: DataFnExample, topLevel: boolean): void {
+  const first = chain[0];
+  // Chain starts: types / global promotes / global functions are PascalCase or
+  // ALL_CAPS in vanilla. Lowercase starts in loc are script-scope bindings
+  // (owner.GetName) — not completable names, but their members still count.
+  if (/^[A-Z]/.test(first.name)) {
+    bump(usage.starts, first.name);
+    addExample(usage, first.name, ex);
+    if (chain.length > 1) {
+      let members = usage.pairs.get(first.name);
+      if (!members) usage.pairs.set(first.name, (members = new Map()));
+      bump(members, chain[1].name);
+    }
+  }
+  for (let i = 0; i < chain.length; i++) {
+    const seg = chain[i];
+    if (i > 0) {
+      bump(usage.memberPool, seg.name);
+      addExample(usage, seg.name, ex);
+    }
+    if (seg.args !== null) {
+      let arities = usage.argCounts.get(seg.name);
+      if (!arities) usage.argCounts.set(seg.name, (arities = new Map()));
+      bump(arities, seg.args.length);
+      for (const arg of seg.args) {
+        if (arg.kind === "literal") {
+          if (arg.value.length === 0 || arg.value.length > MAX_LITERAL_LEN) continue;
+          let lits = usage.literals.get(seg.name);
+          if (!lits) usage.literals.set(seg.name, (lits = new Map()));
+          if (lits.size < MAX_LITERALS_PER_FN || lits.has(arg.value)) bump(lits, arg.value);
+        } else if (arg.kind === "chain") {
+          recordChain(usage, arg.segments, ex, false);
+        }
+      }
+    }
+  }
+  if (topLevel) usage.exprs++;
+}
+
+/** Bracketed expressions in one line of text; `\[` (loc escape) is skipped. */
+const EXPR_RE = /\[([^\][\r\n]+)\]/g;
+
+export function harvestLine(usage: DataFnUsage, lineText: string, file: string, lineNo: number): void {
+  EXPR_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = EXPR_RE.exec(lineText)) !== null) {
+    if (m.index > 0 && lineText[m.index - 1] === "\\") continue;
+    const parsed = parseDataFnExpr(m[1]);
+    if (!parsed) continue;
+    const text = `[${m[1]}]`;
+    const ex: DataFnExample = {
+      text: text.length > MAX_EXAMPLE_LEN ? text.slice(0, MAX_EXAMPLE_LEN - 1) + "…" : text,
+      file,
+      line: lineNo,
+    };
+    recordChain(usage, parsed.chain, ex, true);
+    if (parsed.format) {
+      // Suffix may itself chain formats; count the leading token only.
+      const fmt = /^[A-Za-z0-9+\-=*%.]+/.exec(parsed.format)?.[0];
+      if (fmt && fmt.length <= 3) bump(usage.formats, fmt);
+    }
+  }
+}
+
+// ---- scanning + cache ---------------------------------------------------------
+
+function harvestFile(usage: DataFnUsage, filePath: string, relPath: string): void {
+  let text: string;
+  try {
+    text = fs.readFileSync(filePath, "utf8");
+  } catch {
+    return;
+  }
+  if (!text.includes("[")) {
+    usage.files++;
+    return;
+  }
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes("[")) harvestLine(usage, lines[i], relPath, i + 1);
+  }
+  usage.files++;
+}
+
+/** The two scanned trees under a game root: the gui/ tree and one localization language folder. */
+function scanRoots(gamePath: string, locLanguage: string): ReadonlyArray<readonly [string, string]> {
+  return [
+    [path.join(gamePath, "gui"), ".gui"],
+    [path.join(gamePath, "localization", locLanguage), ".yml"],
+  ];
+}
+
+export function harvestGameUsage(gamePath: string, locLanguage = "english"): DataFnUsage {
+  const usage = emptyUsage();
+  for (const [root, ext] of scanRoots(gamePath, locLanguage)) {
+    for (const file of listFiles(root, ext)) {
+      harvestFile(usage, file, path.relative(gamePath, file).replace(/\\/g, "/"));
+    }
+  }
+  return usage;
+}
+
+// JSON cache: bump CACHE_VERSION whenever the harvest shape or logic changes.
+const CACHE_VERSION = 1;
+
+interface CacheShape {
+  version: number;
+  stamp: string;
+  starts: Record<string, number>;
+  pairs: Record<string, Record<string, number>>;
+  memberPool: Record<string, number>;
+  argCounts: Record<string, Record<string, number>>;
+  literals: Record<string, Record<string, number>>;
+  formats: Record<string, number>;
+  examples: Record<string, DataFnExample[]>;
+  files: number;
+  exprs: number;
+}
+
+/**
+ * Cheap change stamp: file count + total size of both scanned trees. A game
+ * patch always changes it; it costs one directory walk, not 35 MB of reads.
+ */
+function usageStamp(gamePath: string, locLanguage: string): string {
+  let count = 0;
+  let size = 0;
+  for (const [root, ext] of scanRoots(gamePath, locLanguage)) {
+    for (const file of listFiles(root, ext)) {
+      count++;
+      try {
+        size += fs.statSync(file).size;
+      } catch {
+        /* unreadable file: stamp from the rest */
+      }
+    }
+  }
+  return `${CACHE_VERSION}:${gamePath}:${locLanguage}:${count}:${size}`;
+}
+
+function toObj<V>(map: Map<string, V>): Record<string, V> {
+  return Object.fromEntries(map);
+}
+function toMap<V>(obj: Record<string, V> | undefined): Map<string, V> {
+  return new Map(Object.entries(obj ?? {}));
+}
+
+function serialize(usage: DataFnUsage, stamp: string): CacheShape {
+  return {
+    version: CACHE_VERSION,
+    stamp,
+    starts: toObj(usage.starts),
+    pairs: toObj(new Map([...usage.pairs].map(([k, v]) => [k, toObj(v)]))),
+    memberPool: toObj(usage.memberPool),
+    argCounts: toObj(
+      new Map(
+        [...usage.argCounts].map(([k, v]) => [k, toObj(new Map([...v].map(([n, c]) => [String(n), c])))])
+      )
+    ),
+    literals: toObj(new Map([...usage.literals].map(([k, v]) => [k, toObj(v)]))),
+    formats: toObj(usage.formats),
+    examples: toObj(usage.examples),
+    files: usage.files,
+    exprs: usage.exprs,
+  };
+}
+
+function deserialize(cache: CacheShape): DataFnUsage {
+  return {
+    starts: toMap(cache.starts),
+    pairs: new Map(Object.entries(cache.pairs ?? {}).map(([k, v]) => [k, toMap(v)])),
+    memberPool: toMap(cache.memberPool),
+    argCounts: new Map(
+      Object.entries(cache.argCounts ?? {}).map(([k, v]) => [
+        k,
+        new Map(Object.entries(v).map(([n, c]) => [Number(n), c])),
+      ])
+    ),
+    literals: new Map(Object.entries(cache.literals ?? {}).map(([k, v]) => [k, toMap(v)])),
+    formats: toMap(cache.formats),
+    examples: toMap(cache.examples),
+    files: cache.files ?? 0,
+    exprs: cache.exprs ?? 0,
+  };
+}
+
+export interface UsageLoadResult {
+  usage: DataFnUsage;
+  fromCache: boolean;
+}
+
+/** Harvest with a stamp-validated JSON cache; empty usage when no game path. */
+export function loadDataFnUsage(
+  gamePath: string | null,
+  locLanguage: string,
+  cacheFile: string | null,
+  force = false
+): UsageLoadResult {
+  if (!gamePath) return { usage: emptyUsage(), fromCache: false };
+  const stamp = usageStamp(gamePath, locLanguage);
+  const cached = readCache(cacheFile, stamp, force);
+  if (cached) return { usage: cached, fromCache: true };
+  const usage = harvestGameUsage(gamePath, locLanguage);
+  writeCache(cacheFile, usage, stamp);
+  return { usage, fromCache: false };
+}
+
+/**
+ * Async variant for server startup: the uncached first harvest reads ~35 MB
+ * (20s on a cold OS cache), so it yields to the event loop between files
+ * instead of blocking every LSP request. Cache hits return without yielding.
+ */
+export async function loadDataFnUsageAsync(
+  gamePath: string | null,
+  locLanguage: string,
+  cacheFile: string | null,
+  force = false
+): Promise<UsageLoadResult> {
+  if (!gamePath) return { usage: emptyUsage(), fromCache: false };
+  const stamp = usageStamp(gamePath, locLanguage);
+  const cached = readCache(cacheFile, stamp, force);
+  if (cached) return { usage: cached, fromCache: true };
+  const usage = emptyUsage();
+  const yieldNow = () => new Promise<void>((resolve) => setImmediate(resolve));
+  for (const [root, ext] of scanRoots(gamePath, locLanguage)) {
+    for (const file of listFiles(root, ext)) {
+      harvestFile(usage, file, path.relative(gamePath, file).replace(/\\/g, "/"));
+      if (usage.files % 20 === 0) await yieldNow();
+    }
+  }
+  writeCache(cacheFile, usage, stamp);
+  return { usage, fromCache: false };
+}
+
+function readCache(cacheFile: string | null, stamp: string, force: boolean): DataFnUsage | null {
+  if (!cacheFile || force) return null;
+  try {
+    const cache = JSON.parse(fs.readFileSync(cacheFile, "utf8")) as CacheShape;
+    if (cache.version === CACHE_VERSION && cache.stamp === stamp) return deserialize(cache);
+  } catch {
+    /* no/invalid cache: harvest */
+  }
+  return null;
+}
+
+function writeCache(cacheFile: string | null, usage: DataFnUsage, stamp: string): void {
+  if (!cacheFile || usage.exprs === 0) return;
+  try {
+    fs.writeFileSync(cacheFile, JSON.stringify(serialize(usage, stamp)));
+  } catch {
+    /* cache write is best-effort */
+  }
+}

package/src/data/dataTypes.ts

@@ -0,0 +1,279 @@
+/**
+ * Data types for [ ... ] data-function expressions in .gui and localization
+ * files: global promotes/functions (GetPlayer, …) and per-type members
+ * (Character.IsAlive, …).
+ *
+ * Two sources, script_docs-style:
+ *  - bundled baseline harvested from the modding wiki's Data types page
+ *    (packages/server/data/<game>/dataTypes.json, built by scripts/build-data-types-json.ts);
+ *  - the user's own `data_types.log`, written by the game's `DumpDataTypes`
+ *    console command — complete and version-exact, so its entries win.
+ *
+ * No vscode imports: unit-tested in plain Node.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { activeProfile } from "../games/active";
+
+export interface DataTypeMember {
+  /** Return type name; null when unknown (wiki lists some as [unregistered]). */
+  ret: string | null;
+  /** Argument type names from the dump header; null when unknown/none recorded. */
+  args: string[] | null;
+  kind: "promote" | "function";
+  /** Description prose from the dump, when the entry carries one. */
+  desc?: string;
+  /** Which source produced this entry (provenance shown in hovers). */
+  src?: "wiki" | "dump" | "macro";
+}
+
+export interface DataTypesData {
+  /** Chain-start names: global promotes and global functions. */
+  globals: Map<string, DataTypeMember>;
+  /** Type name -> member name -> member. */
+  types: Map<string, Map<string, DataTypeMember>>;
+  /** Lowercased type name -> canonical casing (tolerant hover/completion). */
+  typeNamesLower: Map<string, string>;
+  /** Where the (majority of the) data came from. */
+  source: "bundled wiki" | "data_types.log";
+  /** Total member count, for the status log line. */
+  count: number;
+}
+
+interface BundledShape {
+  globalPromotes: Record<string, string | null>;
+  globalFunctions: Record<string, string | null>;
+  types: Record<string, Record<string, string | null>>;
+}
+
+export function emptyDataTypes(): DataTypesData {
+  return {
+    globals: new Map(),
+    types: new Map(),
+    typeNamesLower: new Map(),
+    source: "bundled wiki",
+    count: 0,
+  };
+}
+
+function typeMembers(data: DataTypesData, type: string): Map<string, DataTypeMember> {
+  let members = data.types.get(type);
+  if (!members) {
+    data.types.set(type, (members = new Map()));
+    data.typeNamesLower.set(type.toLowerCase(), type);
+  }
+  return members;
+}
+
+export function loadBundledDataTypes(): DataTypesData {
+  const data = emptyDataTypes();
+  const bundled = activeProfile().bundledDataTypes as BundledShape | undefined;
+  if (!bundled) return data;
+  for (const [name, ret] of Object.entries(bundled.globalPromotes)) {
+    data.globals.set(name, { ret, args: null, kind: "promote", src: "wiki" });
+    data.count++;
+  }
+  for (const [name, ret] of Object.entries(bundled.globalFunctions)) {
+    if (!data.globals.has(name)) data.globals.set(name, { ret, args: null, kind: "function", src: "wiki" });
+    data.count++;
+  }
+  for (const [type, members] of Object.entries(bundled.types)) {
+    const map = typeMembers(data, type);
+    for (const [name, ret] of Object.entries(members)) {
+      map.set(name, { ret, args: null, kind: "function", src: "wiki" });
+      data.count++;
+    }
+  }
+  return data;
+}
+
+/**
+ * Parse the game's DumpDataTypes output. Entries are separated by dashed
+ * lines; each entry is a header (`Name`, `Type.Name`, or `Name( arg, arg )`)
+ * followed by `Definition type: <Global promote|Global function|Promote|
+ * Function|Type|Global macro>` and `Return type: <name>` lines. Tolerant: an
+ * entry missing any expected part is skipped.
+ */
+export function parseDataTypesDump(text: string, into?: DataTypesData): DataTypesData {
+  const data = into ?? emptyDataTypes();
+  for (const rawEntry of text.split(/\r?\n-{4,}\r?\n/)) {
+    const entry = rawEntry.trim();
+    if (entry.length === 0) continue;
+    const lines = entry.split(/\r?\n/);
+    const header = lines[0].trim();
+    let defType: string | null = null;
+    let ret: string | null = null;
+    const descLines: string[] = [];
+    for (const line of lines.slice(1)) {
+      const def = /^Definition type:\s*(.+)$/.exec(line.trim());
+      if (def) {
+        defType = def[1].trim();
+        continue;
+      }
+      const rt = /^Return type:\s*(.+)$/.exec(line.trim());
+      if (rt) {
+        ret = rt[1].trim();
+        continue;
+      }
+      // Descriptions come as "Description: ..." lines; older dumps used bare
+      // prose. Either way, strip the prefix and keep the text. A dash run is
+      // a separator (reachable here when the file lacks a trailing newline).
+      const prose = line.trim().replace(/^Description:\s*/, "");
+      if (prose.length > 0 && !/^-{4,}$/.test(prose)) descLines.push(prose);
+    }
+    if (!defType) continue;
+    const kind = /promote/i.test(defType) ? "promote" : "function";
+    if (!/^(Global promote|Global function|Promote|Function)$/i.test(defType)) continue;
+
+    // Header: strip an argument list, split an owning type off the name.
+    let signature = header;
+    let args: string[] | null = null;
+    const paren = signature.indexOf("(");
+    if (paren >= 0) {
+      const argText = signature.slice(
+        paren + 1,
+        signature.lastIndexOf(")") >= 0 ? signature.lastIndexOf(")") : undefined
+      );
+      args = argText
+        .split(",")
+        .map((a) => a.trim())
+        .filter((a) => a.length > 0);
+      signature = signature.slice(0, paren).trim();
+    }
+    if (!/^[A-Za-z_][A-Za-z0-9_.]*$/.test(signature)) continue;
+
+    // "[unregistered]" is the dump's "no registered return type" marker — a
+    // null ret (fallback completion) beats a bogus type name (dead chain).
+    const member: DataTypeMember = {
+      ret: ret === "void" || ret === "[unregistered]" ? null : ret,
+      args,
+      kind,
+      src: "dump",
+    };
+    const desc = descLines.join(" ").slice(0, 300);
+    // "Jomini Script System" is per-entry boilerplate, not a description.
+    if (desc.length > 0 && desc !== "Jomini Script System") member.desc = desc;
+    const isGlobal = /^Global/i.test(defType);
+    const dot = signature.indexOf(".");
+    if (!isGlobal && dot > 0) {
+      const owner = signature.slice(0, dot);
+      const name = signature.slice(dot + 1);
+      if (name.length === 0 || name.includes(".")) continue;
+      insertMember(data, typeMembers(data, owner), name, member);
+    } else if (isGlobal && dot < 0) {
+      insertMember(data, data.globals, signature, member);
+    }
+  }
+  return data;
+}
+
+/**
+ * Insert a dump entry without losing information: the dump lists some members
+ * twice (e.g. `Character.GetFather` once as a Promote with a real return type
+ * and once as a Function returning "[unregistered]"), and the wiki baseline
+ * may already hold a typed entry. An entry with a known return type is never
+ * clobbered by one without; desc/args fill in whichever survivor lacks them.
+ */
+function insertMember(
+  data: DataTypesData,
+  map: Map<string, DataTypeMember>,
+  name: string,
+  member: DataTypeMember
+): void {
+  const prev = map.get(name);
+  if (!prev) {
+    map.set(name, member);
+    data.count++;
+    return;
+  }
+  const keep = prev.ret !== null && member.ret === null ? prev : member;
+  const other = keep === prev ? member : prev;
+  if (!keep.desc && other.desc) keep.desc = other.desc;
+  if (!keep.args && other.args) keep.args = other.args;
+  map.set(name, keep);
+}
+
+/** The dump files a directory holds, in any of the three shapes different
+ * game versions have written: `data_types.log`, `data_type*.txt` files, and a
+ * `data_types/` subfolder of per-category files. */
+function dumpFilesIn(dir: string): string[] {
+  const files: string[] = [];
+  const logFile = path.join(dir, "data_types.log");
+  if (fs.existsSync(logFile)) files.push(logFile);
+  try {
+    for (const name of fs.readdirSync(dir)) {
+      if (/^data_type.*\.txt$/i.test(name)) files.push(path.join(dir, name));
+    }
+  } catch {
+    /* dir unreadable */
+  }
+  const dumpDir = path.join(dir, "data_types");
+  try {
+    for (const name of fs.readdirSync(dumpDir)) {
+      const file = path.join(dumpDir, name);
+      if (fs.statSync(file).isFile()) files.push(file);
+    }
+  } catch {
+    /* no data_types/ subfolder */
+  }
+  return files;
+}
+
+/**
+ * Bundled baseline upgraded by dumps. `dirs` are searched in order and later
+ * directories win on conflicts, so callers list them lowest priority first
+ * (bundled dump, then the user's folders). A single string is accepted for
+ * convenience. Games whose script_docs live outside logs/ (newer Jomini
+ * titles) dump data types to logs/ anyway, so callers pass both folders.
+ */
+export function loadDataTypes(dirs: string | null | Array<string | null>): DataTypesData {
+  const data = loadBundledDataTypes();
+  const list = (Array.isArray(dirs) ? dirs : [dirs]).filter((d): d is string => d !== null);
+  const dumpFiles = list.flatMap(dumpFilesIn);
+  if (dumpFiles.length === 0) return data;
+  const before = data.count;
+  for (const file of dumpFiles) {
+    try {
+      parseDataTypesDump(fs.readFileSync(file, "utf8"), data);
+    } catch {
+      /* unreadable dump: keep what we have */
+    }
+  }
+  if (data.count > before) data.source = "data_types.log";
+  return data;
+}
+
+/** Member lookup on a type, exact first then case-insensitive canonicalization. */
+export function membersOf(data: DataTypesData, typeName: string): Map<string, DataTypeMember> | null {
+  const direct = data.types.get(typeName);
+  if (direct) return direct;
+  const canonical = data.typeNamesLower.get(typeName.toLowerCase());
+  return canonical ? (data.types.get(canonical) ?? null) : null;
+}
+
+/**
+ * Resolve a dotted chain (["Character","GetFather"]) to the type the NEXT
+ * segment completes against. The first segment may be a data type name (the
+ * datacontext style: Character.GetName) or a global promote/function. Returns
+ * null when any segment is unknown.
+ */
+export function resolveChainType(data: DataTypesData, segments: string[]): string | null {
+  if (segments.length === 0) return null;
+  let current: string | null = null;
+  const first = segments[0];
+  if (membersOf(data, first)) {
+    current = data.typeNamesLower.get(first.toLowerCase()) ?? first;
+  } else {
+    const global = data.globals.get(first);
+    if (!global || !global.ret) return null;
+    current = global.ret;
+  }
+  for (const segment of segments.slice(1)) {
+    if (current === null) return null;
+    const members = membersOf(data, current);
+    const member = members?.get(segment);
+    if (!member || !member.ret) return null;
+    current = member.ret;
+  }
+  return current;
+}