@px-lsp/protocol 0.1.0 → 0.2.1

package/README.md

@@ -1,25 +1,25 @@
-# @px-lsp/protocol
-
-The wire contract of the [px-lsp language server](https://github.com/JDeffner/paradox-modding-toolkit):
-custom LSP request/notification names, their payload types, the settings and
-initialization-option shapes, plus a few pure helpers shared between the
-server and its clients (tiger report parsing, `.mod` descriptor parsing,
-diagnostic suppression, localization helpers).
-
-The published package ships compiled JavaScript with type declarations, so it
-works from plain Node and from any bundler:
-
-```ts
-// The root export is the wire contract (request/notification names + payload types):
-import { modOverviewRequest, type ModOverview } from "@px-lsp/protocol";
-// The helpers live in named modules:
-import { parseTigerJson } from "@px-lsp/protocol/tigerParser";
-import { parseDescriptor } from "@px-lsp/protocol/descriptorMod";
-```
-
-Clients in other languages should code against the documented contract instead:
-see [`docs/PROTOCOL.md`](https://github.com/JDeffner/paradox-modding-toolkit/blob/main/docs/PROTOCOL.md)
-in the repository. Changes to the wire contract are treated as API changes
-and versioned with the packages.
-
-License: GPL-3.0-or-later.
+# @px-lsp/protocol
+
+The wire contract of the [px-lsp language server](https://github.com/JDeffner/paradox-modding-toolkit):
+custom LSP request/notification names, their payload types, the settings and
+initialization-option shapes, plus a few pure helpers shared between the
+server and its clients (tiger report parsing, `.mod` descriptor parsing,
+diagnostic suppression, localization helpers).
+
+The published package ships compiled JavaScript with type declarations, so it
+works from plain Node and from any bundler:
+
+```ts
+// The root export is the wire contract (request/notification names + payload types):
+import { modOverviewRequest, type ModOverview } from "@px-lsp/protocol";
+// The helpers live in named modules:
+import { parseTigerJson } from "@px-lsp/protocol/tigerParser";
+import { parseDescriptor } from "@px-lsp/protocol/descriptorMod";
+```
+
+Clients in other languages should code against the documented contract instead:
+see [`docs/PROTOCOL.md`](https://github.com/JDeffner/paradox-modding-toolkit/blob/main/docs/PROTOCOL.md)
+in the repository. Changes to the wire contract are treated as API changes
+and versioned with the packages.
+
+License: GPL-3.0-or-later.

package/dist/calendar.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Custom calendar display: total-conversion mods (AGoT, LotR, Hegemonia...)
+ * keep script dates on the engine's single increasing year axis but *display*
+ * them on their own era system, e.g. epoch 4000 means script year 3000 shows
+ * as "1000 BC" and 4000 as "1 AD". The mapping cannot be detected from mod
+ * files, so the mod declares it once in `px.calendar` (workspace settings,
+ * committed with the mod).
+ *
+ * Pure logic, no `vscode` imports: shared by the language server (inlay hints,
+ * hover) and the extension (the Insert Date command), unit-tested in plain
+ * Node.
+ */
+export interface CalendarSetting {
+    /** Script year displayed as year 1 of the `after` era (no year zero). */
+    epoch: number;
+    /** Era label for script years >= epoch ("AD", "TA"...). */
+    after: string;
+    /** Era label for script years < epoch ("BC"). Omitted = single-era
+     * calendar: years before the epoch get no display form. */
+    before?: string;
+    /**
+     * The engine's twelve months under the mod's own names, first month first.
+     * Omitted = January to December. Only the NAMES are the mod's: the game has
+     * twelve months of fixed length (31 28 31 30 31 30 31 31 30 31 30 31, no
+     * leap years) and no script can change that, so a date's month and day are
+     * always the engine's and only read differently.
+     */
+    months?: string[];
+}
+/** Days per engine month; what a script date's day is bounded by. */
+export declare const ENGINE_MONTH_DAYS: number[];
+export declare const GREGORIAN_MONTHS: string[];
+/** The month names a date reads with: the mod's twelve, or the engine's. */
+export declare function monthNames(cal: CalendarSetting): string[];
+/**
+ * Validate a calendar straight out of JSON settings (any client, any hand-
+ * edited settings file). Returns a clean copy, or undefined when the value is
+ * not a usable calendar - features then behave as if none was configured.
+ */
+export declare function sanitizeCalendar(raw: unknown): CalendarSetting | undefined;
+/** A script-file date token (`3000.1.1`), or null when the text is not one. */
+export declare function parseScriptDate(text: string): {
+    y: number;
+    m: number;
+    d: number;
+} | null;
+/** A date the engine reads: a positive year, one of its twelve months, a day that month has. */
+export declare function isValidScriptDate(y: number, m: number, d: number): boolean;
+/** Era-mapped year: "1000 BC". Null for pre-epoch years of a single-era calendar. */
+export declare function displayYear(cal: CalendarSetting, y: number): string | null;
+/**
+ * Full display form of a script date: "1000 BC" for the year's first day
+ * (how start dates read in game), "15 March 1000 BC" otherwise. Null when the
+ * date does not fit the calendar.
+ */
+export declare function displayDate(cal: CalendarSetting, y: number, m: number, d: number): string | null;
+export type ConvertResult = {
+    ok: true;
+    script: string;
+    display: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * A display-calendar date typed by the user -> the script date the file needs.
+ * Grammar: `YEAR [ERA] [MONTH [DAY]]`, e.g. "1000 BC", "1000 BC March 15",
+ * "1000 BC 3 15", "1 AD", "500" (era defaults to `after`). MONTH is a number
+ * or a month name (unique prefix is enough).
+ */
+export declare function convertDisplayInput(cal: CalendarSetting, input: string): ConvertResult;

package/dist/calendar.js

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * Custom calendar display: total-conversion mods (AGoT, LotR, Hegemonia...)
+ * keep script dates on the engine's single increasing year axis but *display*
+ * them on their own era system, e.g. epoch 4000 means script year 3000 shows
+ * as "1000 BC" and 4000 as "1 AD". The mapping cannot be detected from mod
+ * files, so the mod declares it once in `px.calendar` (workspace settings,
+ * committed with the mod).
+ *
+ * Pure logic, no `vscode` imports: shared by the language server (inlay hints,
+ * hover) and the extension (the Insert Date command), unit-tested in plain
+ * Node.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GREGORIAN_MONTHS = exports.ENGINE_MONTH_DAYS = void 0;
+exports.monthNames = monthNames;
+exports.sanitizeCalendar = sanitizeCalendar;
+exports.parseScriptDate = parseScriptDate;
+exports.isValidScriptDate = isValidScriptDate;
+exports.displayYear = displayYear;
+exports.displayDate = displayDate;
+exports.convertDisplayInput = convertDisplayInput;
+/** Days per engine month; what a script date's day is bounded by. */
+exports.ENGINE_MONTH_DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+exports.GREGORIAN_MONTHS = [
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December",
+];
+/** The month names a date reads with: the mod's twelve, or the engine's. */
+function monthNames(cal) {
+    return cal.months ?? exports.GREGORIAN_MONTHS;
+}
+/**
+ * Validate a calendar straight out of JSON settings (any client, any hand-
+ * edited settings file). Returns a clean copy, or undefined when the value is
+ * not a usable calendar - features then behave as if none was configured.
+ */
+function sanitizeCalendar(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const o = raw;
+    const epoch = o.epoch;
+    const after = o.after;
+    if (typeof epoch !== "number" || !Number.isInteger(epoch) || epoch < 1)
+        return undefined;
+    if (typeof after !== "string" || after.trim() === "")
+        return undefined;
+    const cal = { epoch, after: after.trim() };
+    if (typeof o.before === "string" && o.before.trim() !== "")
+        cal.before = o.before.trim();
+    // Typed input picks the era by its label and the month by its name, so a
+    // collision would resolve silently to the wrong one: not a usable calendar.
+    if (cal.before && cal.before.toLowerCase() === cal.after.toLowerCase())
+        return undefined;
+    if (Array.isArray(o.months) && o.months.length > 0) {
+        // Exactly the engine's twelve. A name may still arrive as the older
+        // `{ name, days }` object; its day count never meant anything to the
+        // game and is dropped.
+        if (o.months.length !== exports.GREGORIAN_MONTHS.length)
+            return undefined;
+        const months = [];
+        const seen = new Set();
+        for (const m of o.months) {
+            const name = typeof m === "string" ? m : (m?.name ?? null);
+            if (typeof name !== "string" || name.trim() === "")
+                return undefined;
+            const key = name.trim().toLowerCase();
+            if (seen.has(key))
+                return undefined;
+            seen.add(key);
+            months.push(name.trim());
+        }
+        cal.months = months;
+    }
+    return cal;
+}
+/** A script-file date token (`3000.1.1`), or null when the text is not one. */
+function parseScriptDate(text) {
+    const match = /^(\d{1,5})\.(\d{1,2})\.(\d{1,2})$/.exec(text);
+    if (!match)
+        return null;
+    return { y: Number(match[1]), m: Number(match[2]), d: Number(match[3]) };
+}
+/** A date the engine reads: a positive year, one of its twelve months, a day that month has. */
+function isValidScriptDate(y, m, d) {
+    return y >= 1 && m >= 1 && m <= exports.ENGINE_MONTH_DAYS.length && d >= 1 && d <= exports.ENGINE_MONTH_DAYS[m - 1];
+}
+/** Era-mapped year: "1000 BC". Null for pre-epoch years of a single-era calendar. */
+function displayYear(cal, y) {
+    if (y >= cal.epoch)
+        return `${y - cal.epoch + 1} ${cal.after}`;
+    return cal.before ? `${cal.epoch - y} ${cal.before}` : null;
+}
+/**
+ * Full display form of a script date: "1000 BC" for the year's first day
+ * (how start dates read in game), "15 March 1000 BC" otherwise. Null when the
+ * date does not fit the calendar.
+ */
+function displayDate(cal, y, m, d) {
+    if (!isValidScriptDate(y, m, d))
+        return null;
+    const year = displayYear(cal, y);
+    if (!year)
+        return null;
+    if (m === 1 && d === 1)
+        return year;
+    return `${d} ${monthNames(cal)[m - 1]} ${year}`;
+}
+/** Case-insensitive month lookup: exact name, else unique prefix. */
+function monthByName(cal, text) {
+    const needle = text.toLowerCase();
+    const months = monthNames(cal);
+    const exact = months.findIndex((m) => m.toLowerCase() === needle);
+    if (exact >= 0)
+        return exact + 1;
+    const prefixed = months.map((m, i) => ({ m, i })).filter(({ m }) => m.toLowerCase().startsWith(needle));
+    return prefixed.length === 1 ? prefixed[0].i + 1 : null;
+}
+/**
+ * A display-calendar date typed by the user -> the script date the file needs.
+ * Grammar: `YEAR [ERA] [MONTH [DAY]]`, e.g. "1000 BC", "1000 BC March 15",
+ * "1000 BC 3 15", "1 AD", "500" (era defaults to `after`). MONTH is a number
+ * or a month name (unique prefix is enough).
+ */
+function convertDisplayInput(cal, input) {
+    const words = input.trim().split(/\s+/).filter(Boolean);
+    if (words.length === 0)
+        return { ok: false, error: "type a year, e.g. 1000 " + (cal.before ?? cal.after) };
+    if (!/^\d{1,5}$/.test(words[0]))
+        return { ok: false, error: `"${words[0]}" is not a year` };
+    const year = Number(words[0]);
+    let rest = words.slice(1);
+    let era = cal.after;
+    if (rest.length > 0) {
+        const w = rest[0].toLowerCase();
+        if (w === cal.after.toLowerCase()) {
+            rest = rest.slice(1);
+        }
+        else if (cal.before && w === cal.before.toLowerCase()) {
+            era = cal.before;
+            rest = rest.slice(1);
+        }
+    }
+    let m = 1;
+    let d = 1;
+    if (rest.length > 0) {
+        const month = /^\d{1,2}$/.test(rest[0]) ? Number(rest[0]) : monthByName(cal, rest[0]);
+        if (month === null)
+            return { ok: false, error: `"${rest[0]}" is not a month of this calendar` };
+        m = month;
+        rest = rest.slice(1);
+    }
+    if (rest.length > 0) {
+        if (!/^\d{1,3}$/.test(rest[0]))
+            return { ok: false, error: `"${rest[0]}" is not a day` };
+        d = Number(rest[0]);
+        rest = rest.slice(1);
+    }
+    if (rest.length > 0)
+        return { ok: false, error: `unexpected "${rest.join(" ")}"` };
+    if (year < 1)
+        return { ok: false, error: "years start at 1 (no year zero)" };
+    const y = era === cal.after ? year + cal.epoch - 1 : cal.epoch - year;
+    if (y < 1)
+        return { ok: false, error: `${year} ${era} is before script year 1 (epoch ${cal.epoch})` };
+    if (!isValidScriptDate(y, m, d)) {
+        return m >= 1 && m <= exports.ENGINE_MONTH_DAYS.length
+            ? { ok: false, error: `${monthNames(cal)[m - 1]} has ${exports.ENGINE_MONTH_DAYS[m - 1]} days` }
+            : { ok: false, error: `the game has ${exports.ENGINE_MONTH_DAYS.length} months` };
+    }
+    return { ok: true, script: `${y}.${m}.${d}`, display: displayDate(cal, y, m, d) };
+}

package/dist/calendarFile.d.ts

@@ -0,0 +1,26 @@
+import { type CalendarSetting } from "./calendar";
+import { type ConfigDirNames } from "./configDir";
+export declare 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 declare function calendarFilePath(modRoot: string, names: ConfigDirNames): string;
+/**
+ * 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 declare function readCalendarFile(modRoot: string, names: ConfigDirNames): CalendarFile | null;
+/**
+ * Write the declaration into the mod (renaming a legacy config dir first,
+ * like every other config-dir write). Returns the file path.
+ */
+export declare function writeCalendarFile(modRoot: string, names: ConfigDirNames, cal: CalendarSetting): string;
+/** True when `fsPath` is a calendar declaration file (any config dir name). */
+export declare function isCalendarFile(fsPath: string, names: ConfigDirNames): boolean;

package/dist/calendarFile.js

@@ -0,0 +1,109 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CALENDAR_FILE = void 0;
+exports.calendarFilePath = calendarFilePath;
+exports.readCalendarFile = readCalendarFile;
+exports.writeCalendarFile = writeCalendarFile;
+exports.isCalendarFile = isCalendarFile;
+/**
+ * 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.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const calendar_1 = require("./calendar");
+const configDir_1 = require("./configDir");
+exports.CALENDAR_FILE = "calendar.json";
+/** The path the file is read from: the mod's config dir (legacy name included). */
+function calendarFilePath(modRoot, names) {
+    return path.join((0, configDir_1.resolveConfigDir)(modRoot, names), exports.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.
+ */
+function readCalendarFile(modRoot, names) {
+    const file = calendarFilePath(modRoot, names);
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text.replace(/^\uFEFF/, ""));
+    }
+    catch (err) {
+        return { file, error: `not valid JSON (${err.message})` };
+    }
+    const calendar = (0, calendar_1.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.
+ */
+function writeCalendarFile(modRoot, names, cal) {
+    const dir = (0, configDir_1.migrateConfigDir)(modRoot, names);
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, exports.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). */
+function isCalendarFile(fsPath, names) {
+    const parts = fsPath.split(/[\\/]/);
+    if (parts.length < 2 || parts[parts.length - 1].toLowerCase() !== exports.CALENDAR_FILE)
+        return false;
+    const dir = parts[parts.length - 2].toLowerCase();
+    return dir === names.configDirName.toLowerCase() || dir === names.legacyConfigDirName?.toLowerCase();
+}

package/dist/calendarLoc.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 declare const CAL_YEAR_KEY = "PX_CAL_YEAR";
+export declare const CAL_ERA_KEY = "PX_CAL_ERA";
+/**
+ * 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 declare function generateCalendarLoc(cal: CalendarSetting, spec: CalendarLocSpec, lang: string): CalendarLocResult;

package/dist/calendarLoc.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CAL_ERA_KEY = exports.CAL_YEAR_KEY = void 0;
+exports.generateCalendarLoc = generateCalendarLoc;
+/** Keys the generated files define; exported so tests and docs stay in sync. */
+exports.CAL_YEAR_KEY = "PX_CAL_YEAR";
+exports.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) {
+    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) {
+    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) {
+    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, lines) {
+    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.
+ */
+function generateCalendarLoc(cal, spec, lang) {
+    const notes = [];
+    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,
+        ` ${exports.CAL_YEAR_KEY}:0 "${yearExpr(cal)}"`,
+        ` ${exports.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 ${exports.CAL_YEAR_KEY}/${exports.CAL_ERA_KEY}.`,
+    ];
+    for (const [key, format] of Object.entries(spec.dateFormats)) {
+        const value = format.replace("{year}", `$${exports.CAL_YEAR_KEY}$`).replace("{era}", `$${exports.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/dist/configDir.d.ts

@@ -0,0 +1,17 @@
+export declare 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 declare function resolveConfigDir(root: string, names: ConfigDirNames): string;
+/**
+ * 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 declare function migrateConfigDir(root: string, names: ConfigDirNames): string;