@tjalve/cube-cli 0.1.0

package/dist/fixtures/metadata.js

@@ -0,0 +1,372 @@
+import { defineArgument, defineCommand, defineExample, defineExtensions, defineFlag, defineTopic } from "../metadata/index.js";
+import { defineMutationMetadata, dryRunSupported, mutationCategories } from "../mutation/index.js";
+import { createCommandRegistry } from "../registry/index.js";
+const fixtureExtensions = defineExtensions({
+    fixture: true,
+    owner: "toolkit-tests",
+    nested: {
+        beta: 2,
+        alpha: 1
+    }
+});
+export const cacheTopic = defineTopic({
+    kind: "topic",
+    name: "cache",
+    description: "Commands for inspecting and maintaining a local cache.",
+    extensions: fixtureExtensions
+});
+export const cacheInspectCommand = defineCommand({
+    kind: "command",
+    name: "cache inspect",
+    description: "Inspect cache entries without changing local state.",
+    arguments: [
+        defineArgument({
+            name: "key",
+            description: "Cache key to inspect.",
+            required: false,
+            extensions: defineExtensions({
+                fixtureRole: "lookup-key"
+            })
+        })
+    ],
+    flags: [
+        defineFlag({
+            name: "json",
+            description: "Render machine-readable JSON output.",
+            type: "boolean"
+        }),
+        defineFlag({
+            name: "output",
+            description: "Select the output format.",
+            type: "option",
+            options: ["human", "json"],
+            defaultValue: "human",
+            extensions: defineExtensions({
+                fixtureRole: "format-selector"
+            })
+        })
+    ],
+    examples: [
+        defineExample({
+            description: "Inspect all cache entries.",
+            command: "fixture cache inspect"
+        })
+    ],
+    output: {
+        formats: ["human", "json"],
+        defaultFormat: "human"
+    },
+    interactions: {
+        json: true,
+        noColor: true,
+        nonInteractive: true,
+        ttyPrompt: false
+    },
+    externalServices: [],
+    errors: [
+        {
+            kind: "cache-read-failed",
+            description: "The cache could not be read.",
+            exitCode: 2
+        }
+    ],
+    exitCodes: [
+        {
+            code: 0,
+            category: "success",
+            description: "The command completed successfully."
+        },
+        {
+            code: 2,
+            category: "validation",
+            description: "The cache key or cache state was invalid."
+        }
+    ],
+    extensions: fixtureExtensions
+});
+export const cacheClearCommand = defineCommand({
+    kind: "command",
+    name: "cache clear",
+    description: "Clear cache entries after showing the planned local file changes.",
+    aliases: ["cc"],
+    flags: [
+        defineFlag({
+            name: "dry-run",
+            description: "Show cache entries that would be removed without deleting them.",
+            type: "boolean"
+        }),
+        defineFlag({
+            name: "yes",
+            description: "Run without interactive confirmation.",
+            type: "boolean"
+        })
+    ],
+    examples: [
+        defineExample({
+            description: "Preview cache cleanup.",
+            command: "fixture cache clear --dry-run"
+        })
+    ],
+    output: {
+        formats: ["human", "json"],
+        defaultFormat: "human"
+    },
+    interactions: {
+        json: true,
+        dryRun: dryRunSupported(),
+        noColor: true,
+        nonInteractive: true,
+        ttyPrompt: true
+    },
+    mutation: defineMutationMetadata({
+        categories: mutationCategories("local-files"),
+        extensions: defineExtensions({
+            fixtureMutation: "cache-cleanup"
+        })
+    }),
+    exitCodes: [
+        {
+            code: 0,
+            category: "success",
+            description: "The command completed successfully."
+        },
+        {
+            code: 5,
+            category: "safety",
+            description: "The command was blocked by a safety policy."
+        }
+    ],
+    extensions: fixtureExtensions
+});
+export const cacheInstallCommand = defineCommand({
+    kind: "command",
+    name: "cache install",
+    description: "Prepare dependency cache entries after showing supply-chain-sensitive checks.",
+    flags: [
+        defineFlag({
+            name: "dry-run",
+            description: "Show dependency cache changes without writing fixture state.",
+            type: "boolean"
+        }),
+        defineFlag({
+            name: "json",
+            description: "Render machine-readable JSON output.",
+            type: "boolean"
+        })
+    ],
+    examples: [
+        defineExample({
+            description: "Preview dependency cache preparation.",
+            command: "fixture cache install --dry-run"
+        })
+    ],
+    output: {
+        formats: ["human", "json"],
+        defaultFormat: "human"
+    },
+    interactions: {
+        json: true,
+        dryRun: dryRunSupported(),
+        noColor: true,
+        nonInteractive: true,
+        ttyPrompt: false
+    },
+    mutation: defineMutationMetadata({
+        categories: mutationCategories("dependency", "local-files"),
+        extensions: defineExtensions({
+            fixtureMutation: "dependency-cache"
+        })
+    }),
+    supplyChain: {
+        sensitive: true,
+        kinds: ["dependency", "package-manager"],
+        reason: "Dependency cache preparation depends on package-manager metadata supplied by the consuming package.",
+        extensions: defineExtensions({
+            fixtureSupplyChain: "dependency-cache"
+        })
+    },
+    errors: [
+        {
+            kind: "supply-chain-blocked",
+            description: "The dependency cache operation was blocked for supply-chain review.",
+            exitCode: 5
+        }
+    ],
+    exitCodes: [
+        {
+            code: 0,
+            category: "success",
+            description: "The command completed successfully."
+        },
+        {
+            code: 5,
+            category: "safety",
+            description: "The command was blocked by supply-chain safety guidance."
+        }
+    ],
+    extensions: fixtureExtensions
+});
+export const cacheValidateCommand = defineCommand({
+    kind: "command",
+    name: "cache validate",
+    description: "Validate cache configuration and report actionable failures.",
+    flags: [
+        defineFlag({
+            name: "json",
+            description: "Render machine-readable JSON output.",
+            type: "boolean"
+        })
+    ],
+    examples: [
+        defineExample({
+            description: "Validate cache configuration.",
+            command: "fixture cache validate --json"
+        })
+    ],
+    output: {
+        formats: ["human", "json"],
+        defaultFormat: "human"
+    },
+    interactions: {
+        json: true,
+        noColor: true,
+        nonInteractive: true,
+        ttyPrompt: false
+    },
+    errors: [
+        {
+            kind: "cache-config-invalid",
+            description: "The cache configuration failed validation.",
+            exitCode: 3
+        }
+    ],
+    exitCodes: [
+        {
+            code: 0,
+            category: "success",
+            description: "The command completed successfully."
+        },
+        {
+            code: 3,
+            category: "validation",
+            description: "The cache configuration was invalid."
+        }
+    ],
+    extensions: fixtureExtensions
+});
+export const cachePromptCommand = defineCommand({
+    kind: "command",
+    name: "cache prompt",
+    description: "Resolve a cache prompt through flags, defaults, or an interactive TTY.",
+    flags: [
+        defineFlag({
+            name: "value",
+            description: "Prompt value supplied by flags or config.",
+            type: "string"
+        }),
+        defineFlag({
+            name: "defaults",
+            description: "Use deterministic defaults without prompting.",
+            type: "boolean"
+        }),
+        defineFlag({
+            name: "yes",
+            description: "Accept the deterministic prompt default.",
+            type: "boolean"
+        }),
+        defineFlag({
+            name: "json",
+            description: "Render machine-readable JSON output.",
+            type: "boolean"
+        })
+    ],
+    examples: [
+        defineExample({
+            description: "Resolve a prompt from flags.",
+            command: "fixture cache prompt --value alpha"
+        })
+    ],
+    output: {
+        formats: ["human", "json"],
+        defaultFormat: "human"
+    },
+    interactions: {
+        json: true,
+        noColor: true,
+        nonInteractive: false,
+        ttyPrompt: true
+    },
+    errors: [
+        {
+            kind: "prompt-blocked",
+            description: "The prompt was blocked by non-interactive execution.",
+            exitCode: 2
+        },
+        {
+            kind: "prompt-cancelled",
+            description: "The prompt was cancelled before a value was supplied.",
+            exitCode: 2
+        }
+    ],
+    exitCodes: [
+        {
+            code: 0,
+            category: "success",
+            description: "The command completed successfully."
+        },
+        {
+            code: 2,
+            category: "usage",
+            description: "The prompt could not run in the current execution mode."
+        }
+    ],
+    extensions: fixtureExtensions
+});
+export const cacheExplodeCommand = defineCommand({
+    kind: "command",
+    name: "cache explode",
+    description: "Raise an unexpected fixture failure for runtime error tests.",
+    flags: [
+        defineFlag({
+            name: "json",
+            description: "Render machine-readable JSON output.",
+            type: "boolean"
+        })
+    ],
+    examples: [
+        defineExample({
+            description: "Raise an unexpected fixture failure.",
+            command: "fixture cache explode --json"
+        })
+    ],
+    output: {
+        formats: ["human", "json"],
+        defaultFormat: "human"
+    },
+    interactions: {
+        json: true,
+        noColor: true,
+        nonInteractive: true,
+        ttyPrompt: false
+    },
+    errors: [
+        {
+            kind: "unexpected-error",
+            description: "The command failed unexpectedly.",
+            exitCode: 70
+        }
+    ],
+    exitCodes: [
+        {
+            code: 70,
+            category: "unexpected",
+            description: "The command failed unexpectedly."
+        }
+    ],
+    extensions: fixtureExtensions
+});
+export const fixtureMetadata = createCommandRegistry({
+    topics: [cacheTopic],
+    commands: [cacheInspectCommand, cacheClearCommand, cacheInstallCommand, cacheValidateCommand, cachePromptCommand, cacheExplodeCommand]
+});
+//# sourceMappingURL=metadata.js.map

