@gunshi/bone 0.32.0 → 0.34.0

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.25.0/node_modules/args-tokens/lib/parser-D95CJBHr.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.26.1/node_modules/args-tokens/lib/parser-DT7Ztcch.d.ts
 //#region src/parser.d.ts
 /**
  * Entry point of argument parser.
@@ -55,7 +55,7 @@ interface ArgToken {
  * Parser Options.
  */
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.25.0/node_modules/args-tokens/lib/resolver.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.26.1/node_modules/args-tokens/lib/resolver.d.ts
 //#region src/resolver.d.ts
 /**
  * An argument schema definition for command-line argument parsing.
@@ -172,7 +172,10 @@ interface ArgSchema {
    * When `true`, the argument must be provided by the user.
    * If missing, an `ArgResolveError` with type 'required' will be thrown.
    *
-   * Note: Only `true` is allowed (not `false`) to make intent explicit.
+   * For single-value positional arguments, omitting `required` keeps the argument
+   * required for compatibility. Set `required: false` to make a positional argument
+   * optional. Optional positional arguments leave enough input values for later
+   * required positional arguments before consuming a value.
    *
    * @example
    * Required arguments:
@@ -196,7 +199,8 @@ interface ArgSchema {
    *
    * When `true`, the resolved value becomes an array.
    * For options: can be specified multiple times (--tag foo --tag bar)
-   * For positional: collects remaining positional arguments
+   * For positional: collects remaining positional arguments after preserving values for
+   * later required positional arguments.
    *
    * Note: Only `true` is allowed (not `false`) to make intent explicit.
    *
@@ -276,7 +280,11 @@ interface ArgSchema {
    * - `boolean` type: boolean default
    * - `number` type: number default
    * - `enum` type: must be one of the `choices` values
-   * - `positional`/`custom` type: any appropriate default
+   * - `positional`/`custom` type: string, boolean, or number default
+   *
+   * For single-value positional arguments, the default is used when the positional
+   * value is missing or when the value is preserved for later required positional
+   * arguments, unless `required: true` is set.
    *
    * @example
    * Default values by type:
@@ -533,7 +541,8 @@ type FilterArgs<A extends Args, V extends Record<keyof A, unknown>, K extends ke
  *
  * @internal
  */
-type FilterPositionalArgs<A extends Args, V extends Record<keyof A, unknown>> = { [Arg in keyof A as A[Arg]['type'] extends 'positional' ? Arg : never]: V[Arg] };
+type FilterPositionalArgs<A extends Args, V extends Record<keyof A, unknown>> = { [Arg in keyof A as IsRequiredPositionalArg<A[Arg]> extends true ? Arg : never]: V[Arg] };
+type IsRequiredPositionalArg<A extends ArgSchema> = A['type'] extends 'positional' ? A['multiple'] extends true ? A['required'] extends true ? true : false : A['required'] extends false ? A['default'] extends {} ? true : false : true : false;
 /**
  * An arguments for {@link resolveArgs | resolve arguments}.
  */
@@ -581,15 +590,6 @@ type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean };
  */
 //#endregion
 //#region ../gunshi/src/plugin/context.d.ts
-/**
- * Type helper to create GunshiParams from extracted args and extensions
- *
- * @internal
- */
-type ExtractedParams<G extends GunshiParamsConstraint, L extends Record<string, unknown> = {}> = {
-  args: ExtractArgs<G>;
-  extensions: ExtractExtensions<G> & L;
-};
 /**
  * Gunshi plugin context interface.
  *
@@ -638,7 +638,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    *
    * @param decorator - A decorator function that wraps the base header renderer.
    */
-  decorateHeaderRenderer<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRenderer: (ctx: Readonly<CommandContext<ExtractedParams<G, L>>>) => Promise<string>, ctx: Readonly<CommandContext<ExtractedParams<G, L>>>) => Promise<string>): void;
+  decorateHeaderRenderer<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRenderer: (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Promise<string>, ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Promise<string>): void;
   /**
    * Decorate the usage renderer.
    *
@@ -646,7 +646,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    *
    * @param decorator - A decorator function that wraps the base usage renderer.
    */
-  decorateUsageRenderer<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRenderer: (ctx: Readonly<CommandContext<ExtractedParams<G, L>>>) => Promise<string>, ctx: Readonly<CommandContext<ExtractedParams<G, L>>>) => Promise<string>): void;
+  decorateUsageRenderer<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRenderer: (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Promise<string>, ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Promise<string>): void;
   /**
    * Decorate the validation errors renderer.
    *
@@ -654,7 +654,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    *
    * @param decorator - A decorator function that wraps the base validation errors renderer.
    */
-  decorateValidationErrorsRenderer<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRenderer: (ctx: Readonly<CommandContext<ExtractedParams<G, L>>>, error: AggregateError) => Promise<string>, ctx: Readonly<CommandContext<ExtractedParams<G, L>>>, error: AggregateError) => Promise<string>): void;
+  decorateValidationErrorsRenderer<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRenderer: (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>, error: AggregateError) => Promise<string>, ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>, error: AggregateError) => Promise<string>): void;
   /**
    * Decorate the command execution.
    *
@@ -664,7 +664,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    *
    * @param decorator - A decorator function that wraps the command runner
    */
