@px-lsp/server 0.3.0 → 0.3.1

package/src/schema/skeletons.ts

@@ -0,0 +1,182 @@
+/**
+ * Definition skeletons: the canonical shape of one definition of a kind,
+ * derived from measured vanilla usage by scripts/build-skeletons.ts and shipped
+ * as packages/server/data/<game>/skeletons.json.
+ *
+ * Nothing here is written by hand. A key is in a skeleton because at least
+ * SKELETON_MAJORITY of the game's own definitions of that kind carry it; its
+ * order is the median position it holds in them; its pre-filled value is the
+ * value the corpus uses most, and only where the key's whole measured
+ * vocabulary is small enough to be a real choice. A key whose vocabulary is
+ * wider but entirely NUMERIC still gets the number the corpus writes most,
+ * since a key name is valid script nowhere in a numeric slot. Anything wider
+ * than that (loc keys, names, paths) gets its own name as placeholder text,
+ * which says "fill this in" without asserting a value.
+ *
+ * Both insert forms are rendered at once, exactly like features/blockSnippets.ts:
+ * `snippet` for clients that declared snippetSupport, `plain` (free of `${`) for
+ * the rest.
+ *
+ * No `vscode` imports: plain data plus pure renderers.
+ */
+
+/**
+ * Share of a kind's definitions a key must appear in to enter the skeleton.
+ * Half: a skeleton is what a definition of this kind USUALLY looks like, not
+ * the union of everything the folder has ever used. Applied identically to the
+ * keys of a nested block (share of that block's own occurrences).
+ */
+export const SKELETON_MAJORITY = 0.5;
+
+/** One key of a skeleton body. */
+export interface SkeletonKey {
+  key: string;
+  /**
+   * The key's whole measured value vocabulary, most-used first. Set only where
+   * the corpus uses few enough distinct values for the list to be a choice
+   * rather than a guess; absent = the value is a placeholder.
+   */
+  choices?: string[];
+  /**
+   * The single most-used measured value, set only where the vocabulary is too
+   * wide to offer as a choice AND every value the corpus writes for the key is
+   * a number. A key name is valid script nowhere in a numeric slot, so a
+   * measured number is the honest placeholder; it stays a tabstop, so it still
+   * reads as "fill this in".
+   */
+  placeholder?: string;
+  /**
+   * Nested one level: the block this key opens, carrying the keys measured in
+   * at least SKELETON_MAJORITY of its occurrences. An empty array = the block
+   * has no stable shape, so it is inserted empty.
+   */
+  block?: SkeletonKey[];
+}
+
+/** A named child block of a definition, offered on its own. */
+export interface SkeletonBlock {
+  /** Occurrences of the block measured across the kind's definitions. */
+  sampled: number;
+  keys: SkeletonKey[];
+}
+
+export interface KindSkeleton {
+  /** Vanilla definitions of this kind the skeleton was measured over. */
+  sampled: number;
+  keys: SkeletonKey[];
+  /**
+   * The file-level key the kind's definition names were measured to derive
+   * from: at least SKELETON_MAJORITY of the folder's files declare it as a
+   * top-level scalar, and at least that share of the kind's names are
+   * `<its value>.<number>` (`namespace = intrigue` → `intrigue.0001`). Absent =
+   * names are plain identifiers and files need no header line.
+   */
+  nameFromHeader?: string;
+  /** Child-block skeletons, keyed by the block's key. */
+  blocks?: Record<string, SkeletonBlock>;
+}
+
+export interface SkeletonData {
+  meta: { generated: string; sources: string[]; majority: number };
+  /** Definition kind, as the schema table spells it. */
+  kinds: Record<string, KindSkeleton>;
+}
+
+/** Both insert forms of one skeleton. */
+export interface RenderedSkeleton {
+  /** `${n:…}` tabstop form; only for clients declaring snippetSupport. */
+  snippet: string;
+  /** Plain-text skeleton, free of `${`. */
+  plain: string;
+}
+
+interface Counter {
+  n: number;
+}
+
+function escapeSnippet(text: string): string {
+  return text.replace(/[\\$}]/g, "\\$&");
+}
+
+/** The right-hand side of a leaf key, in one of the two forms. */
+function leafValue(spec: SkeletonKey, snippet: boolean, c: Counter): string {
+  const filled = spec.choices?.[0] ?? spec.placeholder ?? spec.key;
+  if (!snippet) return filled;
+  if (spec.choices && spec.choices.length > 1) return `\${${++c.n}|${spec.choices.join(",")}|}`;
+  return `\${${++c.n}:${escapeSnippet(filled)}}`;
+}
+
+function renderKeys(keys: SkeletonKey[], indent: string, snippet: boolean, c: Counter): string {
+  let out = "";
+  for (const spec of keys) {
+    if (spec.block) {
+      out += `${indent}${spec.key} = {\n`;
+      out +=
+        spec.block.length > 0
+          ? renderKeys(spec.block, indent + "\t", snippet, c)
+          : `${indent}\t${snippet ? `$${++c.n}` : ""}\n`;
+      out += `${indent}}\n`;
+      continue;
+    }
+    out += `${indent}${spec.key} = ${leafValue(spec, snippet, c)}\n`;
+  }
+  return out;
+}
+
+export interface SkeletonRenderOptions {
+  /**
+   * Value of the header key the target document already declares
+   * (`namespace = my_events`), so a generated name matches its own file.
+   */
+  headerValue?: string;
+  /** Write the header line above the definition (the document declares none). */
+  withHeader?: boolean;
+}
+
+/** The whole definition, header line included when the document lacks it. */
+export function renderDefinitionSkeleton(
+  kind: string,
+  skel: KindSkeleton,
+  opts: SkeletonRenderOptions = {}
+): RenderedSkeleton {
+  const one = (snippet: boolean): string => {
+    const c: Counter = { n: 0 };
+    // A name built from a header key the insert writes itself mirrors tabstop 1
+    // into both places, so editing the namespace renames the definition too.
+    const mirrored = skel.nameFromHeader !== undefined && opts.headerValue === undefined;
+    if (mirrored) c.n = 1;
+    const prefix = mirrored
+      ? snippet
+        ? `\${1:my_${escapeSnippet(skel.nameFromHeader!)}}`
+        : `my_${skel.nameFromHeader}`
+      : opts.headerValue;
+
+    // The header line is written only when the document has none: a second
+    // `namespace =` in one file is exactly the silent failure to avoid.
+    const out = opts.withHeader && skel.nameFromHeader ? `${skel.nameFromHeader} = ${prefix}\n\n` : "";
+
+    const name = skel.nameFromHeader
+      ? snippet
+        ? `${prefix}.\${${++c.n}:1}`
+        : `${prefix}.1`
+      : snippet
+        ? `\${${++c.n}:my_${escapeSnippet(kind)}}`
+        : `my_${kind}`;
+    // A kind with no measured body is still worth inserting: the wrapper, the
+    // name shape and the header are the parts the game fails silently on.
+    const body =
+      skel.keys.length > 0 ? renderKeys(skel.keys, "\t", snippet, c) : `\t${snippet ? `$${++c.n}` : ""}\n`;
+    return `${out}${name} = {\n${body}}`;
+  };
+  return { snippet: one(true), plain: one(false) };
+}
+
+/** One named child block (`option = { name = … }`), inserted on its own. */
+export function renderBlockSkeleton(name: string, block: SkeletonBlock): RenderedSkeleton {
+  const one = (snippet: boolean): string => {
+    const body =
+      block.keys.length > 0 ? renderKeys(block.keys, "\t", snippet, { n: 0 }) : `\t${snippet ? "$1" : ""}\n`;
+    return `${name} = {\n${body}}`;
+  };
+  return { snippet: one(true), plain: one(false) };
+}

