@px-lsp/server 0.1.0

package/src/index/indexer.ts

@@ -0,0 +1,369 @@
+/**
+ * Definition indexer for vanilla + parent-mod + mod folders, driven by the
+ * schema table (packages/server/src/schema): every schema entry maps one folder to a
+ * definition kind and an extraction mode.
+ *
+ * No `vscode` imports here: this module is unit-tested in plain Node. The
+ * FileSystemWatcher wiring lives in the client.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import type { DefKind, Definition, DefSource, IndexStats } from "@px-lsp/protocol/types";
+import { listFiles, walkDir } from "@px-lsp/protocol/fsWalk";
+import { pushAll } from "@px-lsp/protocol/arrays";
+import { activeProfile } from "../games/active";
+import type { SchemaEntry } from "../schema/types";
+import { EVENT_ID, extractDefinitions, extractLocDefinitions } from "./extract";
+
+export { listFiles, EVENT_ID };
+export type { IndexStats };
+
+/** Priority when several sources define the same name (higher shadows lower). */
+const SOURCE_RANK: Record<DefSource, number> = { mod: 2, parent: 1, vanilla: 0 };
+
+/**
+ * The one kind whose names are tracked incrementally (perf campaign §B2): the
+ * scope model is refed every scripted list on EVERY index change, a save
+ * included, and walking all 1.9M names to find the ~50 that are scripted lists
+ * cost 65-85 ms per save (measured, recipe 1).
+ */
+const TRACKED_KIND = "scripted_list";
+
+// Back-compat helpers used by unit tests and older callers.
+export function parseScriptDefinitions(
+  content: string,
+  kind: DefKind,
+  file: string,
+  source: DefSource
+): Definition[] {
+  const entry: SchemaEntry = {
+    path: "",
+    kind,
+    extraction: kind === "event" ? "event-id" : "top-level-key",
+  };
+  return extractDefinitions(content, entry, file, source);
+}
+
+export function parseLocDefinitions(content: string, file: string, source: DefSource): Definition[] {
+  return extractLocDefinitions(content, file, source);
+}
+
+function normFile(file: string): string {
+  const n = path.normalize(file);
+  return process.platform === "win32" ? n.toLowerCase() : n;
+}
+
+export class DefinitionIndex {
+  private byName = new Map<string, Definition[]>();
+  private byFile = new Map<string, Definition[]>();
+  /** Names carrying at least one TRACKED_KIND definition, refcounted so
+   *  removeFile drops the name again (§B2). */
+  private trackedNames = new Map<string, number>();
+  /** Bumped on every mutation; used by providers to invalidate caches. */
+  revision = 0;
+
+  addAll(defs: Definition[]): void {
+    for (const def of defs) {
+      let list = this.byName.get(def.name);
+      if (!list) this.byName.set(def.name, (list = []));
+      list.push(def);
+      if (def.kind === TRACKED_KIND)
+        this.trackedNames.set(def.name, (this.trackedNames.get(def.name) ?? 0) + 1);
+      const fkey = normFile(def.file);
+      let flist = this.byFile.get(fkey);
+      if (!flist) this.byFile.set(fkey, (flist = []));
+      flist.push(def);
+      this.total++;
+      this.bump(this.byKind, def.kind, 1);
+      this.bump(this.bySource, def.source, 1);
+    }
+    if (defs.length > 0) this.revision++;
+  }
+
+  removeFile(file: string): void {
+    const fkey = normFile(file);
+    const defs = this.byFile.get(fkey);
+    if (!defs) return;
+    this.byFile.delete(fkey);
+    for (const def of defs) {
+      this.total--;
+      this.bump(this.byKind, def.kind, -1);
+      this.bump(this.bySource, def.source, -1);
+      const list = this.byName.get(def.name);
+      if (!list) continue;
+      const filtered = list.filter((d) => d !== def);
+      if (filtered.length === 0) this.byName.delete(def.name);
+      else this.byName.set(def.name, filtered);
+      if (def.kind === TRACKED_KIND) {
+        const left = (this.trackedNames.get(def.name) ?? 0) - 1;
+        if (left <= 0) this.trackedNames.delete(def.name);
+        else this.trackedNames.set(def.name, left);
+      }
+    }
+    this.revision++;
+  }
+
+  /** Only the highest-ranked source present: mod shadows parent shadows vanilla. */
+  private shadowResolve(list: Definition[]): Definition[] {
+    let best = -1;
+    for (const d of list) best = Math.max(best, SOURCE_RANK[d.source]);
+    return list.filter((d) => SOURCE_RANK[d.source] === best);
+  }
+
+  /** All definitions for a name after shadow resolution. */
+  lookup(name: string): Definition[] {
+    const list = this.byName.get(name);
+    if (!list || list.length === 0) return [];
+    return this.shadowResolve(list);
+  }
+
+  /** All definitions for a name, all sources (for "peek all"). */
+  lookupAll(name: string): Definition[] {
+    return this.byName.get(name) ?? [];
+  }
+
+  /** Iterate one shadow-resolved definition per name, optionally filtered. */
+  *entries(filter?: (def: Definition) => boolean): IterableIterator<Definition> {
+    for (const list of this.byName.values()) {
+      // Apply the filter across ALL shadow-resolved defs of the name, not just
+      // the first: a name can carry several kinds (vanilla `brave` is a loc_key
+      // AND a trait), and a kind-filtered caller must still see the matching one.
+      const resolved = this.shadowResolve(list);
+      const def = filter ? resolved.find(filter) : resolved[0];
+      if (def) yield def;
+    }
+  }
+
+  /**
+   * Scripted-list definitions, shadow-resolved. Identical to
+   * `entries((d) => d.kind === "scripted_list")` — same shadow resolution over
+   * the full name list, so a mod loc_key still shadows a vanilla scripted list
+   * of the same name — but it only visits the names that carry one (§B2).
+   */
+  *scriptedLists(): IterableIterator<Definition> {
+    for (const name of this.trackedNames.keys()) {
+      const list = this.byName.get(name);
+      if (!list || list.length === 0) continue;
+      const def = this.shadowResolve(list).find((d) => d.kind === TRACKED_KIND);
+      if (def) yield def;
+    }
+  }
+
+  /**
+   * Running totals, maintained by addAll/removeFile. The status notification
+   * asks for stats() on every index change, and one full walk of a 1.9M
+   * definition index cost 61-74 ms per save (§B2). Counters are dropped at
+   * zero so the result equals a full rebuild's, key for key.
+   */
+  private total = 0;
+  private byKind = new Map<string, number>();
+  private bySource = new Map<string, number>();
+
+  private bump(counts: Map<string, number>, key: string, by: number): void {
+    const n = (counts.get(key) ?? 0) + by;
+    if (n <= 0) counts.delete(key);
+    else counts.set(key, n);
+  }
+
+  stats(): IndexStats {
+    return {
+      total: this.total,
+      files: this.byFile.size,
+      byKind: Object.fromEntries(this.byKind),
+      bySource: Object.fromEntries(this.bySource),
+    };
+  }
+
+  allDefinitions(): Definition[] {
+    const out: Definition[] = [];
+    for (const list of this.byFile.values()) pushAll(out, list);
+    return out;
+  }
+
+  /** Definitions in one file. */
+  inFile(file: string): Definition[] {
+    return this.byFile.get(normFile(file)) ?? [];
+  }
+}
+
+/** Which schema entry a file contributes to under `root`, or null if not indexed. */
+export function classifyFile(
+  root: string,
+  file: string,
+  entries: SchemaEntry[] = activeProfile().schema
+): SchemaEntry | null {
+  const rel = path.relative(root, file);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
+  const relFwd = rel.split(path.sep).join("/").toLowerCase();
+  let best: SchemaEntry | null = null;
+  for (const entry of entries) {
+    const ext = entry.ext ?? ".txt";
+    if (relFwd.startsWith(entry.path + "/") && relFwd.endsWith(ext)) {
+      // Longest path wins (common/culture/traditions over a hypothetical common/culture).
+      if (!best || entry.path.length > best.path.length) best = entry;
+    }
+  }
+  return best;
+}
+
+/** True if a localization file belongs to the configured language. */
+export function isWantedLocFile(relPath: string, locLanguage: string): boolean {
+  const lower = relPath.toLowerCase().split(path.sep).join("/");
+  if (lower.includes(`l_${locLanguage}`)) return true;
+  return lower.split("/").includes(locLanguage);
+}
+
+export function parseFile(file: string, entry: SchemaEntry, source: DefSource): Definition[] {
+  let content: string;
+  try {
+    content = fs.readFileSync(file, "utf8");
+  } catch {
+    return [];
+  }
+  content = content.replace(/^/, "");
+  return extractDefinitions(content, entry, file, source);
+}
+
+export interface ScanOptions {
+  locLanguage: string;
+  entries?: SchemaEntry[];
+}
+
+/** Scan every schema folder under `root` and return the definitions found. */
+export function scanRoot(root: string, source: DefSource, opts: ScanOptions): Definition[] {
+  const defs: Definition[] = [];
+  for (const entry of opts.entries ?? activeProfile().schema) {
+    const dir = path.join(root, ...entry.path.split("/"));
+    const files: string[] = [];
+    walkDir(dir, entry.ext ?? ".txt", files);
+    for (const file of files) {
+      if (entry.kind === "loc_key" && !isWantedLocFile(path.relative(root, file), opts.locLanguage)) continue;
+      pushAll(defs, parseFile(file, entry, source));
+    }
+  }
+  return defs;
+}
+
+// ---------------------------------------------------------------------------
+// Vanilla index cache (compact JSON, keyed by game version)
+// ---------------------------------------------------------------------------
+
+// Bumped to 4 for §E doc/tags columns; a v3 cache is silently rejected and rebuilt.
+// Bumped to 5 when engine-layer (jomini) definitions joined the vanilla scan;
+// older caches lack them and must rebuild.
+// Bumped to 6 when event files started contributing inline
+// scripted_trigger/scripted_effect declarations (#5); older caches lack them.
+const INDEX_CACHE_FORMAT = 6;
+
+/** Compact "absent" marker inside cache rows. */
+type Absent = 0;
+
+/** Tags serialized as a compact array; absent → 0. */
+type CachedTags = Array<[string, string]> | Absent;
+
+interface IndexCacheFile {
+  cacheFormat: number;
+  gameVersion: string;
+  /** Kind string table (schema-driven, open set). */
+  kinds: string[];
+  files: string[];
+  // [name, kindIdx, fileIdx, line, value|0, paramsSpaceJoined|0, doc|0, tags|0]
+  defs: Array<
+    [string, number, number, number, string | Absent, string | Absent, string | Absent, CachedTags]
+  >;
+}
+
+/**
+ * Both halves of the cache round trip build ONE contiguous JSON string and block
+ * the event loop for its whole duration. Measured with 460k definitions (the
+ * vanilla tree per vitest.config.ts): a 26.3 MB file, 528 ms to save, 271 ms to
+ * load. That is the deliberate trade the compact row format above exists to
+ * make: the alternative it replaces is a multi-second rescan on every start.
+ *
+ * The ceiling is V8's ~512 MB single-string cap, roughly 20x the measured size.
+ * A tree that reached it throws RangeError, which both sides already degrade
+ * from: the caller of saveIndexCache logs and continues, loadIndexCache returns
+ * null and the caller rescans. So the failure mode is "no cache", not a crash.
+ * If the save or the load ever shows up in the perf trace, the answer is
+ * newline-delimited rows parsed in batches inside the scan's yieldNow rhythm.
+ */
+export function saveIndexCache(cacheFile: string, gameVersion: string, defs: Definition[]): void {
+  const kindIdx = new Map<string, number>();
+  const kinds: string[] = [];
+  const fileIdx = new Map<string, number>();
+  const files: string[] = [];
+  const rows: IndexCacheFile["defs"] = [];
+  for (const def of defs) {
+    let ki = kindIdx.get(def.kind);
+    if (ki === undefined) {
+      ki = kinds.length;
+      kinds.push(def.kind);
+      kindIdx.set(def.kind, ki);
+    }
+    let fi = fileIdx.get(def.file);
+    if (fi === undefined) {
+      fi = files.length;
+      files.push(def.file);
+      fileIdx.set(def.file, fi);
+    }
+    const tags: CachedTags = def.tags && def.tags.length > 0 ? def.tags.map((t) => [t.tag, t.text]) : 0;
+    rows.push([
+      def.name,
+      ki,
+      fi,
+      def.line,
+      def.value ?? 0,
+      def.params ? def.params.join(" ") : 0,
+      def.doc ?? 0,
+      tags,
+    ]);
+  }
+  const payload: IndexCacheFile = { cacheFormat: INDEX_CACHE_FORMAT, gameVersion, kinds, files, defs: rows };
+  fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
+  fs.writeFileSync(cacheFile, JSON.stringify(payload));
+}
+
+export function loadIndexCache(cacheFile: string, expectedGameVersion: string): Definition[] | null {
+  let payload: IndexCacheFile;
+  try {
+    payload = JSON.parse(fs.readFileSync(cacheFile, "utf8"));
+  } catch {
+    return null;
+  }
+  if (payload.cacheFormat !== INDEX_CACHE_FORMAT || payload.gameVersion !== expectedGameVersion) return null;
+  if (!Array.isArray(payload.files) || !Array.isArray(payload.defs) || !Array.isArray(payload.kinds))
+    return null;
+  const defs: Definition[] = [];
+  for (const [name, kindIdx, fileIdx, line, value, params, doc, tags] of payload.defs) {
+    const kind = payload.kinds[kindIdx];
+    const file = payload.files[fileIdx];
+    if (!kind || !file) return null;
+    const def: Definition = { name, kind, file, line, source: "vanilla" };
+    if (typeof value === "string") def.value = value;
+    if (typeof params === "string" && params !== "") def.params = params.split(" ");
+    if (typeof doc === "string" && doc !== "") def.doc = doc;
+    if (Array.isArray(tags) && tags.length > 0) def.tags = tags.map(([tag, text]) => ({ tag, text }));
+    defs.push(def);
+  }
+  return defs;
+}
+
+/**
+ * Game version used as the vanilla cache key: `rawVersion` from
+ * launcher/launcher-settings.json, falling back to the game folder mtime.
+ */
+export function detectGameVersion(gamePath: string): string {
+  try {
+    const launcherSettings = path.join(path.dirname(gamePath), "launcher", "launcher-settings.json");
+    const parsed = JSON.parse(fs.readFileSync(launcherSettings, "utf8"));
+    if (typeof parsed.rawVersion === "string" && parsed.rawVersion !== "") return parsed.rawVersion;
+    if (typeof parsed.version === "string" && parsed.version !== "") return parsed.version;
+  } catch {
+    // fall through
+  }
+  try {
+    return `mtime-${fs.statSync(gamePath).mtimeMs}`;
+  } catch {
+    return "unknown";
+  }
+}

