@px-lsp/protocol 0.1.0 → 0.2.1

package/src/calendarFile.ts

@@ -0,0 +1,81 @@
+/**
+ * The per-mod calendar declaration: `<mod>/.px-toolkit/calendar.json`, the
+ * JSON form of calendar.ts `CalendarSetting`. A display calendar is a fact
+ * about the mod, so it travels with the mod (committed, one per mod, read by
+ * every client and by the server itself) instead of living in one editor's
+ * window-scoped `px.calendar` setting. The setting stays as the fallback for
+ * a mod without the file.
+ *
+ * No `vscode` imports: unit-tested in plain Node.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { sanitizeCalendar, type CalendarSetting } from "./calendar";
+import { migrateConfigDir, resolveConfigDir, type ConfigDirNames } from "./configDir";
+
+export const CALENDAR_FILE = "calendar.json";
+
+export interface CalendarFile {
+  /** Where the declaration was read from (or would be written to). */
+  file: string;
+  /** The declared calendar, when the file parses and sanitizes. */
+  calendar?: CalendarSetting;
+  /** Why an existing file yields no calendar: unparsable JSON or an unusable shape. */
+  error?: string;
+}
+
+/** The path the file is read from: the mod's config dir (legacy name included). */
+export function calendarFilePath(modRoot: string, names: ConfigDirNames): string {
+  return path.join(resolveConfigDir(modRoot, names), CALENDAR_FILE);
+}
+
+/**
+ * Read `<mod>/.px-toolkit/calendar.json`. Null when the file does not exist;
+ * a `CalendarFile` without `calendar` when it exists but is not usable, so a
+ * client can say so instead of silently showing no dates.
+ */
+export function readCalendarFile(modRoot: string, names: ConfigDirNames): CalendarFile | null {
+  const file = calendarFilePath(modRoot, names);
+  let text: string;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text.replace(/^\uFEFF/, ""));
+  } catch (err) {
+    return { file, error: `not valid JSON (${(err as Error).message})` };
+  }
+  const calendar = sanitizeCalendar(raw);
+  if (!calendar) {
+    return {
+      file,
+      error:
+        'not a usable calendar: needs a whole-number "epoch" (1 or more), a non-empty "after" era label, ' +
+        'a "before" label different from "after" when present, and, when "months" is given, exactly twelve distinct names',
+    };
+  }
+  return { file, calendar };
+}
+
+/**
+ * Write the declaration into the mod (renaming a legacy config dir first,
+ * like every other config-dir write). Returns the file path.
+ */
+export function writeCalendarFile(modRoot: string, names: ConfigDirNames, cal: CalendarSetting): string {
+  const dir = migrateConfigDir(modRoot, names);
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, CALENDAR_FILE);
+  fs.writeFileSync(file, JSON.stringify(cal, null, 2) + "\n", "utf8");
+  return file;
+}
+
+/** True when `fsPath` is a calendar declaration file (any config dir name). */
+export function isCalendarFile(fsPath: string, names: ConfigDirNames): boolean {
+  const parts = fsPath.split(/[\\/]/);
+  if (parts.length < 2 || parts[parts.length - 1].toLowerCase() !== CALENDAR_FILE) return false;
+  const dir = parts[parts.length - 2].toLowerCase();
+  return dir === names.configDirName.toLowerCase() || dir === names.legacyConfigDirName?.toLowerCase();
+}

package/src/calendarLoc.ts