package/dist/fixtures/metadata.js.map

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

package/dist/help/index.d.ts

@@ -0,0 +1,24 @@
+import type { CommandMetadata, TopicMetadata } from "../metadata/index.js";
+import type { CommandRegistry } from "../registry/index.js";
+export interface HelpRenderOptions {
+    readonly bin: string;
+    readonly packageVersion?: string | undefined;
+    readonly description?: string | undefined;
+}
+export interface HelpRequest {
+    readonly kind: "root" | "target";
+    readonly targetTokens: readonly string[];
+}
+export interface Suggestion {
+    readonly value: string;
+    readonly distance: number;
+}
+export declare function normalizeHelpRequest(argv: readonly string[]): HelpRequest | undefined;
+export declare function renderHelp(registry: CommandRegistry, request: HelpRequest, options: HelpRenderOptions): string;
+export declare function renderRootHelp(registry: CommandRegistry, options: HelpRenderOptions): string;
+export declare function renderTopicHelp(registry: CommandRegistry, topic: TopicMetadata, options: HelpRenderOptions): string;
+export declare function renderCommandHelp(command: CommandMetadata, options: HelpRenderOptions): string;
+export declare function suggestCommand(registry: CommandRegistry, input: string): Suggestion | undefined;
+export declare function suggestFlag(command: CommandMetadata, input: string): Suggestion | undefined;
+export declare function suggestValue(input: string, candidates: readonly string[]): Suggestion | undefined;
+//# sourceMappingURL=index.d.ts.map

