@px-lsp/server 0.1.0

package/src/features/hoverRender.ts

@@ -0,0 +1,222 @@
+/**
+ * Hover markdown builders (§D). Pure string assembly, no LSP or `vscode` types,
+ * so the card layout is unit-testable in plain Node against the D2 mocks.
+ *
+ * Rendering contract (§D1): the only HTML emitted is sanitized
+ * `<span style="color:var(--vscode-*)">…</span>` — VS Code renders the color
+ * when `supportHtml` is on and strips the tag (keeping the plain text) when it
+ * is not. Every span's *content* is therefore self-sufficient plain text (a
+ * "■ trigger" badge, a scope name), so older clients degrade to markdown with
+ * no loss of meaning. Do not introduce any other HTML here.
+ */
+
+/** `--vscode-charts-*` / semantic color slot per kind family (§D2). */
+type ChartColor = "purple" | "red" | "yellow" | "green" | "orange" | "blue" | "foreground";
+
+import { hoverHtml } from "../clientMode";
+
+function colorVar(c: ChartColor): string {
+  return c === "foreground" ? "var(--vscode-charts-foreground)" : `var(--vscode-charts-${c})`;
+}
+
+/** A sanitized colored span. Content is plain text so it survives HTML stripping.
+ * Plain-markdown clients (no `client.hoverHtml`) get the bare text. */
+function span(color: ChartColor, text: string): string {
+  if (!hoverHtml()) return text;
+  return `<span style="color:${colorVar(color)};">${text}</span>`;
+}
+
+/** Kind → badge color (fixed per kind family, §D2). Definition kinds default green. */
+function badgeColor(kind: string): ChartColor {
+  switch (kind) {
+    case "trigger":
+      return "purple";
+    case "effect":
+      return "red";
+    case "structure_key":
+    case "keyword":
+    case "text_format":
+      return "yellow";
+    case "define":
+      return "blue";
+    case "saved_scope":
+    case "scope_word":
+    case "macro_param":
+      return "orange";
+    case "loc_key":
+      return "foreground";
+    default:
+      // Definition kinds (scripted_effect/trigger/modifier, script_value, event,
+      // decision, …) all read green.
+      return "green";
+  }
+}
+
+/** Human label for a kind badge ("scripted trigger", "trigger", "saved scope"). */
+function kindLabel(kind: string): string {
+  if (kind === "structure_key") return "key";
+  return kind.replace(/_/g, " ");
+}
+
+/** `■ kind` badge, colored per family. */
+export function kindBadge(kind: string, label = kindLabel(kind)): string {
+  return span(badgeColor(kind), `■ ${label}`);
+}
+
+/**
+ * A scope pill: blue when it matches the current cursor scope, muted otherwise
+ * (§D3). Content is the plain scope name so stripping the span leaves it legible.
+ */
+export function scopePill(scope: string, current: ReadonlySet<string> | null): string {
+  const matches = current !== null && current.has(scope.toLowerCase());
+  if (matches) return span("blue", scope);
+  if (!hoverHtml()) return scope;
+  return `<span style="color:var(--vscode-descriptionForeground);">${scope}</span>`;
+}
+
+/** Blue scope-type span for the "→ character" tail on badges/pills. */
+export function scopeType(type: string): string {
+  return span("blue", type);
+}
+
+/**
+ * A ■ swatch in an actual game color (not a theme var): the only place an
+ * inline `color:rgb(...)` is emitted, since these are literal loc colors the
+ * theme must not recolor. Content is a ■ so stripping the span leaves a marker.
+ */
+export function colorSwatch(rgb: [number, number, number]): string {
+  if (!hoverHtml()) return "■";
+  const to255 = (v: number) => Math.round(Math.max(0, Math.min(1, v)) * 255);
+  return `<span style="color:rgb(${to255(rgb[0])}, ${to255(rgb[1])}, ${to255(rgb[2])});">■</span>`;
+}
+
+// ---------------------------------------------------------------------------
+// Card model
+// ---------------------------------------------------------------------------
+
+export interface CardInput {
+  kind: string;
+  /** Badge label override (e.g. "scripted trigger" for a mod def). */
+  badgeLabel?: string;
+  name: string;
+  /** Rendered inline after the name on line 1: pills, `· mod`, `→ character`. */
+  headTail?: string;
+  /** Doc prose (blank slot workstream E extends). */
+  doc?: string;
+  /** Italic traits line ("*Traits: yes/no · comparison ok*"). */
+  traits?: string;
+  /** A fenced example body (rendered ```paradox); short bodies only (§D2 mock 2). */
+  example?: string;
+  /** Footer fragments merged into one compact line (provenance, refs). */
+  footer?: string[];
+}
+
+/** The language id our TextMate grammar registers (package.json `languages`). */
+const FENCE_LANG = "paradox";
+
+/** Build one card's markdown per the D2 layout. */
+export function renderCard(card: CardInput): string {
+  const badge = kindBadge(card.kind, card.badgeLabel);
+  const head = card.headTail ? `${badge} **${card.name}** ${card.headTail}` : `${badge} **${card.name}**`;
+  const lines: string[] = [head];
+
+  if (card.doc) lines.push(card.doc);
+  if (card.example) lines.push(`\`\`\`${FENCE_LANG}\n${card.example}\n\`\`\``);
+  if (card.traits) lines.push(`*${card.traits}*`);
+
+  let md = lines.join("\n\n");
+  if (card.footer && card.footer.length > 0) {
+    md += `\n\n---\n${card.footer.join(" · ")}`;
+  }
+  return md;
+}
+
+/**
+ * Join up to `MAX_CARDS` cards, appending "*n more meanings*" when capped, then
+ * the single shared scope-context footer line (§D2: scope context always last,
+ * once per hover).
+ */
+export const MAX_CARDS = 3;
+
+export function renderHover(cards: string[], scopeFooter: string | null): string {
+  const shown = cards.slice(0, MAX_CARDS);
+  const parts = [...shown];
+  const extra = cards.length - shown.length;
+  if (extra > 0) parts.push(`*${extra} more meaning${extra === 1 ? "" : "s"}*`);
+  let md = parts.join("\n\n---\n\n");
+  if (scopeFooter) md += `\n\n${scopeFooter}`;
+  return md;
+}
+
+/** "Scope here: **X** (chain)" — the shared footer line appended once (§D2). */
+export function scopeHereLine(scopes: string, chain: string | null): string {
+  return chain ? `Scope here: **${scopes}** (${chain})` : `Scope here: **${scopes}**`;
+}
+
+/** True when a definition body is short enough to inline as an example (§D2). */
+export function isShortExample(body: string): boolean {
+  const lines = body.split("\n").filter((l) => l.trim() !== "");
+  return lines.length > 0 && lines.length < 4;
+}
+
+// ---------------------------------------------------------------------------
+// PdxDoc rendering (§E3)
+// ---------------------------------------------------------------------------
+
+interface DocTagLike {
+  tag: string;
+  text: string;
+}
+
+export interface DocBody {
+  /** Prose + structured-tag markdown for the card's `doc` slot. Empty → undefined. */
+  doc?: string;
+  /** `@example` body for the card's fenced `example` slot. */
+  example?: string;
+  /** True when `@deprecated` is present — the card renders the name prominently. */
+  deprecated?: boolean;
+}
+
+/**
+ * Turn PdxDoc prose + tags (§E) into the card's `doc`/`example` slots.
+ * Prose renders first, then structured tags compactly (§E3): `@param` as
+ * `*@param NAME — desc*` lines, `@deprecated` as a prominent ⚠ line, other
+ * recognized/unknown tags as compact italic lines. `@example` fills the fenced
+ * slot. Fail-soft: absent fields yield an empty body.
+ */
+export function renderDocBody(def: { doc?: string; tags?: DocTagLike[] }): DocBody {
+  const out: DocBody = {};
+  const lines: string[] = [];
+  if (def.doc) lines.push(def.doc);
+
+  const tagLines: string[] = [];
+  for (const t of def.tags ?? []) {
+    switch (t.tag) {
+      case "example":
+        if (t.text && !out.example) out.example = t.text;
+        break;
+      case "deprecated":
+        out.deprecated = true;
+        tagLines.push(t.text ? `⚠ **Deprecated** — ${t.text}` : `⚠ **Deprecated**`);
+        break;
+      case "param": {
+        // `@param NAME desc` → `*@param NAME — desc*`.
+        const m = /^(\S+)\s*(.*)$/.exec(t.text);
+        if (m) {
+          const desc = m[2].trim();
+          tagLines.push(desc ? `*@param ${m[1]} — ${desc}*` : `*@param ${m[1]}*`);
+        } else {
+          tagLines.push(`*@param*`);
+        }
+        break;
+      }
+      default:
+        // @scope, @saves, @returns, and unknown tags: compact italic line.
+        tagLines.push(t.text ? `*@${t.tag} ${t.text}*` : `*@${t.tag}*`);
+    }
+  }
+  if (tagLines.length > 0) lines.push(tagLines.join("  \n"));
+
+  if (lines.length > 0) out.doc = lines.join("\n\n");
+  return out;
+}

