@px-lsp/server 0.1.0

package/src/overview/eventVocabulary.ts

@@ -0,0 +1,214 @@
+/**
+ * paradox/eventVocabulary: what an event editor is allowed to offer.
+ *
+ * The graph inspector guides a new modder with dropdowns, and a dropdown is
+ * only as honest as its source. So every list here is derived from data the
+ * server already holds:
+ *
+ *   keys          the active profile's structure table (harvested `_*.info`),
+ *                 ordered by the usage counts it carries
+ *   value sets    a `values: "enum:a|b|c"` spec, or the schema's reference
+ *                 fields resolved through the definition index (`theme` ->
+ *                 every indexed event_theme, mod entries first)
+ *   effects       script_docs tokens (the user's own logs, or the bundled
+ *   triggers      wiki fallback), with the log's own description
+ *   saved scopes  the mod's own `save_scope_as` sites, from the index
+ *
+ * Nothing is hand-written, so a game patch that adds a theme or renames an
+ * effect changes the dropdown without a release. No `vscode` imports.
+ */
+import {
+  EVENT_VOCABULARY_MAX_TOKENS,
+  EVENT_VOCABULARY_MAX_VALUES,
+  type EventValueOptionsResult,
+  type EventVocabularyItem,
+  type EventVocabularyResult,
+} from "@px-lsp/protocol/protocol";
+import type { ServerData } from "../serverData";
+import type { SchemaData } from "../schema/loader";
+import type { KeySpec } from "../schema/types";
+
+/** One line is what a menu row shows; the rest is noise at that size. */
+const MAX_DOC = 220;
+
+function short(doc: string | undefined): string | undefined {
+  if (!doc) return undefined;
+  const oneLine = doc.replace(/\s+/g, " ").trim();
+  if (oneLine === "") return undefined;
+  return oneLine.length > MAX_DOC ? oneLine.slice(0, MAX_DOC - 1) + "…" : oneLine;
+}
+
+/** Structure keys of one block, most used first (freq is the harvest's count). */
+function keyItems(specs: Map<string, KeySpec> | undefined): EventVocabularyItem[] {
+  if (!specs) return [];
+  const out = [...specs.values()].sort((a, b) => (b.freq ?? 0) - (a.freq ?? 0));
+  return out.map((spec) => ({
+    value: spec.key,
+    doc: short(spec.doc),
+    hint:
+      spec.values === "block"
+        ? "block"
+        : spec.values === "bool"
+          ? "yes/no"
+          : spec.values === "loc"
+            ? "loc"
+            : undefined,
+  }));
+}
+
+export function computeEventVocabulary(
+  data: ServerData,
+  schema: SchemaData,
+  inFocus: (file: string) => boolean = () => true
+): EventVocabularyResult {
+  const blocks = schema.structures.keysByKindBlock.get("event");
+  const eventKeys = keyItems(blocks?.get(""));
+  const optionKeys = keyItems(blocks?.get("option"));
+
+  // Value sets, for the keys that have one. Two sources, in this order: a
+  // declared enumeration wins (it is the exact vocabulary), otherwise the
+  // schema's reference field names the definition kinds the index can list.
+  const values: Record<string, EventVocabularyItem[]> = {};
+  const byKind = new Map<string, EventVocabularyItem[]>();
+  const definitionsOf = (kind: string): EventVocabularyItem[] => {
+    let cached = byKind.get(kind);
+    if (cached) return cached;
+    const seen = new Set<string>();
+    const mod: EventVocabularyItem[] = [];
+    const rest: EventVocabularyItem[] = [];
+    for (const def of data.index.allDefinitions()) {
+      if (def.kind !== kind || seen.has(def.name)) continue;
+      if (def.source === "mod" && !inFocus(def.file)) continue;
+      seen.add(def.name);
+      (def.source === "mod" ? mod : rest).push({
+        value: def.name,
+        doc: short(def.doc),
+        hint: def.source === "mod" ? "this mod" : def.source,
+      });
+    }
+    mod.sort((a, b) => a.value.localeCompare(b.value));
+    rest.sort((a, b) => a.value.localeCompare(b.value));
+    cached = [...mod, ...rest].slice(0, EVENT_VOCABULARY_MAX_VALUES);
+    byKind.set(kind, cached);
+    return cached;
+  };
+
+  for (const specs of [blocks?.get(""), blocks?.get("option")]) {
+    for (const spec of specs?.values() ?? []) {
+      if (values[spec.key]) continue;
+      if (spec.values?.startsWith("enum:")) {
+        values[spec.key] = spec.values
+          .slice(5)
+          .split("|")
+          .filter((v) => v !== "")
+          .map((v) => ({ value: v }));
+        continue;
+      }
+      if (spec.values === "bool") {
+        values[spec.key] = [{ value: "yes" }, { value: "no" }];
+        continue;
+      }
+      const field = schema.refFields.get(spec.key);
+      if (!field) continue;
+      const items: EventVocabularyItem[] = [];
+      for (const kind of field.kinds) items.push(...definitionsOf(kind));
+      if (items.length > 0) values[spec.key] = items.slice(0, EVENT_VOCABULARY_MAX_VALUES);
+    }
+  }
+
+  // Engine tokens. `data.tokens` is the parsed script_docs (or the bundled wiki
+  // baseline); the reference index's non-call usage counts order them, so the
+  // effects a real corpus writes come first instead of the alphabet.
+  const effects: EventVocabularyItem[] = [];
+  const triggers: EventVocabularyItem[] = [];
+  const seenToken = new Set<string>();
+  const ranked = [...data.tokens].sort(
+    (a, b) => data.refIndex.usageCount(b.name) - data.refIndex.usageCount(a.name)
+  );
+  for (const token of ranked) {
+    const bucket = token.kind === "effect" ? effects : token.kind === "trigger" ? triggers : null;
+    if (!bucket || bucket.length >= EVENT_VOCABULARY_MAX_TOKENS) continue;
+    const key = `${token.kind}:${token.name}`;
+    if (seenToken.has(key)) continue;
+    seenToken.add(key);
+    bucket.push({
+      value: token.name,
+      doc: short(token.doc),
+      hint: token.scopes.length > 0 ? token.scopes.slice(0, 3).join(", ") : undefined,
+    });
+  }
+
+  const savedScopes: EventVocabularyItem[] = [];
+  const seenScope = new Set<string>();
+  for (const def of data.index.allDefinitions()) {
+    if (def.kind !== "saved_scope" || seenScope.has(def.name)) continue;
+    if (!inFocus(def.file)) continue;
+    seenScope.add(def.name);
+    savedScopes.push({ value: def.name, hint: def.container });
+  }
+  savedScopes.sort((a, b) => a.value.localeCompare(b.value));
+
+  return {
+    eventKeys,
+    optionKeys,
+    values,
+    effects,
+    triggers,
+    savedScopes: savedScopes.slice(0, EVENT_VOCABULARY_MAX_VALUES),
+  };
+}
+
+/**
+ * Kinds whose full listing is not a useful dropdown: sites rather than
+ * choices (loc keys, saved scopes, variables), bodies rather than values
+ * (scripted effects/triggers), and the id spaces so large a capped list
+ * would silently lie (events, on_actions, decisions — those get inline
+ * completions instead).
+ */
+const VALUE_KIND_SKIP = new Set([
+  "event",
+  "on_action",
+  "decision",
+  "loc_key",
+  "saved_scope",
+  "variable",
+  "scripted_effect",
+  "scripted_trigger",
+  "script_value",
+]);
+
+/**
+ * The value set `value` belongs to: resolve it through the definition index
+ * (`secret_cultivator` is a `secret`), then list every definition of that
+ * kind, mod entries first. Null when the value resolves to nothing
+ * enumerable — a number, yes/no, a scope chain, an unindexed name.
+ */
+export function computeValueOptions(
+  data: ServerData,
+  value: string,
+  inFocus: (file: string) => boolean = () => true
+): EventValueOptionsResult | null {
+  const name = value.trim();
+  if (name === "" || name === "yes" || name === "no") return null;
+  if (/^-?[\d.]+$/.test(name) || name.includes(":") || name.includes(".")) return null;
+  const def = data.index.lookup(name).find((d) => !VALUE_KIND_SKIP.has(d.kind));
+  if (!def) return null;
+  const seen = new Set<string>();
+  const mod: EventVocabularyItem[] = [];
+  const rest: EventVocabularyItem[] = [];
+  for (const d of data.index.allDefinitions()) {
+    if (d.kind !== def.kind || seen.has(d.name)) continue;
+    if (d.source === "mod" && !inFocus(d.file)) continue;
+    seen.add(d.name);
+    (d.source === "mod" ? mod : rest).push({
+      value: d.name,
+      doc: short(d.doc),
+      hint: d.source === "mod" ? "this mod" : d.source,
+    });
+  }
+  mod.sort((a, b) => a.value.localeCompare(b.value));
+  rest.sort((a, b) => a.value.localeCompare(b.value));
+  const items = [...mod, ...rest].slice(0, EVENT_VOCABULARY_MAX_VALUES);
+  // A single entry (the value itself) enumerates nothing worth a menu.
+  return items.length > 1 ? { kind: def.kind, items } : null;
+}

