@px-lsp/server 0.1.0

package/src/features/definition.ts

@@ -0,0 +1,84 @@
+/**
+ * Go-to-definition for script identifiers: every source is listed (a mod
+ * override AND the vanilla/parent originals), mod definitions first. Showing
+ * the shadowed sites too is deliberate — an unintended override of a vanilla
+ * or parent-mod name is exactly what a modder wants to notice (#4, #5).
+ */
+import type { Location, Position } from "vscode-languageserver/node";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+import { URI } from "vscode-uri";
+import type { Definition, DefSource } from "@px-lsp/protocol/types";
+import type { ServerData } from "../serverData";
+import { wordRangeAt } from "../wordAt";
+import { getLineText } from "../documents";
+import { datafunctionExprAt } from "./datafunction";
+
+export function provideDefinition(
+  data: ServerData,
+  document: TextDocument,
+  position: Position,
+  /** Definitions extracted from the OPEN document itself: the index-free net
+   * for same-file declarations (inline scripted_triggers in a vanilla file
+   * whose index is stale, missing, or still building — #5). */
+  docDefs?: (word: string) => Definition[]
+): Location[] {
+  const range = wordRangeAt(getLineText(document, position.line), position.character);
+  if (!range) return [];
+  const locations = lookupLocations(data, range.word);
+  if (locations.length > 0 || !docDefs) return locations;
+  return docDefs(range.word).map((d) => ({
+    uri: document.uri,
+    range: { start: { line: d.line, character: 0 }, end: { line: d.line, character: 0 } },
+  }));
+}
+
+/**
+ * Go-to-definition inside localization values, for [ ... ] datafunction
+ * expressions only: `Custom2('RelationToMe', …)` jumps to the customizable
+ * localization, `scope_name.GetHerHis` chain segments to save sites, etc.
+ * Plain loc-key navigation stays with the client-side provider.
+ */
+export function provideLocDefinition(
+  data: ServerData,
+  document: TextDocument,
+  position: Position
+): Location[] {
+  const lineText = getLineText(document, position.line);
+  // Only inside an unclosed [ before the cursor — i.e. within an expression.
+  if (datafunctionExprAt(lineText.slice(0, position.character)) === null) return [];
+  const isWord = (ch: string) => /[A-Za-z0-9_]/.test(ch);
+  let start = position.character;
+  while (start > 0 && isWord(lineText[start - 1])) start--;
+  let end = position.character;
+  while (end < lineText.length && isWord(lineText[end])) end++;
+  const word = lineText.slice(start, end);
+  if (word.length === 0) return [];
+  const locations = lookupLocations(data, word);
+  // Quoted arguments ('RelationToMe') are most often custom loc names: when
+  // both meanings exist, prefer the customizable_localization definitions.
+  if (lineText[start - 1] === "'" && locations.length > 1) {
+    const custom = orderedDefs(data, word).filter((d) => d.kind === "customizable_localization");
+    if (custom.length > 0) {
+      return custom.map((d) => toLocation(d.file, d.line));
+    }
+  }
+  return locations;
+}
+
+/** Mod first, then parent, then vanilla; insertion order within a source. */
+const SOURCE_ORDER: Record<DefSource, number> = { mod: 0, parent: 1, vanilla: 2 };
+
+function orderedDefs(data: ServerData, word: string) {
+  return [...data.index.lookupAll(word)].sort((a, b) => SOURCE_ORDER[a.source] - SOURCE_ORDER[b.source]);
+}
+
+function lookupLocations(data: ServerData, word: string): Location[] {
+  return orderedDefs(data, word).map((d) => toLocation(d.file, d.line));
+}
+
+function toLocation(file: string, line: number): Location {
+  return {
+    uri: URI.file(file).toString(),
+    range: { start: { line, character: 0 }, end: { line, character: 0 } },
+  };
+}

package/src/features/diagnostics.ts