package/src/features/inlayHints.ts

@@ -0,0 +1,147 @@
+/**
+ * Inlay hints, both directions of the localization workflow:
+ *  - in script files: the resolved loc text next to loc-key references
+ *    ("missing loc" for strict properties with no entry);
+ *  - in translated loc files: the reference-language text next to each entry,
+ *    so a translator never has to switch back to the source file.
+ */
+import { MarkupKind, type InlayHint, type Range } from "vscode-languageserver/node";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+import { URI } from "vscode-uri";
+import * as path from "path";
+import type { ServerData } from "../serverData";
+import type { ParadoxSettings } from "@px-lsp/protocol/protocol";
+import { findLocKeyRefs, locKeyOnLine } from "@px-lsp/protocol/locRefs";
+import { detectLocFileLanguage } from "@px-lsp/protocol/translationCore";
+import { getLineText } from "../documents";
+import { getParse, getSavedScopes } from "../parseCache";
+import { inferScopeAt } from "../scopes/inference";
+import { inferenceContextFor } from "../scopes/varTypes";
+import type { SchemaEntry } from "../schema/types";
+import type { Scope } from "../scopes/model";
+import { walkStatements } from "../parser";
+
+const HINT_MAX_LEN = 60;
+
+function truncate(text: string, max: number): string {
+  return text.length > max ? text.slice(0, max - 1) + "…" : text;
+}
+
+export function provideInlayHints(
+  data: ServerData,
+  settings: ParadoxSettings,
+  document: TextDocument,
+  range: Range,
+  rootScopes: Set<Scope> | null,
+  entry: SchemaEntry | null
+): InlayHint[] {
+  if (document.languageId === "paradox-loc") return translationOverlayHints(data, settings, document, range);
+  const hints = locPreviewHints(data, document, range);
+  if (settings.scopeInlayHints) hints.push(...scopeHints(data, document, range, rootScopes, entry));
+  return hints;
+}
+
+/** Optional (off by default): the inferred scope after each scope-changing block opener. */
+function scopeHints(
+  data: ServerData,
+  document: TextDocument,
+  range: Range,
+  rootScopes: Set<Scope> | null,
+  entry: SchemaEntry | null
+): InlayHint[] {
+  const { result, lineIndex } = getParse(document);
+  const ictx = inferenceContextFor(data, entry);
+  const savedScopes = getSavedScopes(document, data.scopeModel, rootScopes, entry?.ambientScopes, ictx);
+  const hints: InlayHint[] = [];
+  walkStatements(result.root, (stmt) => {
+    if (stmt.kind !== "assignment" || stmt.key.quoted || stmt.value?.kind !== "block") return;
+    const key = stmt.key.text.toLowerCase();
+    const changes =
+      /^(?:every|any|random|ordered)_/.test(key) ||
+      key.startsWith("scope:") ||
+      data.scopeModel.links.has(key);
+    if (!changes) return;
+    const pos = lineIndex.positionAt(stmt.value.openBrace + 1);
+    if (pos.line < range.start.line || pos.line > range.end.line) return;
+    const inference = inferScopeAt(
+      result,
+      stmt.value.openBrace + 1,
+      data.scopeModel,
+      rootScopes,
+      savedScopes,
+      ictx
+    );
+    if (!inference.scopes || inference.scopes.size === 0) return;
+    hints.push({
+      position: pos,
+      label: ` ${[...inference.scopes].join("|")}`,
+      paddingLeft: true,
+    });
+  });
+  return hints;
+}
+
+/** Script files: resolved loc text (or "missing loc") after each loc-key reference. */
+function locPreviewHints(data: ServerData, document: TextDocument, range: Range): InlayHint[] {
+  const hints: InlayHint[] = [];
+  for (let lineNo = range.start.line; lineNo <= range.end.line && lineNo < document.lineCount; lineNo++) {
+    const lineText = getLineText(document, lineNo);
+    for (const ref of findLocKeyRefs(lineText)) {
+      const defs = data.index.lookup(ref.key).filter((d) => d.kind === "loc_key");
+      const position = { line: lineNo, character: ref.end };
+      if (defs.length > 0) {
+        const def = defs[0];
+        hints.push({
+          position,
+          label: truncate(def.value ?? "", HINT_MAX_LEN),
+          paddingLeft: true,
+          tooltip: {
+            kind: MarkupKind.Markdown,
+            value: `${def.value ?? ""}\n\n*${path.basename(def.file)}:${def.line + 1} (${def.source})*`,
+          },
+        });
+      } else if (ref.strictness === "strict") {
+        hints.push({
+          position,
+          label: "missing loc",
+          paddingLeft: true,
+          tooltip: `No "${ref.key}" entry in the indexed localization files.`,
+        });
+      }
+    }
+  }
+  return hints;
+}
+
+/** Translated loc files: overlay the reference-language text per entry. */
+function translationOverlayHints(
+  data: ServerData,
+  settings: ParadoxSettings,
+  document: TextDocument,
+  range: Range
+): InlayHint[] {
+  const fsPath = URI.parse(document.uri).fsPath;
+  const fileLang = detectLocFileLanguage(fsPath);
+  // Only overlay in files of another language than the reference itself.
+  if (!fileLang || fileLang === settings.locLanguage) return [];
+
+  const hints: InlayHint[] = [];
+  for (let lineNo = range.start.line; lineNo <= range.end.line && lineNo < document.lineCount; lineNo++) {
+    const lineText = getLineText(document, lineNo);
+    const key = locKeyOnLine(lineText);
+    if (!key) continue;
+    const def = data.index.lookup(key).find((d) => d.kind === "loc_key");
+    if (!def || def.value === undefined) continue;
+    const label = def.value.length > 80 ? def.value.slice(0, 79) + "…" : def.value;
+    hints.push({
+      position: { line: lineNo, character: lineText.length },
+      label: `⟵ ${settings.locLanguage}: ${label}`,
+      paddingLeft: true,
+      tooltip: {
+        kind: MarkupKind.Markdown,
+        value: `**${settings.locLanguage}**: ${def.value}\n\n*${path.basename(def.file)}:${def.line + 1} (${def.source})*`,
+      },
+    });
+  }
+  return hints;
+}

