@px-lsp/protocol 0.1.0

package/src/descriptorMod.ts

@@ -0,0 +1,354 @@
+/**
+ * Knowledge table + validator for Paradox launcher `.mod` descriptor files
+ * (`descriptor.mod` inside the mod folder, `<name>.mod` next to it).
+ *
+ * The key set and tag list come from the official launcher docs
+ * (the Mod_structure page on the official wiki) cross-checked against 86 real .mod
+ * files (launcher-generated + Workshop). No vscode imports: unit-testable.
+ */
+import * as fs from "fs";
+import * as path from "path";
+
+export interface DescriptorField {
+  key: string;
+  /** Launcher refuses/misbehaves without it. */
+  required: boolean;
+  /** May appear multiple times (replace_path). */
+  repeatable: boolean;
+  /** Only meaningful in the outer `<name>.mod` file, ignored in descriptor.mod. */
+  outerOnly: boolean;
+  /** One-line label shown next to the completion item. */
+  summary: string;
+  /** Markdown: what the value means and what to put in. */
+  doc: string;
+  /** VS Code snippet inserted on completion (placeholder = example value). */
+  snippet: string;
+}
+
+export const DESCRIPTOR_FIELDS: DescriptorField[] = [
+  {
+    key: "name",
+    required: true,
+    repeatable: false,
+    outerOnly: false,
+    summary: "Display name in the launcher and on Steam Workshop",
+    doc:
+      "The name players see in the launcher's mod list and on the Workshop page. " +
+      "Needs at least 3 characters for a Workshop upload.\n\n" +
+      '```\nname="My Mod"\n```',
+    snippet: 'name="${1:My Mod}"',
+  },
+  {
+    key: "version",
+    required: true,
+    repeatable: false,
+    outerOnly: false,
+    summary: "Your mod's own version number (NOT the game version)",
+    doc:
+      "Free-form version string shown in the launcher. Bump it when you release " +
+      "an update so players can tell versions apart. This is about your mod, " +
+      "not the game - the game version goes in `supported_version`.\n\n" +
+      '```\nversion="0.1.0"\n```',
+    snippet: 'version="${1:0.1.0}"',
+  },
+  {
+    key: "supported_version",
+    required: true,
+    repeatable: false,
+    outerOnly: false,
+    summary: "Newest game version the mod works with",
+    doc:
+      "The launcher compares this against the installed game and marks the mod " +
+      "out of date when the game is newer. A `*` wildcard keeps the mod valid " +
+      "for every hotfix of a patch.\n\n" +
+      '```\nsupported_version="1.19.*"\n```',
+    snippet: 'supported_version="${1:1.19.*}"',
+  },
+  {
+    key: "tags",
+    required: false,
+    repeatable: false,
+    outerOnly: false,
+    summary: "Launcher / Workshop category tags (one quoted tag per line)",
+    doc:
+      "Categories players can filter by in the launcher and on the Workshop. " +
+      "Pick from the launcher's list (completion inside the block offers all of " +
+      "them); a Workshop upload needs at least one.\n\n" +
+      '```\ntags={\n\t"Gameplay"\n\t"Events"\n}\n```',
+    snippet: 'tags={\n\t"${1:Gameplay}"\n}',
+  },
+  {
+    key: "path",
+    required: false,
+    repeatable: false,
+    outerOnly: true,
+    summary: "Where the mod folder is - outer <name>.mod file only",
+    doc:
+      "Tells the launcher where the mod's files live. Absolute or relative to " +
+      "the game's user directory, forward slashes only.\n\n" +
+      "**Leave this line out of `descriptor.mod`** - it is ignored there, and a " +
+      "copied absolute path breaks when the mod is shared.\n\n" +
+      '```\npath="mod/my_mod"\n```',
+    snippet: 'path="${1:mod/my_mod}"',
+  },
+  {
+    key: "remote_file_id",
+    required: false,
+    repeatable: false,
+    outerOnly: false,
+    summary: "Steam Workshop item ID (set automatically on first upload)",
+    doc:
+      "Links the local mod to its Workshop page so updates go to the same item. " +
+      "The launcher fills this in when you first upload - you only ever set it " +
+      "by hand to reconnect a mod to an existing Workshop item. Digits only.\n\n" +
+      '```\nremote_file_id="2962333032"\n```',
+    snippet: 'remote_file_id="${1:123456789}"',
+  },
+  {
+    key: "picture",
+    required: false,
+    repeatable: false,
+    outerOnly: false,
+    summary: "Launcher thumbnail image (file inside the mod folder)",
+    doc:
+      "Image shown next to the mod in the launcher. Steam Workshop ignores it " +
+      "and always uses `thumbnail.png` in the mod root instead (1:1, max 1 MB).\n\n" +
+      '```\npicture="thumbnail.png"\n```',
+    snippet: 'picture="${1:thumbnail.png}"',
+  },
+  {
+    key: "replace_path",
+    required: false,
+    repeatable: true,
+    outerOnly: false,
+    summary: "Unload an entire vanilla folder (repeat per folder)",
+    doc:
+      "The game skips every vanilla file under this folder, so only your mod's " +
+      "version of it exists. One line per folder, forward slashes, relative to " +
+      "the game root. Used by total conversions to drop vanilla history, " +
+      "titles, cultures etc. wholesale - do not use it for ordinary overrides.\n\n" +
+      '```\nreplace_path="history/characters"\nreplace_path="common/landed_titles"\n```',
+    snippet: 'replace_path="${1:history/characters}"',
+  },
+  {
+    key: "dependencies",
+    required: false,
+    repeatable: false,
+    outerOnly: false,
+    summary: "Mods that must load BEFORE this one",
+    doc:
+      "The launcher sorts every listed mod above this one in the load order. " +
+      "Use the exact `name` of the other mod, one quoted name per line. Mostly " +
+      "for submods and compatibility patches.\n\n" +
+      '```\ndependencies={\n\t"A Game of Thrones"\n}\n```',
+    snippet: 'dependencies={\n\t"${1:Name of the parent mod}"\n}',
+  },
+];
+
+export const DESCRIPTOR_FIELD_MAP: ReadonlyMap<string, DescriptorField> = new Map(
+  DESCRIPTOR_FIELDS.map((f) => [f.key, f])
+);
+
+/** The launcher's fixed tag categories (Mod_structure wiki page, launcher UI). */
+export const LAUNCHER_TAGS: string[] = [
+  "Alternative History",
+  "Balance",
+  "Bookmarks",
+  "Character Focuses",
+  "Character Interactions",
+  "Culture",
+  "Decisions",
+  "Events",
+  "Fixes",
+  "Gameplay",
+  "Graphics",
+  "Historical",
+  "Map",
+  "Portraits",
+  "Religion",
+  "Schemes",
+  "Sound",
+  "Total Conversion",
+  "Translation",
+  "Utilities",
+  "Warfare",
+];
+
+// ---- parsing -------------------------------------------------------------------
+
+export interface DescriptorEntry {
+  key: string;
+  /** 0-based line of the key. */
+  line: number;
+  /** Column range of the key on its line. */
+  startCol: number;
+  endCol: number;
+  /** Raw text right of `=` (trimmed, quotes kept), "" when the value is a block. */
+  value: string;
+}
+
+/**
+ * Line-based parse of the flat key=value format. Only top-level keys are
+ * entries; lines inside a `{ }` block (tags, dependencies) are skipped.
+ */
+export function parseDescriptor(text: string): DescriptorEntry[] {
+  const entries: DescriptorEntry[] = [];
+  let depth = 0;
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const noComment = line.replace(/#.*$/, "");
+    if (depth === 0) {
+      // Tolerate a UTF-8 BOM on the first line.
+      const m = /^(\uFEFF?\s*)([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(noComment);
+      if (m) {
+        const startCol = m[1].length;
+        entries.push({
+          key: m[2],
+          line: i,
+          startCol,
+          endCol: startCol + m[2].length,
+          value: m[3].trim().startsWith("{") ? "" : m[3].trim(),
+        });
+      }
+    }
+    for (const ch of noComment) {
+      if (ch === "{") depth++;
+      else if (ch === "}") depth = Math.max(0, depth - 1);
+    }
+  }
+  return entries;
+}
+
+// ---- validation ------------------------------------------------------------------
+
+export interface DescriptorIssue {
+  code:
+    | "descriptor-missing-field"
+    | "descriptor-unknown-key"
+    | "descriptor-duplicate-key"
+    | "descriptor-path-ignored";
+  severity: "error" | "warning";
+  line: number;
+  startCol: number;
+  endCol: number;
+  message: string;
+}
+
+/**
+ * Structural checks on a .mod file. Everything here is certain: the key set is
+ * closed (launcher docs) and required-ness is the launcher's own behavior.
+ */
+export function validateDescriptor(text: string, opts: { isDescriptorFile: boolean }): DescriptorIssue[] {
+  const issues: DescriptorIssue[] = [];
+  const entries = parseDescriptor(text);
+  const seen = new Map<string, DescriptorEntry>();
+
+  for (const e of entries) {
+    const field = DESCRIPTOR_FIELD_MAP.get(e.key);
+    const at = { line: e.line, startCol: e.startCol, endCol: e.endCol };
+    if (!field) {
+      issues.push({
+        code: "descriptor-unknown-key",
+        severity: "warning",
+        ...at,
+        message: `'${e.key}' is not a .mod descriptor key; the launcher ignores it.`,
+      });
+      continue;
+    }
+    if (seen.has(e.key) && !field.repeatable) {
+      issues.push({
+        code: "descriptor-duplicate-key",
+        severity: "warning",
+        ...at,
+        message: `'${e.key}' appears more than once; only the last value counts.`,
+      });
+    }
+    seen.set(e.key, e);
+    if (e.key === "path" && opts.isDescriptorFile) {
+      issues.push({
+        code: "descriptor-path-ignored",
+        severity: "warning",
+        ...at,
+        message:
+          "path= belongs in the outer <name>.mod file; inside descriptor.mod the launcher ignores it, " +
+          "and a machine-specific path leaks when the mod is shared.",
+      });
+    }
+  }
+
+  for (const field of DESCRIPTOR_FIELDS) {
+    if (!field.required || seen.has(field.key)) continue;
+    // supported_version: the launcher still lists the mod, it just cannot
+    // check compatibility - a warning, not an error.
+    const isHard = field.key !== "supported_version";
+    issues.push({
+      code: "descriptor-missing-field",
+      severity: isHard ? "error" : "warning",
+      line: 0,
+      startCol: 0,
+      endCol: 200,
+      message: isHard
+        ? `Missing ${field.key}= - the launcher needs it to list the mod.`
+        : "Missing supported_version= - the launcher cannot tell which game version the mod is for.",
+    });
+  }
+
+  return issues;
+}
+
+/**
+ * The mod's display name from `<dir>/descriptor.mod` (`name="..."`), or null
+ * when the file or field is missing/unreadable. Lets UI surfaces say WHICH mod
+ * something comes from ("Community Flavor Pack") instead of a generic "mod".
+ */
+export function readDescriptorName(dir: string): string | null {
+  let text: string;
+  try {
+    text = fs.readFileSync(path.join(dir, "descriptor.mod"), "utf8");
+  } catch {
+    return null;
+  }
+  const entry = parseDescriptor(text).find((e) => e.key === "name");
+  if (!entry) return null;
+  const value = entry.value.replace(/^"([^]*)"$/, "$1").trim();
+  return value === "" ? null : value;
+}
+
+/**
+ * The mod names inside `<dir>/descriptor.mod`'s `dependencies={ "A" "B" }`
+ * block, in file order; empty when the file or the block is missing. The
+ * launcher matches these against the other mods' `name=`, not against their
+ * Workshop id, so that is what the caller compares them with.
+ */
+export function readDescriptorDependencies(dir: string): string[] {
+  let text: string;
+  try {
+    text = fs.readFileSync(path.join(dir, "descriptor.mod"), "utf8");
+  } catch {
+    return [];
+  }
+  // Comments first: a commented-out dependency is not a dependency.
+  const block = /(?:^|\n)[ \t]*dependencies[ \t]*=[ \t]*\{([^}]*)\}/.exec(text.replace(/#[^\n]*/g, ""));
+  if (!block) return [];
+  return [...block[1].matchAll(/"([^"]*)"/g)].map((m) => m[1].trim()).filter((s) => s !== "");
+}
+
+/** "1.19.0.6" -> "1.19.*" (the wildcard form that survives hotfixes). */
+export function wildcardVersion(raw: string): string | null {
+  const m = /^(\d+)\.(\d+)/.exec(raw.trim());
+  return m ? `${m[1]}.${m[2]}.*` : null;
+}
+
+/** A launcher-correct starter descriptor.mod. */
+export function scaffoldDescriptor(modName: string, supportedVersion: string): string {
+  return [
+    'version="0.1.0"',
+    "tags={",
+    '\t"Gameplay"',
+    "}",
+    `name="${modName.replace(/"/g, "'")}"`,
+    `supported_version="${supportedVersion}"`,
+    "",
+  ].join("\n");
+}

package/src/errorLogParser.ts

@@ -0,0 +1,136 @@
+/**
+ * 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.
+ */
+
+/** `... 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*/;
+
+export interface ParsedGameError {
+  message: string;
+  relFile: string;
+  /** 0-based, or null for file-level entries. */
+  line: number | null;
+  severity: "error" | "warning";
+}
+
+interface FileMatch {
+  relFile: string;
+  line: number | null;
+  /** Text of the location match, so callers can drop it from the message. */
+  matched: string;
+}
+
+/** The file/line a log line names, in either shape; null when it names none. */
+function matchFile(line: string): FileMatch | null {
+  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. */
+export function parseErrorLogLine(raw: string): ParsedGameError | null {
+  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.
+ */
+export class ErrorLogParser {
+  private pendingSeverity: "error" | "warning" | null = null;
+  private pendingError: string | null = null;
+
+  push(raw: string): ParsedGameError | null {
+    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: ParsedGameError = {
+      message: this.pendingError ?? line.trim(),
+      relFile: m.relFile,
+      line: m.line,
+      severity: this.pendingSeverity,
+    };
+    this.reset();
+    return parsed;
+  }
+
+  reset(): void {
+    this.pendingSeverity = null;
+    this.pendingError = null;
+  }
+}

package/src/fsWalk.ts

@@ -0,0 +1,126 @@
+/**
+ * Recursive file listing shared by the server indexer and client-side
+ * reference scans. No `vscode` imports.
+ */
+import * as fs from "fs";
+import * as path from "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.
+ */
+export 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 function* iterFiles(dir: string, ext: string): Generator<string | null> {
+  // 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<string>(), { count: 0 });
+}
+
+/** All files under `dir` (recursive) with the given extension (lowercase match). */
+export function listFiles(dir: string, ext: string): string[] {
+  const out: string[] = [];
+  walkDir(dir, ext, out);
+  return out;
+}
+
+export function walkDir(dir: string, ext: string, out: string[]): void {
+  for (const file of iterFiles(dir, ext)) {
+    if (file !== null) out.push(file);
+  }
+}
+
+function* walk(
+  dir: string,
+  ext: string,
+  visited: Set<string>,
+  tick: { count: number }
+): Generator<string | null> {
+  let entries: fs.Dirent[];
+  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 % 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: string): string {
+  const n = process.platform === "win32" ? p.toLowerCase() : p;
+  return n.replace(/[\\/]+$/, "");
+}
+
+/** True when `inner` is `outer` itself or sits below it. */
+function isSameOrBelow(outer: string, inner: string): boolean {
+  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: string,
+  ext: string,
+  visited: Set<string>,
+  tick: { count: number }
+): Generator<string | null> {
+  let target: fs.Stats;
+  let real: string;
+  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: string;
+  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/src/locProperties.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 const STRICT_LOC_PROPERTIES = new Set<string>([
+  "title",
+  "desc",
+  "flavor",
+  "custom_tooltip",
+  "confirm_text",
+  "confirm_title",
+  "prompt",
+  "failure_desc",
+  "success_desc",
+]);
+
+export const BROAD_LOC_PROPERTIES = new Set<string>([
+  ...STRICT_LOC_PROPERTIES,
+  "name",
+  "text",
+  "tooltip",
+  "first_valid",
+  "reason",
+  "format",
+  "header",
+  "opinion_text",
+  "what",
+  "who",
+]);
+
+export function isLocProperty(prop: string): "strict" | "broad" | null {
+  const p = prop.toLowerCase();
+  if (STRICT_LOC_PROPERTIES.has(p)) return "strict";
+  if (BROAD_LOC_PROPERTIES.has(p)) return "broad";
+  return null;
+}

package/src/locRefs.ts

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+import { isLocProperty } from "./locProperties";
+
+const PROP_VALUE = /([A-Za-z_][A-Za-z0-9_.-]*)\s*=\s*("?)([A-Za-z_][A-Za-z0-9_.-]*)\2/g;
+
+export interface LocKeyRef {
+  prop: string;
+  key: string;
+  /** Character range of the key on the line. */
+  start: number;
+  end: number;
+  strictness: "strict" | "broad";
+}
+
+export function findLocKeyRefs(lineText: string): LocKeyRef[] {
+  const refs: LocKeyRef[] = [];
+  PROP_VALUE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = PROP_VALUE.exec(lineText)) !== null) {
+    const strictness = 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. */
+export function locKeyOnLine(lineText: string): string | null {
+  const m = /^\s*([A-Za-z0-9_.\-']+):\d*\s*"/.exec(lineText.replace(/^/, ""));
+  return m ? m[1] : null;
+}