@px-lsp/protocol 0.1.0

package/dist/protocol.js

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scopeAtRequest = exports.dependenciesRequest = exports.eventValueOptionsRequest = exports.EVENT_VOCABULARY_MAX_VALUES = exports.EVENT_VOCABULARY_MAX_TOKENS = exports.eventVocabularyRequest = exports.eventBannerRequest = exports.eventGraphRequest = exports.guiWidgetEditRequest = exports.guiSourceEditRequest = exports.guiSaveValuesRequest = exports.GUI_PREVIEW_MAX = exports.guiPreviewRequest = exports.guiVocabularyRequest = exports.guiDependenciesRequest = exports.guiWidgetInfoRequest = exports.guiLayoutRequest = exports.guiTreeRequest = exports.eventDetailRequest = exports.overridesRequest = exports.locCoverageRequest = exports.modOverviewRequest = exports.progressNotification = exports.indexChangedNotification = exports.statusNotification = exports.lookupLocRequest = exports.indexStatsRequest = exports.reloadDocsRequest = exports.modFileChangedNotification = exports.configChangedNotification = exports.allClientCommandIds = exports.clientCommands = void 0;
+// ---- client command ids ----------------------------------------------------
+/**
+ * Client commands the server references in code actions and hover links (part
+ * of the wire contract: a client that implements one must register exactly
+ * this id and list it in {@link ParadoxClientCapabilities.commands}). They
+ * carry the "px." prefix: these are public extension command ids with shipped
+ * default keybindings. The prefix was renamed in the Paradox Toolkit rebrand
+ * and no fallback to the old ids is registered.
+ */
+exports.clientCommands = {
+    editLocalization: "px.editLocalization",
+    openLocalizationSideBySide: "px.openLocalizationSideBySide",
+    showReferences: "px.showReferences",
+};
+/** Every id in {@link clientCommands}: what a fully capable client registers. */
+exports.allClientCommandIds = Object.values(exports.clientCommands);
+// ---- client -> server ------------------------------------------------------
+/** Notification: settings changed; payload {@link ParadoxSettings}. */
+exports.configChangedNotification = "paradox/configChanged";
+/** Notification: a mod file changed on disk; payload {@link ModFileChangeParams}. */
+exports.modFileChangedNotification = "paradox/modFileChanged";
+/** Request: re-parse script_docs logs; payload {@link ReloadDocsParams} -> {@link ReloadDocsResult}. */
+exports.reloadDocsRequest = "paradox/reloadDocs";
+/** Request: index statistics; no payload -> {@link IndexStats}. */
+exports.indexStatsRequest = "paradox/indexStats";
+/** Request: look up localization entries for a key; {@link LookupLocParams} -> {@link LocEntryInfo}[].
+ * Mod entries shadow vanilla ones (the full list is returned, mod first). */
+exports.lookupLocRequest = "paradox/lookupLoc";
+// ---- server -> client ------------------------------------------------------
+/** Notification: data health for the status bar; payload {@link StatusPayload}. */
+exports.statusNotification = "paradox/status";
+/** Notification: the definition index changed (debounced server-side); no payload.
+ * Overview views re-query on this signal. */
+exports.indexChangedNotification = "paradox/indexChanged";
+/** Notification: a long-running server phase started or finished; payload
+ * {@link ProgressPayload}. The status bar lists what is still loading, so a
+ * cold workspace says which step it is on instead of looking idle. No
+ * percentages: the phases are coarse and the client only shows their state. */
+exports.progressNotification = "paradox/progress";
+/** Request: mod content inventory; {@link ModScopedParams} -> {@link ModOverview}. */
+exports.modOverviewRequest = "paradox/modOverview";
+/** Request: localization coverage; {@link ModScopedParams} -> {@link LocCoverage}[]. */
+exports.locCoverageRequest = "paradox/locCoverage";
+/** Request: override/conflict map; {@link ModScopedParams} -> {@link OverrideInfo}[]. */
+exports.overridesRequest = "paradox/overrides";
+/** Request: full event detail for the graph inspector; {@link EventDetailParams} -> {@link EventDetail} | null. */
+exports.eventDetailRequest = "paradox/eventDetail";
+/** Request: GUI widget tree for a .gui document; {@link GuiTreeParams} -> {@link GuiTree}. */
+exports.guiTreeRequest = "paradox/guiTree";
+/**
+ * Request: rendered GUI layout for a .gui document;
+ * {@link GuiLayoutParams} -> {@link GuiLayoutResult}. Rectangles come from
+ * the measured layout engine (docs/gui-designer/calibration/spec.md), with
+ * templates/types resolved against the vanilla + mod gui tree.
+ */
+exports.guiLayoutRequest = "paradox/guiLayout";
+/**
+ * Request: the properties of ONE widget, as the layout engine resolved them;
+ * {@link GuiWidgetInfoParams} -> {@link GuiWidgetInfo}, null when the line
+ * carries no widget of its own (a node spliced in from a template or a type has
+ * no source here, the same answer `guiSourceEdit` refuses with).
+ *
+ * This is the designer inspector's READ side. It is a separate request rather
+ * than a field on {@link GuiLayoutNode} because it is per-SELECTION data: a
+ * vanilla window lays out 500+ widgets and carrying every widget's expanded
+ * property list on every layout push would multiply the payload for rows one
+ * widget at a time is ever shown.
+ */
+exports.guiWidgetInfoRequest = "paradox/guiWidgetInfo";
+/**
+ * Request: what a `.gui` document reaches on the SCRIPT side;
+ * {@link GuiDependenciesParams} -> {@link GuiDependenciesResult}. The forward
+ * half of the dependency surface; the reverse (script definition -> the .gui
+ * paths using it) is `paradox/dependencies` with `guiUses: true`, so both
+ * directions come out of the same scripted_gui link.
+ */
+exports.guiDependenciesRequest = "paradox/guiDependencies";
+/**
+ * Request: the widget names a designer palette may offer for THIS document;
+ * {@link GuiVocabularyParams} -> {@link GuiVocabularyResult}.
+ *
+ * Every name is harvested, never listed by hand: the bundled per-game widget
+ * schema (`data/<game>/guiSchema.json`, built from the vanilla `gui/` tree)
+ * plus the requested document's own `template` and `type` declarations. A
+ * palette entry is therefore always a widget the game knows.
+ */
+exports.guiVocabularyRequest = "paradox/guiVocabulary";
+/**
+ * Render-ready previews of palette entries: one instance of each entry laid
+ * out in a synthetic document that keeps the requested document's own
+ * declarations (so a local template previews with its real base). The
+ * result is an ordinary node tree the client draws with the same painter as
+ * the canvas. Entries a synthetic document cannot stand up (nothing to show,
+ * zero size, a type the store lacks) come back with `node: null` and a
+ * `reason`. Capped per request (GUI_PREVIEW_MAX); ask for the visible page.
+ */
+exports.guiPreviewRequest = "paradox/guiPreview";
+exports.GUI_PREVIEW_MAX = 48;
+/**
+ * Preview values read out of a save game, so a designer draws
+ * `[GetPlayer.GetName]` as "Great Britain" instead of a placeholder chip.
+ *
+ * `values` is keyed by datafunction chain WITHOUT brackets, exactly the shape
+ * {@link GuiLayoutParams.previewValues} takes, so a client hands the answer
+ * straight back to the next layout request. A chain the save has no field for
+ * is absent: a preview shows what is knowable and never invents a value.
+ *
+ * The server streams the file and parses only the few blocks it needs (a big
+ * campaign runs ~115 MB), and caches the answer per file and mtime.
+ * Ironman and binary saves are refused with `error` set; melting them is a
+ * different tool.
+ */
+exports.guiSaveValuesRequest = "paradox/guiSaveValues";
+/**
+ * Request: source edits for a `.gui` designer gesture;
+ * {@link GuiSourceEditParams} -> {@link GuiSourceEditResult}, null when the
+ * request itself makes no sense (an unknown op). The server never writes: it
+ * returns offsets into the text it was handed and the host applies them, which
+ * keeps undo, dirty state and the live preview in the editor (EMBEDDING.md,
+ * host-owns-text).
+ *
+ * Every edit is surgical, over the exact span the source model recorded, so
+ * untouched bytes stay byte-identical: comments, CRLF, tabs-vs-spaces and
+ * single-line bodies all survive a write.
+ */
+exports.guiSourceEditRequest = "paradox/guiSourceEdit";
+/**
+ * Request: text edit for a preview interaction (drag / property change);
+ * {@link GuiWidgetEditParams} -> {@link GuiWidgetEditResult} (null when the
+ * widget or property cannot be edited). The client applies the offsets via
+ * WorkspaceEdit so undo and the live preview loop stay in the editor.
+ *
+ * @deprecated Use {@link guiSourceEditRequest} with a `setProperties` op. This
+ * is a thin alias over the same core, kept for hosts already wired to it: it
+ * can only write the `position`/`size` pair and returns one edit or null, so a
+ * refusal reaches the caller as a bare null with no reason attached.
+ */
+exports.guiWidgetEditRequest = "paradox/guiWidgetEdit";
+/** Request: event graph; {@link EventGraphParams} -> {@link EventGraph}. */
+exports.eventGraphRequest = "paradox/eventGraph";
+/**
+ * Request: the value sets an event editor may offer; {@link EventVocabularyParams}
+ * to {@link EventVocabularyResult}.
+ *
+ * Everything in the answer is DERIVED: the key lists come from the active
+ * profile's structure table, the field value sets from the schema's reference
+ * fields resolved through the definition index, and the effect/trigger lists
+ * from the user's script_docs (or the bundled wiki fallback). Nothing here is a
+ * hand-written name list, so a game patch that adds a theme or an effect shows
+ * up without a release.
+ */
+/**
+ * Request: the illustration an event theme puts behind its window;
+ * {@link EventBannerParams} to {@link EventBannerResult}.
+ *
+ * Resolved through the game's own two hops (event_themes -> event_backgrounds),
+ * taking the last `background` block that carries no `trigger`, which is the
+ * file's own unconditional fallback. `texture` is the engine's mod-relative
+ * path, exactly as a `.gui` file would spell it, so a client resolves it with
+ * the same mod-then-game lookup it uses for any other texture. A theme that
+ * resolves to nothing answers `reason` instead: the caller is expected to say
+ * so rather than draw a picture that is not the event's.
+ */
+exports.eventBannerRequest = "paradox/eventBanner";
+exports.eventVocabularyRequest = "paradox/eventVocabulary";
+/** Caps: an editor lists a page at a time, and these ride on every open. */
+exports.EVENT_VOCABULARY_MAX_TOKENS = 600;
+exports.EVENT_VOCABULARY_MAX_VALUES = 400;
+/**
+ * Request: the value set a VALUE belongs to, resolved through the definition
+ * index; {@link EventValueOptionsParams} -> {@link EventValueOptionsResult} |
+ * null. The static vocabulary maps a KEY to its values, which only works where
+ * the schema knows the key's context (an event's or option's own fields). Deep
+ * inside an effect tree the same key name means something else (`type` in
+ * `random_secret` is a secret, not an event type), so there the editor asks
+ * about the value it already has: `secret_cultivator` is an indexed `secret`,
+ * and the answer is every secret the index knows. Null = the value resolves to
+ * nothing enumerable; the editor falls back to a free input.
+ */
+exports.eventValueOptionsRequest = "paradox/eventValueOptions";
+/**
+ * Request: dependency explorer for any indexed definition;
+ * {@link DependenciesParams} -> {@link DependenciesResult}. Cursor-driven
+ * (uri + position) or by name (optionally disambiguated by kind).
+ */
+exports.dependenciesRequest = "paradox/dependencies";
+/**
+ * Request: the inferred scope chain at a cursor position;
+ * {@link ScopeAtParams} -> {@link ScopeAtResult} | null. Answers for OPEN
+ * script documents only (the server reads the client's text, not the disk);
+ * null means "not open / not a script document", which a status bar renders as
+ * nothing rather than as an error.
+ *
+ * This is a read-out of the same inference completion, hover and inlay hints
+ * run at a position: it ranks and annotates, never diagnoses, and never
+ * asserts more than the derived link tables actually say.
+ */
+exports.scopeAtRequest = "paradox/scopeAt";