package/src/features/locFormatting.ts

@@ -0,0 +1,127 @@
+/**
+ * Completion and hover for `#G`, `#bold`, … text-formatting tags inside a
+ * localization VALUE string (paradox-loc). Tag names come from the harvested
+ * textformatting index (data/textFormatting.ts). The tag context ends at `#!`.
+ *
+ * Completion docs and the hover card show the format chain plus, when known,
+ * the resolved color as `rgb(r, g, b)` text (completion docs cannot color a
+ * swatch) or an inline colored ■ span (hover, which supports HTML).
+ */
+import { CompletionItemKind, MarkupKind, type CompletionItem } from "vscode-languageserver/node";
+import * as path from "path";
+import { URI } from "vscode-uri";
+import type { TextFormattingIndex, FormatEntry } from "../data/textFormatting";
+import { rgbCss } from "../data/textFormatting";
+import { finalize, MAX_ITEMS, type CompletionResult } from "./completion";
+import { colorSwatch, renderCard, type CardInput } from "./hoverRender";
+
+/** True when `prefix` ends inside an open loc value (odd count of unescaped `"`). */
+function insideLocValue(prefix: string): boolean {
+  let quotes = 0;
+  for (let i = 0; i < prefix.length; i++) {
+    if (prefix[i] === "\\") {
+      i++;
+      continue;
+    }
+    if (prefix[i] === '"') quotes++;
+  }
+  return quotes % 2 === 1;
+}
+
+/** A one-line summary of a resolved tag: `→ instruction → G` · rgb(0, 255, 0). */
+function summarize(index: TextFormattingIndex, name: string): { chain: string; color: string | null } {
+  const { chain, rgb } = index.resolve(name);
+  const rest = chain.slice(1);
+  return {
+    chain: rest.length > 0 ? `→ ${rest.join(" → ")}` : "(direct)",
+    color: rgb ? rgbCss(rgb) : null,
+  };
+}
+
+/** `common/…`-style tail of a source path, from the `gui/` segment onward. */
+function guiRelTail(file: string): string {
+  const norm = file.replace(/\\/g, "/");
+  const i = norm.toLowerCase().lastIndexOf("/gui/");
+  return i >= 0 ? norm.slice(i + 1) : path.basename(file);
+}
+
+/**
+ * `#` tag-name completion inside a loc value, or null when the cursor is not in
+ * that context (caller falls through).
+ */
+export function provideFormatTagCompletion(
+  index: TextFormattingIndex,
+  linePrefix: string
+): CompletionResult | null {
+  const m = /#([A-Za-z0-9_]*)$/.exec(linePrefix);
+  if (!m) return null;
+  if (!insideLocValue(linePrefix.slice(0, m.index))) return null;
+  const items: CompletionItem[] = index.names().map((name) => {
+    const { chain, color } = summarize(index, name);
+    const item: CompletionItem = {
+      label: name,
+      kind: CompletionItemKind.EnumMember,
+      detail: `text format ${chain}${color ? ` · ${color}` : ""}`,
+      sortText: name.toLowerCase(),
+    };
+    const entry = index.winner(name)!;
+    const docParts = [
+      entry.layer === "builtin" ? "Engine built-in format." : `\`${entry.format || "(style only)"}\``,
+    ];
+    if (color) docParts.push(`Color: ${color}`);
+    item.documentation = { kind: MarkupKind.Markdown, value: docParts.join("\n\n") };
+    return item;
+  });
+  return finalize(items, m[1], MAX_ITEMS);
+}
+
+/** The `#tag` under the cursor inside a loc value, or null. */
+function tagAt(lineText: string, character: number): { name: string; start: number; end: number } | null {
+  const re = /#([A-Za-z0-9_]+)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(lineText)) !== null) {
+    const start = m.index;
+    const end = m.index + m[0].length;
+    if (character >= start && character <= end && insideLocValue(lineText.slice(0, start))) {
+      return { name: m[1], start, end };
+    }
+  }
+  return null;
+}
+
+export interface FormatTagHover {
+  markdown: string;
+  start: number;
+  end: number;
+}
+
+/** Hover card for a `#tag` in a loc value, or null when there is none / unknown. */
+export function provideFormatTagHover(
+  index: TextFormattingIndex,
+  lineText: string,
+  character: number
+): FormatTagHover | null {
+  const hit = tagAt(lineText, character);
+  if (!hit) return null;
+  const entry = index.winner(hit.name);
+  if (!entry) return null;
+  const { chain, rgb } = index.resolve(hit.name);
+  const card: CardInput = { kind: "text_format", badgeLabel: "text format", name: `#${hit.name}` };
+  const rest = chain.slice(1);
+  const doc: string[] = [];
+  if (rest.length > 0) doc.push(`Format chain: ${chain.map((c) => `\`${c}\``).join(" → ")}`);
+  else if (entry.format) doc.push(`\`${entry.format}\``);
+  if (rgb) doc.push(`Color: ${colorSwatch(rgb)} ${rgbCss(rgb)}`);
+  if (entry.layer === "builtin") doc.push("Engine built-in format.");
+  if (doc.length > 0) card.doc = doc.join("  \n");
+  if (entry.file) card.footer = [sourceLink(entry)];
+  return { markdown: renderCard(card), start: hit.start, end: hit.end };
+}
+
+function sourceLink(entry: FormatEntry): string {
+  const rel = guiRelTail(entry.file);
+  const target = URI.file(entry.file)
+    .with({ fragment: String(entry.line + 1) })
+    .toString();
+  return `${entry.layer} · [${rel}](${target})`;
+}

