@px-lsp/server 0.1.0

package/src/schema/loader.ts

@@ -0,0 +1,113 @@
+/**
+ * Schema loading: the active game profile's bundled schema table merged with an
+ * optional per-workspace overlay at `<mod>/<configDir>/schema.json`, so
+ * total-conversion frameworks can teach the extension their own folders
+ * without a release.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { activeProfile } from "../games/active";
+import type { GameProfile } from "../games/profile";
+import type { AmbientScope, SchemaEntry, KeySpec, RefField, SchemaOverlay } from "./types";
+
+/**
+ * Per-kind structure/ambient lookup precomputed at schema load (v1.1 §B2/§B3),
+ * so completion and hover do no per-request scans (perf budget ~1-2 ms).
+ */
+export interface StructureIndex {
+  /** kind -> block name ("" = top level) -> KeySpec, for key/doc lookup. */
+  keysByKindBlock: Map<string, Map<string, Map<string, KeySpec>>>;
+  /** kind -> ambient scope name -> AmbientScope. */
+  ambientByKind: Map<string, Map<string, AmbientScope>>;
+  /** kind -> provenance label for hover ("character_interactions"). */
+  source(kind: string): string | undefined;
+}
+
+export interface SchemaData {
+  entries: SchemaEntry[];
+  /** key -> field spec (merged). */
+  refFields: Map<string, RefField>;
+  /** value prefix -> candidate kinds. */
+  prefixRefs: Record<string, string[]>;
+  /** Precomputed structure/ambient lookup (v1.1). */
+  structures: StructureIndex;
+}
+
+function buildStructureIndex(profile: GameProfile, entries: SchemaEntry[]): StructureIndex {
+  const keysByKindBlock = new Map<string, Map<string, Map<string, KeySpec>>>();
+  const ambientByKind = new Map<string, Map<string, AmbientScope>>();
+  for (const entry of entries) {
+    if (entry.structure) {
+      const byBlock = new Map<string, Map<string, KeySpec>>();
+      const top = new Map<string, KeySpec>();
+      for (const spec of entry.structure.topLevel) top.set(spec.key, spec);
+      byBlock.set("", top);
+      for (const [name, specs] of Object.entries(entry.structure.blocks ?? {})) {
+        const m = new Map<string, KeySpec>();
+        for (const spec of specs) m.set(spec.key, spec);
+        byBlock.set(name, m);
+      }
+      keysByKindBlock.set(entry.kind, byBlock);
+    }
+    if (entry.ambientScopes) {
+      const m = new Map<string, AmbientScope>();
+      for (const a of entry.ambientScopes) m.set(a.name, a);
+      ambientByKind.set(entry.kind, m);
+    }
+  }
+  return {
+    keysByKindBlock,
+    ambientByKind,
+    source: (kind) => profile.structureSources[kind],
+  };
+}
+
+export function loadSchema(modPath: string | string[] | null, log?: (msg: string) => void): SchemaData {
+  const profile = activeProfile();
+  const entries = [...profile.schema];
+  const refFields = new Map<string, RefField>();
+  for (const f of profile.refFields) refFields.set(f.key, f);
+  const prefixRefs: Record<string, string[]> = { ...profile.prefixRefs };
+
+  // Multi-mod workspaces: every workspace mod may carry an overlay; later
+  // roots win on collisions (roots are passed in load order, mod-of-record
+  // first, collisions are rare and per-path).
+  const roots = modPath === null ? [] : Array.isArray(modPath) ? modPath : [modPath];
+  for (const root of roots) {
+    const overlayFile = path.join(root, profile.configDirName, "schema.json");
+    try {
+      if (!fs.existsSync(overlayFile)) continue;
+      const overlay = JSON.parse(fs.readFileSync(overlayFile, "utf8")) as SchemaOverlay;
+      for (const e of overlay.entries ?? []) {
+        if (typeof e?.path !== "string" || typeof e?.kind !== "string") continue;
+        // Overlay entries replace bundled ones with the same path.
+        const i = entries.findIndex((x) => x.path === e.path);
+        if (i >= 0) entries[i] = e;
+        else entries.push(e);
+      }
+      for (const f of overlay.refFields ?? []) {
+        if (typeof f?.key !== "string" || !Array.isArray(f?.kinds)) continue;
+        refFields.set(f.key, f);
+      }
+      for (const [prefix, kinds] of Object.entries(overlay.prefixRefs ?? {})) {
+        if (Array.isArray(kinds)) prefixRefs[prefix] = kinds;
+      }
+      log?.(`schema overlay loaded from ${overlayFile}`);
+    } catch (err) {
+      log?.(`schema overlay ignored (${overlayFile}): ${String(err)}`);
+    }
+  }
+
+  // Profile-level structure layer (a fully harvested one, as opposed to a schema
+  // table that already carries curated `structure` on its entries). Applied last
+  // so workspace-overlay folders of a known kind get it too; an entry that
+  // already declares its own structure keeps it.
+  if (profile.structures) {
+    for (let i = 0; i < entries.length; i++) {
+      const structure = profile.structures[entries[i].kind];
+      if (structure && !entries[i].structure) entries[i] = { ...entries[i], structure };
+    }
+  }
+
+  return { entries, refFields, prefixRefs, structures: buildStructureIndex(profile, entries) };
+}

package/src/schema/types.ts