@@ -0,0 +1,244 @@
+/**
+ * Structural diagnostics: the silent-failure class that makes the game ignore
+ * content with zero error output. Everything here is *certain* — semantic
+ * validation stays the tiger validator's job (rework plan AD-5/6).
+ *
+ * Each diagnostic carries a stable code; docs/diagnostics/<code>.md explains
+ * the in-game consequence. The `source` label and game-name prose come from
+ * the active profile.
+ */
+import { DiagnosticSeverity, type Diagnostic } from "vscode-languageserver/node";
+import type { LineIndex, LocParseResult, ParseResult, Range } from "../parser";
+import type { Definition, Reference } from "@px-lsp/protocol/types";
+import type { SchemaEntry } from "../schema/types";
+import type { ServerData } from "../serverData";
+import { activeProfile } from "../games/active";
+
+export interface FileContext {
+  /** Absolute path of the file on disk. */
+  fsPath: string;
+  /** The mod root, when known — folder-layout checks only apply to mod files. */
+  modPath: string | null;
+  /** Whether the file on disk starts with a UTF-8 BOM; null = unknown/unsaved. */
+  bomOnDisk: boolean | null;
+}
+
+function isUnder(root: string | null, file: string): boolean {
+  if (!root) return false;
+  const norm = (p: string) => p.replace(/\\/g, "/").toLowerCase().replace(/\/+$/, "");
+  const f = norm(file);
+  const r = norm(root);
+  return f.startsWith(r + "/");
+}
+
+/** Path of `file` relative to the mod root, forward slashes, lowercase; null when outside. */
+function modRelPath(ctx: FileContext): string | null {
+  if (!isUnder(ctx.modPath, ctx.fsPath)) return null;
+  return ctx.fsPath
+    .replace(/\\/g, "/")
+    .slice(ctx.modPath!.replace(/\\/g, "/").replace(/\/+$/, "").length + 1)
+    .toLowerCase();
+}
+
+function diag(
+  range: { start: { line: number; character: number }; end: { line: number; character: number } },
+  severity: DiagnosticSeverity,
+  code: string,
+  message: string
+): Diagnostic {
+  return { range, severity, code, message, source: activeProfile().diagnosticSource };
+}
+
+function toRange(lines: LineIndex, range: Range) {
+  return { start: lines.positionAt(range.start), end: lines.positionAt(range.end) };
+}
+
+const TOP_OF_FILE = { start: { line: 0, character: 0 }, end: { line: 0, character: 200 } };
+
+// ---- script files ------------------------------------------------------------
+
+const SCRIPT_ERROR_SEVERITY: Record<string, DiagnosticSeverity> = {
+  "unclosed-brace": DiagnosticSeverity.Error,
+  "stray-close": DiagnosticSeverity.Error,
+  "unterminated-string": DiagnosticSeverity.Warning,
+  "missing-value": DiagnosticSeverity.Warning,
+};
+
+function scriptErrorHint(code: string): string {
+  const game = activeProfile().shortName;
+  if (code === "unclosed-brace")
+    return ` ${game} silently ignores everything in the file after an unbalanced brace.`;
+  if (code === "stray-close") return ` ${game} may misread the rest of the file.`;
+  return "";
+}
+
+export function computeScriptDiagnostics(
+  parse: ParseResult,
+  lines: LineIndex,
+  ctx: FileContext
+): Diagnostic[] {
+  const out: Diagnostic[] = [];
+
+  for (const err of parse.errors) {
+    const severity = SCRIPT_ERROR_SEVERITY[err.code] ?? DiagnosticSeverity.Warning;
+    out.push(diag(toRange(lines, err.range), severity, err.code, err.message + scriptErrorHint(err.code)));
+  }
+
+  const rel = modRelPath(ctx);
+  if (rel) {
+    // Only games whose schema reads common/on_action (singular) get the
+    // plural-folder trap check (in other games the plural IS the real folder).
+    const singular = activeProfile().schema.some((e) => e.path === "common/on_action");
+    if (singular && rel.startsWith("common/on_actions/")) {
+      out.push(
+        diag(
+          TOP_OF_FILE,
+          DiagnosticSeverity.Error,
+          "wrong-on-action-folder",
+          `This file is under common/on_actions/ — ${activeProfile().shortName} reads common/on_action/ (singular). The game silently ignores this file.`
+        )
+      );
+    }
+  }
+
+  return out;
+}
+
+// ---- index-backed conservative checks (mod content only) ----------------------
+
+/**
+ * Unknown event references — only for namespaces the mod itself declares, so
+ * vanilla/DLC content can never false-positive (rework plan Phase 2).
+ */
+export function computeReferenceDiagnostics(references: Reference[], data: ServerData): Diagnostic[] {
+  const out: Diagnostic[] = [];
+  for (const ref of references) {
+    if (!ref.kinds.includes("event")) continue;
+    const dot = ref.name.indexOf(".");
+    if (dot <= 0) continue;
+    const ns = ref.name.slice(0, dot);
+    if (!data.modNamespaces.has(ns)) continue;
+    if (data.index.lookupAll(ref.name).length > 0) continue;
+    out.push(
+      diag(
+        {
+          start: { line: ref.line, character: ref.startChar },
+          end: { line: ref.line, character: ref.endChar },
+        },
+        DiagnosticSeverity.Warning,
+        "unknown-event",
+        `Event "${ref.name}" is not defined anywhere, but its namespace "${ns}" belongs to this mod. Triggering it will silently do nothing.`
+      )
+    );
+  }
+  return out;
+}
+
+/** Schema-declared required localization keys missing for mod definitions. */
+export function computeRequiredLocDiagnostics(
+  defs: Definition[],
+  entry: SchemaEntry,
+  data: ServerData
+): Diagnostic[] {
+  const patterns = entry.requiredLoc ?? [];
+  if (patterns.length === 0) return [];
+  const out: Diagnostic[] = [];
+  for (const def of defs) {
+    if (def.source !== "mod") continue;
+    for (const pattern of patterns) {
+      const key = pattern.replace(/\$/g, def.name);
+      if (data.index.lookup(key).some((d) => d.kind === "loc_key")) continue;
+      const d = diag(
+        { start: { line: def.line, character: 0 }, end: { line: def.line, character: 200 } },
+        DiagnosticSeverity.Warning,
+        "missing-required-loc",
+        `Missing localization key "${key}" — ${entry.kind.replace(/_/g, " ")} definitions show raw keys in game without it.`
+      );
+      d.data = { key };
+      out.push(d);
+    }
+  }
+  return out;
+}
+
+// ---- localization files --------------------------------------------------------
+
+const LOC_ERROR_SEVERITY: Record<string, DiagnosticSeverity> = {
+  "no-header": DiagnosticSeverity.Error,
+  "bad-entry": DiagnosticSeverity.Warning,
+  "tab-indent": DiagnosticSeverity.Error,
+  "unterminated-value": DiagnosticSeverity.Warning,
+  "content-before-header": DiagnosticSeverity.Warning,
+};
+
+function locErrorHint(code: string): string {
+  if (code === "no-header") return " Without an l_<language>: header the game loads none of these entries.";
+  if (code === "tab-indent")
+    return ` ${activeProfile().shortName} rejects tab indentation in localization files.`;
+  return "";
+}
+
+const FILENAME_LANG = /_l_([a-z_]+)\.ya?ml$/i;
+
+export function computeLocDiagnostics(loc: LocParseResult, lines: LineIndex, ctx: FileContext): Diagnostic[] {
+  const out: Diagnostic[] = [];
+
+  for (const err of loc.errors) {
+    const severity = LOC_ERROR_SEVERITY[err.code] ?? DiagnosticSeverity.Warning;
+    out.push(
+      diag(toRange(lines, err.range), severity, `loc-${err.code}`, err.message + locErrorHint(err.code))
+    );
+  }
+
+  // BOM is checked against the bytes on disk (editors strip it from the buffer text).
+  if (ctx.bomOnDisk === false) {
+    out.push(
+      diag(
+        TOP_OF_FILE,
+        DiagnosticSeverity.Error,
+        "missing-bom",
+        `This localization file has no UTF-8 BOM. ${activeProfile().shortName} requires UTF-8 with BOM; without it the game ignores the file. Save with encoding "UTF-8 with BOM".`
+      )
+    );
+  }
+
+  const basename = ctx.fsPath.replace(/\\/g, "/").split("/").pop() ?? "";
+  const fileLang = FILENAME_LANG.exec(basename)?.[1]?.toLowerCase() ?? null;
+  if (loc.language !== null && fileLang !== null && loc.language.toLowerCase() !== fileLang) {
+    const range = loc.headerRange ? toRange(lines, loc.headerRange) : TOP_OF_FILE;
+    out.push(
+      diag(
+        range,
+        DiagnosticSeverity.Error,
+        "loc-header-mismatch",
+        `Header l_${loc.language}: does not match the filename marker _l_${fileLang}.yml — the game will not load these entries.`
+      )
+    );
+  }
+
+  const rel = modRelPath(ctx);
+  if (rel) {
+    if (fileLang === null && rel.startsWith("localization/")) {
+      out.push(
+        diag(
+          TOP_OF_FILE,
+          DiagnosticSeverity.Error,
+          "loc-bad-filename",
+          `Localization files must end in _l_<language>.yml (e.g. ${basename.replace(/\.ya?ml$/i, "")}_l_english.yml); the game silently ignores this file.`
+        )
+      );
+    }
+    if (rel.startsWith("localisation/")) {
+      out.push(
+        diag(
+          TOP_OF_FILE,
+          DiagnosticSeverity.Error,
+          "wrong-localization-folder",
+          `This folder is localisation/ (British spelling) — ${activeProfile().shortName} reads localization/. The game silently ignores this file.`
+        )
+      );
+    }
+  }
+
+  return out;
+}