package/src/features/references.ts

@@ -0,0 +1,70 @@
+/**
+ * Find-all-references over the reference index (workspace-mod usage sites)
+ * merged with the on-demand vanilla/parent scan (#3 — without it, a name used
+ * only by vanilla files listed nothing but its definitions), optionally
+ * including the definition sites.
+ */
+import * as path from "path";
+import type { Location, Position } from "vscode-languageserver/node";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+import { URI } from "vscode-uri";
+import type { Reference } from "@px-lsp/protocol/types";
+import { pushAll } from "@px-lsp/protocol/arrays";
+import type { ServerData } from "../serverData";
+import { wordRangeAt } from "../wordAt";
+import { getLineText } from "../documents";
+
+/** file+line key with the DefinitionIndex's path normalization (win32 is
+ * case-insensitive), so lazy-scan paths compare equal to indexed ones. */
+function siteKey(file: string, line: number): string {
+  const n = path.normalize(file);
+  return `${process.platform === "win32" ? n.toLowerCase() : n}|${line}`;
+}
+
+export async function provideReferences(
+  data: ServerData,
+  document: TextDocument,
+  position: Position,
+  includeDeclaration: boolean,
+  lazyRefs?: (name: string) => Promise<Reference[]>
+): Promise<Location[]> {
+  const range = wordRangeAt(getLineText(document, position.line), position.character);
+  if (!range) return [];
+  const name = stripPrefix(range.word);
+
+  const refs: Reference[] = data.refIndex.lookup(name).slice();
+  if (lazyRefs) {
+    // The textual scan cannot tell a non-top-level definition site (inline
+    // scripted_trigger, nested title) from a use: drop hits the definition
+    // index already knows, they are appended under includeDeclaration below.
+    const defSites = new Set(data.index.lookupAll(name).map((d) => siteKey(d.file, d.line)));
+    pushAll(
+      refs,
+      (await lazyRefs(name)).filter((r) => !defSites.has(siteKey(r.file, r.line)))
+    );
+  }
+
+  const locations: Location[] = refs.map((r) => ({
+    uri: URI.file(r.file).toString(),
+    range: {
+      start: { line: r.line, character: r.startChar },
+      end: { line: r.line, character: r.endChar },
+    },
+  }));
+
+  if (includeDeclaration) {
+    for (const d of data.index.lookupAll(name)) {
+      locations.push({
+        uri: URI.file(d.file).toString(),
+        range: { start: { line: d.line, character: 0 }, end: { line: d.line, character: 0 } },
+      });
+    }
+  }
+  return locations;
+}
+
+/** `scope:x` / `culture:x` under the cursor → the name part. */
+export function stripPrefix(word: string): string {
+  const colon = word.lastIndexOf(":");
+  return colon >= 0 ? word.slice(colon + 1) : word;
+}