-  decorateCommand<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRunner: (ctx: Readonly<CommandContext<ExtractedParams<G, L>>>) => Awaitable<void | string>) => (ctx: Readonly<CommandContext<ExtractedParams<G, L>>>) => Awaitable<void | string>): void;
+  decorateCommand<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRunner: (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Awaitable<void | string>) => (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Awaitable<void | string>): void;
 }
 //#endregion
 //#region ../gunshi/src/plugin/core.d.ts
@@ -807,11 +807,37 @@ type ExtractExtensions<G> = G extends GunshiParams<any> ? G['extensions'] : G ex
  * @internal
  */
 type NormalizeToGunshiParams<G> = G extends GunshiParams<any> ? G : G extends {
-  extensions: ExtendContext;
+  args: infer A extends Args;
+  extensions: infer E extends ExtendContext;
+} ? GunshiParams<{
+  args: A;
+  extensions: E;
+}> : G extends {
+  args: infer A extends Args;
+} ? GunshiParams<{
+  args: A;
+  extensions: {};
+}> : G extends {
+  extensions: infer E extends ExtendContext;
 } ? GunshiParams<{
   args: Args;
-  extensions: G['extensions'];
+  extensions: E;
 }> : DefaultGunshiParams;
+/**
+ * Type helper to merge command context extensions into G
+ *
+ * @internal
+ */
+type MergeGunshiExtensions<G extends GunshiParamsConstraint, E extends ExtendContext> = GunshiParams<{
+  /**
+   * Command argument definitions.
+   */
+  args: ExtractArgs<G>;
+  /**
+   * Merged command context extensions.
+   */
+  extensions: ExtractExtensions<G> & E;
+}>;
 /**
  * Command environment.
  *
@@ -1125,7 +1151,7 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
   validationError?: AggregateError;
 }
 /**
- * CommandContextCore type (base type without extensions)
+ * Readonly command context available to a command context extension factory.
  *
  * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
  *
@@ -1456,4 +1482,4 @@ declare function cli<G extends GunshiParams = DefaultGunshiParams>(args: string[
 */
 
 //#endregion
-export { type ArgSchema, type ArgToken, type ArgValues, type Args, Awaitable, CliOptions, Command, CommandCallMode, CommandContext, CommandContextCore, CommandContextExtension, CommandDecorator, CommandEnvironment, CommandExamplesFetcher, CommandLoader, CommandRunner, Commandable, DefaultGunshiParams, ExtendContext, ExtractArgExplicitlyProvided, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, LazyCommand, NormalizeToGunshiParams, Prettify, RendererDecorator, RenderingOptions, SubCommandable, ValidationErrorsDecorator, cli };
+export { type ArgSchema, type ArgToken, type ArgValues, type Args, Awaitable, CliOptions, Command, CommandCallMode, CommandContext, CommandContextCore, CommandContextExtension, CommandDecorator, CommandEnvironment, CommandExamplesFetcher, CommandLoader, CommandRunner, Commandable, DefaultGunshiParams, ExtendContext, ExtractArgExplicitlyProvided, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, LazyCommand, MergeGunshiExtensions, NormalizeToGunshiParams, Prettify, RendererDecorator, RenderingOptions, SubCommandable, ValidationErrorsDecorator, cli };

package/lib/index.js

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.25.0/node_modules/args-tokens/lib/parser.js
+//#region ../../node_modules/.pnpm/args-tokens@0.26.1/node_modules/args-tokens/lib/parser.js
 /**
 * forked from `nodejs/node` (`pkgjs/parseargs`)
 * repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
@@ -203,7 +203,7 @@ function hasOptionValue(value) {
 	return !(value == null) && value.codePointAt(0) !== HYPHEN_CODE;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.25.0/node_modules/args-tokens/lib/utils.js
+//#region ../../node_modules/.pnpm/args-tokens@0.26.1/node_modules/args-tokens/lib/utils.js
 /**
 * Entry point of utils.
 *
@@ -225,7 +225,7 @@ function kebabnize(str) {
 	return str.replace(/[A-Z]/g, (match, offset) => (offset > 0 ? "-" : "") + match.toLowerCase());
 }
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.25.0/node_modules/args-tokens/lib/resolver.js
+//#region ../../node_modules/.pnpm/args-tokens@0.26.1/node_modules/args-tokens/lib/resolver.js
 /**
 * Entry point of argument options resolver.
 *
@@ -368,6 +368,8 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 	const errors = [];
 	const explicit = Object.create(null);
 	const actualInputNames = /* @__PURE__ */ new Map();
+	const argEntries = Object.entries(args);
+	let requiredPositionalsAfter;
 	function checkTokenName(option, schema, token) {
 		return token.name === (schema.type === "boolean" ? schema.negatable && token.name?.startsWith("no-") ? `no-${option}` : option : option);
 	}
