@px-lsp/protocol 0.1.0 → 0.2.1

package/dist/configDir.js

@@ -0,0 +1,79 @@
+"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.PX_CONFIG_DIR = void 0;
+exports.resolveConfigDir = resolveConfigDir;
+exports.migrateConfigDir = migrateConfigDir;
+/**
+ * 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.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+exports.PX_CONFIG_DIR = ".px-toolkit";
+/**
+ * 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.
+ */
+function resolveConfigDir(root, names) {
+    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.
+ */
+function migrateConfigDir(root, names) {
+    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/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[];

package/dist/kinds.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_KIND_STYLE = void 0;
+exports.kindStyle = kindStyle;
+exports.hasKindStyle = hasKindStyle;
+exports.mappedKinds = mappedKinds;
+/**
+ * The `SymbolKind` member VS Code draws with each picture the table uses. VS
+ * Code renders member `X` as `symbol-<kebab X>`, so this is that rule read
+ * backwards, with the alias pairs resolved to the member owning the codepoint
+ * (`symbol-value` is `symbol-enum`, `symbol-text` is `symbol-key`). A codicon
+ * absent here has no `SymbolKind` at all: there are 26 members against 461
+ * codicons.
+ */
+const SYMBOL_KIND_BY_CODICON = {
+    "symbol-array": "Array",
+    "symbol-class": "Class",
+    "symbol-constant": "Constant",
+    "symbol-enum-member": "EnumMember",
+    "symbol-event": "Event",
+    "symbol-field": "Field",
+    "symbol-interface": "Interface",
+    "symbol-method": "Method",
+    "symbol-module": "Module",
+    "symbol-operator": "Operator",
+    "symbol-property": "Property",
+    "symbol-struct": "Struct",
+    "symbol-text": "Key",
+    "symbol-type-parameter": "TypeParameter",
+    "symbol-value": "Enum",
+    "symbol-variable": "Variable",
+};
+/**
+ * The only completion kinds VS Code tints; the other 15 render in the plain
+ * editor foreground, so their badge emits no span at all.
+ */
+const TINT = {
+    Method: "method",
+    Function: "function",
+    Constructor: "constructor",
+    Class: "class",
+    Enum: "enumerator",
+    Value: "enumerator",
+    Event: "event",
+    Variable: "variable",
+    Field: "field",
+    Interface: "interface",
+    EnumMember: "enumeratorMember",
+};
+/**
+ * `colorFrom` defaults to the completion kind, which is what keeps the badge
+ * and the row the same colour. `on_action` is the one entry that overrides it:
+ * it wants the interface glyph with the orange of the group it belongs to, and
+ * a completion row cannot have both.
+ */
+const c = (codicon, completionKind, colorFrom = completionKind) => ({
+    codicon,
+    completionKind,
+    symbolKind: SYMBOL_KIND_BY_CODICON[codicon] ?? null,
+    color: TINT[colorFrom] ? `var(--vscode-symbolIcon-${TINT[colorFrom]}Foreground)` : null,
+});
+const SCRIPT = {
+    // purple: asks a question.
+    trigger: c("symbol-method", "Method"),
+    scripted_trigger: c("symbol-method", "Method"),
+    datafn: c("symbol-method", "Method"),
+    // orange: makes it happen.
+    effect: c("symbol-event", "Event"),
+    scripted_effect: c("symbol-event", "Event"),
+    event: c("symbol-class", "Class"),
+    decision: c("symbol-class", "Class"),
+    gui_type: c("symbol-class", "Class"),
+    data_type: c("symbol-class", "Class"),
+    on_action: c("symbol-interface", "Interface", "Class"),
+    trait: c("symbol-value", "Value"),
+    // blue: you stored it. A name that resolves to a scope or a stored value.
+    variable: c("symbol-variable", "Variable"),
+    local_variable: c("symbol-variable", "Variable"),
+    global_variable: c("symbol-variable", "Variable"),
+    promote: c("symbol-variable", "Variable"),
+    saved_scope: c("symbol-field", "Field"),
+    event_target: c("symbol-interface", "Interface"),
+    // The four list kinds each get their own picture. `add_to_list` builds a
+    // collection that lives for one effect block and is never saved, so it takes
+    // the array picture; the three `*_variable_list` kinds are entries in
+    // variable storage, split by storage class: the object-attached one keeps
+    // the enum-member picture, the event-chain-local one the plain list, the
+    // game-global one the globe.
+    // All four stay on `EnumMember`: the four blue completion kinds are already
+    // spoken for by variable, saved_scope and event_target, so the suggest widget
+    // draws every list as one blue enum-member row; the split shows in the hover
+    // badge and the tree. Of the four pictures only `symbol-enum-member` carries
+    // a `symbolIcon` colour rule, so the other three render tree leaves in the
+    // plain icon foreground while their badges stay blue (the map emits the
+    // colour); `list-unordered` and `globe` are pictures no SymbolKind draws, so
+    // those two fall back to Object in symbol lists.
+    list: c("symbol-array", "EnumMember"),
+    variable_list: c("symbol-enum-member", "EnumMember"),
+    local_variable_list: c("list-unordered", "EnumMember"),
+    global_variable_list: c("globe", "EnumMember"),
+    // grey: syntax and everything else.
+    scope_word: c("symbol-constant", "Constant"),
+    structure_key: c("symbol-struct", "Struct"),
+    descriptor_field: c("symbol-struct", "Struct"),
+    keyword: c("symbol-keyword", "Keyword"),
+    modifier: c("symbol-property", "Property"),
+    scripted_modifier: c("symbol-property", "Property"),
+    gui_property: c("symbol-property", "Property"),
+    script_value: c("symbol-operator", "Operator"),
+    define: c("symbol-unit", "Unit"),
+    namespace: c("symbol-module", "Module"),
+    loc_key: c("symbol-text", "Text"),
+    macro_param: c("symbol-type-parameter", "TypeParameter"),
+    text_format: c("symbol-color", "Color"),
+    gui_enum_value: c("symbol-constant", "Constant"),
+    format_suffix: c("symbol-constant", "Constant"),
+    gui_template: c("symbol-snippet", "Snippet"),
+    // The picture-frame glyph no completion kind can draw: the hover and the tree
+    // get `file-media`, the completion row falls back to the plain file glyph.
+    texture: c("file-media", "File"),
+};
+/** Anything the map does not name: a definition we have no opinion about. */
+exports.DEFAULT_KIND_STYLE = c("go-to-file", "Reference");
+/** Glyph, completion kind and badge colour for a kind name. Never throws. */
+function kindStyle(kind) {
+    return SCRIPT[kind] ?? exports.DEFAULT_KIND_STYLE;
+}
+/** True when the map has an opinion, i.e. the kind is not falling through. */
+function hasKindStyle(kind) {
+    return Object.prototype.hasOwnProperty.call(SCRIPT, kind);
+}
+/** Every mapped kind, for the coverage test that keeps this table honest. */
+function mappedKinds() {
+    return Object.keys(SCRIPT);
+}