@px-lsp/server 0.1.0

package/src/data/modifierTemplates.ts

@@ -0,0 +1,143 @@
+/**
+ * Templated modifier tags from modifiers.log (`$CULTURE$_opinion`,
+ * `stationed_$MEN_AT_ARMS_TYPE$_damage_add`, …): the engine generates one
+ * concrete modifier per definition (e.g. `french_opinion` for the culture
+ * `french`). Like the generated `has_relation_X` cards in hover.ts, expansion
+ * is LAZY — matched against the definition index on hover / expanded once per
+ * completion cache build — never materialized into tokenMap (huge mods define
+ * thousands of cultures).
+ *
+ * The placeholder table itself is game knowledge and lives in the game
+ * profile (games/<id>/modifierPlaceholders.ts).
+ *
+ * No `vscode` imports here: this module is unit-tested in plain Node.
+ */
+import * as path from "path";
+import type { Definition, TokenData } from "@px-lsp/protocol/types";
+import { activeProfile } from "../games/active";
+
+export interface PlaceholderSpec {
+  /** Definition-index kind the placeholder expands over. */
+  kind?: string;
+  /** Fixed engine value set, for placeholders not backed by the index. */
+  values?: readonly string[];
+  /** Human label for hover/completion docs ("culture", "men-at-arms base type"). */
+  label: string;
+  /** Values that do NOT exist for templates with the given prefix
+   * (verified per-game exceptions to `values`). */
+  excludeValues?: Record<string, readonly string[]>;
+}
+
+export interface ModifierTemplate {
+  /** The raw templated tag, e.g. `stationed_$MEN_AT_ARMS_TYPE$_damage_add`. */
+  name: string;
+  prefix: string;
+  suffix: string;
+  placeholder: string;
+  spec: PlaceholderSpec;
+  /** Metadata lines from the log ("Use areas: character"). */
+  traits?: string;
+}
+
+const TEMPLATE_NAME = /^([a-z0-9_]*)\$([A-Z_]+)\$([a-z0-9_]*)$/;
+
+/** Compile raw templated tokens into matchable templates; unknown placeholders are dropped. */
+export function compileModifierTemplates(raw: TokenData[]): ModifierTemplate[] {
+  const placeholders = activeProfile().modifierPlaceholders;
+  const templates: ModifierTemplate[] = [];
+  for (const t of raw) {
+    const m = TEMPLATE_NAME.exec(t.name);
+    if (!m) continue;
+    let spec = placeholders[m[2]];
+    if (!spec) continue;
+    const excluded = spec.values && spec.excludeValues?.[m[1]];
+    if (excluded) {
+      spec = { ...spec, values: spec.values!.filter((v) => !excluded.includes(v)) };
+    }
+    templates.push({ name: t.name, prefix: m[1], suffix: m[3], placeholder: m[2], spec, traits: t.traits });
+  }
+  return templates;
+}
+
+export interface TemplateMatch {
+  template: ModifierTemplate;
+  /** The definition/base-type name the placeholder matched ("french"). */
+  base: string;
+  /** The matched definition; undefined for fixed-value placeholders. */
+  def?: Definition;
+}
+
+/**
+ * Match a concrete name (`french_opinion`) against the templates: the first
+ * template whose placeholder slice resolves — to a fixed engine value or to an
+ * indexed definition of the mapped kind — wins. Shared-suffix ambiguity
+ * (`_opinion` appears in six templates) is resolved by that lookup.
+ */
+export function matchTemplatedModifier(
+  word: string,
+  templates: ModifierTemplate[],
+  lookup: (name: string) => Definition[]
+): TemplateMatch | null {
+  for (const template of templates) {
+    const minLen = template.prefix.length + template.suffix.length + 1;
+    if (word.length < minLen) continue;
+    if (!word.startsWith(template.prefix) || !word.endsWith(template.suffix)) continue;
+    const base = word.slice(template.prefix.length, word.length - template.suffix.length);
+    if (template.spec.values) {
+      if (template.spec.values.includes(base)) return { template, base };
+      continue;
+    }
+    const def = lookup(base).find((d) => d.kind === template.spec.kind);
+    if (def) return { template, base, def };
+  }
+  return null;
+}
+
+/** One-line doc for a matched expansion, shared by hover and completion resolve. */
+export function templatedModifierDoc(m: TemplateMatch): string {
+  if (m.def) {
+    return `Modifier the engine generates for the ${m.template.spec.label} \`${m.base}\` (${path.basename(m.def.file)}:${m.def.line + 1}).`;
+  }
+  return `Modifier the engine generates for the built-in ${m.template.spec.label} \`${m.base}\`.`;
+}
+
+export interface TemplateExpansion {
+  name: string;
+  template: ModifierTemplate;
+  /** The definition the expansion came from; undefined for fixed value sets. */
+  def?: Definition;
+}
+
+/**
+ * Expand every template against the definition index (one pass) plus the fixed
+ * value sets. Used to build the completion list for modifier contexts; hover
+ * uses matchTemplatedModifier instead and never needs the full expansion.
+ */
+export function expandModifierTemplates(
+  templates: ModifierTemplate[],
+  index: { entries(filter?: (def: Definition) => boolean): IterableIterator<Definition> },
+  completableKinds: ReadonlySet<string>
+): TemplateExpansion[] {
+  const byKind = new Map<string, ModifierTemplate[]>();
+  const out: TemplateExpansion[] = [];
+  for (const template of templates) {
+    if (template.spec.values) {
+      for (const v of template.spec.values)
+        out.push({ name: template.prefix + v + template.suffix, template });
+      continue;
+    }
+    const kind = template.spec.kind!;
+    if (completableKinds.size > 0 && !completableKinds.has(kind)) continue;
+    const list = byKind.get(kind);
+    if (list) list.push(template);
+    else byKind.set(kind, [template]);
+  }
+  if (byKind.size > 0) {
+    for (const def of index.entries((d) => byKind.has(d.kind))) {
+      for (const template of byKind.get(def.kind) ?? []) {
+        out.push({ name: template.prefix + def.name + template.suffix, template, def });
+      }
+    }
+  }
+  return out;
+}