@@ -375,14 +377,21 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 	function getPositionalSkipIndex() {
 		return Math.min(skipPositionalIndex, positionalItemCount);
 	}
+	function getRequiredPositionalsAfter(rawArg) {
+		requiredPositionalsAfter ??= createRequiredPositionalsAfter(argEntries);
+		return requiredPositionalsAfter[rawArg] ?? 0;
+	}
 	let positionalsCount = 0;
-	for (const [rawArg, schema] of Object.entries(args)) {
+	for (const [rawArg, schema] of argEntries) {
 		const arg = toKebab || schema.toKebab ? kebabnize(rawArg) : rawArg;
 		explicit[rawArg] = false;
 		if (schema.type === "positional") {
 			if (skipPositionalIndex > SKIP_POSITIONAL_DEFAULT) while (positionalsCount <= getPositionalSkipIndex()) positionalsCount++;
+			const requiredPositionals = getRequiredPositionalsAfter(rawArg);
+			const availablePositionals = Math.max(positionalTokens.length - positionalsCount, 0);
 			if (schema.multiple) {
-				const remainingPositionals = positionalTokens.slice(positionalsCount);
+				const positionalsToConsume = Math.max(availablePositionals - requiredPositionals, 0);
+				const remainingPositionals = positionalTokens.slice(positionalsCount, positionalsCount + positionalsToConsume);
 				if (remainingPositionals.length > 0) {
 					if (typeof schema.parse === "function") {
 						const parsed = [];
@@ -398,7 +407,7 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 				} else if (schema.required) errors.push(createRequireError(arg, schema));
 			} else {
 				const positional = positionalTokens[positionalsCount];
-				if (positional != null) {
+				if (positional != null && (shouldRequireMissingSinglePositional(schema) || availablePositionals > requiredPositionals)) {
 					if (typeof schema.parse === "function") try {
 						values[rawArg] = schema.parse(positional.value);
 					} catch (error) {
@@ -406,8 +415,9 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 					}
 					else values[rawArg] = positional.value;
 					explicit[rawArg] = true;
-				} else errors.push(createRequireError(arg, schema));
-				positionalsCount++;
+					positionalsCount++;
+				} else if (shouldRequireMissingSinglePositional(schema)) errors.push(createRequireError(arg, schema));
+				else if (hasDefault(schema)) values[rawArg] = schema.default;
 			}
 			continue;
 		}
@@ -476,6 +486,30 @@ function parse(token, option, schema) {
 function createRequireError(option, schema) {
 	return new ArgResolveError(schema.type === "positional" ? `Positional argument '${option}' is required` : `Optional argument '--${option}' ${schema.short ? `or '-${schema.short}' ` : ""}is required`, option, "required", schema);
 }
+function hasDefault(schema) {
+	return schema.default != null;
+}
+function shouldRequireMissingSinglePositional(schema) {
+	if (schema.required === true) return true;
+	if (schema.required === false) return false;
+	return !hasDefault(schema);
+}
+function getRequiredPositionalInputCount(schema) {
+	if (schema.type !== "positional") return 0;
+	if (schema.multiple) return schema.required === true ? 1 : 0;
+	return shouldRequireMissingSinglePositional(schema) ? 1 : 0;
+}
+function createRequiredPositionalsAfter(argEntries) {
+	const requiredPositionalsAfter = Object.create(null);
+	let minimumRequiredPositionals = 0;
+	for (let i = argEntries.length - 1; i >= 0; i--) {
+		const [rawArg, schema] = argEntries[i];
+		if (schema.type !== "positional") continue;
+		requiredPositionalsAfter[rawArg] = minimumRequiredPositionals;
+		minimumRequiredPositionals += getRequiredPositionalInputCount(schema);
+	}
+	return requiredPositionalsAfter;
+}
 /**
 * An error that occurs when resolving arguments.
 * This error is thrown when the argument is not valid.
@@ -525,7 +559,7 @@ function checkConflicts(args, explicit, toKebab, actualInputNames) {
 	return [];
 }
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.25.0/node_modules/args-tokens/lib/index.js
+//#region ../../node_modules/.pnpm/args-tokens@0.26.1/node_modules/args-tokens/lib/index.js
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/bone",
   "description": "gunshi minimum",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -56,10 +56,10 @@
     "jsr-exports-lint": "^0.4.2",
     "publint": "^0.3.20",
     "tsdown": "0.21.0",
-    "@gunshi/definition": "0.32.0",
-    "@gunshi/plugin-global": "0.32.0",
-    "@gunshi/plugin-renderer": "0.32.0",
-    "gunshi": "0.32.0"
+    "@gunshi/definition": "0.34.0",
+    "@gunshi/plugin-renderer": "0.34.0",
+    "gunshi": "0.34.0",
+    "@gunshi/plugin-global": "0.34.0"
   },
   "scripts": {
     "build": "tsdown",