@optique/core 1.3.0-dev.2488 → 1.3.0-dev.2491

package/dist/internal/parser.js

@@ -2,7 +2,7 @@ import { hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInje
 import { cloneMessage, message } from "../message.js";
 import { cloneUsage, normalizeUsage } from "../usage.js";
 import { cloneDocEntry, isDocEntryHidden } from "../doc.js";
-import { dispatchByMode } from "./mode-dispatch.js";
+import { dispatchByMode, dispatchParserByMode } from "./mode-dispatch.js";
 import { collectExplicitSourceValues, collectExplicitSourceValuesAsync, createDependencyRuntimeContext } from "../dependency-runtime.js";
 import { createInputTrace } from "../input-trace.js";
 
@@ -91,6 +91,160 @@ function createParserContext(frame, exec) {
 function injectAnnotationsIntoState(state, options) {
 	return injectAnnotations(state, options?.annotations);
 }
+function getFailureProgress(args, buffer, consumedInStep) {
+	return {
+		remainingArgs: buffer.slice(consumedInStep),
+		consumedCount: args.length - buffer.length + consumedInStep
+	};
+}
+function createParseExec(parser) {
+	return {
+		usage: parser.usage,
+		phase: "parse",
+		path: [],
+		commandPath: [],
+		trace: createInputTrace()
+	};
+}
+function getCommandPath(exec) {
+	return [...exec?.commandPath ?? []];
+}
+function createCompleteExec(exec, context, session) {
+	const runtime = createDependencyRuntimeContext();
+	return {
+		...exec,
+		phase: "complete",
+		dependencyRuntime: runtime,
+		dependencyRegistry: runtime.registry,
+		commandPath: context.exec?.commandPath ?? exec.commandPath,
+		trace: context.exec?.trace ?? context.trace ?? exec.trace,
+		effectfulCompletionSession: session ?? createEffectfulCompletionSession()
+	};
+}
+function attemptParseSync(parser, args, options = {}) {
+	const initialState = injectAnnotationsIntoState(parser.initialState, options.parseOptions);
+	const shouldUnwrapAnnotatedValue = hasMeaningfulAnnotations(options.parseOptions?.annotations) || isInjectedAnnotationWrapper(parser.initialState);
+	const exec = createParseExec(parser);
+	let context = createParserContext({
+		buffer: [...args],
+		state: initialState,
+		optionsTerminated: false
+	}, exec);
+	do {
+		const result = parser.parse(context);
+		if (!result.success) {
+			const progress = getFailureProgress(args, context.buffer, result.consumed);
+			return {
+				kind: "failure",
+				error: result.error,
+				remainingArgs: progress.remainingArgs,
+				consumedCount: progress.consumedCount,
+				optionsTerminated: context.optionsTerminated,
+				commandPath: getCommandPath(context.exec)
+			};
+		}
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) {
+			const progress = getFailureProgress(args, previousBuffer, result.consumed.length);
+			return {
+				kind: "failure",
+				error: message`Unexpected option or argument: ${context.buffer[0]}.`,
+				remainingArgs: progress.remainingArgs,
+				consumedCount: progress.consumedCount,
+				optionsTerminated: context.optionsTerminated,
+				commandPath: getCommandPath(context.exec)
+			};
+		}
+	} while (context.buffer.length > 0);
+	if (options.mode === "parse-only") return {
+		kind: "success",
+		result: {
+			success: true,
+			value: void 0
+		}
+	};
+	const endResult = parser.complete(context.state, createCompleteExec(exec, context, options.session));
+	if (!endResult.success) return {
+		kind: "failure",
+		error: endResult.error,
+		remainingArgs: [],
+		consumedCount: args.length,
+		optionsTerminated: context.optionsTerminated,
+		commandPath: getCommandPath(context.exec)
+	};
+	return {
+		kind: "success",
+		result: {
+			success: true,
+			value: shouldUnwrapAnnotatedValue ? unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
+			...endResult.deferred ? { deferred: true } : {},
+			...endResult.deferredKeys ? { deferredKeys: endResult.deferredKeys } : {}
+		}
+	};
+}
+async function attemptParseAsync(parser, args, options = {}) {
+	const initialState = injectAnnotationsIntoState(parser.initialState, options.parseOptions);
+	const shouldUnwrapAnnotatedValue = hasMeaningfulAnnotations(options.parseOptions?.annotations) || isInjectedAnnotationWrapper(parser.initialState);
+	const exec = createParseExec(parser);
+	let context = createParserContext({
+		buffer: [...args],
+		state: initialState,
+		optionsTerminated: false
+	}, exec);
+	do {
+		const result = await parser.parse(context);
+		if (!result.success) {
+			const progress = getFailureProgress(args, context.buffer, result.consumed);
+			return {
+				kind: "failure",
+				error: result.error,
+				remainingArgs: progress.remainingArgs,
+				consumedCount: progress.consumedCount,
+				optionsTerminated: context.optionsTerminated,
+				commandPath: getCommandPath(context.exec)
+			};
+		}
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) {
+			const progress = getFailureProgress(args, previousBuffer, result.consumed.length);
+			return {
+				kind: "failure",
+				error: message`Unexpected option or argument: ${context.buffer[0]}.`,
+				remainingArgs: progress.remainingArgs,
+				consumedCount: progress.consumedCount,
+				optionsTerminated: context.optionsTerminated,
+				commandPath: getCommandPath(context.exec)
+			};
+		}
+	} while (context.buffer.length > 0);
+	if (options.mode === "parse-only") return {
+		kind: "success",
+		result: {
+			success: true,
+			value: void 0
+		}
+	};
+	const endResult = await parser.complete(context.state, createCompleteExec(exec, context, options.session));
+	if (!endResult.success) return {
+		kind: "failure",
+		error: endResult.error,
+		remainingArgs: [],
+		consumedCount: args.length,
+		optionsTerminated: context.optionsTerminated,
+		commandPath: getCommandPath(context.exec)
+	};
+	return {
+		kind: "success",
+		result: {
+			success: true,
+			value: shouldUnwrapAnnotatedValue ? unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
+			...endResult.deferred ? { deferred: true } : {},
+			...endResult.deferredKeys ? { deferredKeys: endResult.deferredKeys } : {}
+		}
+	};
+}
 /**
 * Parses an array of command-line arguments using the provided combined parser.
 * This function processes the input arguments, applying the parser to each
@@ -116,51 +270,10 @@ function injectAnnotationsIntoState(state, options) {
 * @since 0.10.0 Added optional `options` parameter for annotations support.
 */
 function parseSync(parser, args, options) {
-	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	const shouldUnwrapAnnotatedValue = hasMeaningfulAnnotations(options?.annotations) || isInjectedAnnotationWrapper(parser.initialState);
-	const exec = {
-		usage: parser.usage,
-		phase: "parse",
-		path: [],
-		trace: createInputTrace()
-	};
-	let context = createParserContext({
-		buffer: args,
-		state: initialState,
-		optionsTerminated: false
-	}, exec);
-	do {
-		const result = parser.parse(context);
-		if (!result.success) return {
-			success: false,
-			error: result.error
-		};
-		const previousBuffer = context.buffer;
-		context = result.next;
-		if (isBufferUnchanged(previousBuffer, context.buffer)) return {
-			success: false,
-			error: message`Unexpected option or argument: ${context.buffer[0]}.`
-		};
-	} while (context.buffer.length > 0);
-	const runtime = createDependencyRuntimeContext();
-	const completeExec = {
-		...exec,
-		phase: "complete",
-		dependencyRuntime: runtime,
-		dependencyRegistry: runtime.registry,
-		commandPath: context.exec?.commandPath ?? exec.commandPath,
-		trace: context.exec?.trace ?? context.trace ?? exec.trace,
-		effectfulCompletionSession: createEffectfulCompletionSession()
-	};
-	const endResult = parser.complete(context.state, completeExec);
-	return endResult.success ? {
-		success: true,
-		value: shouldUnwrapAnnotatedValue ? unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
-		...endResult.deferred ? { deferred: true } : {},
-		...endResult.deferredKeys ? { deferredKeys: endResult.deferredKeys } : {}
-	} : {
+	const attempted = attemptParseSync(parser, args, { parseOptions: options });
+	return attempted.kind === "success" ? attempted.result : {
 		success: false,
-		error: endResult.error
+		error: attempted.error
 	};
 }
 /**
@@ -190,52 +303,47 @@ function isBufferUnchanged(previous, current) {
 * @since 0.10.0 Added optional `options` parameter for annotations support.
 */
 async function parseAsync(parser, args, options) {
-	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	const shouldUnwrapAnnotatedValue = hasMeaningfulAnnotations(options?.annotations) || isInjectedAnnotationWrapper(parser.initialState);
-	const exec = {
-		usage: parser.usage,
-		phase: "parse",
-		path: [],
-		trace: createInputTrace()
+	const attempted = await attemptParseAsync(parser, args, { parseOptions: options });
+	return attempted.kind === "success" ? attempted.result : {
+		success: false,
+		error: attempted.error
 	};
-	let context = createParserContext({
-		buffer: args,
-		state: initialState,
-		optionsTerminated: false
-	}, exec);
-	do {
-		const result = await parser.parse(context);
-		if (!result.success) return {
+}
+/**
+* Parses a complete argument list while preserving failure progress.
+*
+* The return mode follows the parser: synchronous parsers return immediately,
+* while asynchronous parsers return a promise.  Use this lower-level API when
+* a caller needs the unconsumed argument suffix or matched command path.
+*
+* @template M The execution mode of the parser.
+* @template T The type of the value produced by the parser.
+* @param parser The parser to run.
+* @param args The complete argument list to parse.
+* @param options Optional parsing annotations.
+* @returns A detailed success or failure result in the parser's mode.
+* @throws {TypeError} When a synchronous dependency source extractor returns a
+*         thenable during completion-time dependency seeding.
+* @since 1.3.0
+*/
+function parseDetailed(parser, args, options) {
+	return dispatchParserByMode(parser, (parser$1) => {
+		const attempted = attemptParseSync(parser$1, args, { parseOptions: options });
+		return attempted.kind === "success" ? attempted.result : {
 			success: false,
-			error: result.error
+			error: attempted.error,
+			remainingArgs: attempted.remainingArgs,
+			commandPath: attempted.commandPath
 		};
-		const previousBuffer = context.buffer;
-		context = result.next;
-		if (isBufferUnchanged(previousBuffer, context.buffer)) return {
+	}, async (parser$1) => {
+		const attempted = await attemptParseAsync(parser$1, args, { parseOptions: options });
+		return attempted.kind === "success" ? attempted.result : {
 			success: false,
-			error: message`Unexpected option or argument: ${context.buffer[0]}.`
+			error: attempted.error,
+			remainingArgs: attempted.remainingArgs,
+			commandPath: attempted.commandPath
 		};
-	} while (context.buffer.length > 0);
-	const runtime = createDependencyRuntimeContext();
-	const completeExec = {
-		...exec,
-		phase: "complete",
-		dependencyRuntime: runtime,
-		dependencyRegistry: runtime.registry,
-		commandPath: context.exec?.commandPath ?? exec.commandPath,
-		trace: context.exec?.trace ?? context.trace ?? exec.trace,
-		effectfulCompletionSession: createEffectfulCompletionSession()
-	};
-	const endResult = await parser.complete(context.state, completeExec);
-	return endResult.success ? {
-		success: true,
-		value: shouldUnwrapAnnotatedValue ? unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
-		...endResult.deferred ? { deferred: true } : {},
-		...endResult.deferredKeys ? { deferredKeys: endResult.deferredKeys } : {}
-	} : {
-		success: false,
-		error: endResult.error
-	};
+	});
 }
 /**
 * Parses an array of command-line arguments using the provided combined parser.
@@ -903,4 +1011,4 @@ function findNextMatchedCommandArgIndex(args, matchedCommandArgIndices, start) {
 }
 
 //#endregion
-export { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createEffectfulCompletionSession, createParserContext, defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getOwnParseLanes, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseLanesKey, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };
+export { annotationWrapperRequiresSourceBindingKey, attemptParseAsync, attemptParseSync, composeWrappedSourceMetadata, createEffectfulCompletionSession, createParserContext, defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getOwnParseLanes, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseDetailed, parseLanesKey, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };

package/dist/parser.cjs

@@ -6,6 +6,7 @@ exports.getDocPageAsync = require_internal_parser.getDocPageAsync;
 exports.getDocPageSync = require_internal_parser.getDocPageSync;
 exports.parse = require_internal_parser.parse;
 exports.parseAsync = require_internal_parser.parseAsync;
+exports.parseDetailed = require_internal_parser.parseDetailed;
 exports.parseSync = require_internal_parser.parseSync;
 exports.suggest = require_internal_parser.suggest;
 exports.suggestAsync = require_internal_parser.suggestAsync;

package/dist/parser.d.cts

@@ -1,3 +1,3 @@
 import { ParseOptions } from "./internal/annotations.cjs";
-import { CombineModes, DocState, EffectfulCompletionSession, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.cjs";
-export { type CombineModes, type DocState, type EffectfulCompletionSession, type ExecutionContext, type ExecutionPhase, type InferMode, type InferValue, type Mode, type ModeIterable, type ModeValue, type ParseFrame, type ParseOptions, type Parser, type ParserContext, type ParserResult, type Result, type Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync };
+import { CombineModes, DetailedParseResult, DocState, EffectfulCompletionSession, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseDetailed, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.cjs";
+export { type CombineModes, type DetailedParseResult, type DocState, type EffectfulCompletionSession, type ExecutionContext, type ExecutionPhase, type InferMode, type InferValue, type Mode, type ModeIterable, type ModeValue, type ParseFrame, type ParseOptions, type Parser, type ParserContext, type ParserResult, type Result, type Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseDetailed, parseSync, suggest, suggestAsync, suggestSync };

package/dist/parser.d.ts

@@ -1,3 +1,3 @@
 import { ParseOptions } from "./internal/annotations.js";
-import { CombineModes, DocState, EffectfulCompletionSession, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
-export { type CombineModes, type DocState, type EffectfulCompletionSession, type ExecutionContext, type ExecutionPhase, type InferMode, type InferValue, type Mode, type ModeIterable, type ModeValue, type ParseFrame, type ParseOptions, type Parser, type ParserContext, type ParserResult, type Result, type Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync };
+import { CombineModes, DetailedParseResult, DocState, EffectfulCompletionSession, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseDetailed, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
+export { type CombineModes, type DetailedParseResult, type DocState, type EffectfulCompletionSession, type ExecutionContext, type ExecutionPhase, type InferMode, type InferValue, type Mode, type ModeIterable, type ModeValue, type ParseFrame, type ParseOptions, type Parser, type ParserContext, type ParserResult, type Result, type Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseDetailed, parseSync, suggest, suggestAsync, suggestSync };

package/dist/parser.js

@@ -1,3 +1,3 @@
-import { createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
+import { createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseDetailed, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
 
-export { createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync };
+export { createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseDetailed, parseSync, suggest, suggestAsync, suggestSync };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.3.0-dev.2488",
+  "version": "1.3.0-dev.2491",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -221,7 +221,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.3.0-dev.2488+14f7b46a",
+    "@optique/env": "1.3.0-dev.2491+0b23bdcf",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -22,11 +22,11 @@ they cover the parts agents most often get wrong.
 Core rules
 ----------
 
- -  Use `run()` from *@optique/run* for real CLI applications. It reads
-    `process.argv`/`Deno.args`, handles help, version output, errors, exit
-    codes, colors, terminal width, and shell completion. Use `parse()` from
-    `@optique/core/parser` or `runParser()` from `@optique/core/facade` when
-    embedding Optique in tests, libraries, tools, or custom runtimes.
+ -  Use `run()` from *@optique/run* for applications; use `parse()` or
+    `runParser()` for embedded and custom runtimes.
+ -  In parser-focused tests, use `parseArgs()` or `parseArgsSync()` from
+    *@optique/testing/parser* for inferred values and detailed failures without
+    running help, output, exits, or command handlers.
  -  Compose parsers with `object()`, `tuple()`, `seq()`, `or()`, `merge()`, and
     modifiers. Do not write imperative `if`/`else` argument scanners around
     Optique parsers.