@px-lsp/server 0.1.0

package/src/features/rename.ts

@@ -0,0 +1,135 @@
+/**
+ * Safe rename across script and localization: definition sites + every indexed
+ * reference (scope:x, ref fields, loc-key usages). Only names whose every
+ * definition lives in the mod are renameable — renaming a vanilla override
+ * would silently un-override it.
+ */
+import {
+  ResponseError,
+  type Position,
+  type Range as LspRange,
+  type TextEdit,
+  type WorkspaceEdit,
+} from "vscode-languageserver/node";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+import { URI } from "vscode-uri";
+import * as fs from "fs";
+import type { Definition } from "@px-lsp/protocol/types";
+import { wholeNamePattern } from "@px-lsp/protocol/regex";
+import type { ServerData } from "../serverData";
+import { activeProfile } from "../games/active";
+import { wordRangeAt } from "../wordAt";
+import { getLineText } from "../documents";
+import { stripPrefix } from "./references";
+
+const VALID_NAME = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/;
+
+interface RenameTarget {
+  name: string;
+  defs: Definition[];
+  /** Range of the name under the cursor. */
+  range: LspRange;
+}
+
+function targetAt(data: ServerData, document: TextDocument, position: Position): RenameTarget {
+  const lineText = getLineText(document, position.line);
+  const range = wordRangeAt(lineText, position.character);
+  if (!range) throw new ResponseError(0, "No renameable name at the cursor.");
+  const name = stripPrefix(range.word);
+  const prefixLen = range.word.length - name.length;
+
+  const defs = data.index.lookupAll(name);
+  if (defs.length === 0) {
+    throw new ResponseError(
+      0,
+      `No indexed definition of "${name}" — only indexed names can be renamed safely.`
+    );
+  }
+  const foreign = defs.find((d) => d.source !== "mod");
+  if (foreign) {
+    throw new ResponseError(
+      0,
+      `"${name}" is defined in ${foreign.source} content; only names defined solely by the mod can be renamed.`
+    );
+  }
+  return {
+    name,
+    defs,
+    range: {
+      start: { line: position.line, character: range.start + prefixLen },
+      end: { line: position.line, character: range.end },
+    },
+  };
+}
+
+export function prepareRename(data: ServerData, document: TextDocument, position: Position): LspRange {
+  return targetAt(data, document, position).range;
+}
+
+export function provideRename(
+  data: ServerData,
+  document: TextDocument,
+  position: Position,
+  newName: string,
+  readOpenDocument: (uri: string) => TextDocument | undefined
+): WorkspaceEdit {
+  const target = targetAt(data, document, position);
+  if (!VALID_NAME.test(newName)) {
+    throw new ResponseError(0, `"${newName}" is not a valid ${activeProfile().shortName} identifier.`);
+  }
+
+  const editsByUri = new Map<string, TextEdit[]>();
+  const seen = new Set<string>();
+  const addEdit = (file: string, line: number, startChar: number, endChar: number) => {
+    const uri = URI.file(file).toString();
+    const key = `${uri}:${line}:${startChar}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    let list = editsByUri.get(uri);
+    if (!list) editsByUri.set(uri, (list = []));
+    list.push({
+      range: { start: { line, character: startChar }, end: { line, character: endChar } },
+      newText: newName,
+    });
+  };
+
+  // Reference sites carry precise ranges.
+  for (const ref of data.refIndex.lookup(target.name)) {
+    addEdit(ref.file, ref.line, ref.startChar, ref.endChar);
+  }
+
+  // Definition sites: locate the name on its recorded line.
+  for (const def of target.defs) {
+    const lineText = readLine(def, readOpenDocument);
+    if (lineText === null) continue;
+    const col = findNameOnLine(lineText, target.name);
+    if (col < 0) continue;
+    addEdit(def.file, def.line, col, col + target.name.length);
+  }
+
+  const changes: Record<string, TextEdit[]> = {};
+  for (const [uri, edits] of editsByUri) changes[uri] = edits;
+  return { changes };
+}
+
+function readLine(
+  def: Definition,
+  readOpenDocument: (uri: string) => TextDocument | undefined
+): string | null {
+  const uri = URI.file(def.file).toString();
+  const open = readOpenDocument(uri);
+  if (open) return getLineText(open, def.line);
+  try {
+    const lines = fs.readFileSync(def.file, "utf8").replace(/^/, "").split(/\r?\n/);
+    return lines[def.line] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** First word-boundary occurrence of `name` on the line. */
+function findNameOnLine(lineText: string, name: string): number {
+  const re = new RegExp(wholeNamePattern(name));
+  const m = re.exec(lineText);
+  return m ? m.index : -1;
+}

package/src/features/scopeAt.ts

@@ -0,0 +1,65 @@
+/**
+ * paradox/scopeAt: the inferred scope chain at a cursor position, for an
+ * embedder's scope status bar ("Scope: character →[every_vassal]→ character").
+ *
+ * Strictly a read-out of the AD-5 inference that completion, hover and inlay
+ * hints already run at a position — same parse cache, same canonical
+ * InferenceContext — so what a client displays can never disagree with what
+ * ranking used. Nothing here influences inference or ranking.
+ */
+import type { Position } from "vscode-languageserver/node";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+import type { ScopeAtResult, ScopeChainStep } from "@px-lsp/protocol/protocol";
+import { getParse, getSavedScopes } from "../parseCache";
+import { inferScopeAt } from "../scopes/inference";
+import { inferenceContextFor } from "../scopes/varTypes";
+import type { Scope } from "../scopes/model";
+import type { SchemaEntry } from "../schema/types";
+import type { ServerData } from "../serverData";
+
+export function computeScopeAt(
+  data: ServerData,
+  document: TextDocument,
+  position: Position,
+  rootScopes: Set<Scope> | null,
+  entry: SchemaEntry | null
+): ScopeAtResult {
+  const { result, lineIndex } = getParse(document);
+  const ictx = inferenceContextFor(data, entry);
+  const saved = getSavedScopes(document, data.scopeModel, rootScopes, entry?.ambientScopes, ictx);
+  const inference = inferScopeAt(
+    result,
+    lineIndex.offsetAt(position),
+    data.scopeModel,
+    rootScopes,
+    saved,
+    ictx
+  );
+  return {
+    scopes: list(inference.scopes),
+    chain: inference.chain.map(parseStep),
+    savedScopes: [...saved]
+      .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+      .map(([name, scopes]) => ({ name, scopes: list(scopes) })),
+  };
+}
+
+/**
+ * inferScopeAt reports its chain as display strings — the seed scope alone
+ * first, then `<key> → <scopes>` per step, with "unknown" for an unresolved
+ * set and "|" between alternatives. Splitting them back apart is what keeps
+ * this request read-only over the inference module.
+ */
+function parseStep(text: string): ScopeChainStep {
+  const sep = text.indexOf(" → ");
+  if (sep < 0) return { scopes: parseScopes(text) };
+  return { entryKeyword: text.slice(0, sep), scopes: parseScopes(text.slice(sep + 3)) };
+}
+
+function parseScopes(text: string): string[] {
+  return text === "unknown" ? [] : text.split("|");
+}
+
+function list(scopes: Set<Scope> | null): string[] {
+  return scopes ? [...scopes] : [];
+}

package/src/features/semanticTokens.ts

@@ -0,0 +1,188 @@
+/**
+ * Semantic highlighting: colors identifiers by what they actually are, using the
+ * script_docs/wiki token data and the definition index. Standard token types
+ * only, so every theme colors them without configuration.
+ *
+ * Based on the CST (comments and quoted strings are simply never visited),
+ * replacing the v0.3 per-line mask-and-regex scan.
+ */
+import { SemanticTokensBuilder } from "vscode-languageserver/node";
+import type { SemanticTokens, SemanticTokensLegend } from "vscode-languageserver/node";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+import type { TokenKind } from "@px-lsp/protocol/types";
+import type { SchemaEntry, RefField } from "../schema/types";
+import { dynamicRefKinds } from "../games/jomini/variables";
+import type { StructureIndex } from "../schema/loader";
+import type { ServerData } from "../serverData";
+import { walkStatements, type AssignmentNode, type BlockNode, type ScalarNode } from "../parser";
+import { getParse } from "../parseCache";
+
+const TOKEN_TYPES = [
+  "method", // engine effects
+  "function", // engine triggers
+  "variable", // event targets
+  "property", // modifiers
+  "macro", // scripted effects/triggers (reusable script)
+  "event", // event IDs and on_actions
+  "enumMember", // script values
+  "string", // loc keys referenced from script
+] as const;
+
+const TOKEN_MODIFIERS = ["defaultLibrary"] as const; // vanilla/engine vs mod
+
+export const SEMANTIC_LEGEND: SemanticTokensLegend = {
+  tokenTypes: [...TOKEN_TYPES],
+  tokenModifiers: [...TOKEN_MODIFIERS],
+};
+
+const TYPE_INDEX: Record<string, number> = Object.fromEntries(TOKEN_TYPES.map((t, i) => [t, i]));
+const VANILLA_BIT = 1 << 0;
+
+const ENGINE_TYPE: Record<TokenKind, string> = {
+  effect: "method",
+  trigger: "function",
+  event_target: "variable",
+  modifier: "property",
+};
+
+// Schema-driven kinds are an open set; unlisted ones read as enumMember.
+const DEF_TYPE: Record<string, string> = {
+  scripted_effect: "macro",
+  scripted_trigger: "macro",
+  event: "event",
+  on_action: "event",
+  script_value: "enumMember",
+  scripted_modifier: "property",
+  loc_key: "string",
+  saved_scope: "variable",
+  variable: "variable",
+  local_variable: "variable",
+  global_variable: "variable",
+  variable_list: "variable",
+  local_variable_list: "variable",
+  global_variable_list: "variable",
+  flag: "variable",
+  list: "variable",
+};
+const DEF_TYPE_FALLBACK = "enumMember";
+
+const IDENTIFIER_START = /^[A-Za-z_]/;
+
+export function provideSemanticTokens(
+  data: ServerData,
+  document: TextDocument,
+  refFields?: Map<string, RefField>,
+  entry?: SchemaEntry | null,
+  structures?: StructureIndex
+): SemanticTokens {
+  const { result, lineIndex } = getParse(document);
+  const builder = new SemanticTokensBuilder();
+  const byBlock = entry?.kind && structures ? structures.keysByKindBlock.get(entry.kind) : undefined;
+
+  const pushScalar = (scalar: ScalarNode, expectedKinds?: string[]) => {
+    if (scalar.quoted) return;
+    let word = scalar.text;
+    if (!IDENTIFIER_START.test(word)) return;
+    // For prefixed references (scope:x, culture:czech) classify the prefix only —
+    // the grammar colors the whole reference, we refine the head word.
+    const colon = word.indexOf(":");
+    if (colon >= 0) word = word.slice(0, colon);
+    if (word === "") return;
+    const classified = classify(data, word, colon >= 0 ? undefined : expectedKinds);
+    if (!classified) return;
+    const pos = lineIndex.positionAt(scalar.range.start);
+    builder.push(pos.line, pos.character, word.length, classified.type, classified.modifiers);
+  };
+
+  /** Kinds a ref field expects for values under `key` (scalar or list form). */
+  const fieldKinds = (key: ScalarNode, form: "scalar" | "list"): string[] | undefined => {
+    if (key.quoted) return undefined;
+    const field = refFields?.get(key.text);
+    if (!field) {
+      // Pattern families (has_*_flag, is_in_list) — scalar form only.
+      return refFields && form === "scalar" ? (dynamicRefKinds(key.text) ?? undefined) : undefined;
+    }
+    return field.form !== (form === "scalar" ? "list" : "scalar") ? field.kinds : undefined;
+  };
+
+  /** `type = character_event`: the value is a member of the key's structure enum. */
+  const isEnumMember = (
+    key: ScalarNode,
+    value: ScalarNode,
+    ancestors: readonly (AssignmentNode | BlockNode)[]
+  ): boolean => {
+    if (!byBlock || key.quoted || value.quoted) return false;
+    const named = ancestors.filter((a): a is AssignmentNode => a.kind === "assignment" && !a.key.quoted);
+    if (named.length === 0) return false;
+    const keys =
+      named.length === 1 ? byBlock.get("") : byBlock.get(named[named.length - 1].key.text.toLowerCase());
+    const spec = keys?.get(key.text);
+    if (!spec?.values?.startsWith("enum:")) return false;
+    return spec.values.slice(5).split("|").includes(value.text);
+  };
+
+  const pushAs = (scalar: ScalarNode, type: string, modifiers: number) => {
+    const pos = lineIndex.positionAt(scalar.range.start);
+    builder.push(pos.line, pos.character, scalar.text.length, TYPE_INDEX[type], modifiers);
+  };
+
+  walkStatements(result.root, (stmt, ancestors) => {
+    if (stmt.kind === "assignment") {
+      pushScalar(stmt.key);
+      if (stmt.value?.kind === "scalar") {
+        const key = stmt.key;
+        const value = stmt.value;
+        if (!key.quoted && key.text === "namespace" && !value.quoted && IDENTIFIER_START.test(value.text)) {
+          // Event namespaces read as the event family.
+          pushAs(value, "event", 0);
+        } else if (isEnumMember(key, value, ancestors)) {
+          pushAs(value, "enumMember", VANILLA_BIT);
+        } else {
+          pushScalar(value, fieldKinds(key, "scalar"));
+        }
+      }
+      if (stmt.value?.kind === "tagged-block") pushScalar(stmt.value.tag);
+    } else if (stmt.value.kind === "scalar") {
+      // Bare list element: the owning assignment is two frames up (assignment, block).
+      const parent = ancestors.length >= 2 ? ancestors[ancestors.length - 2] : undefined;
+      const kinds = parent?.kind === "assignment" ? fieldKinds(parent.key, "list") : undefined;
+      pushScalar(stmt.value, kinds);
+    } else if (stmt.value.kind === "tagged-block") {
+      pushScalar(stmt.value.tag);
+    }
+  });
+
+  return builder.build();
+}
+
+function classify(
+  data: ServerData,
+  word: string,
+  expectedKinds?: string[]
+): { type: number; modifiers: number } | null {
+  // A ref-field value names a definition of a known kind — that reading wins
+  // over a same-named engine token (`theme = faith` is an event theme, not the
+  // faith event target).
+  if (expectedKinds) {
+    const match = data.index.lookup(word).find((d) => expectedKinds.includes(d.kind));
+    if (match) {
+      return {
+        type: TYPE_INDEX[DEF_TYPE[match.kind] ?? DEF_TYPE_FALLBACK],
+        modifiers: match.source === "mod" ? 0 : VANILLA_BIT,
+      };
+    }
+  }
+  const tokens = data.tokenMap.get(word);
+  if (tokens && tokens.length > 0) {
+    return { type: TYPE_INDEX[ENGINE_TYPE[tokens[0].kind]], modifiers: VANILLA_BIT };
+  }
+  const defs = data.index.lookup(word);
+  if (defs.length > 0) {
+    const def = defs[0];
+    return {
+      type: TYPE_INDEX[DEF_TYPE[def.kind] ?? DEF_TYPE_FALLBACK],
+      modifiers: def.source === "mod" ? 0 : VANILLA_BIT,
+    };
+  }
+  return null;
+}

package/src/features/signatureHelp.ts

@@ -0,0 +1,72 @@
+/**
+ * Signature help for scripted effects/triggers with $PARAM$ parameters,
+ * harvested at index time: inside `my_effect = { PARAM = ... }` call blocks
+ * the parameter list is shown with the active parameter highlighted.
+ */
+import type { Position, SignatureHelp } from "vscode-languageserver/node";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+import type { ServerData } from "../serverData";
+import { getParse } from "../parseCache";
+import { nodeAtOffset, type Statement } from "../parser";
+import { getLineText } from "../documents";
+
+export function provideSignatureHelp(
+  data: ServerData,
+  document: TextDocument,
+  position: Position
+): SignatureHelp | null {
+  const { result, lineIndex } = getParse(document);
+  const offset = lineIndex.offsetAt(position);
+  const hit = nodeAtOffset(result.root, offset);
+  if (!hit) return null;
+
+  // Innermost enclosing assignment whose key is a parameterized definition.
+  for (let i = hit.path.length - 1; i >= 0; i--) {
+    const stmt: Statement = hit.path[i];
+    if (stmt.kind !== "assignment" || stmt.key.quoted) continue;
+    if (stmt.value?.kind !== "block") continue;
+    if (offset <= stmt.value.openBrace) continue;
+    const defs = data.index.lookup(stmt.key.text);
+    const def = defs.find((d) => d.params && d.params.length > 0);
+    if (!def || !def.params) continue;
+
+    const params = def.params;
+    const label = `${def.name} = { ${params.map((p) => `${p} = …`).join(" ")} }`;
+
+    // Active parameter: the key being written on the current line, if it matches.
+    const lineText = getLineText(document, position.line);
+    const keyMatch = /([A-Za-z0-9_]+)\s*=?[^=]*$/.exec(lineText.slice(0, position.character));
+    let active = 0;
+    if (keyMatch) {
+      const idx = params.indexOf(keyMatch[1]);
+      if (idx >= 0) active = idx;
+    }
+
+    // Align PdxDoc `@param NAME desc` tags (§E3) to the $PARAM$ names by NAME, so
+    // the active parameter shows its description. Fail-soft: no doc → no text.
+    const paramDoc = new Map<string, string>();
+    for (const t of def.tags ?? []) {
+      if (t.tag !== "param") continue;
+      const m = /^(\S+)\s*(.*)$/.exec(t.text);
+      if (m && m[2].trim()) paramDoc.set(m[1], m[2].trim());
+    }
+
+    const prose = def.doc ? `${def.doc}\n\n` : "";
+
+    return {
+      signatures: [
+        {
+          label,
+          documentation: `${prose}${def.kind.replace(/_/g, " ")} (${def.source}) with ${params.length} parameter(s)`,
+          parameters: params.map((p) => {
+            const desc = paramDoc.get(p);
+            return desc ? { label: `${p} = …`, documentation: desc } : { label: `${p} = …` };
+          }),
+        },
+      ],
+      activeSignature: 0,
+      activeParameter: active,
+    };
+  }
+  return null;
+}