@px-lsp/protocol 0.1.0 → 0.2.0

package/src/translationCore.ts

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

@@ -1,90 +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;
-}
+/** 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/src/workshopMeta.ts

@@ -0,0 +1,132 @@
+/**
+ * The mod's local Workshop record: `<mod>/<configDir>/workshop.json`. It holds
+ * what the game's own descriptor has no field for - the item's description and
+ * its per-language translations (title + description shown to Workshop
+ * visitors browsing Steam in that language), plus the published id for the
+ * `.metadata` games (launcher-`.mod` games keep the id in `remote_file_id`).
+ *
+ * The local file is the canonical copy once the user manages the item from the
+ * toolkit: uploads read from here, and "fetch" pulls the live values down into
+ * it. Reads and writes are merge-preserving: keys this version does not know
+ * survive a round trip.
+ *
+ * No `vscode` imports here: this module is unit-tested in plain Node.
+ */
+import * as fs from "fs";
+import * as path from "path";
+
+/** Title/description pair of one Workshop language. Absent field = not translated. */
+export interface WorkshopTranslation {
+  title?: string;
+  description?: string;
+}
+
+/** The fields of `workshop.json` this toolkit reads or writes. */
+export interface WorkshopMeta {
+  /** Workshop item id (decimal string), for the games whose descriptor has no field for it. */
+  publishedFileId?: string;
+  /** The item's description in the default language, BBCode as Steam renders it. */
+  description?: string;
+  /** Keyed by Steam API language code (`german`, `schinese`, ...), never the default language. */
+  translations?: Record<string, WorkshopTranslation>;
+}
+
+/** Mod-root-relative path of the record, forward slashes. */
+export function workshopMetaRelPath(configDirName: string): string {
+  return `${configDirName}/workshop.json`;
+}
+
+/** The parsed `<dir>/<configDir>/workshop.json`, or null when absent/unreadable. */
+export function readWorkshopMeta(dir: string, configDirName: string): WorkshopMeta | null {
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(dir, configDirName, "workshop.json"), "utf8")) as Record<
+      string,
+      unknown
+    >;
+    if (typeof raw !== "object" || raw === null) return null;
+    return raw as WorkshopMeta;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Merge `patch` into the record and write it back. Unknown keys of the file
+ * survive; a patch key set to `undefined` is left as it was. `translations`
+ * replaces as a whole (the caller edits the full map).
+ */
+export function upsertWorkshopMeta(dir: string, configDirName: string, patch: WorkshopMeta): void {
+  const file = path.join(dir, configDirName, "workshop.json");
+  const current = (readWorkshopMeta(dir, configDirName) ?? {}) as Record<string, unknown>;
+  for (const [key, value] of Object.entries(patch)) {
+    if (value !== undefined) current[key] = value;
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(current, null, 2) + "\n", "utf8");
+}
+
+/**
+ * The languages the Workshop accepts item text in: Steam's API language codes
+ * with their English names, in Steam's documented order.
+ * https://partner.steamgames.com/doc/store/localization/languages
+ */
+export const STEAM_LANGUAGES: readonly { api: string; label: string }[] = [
+  { api: "arabic", label: "Arabic" },
+  { api: "bulgarian", label: "Bulgarian" },
+  { api: "schinese", label: "Chinese (Simplified)" },
+  { api: "tchinese", label: "Chinese (Traditional)" },
+  { api: "czech", label: "Czech" },
+  { api: "danish", label: "Danish" },
+  { api: "dutch", label: "Dutch" },
+  { api: "english", label: "English" },
+  { api: "finnish", label: "Finnish" },
+  { api: "french", label: "French" },
+  { api: "german", label: "German" },
+  { api: "greek", label: "Greek" },
+  { api: "hungarian", label: "Hungarian" },
+  { api: "indonesian", label: "Indonesian" },
+  { api: "italian", label: "Italian" },
+  { api: "japanese", label: "Japanese" },
+  { api: "koreana", label: "Korean" },
+  { api: "norwegian", label: "Norwegian" },
+  { api: "polish", label: "Polish" },
+  { api: "portuguese", label: "Portuguese" },
+  { api: "brazilian", label: "Portuguese (Brazil)" },
+  { api: "romanian", label: "Romanian" },
+  { api: "russian", label: "Russian" },
+  { api: "spanish", label: "Spanish (Spain)" },
+  { api: "latam", label: "Spanish (Latin America)" },
+  { api: "swedish", label: "Swedish" },
+  { api: "thai", label: "Thai" },
+  { api: "turkish", label: "Turkish" },
+  { api: "ukrainian", label: "Ukrainian" },
+  { api: "vietnamese", label: "Vietnamese" },
+];
+
+/** English name of a Steam API language code; the code itself when unknown. */
+export function steamLanguageLabel(api: string): string {
+  return STEAM_LANGUAGES.find((l) => l.api === api)?.label ?? api;
+}
+
+/**
+ * Steam API language code for a Paradox localization folder language
+ * (`translationCore.ts` LOC_LANGUAGES), or null when Steam has no counterpart.
+ * The two vocabularies differ where Steam's codes predate its own store pages
+ * (`koreana`, `schinese`).
+ */
+export function steamLanguageForLoc(locLanguage: string): string | null {
+  const map: Record<string, string> = {
+    english: "english",
+    french: "french",
+    german: "german",
+    spanish: "spanish",
+    russian: "russian",
+    korean: "koreana",
+    simp_chinese: "schinese",
+    japanese: "japanese",
+    polish: "polish",
+    braz_por: "brazilian",
+    turkish: "turkish",
+  };
+  return map[locLanguage] ?? null;
+}