@px-lsp/protocol 0.1.0

package/dist/errorLogParser.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * Best-effort parsing of the game's logs/error.log lines. Pure (no vscode),
+ * so it stays unit-testable; the tailing/diagnostics wiring lives in the
+ * client.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorLogParser = void 0;
+exports.parseErrorLogLine = parseErrorLogLine;
+/** `... in file: events/x.txt line: 12` / `file: "gui/y.gui" near line: 3` */
+const FILE_LINE = /file:\s*"?([^"\r\n]+?\.(?:txt|yml|gui|info|mod|gfx|asset))"?(?:\s+(?:near\s+)?line:?\s*(\d+))?/i;
+/**
+ * Newer Jomini titles write the location with no `file:` keyword:
+ * `gui/x.gui:110 - Widget cannot have a position in a layout`. The ` - `
+ * separator is required; without it any "foo.txt:3" quoted inside a message
+ * would be read as a location.
+ */
+const FILE_LINE_BARE = /([\w./\\-]+\.(?:txt|yml|gui)):(\d+)\s+-\s+/;
+/**
+ * Timestamp, with an OPTIONAL severity tag: older logs write
+ * `[18:33:24][E][x.cpp:1]:`, newer ones `[01:30:39][x.cpp:186]:` and leave the
+ * severity to the message text. Untagged entries count as errors.
+ */
+const TIMESTAMP = /^\[\d{2}:\d{2}:\d{2}\](?:\[([EW])\])?/;
+/** The `[time][sev][source.cpp:N]: ` preamble, stripped from messages. */
+const PREAMBLE = /^\[\d{2}:\d{2}:\d{2}\](?:\[[EW]\])?\[[^\]]*\]:\s*/;
+/** The file/line a log line names, in either shape; null when it names none. */
+function matchFile(line) {
+    const m = FILE_LINE.exec(line);
+    if (m) {
+        return {
+            relFile: m[1].replace(/\\/g, "/"),
+            line: m[2] !== undefined ? Math.max(0, parseInt(m[2], 10) - 1) : null,
+            matched: "",
+        };
+    }
+    const bare = FILE_LINE_BARE.exec(line);
+    if (!bare)
+        return null;
+    return {
+        relFile: bare[1].replace(/\\/g, "/"),
+        line: Math.max(0, parseInt(bare[2], 10) - 1),
+        matched: bare[0],
+    };
+}
+/** Parse one error.log line; null when it names no file. */
+function parseErrorLogLine(raw) {
+    const line = raw.replace(/\r$/, "");
+    if (line.trim() === "")
+        return null;
+    const m = matchFile(line);
+    if (!m)
+        return null;
+    const sev = TIMESTAMP.exec(line);
+    let message = line.replace(PREAMBLE, "").trim();
+    // The bare shape puts the location in front of the text; the diagnostic
+    // already carries file and line, so it is redundant there.
+    if (m.matched !== "" && message.startsWith(m.matched))
+        message = message.slice(m.matched.length).trim() || message;
+    return {
+        message,
+        relFile: m.relFile,
+        line: m.line,
+        severity: sev?.[1] === "W" ? "warning" : "error",
+    };
+}
+/**
+ * Stateful line parser: same as `parseErrorLogLine`, but additionally stitches
+ * multi-line `Script system error!` blocks together, where the actual error
+ * text and the file location sit on separate indented continuation lines:
+ *
+ *     [18:14:55][E][jomini_script_system.cpp:303]: Script system error!
+ *       Error: is_cultivator trigger [ Scoped object ... is not valid ]
+ *       Script location: file: common/script_values/x.txt line: 25 (name)
+ *
+ * Line-by-line, the location line would become the diagnostic message and the
+ * error text would be dropped. Feed EVERY line through `push` in order (state
+ * carries across reads); call `reset` when the log is cleared or replaced.
+ */
+class ErrorLogParser {
+    pendingSeverity = null;
+    pendingError = null;
+    push(raw) {
+        const line = raw.replace(/\r$/, "");
+        if (line.trim() === "") {
+            this.reset();
+            return null;
+        }
+        const sev = TIMESTAMP.exec(line);
+        if (sev) {
+            // Timestamped entry: single-line entries parse as before; a header that
+            // names no file (e.g. "Script system error!") opens a block.
+            this.reset();
+            const single = parseErrorLogLine(line);
+            if (single)
+                return single;
+            this.pendingSeverity = sev[1] === "W" ? "warning" : "error"; // untagged = error
+            return null;
+        }
+        // Untimestamped continuation line of an open block.
+        if (this.pendingSeverity === null)
+            return null;
+        const err = /^\s*Error:\s*(.+)$/.exec(line);
+        if (err) {
+            this.pendingError = err[1].trim();
+            return null;
+        }
+        const m = matchFile(line);
+        if (!m)
+            return null;
+        const parsed = {
+            message: this.pendingError ?? line.trim(),
+            relFile: m.relFile,
+            line: m.line,
+            severity: this.pendingSeverity,
+        };
+        this.reset();
+        return parsed;
+    }
+    reset() {
+        this.pendingSeverity = null;
+        this.pendingError = null;
+    }
+}
+exports.ErrorLogParser = ErrorLogParser;