@@ -0,0 +1,159 @@
+/**
+ * Generate the GAME-SIDE localization for a `px.calendar` display calendar:
+ * the era-math datafunction keys plus the `localization/replace/` overrides
+ * of the engine's date-format and month-name keys. This is the mirror image
+ * of calendar.ts: that file teaches the EDITOR the mapping, this one writes
+ * the mapping into the mod so the GAME displays it (the AGoT/LotR technique).
+ *
+ * Pure logic, no `vscode` imports; the extension command writes the returned
+ * files (adding the BOM) and per-game key names come in via `CalendarLocSpec`
+ * from the GameProfile, so no game knowledge lives here.
+ */
+import type { CalendarSetting } from "./calendar";
+
+/**
+ * The loc keys a game formats dates through, verified against the game's
+ * binary/files. Lives in the GameProfile (`games/<id>/meta.ts`); a profile
+ * without one does not support generation.
+ */
+export interface CalendarLocSpec {
+  /**
+   * Vanilla date-format keys to override in `localization/replace/`, mapped
+   * to their format template. `{year}` and `{era}` mark where the generated
+   * era-math key references go; everything else is kept verbatim (the
+   * vanilla `$DAY$`/`$MONTH$` parameters).
+   */
+  dateFormats: Record<string, string>;
+  /**
+   * Engine month-name loc keys, first month first: [longKey, shortKey].
+   * Overridden only when the calendar declares custom months, and only when
+   * it declares exactly as many months as the engine has.
+   */
+  monthKeys?: [string, string][];
+}
+
+/** One file the generator wants written, path relative to the mod root. */
+export interface GeneratedLocFile {
+  /** Forward slashes; the writer joins it onto the mod root. */
+  relPath: string;
+  /** Content without BOM; the writer prepends it. */
+  content: string;
+}
+
+export interface CalendarLocResult {
+  files: GeneratedLocFile[];
+  /** Facts the modder should know after generating (limits, follow-ups). */
+  notes: string[];
+}
+
+/** Keys the generated files define; exported so tests and docs stay in sync. */
+export const CAL_YEAR_KEY = "PX_CAL_YEAR";
+export const CAL_ERA_KEY = "PX_CAL_ERA";
+
+/** Era labels sit inside '...' CString literals; a quote would break the
+ * datafunction silently, which is exactly the failure class we exist to
+ * prevent. */
+function cstring(label: string): string {
+  return label.replace(/'/g, "");
+}
+
+/**
+ * `[Select_int32(...)]` era math for the year, mirroring
+ * calendar.ts `displayYear`: y >= epoch shows as y - (epoch - 1), below as
+ * epoch - y. A single-era calendar (no `before`) clamps to 1 instead, so
+ * pre-epoch years never display as 0 or negative.
+ */
+function yearExpr(cal: CalendarSetting): string {
+  const year = "'(int32)$YEAR|q$'";
+  const toAfter = `Subtract_int32( ${year}, '(int32)${cal.epoch - 1}' )`;
+  if (!cal.before) return `[Max_int32( ${toAfter}, '(int32)1' )]`;
+  const toBefore = `Subtract_int32( '(int32)${cal.epoch}', ${year} )`;
+  return `[Select_int32( GreaterThanOrEqualTo_int32( ${year}, '(int32)${cal.epoch}' ), ${toAfter}, ${toBefore} )]`;
+}
+
+function eraExpr(cal: CalendarSetting): string {
+  if (!cal.before) return cal.after;
+  return (
+    `[Select_CString( GreaterThanOrEqualTo_int32( '(int32)$YEAR|q$', '(int32)${cal.epoch}' ), ` +
+    `'${cstring(cal.after)}', '${cstring(cal.before)}' )]`
+  );
+}
+
+function locFile(lang: string, lines: string[]): string {
+  return [`l_${lang}:`, ...lines, ""].join("\n");
+}
+
+/**
+ * The two files implementing the calendar in game:
+ *
+ * - `localization/<lang>/px_calendar_l_<lang>.yml` - the era-math keys
+ *   (new keys, so NOT in replace/).
+ * - `localization/replace/<lang>/px_calendar_dates_l_<lang>.yml` - the
+ *   vanilla date-format overrides routing `$YEAR$` through them, plus the
+ *   engine month-name overrides when the calendar has custom months.
+ *
+ * Deterministic filenames: regenerating after a `px.calendar` change
+ * overwrites the same two files.
+ */
+export function generateCalendarLoc(
+  cal: CalendarSetting,
+  spec: CalendarLocSpec,
+  lang: string
+): CalendarLocResult {
+  const notes: string[] = [];
+  const header = [
+    " # Generated by 'Paradox: Generate Calendar Localization' from the px.calendar",
+    " # setting. Edit px.calendar and regenerate instead of editing by hand.",
+  ];
+
+  const eraDoc = cal.before
+    ? ` # Script year >= ${cal.epoch} shows as (year - ${cal.epoch - 1}) ${cal.after}; below as (${cal.epoch} - year) ${cal.before}.`
+    : ` # Script year >= ${cal.epoch} shows as (year - ${cal.epoch - 1}) ${cal.after}; earlier years clamp to 1.`;
+  const mathLines = [
+    ...header,
+    eraDoc,
+    ` ${CAL_YEAR_KEY}:0 "${yearExpr(cal)}"`,
+    ` ${CAL_ERA_KEY}:0 "${eraExpr(cal)}"`,
+  ];
+
+  const overrideLines = [
+    ...header,
+    " # Overrides of the engine's date-format keys: same formats as vanilla, with",
+    ` # the raw $YEAR$ routed through ${CAL_YEAR_KEY}/${CAL_ERA_KEY}.`,
+  ];
+  for (const [key, format] of Object.entries(spec.dateFormats)) {
+    const value = format.replace("{year}", `$${CAL_YEAR_KEY}$`).replace("{era}", `$${CAL_ERA_KEY}$`);
+    overrideLines.push(` ${key}:0 "${value}"`);
+  }
+
+  if (cal.months) {
+    const months = cal.months;
+    if (!spec.monthKeys) {
+      notes.push("This game's month-name keys are not mapped yet; custom month names were not generated.");
+    } else {
+      // The calendar carries the engine's twelve names (sanitizeCalendar); the
+      // spec lists the keys of the months it knows, first month first.
+      overrideLines.push(" # Engine month names (long and abbreviated forms both get the custom name).");
+      spec.monthKeys.forEach(([long, short], i) => {
+        const name = months[i].replace(/"/g, '\\"');
+        overrideLines.push(` ${long}:0 "${name}"`);
+        if (short !== long) overrideLines.push(` ${short}:0 "${name}"`);
+      });
+    }
+  }
+
+  notes.push(
+    `Generated for '${lang}' only; other languages the mod ships need the same overrides in their replace folder.`
+  );
+
+  return {
+    files: [
+      { relPath: `localization/${lang}/px_calendar_l_${lang}.yml`, content: locFile(lang, mathLines) },
+      {
+        relPath: `localization/replace/${lang}/px_calendar_dates_l_${lang}.yml`,
+        content: locFile(lang, overrideLines),
+      },
+    ],
+    notes,
+  };
+}

package/src/configDir.ts

@@ -0,0 +1,47 @@
+/**
+ * The toolkit's per-mod config dir: `<mod>/.px-toolkit/`, holding
+ * `workshop.json`, `schema.json`, `playset.json`, the tiger baseline, the GUI
+ * preview values and the Workshop listing folder. Mods created before 0.4.0
+ * have a per-game name instead (each GameMeta's `legacyConfigDirName`);
+ * reads keep finding it, and the first write renames it.
+ *
+ * No `vscode` imports: unit-tested in plain Node.
+ */
+import * as fs from "fs";
+import * as path from "path";
+
+export const PX_CONFIG_DIR = ".px-toolkit";
+
+export interface ConfigDirNames {
+  configDirName: string;
+  /** The pre-0.4.0 per-game name, still read as a fallback. */
+  legacyConfigDirName?: string;
+}
+
+/**
+ * The config dir to READ from: the current name when it exists, else the
+ * legacy one when that exists, else the current name. Never touches disk.
+ */
+export function resolveConfigDir(root: string, names: ConfigDirNames): string {
+  const current = path.join(root, names.configDirName);
+  if (!names.legacyConfigDirName || fs.existsSync(current)) return current;
+  const legacy = path.join(root, names.legacyConfigDirName);
+  return fs.existsSync(legacy) ? legacy : current;
+}
+
+/**
+ * The config dir to WRITE to. Renames a legacy dir to the current name first;
+ * if the rename fails (locked file, read-only parent) the legacy dir stays in
+ * use so the write still lands where reads look.
+ */
+export function migrateConfigDir(root: string, names: ConfigDirNames): string {
+  const current = path.join(root, names.configDirName);
+  const resolved = resolveConfigDir(root, names);
+  if (resolved === current) return current;
+  try {
+    fs.renameSync(resolved, current);
+    return current;
+  } catch {
+    return resolved;
+  }
+}

package/src/constants.ts

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

package/src/descriptorMetadata.ts

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