@gunshi/plugin-suggestion 0.35.2

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 kazuya kawaguchi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# @gunshi/plugin-suggestion
+
+Suggestion plugin for Gunshi.
+
+This plugin adds a short hint to validation errors when a user enters an unknown long option or an unknown command.
+It uses Levenshtein distance by default and works with Gunshi's structured validation errors.
+
+## Installation
+
+```sh
+npm install @gunshi/plugin-suggestion
+```
+
+## Usage
+
+```ts
+import { cli, define } from 'gunshi'
+import { suggestion } from '@gunshi/plugin-suggestion'
+
+const command = define({
+  name: 'app',
+  toKebab: true,
+  args: {
+    allowReload: {
+      type: 'boolean',
+      description: 'Allow reload'
+    }
+  },
+  run: () => {}
+})
+
+await cli(process.argv.slice(2), command, {
+  strict: true,
+  plugins: [suggestion()]
+})
+```
+
+When the user enters an unknown long option, the validation message includes a hint:
+
+```txt
+Unknown option: --alow-reload
+Did you mean --allow-reload?
+```
+
+When the user enters an unknown command, the plugin suggests a command from the same command level:
+
+```txt
+Command not found: rn
+Did you mean run?
+```
+
+## Options
+
+```ts
+suggestion({
+  maxDistance: 2,
+  maxSuggestions: 1,
+  includeOptions: true,
+  includeCommands: true,
+  distance: customDistance,
+  normalize: value => value.toLowerCase()
+})
+```
+
+- `maxDistance`: maximum distance allowed for a candidate.
+- `maxSuggestions`: maximum number of suggestions per validation error.
+- `includeOptions`: enables unknown long option suggestions.
+- `includeCommands`: enables command not found suggestions.
+- `distance`: custom distance function. Lower values are better matches.
+- `normalize`: normalizes typed input and candidates before scoring.
+
+## Internationalization
+
+The plugin can be combined with `@gunshi/plugin-i18n`.
+The suggestion hint uses the built-in resource key `err:suggestion:did-you-mean`.
+
+```ts
+import i18n from '@gunshi/plugin-i18n'
+import { suggestion } from '@gunshi/plugin-suggestion'
+
+await cli(argv, command, {
+  strict: true,
+  plugins: [i18n({ locale: 'ja-JP' }), suggestion()]
+})
+```
+
+Without i18n, the plugin falls back to `Did you mean {$name}?`.
+
+## Design notes
+
+The plugin does not detect unknown options or unknown commands by itself.
+Gunshi core creates structured validation errors and provides candidate metadata.
+This plugin only decorates validation error rendering and appends suggestion hints.

package/lib/index.d.ts

@@ -0,0 +1,126 @@
+import { PluginWithoutExtension } from "@gunshi/plugin";
+
+//#region src/index.d.ts
+
+/**
+ * The unique identifier for suggestion plugin.
+ */
+declare const pluginId: "g:suggestion";
+/**
+ * Type representing the unique identifier for suggestion plugin.
+ */
+type PluginId = typeof pluginId;
+/**
+ * Suggestion error resource keys.
+ */
+declare const SuggestionErrorKeys: {
+  readonly didYouMean: "err:suggestion:did-you-mean";
+};
+/**
+ * Suggestion error resource key type.
+ */
+type SuggestionErrorCode = (typeof SuggestionErrorKeys)[keyof typeof SuggestionErrorKeys];
+/**
+ * Distance function for scoring candidate names.
+ *
+ * Lower values are treated as better matches.
+ */
+type DistanceFunction = (input: string, candidate: string) => number;
+/**
+ * Suggestion function returned by {@link defineSuggestNames}.
+ */
+type SuggestNames = (typed: string, candidates: readonly string[]) => string[];
+/**
+ * Suggestion plugin options.
+ */
+interface SuggestionOptions {
+  /**
+   * Maximum distance allowed for a candidate.
+   *
+   * @default 2
+   */
+  maxDistance?: number;
+  /**
+   * Maximum number of suggestions to render for one error.
+   *
+   * @default 1
+   */
+  maxSuggestions?: number;
+  /**
+   * Whether to suggest known long options for unknown option errors.
+   *
+   * @default true
+   */
+  includeOptions?: boolean;
+  /**
+   * Whether to suggest known commands for command-not-found errors.
+   *
+   * @default true
+   */
+  includeCommands?: boolean;
+  /**
+   * Distance function used for ranking candidates.
+   *
+   * @default levenshtein
+   */
+  distance?: DistanceFunction;
+  /**
+   * Normalize typed input and candidates before distance calculation.
+   *
+   * @default value => value
+   */
+  normalize?: (value: string) => string;
+}
+/**
+ * Resolved suggestion plugin options.
+ */
+interface ResolvedSuggestionOptions {
+  /**
+   * Maximum distance allowed for a candidate.
+   */
+  maxDistance: number;
+  /**
+   * Maximum number of suggestions to render for one error.
+   */
+  maxSuggestions: number;
+  /**
+   * Whether to suggest known long options for unknown option errors.
+   */
+  includeOptions: boolean;
+  /**
+   * Whether to suggest known commands for command-not-found errors.
+   */
+  includeCommands: boolean;
+  /**
+   * Distance function used for ranking candidates.
+   */
+  distance: DistanceFunction;
+  /**
+   * Normalize typed input and candidates before distance calculation.
+   */
+  normalize: (value: string) => string;
+}
+/**
+ * Calculate the Levenshtein distance between two strings.
+ *
+ * @param input - Input string
+ * @param candidate - Candidate string
+ * @returns Edit distance between the two strings
+ */
+declare function levenshtein(input: string, candidate: string): number;
+/**
+ * Create a suggestion function with resolved options captured in a closure.
+ *
+ * @param options - Resolved suggestion options
+ * @returns A function that suggests candidate names
+ */
+declare function defineSuggestNames(options: ResolvedSuggestionOptions): SuggestNames;
+/**
+ * Suggestion plugin.
+ *
+ * @param options - Suggestion plugin options
+ * @returns A defined plugin as suggestion
+ */
+declare function suggestion(options?: SuggestionOptions): PluginWithoutExtension;
+//#endregion
+export { DistanceFunction, PluginId, ResolvedSuggestionOptions, SuggestNames, SuggestionErrorCode, SuggestionErrorKeys, SuggestionOptions, defineSuggestNames, levenshtein, pluginId, suggestion };