package/src/index/intern.ts

@@ -0,0 +1,101 @@
+/**
+ * String sharing for everything that escapes into the index (perf campaign §C2).
+ *
+ * The parser hands out `content.slice(start, end)` for every key and value, and
+ * V8 represents a substring of 13+ characters as a SlicedString that keeps its
+ * PARENT alive. One definition or reference name therefore pinned the whole
+ * file's text for as long as the index held it: the index was carrying a second
+ * copy of every tree it scanned. Retained heap, post-GC, before -> after:
+ *
+ *   vanilla scan       462,886 defs    408 MB ->  193 MB
+ *   AGOT scan          345,557 defs    429 MB ->  145 MB
+ *   AGOT references  4,150,494 refs   1017 MB ->  590 MB
+ *   game + AGOT x2   (both, in one)   3153 MB -> 1412 MB (budgets.test.ts §C1)
+ *
+ * The CPU it costs is inside noise on the definition scan (3.83 -> 3.73 s for
+ * vanilla) and under 10% on the reference scan (14.4 -> 15.2 s for AGOT).
+ *
+ * `copyOf` gives a string that owns its characters, so the parent goes away.
+ * `intern` also SHARES them, which is the bigger half on the reference side:
+ * the AGOT corpus names 4.15M usage sites with 197,873 distinct names.
+ *
+ * Identifiers (names, containers, params, key chains, namespaces) go through
+ * `intern`. Prose and loc values are near-unique per site, so they are copied
+ * but not kept in the table. `kind`, `file` and `source` are already one shared
+ * string per schema entry / file / literal and need neither.
+ *
+ * No `vscode` imports here: unit-tested in plain Node.
+ */
+import type { Definition, Reference } from "@px-lsp/protocol/types";
+
+/**
+ * A fresh string that owns its characters. utf16le rather than utf8 because it
+ * round-trips every JS string exactly (lone surrogates included); V8 still
+ * stores the result one byte per character when it is ASCII.
+ */
+export function copyOf(s: string): string {
+  return Buffer.from(s, "utf16le").toString("utf16le");
+}
+
+let table = new Map<string, string>();
+
+/** The shared copy of `s`, creating it on first sight. */
+export function intern(s: string): string {
+  const hit = table.get(s);
+  if (hit !== undefined) return hit;
+  // Keyed by the COPY: keying by `s` would leave the table itself holding the
+  // sliced string, i.e. the file text this exists to release.
+  const copy = copyOf(s);
+  table.set(copy, copy);
+  return copy;
+}
+
+/**
+ * Drop the shared copies. Called when the index is rebuilt from scratch: the
+ * old index's strings die with it, and keeping their table entries alive would
+ * retain a whole workspace's identifiers for nothing.
+ */
+export function resetInternTable(): void {
+  table = new Map();
+}
+
+/** Distinct identifiers currently shared (perf trace). */
+export function internedCount(): number {
+  return table.size;
+}
+
+/**
+ * A definition `value` is either a short hint that repeats across the workspace
+ * (`chain:immediate`, a scripted list's `base`) or a loc line, which is unique.
+ */
+function shareValue(s: string): string {
+  return s.length <= 32 ? intern(s) : copyOf(s);
+}
+
+/** Share the strings a batch of definitions will hold for the index's lifetime. */
+export function shareDefinitionStrings(defs: Definition[]): Definition[] {
+  for (const def of defs) {
+    def.name = intern(def.name);
+    if (def.value !== undefined) def.value = shareValue(def.value);
+    if (def.container !== undefined) def.container = intern(def.container);
+    if (def.params) for (let i = 0; i < def.params.length; i++) def.params[i] = intern(def.params[i]);
+    if (def.doc !== undefined) def.doc = copyOf(def.doc);
+    if (def.tags) {
+      for (const tag of def.tags) {
+        tag.tag = intern(tag.tag);
+        tag.text = copyOf(tag.text);
+      }
+    }
+    if (def.entryMode !== undefined) def.entryMode = intern(def.entryMode);
+  }
+  return defs;
+}
+
+/** Share the strings a batch of references will hold for the index's lifetime. */
+export function shareReferenceStrings(refs: Reference[]): Reference[] {
+  for (const ref of refs) {
+    ref.name = intern(ref.name);
+    if (ref.chain !== undefined) ref.chain = intern(ref.chain);
+  }
+  return refs;
+}

