@px-lsp/server 0.1.0

package/src/contextKeywords.ts

@@ -0,0 +1,224 @@
+/**
+ * Static keyword-to-context table for block-context detection.
+ *
+ * Extending behavior is a one-line change here; the walking logic in context.ts
+ * never needs to be touched. Keywords are matched lowercase.
+ */
+
+/** Blocks whose direct content is written in trigger grammar. */
+export const TRIGGER_BLOCK_KEYWORDS = new Set<string>([
+  "trigger",
+  "limit",
+  "alternative_limit",
+  "potential",
+  "allow",
+  "is_shown",
+  "is_valid",
+  "is_valid_showing_failures_only",
+  "can_start",
+  "can_join",
+  "can_pick",
+  "can_pick_phase",
+  "is_highlighted",
+  "valid",
+  "filter",
+  "trigger_if",
+  "trigger_else_if",
+  "trigger_else",
+  "calc_true_if",
+  "custom_description", // contains a trigger plus text/subject keys
+  "modifier", // mtth/chance modifier blocks contain triggers (+ add/factor)
+  "compare_modifier",
+  "opinion_modifier",
+  "is_visible",
+  "is_valid_demand",
+  "can_send",
+  "can_be_picked",
+  "can_be_picked_title",
+  "on_invalidated_trigger",
+  "cancellation_trigger",
+  "hidden_trigger",
+  "show_as_tooltip_trigger",
+]);
+
+/** Blocks whose direct content is written in effect grammar. */
+export const EFFECT_BLOCK_KEYWORDS = new Set<string>([
+  "effect",
+  "immediate",
+  "after",
+  "option", // options mix metadata keys with effects; effect is the useful default
+  "on_accept",
+  "on_decline",
+  "on_send",
+  "on_start",
+  "on_end",
+  "on_join",
+  "on_leave",
+  "on_complete",
+  "on_success",
+  "on_failure",
+  "on_invalidated",
+  "on_cancel",
+  "on_monthly",
+  "on_yearly",
+  "on_activate",
+  "on_deactivate",
+  "then",
+  "fallback",
+  "hidden_effect",
+  "show_as_tooltip",
+  "random",
+  "random_list",
+  "creation_effect",
+  "removal_effect",
+  "success",
+  "abort_effect",
+]);
+
+/**
+ * Blocks whose direct content is script-value math: base/add/factor/modifier
+ * keys plus iterators — NOT effects or plain triggers. `modifier` children
+ * switch back to trigger grammar via TRIGGER_BLOCK_KEYWORDS.
+ *
+ * The math instruction keys themselves are included for their BLOCK form
+ * (`add = { value = x if = { … } }` inside an effect or trigger): a math key
+ * opening a block always contains math, wherever it appears. Scalar forms
+ * (`add = 5`) never enter the block stack, so this cannot misfire there.
+ */
+export const VALUE_BLOCK_KEYWORDS = new Set<string>([
+  "ai_chance",
+  "ai_will_do",
+  "weight",
+  "weight_multiplier",
+  "chance",
+  "ai_value",
+  "ai_will_revoke_title",
+  "join_chance",
+  "value",
+  "add",
+  "subtract",
+  "multiply",
+  "divide",
+  "modulo",
+  "min",
+  "max",
+  "base",
+  "factor",
+  "fixed_range",
+  "integer_range",
+]);
+
+/**
+ * Blocks that keep their parent's context: control flow, boolean operators and
+ * scope changes. The context walk skips over these and keeps going up.
+ */
+export const TRANSPARENT_KEYWORDS = new Set<string>([
+  "if",
+  "else_if",
+  "else",
+  "while",
+  "switch",
+  "trigger_switch",
+  "and",
+  "or",
+  "not",
+  "nor",
+  "nand",
+  "all_false",
+  "any_false",
+  "custom_tooltip",
+  "first_valid",
+  "random_valid",
+  "triggered_desc",
+  "desc",
+  "root",
+  "this",
+  "prev",
+  "from",
+  "liege",
+  "mother",
+  "father",
+  "primary_spouse",
+  "primary_title",
+  "capital_province",
+  "capital_county",
+  "faith",
+  "culture",
+  "dynasty",
+  "house",
+  "top_liege",
+  "court_owner",
+  "employer",
+  "holder",
+  "county",
+  "duchy",
+  "kingdom",
+  "empire",
+  "title_province",
+  "location",
+  "province_owner",
+  "barony",
+  "barony_controller",
+  "county_controller",
+  "religion",
+]);
+
+export type KeywordClass = "trigger" | "effect" | "value" | "transparent" | "unknown";
+
+/**
+ * True when the keyword is EXPLICITLY listed in one of the four sets above —
+ * i.e. classified by curation rather than by prefix heuristics. Scope inference
+ * uses this to divert iterator-shaped non-iterators (random_list, random_valid).
+ */
+export function isExplicitKeyword(rawKeyword: string): boolean {
+  const kw = rawKeyword.toLowerCase();
+  return (
+    TRIGGER_BLOCK_KEYWORDS.has(kw) ||
+    EFFECT_BLOCK_KEYWORDS.has(kw) ||
+    VALUE_BLOCK_KEYWORDS.has(kw) ||
+    TRANSPARENT_KEYWORDS.has(kw)
+  );
+}
+
+/**
+ * Grammar words that can never be the call site of a scripted effect/trigger:
+ * the exact keyword sets plus iterator- and prev-shaped keys. Deliberately
+ * NARROWER than classifyKeyword's "not unknown" — its naming-convention
+ * buckets (X_trigger blocks, on_X blocks) match the names modders give their
+ * scripted triggers/effects, and those keys ARE call sites (#3, #5:
+ * tribute_mission_1000_can_give_treasury_trigger = yes).
+ */
+export function isStructuralKeyword(rawKeyword: string): boolean {
+  const kw = rawKeyword.toLowerCase();
+  if (isExplicitKeyword(kw)) return true;
+  if (/^(any|every|random|ordered)_/.test(kw)) return true;
+  return /^prev+$/.test(kw);
+}
+
+export function classifyKeyword(rawKeyword: string): KeywordClass {
+  const kw = rawKeyword.toLowerCase();
+  if (TRIGGER_BLOCK_KEYWORDS.has(kw)) return "trigger";
+  if (EFFECT_BLOCK_KEYWORDS.has(kw)) return "effect";
+  if (VALUE_BLOCK_KEYWORDS.has(kw)) return "value";
+  if (TRANSPARENT_KEYWORDS.has(kw)) return "transparent";
+  // Iterators: any_* blocks are triggers; every_/random_/ordered_ blocks are effects
+  // (their `limit` child switches back to trigger and is found first by the walk).
+  if (kw.startsWith("any_")) return "trigger";
+  if (kw.startsWith("every_") || kw.startsWith("random_") || kw.startsWith("ordered_")) return "effect";
+  // Naming conventions the game's own .info docs follow: X_trigger blocks hold
+  // triggers (cancellation_trigger, ai_target_quick_trigger…); on_X blocks hold
+  // effects (on_auto_accept, on_intermediary_accept, on_blocked_effect…) —
+  // except on_action(s), which lists on_action NAMES, not effects.
+  if (kw.endsWith("_trigger")) return "trigger";
+  if (kw.startsWith("on_") && kw !== "on_action" && kw !== "on_actions") return "effect";
+  // Scope changers keep the parent context.
+  if (
+    kw.startsWith("scope:") ||
+    kw.startsWith("var:") ||
+    kw.startsWith("local_var:") ||
+    kw.startsWith("global_var:")
+  )
+    return "transparent";
+  if (/^prev+$/.test(kw)) return "transparent";
+  return "unknown";
+}

