@px-lsp/protocol 0.1.0

package/src/regex.ts

@@ -0,0 +1,19 @@
+/**
+ * One correct copy of the regex-escape both sides need. It lived inline at five
+ * call sites and one of them had an extra backslash, which silently turned the
+ * escape into a no-op (it matched a metacharacter followed by two literal
+ * backslashes, so nothing was ever escaped).
+ */
+
+/** Escape every regex metacharacter in `literal` so it matches itself. */
+export function escapeRegExp(literal: string): string {
+  return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * A pattern matching `name` only as a whole script identifier: not when it is
+ * a substring of a longer name, and not across a dot-chain segment boundary.
+ */
+export function wholeNamePattern(name: string): string {
+  return `(?<![A-Za-z0-9_.\\-])${escapeRegExp(name)}(?![A-Za-z0-9_.\\-])`;
+}

package/src/suppression.ts

@@ -0,0 +1,178 @@
+/**
+ * Diagnostic suppression, shared by the server (own structural/loc diagnostics)
+ * and the client (tiger-forwarded reports) so one habit works across both tools.
+ *
+ * No `vscode` imports: plain data in, plain predicates out. Everything here is
+ * fail-soft — bad setting values or malformed comments are ignored, never thrown.
+ *
+ * Two mechanisms:
+ *   1. Settings: the diagnostics.ignore setting (diagnostic codes) and
+ *      the diagnostics.ignorePatterns setting (globs on the workspace-relative path).
+ *   2. Inline comments: `# px:ignore <code…>` (same line) and
+ *      `# px:ignore-next-line <code…>` (following line); a bare form with no
+ *      codes suppresses every diagnostic on the target line. A trailing
+ *      `-- <rationale>` is allowed and ignored.
+ */
+
+/**
+ * Settings-driven filter. `ignore` matches a diagnostic's code (our stable
+ * codes, or tiger's `key`); `ignorePatterns` matches globs against the
+ * workspace-relative file path.
+ */
+export interface DiagnosticIgnoreConfig {
+  /** Diagnostic codes to drop everywhere. */
+  ignore: string[];
+  /** Glob patterns matched against the workspace-relative (forward-slash) path. */
+  ignorePatterns: string[];
+}
+
+/** Normalize a raw settings array: strings only, trimmed, empties dropped. */
+export function sanitizeStringList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  const out: string[] = [];
+  for (const v of value) {
+    if (typeof v !== "string") continue;
+    const t = v.trim();
+    if (t !== "") out.push(t);
+  }
+  return out;
+}
+
+/**
+ * Tiny `*`/`**` glob matcher (no dependency). `*` matches within a path segment,
+ * `**` matches across segments (including `/`). Matching is done on
+ * forward-slash paths and is case-insensitive (Windows-friendly). A pattern with
+ * no slash also matches against the basename, so `*.txt` works like a gitignore
+ * entry. Returns false on any malformed pattern.
+ */
+export function globMatch(pattern: string, filePath: string): boolean {
+  const p = pattern.replace(/\\/g, "/").toLowerCase();
+  const f = filePath.replace(/\\/g, "/").replace(/^\/+/, "").toLowerCase();
+  if (p === "") return false;
+  try {
+    const re = new RegExp("^" + globToRegExpSource(p) + "$");
+    if (re.test(f)) return true;
+    // Slash-free patterns also match the basename (gitignore-style convenience).
+    if (!p.includes("/")) {
+      const base = f.slice(f.lastIndexOf("/") + 1);
+      return re.test(base);
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/** Translate a glob (already lowercased, forward-slashed) into a regex source. */
+function globToRegExpSource(glob: string): string {
+  let out = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        // `**` — cross segments, optionally swallowing a trailing slash.
+        i++;
+        if (glob[i + 1] === "/") {
+          i++;
+          out += "(?:.*/)?";
+        } else {
+          out += ".*";
+        }
+      } else {
+        out += "[^/]*";
+      }
+    } else if (c === "?") {
+      out += "[^/]";
+    } else if ("\\^$.|+()[]{}".includes(c)) {
+      out += "\\" + c;
+    } else {
+      out += c;
+    }
+  }
+  return out;
+}
+
+/** True when a diagnostic with `code` in `filePath` should be dropped by settings. */
+export function isIgnoredByConfig(
+  cfg: DiagnosticIgnoreConfig,
+  code: string | undefined,
+  relPath: string
+): boolean {
+  if (code !== undefined && cfg.ignore.includes(code)) return true;
+  for (const pattern of cfg.ignorePatterns) {
+    if (globMatch(pattern, relPath)) return true;
+  }
+  return false;
+}
+
+/**
+ * Inline suppression map for a file, keyed by 0-based line number. A `null`
+ * value means "suppress every code on this line"; an array means "suppress only
+ * these codes". Built by scanning comment lines once when publishing.
+ */
+export type InlineSuppressions = Map<number, string[] | null>;
+
+const IGNORE_RE = /#\s*px:ignore(-next-line)?\b([^\n]*)/i;
+
+/**
+ * Scan a document's text for `# px:ignore[-next-line] <code…>` comments.
+ * Cheap: only lines containing `px:ignore` are parsed. `-next-line` targets
+ * the following line; the plain form targets its own line.
+ */
+export function scanInlineSuppressions(text: string): InlineSuppressions {
+  const map: InlineSuppressions = new Map();
+  if (!text.includes("px:ignore")) return map;
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    // A comment can trail script on the same line; only look after the `#`.
+    const hash = line.indexOf("#");
+    if (hash < 0) continue;
+    const m = IGNORE_RE.exec(line.slice(hash));
+    if (!m) continue;
+    const target = m[1] ? i + 1 : i;
+    const codes = parseCodes(m[2]);
+    mergeSuppression(map, target, codes.length === 0 ? null : codes);
+  }
+  return map;
+}
+
+/**
+ * The codes following the marker, stopping at a `--` rationale. Writing a
+ * reason is the natural instinct, and without the cut-off every word of it
+ * parsed as a code — turning a suppression that matched everything into one
+ * that matched nothing, silently. Codes are kebab-case slugs
+ * (`unclosed-brace`, `loc-no-header`), so a leading `-` can only be the
+ * separator.
+ */
+function parseCodes(rest: string): string[] {
+  const out: string[] = [];
+  for (const token of rest.trim().split(/\s+/)) {
+    if (token === "") continue;
+    if (token.startsWith("-")) break; // `-- because the game allows it`
+    out.push(token);
+  }
+  return out;
+}
+
+function mergeSuppression(map: InlineSuppressions, line: number, codes: string[] | null): void {
+  const existing = map.get(line);
+  if (existing === undefined) {
+    map.set(line, codes);
+    return;
+  }
+  // `null` (suppress-all) wins; otherwise union the code lists.
+  if (existing === null || codes === null) {
+    map.set(line, null);
+    return;
+  }
+  map.set(line, [...existing, ...codes]);
+}
+
+/** True when line `line` has an inline suppression covering `code`. */
+export function isSuppressedInline(map: InlineSuppressions, line: number, code: string | undefined): boolean {
+  if (!map.has(line)) return false;
+  const codes = map.get(line) ?? null;
+  if (codes === null) return true; // bare `# px:ignore` suppresses all
+  return code !== undefined && codes.includes(code);
+}

