@neontechspace/fluxerly 1000.0.0-nightly.12

package/dist/internal/sharding.js

@@ -0,0 +1,205 @@
+/**
+ * Shard plan: Validation of the fixed local shard assignment, automatic plan sizing, scaling hooks and guild-to-shard
+ * routing.
+ * Invariant: A plan is immutable once known and decides guild ownership, never cache contents or discovery hints. An
+ * automatic plan is computed at the first connect from the bot's guild count, and omitted settings start with one shard.
+ * The client replaces either with a new, larger automatic plan only when Fluxer closes a shard with 4011 (sharding
+ * required), and an explicit plan never changes.
+ * Implements [SDK contracts: Connection and recovery](/docs/SDK-CONTRACTS.md#connection-and-recovery)
+ */
+import { ConfigurationError } from "#sdk/errors";
+import { settingError } from "./client/configuration-fields.js";
+import { record } from "./decode/primitives.js";
+import { maxGuildsPerShard, sessionRetentionMs } from "./protocol/gateway.js";
+import { unsupportedKeyHint } from "./suggest.js";
+/** Largest total shard count Fluxer accepts */
+export const maximumShardCount = 16_384;
+/**
+ * Average guilds per shard that automatic sharding aims for, four fifths of Fluxer's per-shard ceiling.
+ * Fluxer counts the guilds routed to each shard, not the average. The validate_session_guild_count function in
+ * fluxer_gateway/src/gateway/gateway_sharding.erl at fluxerapp/fluxer commit 858a2d9e2b987330edd81711bb53e4f7edc0bbcc
+ * rejects Identify with 4011 when one shard's own guilds exceed 2,500. Routing by (id >> 22) % totalShards is uneven,
+ * so a plan sized to the ceiling almost always overfills a shard above about 20,000 guilds. At 2,000 the fullest of
+ * 16,384 shards stays near 2,200 and leaves room for growth before a 4011 closure makes the client move to a larger plan
+ */
+export const guildsPerShard = (maxGuildsPerShard * 4) / 5;
+const defaultShardPlan = immutablePlan(1, [0]);
+const defaultSharding = Object.freeze({
+    plan: defaultShardPlan,
+    reshard: true,
+    identify: undefined,
+    sessions: undefined,
+    refillCaches: true,
+});
+function hook(value, field, methods) {
+    if (value === undefined)
+        return undefined;
+    // Methods may come from a class prototype, and other members such as a store's own state are left alone
+    if (!record(value) || methods.some((method) => typeof value[method] !== "function"))
+        return settingError(field, field === "identify"
+            ? 'The option "sharding.identify" must be an object with a permit function'
+            : 'The option "sharding.sessions" must be an object with load and save functions');
+    // Bind the methods now so later caller mutation cannot change the hooks this client calls
+    return Object.freeze(Object.fromEntries(methods.map((method) => [method, value[method].bind(value)])));
+}
+/** Validate and copy the one-time sharding settings without changing caller-owned input */
+export function parseSharding(input) {
+    if (input === undefined)
+        return defaultSharding;
+    if (input === "auto")
+        return Object.freeze({
+            plan: "auto",
+            reshard: true,
+            identify: undefined,
+            sessions: undefined,
+            refillCaches: true,
+        });
+    if (!record(input))
+        return new ConfigurationError("sharding", 'Sharding settings must be an object or "auto"');
+    const shardingKeys = ["totalShards", "shardIds", "identify", "sessions", "refillCaches"];
+    const unsupported = Reflect.ownKeys(input).find((key) => typeof key !== "string" || !shardingKeys.includes(key));
+    if (unsupported !== undefined)
+        return new ConfigurationError("sharding", typeof unsupported === "string"
+            ? `Unsupported sharding setting ${JSON.stringify(unsupported)}`
+            : "Sharding settings must not contain symbol keys", { hint: unsupportedKeyHint(typeof unsupported === "string" ? unsupported : "", shardingKeys, "settings") });
+    const identify = hook(input.identify, "identify", ["permit"]);
+    if (identify instanceof ConfigurationError)
+        return identify;
+    const sessions = hook(input.sessions, "sessions", ["load", "save"]);
+    if (sessions instanceof ConfigurationError)
+        return sessions;
+    const refillCaches = input.refillCaches ?? true;
+    if (typeof refillCaches !== "boolean")
+        return new ConfigurationError("sharding", 'The option "sharding.refillCaches" must be a boolean');
+    const hooks = {
+        identify: identify,
+        sessions: sessions,
+        refillCaches,
+    };
+    const totalShards = input.totalShards;
+    if (totalShards === "auto") {
+        if (input.shardIds !== undefined)
+            return new ConfigurationError("shardIds", "Automatic sharding assigns every shard, so omit sharding.shardIds", {
+                hint: "Set sharding.totalShards to a number to run only some shards",
+            });
+        return Object.freeze({ plan: "auto", reshard: true, ...hooks });
+    }
+    if (typeof totalShards !== "number" ||
+        !Number.isSafeInteger(totalShards) ||
+        totalShards < 1 ||
+        totalShards > maximumShardCount) {
+        return new ConfigurationError("totalShards", 'The option "sharding.totalShards" must be "auto" or an integer from 1 through 16,384');
+    }
+    const inputShardIds = input.shardIds;
+    if (inputShardIds === undefined) {
+        return Object.freeze({
+            plan: immutablePlan(totalShards, Array.from({ length: totalShards }, (_, shardId) => shardId)),
+            reshard: false,
+            ...hooks,
+        });
+    }
+    if (!Array.isArray(inputShardIds) || inputShardIds.length === 0)
+        return new ConfigurationError("shardIds", 'The option "sharding.shardIds" must be a non-empty array');
+    const shardIds = [];
+    const seen = new Set();
+    for (const shardId of inputShardIds) {
+        if (typeof shardId !== "number" ||
+            !Number.isSafeInteger(shardId) ||
+            shardId < 0 ||
+            shardId >= totalShards ||
+            seen.has(shardId)) {
+            return new ConfigurationError("shardIds", `The option "sharding.shardIds" must contain unique integers from 0 through ${totalShards - 1}`);
+        }
+        seen.add(shardId);
+        shardIds.push(shardId);
+    }
+    return Object.freeze({ plan: immutablePlan(totalShards, shardIds), reshard: false, ...hooks });
+}
+/** The plan automatic sharding picks for a guild count: Every shard, at most guildsPerShard guilds each on average */
+export function automaticShardPlan(guildCount) {
+    return fullShardPlan(Math.min(maximumShardCount, Math.max(1, Math.ceil(guildCount / guildsPerShard))));
+}
+/**
+ * The plan an automatic client moves to after Fluxer closed one of its shards with 4011 (sharding required): The plan
+ * for the new guild count, or one shard more than before when that count still fits the old total, because Fluxer
+ * found a shard above its ceiling whatever the average. Callers check that the old total is below maximumShardCount
+ */
+export function largerShardPlan(guildCount, previousTotalShards) {
+    const counted = automaticShardPlan(guildCount);
+    return counted.totalShards > previousTotalShards
+        ? counted
+        : fullShardPlan(Math.min(maximumShardCount, previousTotalShards + 1));
+}
+/** Moves to a larger automatic plan allowed within reshardWindowMs, for a client or a supervisor */
+const reshardLimit = 3;
+const reshardWindowMs = 3_600_000;
+/**
+ * Admit a move to a larger automatic plan at now, recording it in history, or return why it is refused: The plan
+ * already has the largest total, or reshardLimit moves happened within reshardWindowMs. The history keeps only moves
+ * inside the window
+ */
+export function admitReshard(history, now, totalShards) {
+    if (totalShards >= maximumShardCount)
+        return `the plan already has the largest total of ${maximumShardCount.toLocaleString("en-US")} shards`;
+    const recent = history.filter((at) => now - at < reshardWindowMs);
+    history.splice(0, history.length, ...recent);
+    if (history.length >= reshardLimit)
+        return `it already moved to a larger plan ${reshardLimit} times within an hour`;
+    history.push(now);
+    return undefined;
+}
+/** A plan of totalShards shards, all owned by this client */
+function fullShardPlan(totalShards) {
+    return immutablePlan(totalShards, Array.from({ length: totalShards }, (_, shardId) => shardId));
+}
+/** Route a guild snowflake to its planned shard. Callers provide a validated plan total */
+export function guildShardId(guildId, totalShards) {
+    return Number((BigInt(guildId) >> 22n) % BigInt(totalShards));
+}
+function immutablePlan(totalShards, shardIds) {
+    return Object.freeze({
+        totalShards,
+        shardIds: Object.freeze([...shardIds]),
+        identifyShards: totalShards > 1,
+    });
+}
+/** Allowed clock difference between the process that saved a snapshot and the one loading it */
+const snapshotClockSkewMs = 5_000;
+/** Check a loaded snapshot: The frozen copy to resume, or why it cannot be resumed */
+export function checkSnapshot(value, gatewayUrl, totalShards, nowMs) {
+    if (!record(value) ||
+        typeof value.sessionId !== "string" ||
+        value.sessionId.length === 0 ||
+        value.sessionId.length > 256 ||
+        typeof value.sequence !== "number" ||
+        !Number.isSafeInteger(value.sequence) ||
+        value.sequence < 0 ||
+        typeof value.resumeUrl !== "string" ||
+        typeof value.savedAt !== "number" ||
+        !Number.isSafeInteger(value.savedAt) ||
+        typeof value.totalShards !== "number" ||
+        !Number.isSafeInteger(value.totalShards) ||
+        value.totalShards < 1)
+        return { problem: "the snapshot is malformed" };
+    const age = nowMs - value.savedAt;
+    if (age >= sessionRetentionMs)
+        return { problem: "the snapshot is older than Fluxer's 60-second resume window" };
+    if (age < -snapshotClockSkewMs)
+        return { problem: "the snapshot was saved in the future" };
+    // Resume sends the token, so it only goes to the gateway this client discovered itself
+    if (value.resumeUrl !== gatewayUrl)
+        return { problem: "the snapshot belongs to a different gateway endpoint" };
+    // Fluxer binds a session to the shard tuple it identified with, so resuming it under another plan routes guilds to the wrong shard
+    if (value.totalShards !== totalShards)
+        return { problem: "the snapshot belongs to a different shard plan" };
+    return {
+        snapshot: Object.freeze({
+            sessionId: value.sessionId,
+            sequence: value.sequence,
+            resumeUrl: value.resumeUrl,
+            savedAt: value.savedAt,
+            totalShards: value.totalShards,
+        }),
+    };
+}
+//# sourceMappingURL=sharding.js.map