package/dist/fsWalk.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Directory entries between two `null` ticks from `iterFiles`. Measured walk
+ * throughput on a real tree is 4.2k entries/s cold and 29k/s warm, so 500
+ * entries is tens of milliseconds of blocking at worst.
+ */
+export declare const WALK_TICK = 500;
+/**
+ * Every file under `dir` (recursive) with the given extension (lowercase
+ * match), yielded as it is found, plus a `null` every WALK_TICK entries
+ * VISITED.
+ *
+ * The nulls are what lets an async caller pace the listing: a subtree with no
+ * match in it at all (a mod's `gfx/` under a `.txt` scan) still costs one
+ * readdirSync per directory, so a caller handed only paths would have nothing
+ * to pace itself against and would block for the whole traversal.
+ */
+export declare function iterFiles(dir: string, ext: string): Generator<string | null>;
+/** All files under `dir` (recursive) with the given extension (lowercase match). */
+export declare function listFiles(dir: string, ext: string): string[];
+export declare function walkDir(dir: string, ext: string, out: string[]): void;

package/dist/fsWalk.js

@@ -0,0 +1,159 @@
+"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.WALK_TICK = void 0;
+exports.iterFiles = iterFiles;
+exports.listFiles = listFiles;
+exports.walkDir = walkDir;
+/**
+ * Recursive file listing shared by the server indexer and client-side
+ * reference scans. No `vscode` imports.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Directory entries between two `null` ticks from `iterFiles`. Measured walk
+ * throughput on a real tree is 4.2k entries/s cold and 29k/s warm, so 500
+ * entries is tens of milliseconds of blocking at worst.
+ */
+exports.WALK_TICK = 500;
+/**
+ * Every file under `dir` (recursive) with the given extension (lowercase
+ * match), yielded as it is found, plus a `null` every WALK_TICK entries
+ * VISITED.
+ *
+ * The nulls are what lets an async caller pace the listing: a subtree with no
+ * match in it at all (a mod's `gfx/` under a `.txt` scan) still costs one
+ * readdirSync per directory, so a caller handed only paths would have nothing
+ * to pace itself against and would block for the whole traversal.
+ */
+function* iterFiles(dir, ext) {
+    // One visited-target set per walk: shared across sibling links so two links
+    // to the same tree cannot index it twice. The walk runs once per schema folder
+    // (tens of times per root), never per directory, so the Set is free.
+    yield* walk(dir, ext, new Set(), { count: 0 });
+}
+/** All files under `dir` (recursive) with the given extension (lowercase match). */
+function listFiles(dir, ext) {
+    const out = [];
+    walkDir(dir, ext, out);
+    return out;
+}
+function walkDir(dir, ext, out) {
+    for (const file of iterFiles(dir, ext)) {
+        if (file !== null)
+            out.push(file);
+    }
+}
+function* walk(dir, ext, visited, tick) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        // Dot-directories (.git, .claude worktrees, …) are never game content and
+        // can hold stale copies of the whole mod — indexing them pollutes results.
+        if (entry.name.startsWith("."))
+            continue;
+        if (++tick.count % exports.WALK_TICK === 0)
+            yield null;
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            yield* walk(full, ext, visited, tick);
+        else if (entry.isFile()) {
+            if (entry.name.toLowerCase().endsWith(ext))
+                yield full;
+        }
+        else if (entry.isSymbolicLink())
+            yield* followLink(full, ext, visited, tick);
+    }
+}
+/** Case-folded on Windows, trailing separator stripped. */
+function norm(p) {
+    const n = process.platform === "win32" ? p.toLowerCase() : p;
+    return n.replace(/[\\/]+$/, "");
+}
+/** True when `inner` is `outer` itself or sits below it. */
+function isSameOrBelow(outer, inner) {
+    const a = norm(outer);
+    const b = norm(inner);
+    return b === a || b.startsWith(a + path.sep);
+}
+/**
+ * A Dirent reports a symlink as neither file nor directory, so links need an
+ * explicit stat. Following them is not optional: symlinking a mod into the
+ * Paradox `mod/` folder is the standard Linux workflow, and Windows junctions
+ * do the same for a redirected Documents folder. Entries keep the LINK path so
+ * definitions stay attributed to the root the user configured.
+ *
+ * Two guards keep a malformed tree from looping or double-indexing: a link
+ * resolving to the directory it sits in (or one of its ancestors) is skipped
+ * outright, and every followed target is remembered for the rest of the walk.
+ */
+function* followLink(full, ext, visited, tick) {
+    let target;
+    let real;
+    try {
+        target = fs.statSync(full); // follows the link; throws when dangling
+        real = fs.realpathSync(full);
+    }
+    catch {
+        return; // dangling or unreadable link indexes nothing
+    }
+    if (target.isFile()) {
+        if (path.basename(full).toLowerCase().endsWith(ext))
+            yield full;
+        return;
+    }
+    if (!target.isDirectory())
+        return;
+    let host;
+    try {
+        host = fs.realpathSync(path.dirname(full));
+    }
+    catch {
+        return;
+    }
+    if (isSameOrBelow(real, host))
+        return; // points back into the tree being walked
+    const key = norm(real);
+    if (visited.has(key))
+        return;
+    visited.add(key);
+    yield* walk(full, ext, visited, tick);
+}