package/src/data/dataBindingMacros.ts

@@ -0,0 +1,82 @@
+/**
+ * `game/data_binding/*.txt` macros: `macro = { description = "…" definition =
+ * "IsZero(Value)" replace_with = "…" }`. These are callable inside `[ … ]`
+ * data-function expressions, so they promote into the DataTypesData knowledge
+ * as global functions (with their signature args and description).
+ *
+ * A promotion source only: a macro never overwrites a real dump/wiki global of
+ * the same name. Harvested from game (+ mod `data_binding/` if present) at
+ * startup. No `vscode` imports.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { parseScript } from "../parser";
+import { listFiles } from "@px-lsp/protocol/fsWalk";
+import type { DataTypesData } from "./dataTypes";
+
+/** Split a `Name(a,b)` signature into its function name and argument names. */
+function parseSignature(definition: string): { name: string; args: string[] } | null {
+  const paren = definition.indexOf("(");
+  if (paren < 0) {
+    const name = definition.trim();
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ? { name, args: [] } : null;
+  }
+  const name = definition.slice(0, paren).trim();
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) return null;
+  const close = definition.lastIndexOf(")");
+  const argText = definition.slice(paren + 1, close >= 0 ? close : undefined);
+  const args = argText
+    .split(",")
+    .map((a) => a.trim())
+    .filter((a) => a.length > 0);
+  return { name, args };
+}
+
+/**
+ * Harvest `data_binding/` under each root and add the macros into `into` as
+ * global functions (add-if-absent). Returns the number of macros added.
+ */
+export function loadDataBindingMacros(roots: string[], into: DataTypesData): number {
+  let added = 0;
+  for (const root of roots) {
+    for (const file of listFiles(path.join(root, "data_binding"), ".txt").sort()) {
+      let text: string;
+      try {
+        text = fs.readFileSync(file, "utf8").replace(/^/, "");
+      } catch {
+        continue;
+      }
+      const { root: parsed } = parseScript(text);
+      for (const stmt of parsed.statements) {
+        if (stmt.kind !== "assignment" || stmt.key.text.toLowerCase() !== "macro") continue;
+        if (stmt.value?.kind !== "block") continue;
+        let definition: string | null = null;
+        let description = "";
+        let replaceWith = "";
+        for (const inner of stmt.value.statements) {
+          if (inner.kind !== "assignment" || inner.value?.kind !== "scalar") continue;
+          const key = inner.key.text.toLowerCase();
+          if (key === "definition") definition = inner.value.text;
+          else if (key === "description") description = inner.value.text;
+          else if (key === "replace_with") replaceWith = inner.value.text;
+        }
+        if (!definition) continue;
+        const sig = parseSignature(definition);
+        if (!sig || into.globals.has(sig.name)) continue; // real global wins
+        const descParts: string[] = [];
+        if (description) descParts.push(description);
+        if (replaceWith) descParts.push("Expands to `" + replaceWith + "`.");
+        into.globals.set(sig.name, {
+          ret: null,
+          args: sig.args.length > 0 ? sig.args : null,
+          kind: "function",
+          src: "macro",
+          ...(descParts.length > 0 ? { desc: descParts.join("\n\n") } : {}),
+        });
+        into.count++;
+        added++;
+      }
+    }
+  }
+  return added;
+}