package/dist/internal/sharding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharding.js","sourceRoot":"","sources":["../../src/internal/sharding.ts"],"names":[],"mappings":"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"}

package/dist/internal/starter-project.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Writes a ready-to-run starter bot project for `fluxerly init`, in JavaScript, TypeScript or TypeScript with the
+ * native Effect API.
+ * Invariant: Existing files are never replaced. A conflict writes nothing, and a failed write removes only the files
+ * this run created. Two files are no conflict. An existing .env is kept, because it holds the bot's own token, and an
+ * existing .gitignore is kept with only its missing starter lines appended, last, after every other file is written.
+ * Each bot's handlers match its shipped starter in examples/starter
+ */
+/** The starters init writes, in the order the prompt offers them */
+export declare const starterTemplates: readonly ["js", "ts", "effect"];
+export type StarterTemplate = (typeof starterTemplates)[number];
+/** Thrown when a file that init writes already exists. Nothing was written */
+export declare class StarterConflictError extends Error {
+    readonly conflicts: readonly string[];
+    readonly name = "StarterConflictError";
+    constructor(conflicts: readonly string[]);
+}
+/** What one run of writeStarterProject changed */
+export interface StarterResult {
+    /** The files this run created, in the order it wrote them */
+    readonly written: readonly string[];
+    /** The lines this run appended to an existing .gitignore. None when it had them all or did not exist */
+    readonly ignored: readonly string[];
+}
+/** Write a starter project into `project` and report what changed, or throw StarterConflictError */
+export declare function writeStarterProject(project: string, packageRoot: string, template?: StarterTemplate): StarterResult;
+//# sourceMappingURL=starter-project.d.ts.map

