@px-lsp/protocol 0.1.0

package/dist/translationCore.js

@@ -0,0 +1,162 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOC_LANGUAGES = void 0;
+exports.detectLocFileLanguage = detectLocFileLanguage;
+exports.retargetLocPath = retargetLocPath;
+exports.buildTranslation = buildTranslation;
+exports.mergeTranslation = mergeTranslation;
+/**
+ * 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.
+ */
+const path = __importStar(require("path"));
+exports.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. */
+function detectLocFileLanguage(filePath) {
+    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 exports.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.
+ */
+function retargetLocPath(srcFile, sourceLang, targetLang) {
+    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, sourceLang) {
+    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.
+ */
+function buildTranslation(sourceContent, targetLang, sourceLang = "english") {
+    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;
+}
+/**
+ * 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.
+ */
+function mergeTranslation(targetContent, sourceContent, sourceLang) {
+    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();
+    for (const line of target.split(/\r?\n/)) {
+        const m = ENTRY.exec(line);
+        if (m)
+            existing.add(m[1]);
+    }
+    const missing = [];
+    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/dist/types.d.ts

@@ -0,0 +1,82 @@
+/** 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;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+/** Shared data model. Keep this module free of `vscode` imports: it is used by unit-tested code. */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@px-lsp/protocol",
+  "version": "0.1.0",
+  "license": "GPL-3.0-or-later",
+  "description": "Wire contract (custom LSP requests/notifications, settings types) and shared helpers for the px-lsp language server and its clients.",
+  "keywords": [
+    "lsp",
+    "paradox",
+    "modding"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JDeffner/paradox-modding-toolkit.git",
+    "directory": "packages/protocol"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/protocol.d.ts",
+      "default": "./dist/protocol.js"
+    },
+    "./package.json": "./package.json",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  }
+}

package/src/arrays.ts

@@ -0,0 +1,16 @@
+/** Array helpers shared by the server and the client. */
+
+/**
+ * Append every element of `source` to `target`.
+ *
+ * `target.push(...source)` passes one argument per element and throws
+ * `RangeError: Maximum call stack size exceeded` past ~125k elements (measured,
+ * node 24, default stack). On the index paths that is a size-triggered crash:
+ * one engine/vanilla root already carries ~460k definitions and one generated
+ * mod file can carry six figures on its own. The loop has no ceiling and
+ * measures the same as the spread (2M elements appended in 10k pieces: 23 ms
+ * loop vs 22 ms spread; as one 500k piece: 5.5 ms loop vs 9.6 ms spread).
+ */
+export function pushAll<T>(target: T[], source: readonly T[]): void {
+  for (let i = 0; i < source.length; i++) target.push(source[i]);
+}

package/src/constants.ts

@@ -0,0 +1,12 @@
+/**
+ * Constants needed on both sides of the LSP boundary.
+ */
+import type { TokenKind } from "./types";
+
+/** The script_docs log files and the token kind each one contributes. */
+export const LOG_FILES: Array<{ file: string; kind: TokenKind }> = [
+  { file: "triggers.log", kind: "trigger" },
+  { file: "effects.log", kind: "effect" },
+  { file: "event_targets.log", kind: "event_target" },
+  { file: "modifiers.log", kind: "modifier" },
+];

package/src/descriptorMetadata.ts

@@ -0,0 +1,101 @@
+/**
+ * Reader and writer for the newer Paradox mod descriptor convention:
+ * `<mod>/.metadata/metadata.json` (newer titles) instead of the launcher
+ * `.mod` file. Fail-soft on read: any read/parse problem yields null.
+ *
+ * The field set is copied from three real workshop mods (2026-08-12: name, id,
+ * version, supported_game_version, tags, relationships, game_custom_data;
+ * `game_id` appears in one of the three and is left out here because the other
+ * two load without it). The relationship shape is the one the Community Mod
+ * Framework documents for the mods that depend on it.
+ */
+import * as fs from "fs";
+import * as path from "path";
+
+/** Mod-root-relative path of the descriptor, forward slashes. */
+export const METADATA_REL_PATH = ".metadata/metadata.json";
+
+/** One entry of `relationships`: a link to another mod. */
+export interface MetadataRelationship {
+  /** "dependency", "incompatible_with", "load_before", "load_after". */
+  rel_type: string;
+  /** The other mod's `id` field (NOT its Workshop number). */
+  id: string;
+  /** Shown when the other mod is not on disk. */
+  display_name?: string;
+  /** Only "mod" is supported by the launcher today. */
+  resource_type: string;
+  /** Version of the other mod, `*` for any. */
+  version?: string;
+}
+
+/** The fields of a mod's metadata.json this toolkit reads or writes. */
+export interface ModMetadata {
+  name?: string;
+  id?: string;
+  version?: string;
+  supported_game_version?: string;
+  short_description?: string;
+  tags?: string[];
+  relationships?: MetadataRelationship[];
+  game_custom_data?: { multiplayer_synchronized?: boolean; replace_paths?: string[] };
+}
+
+/** The parsed `<dir>/.metadata/metadata.json`, or null when absent/unreadable. */
+export function readMetadata(dir: string): ModMetadata | null {
+  try {
+    const file = path.join(dir, ".metadata", "metadata.json");
+    if (!fs.existsSync(file)) return null;
+    return JSON.parse(fs.readFileSync(file, "utf8")) as ModMetadata;
+  } catch {
+    return null;
+  }
+}
+
+/** The mod's display name from `<dir>/.metadata/metadata.json`, or null. */
+export function readMetadataName(dir: string): string | null {
+  const name = readMetadata(dir)?.name;
+  return typeof name === "string" && name.trim() !== "" ? name : null;
+}
+
+/** True when `dir` carries a metadata-style descriptor. */
+export function hasMetadataDescriptor(dir: string): boolean {
+  try {
+    return fs.existsSync(path.join(dir, ".metadata", "metadata.json"));
+  } catch {
+    return false;
+  }
+}
+
+export interface MetadataScaffold {
+  name: string;
+  /** Stable identifier other mods point their relationships at. */
+  id: string;
+  /** The mod's own version, not the game's. */
+  version?: string;
+  /** Game version the mod is for, `*` when unknown. */
+  supportedGameVersion: string;
+  shortDescription?: string;
+  tags?: string[];
+  relationships?: MetadataRelationship[];
+  /** Vanilla folders the mod unloads wholesale (total conversions). */
+  replacePaths?: string[];
+}
+
+/** A launcher-correct starter metadata.json, in the corpus's field order. */
+export function scaffoldMetadata(opts: MetadataScaffold): string {
+  const body: ModMetadata = {
+    name: opts.name,
+    id: opts.id,
+    version: opts.version ?? "0.1.0",
+    supported_game_version: opts.supportedGameVersion,
+    ...(opts.shortDescription ? { short_description: opts.shortDescription } : {}),
+    tags: opts.tags ?? [],
+    relationships: opts.relationships ?? [],
+    game_custom_data: {
+      multiplayer_synchronized: true,
+      ...(opts.replacePaths && opts.replacePaths.length > 0 ? { replace_paths: opts.replacePaths } : {}),
+    },
+  };
+  return JSON.stringify(body, null, 2) + "\n";
+}