@px-lsp/protocol 0.1.0 → 0.2.0

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,69 @@
+/**
+ * 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 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;
+    /** 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;
+    /** Custom month names and day counts, first month first. Omitted = the
+     * standard 12 months (Feb 28: the engine has no leap years). */
+    months?: CalendarMonth[];
+}
+export declare const GREGORIAN_MONTHS: CalendarMonth[];
+export declare function monthsOf(cal: CalendarSetting): CalendarMonth[];
+/**
+ * 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;
+/** Month/day within the calendar's bounds (year just has to be positive). */
+export declare function isValidScriptDate(cal: CalendarSetting, 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,183 @@
+"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 = void 0;
+exports.monthsOf = monthsOf;
+exports.sanitizeCalendar = sanitizeCalendar;
+exports.parseScriptDate = parseScriptDate;
+exports.isValidScriptDate = isValidScriptDate;
+exports.displayYear = displayYear;
+exports.displayDate = displayDate;
+exports.convertDisplayInput = convertDisplayInput;
+const 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",
+].map((name, i) => ({ name, days: DAYS[i] }));
+function monthsOf(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) {
+        const months = [];
+        const seen = new Set();
+        for (const m of o.months) {
+            if (typeof m !== "object" || m === null)
+                return undefined;
+            const { name, days } = m;
+            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 });
+        }
+        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]) };
+}
+/** Month/day within the calendar's bounds (year just has to be positive). */
+function isValidScriptDate(cal, y, m, d) {
+    const months = monthsOf(cal);
+    return y >= 1 && m >= 1 && m <= months.length && d >= 1 && d <= months[m - 1].days;
+}
+/** 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(cal, 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}`;
+}
+/** Case-insensitive month lookup: exact name, else unique prefix. */
+function monthByName(cal, text) {
+    const needle = text.toLowerCase();
+    const months = monthsOf(cal);
+    const exact = months.findIndex((m) => m.name.toLowerCase() === needle);
+    if (exact >= 0)
+        return exact + 1;
+    const prefixed = months
+        .map((m, i) => ({ m, i }))
+        .filter(({ m }) => m.name.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(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` };
+    }
+    return { ok: true, script: `${y}.${m}.${d}`, display: displayDate(cal, y, m, d) };
+}

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,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CAL_ERA_KEY = exports.CAL_YEAR_KEY = void 0;
+exports.generateCalendarLoc = generateCalendarLoc;
+const calendar_1 = require("./calendar");
+/** 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 = (0, calendar_1.monthsOf)(cal);
+        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 {
+            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, '\\"')}"`);
+            });
+            notes.push("Month day counts are engine-fixed (31/28/31...); custom day counts only affect the editor's display.");
+        }
+    }
+    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/descriptorMod.d.ts