package/dist/internal/starter-project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"starter-project.d.ts","sourceRoot":"","sources":["../../src/internal/starter-project.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,oEAAoE;AACpE,eAAO,MAAM,gBAAgB,YAAI,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAU,CAAA;AAC/D,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAA;AAK/D,8EAA8E;AAC9E,qBAAa,oBAAqB,SAAQ,KAAK;IAE/B,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE;IADjD,SAAkB,IAAI,0BAAyB;IAC/C,YAAqB,SAAS,EAAE,SAAS,MAAM,EAAE,EAEhD;CACJ;AA+JD,kDAAkD;AAClD,MAAM,WAAW,aAAa;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,wGAAwG;IACxG,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACtC;AAeD,oGAAoG;AACpG,wBAAgB,mBAAmB,CAC/B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,GAAE,eAAsB,GACjC,aAAa,CAuCf"}

package/dist/internal/starter-project.js

@@ -0,0 +1,224 @@
+/**
+ * Writes a ready-to-run starter bot project for `fluxerly init`, in JavaScript, TypeScript or TypeScript with the
+ * native Effect API.
+ * Invariant: Existing files are never replaced. A conflict writes nothing, and a failed write removes only the files
+ * this run created. Two files are no conflict. An existing .env is kept, because it holds the bot's own token, and an
+ * existing .gitignore is kept with only its missing starter lines appended, last, after every other file is written.
+ * Each bot's handlers match its shipped starter in examples/starter
+ */
+import { appendFileSync, closeSync, existsSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { newAgentsFile } from "./agents-section.js";
+/** The starters init writes, in the order the prompt offers them */
+export const starterTemplates = ["js", "ts", "effect"];
+/** The lines the starter needs in .gitignore, so the token and the installed packages stay out of version control */
+const ignoredLines = ["node_modules", ".env"];
+/** Thrown when a file that init writes already exists. Nothing was written */
+export class StarterConflictError extends Error {
+    conflicts;
+    name = "StarterConflictError";
+    constructor(conflicts) {
+        super(`These files already exist: ${conflicts.join(", ")}`);
+        this.conflicts = conflicts;
+    }
+}
+const startComment = `// Running this file starts the bot, while importing it from a test does not.
+// A failure that stops the bot, such as a rejected token, is logged and sets a failing exit code`;
+// Each bot exports its options without the token, so its test can run them through createTestBot without a token or a
+// network. The events blocks match the shipped starters
+const javaScriptBot = `import { runBot } from "@neontechspace/fluxerly"
+
+export const bot = {
+    events: {
+        messageCreate: ({ message, reply }) => {
+            if (message.content !== "!ping") return
+            // Returning the reply reports a failed send to the log
+            return reply("Pong!")
+        },
+    },
+}
+
+${startComment}
+if (import.meta.main) await runBot({ token: process.env.FLUXER_BOT_TOKEN, ...bot })
+`;
+const typeScriptBot = `import { runBot, type BotOptions } from "@neontechspace/fluxerly"
+
+export const bot: Omit<BotOptions, "token"> = {
+    events: {
+        messageCreate: ({ message, reply }) => {
+            if (message.content !== "!ping") return
+            // Returning the reply reports a failed send to the log
+            return reply("Pong!")
+        },
+    },
+}
+
+${startComment}
+if (import.meta.main) await runBot({ token: process.env.FLUXER_BOT_TOKEN, ...bot })
+`;
+// satisfies keeps the handlers' own error and service types, which runBot and createTestBot read
+const effectBot = `import { Effect } from "effect"
+import { runBot, type BotOptions } from "@neontechspace/fluxerly/effect"
+
+export const bot = {
+    events: {
+        messageCreate: ({ message, reply }) => {
+            if (message.content !== "!ping") return Effect.void
+            // A failed reply is reported to the log without stopping the bot
+            return reply("Pong!")
+        },
+    },
+} satisfies Omit<BotOptions<unknown, unknown>, "token">
+
+${startComment}
+if (import.meta.main)
+    await Effect.runPromiseExit(runBot({ token: process.env.FLUXER_BOT_TOKEN, processSignals: true, ...bot }))
+`;
+const defaultTest = (botFile) => `import assert from "node:assert/strict"
+import { test } from "node:test"
+import { createTestBot } from "@neontechspace/fluxerly/testing"
+import { bot } from "./${botFile}"
+
+// createTestBot runs the bot against an in-memory Fluxer, so no token or network is needed
+test("the bot answers !ping with Pong! and ignores other messages", async () => {
+    await using testBot = createTestBot(bot)
+    await testBot.ready()
+
+    // The say method sends a message as a user and returns the messages the bot sent in response
+    assert.deepEqual((await testBot.say("!ping")).map((message) => message.content), ["Pong!"])
+    assert.deepEqual(await testBot.say("hello"), [])
+})
+`;
+const effectTest = `import assert from "node:assert/strict"
+import { test } from "node:test"
+import { Effect } from "effect"
+import { createTestBot } from "@neontechspace/fluxerly/effect/testing"
+import { bot } from "./bot.ts"
+
+// createTestBot runs the bot against an in-memory Fluxer, so no token or network is needed
+test("the bot answers !ping with Pong! and ignores other messages", async () => {
+    // Effect.scoped shuts the test bot down once the conversation ends
+    const { ping, hello } = await Effect.runPromise(
+        Effect.scoped(
+            Effect.gen(function* () {
+                const testBot = yield* createTestBot(bot)
+                yield* testBot.ready()
+                // The say method sends a message as a user and returns the messages the bot sent in response
+                return { ping: yield* testBot.say("!ping"), hello: yield* testBot.say("hello") }
+            }),
+        ),
+    )
+
+    assert.deepEqual(ping.map((message) => message.content), ["Pong!"])
+    assert.deepEqual(hello, [])
+})
+`;
+// Node.js runs .ts files directly by removing their types, so the scripts need no build step. Removing types checks
+// nothing, so a TypeScript starter also gets a check script that runs the compiler
+const packageJson = (botFile) => `${JSON.stringify({
+    private: true,
+    type: "module",
+    scripts: {
+        start: `node --env-file-if-exists=.env ${botFile}`,
+        test: "node --test",
+        ...(botFile.endsWith(".ts") ? { check: "tsc" } : {}),
+    },
+}, null, 2)}\n`;
+// TypeScript only checks the code, for editors and the check script. The last three settings keep it in a form Node.js
+// can run directly
+const tsconfig = `${JSON.stringify({
+    compilerOptions: {
+        target: "ES2024",
+        module: "NodeNext",
+        types: ["node"],
+        strict: true,
+        noEmit: true,
+        allowImportingTsExtensions: true,
+        verbatimModuleSyntax: true,
+        erasableSyntaxOnly: true,
+    },
+}, null, 4)}\n`;
+/** The files init writes for a template, in the order it reports them */
+function starterFiles(project, packageRoot, template) {
+    const shared = () => [
+        [".env.example", "FLUXER_BOT_TOKEN=\n"],
+        [".env", "FLUXER_BOT_TOKEN=\n"],
+        [".gitignore", `${ignoredLines.join("\n")}\n`],
+        ["AGENTS.md", newAgentsFile(project, packageRoot)],
+    ];
+    if (template === "js")
+        return new Map([
+            ["package.json", packageJson("bot.js")],
+            ["bot.js", javaScriptBot],
+            ["bot.test.js", defaultTest("bot.js")],
+            ...shared(),
+        ]);
+    return new Map([
+        ["package.json", packageJson("bot.ts")],
+        ["tsconfig.json", tsconfig],
+        ["bot.ts", template === "ts" ? typeScriptBot : effectBot],
+        ["bot.test.ts", template === "ts" ? defaultTest("bot.ts") : effectTest],
+        ...shared(),
+    ]);
+}
+/** Append the starter's lines that `file` lacks, keeping its content and line endings, and return the lines added */
+function addMissingIgnoredLines(file) {
+    const text = readFileSync(file, "utf8");
+    const present = new Set(text.split(/\r?\n/).map((line) => line.trim()));
+    const missing = ignoredLines.filter((line) => !present.has(line));
+    if (missing.length === 0)
+        return [];
+    const lineEnd = text.includes("\r\n") ? "\r\n" : "\n";
+    // A file that ends without a line break gets one first, so the added lines start on their own line
+    const lead = text === "" || text.endsWith("\n") ? "" : lineEnd;
+    appendFileSync(file, `${lead}${missing.map((line) => `${line}${lineEnd}`).join("")}`);
+    return missing;
+}
+/** Write a starter project into `project` and report what changed, or throw StarterConflictError */
+export function writeStarterProject(project, packageRoot, template = "js") {
+    const files = starterFiles(project, packageRoot, template);
+    const conflicts = [...files.keys()].filter((name) => name !== ".env" && name !== ".gitignore" && existsSync(join(project, name)));
+    if (conflicts.length > 0)
+        throw new StarterConflictError(conflicts);
+    const written = [];
+    let ignored = [];
+    let current = "";
+    try {
+        // The wx flag refuses a file that appeared after the check, so a concurrent writer's file is never replaced.
+        // A file counts as created once opened, so a failed write removes its partial content
+        for (const [name, text] of files) {
+            current = name;
+            let descriptor;
+            try {
+                descriptor = openSync(join(project, name), "wx");
+            }
+            catch (error) {
+                // An existing .env holds the bot's own token, so it is kept. An existing .gitignore is kept too, and
+                // gets its missing lines below
+                const keep = name === ".env" || name === ".gitignore";
+                if (keep && error.code === "EEXIST")
+                    continue;
+                throw error;
+            }
+            written.push(name);
+            try {
+                writeFileSync(descriptor, text);
+            }
+            finally {
+                closeSync(descriptor);
+            }
+        }
+        // Last, so a failure above leaves the user's .gitignore as it was
+        if (!written.includes(".gitignore"))
+            ignored = addMissingIgnoredLines(join(project, ".gitignore"));
+    }
+    catch (error) {
+        for (const name of written)
+            rmSync(join(project, name), { force: true });
+        if (error.code === "EEXIST")
+            throw new StarterConflictError([current]);
+        throw error;
+    }
+    return { written, ignored };
+}
+//# sourceMappingURL=starter-project.js.map

package/dist/internal/starter-project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"starter-project.js","sourceRoot":"","sources":["../../src/internal/starter-project.ts"],"names":[],"mappings":"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"}