package/src/tigerParser.ts

@@ -0,0 +1,79 @@
+/**
+ * Parser for tiger `--json` reports (the Paradox script validator family).
+ *
+ * Kept separate from the process management in tiger.ts so it stays free of
+ * `vscode` imports and defensively tolerant of format drift between tiger
+ * releases: unknown fields are ignored, malformed entries are skipped.
+ */
+
+export interface TigerLocation {
+  path: string;
+  fullpath?: string;
+  /** 1-based, may be missing for file-level reports. */
+  linenr?: number;
+  /** 1-based. */
+  column?: number;
+  length?: number;
+  tag?: string;
+}
+
+export interface TigerReport {
+  severity: string;
+  /** tiger also rates how sure it is: weak | reasonable | strong. */
+  confidence?: string;
+  key: string;
+  message: string;
+  info?: string;
+  locations: TigerLocation[];
+}
+
+/** Parse tiger's JSON output. Returns null if no JSON array can be found at all. */
+export function parseTigerJson(stdout: string): TigerReport[] | null {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(stdout);
+  } catch {
+    // tiger may print progress noise before the JSON; try from the first '['.
+    const start = stdout.indexOf("[");
+    if (start < 0) return null;
+    try {
+      raw = JSON.parse(stdout.slice(start));
+    } catch {
+      return null;
+    }
+  }
+  if (!Array.isArray(raw)) return null;
+
+  const reports: TigerReport[] = [];
+  for (const entry of raw) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const e = entry as Record<string, unknown>;
+    const message = typeof e.message === "string" ? e.message : null;
+    const locationsRaw = Array.isArray(e.locations) ? e.locations : [];
+    if (message === null) continue;
+    const locations: TigerLocation[] = [];
+    for (const locRaw of locationsRaw) {
+      if (typeof locRaw !== "object" || locRaw === null) continue;
+      const l = locRaw as Record<string, unknown>;
+      const p = typeof l.fullpath === "string" ? l.fullpath : typeof l.path === "string" ? l.path : null;
+      if (p === null) continue;
+      const loc: TigerLocation = { path: typeof l.path === "string" ? l.path : p };
+      if (typeof l.fullpath === "string") loc.fullpath = l.fullpath;
+      const linenr = l.linenr ?? l.line;
+      if (typeof linenr === "number") loc.linenr = linenr;
+      if (typeof l.column === "number") loc.column = l.column;
+      if (typeof l.length === "number") loc.length = l.length;
+      if (typeof l.tag === "string") loc.tag = l.tag;
+      locations.push(loc);
+    }
+    reports.push({
+      severity: typeof e.severity === "string" ? e.severity : "warning",
+      confidence: typeof e.confidence === "string" ? e.confidence : undefined,
+      key: typeof e.key === "string" ? e.key : "unknown",
+      message,
+      info: typeof e.info === "string" ? e.info : undefined,
+      locations,
+    });
+  }
+  return reports;
+}

