@gunshi/bone 0.33.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}.
  */

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.33.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/plugin-renderer": "0.33.0",
-    "gunshi": "0.33.0",
-    "@gunshi/plugin-global": "0.33.0",
-    "@gunshi/definition": "0.33.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",