package/src/index/lazyRefs.ts

@@ -0,0 +1,145 @@
+/**
+ * On-demand reference search over roots that are NOT reference-indexed up
+ * front: vanilla and read-only dependency parents (rework plan AD-4). Keeping
+ * those out of the persistent ReferenceIndex is a memory guard (vanilla alone
+ * holds hundreds of thousands of usage sites); find-references still has to
+ * SHOW them (#3), so this scanner greps the roots for one name at a time.
+ *
+ * The scan is textual (exact-token match per line, comments stripped), not
+ * schema-driven: script values, trigger/effect arguments and loc-key values
+ * are all real usage sites even where the schema has no ref-field for the
+ * enclosing key. Column-0 keys are skipped — those are the definition sites,
+ * which the provider appends separately under includeDeclaration.
+ *
+ * Costs are bounded three ways: the per-root file list is enumerated once,
+ * lines are tokenized only when a cheap substring test hits, and results are
+ * memoized per name until the roots change. First lookup of a name pays one
+ * pass of disk reads; repeats are O(1).
+ *
+ * No `vscode` imports here: unit-tested in plain Node.
+ */
+import * as fs from "fs";
+import type { DefSource, Reference } from "@px-lsp/protocol/types";
+import { listFiles } from "@px-lsp/protocol/fsWalk";
+import { isStructuralKeyword } from "../contextKeywords";
+
+export interface LazyRefRoot {
+  root: string;
+  source: DefSource;
+}
+
+/** Memoized names kept per roots generation (FIFO eviction). */
+const CACHE_CAP = 64;
+/** Files read per event-loop turn. */
+const BATCH = 200;
+/** Result cap per name: protects the peek widget and memory from a lookup on
+ * a near-universal name; real identifiers stay far below it. */
+const MAX_REFS = 5000;
+
+const NAME_OK = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/;
+/** Identifier characters: a hit is a token only when NOT flanked by these. */
+const IDENT = /[A-Za-z0-9_.-]/;
+
+const yieldNow = () => new Promise<void>((resolve) => setImmediate(resolve));
+
+export class LazyReferenceScanner {
+  private roots: LazyRefRoot[] = [];
+  private isEngineToken?: (name: string) => boolean;
+  private fileLists = new Map<string, string[]>();
+  private cache = new Map<string, Promise<Reference[]>>();
+
+  /** Reconfigure (on reindex/settings change): drops all memoized results. */
+  setRoots(roots: LazyRefRoot[], isEngineToken?: (name: string) => boolean): void {
+    this.roots = roots;
+    this.isEngineToken = isEngineToken;
+    this.fileLists.clear();
+    this.cache.clear();
+  }
+
+  /** All usage sites of `name` across the configured roots. Engine tokens and
+   * structural grammar keywords are excluded: they appear in nearly every
+   * file, and their documentation comes from script_docs, not the index.
+   * (isStructuralKeyword, not classifyKeyword: the latter's naming-convention
+   * buckets would swallow every *_trigger-named scripted trigger, #5.) */
+  lookup(name: string): Promise<Reference[]> {
+    if (
+      this.roots.length === 0 ||
+      name.length < 2 ||
+      !NAME_OK.test(name) ||
+      isStructuralKeyword(name) ||
+      this.isEngineToken?.(name)
+    ) {
+      return Promise.resolve([]);
+    }
+    let pending = this.cache.get(name);
+    if (!pending) {
+      pending = this.scan(name);
+      // FIFO eviction: Map iteration order is insertion order.
+      if (this.cache.size >= CACHE_CAP) {
+        const oldest = this.cache.keys().next().value;
+        if (oldest !== undefined) this.cache.delete(oldest);
+      }
+      this.cache.set(name, pending);
+    }
+    return pending;
+  }
+
+  private filesOf(root: string): string[] {
+    let files = this.fileLists.get(root);
+    if (!files) this.fileLists.set(root, (files = listFiles(root, ".txt")));
+    return files;
+  }
+
+  private async scan(name: string): Promise<Reference[]> {
+    const out: Reference[] = [];
+    for (const { root } of this.roots) {
+      const files = this.filesOf(root);
+      for (let i = 0; i < files.length; i += BATCH) {
+        for (const file of files.slice(i, i + BATCH)) {
+          let content: string;
+          try {
+            content = fs.readFileSync(file, "utf8");
+          } catch {
+            continue;
+          }
+          if (!content.includes(name)) continue;
+          scanContent(content, name, file, out);
+          if (out.length >= MAX_REFS) return out.slice(0, MAX_REFS);
+        }
+        await yieldNow();
+      }
+    }
+    return out;
+  }
+}
+
+/** Exact-token occurrences of `name` in `content`, appended to `out`. */
+export function scanContent(content: string, name: string, file: string, out: Reference[]): void {
+  const lines = content.split("\n");
+  for (let lineNo = 0; lineNo < lines.length; lineNo++) {
+    let line = lines[lineNo];
+    if (!line.includes(name)) continue;
+    // Strip comments; # inside a string is rare enough to accept the miss.
+    const hash = line.indexOf("#");
+    if (hash >= 0) line = line.slice(0, hash);
+    let from = 0;
+    for (;;) {
+      const at = line.indexOf(name, from);
+      if (at < 0) break;
+      from = at + name.length;
+      if (at > 0 && IDENT.test(line[at - 1])) continue;
+      const after = line[at + name.length];
+      if (after !== undefined && IDENT.test(after)) continue;
+      // Column-0 keys are definition sites (top-level assignments), not uses.
+      if (at === 0) continue;
+      out.push({
+        name,
+        kinds: [],
+        file,
+        line: lineNo,
+        startChar: at,
+        endChar: at + name.length,
+      });
+    }
+  }
+}