package/lib/index.js

@@ -0,0 +1,152 @@
+import { ArgsValidationErrorKeys, isArgsValidationError, isCommandNotFoundError, plugin } from "@gunshi/plugin";
+//#region src/index.ts
+/**
+* The entry point of suggestion plugin.
+*
+* @example
+* ```js
+* import { cli } from 'gunshi'
+* import { suggestion } from '@gunshi/plugin-suggestion'
+*
+* await cli(process.argv.slice(2), command, {
+*   strict: true,
+*   plugins: [
+*     suggestion()
+*   ]
+* })
+* ```
+*
+* @module
+*/
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* The unique identifier for suggestion plugin.
+*/
+const pluginId = "g:suggestion";
+/**
+* Suggestion error resource keys.
+*/
+const SuggestionErrorKeys = { didYouMean: "err:suggestion:did-you-mean" };
+const i18nPluginId = "g:i18n";
+const dependencies = [{
+	id: i18nPluginId,
+	optional: true
+}];
+/**
+* Calculate the Levenshtein distance between two strings.
+*
+* @param input - Input string
+* @param candidate - Candidate string
+* @returns Edit distance between the two strings
+*/
+function levenshtein(input, candidate) {
+	if (input === candidate) return 0;
+	if (input.length === 0) return candidate.length;
+	if (candidate.length === 0) return input.length;
+	let previous = Array.from({ length: candidate.length + 1 }, (_, index) => index);
+	let current = Array.from({ length: candidate.length + 1 }, () => 0);
+	for (let i = 1; i <= input.length; i++) {
+		current[0] = i;
+		for (let j = 1; j <= candidate.length; j++) {
+			const cost = input[i - 1] === candidate[j - 1] ? 0 : 1;
+			current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + cost);
+		}
+		[previous, current] = [current, previous];
+	}
+	return previous[candidate.length];
+}
+/**
+* Create a suggestion function with resolved options captured in a closure.
+*
+* @param options - Resolved suggestion options
+* @returns A function that suggests candidate names
+*/
+function defineSuggestNames(options) {
+	return function suggestNames(typed, candidates) {
+		const normalizedTyped = options.normalize(normalizeSuggestionName(typed));
+		return candidates.map((candidate, index) => ({
+			candidate,
+			index,
+			distance: options.distance(normalizedTyped, options.normalize(normalizeSuggestionName(candidate)))
+		})).filter((item) => item.distance <= options.maxDistance).sort((a, b) => a.distance - b.distance || a.index - b.index).slice(0, options.maxSuggestions).map((item) => item.candidate);
+	};
+}
+/**
+* Suggestion plugin.
+*
+* @param options - Suggestion plugin options
+* @returns A defined plugin as suggestion
+*/
+function suggestion(options = {}) {
+	const resolved = resolveSuggestionOptions(options);
+	const suggestNames = defineSuggestNames(resolved);
+	return plugin({
+		id: pluginId,
+		name: "suggestion",
+		dependencies,
+		setup(ctx) {
+			ctx.decorateValidationErrorsRenderer(async (baseRenderer, cmdCtx, error) => {
+				const message = await baseRenderer(cmdCtx, error);
+				const hints = [];
+				const seen = /* @__PURE__ */ new Set();
+				for (const err of error.errors) {
+					if (resolved.includeOptions) await collectSuggestions(hints, seen, cmdCtx, getUnknownOptionSuggestionInput(err), suggestNames);
+					if (resolved.includeCommands) await collectSuggestions(hints, seen, cmdCtx, getCommandSuggestionInput(err), suggestNames);
+				}
+				return [message, ...hints].filter(Boolean).join("\n");
+			});
+		}
+	});
+}
+function resolveSuggestionOptions(options) {
+	return {
+		maxDistance: options.maxDistance ?? 2,
+		maxSuggestions: options.maxSuggestions ?? 1,
+		includeOptions: options.includeOptions ?? true,
+		includeCommands: options.includeCommands ?? true,
+		distance: options.distance ?? levenshtein,
+		normalize: options.normalize ?? ((value) => value)
+	};
+}
+async function collectSuggestions(hints, seen, ctx, input, suggestNames) {
+	if (!input) return;
+	const suggestions = suggestNames(input.name, input.candidates);
+	for (const name of suggestions) {
+		const hint = localizeSuggestion(ctx, name);
+		if (!seen.has(hint)) {
+			seen.add(hint);
+			hints.push(hint);
+		}
+	}
+}
+function getUnknownOptionSuggestionInput(error) {
+	if (!isArgsValidationError(error) || error.code !== ArgsValidationErrorKeys.unknownOption) return;
+	const values = error.values;
+	if (typeof values.rawName !== "string" || !values.rawName.startsWith("--")) return;
+	if (typeof values.name !== "string" || !Array.isArray(values.candidates)) return;
+	const candidates = values.candidates.filter((candidate) => {
+		return typeof candidate === "string" && candidate.startsWith("--");
+	});
+	return candidates.length > 0 ? {
+		name: values.name,
+		candidates
+	} : void 0;
+}
+function getCommandSuggestionInput(error) {
+	if (!isCommandNotFoundError(error) || error.candidates.length === 0) return;
+	return {
+		name: error.commandName,
+		candidates: error.candidates
+	};
+}
+function localizeSuggestion(ctx, name) {
+	return (ctx.extensions?.[i18nPluginId])?.translate?.(SuggestionErrorKeys.didYouMean, { name }) || `Did you mean ${name}?`;
+}
+function normalizeSuggestionName(value) {
+	return value.startsWith("--") ? value.slice(2) : value;
+}
+//#endregion
+export { SuggestionErrorKeys, defineSuggestNames, levenshtein, pluginId, suggestion };

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@gunshi/plugin-suggestion",
+  "description": "suggestion plugin for gunshi",
+  "version": "0.35.2",
+  "author": {
+    "name": "kazuya kawaguchi",
+    "email": "kawakazu80@gmail.com"
+  },
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/kazupon",
+  "bugs": {
+    "url": "https://github.com/kazupon/gunshi/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kazupon/gunshi.git",
+    "directory": "packages/plugin-suggestion"
+  },
+  "keywords": [
+    "gunshi",
+    "suggestion",
+    "plugin",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">= 22"
+  },
+  "type": "module",
+  "files": [
+    "lib"
+  ],
+  "module": "lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.js",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "lib/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./lib/*",
+        "./*"
+      ]
+    }
+  },
+  "dependencies": {
+    "@gunshi/plugin": "0.35.2"
+  },
+  "peerDependencies": {
+    "@gunshi/plugin-i18n": "0.35.2"
+  },
+  "devDependencies": {
+    "deno": "^2.7.14",
+    "jsr": "^0.14.3",
+    "jsr-exports-lint": "^0.4.2",
+    "publint": "^0.3.20",
+    "tsdown": "0.21.0",
+    "@gunshi/resources": "0.35.2",
+    "gunshi": "0.35.2",
+    "@gunshi/plugin-i18n": "0.35.2"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "build:docs": "tsx ../../scripts/api-references.ts",
+    "lint:jsr": "jsr publish --dry-run --allow-dirty",
+    "typecheck:deno": "deno check --import-map=../../importmap.json ./src"
+  }
+}