package/dist/internal/suggest.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Typo suggestions shared by command names, event names and option keys.
+ * Invariant: Suggestions only name known candidates and never echo rejected values beyond the misspelled name itself
+ */
+/** Edit distance with adjacent transpositions counted as one edit (optimal string alignment), so swapping two
+ * adjacent characters is one edit. Comparison is case-sensitive. Stops early and returns limit + 1 once every
+ * alignment exceeds limit
+ */
+export declare function editDistance(left: string, right: string, limit?: number): number;
+/** A hint for an unsupported option key: The closest supported key when one is near, then the full supported list */
+export declare function unsupportedKeyHint(key: string, supported: readonly string[], noun?: string): string;
+//# sourceMappingURL=suggest.d.ts.map

package/dist/internal/suggest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.d.ts","sourceRoot":"","sources":["../../src/internal/suggest.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,SAA2B,GAAG,MAAM,CAoBlG;AAgBD,qHAAqH;AACrH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,SAAY,GAAG,MAAM,CAGtG"}

package/dist/internal/suggest.js

@@ -0,0 +1,51 @@
+/**
+ * Typo suggestions shared by command names, event names and option keys.
+ * Invariant: Suggestions only name known candidates and never echo rejected values beyond the misspelled name itself
+ */
+/** Edit distance with adjacent transpositions counted as one edit (optimal string alignment), so swapping two
+ * adjacent characters is one edit. Comparison is case-sensitive. Stops early and returns limit + 1 once every
+ * alignment exceeds limit
+ */
+export function editDistance(left, right, limit = Number.POSITIVE_INFINITY) {
+    if (Math.abs(left.length - right.length) > limit)
+        return limit + 1;
+    let before = [];
+    let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let row = 1; row <= left.length; row += 1) {
+        const current = [row];
+        let smallest = row;
+        for (let column = 1; column <= right.length; column += 1) {
+            const cost = left[row - 1] === right[column - 1] ? 0 : 1;
+            let value = Math.min(previous[column] + 1, current[column - 1] + 1, previous[column - 1] + cost);
+            if (row > 1 && column > 1 && left[row - 1] === right[column - 2] && left[row - 2] === right[column - 1])
+                value = Math.min(value, before[column - 2] + 1);
+            current.push(value);
+            smallest = Math.min(smallest, value);
+        }
+        if (smallest > limit)
+            return limit + 1;
+        before = previous;
+        previous = current;
+    }
+    return previous[right.length];
+}
+/** The first candidate closest to value, ignoring case, within one edit for names up to four characters and two edits
+ * for longer names. Returns undefined when no candidate is that close
+ */
+function closestName(value, candidates) {
+    const wanted = value.toLowerCase();
+    const limit = wanted.length <= 4 ? 1 : 2;
+    let best;
+    for (const candidate of candidates) {
+        const distance = editDistance(wanted, candidate.toLowerCase(), limit);
+        if (distance <= limit && (best === undefined || distance < best.distance))
+            best = { name: candidate, distance };
+    }
+    return best?.name;
+}
+/** A hint for an unsupported option key: The closest supported key when one is near, then the full supported list */
+export function unsupportedKeyHint(key, supported, noun = "options") {
+    const suggestion = key.length > 64 ? undefined : closestName(key, supported);
+    return `${suggestion === undefined ? "" : `Did you mean ${JSON.stringify(suggestion)}? `}Supported ${noun} are ${supported.join(", ")}`;
+}
+//# sourceMappingURL=suggest.js.map

package/dist/internal/suggest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.js","sourceRoot":"","sources":["../../src/internal/suggest.ts"],"names":[],"mappings":"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"}