package/src/schema/types.ts

@@ -48,6 +48,13 @@ export interface KeySpec {
    * vocabulary, the completion regression rank-eval caught in 2026-07.
    */
   curated?: boolean;
+  /**
+   * Definition kinds this key's value names, where a global `RefField` would
+   * be wrong because the key means different things in different folders
+   * (`opposites` is a trait list here and a scripted_relation list there).
+   * Per-kind and therefore unambiguous; read by the creators' form request.
+   */
+  refKinds?: string[];
 }
 
 /** The document shape of a definition kind: top-level keys plus named sub-blocks. */
@@ -102,6 +109,29 @@ export interface SchemaEntry {
    * of this kind actually define.
    */
   requiredLoc?: string[];
+  /**
+   * Every loc key the game generates for a definition of this kind, `$` = the
+   * name, as the folder's `_*.info` doc states them. A SUPERSET of
+   * `requiredLoc`, which may only carry the patterns ≥95% of vanilla actually
+   * defines because a diagnostic hangs off it; a creator writes the whole set
+   * and asks the modder for each. Absent = `requiredLoc` is the whole set.
+   */
+  locPatterns?: string[];
+  /**
+   * Where the game looks for a definition's default icon, relative to the
+   * game/mod root, forward slashes, no trailing slash. Only set where the
+   * folder's `_*.info` doc states the path; absent = this kind has no
+   * name-derived icon and a creator offers no icon picker for it.
+   */
+  iconFolder?: string;
+  /**
+   * Key inside a definition's body whose value sorts this kind's definitions
+   * into families, when one folder holds several (`type = ethos` in
+   * common/culture/pillars). A creator that draws one picker per family reads
+   * it through paradox/definitionForm; nothing else does. Absent = the kind is
+   * one flat list.
+   */
+  groupKey?: string;
   /** Scope(s) a definition of this type pushes as root in its script blocks (Phase 3). */
   rootScopes?: string[];
   /** Include definitions of this kind in completion lists (default true).

package/src/server.ts

@@ -32,6 +32,7 @@ import {
   configChangedNotification,
   indexChangedNotification,
   indexStatsRequest,
+  locTextRequest,
   lookupLocRequest,
   modFileChangedNotification,
   progressNotification,
@@ -41,6 +42,7 @@ import {
   type ParadoxSettings,
   type StatusPayload,
   type LocEntryInfo,
+  type LocTextParams,
   type LookupLocParams,
   type ModFileChangeParams,
   type ModScopedParams,
@@ -53,13 +55,21 @@ import {
   exampleWikiVariableKinds,
   type ExampleWikiEntryParams,
   type ExampleWikiKind,
+  dynastyTreeRequest,
   eventGraphRequest,
   eventValueOptionsRequest,
   eventVocabularyRequest,
+  definitionFormRequest,
+  definitionEditRequest,
+  modifierFormatsRequest,
+  type ModifierFormatsParams,
+  type DefinitionFormParams,
+  type DefinitionEditParams,
   guiTreeRequest,
   locCoverageRequest,
   modOverviewRequest,
   overridesRequest,
+  type DynastyTreeParams,
   type EventBannerParams,
   type EventDetailParams,
   type EventGraphParams,
@@ -89,6 +99,9 @@ import {
   type DependenciesParams,
   scopeAtRequest,
   type ScopeAtParams,
+  snippetsRequest,
+  type SnippetsParams,
+  type SnippetsResult,
   type ScopeAtResult,
 } from "@px-lsp/protocol/protocol";
 import { buildGuiTree } from "./features/guiTree";
@@ -149,6 +162,7 @@ import { ModOriginResolver } from "./index/modOrigin";
 import { loadSchema, type SchemaData } from "./schema/loader";
 import { VARIABLE_KINDS } from "./games/jomini/variables";
 import { activeProfile, setActiveProfile } from "./games/active";
+import { resolveConfigDir } from "@px-lsp/protocol/configDir";
 import { resolveProfile } from "./games/registry";
 import type { SchemaEntry } from "./schema/types";
 import { URI } from "vscode-uri";
@@ -157,7 +171,8 @@ import { CompletionFeature } from "./features/completion";
 import { provideHover } from "./features/hover";
 import { setHoverDetail } from "./features/hoverRender";
 import { provideDateHover } from "./features/calendarDates";
-import { sanitizeCalendar } from "@px-lsp/protocol/calendar";
+import { sanitizeCalendar, type CalendarSetting } from "@px-lsp/protocol/calendar";
+import { isCalendarFile, readCalendarFile } from "@px-lsp/protocol/calendarFile";
 import { provideTextureHover } from "./features/textureHover";
 import { provideDefinition, provideLocDefinition } from "./features/definition";
 import { SEMANTIC_LEGEND, provideSemanticTokens } from "./features/semanticTokens";
@@ -180,14 +195,20 @@ import { provideReferences } from "./features/references";
 import { prepareRename, provideRename } from "./features/rename";
 import { provideWorkspaceSymbols } from "./features/workspaceSymbols";
 import { evictParse, getLocParse, getParse } from "./parseCache";
+import { buildSnippetList } from "./features/snippetList";
 import { resolveClientCapabilities, setClientCapabilities } from "./clientMode";
 import { isIgnoredByConfig, isSuppressedInline, scanInlineSuppressions } from "@px-lsp/protocol/suppression";
 import { computeModOverview } from "./overview/modOverview";
 import { computeLocCoverage } from "./overview/locCoverage";
 import { computeOverrides } from "./overview/overrides";
 import { computeEventGraph } from "./overview/eventGraph";
+import { computeDynastyTree } from "./overview/dynastyTree";
 import { computeEventVocabulary, computeValueOptions } from "./overview/eventVocabulary";
 import { computeEventBanner } from "./overview/eventBanner";
+import { computeDefinitionForm } from "./creators/definitionForm";
+import { computeDefinitionEdits } from "./creators/definitionEdit";
+import { computeModifierFormats } from "./creators/modifierFormats";
+import { computeLocText, type LocTextDeps } from "./features/locText";
 import { computeDependencies } from "./overview/dependencies";
 import { wordRangeAt } from "./wordAt";
 
@@ -579,6 +600,30 @@ function workspaceRootOf(fsPath: string): string | null {
   return workspaceModRoots().find((r) => lower.startsWith(r.toLowerCase())) ?? null;
 }
 
+/**
+ * The display calendar a file's dates follow: the owning mod's
+ * `<mod>/.px-toolkit/calendar.json` (read once per root, dropped when the file
+ * changes), else the window-scoped `calendar` setting. `source` names which one
+ * for the hover, so a wrong date can be traced to its declaration.
+ */
+const calendarByRoot = new Map<string, { calendar: CalendarSetting; source: string } | null>();
+function calendarFor(fsPath: string): { calendar: CalendarSetting | undefined; source: string } {
+  const root = workspaceRootOf(fsPath);
+  if (root) {
+    const key = root.toLowerCase();
+    let cached = calendarByRoot.get(key);
+    if (cached === undefined) {
+      const read = readCalendarFile(root, activeProfile());
+      cached = read?.calendar
+        ? { calendar: read.calendar, source: path.relative(root, read.file).replace(/\\/g, "/") }
+        : null;
+      calendarByRoot.set(key, cached);
+    }
+    if (cached) return cached;
+  }
+  return { calendar: settings.calendar, source: "px.calendar" };
+}
+
 /** Schema entry for the folder a file lives in (structure/ambient/root-scope seed). */
 function schemaEntryForFile(fsPath: string): SchemaEntry | null {
   const lower = fsPath.toLowerCase();
@@ -1077,7 +1122,7 @@ function rebuildModNamespaces(): void {
 
 /** Ordered parent-mod roots from <mod>/<configDir>/playset.json, if present. */
 function readPlayset(modPath: string): string[] {
-  const file = path.join(modPath, activeProfile().configDirName, "playset.json");
+  const file = path.join(resolveConfigDir(modPath, activeProfile()), "playset.json");
   try {
     if (!fs.existsSync(file)) return [];
     const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
@@ -1104,6 +1149,7 @@ async function buildIndex(): Promise<void> {
   const tBuild = Date.now();
   const generation = ++scanGeneration;
   clearPathCaches();
+  calendarByRoot.clear();
   schema = loadSchema([...(settings.modPath ? [settings.modPath] : []), ...workspaceModRoots()], log);
   data.completableKinds = new Set([
     ...schema.entries.filter((e) => e.completable !== false).map((e) => e.kind),
@@ -1431,7 +1477,11 @@ connection.onInitialized(() => {
   // ourselves when the client supports dynamic registration.
   if (!clientOwnFileWatcher && clientWatchedFilesDynamic) {
     void connection.client.register(DidChangeWatchedFilesNotification.type, {
-      watchers: [{ globPattern: "**/*.{txt,yml,gui,mod}" }, { globPattern: "**/metadata.json" }],
+      watchers: [
+        { globPattern: "**/*.{txt,yml,gui,mod}" },
+        { globPattern: "**/metadata.json" },
+        { globPattern: "**/calendar.json" },
+      ],
     });
   }
   // Bundled frequency tables for completion ranking (§C3); fail-soft to empty.
@@ -1546,6 +1596,7 @@ function applyModFileChange(fsPath: string): void {
   const lower = fsPath.toLowerCase();
   if (lower.endsWith(".mod") || lower.endsWith("metadata.json")) refreshModOrigin();
   if (lower.endsWith(".gui")) invalidateGuiDefsCache();
+  if (isCalendarFile(fsPath, activeProfile())) calendarByRoot.clear();
   // Full re-harvest when a mod defines file or a gui file WITH textformatting
   // changed. Not on every .gui: the harvest reads only those out of gui/, and
   // autosave fires this after every GUI editor gesture.
@@ -1586,6 +1637,13 @@ connection.onRequest(eventGraphRequest, (params: EventGraphParams) =>
   computeEventGraph(data, params ?? {}, focusFilter(params?.modRoot))
 );
 
+// The dynasty picker list, or one dynasty's houses and members. The whole
+// character corpus is read once per index revision (see overview/dynastyTree.ts);
+// a profile without a `dynasty` schema kind answers supported: false.
+connection.onRequest(dynastyTreeRequest, (params: DynastyTreeParams | null) =>
+  computeDynastyTree(data, params ?? {}, focusFilter(params?.modRoot))
+);
+
 // What an event editor may offer: the profile's structure table, the schema's
 // reference fields resolved through the index, and the script_docs tokens.
 // Never a hand-written name list.
@@ -1605,6 +1663,26 @@ connection.onRequest(eventBannerRequest, (params: EventBannerParams) =>
   computeEventBanner(data, params?.theme ?? "")
 );
 
+// What a visual creator may offer for one definition kind: the schema entry,
+// the harvested structure keys, the index (options and the mod's own
+// definitions) and the modifier tokens. Never a hand-written field list.
+connection.onRequest(definitionFormRequest, (params: DefinitionFormParams | null) =>
+  computeDefinitionForm(data, schema, params ?? { kind: "" }, focusFilter(params?.modRoot))
+);
+
+// The script sibling of guiSourceEdit: the creators' writes as offsets into the
+// text the host handed over, applied there as one WorkspaceEdit.
+connection.onRequest(definitionEditRequest, (params: DefinitionEditParams | null) =>
+  computeDefinitionEdits(params)
+);
+
+// How the game itself prints a modifier: the profile's format folder, the loc
+// index and the game's own texticon blocks. A profile that names no formats
+// source answers null instead of a made-up label.
+connection.onRequest(modifierFormatsRequest, (params: ModifierFormatsParams | null) =>
+  computeModifierFormats(data, activeProfile().modifierFormats, settings.gamePath, params?.lines)
+);
+
 connection.onRequest(guiTreeRequest, (params: GuiTreeParams) => buildGuiTree(params.text ?? ""));
 
 /** Loc keys resolve through the index (configured language, english files as fallback). */
@@ -1768,6 +1846,26 @@ connection.onRequest(scopeAtRequest, (params: ScopeAtParams): ScopeAtResult | nu
   );
 });
 
+connection.onRequest(snippetsRequest, (params: SnippetsParams): SnippetsResult => {
+  // Open script documents only; anything else is an empty list, not an error:
+  // a host that offers an "Insert Snippet" command asks from wherever the user
+  // happens to be.
+  const doc = params?.uri ? documents.get(params.uri) : undefined;
+  if (!doc || !isScriptLanguage(doc.languageId) || !params.position) return { snippets: [] };
+  const entry = schemaEntryForFile(URI.parse(doc.uri).fsPath);
+  const { result } = getParse(doc);
+  return {
+    snippets: buildSnippetList(
+      result,
+      doc.offsetAt(params.position),
+      entry?.kind ?? null,
+      activeProfile().skeletons,
+      data.tokens,
+      freqs.tokens
+    ),
+  };
+});
+
 connection.onRequest(lookupLocRequest, (params: LookupLocParams): LocEntryInfo[] => {
   return data.index
     .lookup(params.key)
@@ -1775,6 +1873,39 @@ connection.onRequest(lookupLocRequest, (params: LookupLocParams): LocEntryInfo[]
     .map((d) => ({ file: d.file, line: d.line, source: d.source, value: d.value }));
 });
 
+/**
+ * What paradox/locText resolves a value with: the loc index for the words, the
+ * definition index for the kind a `Get<Something>('name')` chain names, and the
+ * active profile's schema for the loc key that kind's names take. A kind the
+ * schema states nothing for falls back to the bare name inside locText.ts, so
+ * every game answers from its own table with no per-game branch here.
+ */
+function locTextDeps(): LocTextDeps {
+  return {
+    loc: locValue,
+    kindsOf: (name) => [
+      ...new Set(
+        data.index
+          .lookup(name)
+          .filter((d) => d.kind !== "loc_key")
+          .map((d) => d.kind)
+      ),
+    ],
+    patternsOf: (kind) => {
+      const entry = schema.entries.find((e) => e.kind === kind);
+      // The conservative `requiredLoc` first (the pattern nearly every
+      // definition of the kind defines), then the full `locPatterns` set.
+      return [entry?.requiredLoc?.[0], entry?.locPatterns?.[0]].filter((p): p is string => !!p);
+    },
+  };
+}
+
+// A loc value as the PLAYER reads it: markup stripped and the game's own
+// datafunctions resolved through the loc, definition and schema tables.
+connection.onRequest(locTextRequest, (params: LocTextParams | null) =>
+  computeLocText(params?.keys ?? [], locTextDeps())
+);
+
 // ---- language features ----------------------------------------------------------
 
 connection.onCompletion((params) =>
@@ -1845,7 +1976,8 @@ connection.onHover((params) =>
     if (!isScriptLanguage(doc.languageId)) return null;
     const fsPath = URI.parse(doc.uri).fsPath;
     const entry = schemaEntryForFile(fsPath);
-    const dateHover = provideDateHover(settings.calendar, doc, params.position);
+    const { calendar, source } = calendarFor(fsPath);
+    const dateHover = provideDateHover(calendar, doc, params.position, source);
     if (dateHover) return dateHover;
     const texture = provideTextureHover(settings, doc, params.position, entry?.kind);
     if (texture) return texture;
@@ -1932,11 +2064,20 @@ connection.languages.inlayHint.on((params) =>
   indexRead(`inlayHint ${perfName(params.textDocument.uri)}`, () => {
     const doc = documents.get(params.textDocument.uri);
     if (!doc) return [];
-    const entry = schemaEntryForFile(URI.parse(doc.uri).fsPath);
+    const fsPath = URI.parse(doc.uri).fsPath;
+    const entry = schemaEntryForFile(fsPath);
     const rootScopes = entry?.rootScopes?.length
       ? new Set(entry.rootScopes.map((s) => s.toLowerCase()))
       : null;
-    return provideInlayHints(data, settings, doc, params.range, rootScopes, entry);
+    return provideInlayHints(
+      data,
+      settings,
+      doc,
+      params.range,
+      rootScopes,
+      entry,
+      calendarFor(fsPath).calendar
+    );
   })
 );