@px-lsp/protocol 0.2.0 → 0.2.1

package/dist/workshopMeta.d.ts

@@ -12,16 +12,14 @@ export interface WorkshopMeta {
     /** 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 declare function workshopMetaRelPath(configDirName: string): string;
-/** The parsed `<dir>/<configDir>/workshop.json`, or null when absent/unreadable. */
-export declare function readWorkshopMeta(dir: string, configDirName: string): WorkshopMeta | null;
+/** The parsed `<configDir>/workshop.json`, or null when absent/unreadable. */
+export declare function readWorkshopMeta(configDir: string): WorkshopMeta | 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 declare function upsertWorkshopMeta(dir: string, configDirName: string, patch: WorkshopMeta): void;
+export declare function upsertWorkshopMeta(configDir: string, patch: WorkshopMeta): void;
 /**
  * The languages the Workshop accepts item text in: Steam's API language codes
  * with their English names, in Steam's documented order.

package/dist/workshopMeta.js

@@ -34,7 +34,6 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.STEAM_LANGUAGES = void 0;
-exports.workshopMetaRelPath = workshopMetaRelPath;
 exports.readWorkshopMeta = readWorkshopMeta;
 exports.upsertWorkshopMeta = upsertWorkshopMeta;
 exports.steamLanguageLabel = steamLanguageLabel;
@@ -55,14 +54,10 @@ exports.steamLanguageForLoc = steamLanguageForLoc;
  */
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-/** Mod-root-relative path of the record, forward slashes. */
-function workshopMetaRelPath(configDirName) {
-    return `${configDirName}/workshop.json`;
-}
-/** The parsed `<dir>/<configDir>/workshop.json`, or null when absent/unreadable. */
-function readWorkshopMeta(dir, configDirName) {
+/** The parsed `<configDir>/workshop.json`, or null when absent/unreadable. */
+function readWorkshopMeta(configDir) {
     try {
-        const raw = JSON.parse(fs.readFileSync(path.join(dir, configDirName, "workshop.json"), "utf8"));
+        const raw = JSON.parse(fs.readFileSync(path.join(configDir, "workshop.json"), "utf8"));
         if (typeof raw !== "object" || raw === null)
             return null;
         return raw;
@@ -76,9 +71,9 @@ function readWorkshopMeta(dir, configDirName) {
  * survive; a patch key set to `undefined` is left as it was. `translations`
  * replaces as a whole (the caller edits the full map).
  */
-function upsertWorkshopMeta(dir, configDirName, patch) {
-    const file = path.join(dir, configDirName, "workshop.json");
-    const current = (readWorkshopMeta(dir, configDirName) ?? {});
+function upsertWorkshopMeta(configDir, patch) {
+    const file = path.join(configDir, "workshop.json");
+    const current = (readWorkshopMeta(configDir) ?? {});
     for (const [key, value] of Object.entries(patch)) {
         if (value !== undefined)
             current[key] = value;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@px-lsp/protocol",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "license": "GPL-3.0-or-later",
   "description": "Wire contract (custom LSP requests/notifications, settings types) and shared helpers for the px-lsp language server and its clients.",
   "keywords": [

package/src/calendar.ts

@@ -11,13 +11,6 @@
  * Node.
  */
 
-export interface CalendarMonth {
-  /** Display name ("March", "Narvinye"). */
-  name: string;
-  /** Day count; the engine has no leap years, so one number per month. */
-  days: number;
-}
-
 export interface CalendarSetting {
   /** Script year displayed as year 1 of the `after` era (no year zero). */
   epoch: number;
@@ -26,13 +19,20 @@ export interface CalendarSetting {
   /** Era label for script years < epoch ("BC"). Omitted = single-era
    * calendar: years before the epoch get no display form. */
   before?: string;
-  /** Custom month names and day counts, first month first. Omitted = the
-   * standard 12 months (Feb 28: the engine has no leap years). */
-  months?: CalendarMonth[];
+  /**
+   * 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[];
 }
 
-const DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
-export const GREGORIAN_MONTHS: CalendarMonth[] = [
+/** Days per engine month; what a script date's day is bounded by. */
+export const ENGINE_MONTH_DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+
+export const GREGORIAN_MONTHS: string[] = [
   "January",
   "February",
   "March",
@@ -45,9 +45,10 @@ export const GREGORIAN_MONTHS: CalendarMonth[] = [
   "October",
   "November",
   "December",
-].map((name, i) => ({ name, days: DAYS[i] }));
+];
 
-export function monthsOf(cal: CalendarSetting): CalendarMonth[] {
+/** The month names a date reads with: the mod's twelve, or the engine's. */
+export function monthNames(cal: CalendarSetting): string[] {
   return cal.months ?? GREGORIAN_MONTHS;
 }
 
@@ -69,17 +70,19 @@ export function sanitizeCalendar(raw: unknown): CalendarSetting | undefined {
   // 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) {
-    const months: CalendarMonth[] = [];
+    // 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 !== GREGORIAN_MONTHS.length) return undefined;
+    const months: string[] = [];
     const seen = new Set<string>();
     for (const m of o.months) {
-      if (typeof m !== "object" || m === null) return undefined;
-      const { name, days } = m as Record<string, unknown>;
+      const name = typeof m === "string" ? m : ((m as Record<string, unknown> | null)?.name ?? null);
       if (typeof name !== "string" || name.trim() === "") return undefined;
-      if (typeof days !== "number" || !Number.isInteger(days) || days < 1 || days > 999) return undefined;
       const key = name.trim().toLowerCase();
       if (seen.has(key)) return undefined;
       seen.add(key);
-      months.push({ name: name.trim(), days });
+      months.push(name.trim());
     }
     cal.months = months;
   }
@@ -93,10 +96,9 @@ export function parseScriptDate(text: string): { y: number; m: number; d: number
   return { y: Number(match[1]), m: Number(match[2]), d: Number(match[3]) };
 }
 
-/** Month/day within the calendar's bounds (year just has to be positive). */
-export function isValidScriptDate(cal: CalendarSetting, y: number, m: number, d: number): boolean {
-  const months = monthsOf(cal);
-  return y >= 1 && m >= 1 && m <= months.length && d >= 1 && d <= months[m - 1].days;
+/** A date the engine reads: a positive year, one of its twelve months, a day that month has. */
+export function isValidScriptDate(y: number, m: number, d: number): boolean {
+  return y >= 1 && m >= 1 && m <= ENGINE_MONTH_DAYS.length && d >= 1 && d <= ENGINE_MONTH_DAYS[m - 1];
 }
 
 /** Era-mapped year: "1000 BC". Null for pre-epoch years of a single-era calendar. */
@@ -111,11 +113,11 @@ export function displayYear(cal: CalendarSetting, y: number): string | null {
  * date does not fit the calendar.
  */
 export function displayDate(cal: CalendarSetting, y: number, m: number, d: number): string | null {
-  if (!isValidScriptDate(cal, y, m, d)) return null;
+  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} ${monthsOf(cal)[m - 1].name} ${year}`;
+  return `${d} ${monthNames(cal)[m - 1]} ${year}`;
 }
 
 export type ConvertResult = { ok: true; script: string; display: string } | { ok: false; error: string };
@@ -123,12 +125,10 @@ export type ConvertResult = { ok: true; script: string; display: string } | { ok
 /** Case-insensitive month lookup: exact name, else unique prefix. */
 function monthByName(cal: CalendarSetting, text: string): number | null {
   const needle = text.toLowerCase();
-  const months = monthsOf(cal);
-  const exact = months.findIndex((m) => m.name.toLowerCase() === needle);
+  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.name.toLowerCase().startsWith(needle));
+  const prefixed = months.map((m, i) => ({ m, i })).filter(({ m }) => m.toLowerCase().startsWith(needle));
   return prefixed.length === 1 ? prefixed[0].i + 1 : null;
 }
 
@@ -174,11 +174,10 @@ export function convertDisplayInput(cal: CalendarSetting, input: string): Conver
   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(cal, y, m, d)) {
-    const months = monthsOf(cal);
-    return m >= 1 && m <= months.length
-      ? { ok: false, error: `${months[m - 1].name} has ${months[m - 1].days} days` }
-      : { ok: false, error: `this calendar has ${months.length} months` };
+  if (!isValidScriptDate(y, m, d)) {
+    return m >= 1 && m <= ENGINE_MONTH_DAYS.length
+      ? { ok: false, error: `${monthNames(cal)[m - 1]} has ${ENGINE_MONTH_DAYS[m - 1]} days` }
+      : { ok: false, error: `the game has ${ENGINE_MONTH_DAYS.length} months` };
   }
   return { ok: true, script: `${y}.${m}.${d}`, display: displayDate(cal, y, m, d)! };
 }

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

@@ -10,7 +10,6 @@
  * from the GameProfile, so no game knowledge lives here.
  */
 import type { CalendarSetting } from "./calendar";
-import { monthsOf } from "./calendar";
 
 /**
  * The loc keys a game formats dates through, verified against the game's
@@ -128,24 +127,18 @@ export function generateCalendarLoc(
   }
 
   if (cal.months) {
-    const months = monthsOf(cal);
+    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 if (months.length !== spec.monthKeys.length) {
-      notes.push(
-        `The engine has exactly ${spec.monthKeys.length} months; your calendar declares ${months.length}, ` +
-          "so month names were not generated (the month count itself cannot be modded)."
-      );
     } 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).");
-      months.forEach((m, i) => {
-        const [long, short] = spec.monthKeys![i];
-        overrideLines.push(` ${long}:0 "${m.name.replace(/"/g, '\\"')}"`);
-        if (short !== long) overrideLines.push(` ${short}:0 "${m.name.replace(/"/g, '\\"')}"`);
+      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(
-        "Month day counts are engine-fixed (31/28/31...); custom day counts only affect the editor's display."
-      );
     }
   }
 

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;
+  }
+}