package/dist/regex.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 declare function escapeRegExp(literal: string): string;
+/**
+ * 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 declare function wholeNamePattern(name: string): string;

package/dist/regex.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeRegExp = escapeRegExp;
+exports.wholeNamePattern = wholeNamePattern;
+/** Escape every regex metacharacter in `literal` so it matches itself. */
+function escapeRegExp(literal) {
+    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.
+ */
+function wholeNamePattern(name) {
+    return `(?<![A-Za-z0-9_.\\-])${escapeRegExp(name)}(?![A-Za-z0-9_.\\-])`;
+}

package/dist/suppression.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 declare function sanitizeStringList(value: unknown): string[];
+/**
+ * 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 declare function globMatch(pattern: string, filePath: string): boolean;
+/** True when a diagnostic with `code` in `filePath` should be dropped by settings. */
+export declare function isIgnoredByConfig(cfg: DiagnosticIgnoreConfig, code: string | undefined, relPath: string): boolean;
+/**
+ * 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>;
+/**
+ * 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 declare function scanInlineSuppressions(text: string): InlineSuppressions;
+/** True when line `line` has an inline suppression covering `code`. */
+export declare function isSuppressedInline(map: InlineSuppressions, line: number, code: string | undefined): boolean;

package/dist/suppression.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeStringList = sanitizeStringList;
+exports.globMatch = globMatch;
+exports.isIgnoredByConfig = isIgnoredByConfig;
+exports.scanInlineSuppressions = scanInlineSuppressions;
+exports.isSuppressedInline = isSuppressedInline;
+/** Normalize a raw settings array: strings only, trimmed, empties dropped. */
+function sanitizeStringList(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    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.
+ */
+function globMatch(pattern, filePath) {
+    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) {
+    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. */
+function isIgnoredByConfig(cfg, code, relPath) {
+    if (code !== undefined && cfg.ignore.includes(code))
+        return true;
+    for (const pattern of cfg.ignorePatterns) {
+        if (globMatch(pattern, relPath))
+            return true;
+    }
+    return false;
+}
+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.
+ */
+function scanInlineSuppressions(text) {
+    const map = 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) {
+    const out = [];
+    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, line, codes) {
+    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`. */
+function isSuppressedInline(map, line, code) {
+    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/dist/tigerParser.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 declare function parseTigerJson(stdout: string): TigerReport[] | null;

package/dist/tigerParser.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTigerJson = parseTigerJson;
+/** Parse tiger's JSON output. Returns null if no JSON array can be found at all. */
+function parseTigerJson(stdout) {
+    let raw;
+    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 = [];
+    for (const entry of raw) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const e = entry;
+        const message = typeof e.message === "string" ? e.message : null;
+        const locationsRaw = Array.isArray(e.locations) ? e.locations : [];
+        if (message === null)
+            continue;
+        const locations = [];
+        for (const locRaw of locationsRaw) {
+            if (typeof locRaw !== "object" || locRaw === null)
+                continue;
+            const l = locRaw;
+            const p = typeof l.fullpath === "string" ? l.fullpath : typeof l.path === "string" ? l.path : null;
+            if (p === null)
+                continue;
+            const loc = { 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/dist/translationCore.d.ts

@@ -0,0 +1,26 @@
+export declare const LOC_LANGUAGES: string[];
+/** Language of a loc file, from its `_l_<lang>.yml` suffix or a path segment. */
+export declare function detectLocFileLanguage(filePath: string): string | 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 declare function retargetLocPath(srcFile: string, sourceLang: string, targetLang: string): string | null;
+/**
+ * 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 declare function buildTranslation(sourceContent: string, targetLang: string, sourceLang?: string): string;
+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 declare function mergeTranslation(targetContent: string, sourceContent: string, sourceLang: string): MergeResult;