package/src/data/dataFnDocs.ts

@@ -0,0 +1,152 @@
+/**
+ * Descriptions for [ ... ] datafunction names. Neither the game dump nor the
+ * wiki tables carry prose, so hovers are built from two layers:
+ *
+ *  - CURATED_DOCS: hand-written docs for the small, engine-stable set of
+ *    utility functions every gui/loc file uses (And, ObjectsEqual, Concat…).
+ *    Callers only show these for names that exist in the harvested/dump data,
+ *    so a renamed engine function can never surface a stale doc.
+ *  - describeDataFn: a deduction from the name's morphology (Get→returns,
+ *    Is/Has→condition, On→command…), always available, clearly heuristic.
+ *
+ * No vscode imports: unit-tested in plain Node.
+ */
+import type { DataTypeMember } from "./dataTypes";
+
+export const CURATED_DOCS: ReadonlyMap<string, string> = new Map<string, string>([
+  // Logic
+  ["And", "Logical AND of two or more boolean arguments."],
+  ["Or", "Logical OR of two or more boolean arguments."],
+  ["Not", "Logical negation of a boolean argument."],
+  ["ObjectsEqual", "True when both arguments resolve to the same game object (compare with `.Self`)."],
+  ["IsDataModelEmpty", "True when the given data model (list) has no entries."],
+  ["GetDataModelSize", "Number of entries in the given data model (list)."],
+  // Selection / text
+  [
+    "SelectLocalization",
+    "Picks between two loc keys: `SelectLocalization( bool, key_if_true, key_if_false )`.",
+  ],
+  ["Select_CString", "Picks between two strings by a boolean: `Select_CString( bool, if_true, if_false )`."],
+  ["Concatenate", "Concatenates its string arguments into one string."],
+  ["Localize", "Looks up a localization key by name and returns its text."],
+  ["GetHerHis", "Possessive pronoun for the character (her/his). `|U` capitalizes."],
+  ["GetSheHe", "Subject pronoun for the character (she/he). `|U` capitalizes."],
+  ["GetHerHim", "Object pronoun for the character (her/him). `|U` capitalizes."],
+  [
+    "Custom",
+    "Runs a customizable localization (common/customizable_localization) on this object: `Custom('key')`.",
+  ],
+  ["Custom2", "Customizable localization taking a second scope argument: `Custom2('key', OtherScope)`."],
+  // Commands / gui plumbing
+  ["IsValidCommand", "True when the given gui command is currently allowed (drives enabled states)."],
+  ["GetCommandDesc", "Tooltip text explaining the given gui command's current state."],
+  [
+    "GetVariableSystem",
+    "The gui-local variable store; chain `.Set/.Toggle/.Exists/.HasValue` for pure-UI state.",
+  ],
+  [
+    "GetNullCharacter",
+    "An empty Character reference; used to blank a datacontext or as a comparison target.",
+  ],
+  ["EmptyScope", "An empty scope object; used to blank out a context."],
+  ["GetPlayer", "The local player's character."],
+  ["GetScriptedGui", "Looks up a scripted_gui by name: chain `.IsShown/.IsValid/.Execute` with a GuiScope."],
+  ["GuiScope", "Builds a scope bundle for scripted_gui calls: `.SetRoot(...).AddScope('name', ...).End`."],
+  [
+    "AddScope",
+    "Adds a named scope to the bundle: `AddScope( 'name', object )` (read as `scope:name` in script).",
+  ],
+  ["SetRoot", "Sets the scripted_gui's root scope in a GuiScope chain."],
+  ["MakeScope", "Wraps an object as a script scope (for GuiScope chains and scripted_gui calls)."],
+  ["End", "Finishes a GuiScope builder chain."],
+]);
+
+/** Arithmetic/compare families are generated, not listed one by one. */
+const TYPED_FAMILY =
+  /^(Add|Subtract|Multiply|Divide|Min|Max|EqualTo|NotEqualTo|LessThan|GreaterThan|LessThanOrEqualTo|GreaterThanOrEqualTo|IntTo|FixedPointTo|FloatTo)_?([A-Za-z0-9]+)?$/;
+const FAMILY_DOC: Record<string, string> = {
+  Add: "Sum of the two arguments",
+  Subtract: "First argument minus the second",
+  Multiply: "Product of the two arguments",
+  Divide: "First argument divided by the second",
+  Min: "Smaller of the two arguments",
+  Max: "Larger of the two arguments",
+  EqualTo: "True when the arguments are equal",
+  NotEqualTo: "True when the arguments differ",
+  LessThan: "True when the first argument is smaller",
+  GreaterThan: "True when the first argument is larger",
+  LessThanOrEqualTo: "True when the first argument is smaller or equal",
+  GreaterThanOrEqualTo: "True when the first argument is larger or equal",
+  IntTo: "Converts an integer",
+  FixedPointTo: "Converts a fixed-point number",
+  FloatTo: "Converts a float",
+};
+
+/** "GetHouseAspiration" → ["House", "Aspiration"]; tolerates ALL_CAPS and digits. */
+function splitWords(name: string): string[] {
+  return name
+    .replace(/_/g, " ")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+    .split(/\s+/)
+    .filter((w) => w.length > 0);
+}
+
+function lowerPhrase(words: string[]): string {
+  return words.map((w) => (/^[A-Z0-9]+$/.test(w) && w.length > 1 ? w : w.toLowerCase())).join(" ");
+}
+
+/**
+ * Curated doc when available, else a description deduced from the name.
+ * `member` sharpens the wording (promote vs function, return type) when known.
+ */
+export function describeDataFn(name: string, member: DataTypeMember | null): string | null {
+  const curated = CURATED_DOCS.get(name);
+  if (curated) return curated;
+
+  const family = TYPED_FAMILY.exec(name);
+  if (family && FAMILY_DOC[family[1]]) {
+    const suffix = family[2] ? ` (${family[2]})` : "";
+    return `${FAMILY_DOC[family[1]]}${suffix}.`;
+  }
+
+  if (/^[A-Z0-9_]+$/.test(name) && name.length > 2) {
+    return "Context promote: available where the game (event, interaction, gui datacontext…) binds this scope.";
+  }
+
+  const words = splitWords(name);
+  if (words.length < 2) return null;
+  const head = words[0];
+  const rest = lowerPhrase(words.slice(1));
+  switch (head) {
+    case "Get":
+      return `Returns the ${rest}${member?.ret ? "" : " (deduced from the name)"}.`;
+    case "Is":
+    case "Are":
+    case "Was":
+    case "Has":
+    case "Have":
+    case "Can":
+    case "Should":
+    case "Will":
+      return `Whether ${head.toLowerCase()} ${rest} (boolean, deduced from the name).`;
+    case "On":
+      return `Command: runs when triggered (button click, …) — ${rest}.`;
+    case "Set":
+    case "Toggle":
+    case "Make":
+    case "Add":
+    case "Remove":
+    case "Clear":
+    case "Open":
+    case "Close":
+    case "Show":
+    case "Hide":
+    case "Select":
+      return `Command: ${head.toLowerCase()} ${rest}.`;
+    case "Format":
+      return `Formats ${rest} as text.`;
+    default:
+      return null;
+  }
+}