package/src/index/modOrigin.ts

@@ -0,0 +1,69 @@
+/**
+ * Origin labels for definitions: the owning mod's display name (descriptor.mod
+ * `name=`) instead of the generic "mod"/"parent" source tag, so a hover in a
+ * multi-mod workspace says WHICH of the 20 open mods a definition comes from.
+ *
+ * No `vscode` imports: unit-tested in plain Node.
+ */
+import * as path from "path";
+import { readModName } from "@px-lsp/protocol/modName";
+
+/** Hover head lines stay compact: clip pathological descriptor names. */
+const MAX_LABEL = 40;
+
+function clip(name: string): string {
+  return name.length > MAX_LABEL ? `${name.slice(0, MAX_LABEL - 1)}…` : name;
+}
+
+export class ModOriginResolver {
+  /** Longest prefix first, so a mod nested under another root wins. */
+  private roots: Array<{ root: string; prefix: string; label: string }> = [];
+
+  /** `modRoots`: every mod root (primary mod, workspace mods, parents).
+   *  Descriptor names are read once here, not per lookup. */
+  setRoots(modRoots: string[]): void {
+    this.roots = modRoots
+      .map((root) => ({
+        root,
+        prefix:
+          path
+            .normalize(root)
+            .toLowerCase()
+            .replace(/[\\/]+$/, "") + path.sep,
+        label: clip(readModName(root)),
+      }))
+      .sort((a, b) => b.prefix.length - a.prefix.length);
+  }
+
+  private entryFor(file: string): { root: string; prefix: string; label: string } | null {
+    if (!file || !path.isAbsolute(file)) return null;
+    const lower = path.normalize(file).toLowerCase();
+    for (const r of this.roots) {
+      if (lower.startsWith(r.prefix)) return r;
+    }
+    return null;
+  }
+
+  /** Display label for a definition's origin. Falls back to `source` when the
+   *  file lies under no known mod root (vanilla, engine, synthetic defs). */
+  labelFor(file: string, source: string): string {
+    return this.entryFor(file)?.label ?? source;
+  }
+
+  /** The mod root (as configured) a file lives under, or null. */
+  rootFor(file: string): string | null {
+    return this.entryFor(file)?.root ?? null;
+  }
+
+  /** Display label for a known mod root ("Mod Alpha" for its path). */
+  labelForRoot(root: string): string {
+    const lower = path
+      .normalize(root)
+      .toLowerCase()
+      .replace(/[\\/]+$/, "");
+    for (const r of this.roots) {
+      if (r.prefix === lower + path.sep) return r.label;
+    }
+    return clip(readModName(root));
+  }
+}