package/src/overview/locCoverage.ts

@@ -0,0 +1,138 @@
+/**
+ * paradox/locCoverage: per-language localization health for the mod —
+ * referenced-but-missing keys, defined-but-orphaned keys, and untranslated
+ * keys (value identical to the source language). Feeds the coverage tree and
+ * the translation workflow.
+ */
+import * as path from "path";
+import * as fs from "fs";
+import type { LocCoverage, LocIssue } from "@px-lsp/protocol/protocol";
+import type { SchemaEntry } from "../schema/types";
+import { listFiles } from "@px-lsp/protocol/fsWalk";
+import { detectLocFileLanguage } from "@px-lsp/protocol/translationCore";
+import { parseLoc } from "../parser";
+import type { ServerData } from "../serverData";
+
+const ISSUE_CAP = 500;
+
+interface LocEntrySite {
+  key: string;
+  value: string;
+  file: string;
+  line: number;
+}
+
+/** The mod-relative localization roots, from the profile's loc_key schema entries
+ * (some games nest localization under a load-stage folder rather than the top level). */
+function locRoots(schemaEntries: SchemaEntry[]): string[] {
+  const roots = schemaEntries.filter((e) => e.kind === "loc_key").map((e) => e.path);
+  return roots.length > 0 ? [...new Set(roots)] : ["localization"];
+}
+
+/** All loc entries in the mod, grouped per language (read fresh — mods are small). */
+function modLocByLanguage(
+  modPath: string,
+  schemaEntries: SchemaEntry[]
+): Map<string, Map<string, LocEntrySite>> {
+  const byLang = new Map<string, Map<string, LocEntrySite>>();
+  for (const root of locRoots(schemaEntries)) {
+    const locDir = path.join(modPath, root);
+    for (const file of listFiles(locDir, ".yml")) {
+      const lang = detectLocFileLanguage(file);
+      if (!lang) continue;
+      let content: string;
+      try {
+        content = fs.readFileSync(file, "utf8");
+      } catch {
+        continue;
+      }
+      let entries = byLang.get(lang);
+      if (!entries) byLang.set(lang, (entries = new Map()));
+      for (const e of parseLoc(content).entries) {
+        entries.set(e.key, { key: e.key, value: e.value, file, line: e.line });
+      }
+    }
+  }
+  return byLang;
+}
+
+export function computeLocCoverage(
+  data: ServerData,
+  modPath: string | null,
+  sourceLanguage: string,
+  schemaEntries: SchemaEntry[],
+  inFocus: (file: string) => boolean = () => true
+): LocCoverage[] {
+  if (!modPath) return [];
+  const byLang = modLocByLanguage(modPath, schemaEntries);
+  if (byLang.size === 0) return [];
+
+  // Keys this mod's script uses (recorded loc references), plus schema-required
+  // keys — both restricted to the focus mod's own files in multi-mod workspaces.
+  const referenced = new Map<string, { file: string; line: number }>();
+  for (const ref of data.refIndex.allOfKind("loc_key")) {
+    if (!inFocus(ref.file)) continue;
+    if (!referenced.has(ref.name)) referenced.set(ref.name, { file: ref.file, line: ref.line });
+  }
+  const requiredByKind = new Map<string, string[]>();
+  for (const e of schemaEntries) {
+    if (e.requiredLoc && e.requiredLoc.length > 0) requiredByKind.set(e.kind, e.requiredLoc);
+  }
+  for (const def of data.index.allDefinitions()) {
+    if (def.source !== "mod" || !inFocus(def.file)) continue;
+    const patterns = requiredByKind.get(def.kind);
+    if (!patterns) continue;
+    for (const p of patterns) {
+      const key = p.replace(/\$/g, def.name);
+      if (!referenced.has(key)) referenced.set(key, { file: def.file, line: def.line });
+    }
+  }
+
+  /** Key defined outside this mod (vanilla, parents, other workspace mods, in
+   * the configured language index)? Then it's an override/covered. */
+  const inheritedLoc = (key: string): boolean =>
+    data.index.lookupAll(key).some((d) => d.kind === "loc_key" && (d.source !== "mod" || !inFocus(d.file)));
+
+  const source = byLang.get(sourceLanguage) ?? new Map<string, LocEntrySite>();
+  const result: LocCoverage[] = [];
+
+  for (const [language, entries] of [...byLang.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+    const missing: LocIssue[] = [];
+    for (const [key, site] of referenced) {
+      if (entries.has(key)) continue;
+      if (inheritedLoc(key)) continue;
+      if (missing.length >= ISSUE_CAP) break;
+      missing.push({ key, file: site.file, line: site.line });
+    }
+
+    const orphaned: LocIssue[] = [];
+    for (const [key, site] of entries) {
+      if (referenced.has(key)) continue;
+      if (inheritedLoc(key)) continue; // overriding vanilla text is intentional
+      if (data.refIndex.lookup(key).length > 0) continue; // referenced under a non-loc kind
+      if (orphaned.length >= ISSUE_CAP) break;
+      orphaned.push({ key, file: site.file, line: site.line });
+    }
+
+    const untranslated: LocIssue[] = [];
+    if (language !== sourceLanguage) {
+      for (const [key, site] of entries) {
+        const src = source.get(key);
+        if (!src) continue;
+        // Untranslated = still the source text verbatim, OR a blank value
+        // (the translation scaffold blanks values so nothing fake ships).
+        const isCopy = src.value === site.value && site.value.trim() !== "";
+        const isBlank = site.value.trim() === "";
+        if (!isCopy && !isBlank) continue;
+        if (untranslated.length >= ISSUE_CAP) break;
+        untranslated.push({ key, file: site.file, line: site.line, value: src.value });
+      }
+    }
+
+    missing.sort((a, b) => a.key.localeCompare(b.key));
+    orphaned.sort((a, b) => a.key.localeCompare(b.key));
+    untranslated.sort((a, b) => a.key.localeCompare(b.key));
+    result.push({ language, defined: entries.size, missing, orphaned, untranslated });
+  }
+  return result;
+}

package/src/overview/modOverview.ts

@@ -0,0 +1,29 @@
+/**
+ * paradox/modOverview: the mod's content inventory by kind, for the Mod Overview
+ * tree. Definition lists are capped per kind; counts stay exact.
+ */
+import type { ModOverview, OverviewKind } from "@px-lsp/protocol/protocol";
+import type { ServerData } from "../serverData";
+
+const DEFS_CAP = 500;
+
+export function computeModOverview(
+  data: ServerData,
+  inFocus: (file: string) => boolean = () => true
+): ModOverview {
+  const byKind = new Map<string, OverviewKind>();
+  let total = 0;
+  for (const def of data.index.allDefinitions()) {
+    if (def.source !== "mod" || !inFocus(def.file)) continue;
+    total++;
+    let bucket = byKind.get(def.kind);
+    if (!bucket) byKind.set(def.kind, (bucket = { kind: def.kind, count: 0, defs: [] }));
+    bucket.count++;
+    if (bucket.defs.length < DEFS_CAP) {
+      bucket.defs.push({ name: def.name, file: def.file, line: def.line });
+    }
+  }
+  const kinds = [...byKind.values()].sort((a, b) => b.count - a.count || a.kind.localeCompare(b.kind));
+  for (const k of kinds) k.defs.sort((a, b) => a.name.localeCompare(b.name));
+  return { kinds, totalDefs: total, totalRefs: data.refIndex.size };
+}

package/src/overview/overrides.ts

@@ -0,0 +1,89 @@
+/**
+ * paradox/overrides: mod definitions that shadow vanilla or parent-mod content,
+ * annotated with the folder's load rule — script folders are last-in-or-same
+ * ("LIOS", the mod wins), GUI is first-in-only ("FIOS", vanilla wins unless
+ * the mod replaces the whole file at the same relative path). This is
+ * database_conflicts.log brought into the editor, before launch.
+ *
+ * Multi-mod workspaces: definitions of OTHER workspace mods count as shadowed
+ * sites too (labeled with their mod's name); between two enabled mods the
+ * launcher's load order decides, which we cannot know — the note says so.
+ */
+import type { OverrideInfo } from "@px-lsp/protocol/protocol";
+import type { ServerData } from "../serverData";
+
+const CAP = 2000;
+
+/** Kinds whose files load first-in-only. */
+const FIOS_KINDS = new Set(["gui_type"]);
+
+function relUnder(root: string, file: string): string | null {
+  const lower = file.toLowerCase().replace(/\\/g, "/");
+  const rootLower = root.toLowerCase().replace(/\\/g, "/").replace(/\/+$/, "");
+  return lower.startsWith(rootLower + "/") ? lower.slice(rootLower.length + 1) : null;
+}
+
+export function computeOverrides(
+  data: ServerData,
+  gamePath: string | null,
+  inFocus: (file: string) => boolean = () => true
+): OverrideInfo[] {
+  const out: OverrideInfo[] = [];
+  const seen = new Set<string>();
+
+  for (const def of data.index.allDefinitions()) {
+    if (def.source !== "mod" || !inFocus(def.file)) continue;
+    const ownRoot = data.modRootOf(def.file);
+    const dedupe = `${ownRoot ?? ""}:${def.kind}:${def.name}`;
+    if (seen.has(dedupe)) continue;
+    const shadowed = data.index
+      .lookupAll(def.name)
+      .filter(
+        (d) => d.kind === def.kind && d !== def && (d.source !== "mod" || data.modRootOf(d.file) !== ownRoot)
+      );
+    if (shadowed.length === 0) continue;
+    seen.add(dedupe);
+
+    const rule = FIOS_KINDS.has(def.kind) ? "FIOS" : "LIOS";
+    let winner: "mod" | "other" = rule === "LIOS" ? "mod" : "other";
+    let note: string | undefined;
+    if (rule === "FIOS") {
+      // Whole-file replacement at the same relative path still wins.
+      const modRel = ownRoot ? relUnder(ownRoot, def.file) : null;
+      const replacesFile =
+        modRel !== null && gamePath !== null && shadowed.some((s) => relUnder(gamePath, s.file) === modRel);
+      if (replacesFile) {
+        winner = "mod";
+        note = "whole-file replacement (same relative path)";
+      } else {
+        note = "GUI loads first-in-only: the vanilla definition wins unless the mod replaces the whole file";
+      }
+    } else if (shadowed.some((s) => s.source === "mod")) {
+      note = "another enabled mod defines this too; the launcher load order decides which wins";
+    }
+
+    out.push({
+      name: def.name,
+      kind: def.kind,
+      mod: { source: "mod", label: data.originLabel(def), file: def.file, line: def.line },
+      shadowed: shadowed.map((s) => ({
+        source:
+          s.source === "mod"
+            ? ("mod" as const)
+            : s.source === "parent"
+              ? ("parent" as const)
+              : ("vanilla" as const),
+        label: data.originLabel(s),
+        file: s.file,
+        line: s.line,
+      })),
+      rule,
+      winner,
+      note,
+    });
+    if (out.length >= CAP) break;
+  }
+
+  out.sort((a, b) => a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name));
+  return out;
+}