@@ -0,0 +1,142 @@
+/**
+ * The game type schema (rework plan AD-3): a *small*, declarative,
+ * community-editable table describing what lives in each game folder, how
+ * definitions are named, which loc keys a type requires, what scope its
+ * script blocks run in, and which assignment keys cross-reference other
+ * definitions.
+ *
+ * This is deliberately NOT a validation-rule language (that was CWTools'
+ * mistake); deep semantic validation is the tiger validator's job. The schema feeds
+ * navigation, completion, hover, references, rename, coverage and (very
+ * conservative) structural diagnostics.
+ */
+
+/** How definition names are extracted from files in a folder. */
+export type NameExtraction =
+  /** One definition per top-level assignment key (`my_thing = { ... }`). */
+  | "top-level-key"
+  /** Event files: only `namespace.NNN` top-level keys are definitions. */
+  | "event-id"
+  /** Landed titles: keys matching /^[ekdcb]_/ at any nesting depth. */
+  | "nested-title"
+  /** GUI files: `type X = base { ... }` and `template X { ... }` statements. */
+  | "gui-type"
+  /** Localization yml entries. */
+  | "loc-key";
+
+/**
+ * One documented key inside a definition's body or a named sub-block (v1.1 §B2).
+ * `values` is a coarse value hint ("enum:a|b|c" for enumerations); `freq` is the
+ * per-context usage count used for ranking (Workstream C).
+ */
+export interface KeySpec {
+  key: string;
+  doc?: string;
+  values?: "loc" | "bool" | "block" | `enum:${string}`;
+  freq?: number;
+  /**
+   * Root scope of the block this key opens, when the game's `_*.info` doc
+   * declares one (`# root = the activity` → "activity"). Scope inference sets
+   * the current scope to this when walking through the key.
+   */
+  scope?: string;
+  /**
+   * Hand-curated entry (structures.ts): its position in the curated list is
+   * deliberate and outranks any harvested key. Harvested `.info` freqs count
+   * usage at ANY depth in the folder, so re-sorting curated top-level keys by
+   * them lets option-level keys (name, modifier…) bury the real top-level
+   * vocabulary, the completion regression rank-eval caught in 2026-07.
+   */
+  curated?: boolean;
+}
+
+/** The document shape of a definition kind: top-level keys plus named sub-blocks. */
+export interface StructureSpec {
+  topLevel: KeySpec[];
+  /** Named sub-blocks (option, send_option, cost…) with their own keys. */
+  blocks?: Record<string, KeySpec[]>;
+}
+
+/**
+ * How one definition kind declares the root scope of its own script blocks
+ * (scopes/inference.ts). Games disagree on both the key and the vocabulary: one
+ * writes `scope = character` inside an event, another writes `type = X_event`.
+ * That is why this table lives on the game profile and not in the engine,
+ * assuming one game's spelling everywhere puts every event of the other game in
+ * the wrong root scope, which demotes every correct effect to "other scope" and
+ * sinks it to the bottom of completion.
+ */
+export interface DefRootKey {
+  /** Key inside the definition body that names the root scope. */
+  key: string;
+  /** Scope when the key is absent. Omit = fall back to the schema's rootScopes. */
+  default?: string;
+  /**
+   * Declared value → scope name, for games that do not spell the value as the
+   * scope (`country_event` → country). Absent = the value IS the scope name.
+   * A value the map does not list falls back to `default`.
+   */
+  values?: Record<string, string>;
+}
+
+/** An engine-provided saved scope available in a kind's script blocks (v1.1 §B3). */
+export interface AmbientScope {
+  name: string;
+  type: string;
+  doc: string;
+}
+
+export interface SchemaEntry {
+  /** Folder relative to the game/mod root, forward slashes, no trailing slash. */
+  path: string;
+  /** Definition kind, singular snake_case (e.g. "trait", "decision"). */
+  kind: string;
+  /** File extension, default ".txt". */
+  ext?: string;
+  /** Name extraction mode, default "top-level-key". */
+  extraction?: NameExtraction;
+  /**
+   * Loc keys the game requires per definition; `$` is the definition name
+   * (e.g. "trait_$", "$_desc"). Used for conservative missing-loc diagnostics
+   * and loc coverage, only include patterns that ≥95% of vanilla definitions
+   * of this kind actually define.
+   */
+  requiredLoc?: 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).
+   * False for huge/noisy kinds (history characters, provinces). */
+  completable?: boolean;
+  /**
+   * Block-local structural keys for this kind (v1.1 §B2). Sourced from the game's
+   * `_*.info` files. Static, not harvested at runtime. Not yet overlayable (F5).
+   */
+  structure?: StructureSpec;
+  /** Engine-provided saved scopes for this kind (v1.1 §B3). Not yet overlayable (F5). */
+  ambientScopes?: AmbientScope[];
+}
+
+/** Form a cross-reference field takes. */
+export type RefFieldForm =
+  /** `key = name` */
+  | "scalar"
+  /** `key = { name_a name_b ... }` */
+  | "list"
+  /** either of the above */
+  | "both";
+
+/** An assignment key whose value references definitions of the given kinds. */
+export interface RefField {
+  key: string;
+  kinds: string[];
+  form?: RefFieldForm; // default "scalar"
+  /** List also accepts weighted entries (`<number> = name`), like random_events. */
+  weighted?: boolean;
+}
+
+/** JSON shape of the optional workspace overlay at <configDir>/schema.json. */
+export interface SchemaOverlay {
+  entries?: SchemaEntry[];
+  refFields?: RefField[];
+  prefixRefs?: Record<string, string[]>;
+}