package/src/translationCore.ts

@@ -0,0 +1,140 @@
+/**
+ * Pure logic for the translation scaffolding workflow: mirror the structure of
+ * an existing localization (usually english) into a new language so a
+ * translator only has to replace values.
+ *
+ * No `vscode` imports here: this module is unit-tested in plain Node.
+ */
+import * as path from "path";
+
+export const LOC_LANGUAGES = [
+  "english",
+  "french",
+  "german",
+  "spanish",
+  "russian",
+  "korean",
+  "simp_chinese",
+  "japanese",
+  "polish",
+];
+
+const BOM = "";
+const HEADER = /^(\s*)l_([a-z_]+):/m;
+const ENTRY = /^\s*([A-Za-z0-9_.\-']+):\d*\s*"/;
+
+/** Language of a loc file, from its `_l_<lang>.yml` suffix or a path segment. */
+export function detectLocFileLanguage(filePath: string): string | null {
+  const m = /_l_([a-z_]+)\.ya?ml$/i.exec(filePath);
+  if (m) return m[1].toLowerCase();
+  const segments = filePath.toLowerCase().split(/[\\/]/);
+  for (const lang of LOC_LANGUAGES) {
+    if (segments.includes(lang)) return lang;
+  }
+  return null;
+}
+
+/**
+ * Where the translated counterpart of `srcFile` lives: language path segments
+ * and the `_l_<lang>` filename marker are retargeted. Returns null when the
+ * path carries no language marker at all.
+ */
+export function retargetLocPath(srcFile: string, sourceLang: string, targetLang: string): string | null {
+  const parts = srcFile.split(/([\\/])/); // keep separators
+  let changed = false;
+  const out = parts.map((p) => {
+    if (p.toLowerCase() === sourceLang) {
+      changed = true;
+      return targetLang;
+    }
+    return p;
+  });
+  let result = out.join("");
+  const marker = new RegExp(`_l_${sourceLang}(\\.ya?ml)$`, "i");
+  if (marker.test(path.basename(result))) {
+    result = result.replace(marker, `_l_${targetLang}$1`);
+    changed = true;
+  }
+  return changed ? result : null;
+}
+
+// Greedy `(.*)` closes the value at the LAST quote before any trailing
+// comment, matching the game's parsing of inner quotes (`""speech""`).
+const ENTRY_LINE = /^(\s*[A-Za-z0-9_.\-']+:\d*\s*)"(.*)"\s*(#.*)?$/;
+
+/** Blank an entry's value, keeping the source text visible as a comment. */
+function blankEntry(line: string, sourceLang: string): string {
+  const m = ENTRY_LINE.exec(line);
+  if (!m || m[2] === "") return line;
+  // The game reads the value up to the last quote on the LINE, so any quote
+  // echoed into the comment would leak back into the value; downgrade to '.
+  const comment = `# ${sourceLang}: ${m[2]}${m[3] ? ` ${m[3]}` : ""}`.replace(/"/g, "'");
+  return `${m[1]}"" ${comment}`;
+}
+
+/**
+ * A translation skeleton: the source file's structure (comments and blank
+ * lines preserved — they are context for the translator) with the language
+ * header switched and every value BLANKED; the source text stays visible as
+ * an inline `# english: …` comment so the translator sees it right there
+ * without it leaking into the game as a fake translation.
+ */
+export function buildTranslation(sourceContent: string, targetLang: string, sourceLang = "english"): string {
+  const hadBom = sourceContent.startsWith(BOM);
+  let body = hadBom ? sourceContent.slice(1) : sourceContent;
+  if (HEADER.test(body)) {
+    body = body.replace(HEADER, `$1l_${targetLang}:`);
+  } else {
+    body = `l_${targetLang}:\n` + body;
+  }
+  body = body
+    .split(/\r?\n/)
+    .map((l) => blankEntry(l, sourceLang))
+    .join("\n");
+  return BOM + body;
+}
+
+export interface MergeResult {
+  content: string;
+  added: number;
+}
+
+/**
+ * Add entries that exist in the source but not yet in the target, appended at
+ * the end under a marker comment. Existing target lines are never touched.
+ */
+export function mergeTranslation(
+  targetContent: string,
+  sourceContent: string,
+  sourceLang: string
+): MergeResult {
+  const hadBom = targetContent.startsWith(BOM);
+  const target = hadBom ? targetContent.slice(1) : targetContent;
+  const eol = target.includes("\r\n") ? "\r\n" : "\n";
+
+  const existing = new Set<string>();
+  for (const line of target.split(/\r?\n/)) {
+    const m = ENTRY.exec(line);
+    if (m) existing.add(m[1]);
+  }
+
+  const missing: string[] = [];
+  for (const line of sourceContent.replace(/^/, "").split(/\r?\n/)) {
+    const m = ENTRY.exec(line);
+    if (m && !existing.has(m[1])) {
+      missing.push(blankEntry(line.replace(/\r$/, ""), sourceLang));
+      existing.add(m[1]);
+    }
+  }
+  if (missing.length === 0) return { content: targetContent, added: 0 };
+
+  const lines = target.split(/\r?\n/);
+  while (lines.length > 0 && lines[lines.length - 1].trim() === "") lines.pop();
+  lines.push(
+    "",
+    ` # --- entries missing from this language; ${sourceLang} text in the comments ---`,
+    ...missing,
+    ""
+  );
+  return { content: (hadBom ? BOM : "") + lines.join(eol), added: missing.length };
+}

package/src/types.ts

@@ -0,0 +1,90 @@
+/** Shared data model. Keep this module free of `vscode` imports: it is used by unit-tested code. */
+
+export interface IndexStats {
+  total: number;
+  files: number;
+  byKind: Record<string, number>;
+  bySource: Record<string, number>;
+}
+
+export type TokenKind = "trigger" | "effect" | "event_target" | "modifier";
+
+/** One engine token parsed from a script_docs log file. */
+export interface TokenData {
+  name: string;
+  kind: TokenKind;
+  /** Description text from the log; may be empty. */
+  doc: string;
+  /** Supported scopes as raw strings, display-only in v1. */
+  scopes: string[];
+  /** Extra metadata lines (targets, traits, categories...), display-only. */
+  traits?: string;
+  /** A syntax/usage example block (`add_hook = { type = X ... }`), preserved
+   *  verbatim from a `usage:` section, an inline `name = …` line, or the wiki. */
+  usage?: string;
+}
+
+/**
+ * Definition kinds are open strings driven by the schema table
+ * (packages/server/src/schema): "scripted_effect", "trait", "decision", ...
+ */
+export type DefKind = string;
+
+/** Where a definition comes from; mod shadows parent shadows vanilla. */
+export type DefSource = "vanilla" | "parent" | "mod";
+
+/** One user-defined or vanilla definition found by the indexer. */
+export interface Definition {
+  name: string;
+  kind: DefKind;
+  /** Absolute path. */
+  file: string;
+  /** 0-based line number (VS Code convention). */
+  line: number;
+  source: DefSource;
+  /** For loc_key: the localized text (truncated for memory; the edit flow re-reads the yml). */
+  value?: string;
+  /** Enclosing definition, when meaningful (e.g. the event a save_scope_as sits in). */
+  container?: string;
+  /** For scripted effects/triggers: $PARAM$ names in declaration order (signature help). */
+  params?: string[];
+  /** PdxDoc prose from a leading `#` comment block (§E); capped for memory. */
+  doc?: string;
+  /** PdxDoc structured tags (@scope, @param, @saves, @returns, @example, @deprecated, …). */
+  tags?: DocTag[];
+  /**
+   * Database entry mode stripped from the declaration key (`REPLACE:name`),
+   * for games whose profile declares entryModes. The definition is indexed
+   * under the bare name; the mode is kept for override analysis.
+   */
+  entryMode?: string;
+}
+
+/** One structured PdxDoc tag line (§E1). Unknown tags render as prose, not stored here. */
+export interface DocTag {
+  /** Tag name without the leading `@` (lowercased). */
+  tag: string;
+  /** Text after the tag word. */
+  text: string;
+}
+
+/** One usage site of a name, extracted schema-driven from mod files. */
+export interface Reference {
+  name: string;
+  /** Candidate definition kinds this usage may refer to. */
+  kinds: DefKind[];
+  /** Absolute path. */
+  file: string;
+  /** 0-based line. */
+  line: number;
+  /** Character range of the name on the line (prefix like `scope:` excluded). */
+  startChar: number;
+  endChar: number;
+  /** Key-position call site (`my_effect = yes`): shown by find-references and
+   * rename, excluded from the usage-count completion ranking signal (§C2). */
+  call?: boolean;
+  /** Call sites only: enclosing key chain below the top-level definition
+   * (dotted, outermost first) — input for call-site scope aggregation, which
+   * types un-@scope'd scripted effects/triggers from where they are called. */
+  chain?: string;
+}