@px-lsp/server 0.1.0

package/src/overview/dependencies.ts

@@ -0,0 +1,240 @@
+/**
+ * paradox/dependencies: a generic dependency explorer for any indexed definition.
+ *
+ * Dependents  — mod sites that reference the definition, grouped by the kind
+ *   of their containing top-level definition (else by file). Schema-captured
+ *   references come from the reference index (find-references semantics); bare
+ *   `name = …` invocations of scripted effects/triggers, which the reference
+ *   extractor does not record (they are keys, not schema field values), are
+ *   found by a targeted scan of the mod's definition files. Vanilla references
+ *   are not indexed (rework plan AD-4), so vanilla callers never appear here.
+ *
+ * Dependencies — named definitions referenced inside the definition's own block
+ *   span, grouped by the referenced definition's kind. The file is parsed on
+ *   demand: extractReferences (schema fields, prefixed values, loc keys) is
+ *   filtered to the block's lines, then a scalar walk adds the bare scripted
+ *   effect/trigger calls and script-value scalars the extractor misses.
+ *
+ * No `vscode` imports: unit-tested in plain Node.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import type {
+  DependenciesResult,
+  DependencyGroup,
+  DependencyItem,
+  GuiUseSite,
+} from "@px-lsp/protocol/protocol";
+import type { Definition } from "@px-lsp/protocol/types";
+import { pushAll } from "@px-lsp/protocol/arrays";
+import type { ServerData } from "../serverData";
+import type { SchemaData } from "../schema/loader";
+import { extractReferences } from "../index/references";
+import { decode, LineIndex, parseScript, walkStatements, type BlockNode, type Statement } from "../parser";
+
+/** Definition kinds invoked as a bare `name = …` key (not captured as references). */
+const CALL_KINDS = new Set(["scripted_effect", "scripted_trigger"]);
+
+export function computeDependencies(
+  data: ServerData,
+  schema: SchemaData,
+  name: string,
+  kind?: string,
+  /** The GUI half of the answer, when the caller asked for it. Injected rather
+   *  than imported so this module stays free of the gui store's file walk. */
+  guiUses?: (name: string) => GuiUseSite[]
+): DependenciesResult {
+  const resolved = data.index.lookup(name);
+  const candidates = resolved.length > 0 ? resolved : data.index.lookupAll(name);
+  const def = (kind ? candidates.find((d) => d.kind === kind) : undefined) ?? candidates[0] ?? null;
+  if (!def) return { def: null, dependents: [], dependencies: [], ...(guiUses ? { guiUses: [] } : {}) };
+
+  return {
+    def: { name: def.name, kind: def.kind, file: def.file, line: def.line },
+    dependents: collectDependents(data, def),
+    dependencies: collectDependencies(data, schema, def),
+    ...(guiUses ? { guiUses: guiUses(def.name) } : {}),
+  };
+}
+
+// ---- dependents -------------------------------------------------------------
+
+interface Site {
+  file: string;
+  line: number;
+}
+
+function collectDependents(data: ServerData, def: Definition): DependencyGroup[] {
+  const sites: Site[] = data.refIndex.lookup(def.name).map((r) => ({ file: r.file, line: r.line }));
+  if (CALL_KINDS.has(def.kind)) pushAll(sites, scanCallSites(data, def));
+
+  const groups = new Map<string, Map<string, DependencyItem>>();
+  for (const site of sites) {
+    const container = containingDef(data, site.file, site.line);
+    const groupKind = container ? container.kind : "file";
+    const itemName = container ? container.name : path.basename(site.file);
+    const dedupe = `${itemName} ${site.file}`;
+    let byItem = groups.get(groupKind);
+    if (!byItem) groups.set(groupKind, (byItem = new Map()));
+    // First site wins the jump target: the actual usage line.
+    if (!byItem.has(dedupe)) byItem.set(dedupe, { name: itemName, file: site.file, line: site.line });
+  }
+  return toGroups(groups);
+}
+
+/**
+ * Bare `name = …` invocations across the mod's definition files. These are the
+ * scripted effect/trigger calls the reference extractor cannot record (the name
+ * is a key, and the extractor does not know which keys resolve to definitions).
+ * The definition's own site is excluded.
+ */
+function scanCallSites(data: ServerData, def: Definition): Site[] {
+  const sites: Site[] = [];
+  const seen = new Set<string>();
+  for (const file of modFiles(data)) {
+    let text: string;
+    try {
+      text = decode(fs.readFileSync(file)).text;
+    } catch {
+      continue;
+    }
+    if (!text.includes(def.name)) continue;
+    const parse = parseScript(text);
+    const li = new LineIndex(text);
+    walkStatements(parse.root, (stmt: Statement) => {
+      if (stmt.kind !== "assignment" || stmt.key.quoted || stmt.key.text !== def.name) return;
+      const line = li.positionAt(stmt.key.range.start).line;
+      if (file === def.file && line === def.line) return; // the definition itself
+      const key = `${file} ${line}`;
+      if (seen.has(key)) return;
+      seen.add(key);
+      sites.push({ file, line });
+    });
+  }
+  return sites;
+}
+
+/** Unique mod definition files (where realistic caller sites live). */
+function modFiles(data: ServerData): string[] {
+  const files = new Set<string>();
+  for (const d of data.index.allDefinitions()) {
+    if (d.source === "mod" && d.file.toLowerCase().endsWith(".txt")) files.add(d.file);
+  }
+  return [...files];
+}
+
+/**
+ * The top-level definition in `file` whose block encloses `line`: the one with
+ * the greatest start line at or before it. Implicit/nested sites (save_scope_as
+ * etc., which carry a container) are skipped so the real container is found.
+ */
+function containingDef(data: ServerData, file: string, line: number): Definition | null {
+  let best: Definition | null = null;
+  for (const d of data.index.inFile(file)) {
+    if (d.container !== undefined) continue;
+    if (d.line <= line && (!best || d.line > best.line)) best = d;
+  }
+  return best;
+}
+
+// ---- dependencies -----------------------------------------------------------
+
+function collectDependencies(data: ServerData, schema: SchemaData, def: Definition): DependencyGroup[] {
+  let text: string;
+  try {
+    text = decode(fs.readFileSync(def.file)).text;
+  } catch {
+    return [];
+  }
+  const parse = parseScript(text);
+  const li = new LineIndex(text);
+  const lineOf = (offset: number) => li.positionAt(offset).line;
+  const stmt = parse.root.statements.find(
+    (s): s is Statement & { kind: "assignment" } =>
+      s.kind === "assignment" && s.key.text === def.name && lineOf(s.key.range.start) === def.line
+  );
+  const block = stmt ? childBlock(stmt) : null;
+  if (!block) return [];
+  const startLine = lineOf(block.range.start);
+  const endLine = block.closeBrace !== null ? lineOf(block.closeBrace) : lineOf(block.range.end);
+
+  const groups = new Map<string, Map<string, DependencyItem>>();
+  const addTarget = (target: Definition) => {
+    const dedupe = `${target.kind} ${target.name}`;
+    let byItem = groups.get(target.kind);
+    if (!byItem) groups.set(target.kind, (byItem = new Map()));
+    if (!byItem.has(dedupe)) {
+      byItem.set(dedupe, { name: target.name, file: target.file, line: target.line });
+    }
+  };
+
+  // (a) Schema-captured references within the block: traits (has_trait), events
+  //     (trigger_event), cultures/faiths, loc keys, variables/flags/scopes.
+  for (const ref of extractReferences(text, def.file, def.source, schema).references) {
+    if (ref.line < startLine || ref.line > endLine || ref.name === def.name) continue;
+    const target = resolveTarget(data, ref.name, ref.kinds);
+    if (target) addTarget(target);
+  }
+
+  // (b) Bare `name = …` calls to scripted effects/triggers and script-value
+  //     scalars, which the reference extractor does not record. Same resolution
+  //     as the event inspector (eventDetail.collectRefs); the group map dedupes
+  //     any overlap with (a).
+  walkScalars(block, (word, isKey) => {
+    if (word === def.name) return;
+    const defs = data.index.lookup(word);
+    if (defs.length === 0) return;
+    const target = isKey
+      ? defs.find((d) => d.kind === "scripted_effect" || d.kind === "scripted_trigger")
+      : defs.find((d) => d.kind === "script_value");
+    if (target) addTarget(target);
+  });
+
+  return toGroups(groups);
+}
+
+/** Visit every unquoted scalar in a block: keys (isKey=true) and values. */
+function walkScalars(block: BlockNode, cb: (word: string, isKey: boolean) => void): void {
+  for (const stmt of block.statements) {
+    if (stmt.kind === "assignment") {
+      if (!stmt.key.quoted) cb(stmt.key.text, true);
+      const v = stmt.value;
+      if (v?.kind === "scalar" && !v.quoted) cb(v.text, false);
+      const sub = childBlock(stmt);
+      if (sub) walkScalars(sub, cb);
+    } else if (stmt.value.kind === "scalar" && !stmt.value.quoted) {
+      cb(stmt.value.text, false);
+    } else if (stmt.value.kind === "block") {
+      walkScalars(stmt.value, cb);
+    } else if (stmt.value.kind === "tagged-block") {
+      walkScalars(stmt.value.block, cb);
+    }
+  }
+}
+
+/** Best index match for a reference: prefer a def whose kind the ref allows. */
+function resolveTarget(data: ServerData, name: string, kinds: string[]): Definition | null {
+  const defs = data.index.lookup(name);
+  if (defs.length === 0) return null;
+  return defs.find((d) => kinds.includes(d.kind)) ?? defs[0];
+}
+
+// ---- shared -----------------------------------------------------------------
+
+function childBlock(stmt: Statement): BlockNode | null {
+  if (stmt.kind !== "assignment") return 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;
+}
+
+function toGroups(groups: Map<string, Map<string, DependencyItem>>): DependencyGroup[] {
+  return [...groups.entries()]
+    .map(([kind, byItem]) => ({
+      kind,
+      items: [...byItem.values()].sort((a, b) => a.name.localeCompare(b.name)),
+    }))
+    .sort((a, b) => a.kind.localeCompare(b.kind));
+}