package/dist/locProperties.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Script properties whose right-hand side is a localization key.
+ *
+ * BROAD: properties that often hold a loc key; a resolved inlay hint is shown
+ * when the value exists in the loc index, silence otherwise (these keys also
+ * hold non-loc values, e.g. `name` on a title history entry).
+ *
+ * STRICT: properties that virtually always hold a loc key; an unresolved value
+ * here renders a `missing loc` hint.
+ */
+export declare const STRICT_LOC_PROPERTIES: Set<string>;
+export declare const BROAD_LOC_PROPERTIES: Set<string>;
+export declare function isLocProperty(prop: string): "strict" | "broad" | null;

package/dist/locProperties.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Script properties whose right-hand side is a localization key.
+ *
+ * BROAD: properties that often hold a loc key; a resolved inlay hint is shown
+ * when the value exists in the loc index, silence otherwise (these keys also
+ * hold non-loc values, e.g. `name` on a title history entry).
+ *
+ * STRICT: properties that virtually always hold a loc key; an unresolved value
+ * here renders a `missing loc` hint.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BROAD_LOC_PROPERTIES = exports.STRICT_LOC_PROPERTIES = void 0;
+exports.isLocProperty = isLocProperty;
+exports.STRICT_LOC_PROPERTIES = new Set([
+    "title",
+    "desc",
+    "flavor",
+    "custom_tooltip",
+    "confirm_text",
+    "confirm_title",
+    "prompt",
+    "failure_desc",
+    "success_desc",
+]);
+exports.BROAD_LOC_PROPERTIES = new Set([
+    ...exports.STRICT_LOC_PROPERTIES,
+    "name",
+    "text",
+    "tooltip",
+    "first_valid",
+    "reason",
+    "format",
+    "header",
+    "opinion_text",
+    "what",
+    "who",
+]);
+function isLocProperty(prop) {
+    const p = prop.toLowerCase();
+    if (exports.STRICT_LOC_PROPERTIES.has(p))
+        return "strict";
+    if (exports.BROAD_LOC_PROPERTIES.has(p))
+        return "broad";
+    return null;
+}