package/src/features/folding.ts

@@ -0,0 +1,106 @@
+/**
+ * Folding ranges from the CST: every `{}` block spanning multiple lines, plus
+ * runs of consecutive comment lines. Serves every brace language the client
+ * routes here (script, .gui, and the descriptor/format-doc languages). The
+ * provider being registered means VS Code never falls back to indentation
+ * folding, so returning [] for a routed language actively disables folding
+ * there. Loc files have no braces; they
+ * fold the `l_<lang>:` body and comment banners instead.
+ */
+import { FoldingRangeKind, type FoldingRange } from "vscode-languageserver/node";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+import { walkStatements, type BlockNode, type Statement } from "../parser";
+import { getLocParse, getParse } from "../parseCache";
+
+function blockOf(stmt: Statement): BlockNode | null {
+  const v = stmt.value;
+  if (!v) return null;
+  if (v.kind === "block") return v;
+  if (v.kind === "tagged-block") return v.block;
+  return null;
+}
+
+/** Comment banners: 2+ consecutive full-line comments fold as one region. */
+function commentRuns(lines: { line: number; atLineStart: boolean }[]): FoldingRange[] {
+  const ranges: FoldingRange[] = [];
+  let runStart = -1;
+  let prevLine = -2;
+  const flush = (lastLine: number) => {
+    if (runStart >= 0 && lastLine > runStart) {
+      ranges.push({ startLine: runStart, endLine: lastLine, kind: FoldingRangeKind.Comment });
+    }
+    runStart = -1;
+  };
+  for (const c of lines) {
+    if (!c.atLineStart) continue;
+    if (c.line === prevLine + 1 && runStart >= 0) {
+      prevLine = c.line;
+      continue;
+    }
+    flush(prevLine);
+    runStart = c.line;
+    prevLine = c.line;
+  }
+  flush(prevLine);
+  return ranges;
+}
+
+export function provideFoldingRanges(document: TextDocument): FoldingRange[] {
+  if (document.languageId === "paradox-loc") return locFoldingRanges(document);
+  const { result, lineIndex } = getParse(document);
+  const ranges: FoldingRange[] = [];
+
+  walkStatements(result.root, (stmt) => {
+    const block = blockOf(stmt);
+    if (!block) return;
+    const startLine = lineIndex.positionAt(block.openBrace).line;
+    // Keep the closing brace visible when folded; an unclosed block (parser
+    // recovery, range.end = EOF) has no brace to keep visible, so it folds
+    // through its last line.
+    const endLine =
+      block.closeBrace != null
+        ? lineIndex.positionAt(block.closeBrace).line - 1
+        : lineIndex.positionAt(block.range.end).line;
+    if (endLine > startLine) ranges.push({ startLine, endLine });
+  });
+
+  ranges.push(
+    ...commentRuns(
+      result.comments.map((c) => ({
+        line: c.line,
+        atLineStart: lineIndex.positionAt(c.range.start).character === 0,
+      }))
+    )
+  );
+
+  return ranges;
+}
+
+function locFoldingRanges(document: TextDocument): FoldingRange[] {
+  const { result, lineIndex } = getLocParse(document);
+  const ranges: FoldingRange[] = [];
+  // The language body: header line down to the last entry.
+  if (result.headerRange && result.entries.length > 0) {
+    const startLine = lineIndex.positionAt(result.headerRange.start).line;
+    const last = result.entries[result.entries.length - 1];
+    const endLine = lineIndex.positionAt(last.valueRange.end).line;
+    if (endLine > startLine) ranges.push({ startLine, endLine });
+  }
+  // Comment banners, by raw line scan (the loc parser keeps no comment list).
+  // Vanilla indents body comments by one space, so any whitespace-then-`#`
+  // line counts, matching the loc parser's own comment definition; a line-0
+  // BOM is stripped first (line numbers are unaffected).
+  const lines = document
+    .getText()
+    .replace(/^\uFEFF/, "")
+    .split("\n");
+  ranges.push(
+    ...commentRuns(
+      lines
+        .map((text, line) => ({ line, text }))
+        .filter(({ text }) => /^[ \t]*#/.test(text))
+        .map(({ line }) => ({ line, atLineStart: true }))
+    )
+  );
+  return ranges;
+}

package/src/features/formatting.ts

@@ -0,0 +1,60 @@
+/**
+ * Conservative formatter (rework plan Phase 5): indentation only — one tab per
+ * brace depth, computed from the lexer so strings and comments can never fool
+ * it. Nothing but leading whitespace is ever touched, which makes idempotence
+ * trivial and the diff reviewable.
+ */
+import type { TextEdit } from "vscode-languageserver/node";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+import { LineIndex, tokenize } from "../parser";
+
+export function provideFormattingEdits(document: TextDocument): TextEdit[] {
+  const text = document.getText();
+  const lines = new LineIndex(text);
+  const tokens = tokenize(text);
+
+  // Depth at the start of each line, and whether the line's first token closes.
+  const openBefore: number[] = new Array(lines.lineCount).fill(0);
+  const closersAtStart: number[] = new Array(lines.lineCount).fill(0);
+  let depth = 0;
+  let tokenIdx = 0;
+  for (let line = 0; line < lines.lineCount; line++) {
+    openBefore[line] = depth;
+    const lineEnd = line + 1 < lines.lineCount ? lines.lineStart(line + 1) : text.length;
+    let leadingClosers = 0;
+    let sawNonCloser = false;
+    while (tokenIdx < tokens.length && tokens[tokenIdx].start < lineEnd) {
+      const t = tokens[tokenIdx];
+      if (t.kind === "lbrace") {
+        depth++;
+        sawNonCloser = true;
+      } else if (t.kind === "rbrace") {
+        depth = Math.max(0, depth - 1);
+        if (!sawNonCloser) leadingClosers++;
+      } else if (t.kind !== "eof") {
+        sawNonCloser = true;
+      }
+      tokenIdx++;
+    }
+    closersAtStart[line] = leadingClosers;
+  }
+
+  const edits: TextEdit[] = [];
+  for (let line = 0; line < lines.lineCount; line++) {
+    const start = lines.lineStart(line);
+    const end = line + 1 < lines.lineCount ? lines.lineStart(line + 1) : text.length;
+    const lineText = text.slice(start, end).replace(/\r?\n$/, "");
+    if (lineText.trim() === "") continue; // blank lines stay untouched
+    const current = /^[\t ]*/.exec(lineText)![0];
+    const target = "\t".repeat(Math.max(0, openBefore[line] - closersAtStart[line]));
+    if (current === target) continue;
+    edits.push({
+      range: {
+        start: { line, character: 0 },
+        end: { line, character: current.length },
+      },
+      newText: target,
+    });
+  }
+  return edits;
+}