package/src/overview/eventBanner.ts

@@ -0,0 +1,95 @@
+/**
+ * paradox/eventBanner: the illustration an event theme puts behind its window.
+ *
+ * Two hops through the game's own files, no name table of our own:
+ *
+ *   theme  common/event_themes    `background = { reference = throne_room }`
+ *   bg     common/event_backgrounds `background = { reference = "gfx/....dds" }`
+ *
+ * Both levels list several `background` blocks, all but the last gated by a
+ * `trigger` that only the running game can evaluate. The honest pick is the
+ * LAST block with no trigger: the file's own unconditional fallback (measured
+ * against the vanilla tree, where every background definition ends in one).
+ * A theme whose reference is already a path skips the second hop.
+ *
+ * Answering null is a real answer: the caller draws a labeled placeholder
+ * rather than a picture that is not the event's.
+ */
+import * as fs from "fs";
+import type { EventBannerResult } from "@px-lsp/protocol/protocol";
+import type { ServerData } from "../serverData";
+import { decode, parseScript, type BlockNode, type Statement } from "../parser";
+
+/** A reference that already names a file rather than another definition. */
+const TEXTURE_PATH = /\.(dds|tga|png)$/i;
+
+export function computeEventBanner(data: ServerData, theme: string): EventBannerResult {
+  // The graph sends whatever the event itself names: an override_background
+  // reference (an event_background key, or already a texture path) wins over
+  // the theme, because that is the picture the game actually shows.
+  if (TEXTURE_PATH.test(theme)) return { theme, texture: theme };
+
+  const themeRef = referenceOf(data, theme, "event_theme");
+  if (themeRef !== null) {
+    if (TEXTURE_PATH.test(themeRef)) return { theme, texture: themeRef };
+    const backgroundRef = referenceOf(data, themeRef, "event_background");
+    if (backgroundRef === null) return { theme, reason: `no background definition named ${themeRef}` };
+    if (!TEXTURE_PATH.test(backgroundRef)) return { theme, reason: `${themeRef} names no texture` };
+    return { theme, texture: backgroundRef };
+  }
+
+  // Not a theme: an event_background named directly (override_background).
+  const direct = referenceOf(data, theme, "event_background");
+  if (direct === null) return { theme, reason: "no theme or background definition with a background" };
+  if (!TEXTURE_PATH.test(direct)) return { theme, reason: `${theme} names no texture` };
+  return { theme, texture: direct };
+}
+
+/**
+ * The `reference` of a definition's fallback `background` block: the last one
+ * that carries no `trigger`, else the last one there is.
+ */
+function referenceOf(data: ServerData, name: string, kind: string): string | null {
+  const def = data.index.lookup(name).find((d) => d.kind === kind);
+  if (!def) return null;
+  let block: BlockNode | null = null;
+  try {
+    const text = decode(fs.readFileSync(def.file)).text;
+    const stmt = parseScript(text).root.statements.find(
+      (s): s is Statement & { kind: "assignment" } => s.kind === "assignment" && s.key.text === name
+    );
+    block = stmt ? childBlock(stmt) : null;
+  } catch {
+    return null;
+  }
+  if (!block) return null;
+
+  let fallback: string | null = null;
+  let last: string | null = null;
+  for (const stmt of block.statements) {
+    if (stmt.kind !== "assignment" || stmt.key.text.toLowerCase() !== "background") continue;
+    const body = childBlock(stmt);
+    if (!body) continue;
+    let reference: string | null = null;
+    let gated = false;
+    for (const child of body.statements) {
+      if (child.kind !== "assignment") continue;
+      const key = child.key.text.toLowerCase();
+      if (key === "trigger") gated = true;
+      else if (key === "reference" && child.value?.kind === "scalar") reference = child.value.text;
+    }
+    if (reference === null) continue;
+    last = reference;
+    if (!gated) fallback = reference;
+  }
+  return fallback ?? last;
+}
+
+function childBlock(stmt: Statement): BlockNode | null {
+  if (stmt.kind !== "assignment") return 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;
+}