package/dist/locRefs.d.ts

@@ -0,0 +1,11 @@
+export interface LocKeyRef {
+    prop: string;
+    key: string;
+    /** Character range of the key on the line. */
+    start: number;
+    end: number;
+    strictness: "strict" | "broad";
+}
+export declare function findLocKeyRefs(lineText: string): LocKeyRef[];
+/** The loc key defined on the given line of a loc yml, if any. */
+export declare function locKeyOnLine(lineText: string): string | null;

package/dist/locRefs.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findLocKeyRefs = findLocKeyRefs;
+exports.locKeyOnLine = locKeyOnLine;
+/**
+ * Line-level detection of localization-key references in script and of key
+ * definitions in loc yml. Used by the server (inlay hints, code actions) and
+ * the client (loc reference tracker), so it lives in shared/.
+ *
+ * No `vscode` imports here: this module is unit-tested in plain Node.
+ */
+const locProperties_1 = require("./locProperties");
+const PROP_VALUE = /([A-Za-z_][A-Za-z0-9_.-]*)\s*=\s*("?)([A-Za-z_][A-Za-z0-9_.-]*)\2/g;
+function findLocKeyRefs(lineText) {
+    const refs = [];
+    PROP_VALUE.lastIndex = 0;
+    let m;
+    while ((m = PROP_VALUE.exec(lineText)) !== null) {
+        const strictness = (0, locProperties_1.isLocProperty)(m[1]);
+        if (!strictness)
+            continue;
+        const end = m.index + m[0].length - (m[2] === '"' ? 1 : 0);
+        refs.push({ prop: m[1], key: m[3], start: end - m[3].length, end, strictness });
+    }
+    return refs;
+}
+/** The loc key defined on the given line of a loc yml, if any. */
+function locKeyOnLine(lineText) {
+    const m = /^\s*([A-Za-z0-9_.\-']+):\d*\s*"/.exec(lineText.replace(/^/, ""));
+    return m ? m[1] : null;
+}

package/dist/modName.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The mod's display name: the launcher descriptor's `name=`, else
+ * `.metadata/metadata.json`'s `name`, else the folder's own name. Never null,
+ * so callers need no fallback of their own.
+ */
+export declare function readModName(dir: string): string;

package/dist/modName.js

@@ -0,0 +1,53 @@
+"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.readModName = readModName;
+/**
+ * One display name for a mod folder, whichever descriptor convention it uses.
+ * Every surface that names a mod (setup report, sidebar, pickers, the Project
+ * view, hover origins) goes through this, so a mod is called what its author
+ * called it instead of "3385002128".
+ */
+const path = __importStar(require("path"));
+const descriptorMod_1 = require("./descriptorMod");
+const descriptorMetadata_1 = require("./descriptorMetadata");
+/**
+ * The mod's display name: the launcher descriptor's `name=`, else
+ * `.metadata/metadata.json`'s `name`, else the folder's own name. Never null,
+ * so callers need no fallback of their own.
+ */
+function readModName(dir) {
+    return (0, descriptorMod_1.readDescriptorName)(dir) ?? (0, descriptorMetadata_1.readMetadataName)(dir) ?? path.basename(dir);
+}