package/src/data/textFormatting.ts

@@ -0,0 +1,165 @@
+/**
+ * Loc text-formatting tag harvest: `#G`, `#bold`, … tags come from
+ * `textformatting = { format = { name = G format = "color:{0,1,0}" } … }`
+ * blocks in .gui files. Layers in load order: jomini
+ * (gui/jomini/basetextformatting.gui base set), game (gui/**), read-only
+ * dependency parents, then the mod.
+ *
+ * Resolution is gui FIOS (AGENTS.md): the FIRST-loaded definition of a name
+ * wins, and `override = no` (the base set's default) confirms that; a later
+ * definition only replaces it with `override = yes`. So the jomini base `G`
+ * (green, override=no) is NOT clobbered by game's `G` (which sets no override) —
+ * matching the engine and the Paradox modding convention (a mod overrides a base
+ * format with `override = yes`). Callers must addLayer in load order.
+ *
+ * Aliases chain (`I` → `instruction` → `G;italic` → G's color); the resolved
+ * [r,g,b] is the first `color:{r,g,b}` reached along the chain (0..1 floats).
+ *
+ * No `vscode` imports: unit-tested in plain Node.
+ */
+import * as fs from "fs";
+import { LineIndex, parseScript, type BlockNode } from "../parser";
+import { listFiles } from "@px-lsp/protocol/fsWalk";
+import * as path from "path";
+
+export type FormatLayer = "jomini" | "game" | "parent" | "mod" | "builtin";
+
+export interface FormatEntry {
+  name: string;
+  /** The raw `format = "…"` string (empty for style-only tags like editor_formatting). */
+  format: string;
+  file: string;
+  line: number; // 0-based
+  layer: FormatLayer;
+}
+
+export type Rgb = [number, number, number];
+
+export interface FormatResolution {
+  /** Names visited resolving the tag, e.g. ["I","instruction","G","italic"]. */
+  chain: string[];
+  /** First color reached (0..1 floats), or null for style-only / unknown tags. */
+  rgb: Rgb | null;
+}
+
+/**
+ * Engine-native formats referenced by the harvested format strings but never
+ * declared as `format` blocks: the style primitives the format-string grammar
+ * uses. Included so completion/hover recognize `#bold`, `#italic`.
+ */
+const ENGINE_BUILTINS = ["bold", "italic"];
+
+/** Parse `color:{r,g,b}` (0..1 floats, space/comma separated) → [r,g,b]. */
+function parseColor(segment: string): Rgb | null {
+  const m = /^color\s*:\s*\{\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)\s*\}$/.exec(segment.trim());
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+export class TextFormattingIndex {
+  /** name -> the FIOS winner (first loaded, unless a later `override = yes`). */
+  private byName = new Map<string, FormatEntry>();
+
+  constructor() {
+    for (const name of ENGINE_BUILTINS) {
+      this.byName.set(name, { name, format: "", file: "", line: 0, layer: "builtin" });
+    }
+  }
+
+  /** Harvest every .gui file under `root/gui` whose text mentions `textformatting`. */
+  addLayer(root: string, layer: FormatLayer): void {
+    for (const file of listFiles(path.join(root, "gui"), ".gui").sort()) {
+      let text: string;
+      try {
+        text = fs.readFileSync(file, "utf8").replace(/^/, "");
+      } catch {
+        continue;
+      }
+      if (!text.includes("textformatting")) continue; // cheap prefilter
+      this.harvestText(text, file, layer);
+    }
+  }
+
+  harvestText(text: string, file: string, layer: FormatLayer): void {
+    const { root } = parseScript(text);
+    const lines = new LineIndex(text);
+    for (const stmt of root.statements) {
+      if (stmt.kind !== "assignment" || stmt.key.text.toLowerCase() !== "textformatting") continue;
+      if (stmt.value?.kind !== "block") continue;
+      this.harvestBlock(stmt.value, file, layer, lines);
+    }
+  }
+
+  private harvestBlock(block: BlockNode, file: string, layer: FormatLayer, lines: LineIndex): void {
+    for (const stmt of block.statements) {
+      if (stmt.kind !== "assignment" || stmt.key.text.toLowerCase() !== "format") continue;
+      if (stmt.value?.kind !== "block") continue;
+      let name: string | null = null;
+      let format = "";
+      let nameLine = 0;
+      let override = false; // FIOS default (absent / `override = no`)
+      for (const inner of stmt.value.statements) {
+        if (inner.kind !== "assignment" || inner.value?.kind !== "scalar") continue;
+        const key = inner.key.text.toLowerCase();
+        if (key === "name") {
+          name = inner.value.text;
+          nameLine = lines.positionAt(inner.key.range.start).line;
+        } else if (key === "format") {
+          format = inner.value.text;
+        } else if (key === "override") {
+          override = inner.value.text.toLowerCase() === "yes";
+        }
+      }
+      if (name === null) continue;
+      // FIOS: keep the first definition unless this one explicitly overrides.
+      if (this.byName.has(name) && !override) continue;
+      this.byName.set(name, { name, format, file, line: nameLine, layer });
+    }
+  }
+
+  /** Winning entry for a tag name, or null when unknown. */
+  winner(name: string): FormatEntry | null {
+    return this.byName.get(name) ?? null;
+  }
+
+  names(): string[] {
+    return [...this.byName.keys()].sort();
+  }
+
+  /** Follow the alias chain, collecting the visited names and the first color. */
+  resolve(name: string): FormatResolution {
+    const chain: string[] = [];
+    const seen = new Set<string>();
+    let rgb: Rgb | null = null;
+    const visit = (n: string): void => {
+      if (seen.has(n)) return;
+      seen.add(n);
+      chain.push(n);
+      const entry = this.winner(n);
+      if (!entry) return; // builtin / unknown leaf
+      for (const seg of entry.format
+        .split(";")
+        .map((s) => s.trim())
+        .filter(Boolean)) {
+        const color = parseColor(seg);
+        if (color) {
+          if (!rgb) rgb = color;
+          continue;
+        }
+        visit(seg);
+      }
+    };
+    visit(name);
+    return { chain, rgb };
+  }
+
+  get count(): number {
+    return this.byName.size;
+  }
+}
+
+/** Format a 0..1 rgb triple as `rgb(0, 255, 0)` (0..255 ints) for docs. */
+export function rgbCss(rgb: Rgb): string {
+  const to255 = (v: number) => Math.round(Math.max(0, Math.min(1, v)) * 255);
+  return `rgb(${to255(rgb[0])}, ${to255(rgb[1])}, ${to255(rgb[2])})`;
+}