package/src/parseCache.ts

@@ -0,0 +1,81 @@
+/**
+ * Per-document parse cache: one CST (or loc parse) per open document version,
+ * so completion, symbols, folding, diagnostics and semantic tokens share a
+ * single parse per edit instead of each re-scanning the text.
+ *
+ * Keyed by document version (equivalent to a content hash for open documents,
+ * and cheaper). Entries are evicted when the document closes.
+ */
+import type { TextDocument } from "vscode-languageserver-textdocument";
+import { LineIndex, parseLoc, parseScript, type LocParseResult, type ParseResult } from "./parser";
+import { collectSavedScopeTypes, type InferenceContext } from "./scopes/inference";
+import type { Scope, ScopeModel } from "./scopes/model";
+
+export interface CachedParse {
+  version: number;
+  result: ParseResult;
+  lineIndex: LineIndex;
+  /** Lazily computed save_scope_as → scope types for this document version. */
+  savedScopes?: Map<string, Set<Scope> | null>;
+}
+
+export interface CachedLocParse {
+  version: number;
+  result: LocParseResult;
+  lineIndex: LineIndex;
+}
+
+const scriptCache = new Map<string, CachedParse>();
+const locCache = new Map<string, CachedLocParse>();
+
+export function getParse(document: TextDocument): CachedParse {
+  const cached = scriptCache.get(document.uri);
+  if (cached && cached.version === document.version) return cached;
+  const text = document.getText();
+  const entry: CachedParse = {
+    version: document.version,
+    result: parseScript(text),
+    lineIndex: new LineIndex(text),
+  };
+  scriptCache.set(document.uri, entry);
+  return entry;
+}
+
+export function getLocParse(document: TextDocument): CachedLocParse {
+  const cached = locCache.get(document.uri);
+  if (cached && cached.version === document.version) return cached;
+  const text = document.getText();
+  const entry: CachedLocParse = {
+    version: document.version,
+    result: parseLoc(text),
+    lineIndex: new LineIndex(text),
+  };
+  locCache.set(document.uri, entry);
+  return entry;
+}
+
+export function evictParse(uri: string): void {
+  scriptCache.delete(uri);
+  locCache.delete(uri);
+}
+
+/** Saved-scope types for a document. The save-site scan is cached per version;
+ *  `ambient` (engine-provided scopes from the file's schema entry, §B3) seeds
+ *  the collection so saves INSIDE `scope:ambient = { … }` blocks type correctly,
+ *  and `ctx` carries the per-definition root/structure/variable context.
+ *  The FIRST caller per document version bakes `ambient`/`ctx` into the cache,
+ *  so every caller must pass the file's `entry?.ambientScopes` and
+ *  `inferenceContextFor(data, entry)` (scopes/varTypes.ts) — never a subset. */
+export function getSavedScopes(
+  document: TextDocument,
+  model: ScopeModel,
+  rootScopes: Set<Scope> | null,
+  ambient?: ReadonlyArray<{ name: string; type: string }>,
+  ctx?: InferenceContext
+): Map<string, Set<Scope> | null> {
+  const entry = getParse(document);
+  if (!entry.savedScopes) {
+    entry.savedScopes = collectSavedScopeTypes(entry.result, model, rootScopes, ambient, ctx);
+  }
+  return entry.savedScopes;
+}