@@ -53,6 +53,11 @@ export declare function validateDescriptor(text: string, opts: {
  * something comes from ("Community Flavor Pack") instead of a generic "mod".
  */
 export declare function readDescriptorName(dir: string): string | null;
+/**
+ * The quoted strings inside a top-level `<key>={ "A" "B" }` block of a .mod
+ * text, in file order; empty when the block is missing.
+ */
+export declare function readDescriptorBlock(text: string, key: string): string[];
 /**
  * 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
@@ -60,6 +65,22 @@ export declare function readDescriptorName(dir: string): string | null;
  * Workshop id, so that is what the caller compares them with.
  */
 export declare function readDescriptorDependencies(dir: string): string[];
+/**
+ * `text` with the top-level `key="value"` entry replaced, or appended when the
+ * key is absent. Only scalar entries: a key whose value is a block is left
+ * alone and the entry is appended instead. Line endings and a leading BOM
+ * survive untouched; the appended line follows the file's dominant EOL.
+ * The value is made descriptor-safe like upsertDescriptorBlock's quoting:
+ * the format has no escape, so double quotes become apostrophes and line
+ * breaks collapse to one space.
+ */
+export declare function upsertDescriptorValue(text: string, key: string, value: string): string;
+/**
+ * `text` with the top-level `key={...}` block replaced by one holding exactly
+ * `values` (quoted, tab-indented, the file's EOL), or appended when absent.
+ * Descriptor blocks are flat, so the block ends at the first `}`-only line.
+ */
+export declare function upsertDescriptorBlock(text: string, key: string, values: string[]): string;
 /** "1.19.0.6" -> "1.19.*" (the wildcard form that survives hotfixes). */
 export declare function wildcardVersion(raw: string): string | null;
 /** A launcher-correct starter descriptor.mod. */

package/dist/descriptorMod.js

@@ -37,7 +37,10 @@ exports.LAUNCHER_TAGS = exports.DESCRIPTOR_FIELD_MAP = exports.DESCRIPTOR_FIELDS
 exports.parseDescriptor = parseDescriptor;
 exports.validateDescriptor = validateDescriptor;
 exports.readDescriptorName = readDescriptorName;
+exports.readDescriptorBlock = readDescriptorBlock;
 exports.readDescriptorDependencies = readDescriptorDependencies;
+exports.upsertDescriptorValue = upsertDescriptorValue;
+exports.upsertDescriptorBlock = upsertDescriptorBlock;
 exports.wildcardVersion = wildcardVersion;
 exports.scaffoldDescriptor = scaffoldDescriptor;
 /**
@@ -296,6 +299,17 @@ function readDescriptorName(dir) {
     const value = entry.value.replace(/^"([^]*)"$/, "$1").trim();
     return value === "" ? null : value;
 }
+/**
+ * The quoted strings inside a top-level `<key>={ "A" "B" }` block of a .mod
+ * text, in file order; empty when the block is missing.
+ */
+function readDescriptorBlock(text, key) {
+    // Comments first: a commented-out entry is not an entry.
+    const block = new RegExp(`(?:^|\\n)[ \\t]*${key}[ \\t]*=[ \\t]*\\{([^}]*)\\}`).exec(text.replace(/#[^\n]*/g, ""));
+    if (!block)
+        return [];
+    return [...block[1].matchAll(/"([^"]*)"/g)].map((m) => m[1].trim()).filter((s) => s !== "");
+}
 /**
  * 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
@@ -310,11 +324,53 @@ function readDescriptorDependencies(dir) {
     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 !== "");
+    return readDescriptorBlock(text, "dependencies");
+}
+/**
+ * `text` with the top-level `key="value"` entry replaced, or appended when the
+ * key is absent. Only scalar entries: a key whose value is a block is left
+ * alone and the entry is appended instead. Line endings and a leading BOM
+ * survive untouched; the appended line follows the file's dominant EOL.
+ * The value is made descriptor-safe like upsertDescriptorBlock's quoting:
+ * the format has no escape, so double quotes become apostrophes and line
+ * breaks collapse to one space.
+ */
+function upsertDescriptorValue(text, key, value) {
+    const v = value.replace(/"/g, "'").replace(/\s*\r?\n\s*/g, " ");
+    const entry = parseDescriptor(text).find((e) => e.key === key && e.value !== "");
+    if (entry) {
+        const lines = text.split(/(\r?\n)/); // keep separators at odd indices
+        const idx = entry.line * 2;
+        lines[idx] = lines[idx].replace(/=\s*("[^"]*"|\S+)([ \t]*(#.*)?)$/, (_m, _old, tail) => `="${v}"${tail}`);
+        return lines.join("");
+    }
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    const sep = text === "" || text.endsWith("\n") ? "" : eol;
+    return `${text}${sep}${key}="${v}"${eol}`;
+}
+/**
+ * `text` with the top-level `key={...}` block replaced by one holding exactly
+ * `values` (quoted, tab-indented, the file's EOL), or appended when absent.
+ * Descriptor blocks are flat, so the block ends at the first `}`-only line.
+ */
+function upsertDescriptorBlock(text, key, values) {
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    const q = (v) => `"${v.replace(/"/g, "'")}"`;
+    const block = [`${key}={`, ...values.map((v) => `\t${q(v)}`), `}`].join(eol);
+    const lines = text.split(/\r?\n/);
+    const open = lines.findIndex((l) => new RegExp(`^\\s*${key}\\s*=\\s*\\{`).test(l));
+    if (open >= 0) {
+        let close = open;
+        // A one-line block (`tags={ "x" }`) closes on its own line.
+        if (!/\}\s*(#.*)?$/.test(lines[open])) {
+            while (close < lines.length - 1 && !/^\s*\}\s*(#.*)?$/.test(lines[close]))
+                close++;
+        }
+        lines.splice(open, close - open + 1, block);
+        return lines.join(eol);
+    }
+    const sep = text === "" || text.endsWith("\n") ? "" : eol;
+    return `${text}${sep}${block}${eol}`;
 }
 /** "1.19.0.6" -> "1.19.*" (the wildcard form that survives hotfixes). */
 function wildcardVersion(raw) {

package/dist/kinds.d.ts

@@ -0,0 +1,72 @@
+/**
+ * One kind map, four surfaces.
+ *
+ * Every place the product names a concept - the hover badge, the completion
+ * list icon, the tree leaf, the breadcrumb/outline entry - reads its glyph from
+ * here, so a trigger looks like a trigger everywhere.
+ *
+ * The colour is not a second decision. VS Code paints a completion row from the
+ * `symbolIcon.*Foreground` token of the `CompletionItemKind` we send, and we
+ * cannot override it, so the kind IS the colour. The hover badge reuses that
+ * same token, which is why there is no colour column to keep in sync. Four
+ * groups come out of that, and choosing the kind is choosing the group:
+ *
+ *   purple   asks a question        Method
+ *   orange   makes it happen        Class, Event, Enum, Value
+ *   blue     you stored it          Variable, Field, Interface, EnumMember
+ *   grey     syntax, everything else  all the rest
+ *
+ * Three facts shape the table and are easy to re-break:
+ *
+ *  1. **Codicon aliases collapse.** `symbol-method`, `symbol-function` and
+ *     `symbol-constructor` are one codepoint, so they are one picture. Same for
+ *     `symbol-enum`/`symbol-value`, `symbol-key`/`symbol-text`,
+ *     `symbol-struct`/`symbol-structure`, `symbol-unit`/`symbol-ruler` and
+ *     `symbol-type-parameter`/`symbol-parameter`. Check a proposed mapping
+ *     against codepoints, not against the names. Prefer the canonical name of a
+ *     pair: only it carries the `symbolIcon.*Foreground` rule, so a themed tree
+ *     leaf tints and an alias does not.
+ *  2. **Only `CompletionItemKind` reaches the suggest widget.** 25 values,
+ *     22 distinct pictures after the collapse. A concept that appears in a
+ *     completion list cannot use a glyph from outside that set in the list,
+ *     even though the hover and the tree can draw all 461 codicons.
+ *  3. **Only `SymbolKind` reaches the outline.** Breadcrumbs, the outline,
+ *     sticky scroll and Ctrl+T take an LSP `SymbolKind`, and VS Code draws
+ *     member `X` with the codicon `symbol-<kebab X>`. `symbolKind` names the
+ *     member drawing the same picture as `codicon`, so the breadcrumb bar and
+ *     the hover badge cannot disagree; it is null for a picture no member
+ *     draws. The server resolves the name to the numeric enum.
+ *
+ * `codicon`, `completionKind` and `symbolKind` are separate fields for exactly
+ * that reason. They name the same picture everywhere except two entries:
+ * `texture`, whose `file-media` glyph no completion kind can produce, and
+ * `list`, whose array glyph no *free* completion kind can produce (the colour
+ * has to stay blue, and all four blue kinds are taken), so the suggest widget
+ * alone still draws it as an enum member.
+ *
+ * Uniqueness is promised *within a completion list*, not globally: script, gui
+ * and datafunction completions never appear together, so they may share glyphs.
+ *
+ * No imports: this is shared by the server and the VS Code client.
+ */
+export interface KindStyle {
+    /** Codicon id, drawn in the hover badge and the tree. */
+    codicon: string;
+    /** `CompletionItemKind` member name; the server maps it to the enum. */
+    completionKind: string;
+    /**
+     * `SymbolKind` member name drawing the same picture as `codicon`, or null
+     * when no member draws it. The server maps it to the enum.
+     */
+    symbolKind: string | null;
+    /** Hover badge colour as a `--vscode-symbolIcon-*` var, or null for none. */
+    color: string | null;
+}
+/** Anything the map does not name: a definition we have no opinion about. */
+export declare const DEFAULT_KIND_STYLE: KindStyle;
+/** Glyph, completion kind and badge colour for a kind name. Never throws. */
+export declare function kindStyle(kind: string): KindStyle;
+/** True when the map has an opinion, i.e. the kind is not falling through. */
+export declare function hasKindStyle(kind: string): boolean;
+/** Every mapped kind, for the coverage test that keeps this table honest. */
+export declare function mappedKinds(): string[];