@gunshi/plugin-renderer 0.33.0 → 0.35.0

package/README.md

@@ -38,9 +38,13 @@ const command = define({
   description: 'Deploy your application',
   args: {
     environment: {
-      type: 'string',
-      description: 'Target environment',
-      required: true
+      type: 'positional',
+      description: 'Target environment'
+    },
+    region: {
+      type: 'positional',
+      required: false,
+      description: 'Optional deployment region'
     },
     force: {
       type: 'boolean',
@@ -48,9 +52,10 @@ const command = define({
       description: 'Force deployment without confirmation'
     }
   },
-  examples: '$ deploy production --force',
+  examples: ['$ deploy production --force', '$ deploy production us-east-1 --force'],
   run: async ctx => {
-    console.log(`Deploying to ${ctx.values.environment}...`)
+    const region = ctx.values.region ? ` in ${ctx.values.region}` : ''
+    console.log(`Deploying to ${ctx.values.environment}${region}...`)
   }
 })
 
@@ -94,18 +99,20 @@ When a user runs `--help`, the output looks like:
 ```sh
 deploy - Deploy your application
 
-USAGE
-  $ deploy [options] <environment>
+USAGE:
+  deploy <OPTIONS> <environment> [<region>]
 
-ARGUMENTS
-  environment  Target environment
+ARGUMENTS:
+  environment          Target environment
+  region               Optional deployment region
 
-OPTIONS
-  -f, --force  Force deployment without confirmation
-  -h, --help   Display this help message
+OPTIONS:
+  -f, --force          Force deployment without confirmation
+  -h, --help           Display this help message
 
-EXAMPLES
+EXAMPLES:
   $ deploy production --force
+  $ deploy production us-east-1 --force
 ```
 
 ### Exported Functions

package/lib/index.js

@@ -1,5 +1,5 @@
 import { ANONYMOUS_COMMAND_NAME, plugin } from "@gunshi/plugin";
-//#region ../../node_modules/.pnpm/args-tokens@0.25.0/node_modules/args-tokens/lib/utils.js
+//#region ../../node_modules/.pnpm/args-tokens@0.27.0/node_modules/args-tokens/lib/utils.js
 /**
 * Entry point of utils.
 *
@@ -303,6 +303,15 @@ const pluginId = namespacedId("renderer");
 * @license MIT
 */
 const COMMON_ARGS_KEYS = Object.keys(COMMON_ARGS);
+function isHiddenArg(schema) {
+	return schema.hidden === true;
+}
+function getVisibleOptionalArgs(args) {
+	return Object.entries(args).filter(([_, schema]) => schema.type !== "positional" && !isHiddenArg(schema));
+}
+function getVisiblePositionalArgs(args) {
+	return Object.entries(args).filter(([_, schema]) => schema.type === "positional" && !isHiddenArg(schema));
+}
 /**
 * Render the usage.
 *
@@ -484,7 +493,7 @@ async function hasCommands(ctx) {
 * @returns True if the command has options
 */
 function hasOptionalArgs(args) {
-	return Object.values(args).some((arg) => arg.type !== "positional");
+	return getVisibleOptionalArgs(args).length > 0;
 }
 /**
 * Check if the command has positional arguments
@@ -493,7 +502,7 @@ function hasOptionalArgs(args) {
 * @returns True if the command has options
 */
 function hasPositionalArgs(args) {
-	return Object.values(args).some((arg) => arg.type === "positional");
+	return getVisiblePositionalArgs(args).length > 0;
 }
 /**
 * Check if all options have default values
@@ -502,7 +511,8 @@ function hasPositionalArgs(args) {
 * @returns True if all options have default values
 */
 function hasAllDefaultOptions(args) {
-	return !!(args && Object.values(args).every((arg) => arg.default));
+	const visibleOptionalArgs = getVisibleOptionalArgs(args);
+	return visibleOptionalArgs.length > 0 && visibleOptionalArgs.every(([_, arg]) => arg.default);
 }
 /**
 * Generate options symbols for usage
@@ -512,7 +522,7 @@ function hasAllDefaultOptions(args) {
 * @returns Options symbols for usage
 */
 async function generateOptionsSymbols(ctx, args) {
-	return hasOptionalArgs(args) ? hasAllDefaultOptions(args) ? `[${await ctx.extensions[pluginId].text(resolveBuiltInKey("OPTIONS"))}]` : `<${await ctx.extensions[pluginId].text(resolveBuiltInKey("OPTIONS"))}>` : "";
+	return getVisibleOptionalArgs(args).length > 0 ? hasAllDefaultOptions(args) ? `[${await ctx.extensions[pluginId].text(resolveBuiltInKey("OPTIONS"))}]` : `<${await ctx.extensions[pluginId].text(resolveBuiltInKey("OPTIONS"))}>` : "";
 }
 /**
 * Get optional arguments pairs for usage
@@ -521,8 +531,7 @@ async function generateOptionsSymbols(ctx, args) {
 * @returns Options pairs for usage
 */
 function getOptionalArgsPairs(ctx) {
-	return Object.entries(ctx.args).reduce((acc, [name, schema]) => {
-		if (schema.type === "positional") return acc;
+	return getVisibleOptionalArgs(ctx.args).reduce((acc, [name, schema]) => {
 		let key = makeShortLongOptionPair(schema, name, ctx.toKebab);
 		if (schema.type !== "boolean") {
 			const displayName = ctx.toKebab || schema.toKebab ? kebabnize(name) : name;
@@ -562,9 +571,11 @@ async function resolveDisplayValue(ctx, key) {
 * @returns Generated options usage
 */
 async function generateOptionalArgsUsage(ctx, optionsPairs) {
-	const optionsMaxLength = Math.max(...Object.entries(optionsPairs).map(([_, value]) => value.length));
-	const optionSchemaMaxLength = ctx.env.usageOptionType ? Math.max(...Object.entries(optionsPairs).map(([key]) => resolveNegatableType(key, ctx).length)) : 0;
-	return (await Promise.all(Object.entries(optionsPairs).map(async ([key, value]) => {
+	const optionsPairsEntries = Object.entries(optionsPairs);
+	if (optionsPairsEntries.length === 0) return "";
+	const optionsMaxLength = Math.max(...optionsPairsEntries.map(([_, value]) => value.length));
+	const optionSchemaMaxLength = ctx.env.usageOptionType ? Math.max(...optionsPairsEntries.map(([key]) => resolveNegatableType(key, ctx).length)) : 0;
+	return (await Promise.all(optionsPairsEntries.map(async ([key, value]) => {
 		let rawDesc = await ctx.extensions[pluginId].text(resolveArgKey(key, ctx.name));
 		if (!rawDesc && key.startsWith("no-")) {
 			const name = resolveNegatableKey(key);
@@ -581,10 +592,11 @@ async function generateOptionalArgsUsage(ctx, optionsPairs) {
 	}))).join("\n");
 }
 function getPositionalArgs(args) {
-	return Object.entries(args).filter(([_, schema]) => schema.type === "positional");
+	return getVisiblePositionalArgs(args);
 }
 async function generatePositionalArgsUsage(ctx) {
 	const positionals = getPositionalArgs(ctx.args);
+	if (positionals.length === 0) return "";
 	const argsMaxLength = Math.max(...positionals.map(([name]) => name.length));
 	return (await Promise.all(positionals.map(async ([name]) => {
 		const desc = await ctx.extensions[pluginId].text(resolveArgKey(name, ctx.name)) || ctx.args[name].description || "";
@@ -593,13 +605,21 @@ async function generatePositionalArgsUsage(ctx) {
 	}))).join("\n");
 }
 function generatePositionalSymbols(args) {
-	return hasPositionalArgs(args) ? getPositionalArgs(args).map(([name, arg]) => {
+	const visiblePositionalArgs = getVisiblePositionalArgs(args);
+	return visiblePositionalArgs.length > 0 ? visiblePositionalArgs.map(([name, arg]) => {
 		const elements = [];
-		if (!arg.multiple || arg.required) elements.push(`<${name}>`);
-		if (arg.multiple) elements.push(`[<${name}> ...]`);
+		if (arg.multiple) {
+			if (arg.required) elements.push(`<${name}>`);
+			elements.push(`[<${name}> ...]`);
+		} else elements.push(isRequiredSinglePositionalArg(arg) ? `<${name}>` : `[<${name}>]`);
 		return elements.join(" ");
 	}).join(" ") : "";
 }
+function isRequiredSinglePositionalArg(arg) {
+	if (arg.required === true) return true;
+	if (arg.required === false) return false;
+	return arg.default == null;
+}
 //#endregion
 //#region src/validation.ts
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin-renderer",
   "description": "usage renderer plugin for gunshi",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -53,10 +53,10 @@
     }
   },
   "dependencies": {
-    "@gunshi/plugin": "0.33.0"
+    "@gunshi/plugin": "0.35.0"
   },
   "peerDependencies": {
-    "@gunshi/plugin-i18n": "0.33.0"
+    "@gunshi/plugin-i18n": "0.35.0"
   },
   "devDependencies": {
     "deno": "^2.7.14",
@@ -64,13 +64,11 @@
     "jsr-exports-lint": "^0.4.2",
     "publint": "^0.3.20",
     "tsdown": "0.21.0",
-    "typedoc": "^0.28.19",
-    "typedoc-plugin-markdown": "^4.11.0",
-    "@gunshi/shared": "0.33.0"
+    "@gunshi/shared": "0.35.0"
   },
   "scripts": {
     "build": "tsdown",
-    "build:docs": "typedoc --excludeInternal",
+    "build:docs": "tsx ../../scripts/api-references.ts",
     "lint:jsr": "jsr publish --dry-run --allow-dirty",
     "typecheck:deno": "deno check --import-map=../../importmap.json ./src"
   }