package/src/data/wikiDocs.ts

@@ -0,0 +1,187 @@
+/**
+ * Parser for the wiki reference lists bundled in wikidocs/ (Markdown mirrors
+ * of the Paradox wiki; see wikidocs/ATTRIBUTION.md for provenance).
+ *
+ * These are a fallback and enrichment source for engine tokens: script_docs
+ * output is authoritative for the user's exact game version, but the wiki lists
+ * work without ever launching the game in debug mode and carry usage examples
+ * that script_docs lacks.
+ *
+ * No `vscode` imports here: this module is unit-tested in plain Node.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import type { TokenData, TokenKind } from "@px-lsp/protocol/types";
+import { activeProfile } from "../games/active";
+
+const NAME_RE = /^[A-Za-z0-9_.:]+$/;
+
+/** Strip markdown/HTML noise from a table cell, keeping <br> as line breaks. */
+export function cleanCell(cell: string): string {
+  return cell
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<\/?code[^>]*>/gi, "")
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, "") // images
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1") // links -> text
+    .replace(/\*\*([^*]*)\*\*/g, "$1")
+    .replace(/`/g, "")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#0?39;/g, "'")
+    .replace(/&#124;/g, "|")
+    .replace(/&amp;/g, "&")
+    .split("\n")
+    .map((l) => l.trim())
+    .join("\n")
+    .trim();
+}
+
+/** Split a markdown table row into cleaned cells; returns null for non-row lines. */
+function splitRow(line: string): string[] | null {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("|")) return null;
+  const inner = trimmed.replace(/^\|/, "").replace(/\|\s*$/, "");
+  return inner.split("|").map(cleanCell);
+}
+
+function isHeaderOrSeparator(cells: string[]): boolean {
+  return cells.every((c) => c === "" || /^-{3,}$/.test(c)) || cells.some((c) => /^Name$|^Scope$/i.test(c));
+}
+
+function makeToken(
+  kind: TokenKind,
+  name: string,
+  doc: string,
+  scopes: string[],
+  traitLines: string[],
+  usage?: string
+): TokenData {
+  const token: TokenData = { name, kind, doc, scopes: scopes.filter((s) => s !== "") };
+  // Sections separated by blank lines so consumers can pick out e.g. the Example block.
+  const traits = traitLines.filter((t) => t !== "").join("\n\n");
+  if (traits) token.traits = traits;
+  if (usage) token.usage = usage;
+  return token;
+}
+
+function splitScopes(cell: string): string[] {
+  return cell
+    .split(/[\n,]/)
+    .map((s) => s.trim())
+    .filter((s) => s !== "");
+}
+
+/** Effects_list.md: | Name | Desc | Example | Scopes | Target | */
+export function parseWikiEffects(md: string): TokenData[] {
+  const tokens: TokenData[] = [];
+  for (const line of md.split(/\r?\n/)) {
+    const cells = splitRow(line);
+    if (!cells || cells.length < 4 || isHeaderOrSeparator(cells)) continue;
+    const [name, desc, example, scopes, target] = cells;
+    if (!NAME_RE.test(name)) continue;
+    tokens.push(
+      makeToken(
+        "effect",
+        name,
+        desc,
+        splitScopes(scopes ?? ""),
+        [target ? `Target: ${target}` : ""],
+        example || undefined
+      )
+    );
+  }
+  return tokens;
+}
+
+/** Triggers_list.md: | Name | Description | Usage | Traits | Supported Scopes | Supported Targets | */
+export function parseWikiTriggers(md: string): TokenData[] {
+  const tokens: TokenData[] = [];
+  for (const line of md.split(/\r?\n/)) {
+    const cells = splitRow(line);
+    if (!cells || cells.length < 5 || isHeaderOrSeparator(cells)) continue;
+    const [name, desc, usage, traits, scopes, targets] = cells;
+    if (!NAME_RE.test(name)) continue;
+    tokens.push(
+      makeToken(
+        "trigger",
+        name,
+        desc,
+        splitScopes(scopes ?? ""),
+        [traits ? `Traits: ${traits}` : "", targets ? `Supported Targets: ${targets}` : ""],
+        usage || undefined
+      )
+    );
+  }
+  return tokens;
+}
+
+/**
+ * Scopes_list.md: sections (## Character, ## Culture, ...) each with
+ * | Scope | Description | To scope | Version added | tables. The section is the
+ * input scope, "To scope" the output scope.
+ */
+export function parseWikiEventTargets(md: string): TokenData[] {
+  const tokens: TokenData[] = [];
+  let section = "";
+  for (const line of md.split(/\r?\n/)) {
+    const heading = /^##\s+(.+)$/.exec(line.trim());
+    if (heading) {
+      section = heading[1].trim().toLowerCase();
+      continue;
+    }
+    const cells = splitRow(line);
+    if (!cells || cells.length < 3 || isHeaderOrSeparator(cells)) continue;
+    const [name, desc, toScope, version] = cells;
+    if (!NAME_RE.test(name)) continue;
+    const scopes: string[] = [];
+    if (section && section !== "primitive scopes") scopes.push(`input: ${section}`);
+    if (toScope) scopes.push(`output: ${toScope}`);
+    tokens.push(makeToken("event_target", name, desc, scopes, [version ? `Version added: ${version}` : ""]));
+  }
+  return tokens;
+}
+
+export const WIKI_FILES: Array<{ file: string; parse: (md: string) => TokenData[] }> = [
+  { file: "Effects_list.md", parse: parseWikiEffects },
+  { file: "Triggers_list.md", parse: parseWikiTriggers },
+  { file: "Scopes_list.md", parse: parseWikiEventTargets },
+];
+
+/** Parse all bundled wiki list files found in `dir`. Missing files are skipped. */
+export function loadWikiTokens(dir: string): TokenData[] {
+  const tokens: TokenData[] = [];
+  for (const { file, parse } of WIKI_FILES) {
+    try {
+      tokens.push(...parse(fs.readFileSync(path.join(dir, file), "utf8")));
+    } catch {
+      // Bundled file missing/unreadable: skip, the extension works without it.
+    }
+  }
+  return tokens;
+}
+
+/**
+ * Merge script_docs tokens (authoritative) with wiki tokens (fallback/enrichment):
+ * wiki-only tokens are added with a provenance note; tokens present in both keep
+ * the script_docs doc and scopes but gain the wiki's usage example.
+ */
+export function mergeWikiTokens(scriptDocs: TokenData[], wiki: TokenData[]): TokenData[] {
+  const byKey = new Map<string, TokenData>();
+  for (const t of scriptDocs) byKey.set(`${t.kind}:${t.name}`, t);
+
+  const merged = [...scriptDocs];
+  const wikiNote = activeProfile().wikiNote;
+  for (const w of wiki) {
+    const existing = byKey.get(`${w.kind}:${w.name}`);
+    if (!existing) {
+      const note = w.traits ? `${w.traits}\n${wikiNote}` : wikiNote;
+      merged.push({ ...w, traits: note });
+      continue;
+    }
+    if (existing.doc === "" && w.doc !== "") existing.doc = w.doc;
+    // script_docs is authoritative; the wiki fills a missing syntax example.
+    if (!existing.usage && w.usage) existing.usage = w.usage;
+  }
+  return merged;
+}