package/dist/help/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/help/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,eAAe,EAAgB,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC3G,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG5D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,GAAG,SAAS,CAmBrF;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAgB9G;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAa5F;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAUnH;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAS9F;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAQ/F;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAK3F;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,GAAG,SAAS,CAgBjG"}

package/dist/help/index.js

@@ -0,0 +1,254 @@
+import { findCommand, findTopic, listCommands, listTopics } from "../registry/index.js";
+export function normalizeHelpRequest(argv) {
+    if (argv.length === 0) {
+        return { kind: "root", targetTokens: [] };
+    }
+    if (argv.length === 1 && argv[0] === "--help") {
+        return { kind: "root", targetTokens: [] };
+    }
+    if (argv[0] === "help") {
+        return argv.length === 1
+            ? { kind: "root", targetTokens: [] }
+            : { kind: "target", targetTokens: trimAtFirstFlag(argv.slice(1)) };
+    }
+    if (argv.includes("--help")) {
+        return { kind: "target", targetTokens: trimAtFirstFlag(argv.filter((token) => token !== "--help")) };
+    }
+    if (argv.at(-1) === "help") {
+        return { kind: "target", targetTokens: trimAtFirstFlag(argv.slice(0, -1)) };
+    }
+    return undefined;
+}
+export function renderHelp(registry, request, options) {
+    if (request.kind === "root" || request.targetTokens.length === 0) {
+        return renderRootHelp(registry, options);
+    }
+    const target = request.targetTokens.join(" ");
+    const command = findCommand(registry, target);
+    if (command) {
+        return renderCommandHelp(command, options);
+    }
+    const topic = findTopic(registry, target);
+    if (topic) {
+        return renderTopicHelp(registry, topic, options);
+    }
+    const suggestion = suggestCommand(registry, target);
+    const hint = suggestion ? `\nDid you mean "${suggestion.value}"?` : "";
+    throw new Error(`Unknown help topic or command: ${target}${hint}`);
+}
+export function renderRootHelp(registry, options) {
+    return joinSections([
+        [options.bin, options.description ?? "Metadata-driven command-line interface."].join("\n"),
+        joinLines([
+            "Usage:",
+            `  ${options.bin} <command> [flags]`,
+            `  ${options.bin} help <command>`,
+            ...(options.packageVersion ? [`  ${options.bin} --version`] : [])
+        ]),
+        renderNameDescriptionSection("Topics:", listTopics(registry)),
+        renderNameDescriptionSection("Commands:", listCommands(registry)),
+        "Help invocations never execute command handlers."
+    ]);
+}
+export function renderTopicHelp(registry, topic, options) {
+    const prefix = `${topic.name} `;
+    const commands = listCommands(registry).filter((command) => command.name.startsWith(prefix));
+    return joinSections([
+        [topic.name, topic.description].join("\n"),
+        joinLines(["Usage:", `  ${options.bin} ${topic.name} <command> [flags]`, `  ${options.bin} help ${topic.name} <command>`]),
+        renderNameDescriptionSection("Commands:", commands),
+        renderTopicCommandDetails(commands),
+        "Help invocations never execute command handlers."
+    ]);
+}
+export function renderCommandHelp(command, options) {
+    return joinSections([
+        [command.name, command.description].join("\n"),
+        joinLines(["Usage:", `  ${options.bin} ${command.name}${renderUsageSuffix(command)}`]),
+        renderArguments(command.arguments ?? []),
+        renderFlags(command.flags ?? []),
+        renderExamples(command.examples ?? []),
+        renderBehavior(command)
+    ]);
+}
+export function suggestCommand(registry, input) {
+    const candidates = [
+        ...listCommands(registry).map((command) => command.name),
+        ...listCommands(registry).flatMap((command) => command.aliases ?? []),
+        ...listTopics(registry).map((topic) => topic.name),
+        ...listTopics(registry).flatMap((topic) => topic.aliases ?? [])
+    ];
+    return suggestValue(input, candidates);
+}
+export function suggestFlag(command, input) {
+    const normalizedInput = input.startsWith("-") ? input : `--${input}`;
+    const candidates = (command.flags ?? []).flatMap(renderFlagTokens);
+    const suggestion = suggestValue(normalizedInput, candidates);
+    return suggestion ? { value: suggestion.value, distance: suggestion.distance } : undefined;
+}
+export function suggestValue(input, candidates) {
+    const normalizedInput = input.trim();
+    if (normalizedInput.length === 0) {
+        return undefined;
+    }
+    const ranked = [...new Set(candidates)]
+        .map((candidate) => ({ value: candidate, distance: levenshteinDistance(normalizedInput, candidate) }))
+        .sort((left, right) => left.distance - right.distance || compareText(left.value, right.value));
+    const [best, secondBest] = ranked;
+    if (!best || best.distance > 3 || best.distance > Math.ceil(normalizedInput.length / 2)) {
+        return undefined;
+    }
+    if (secondBest && secondBest.distance === best.distance) {
+        return undefined;
+    }
+    return best;
+}
+function renderUsageSuffix(command) {
+    const args = (command.arguments ?? []).map((argument) => argument.required ? `<${argument.name}>` : `[${argument.name}]`);
+    const flags = (command.flags ?? []).map(renderFlagUsage);
+    const suffix = [...args, ...flags].join(" ");
+    return suffix.length === 0 ? "" : ` ${suffix}`;
+}
+function renderArguments(args) {
+    if (args.length === 0) {
+        return "Arguments:\n  none";
+    }
+    return renderNameDescriptionSection("Arguments:", args.map((argument) => ({
+        name: argument.required ? `<${argument.name}>` : `[${argument.name}]`,
+        description: argument.description
+    })));
+}
+function renderFlags(flags) {
+    if (flags.length === 0) {
+        return "Flags:\n  none";
+    }
+    return renderNameDescriptionSection("Flags:", flags.map((flag) => ({
+        name: `${renderFlagToken(flag)}${flag.type === "boolean" ? "" : " <value>"}`,
+        description: renderFlagDescription(flag)
+    })));
+}
+function renderFlagUsage(flag) {
+    if (flag.negatable === true) {
+        return `[--${flag.name}|--no-${flag.name}]`;
+    }
+    return `[${renderFlagToken(flag)}${flag.type === "boolean" ? "" : " <value>"}]`;
+}
+function renderFlagToken(flag) {
+    const positive = flag.short ? `-${flag.short}, --${flag.name}` : `--${flag.name}`;
+    return flag.negatable === true ? `${positive}, --no-${flag.name}` : positive;
+}
+function renderFlagTokens(flag) {
+    return [
+        `--${flag.name}`,
+        ...(flag.negatable === true ? [`--no-${flag.name}`] : []),
+        ...(flag.short ? [`-${flag.short}`] : []),
+        ...(flag.aliases ?? []).flatMap((alias) => [`--${alias}`, ...(flag.negatable === true ? [`--no-${alias}`] : [])])
+    ];
+}
+function renderFlagDescription(flag) {
+    const pieces = [flag.description];
+    if (flag.options && flag.options.length > 0) {
+        pieces.push(`options: ${flag.options.join(", ")}`);
+    }
+    if (flag.aliases && flag.aliases.length > 0) {
+        pieces.push(`aliases: ${flag.aliases.map((alias) => `--${alias}`).join(", ")}`);
+    }
+    return pieces.join("; ");
+}
+function renderExamples(examples) {
+    if (examples.length === 0) {
+        return "Examples:\n  none";
+    }
+    return joinLines(["Examples:", ...examples.map((example) => `  ${example.command}  # ${example.description}`)]);
+}
+function renderBehavior(command) {
+    const mutationCategories = command.mutation?.categories ?? [];
+    return joinLines([
+        "Behavior:",
+        `  JSON output: ${command.interactions?.json ? "supported" : "not declared"}`,
+        `  Dry run: ${renderDryRun(command)}`,
+        `  Mutation: ${mutationCategories.length === 0 ? "none" : mutationCategories.join(", ")}`,
+        `  Supply chain: ${renderSupplyChain(command)}`
+    ]);
+}
+function renderTopicCommandDetails(commands) {
+    if (commands.length === 0) {
+        return "Command details:\n  none";
+    }
+    return joinLines([
+        "Command details:",
+        ...commands.map((command) => {
+            const flagCount = command.flags?.length ?? 0;
+            const argumentCount = command.arguments?.length ?? 0;
+            const exampleCount = command.examples?.length ?? 0;
+            const mutationCategories = command.mutation?.categories ?? [];
+            const mutation = mutationCategories.length === 0 ? "none" : mutationCategories.join(", ");
+            const dryRun = renderDryRun(command);
+            const json = command.interactions?.json ? "supported" : "not declared";
+            return `  ${command.name}: args=${argumentCount}, flags=${flagCount}, examples=${exampleCount}, json=${json}, dry-run=${dryRun}, mutation=${mutation}, supply-chain=${renderSupplyChain(command)}`;
+        })
+    ]);
+}
+function renderDryRun(command) {
+    const dryRun = command.interactions?.dryRun;
+    if (!dryRun) {
+        return "not declared";
+    }
+    return dryRun.supported ? "supported" : `unsupported (${dryRun.reason})`;
+}
+function renderSupplyChain(command) {
+    const supplyChain = command.supplyChain;
+    if (supplyChain?.sensitive !== true) {
+        return "standard";
+    }
+    const kinds = supplyChain.kinds && supplyChain.kinds.length > 0 ? [...new Set(supplyChain.kinds)].sort(compareText).join(", ") : "unspecified";
+    return `sensitive (${kinds})${supplyChain.reason ? ` — ${supplyChain.reason}` : ""}`;
+}
+function renderNameDescriptionSection(title, entries) {
+    if (entries.length === 0) {
+        return `${title}\n  none`;
+    }
+    const width = Math.max(...entries.map((entry) => entry.name.length));
+    return joinLines([title, ...entries.map((entry) => `  ${entry.name.padEnd(width)}  ${entry.description}`)]);
+}
+function trimAtFirstFlag(tokens) {
+    const flagIndex = tokens.findIndex((token) => token.startsWith("-"));
+    return flagIndex === -1 ? tokens : tokens.slice(0, flagIndex);
+}
+function levenshteinDistance(left, right) {
+    if (left === right) {
+        return 0;
+    }
+    if (left.length < right.length) {
+        return levenshteinDistance(right, left);
+    }
+    if (right.length === 0) {
+        return left.length;
+    }
+    let previousRow = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+        const currentRow = [leftIndex];
+        for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+            const substitutionCost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
+            const insertion = (currentRow[rightIndex - 1] ?? Number.POSITIVE_INFINITY) + 1;
+            const deletion = (previousRow[rightIndex] ?? Number.POSITIVE_INFINITY) + 1;
+            const substitution = (previousRow[rightIndex - 1] ?? Number.POSITIVE_INFINITY) + substitutionCost;
+            currentRow[rightIndex] = Math.min(insertion, deletion, substitution);
+        }
+        previousRow = currentRow;
+    }
+    return previousRow[right.length] ?? left.length;
+}
+function compareText(left, right) {
+    if (left === right) {
+        return 0;
+    }
+    return left < right ? -1 : 1;
+}
+function joinSections(sections) {
+    return `${sections.join("\n\n")}\n`;
+}
+function joinLines(lines) {
+    return lines.join("\n");
+}
+//# sourceMappingURL=index.js.map