@optique/core 1.0.0-dev.1901 → 1.0.0-dev.1970

package/dist/execution-context.cjs

@@ -0,0 +1,56 @@
+
+//#region src/execution-context.ts
+/**
+* Appends a child parser segment to the current execution path.
+* @internal
+*/
+function withChildExecPath(exec, segment) {
+	if (exec == null) return void 0;
+	return {
+		...exec,
+		path: [...exec.path ?? [], segment]
+	};
+}
+/**
+* Merges child-owned execution fields back into the parent execution context.
+* @internal
+*/
+function mergeChildExec(parent, child) {
+	if (parent == null) return child;
+	if (child == null) return parent;
+	return {
+		...parent,
+		trace: child.trace ?? parent.trace,
+		dependencyRuntime: child.dependencyRuntime ?? parent.dependencyRuntime,
+		dependencyRegistry: child.dependencyRegistry ?? parent.dependencyRegistry,
+		commandPath: child.commandPath ?? parent.commandPath,
+		preCompletedByParser: child.preCompletedByParser ?? parent.preCompletedByParser,
+		excludedSourceFields: child.excludedSourceFields ?? parent.excludedSourceFields
+	};
+}
+/**
+* Creates a child parser context while keeping flat and nested execution data
+* aligned.
+* @internal
+*/
+function withChildContext(context, segment, state, usage) {
+	const exec = withChildExecPath(context.exec, segment);
+	const dependencyRegistry = context.dependencyRegistry ?? exec?.dependencyRegistry;
+	return {
+		...context,
+		state,
+		...usage != null ? { usage } : {},
+		...exec != null ? {
+			exec: dependencyRegistry === exec.dependencyRegistry ? exec : {
+				...exec,
+				dependencyRegistry
+			},
+			dependencyRegistry
+		} : {}
+	};
+}
+
+//#endregion
+exports.mergeChildExec = mergeChildExec;
+exports.withChildContext = withChildContext;
+exports.withChildExecPath = withChildExecPath;

package/dist/execution-context.js

@@ -0,0 +1,53 @@
+//#region src/execution-context.ts
+/**
+* Appends a child parser segment to the current execution path.
+* @internal
+*/
+function withChildExecPath(exec, segment) {
+	if (exec == null) return void 0;
+	return {
+		...exec,
+		path: [...exec.path ?? [], segment]
+	};
+}
+/**
+* Merges child-owned execution fields back into the parent execution context.
+* @internal
+*/
+function mergeChildExec(parent, child) {
+	if (parent == null) return child;
+	if (child == null) return parent;
+	return {
+		...parent,
+		trace: child.trace ?? parent.trace,
+		dependencyRuntime: child.dependencyRuntime ?? parent.dependencyRuntime,
+		dependencyRegistry: child.dependencyRegistry ?? parent.dependencyRegistry,
+		commandPath: child.commandPath ?? parent.commandPath,
+		preCompletedByParser: child.preCompletedByParser ?? parent.preCompletedByParser,
+		excludedSourceFields: child.excludedSourceFields ?? parent.excludedSourceFields
+	};
+}
+/**
+* Creates a child parser context while keeping flat and nested execution data
+* aligned.
+* @internal
+*/
+function withChildContext(context, segment, state, usage) {
+	const exec = withChildExecPath(context.exec, segment);
+	const dependencyRegistry = context.dependencyRegistry ?? exec?.dependencyRegistry;
+	return {
+		...context,
+		state,
+		...usage != null ? { usage } : {},
+		...exec != null ? {
+			exec: dependencyRegistry === exec.dependencyRegistry ? exec : {
+				...exec,
+				dependencyRegistry
+			},
+			dependencyRegistry
+		} : {}
+	};
+}
+
+//#endregion
+export { mergeChildExec, withChildContext, withChildExecPath };

package/dist/extension.cjs

@@ -0,0 +1,87 @@
+const require_annotations = require('./internal/annotations.cjs');
+const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
+const require_parser = require('./internal/parser.cjs');
+const require_annotation_state = require('./annotation-state.cjs');
+
+//#region src/extension.ts
+const emptyTraits = Object.freeze({});
+/**
+* Defines stable extension traits on a parser object.
+*
+* @param parser The parser object to annotate.
+* @param traits Traits to enable.
+* @throws {TypeError} If a trait property cannot be defined on `parser`.
+* @since 1.0.0
+*/
+function defineTraits(parser, traits) {
+	if (traits.inheritsAnnotations === true) require_parser.defineInheritedAnnotationParser(parser);
+	if (traits.completesFromSource === true) Object.defineProperty(parser, require_parser.unmatchedNonCliDependencySourceStateMarker, {
+		value: true,
+		configurable: true,
+		enumerable: true
+	});
+	if (traits.requiresSourceBinding === true) Object.defineProperty(parser, require_parser.annotationWrapperRequiresSourceBindingKey, {
+		value: true,
+		configurable: true,
+		enumerable: false
+	});
+}
+/**
+* Reads the stable extension traits defined on a parser object.
+*
+* @param parser The parser object to inspect.
+* @returns The enabled traits.  Returns an empty object when none are set.
+* @since 1.0.0
+*/
+function getTraits(parser) {
+	const traits = {
+		...Reflect.get(parser, require_parser.inheritParentAnnotationsKey) === true ? { inheritsAnnotations: true } : {},
+		...Reflect.get(parser, require_parser.unmatchedNonCliDependencySourceStateMarker) === true ? { completesFromSource: true } : {},
+		...Reflect.get(parser, require_parser.annotationWrapperRequiresSourceBindingKey) === true ? { requiresSourceBinding: true } : {}
+	};
+	return Object.keys(traits).length > 0 ? traits : emptyTraits;
+}
+/**
+* Delegates suggest-time runtime nodes to an inner parser while preserving an
+* outer parser's own source metadata node.
+*
+* @param innerParser The wrapped parser that owns the underlying nodes.
+* @param outerParser The outer parser that may contribute its own source node.
+* @param state The outer parser state.
+* @param path The parser path within the parse tree.
+* @param innerState The state to use when collecting inner nodes.
+* @param position Whether the outer node is appended or prepended.
+* @returns The composed runtime nodes.
+* @since 1.0.0
+*/
+function delegateSuggestNodes(innerParser, outerParser, state, path, innerState, position = "append") {
+	return require_parser.getDelegatingSuggestRuntimeNodes(innerParser, outerParser, state, path, innerState, position);
+}
+/**
+* Maps the source capability of a parser's dependency metadata while
+* preserving any derived or transform capabilities unchanged.
+*
+* @param parser The parser whose source metadata should be transformed.
+* @param mapSource Function that transforms the source capability.
+* @returns The dependency metadata with its source capability transformed when
+*          present; otherwise the original dependency metadata, or
+*          `undefined` when the parser has no dependency metadata.
+* @since 1.0.0
+*/
+function mapSourceMetadata(parser, mapSource) {
+	return require_parser.composeWrappedSourceMetadata(parser.dependencyMetadata, mapSource);
+}
+
+//#endregion
+exports.defineTraits = defineTraits;
+exports.delegateSuggestNodes = delegateSuggestNodes;
+exports.dispatchByMode = require_mode_dispatch.dispatchByMode;
+exports.getTraits = getTraits;
+exports.inheritAnnotations = require_annotations.inheritAnnotations;
+exports.injectAnnotations = require_annotations.injectAnnotations;
+exports.isInjectedAnnotationState = require_annotations.isInjectedAnnotationState;
+exports.mapModeValue = require_mode_dispatch.mapModeValue;
+exports.mapSourceMetadata = mapSourceMetadata;
+exports.unwrapInjectedAnnotationState = require_annotations.unwrapInjectedAnnotationState;
+exports.withAnnotationView = require_annotation_state.withAnnotationView;
+exports.wrapForMode = require_mode_dispatch.wrapForMode;

package/dist/extension.d.cts

@@ -0,0 +1,97 @@
+import { inheritAnnotations, injectAnnotations, isInjectedAnnotationState, unwrapInjectedAnnotationState } from "./internal/annotations.cjs";
+import { Mode, Parser } from "./internal/parser.cjs";
+import { withAnnotationView } from "./annotation-state.cjs";
+import { dispatchByMode, mapModeValue, wrapForMode } from "./internal/mode-dispatch.cjs";
+
+//#region src/extension.d.ts
+
+/**
+ * Stable trait flags for custom parser extensions.
+ *
+ * @since 1.0.0
+ */
+interface ParserTraits {
+  /**
+   * Whether parent-state annotations should be injected into rebuilt child
+   * states instead of relying on structural inheritance.
+   */
+  readonly inheritsAnnotations?: true;
+  /**
+   * Whether a missing CLI state can still complete from a source-backed
+   * fallback such as config or environment data.
+   */
+  readonly completesFromSource?: true;
+  /**
+   * Whether annotation-only primitive states should count as completable only
+   * when they come from a nested source-bound parser.
+   */
+  readonly requiresSourceBinding?: true;
+}
+/**
+ * Suggest-time runtime node used to seed dependency-aware completion.
+ *
+ * @since 1.0.0
+ */
+interface SuggestNode {
+  /** Path from the root parser to this node. */
+  readonly path: readonly PropertyKey[];
+  /** The parser whose dependency metadata should be inspected. */
+  readonly parser: Parser<Mode, unknown, unknown>;
+  /** Current parser state for this node. */
+  readonly state: unknown;
+  /** Whether this node reflects explicit input consumption. */
+  readonly matched?: boolean;
+  /** Snapshotted default dependency values for derived parsers. */
+  readonly defaultDependencyValues?: readonly unknown[];
+}
+/**
+ * Public view of a parser's source capability metadata.
+ *
+ * @since 1.0.0
+ */
+type ParserSourceMetadata<M extends Mode = Mode, TValue = unknown, TState = unknown> = NonNullable<NonNullable<Parser<M, TValue, TState>["dependencyMetadata"]>["source"]>;
+/**
+ * Defines stable extension traits on a parser object.
+ *
+ * @param parser The parser object to annotate.
+ * @param traits Traits to enable.
+ * @throws {TypeError} If a trait property cannot be defined on `parser`.
+ * @since 1.0.0
+ */
+declare function defineTraits(parser: object, traits: ParserTraits): void;
+/**
+ * Reads the stable extension traits defined on a parser object.
+ *
+ * @param parser The parser object to inspect.
+ * @returns The enabled traits.  Returns an empty object when none are set.
+ * @since 1.0.0
+ */
+declare function getTraits(parser: object): ParserTraits;
+/**
+ * Delegates suggest-time runtime nodes to an inner parser while preserving an
+ * outer parser's own source metadata node.
+ *
+ * @param innerParser The wrapped parser that owns the underlying nodes.
+ * @param outerParser The outer parser that may contribute its own source node.
+ * @param state The outer parser state.
+ * @param path The parser path within the parse tree.
+ * @param innerState The state to use when collecting inner nodes.
+ * @param position Whether the outer node is appended or prepended.
+ * @returns The composed runtime nodes.
+ * @since 1.0.0
+ */
+declare function delegateSuggestNodes<TInnerState>(innerParser: Parser<Mode, unknown, TInnerState>, outerParser: Parser<Mode, unknown, unknown>, state: unknown, path: readonly PropertyKey[], innerState: TInnerState, position?: "append" | "prepend"): readonly SuggestNode[];
+/**
+ * Maps the source capability of a parser's dependency metadata while
+ * preserving any derived or transform capabilities unchanged.
+ *
+ * @param parser The parser whose source metadata should be transformed.
+ * @param mapSource Function that transforms the source capability.
+ * @returns The dependency metadata with its source capability transformed when
+ *          present; otherwise the original dependency metadata, or
+ *          `undefined` when the parser has no dependency metadata.
+ * @since 1.0.0
+ */
+declare function mapSourceMetadata<M extends Mode, TValue, TState>(parser: Pick<Parser<M, TValue, TState>, "dependencyMetadata">, mapSource: (source: ParserSourceMetadata<M, TValue, TState>) => ParserSourceMetadata<M, TValue, TState>): Parser<M, TValue, TState>["dependencyMetadata"] | undefined;
+//#endregion
+export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateSuggestNodes, dispatchByMode, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/extension.d.ts

@@ -0,0 +1,97 @@
+import { inheritAnnotations, injectAnnotations, isInjectedAnnotationState, unwrapInjectedAnnotationState } from "./internal/annotations.js";
+import { Mode, Parser } from "./internal/parser.js";
+import { withAnnotationView } from "./annotation-state.js";
+import { dispatchByMode, mapModeValue, wrapForMode } from "./internal/mode-dispatch.js";
+
+//#region src/extension.d.ts
+
+/**
+ * Stable trait flags for custom parser extensions.
+ *
+ * @since 1.0.0
+ */
+interface ParserTraits {
+  /**
+   * Whether parent-state annotations should be injected into rebuilt child
+   * states instead of relying on structural inheritance.
+   */
+  readonly inheritsAnnotations?: true;
+  /**
+   * Whether a missing CLI state can still complete from a source-backed
+   * fallback such as config or environment data.
+   */
+  readonly completesFromSource?: true;
+  /**
+   * Whether annotation-only primitive states should count as completable only
+   * when they come from a nested source-bound parser.
+   */
+  readonly requiresSourceBinding?: true;
+}
+/**
+ * Suggest-time runtime node used to seed dependency-aware completion.
+ *
+ * @since 1.0.0
+ */
+interface SuggestNode {
+  /** Path from the root parser to this node. */
+  readonly path: readonly PropertyKey[];
+  /** The parser whose dependency metadata should be inspected. */
+  readonly parser: Parser<Mode, unknown, unknown>;
+  /** Current parser state for this node. */
+  readonly state: unknown;
+  /** Whether this node reflects explicit input consumption. */
+  readonly matched?: boolean;
+  /** Snapshotted default dependency values for derived parsers. */
+  readonly defaultDependencyValues?: readonly unknown[];
+}
+/**
+ * Public view of a parser's source capability metadata.
+ *
+ * @since 1.0.0
+ */
+type ParserSourceMetadata<M extends Mode = Mode, TValue = unknown, TState = unknown> = NonNullable<NonNullable<Parser<M, TValue, TState>["dependencyMetadata"]>["source"]>;
+/**
+ * Defines stable extension traits on a parser object.
+ *
+ * @param parser The parser object to annotate.
+ * @param traits Traits to enable.
+ * @throws {TypeError} If a trait property cannot be defined on `parser`.
+ * @since 1.0.0
+ */
+declare function defineTraits(parser: object, traits: ParserTraits): void;
+/**
+ * Reads the stable extension traits defined on a parser object.
+ *
+ * @param parser The parser object to inspect.
+ * @returns The enabled traits.  Returns an empty object when none are set.
+ * @since 1.0.0
+ */
+declare function getTraits(parser: object): ParserTraits;
+/**
+ * Delegates suggest-time runtime nodes to an inner parser while preserving an
+ * outer parser's own source metadata node.
+ *
+ * @param innerParser The wrapped parser that owns the underlying nodes.
+ * @param outerParser The outer parser that may contribute its own source node.
+ * @param state The outer parser state.
+ * @param path The parser path within the parse tree.
+ * @param innerState The state to use when collecting inner nodes.
+ * @param position Whether the outer node is appended or prepended.
+ * @returns The composed runtime nodes.
+ * @since 1.0.0
+ */
+declare function delegateSuggestNodes<TInnerState>(innerParser: Parser<Mode, unknown, TInnerState>, outerParser: Parser<Mode, unknown, unknown>, state: unknown, path: readonly PropertyKey[], innerState: TInnerState, position?: "append" | "prepend"): readonly SuggestNode[];
+/**
+ * Maps the source capability of a parser's dependency metadata while
+ * preserving any derived or transform capabilities unchanged.
+ *
+ * @param parser The parser whose source metadata should be transformed.
+ * @param mapSource Function that transforms the source capability.
+ * @returns The dependency metadata with its source capability transformed when
+ *          present; otherwise the original dependency metadata, or
+ *          `undefined` when the parser has no dependency metadata.
+ * @since 1.0.0
+ */
+declare function mapSourceMetadata<M extends Mode, TValue, TState>(parser: Pick<Parser<M, TValue, TState>, "dependencyMetadata">, mapSource: (source: ParserSourceMetadata<M, TValue, TState>) => ParserSourceMetadata<M, TValue, TState>): Parser<M, TValue, TState>["dependencyMetadata"] | undefined;
+//#endregion
+export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateSuggestNodes, dispatchByMode, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/extension.js

@@ -0,0 +1,76 @@
+import { inheritAnnotations, injectAnnotations, isInjectedAnnotationState, unwrapInjectedAnnotationState } from "./internal/annotations.js";
+import { dispatchByMode, mapModeValue, wrapForMode } from "./internal/mode-dispatch.js";
+import { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, defineInheritedAnnotationParser, getDelegatingSuggestRuntimeNodes, inheritParentAnnotationsKey, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
+import { withAnnotationView } from "./annotation-state.js";
+
+//#region src/extension.ts
+const emptyTraits = Object.freeze({});
+/**
+* Defines stable extension traits on a parser object.
+*
+* @param parser The parser object to annotate.
+* @param traits Traits to enable.
+* @throws {TypeError} If a trait property cannot be defined on `parser`.
+* @since 1.0.0
+*/
+function defineTraits(parser, traits) {
+	if (traits.inheritsAnnotations === true) defineInheritedAnnotationParser(parser);
+	if (traits.completesFromSource === true) Object.defineProperty(parser, unmatchedNonCliDependencySourceStateMarker, {
+		value: true,
+		configurable: true,
+		enumerable: true
+	});
+	if (traits.requiresSourceBinding === true) Object.defineProperty(parser, annotationWrapperRequiresSourceBindingKey, {
+		value: true,
+		configurable: true,
+		enumerable: false
+	});
+}
+/**
+* Reads the stable extension traits defined on a parser object.
+*
+* @param parser The parser object to inspect.
+* @returns The enabled traits.  Returns an empty object when none are set.
+* @since 1.0.0
+*/
+function getTraits(parser) {
+	const traits = {
+		...Reflect.get(parser, inheritParentAnnotationsKey) === true ? { inheritsAnnotations: true } : {},
+		...Reflect.get(parser, unmatchedNonCliDependencySourceStateMarker) === true ? { completesFromSource: true } : {},
+		...Reflect.get(parser, annotationWrapperRequiresSourceBindingKey) === true ? { requiresSourceBinding: true } : {}
+	};
+	return Object.keys(traits).length > 0 ? traits : emptyTraits;
+}
+/**
+* Delegates suggest-time runtime nodes to an inner parser while preserving an
+* outer parser's own source metadata node.
+*
+* @param innerParser The wrapped parser that owns the underlying nodes.
+* @param outerParser The outer parser that may contribute its own source node.
+* @param state The outer parser state.
+* @param path The parser path within the parse tree.
+* @param innerState The state to use when collecting inner nodes.
+* @param position Whether the outer node is appended or prepended.
+* @returns The composed runtime nodes.
+* @since 1.0.0
+*/
+function delegateSuggestNodes(innerParser, outerParser, state, path, innerState, position = "append") {
+	return getDelegatingSuggestRuntimeNodes(innerParser, outerParser, state, path, innerState, position);
+}
+/**
+* Maps the source capability of a parser's dependency metadata while
+* preserving any derived or transform capabilities unchanged.
+*
+* @param parser The parser whose source metadata should be transformed.
+* @param mapSource Function that transforms the source capability.
+* @returns The dependency metadata with its source capability transformed when
+*          present; otherwise the original dependency metadata, or
+*          `undefined` when the parser has no dependency metadata.
+* @since 1.0.0
+*/
+function mapSourceMetadata(parser, mapSource) {
+	return composeWrappedSourceMetadata(parser.dependencyMetadata, mapSource);
+}
+
+//#endregion
+export { defineTraits, delegateSuggestNodes, dispatchByMode, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/facade.cjs

@@ -1,18 +1,18 @@
-const require_annotations = require('./annotations.cjs');
+const require_annotations = require('./internal/annotations.cjs');
 const require_message = require('./message.cjs');
 const require_completion = require('./completion.cjs');
 const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
-const require_mode_dispatch = require('./mode-dispatch.cjs');
+const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_input_trace = require('./input-trace.cjs');
+const require_parser = require('./internal/parser.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
+const require_constructs = require('./constructs.cjs');
 const require_modifiers = require('./modifiers.cjs');
 const require_valueparser = require('./valueparser.cjs');
 const require_primitives = require('./primitives.cjs');
-const require_parser = require('./parser.cjs');
-const require_constructs = require('./constructs.cjs');
 
 //#region src/facade.ts
 const SuppressedErrorCtor = typeof SuppressedError === "function" ? SuppressedError : (() => {
@@ -390,7 +390,7 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 	const effectiveVersionOptionNames = versionOptionNames ?? ["--version"];
 	if (helpParsers.helpOption) {
 		const lenientHelpParser = {
-			$mode: "sync",
+			mode: "sync",
 			$valueType: [],
 			$stateType: [],
 			priority: 200,
@@ -471,7 +471,7 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 	}
 	if (versionParsers.versionOption) {
 		const lenientVersionParser = {
-			$mode: "sync",
+			mode: "sync",
 			$valueType: [],
 			$stateType: [],
 			priority: 200,
@@ -733,7 +733,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 				sectionOrder
 			}));
 		}
-		return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
+		return require_mode_dispatch.dispatchByMode(parser.mode, () => {
 			const result = callOnError(1);
 			if (result instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
 			return result;
@@ -750,7 +750,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			colors,
 			quotes: !colors
 		}));
-		return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
+		return require_mode_dispatch.dispatchByMode(parser.mode, () => {
 			const result = callOnError(1);
 			if (result instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
 			return result;
@@ -760,13 +760,13 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 		const completionArg = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
 		const script = shell.generateScript(programName, [completionArg, shellName]);
 		stdout(script);
-		return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
+		return require_mode_dispatch.dispatchByMode(parser.mode, () => {
 			const result = callOnCompletion(0);
 			if (result instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
 			return result;
 		}, async () => callOnCompletion(0));
 	}
-	return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
+	return require_mode_dispatch.dispatchByMode(parser.mode, () => {
 		const syncParser = parser;
 		const suggestions = require_parser.suggest(syncParser, args);
 		for (const chunk of shell.encodeSuggestions(suggestions)) stdout(chunk);
@@ -1095,7 +1095,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			default: throw new RunParserError("Unexpected parse result type");
 		}
 	};
-	const parserMode = parser.$mode;
+	const parserMode = parser.mode;
 	return require_mode_dispatch.dispatchByMode(parserMode, () => {
 		const attempted = attemptParseSync(parser, args);
 		const classified = attempted.kind === "success" ? {
@@ -1135,7 +1135,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 * @since 0.9.0
 */
 function runParserSync(parser, programName, args, options) {
-	if (parser.$mode !== "sync") throw new TypeError("Cannot use an async parser with runParserSync(). Use runParser() or runParserAsync() instead.");
+	if (parser.mode !== "sync") throw new TypeError("Cannot use an async parser with runParserSync(). Use runParser() or runParserAsync() instead.");
 	return runParser(parser, programName, args, options);
 }
 /**
@@ -1402,24 +1402,24 @@ async function runWithBody(parser, programName, contexts, args, options) {
 	if (shouldProbeEarlyExit(options, needsTwoPhase)) {
 		const earlyExitParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 		if (await needsEarlyExitAsync(earlyExitParser, args, options)) {
-			if (parser.$mode === "async") return runParser(earlyExitParser, programName, args, options);
+			if (parser.mode === "async") return runParser(earlyExitParser, programName, args, options);
 			return Promise.resolve(runParser(earlyExitParser, programName, args, options));
 		}
 	}
 	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
 	if (!needsTwoPhase) {
-		if (parser.$mode === "async") return runParser(augmentedParser1, programName, args, options);
+		if (parser.mode === "async") return runParser(augmentedParser1, programName, args, options);
 		return Promise.resolve(runParser(augmentedParser1, programName, args, options));
 	}
-	const firstPassSeed = await require_mode_dispatch.dispatchByMode(parser.$mode, () => extractPhase2SeedSync(augmentedParser1, args), () => extractPhase2SeedAsync(augmentedParser1, args));
+	const firstPassSeed = await require_mode_dispatch.dispatchByMode(parser.mode, () => extractPhase2SeedSync(augmentedParser1, args), () => extractPhase2SeedAsync(augmentedParser1, args));
 	if (firstPassSeed == null) {
 		const fallbackParser = injectAnnotationsIntoParser(parser, phase1Annotations);
-		if (parser.$mode === "async") return runParser(fallbackParser, programName, args, options);
+		if (parser.mode === "async") return runParser(fallbackParser, programName, args, options);
 		return Promise.resolve(runParser(fallbackParser, programName, args, options));
 	}
 	const { annotations: finalAnnotations } = await collectFinalAnnotations(contexts, phase1Snapshots, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
 	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
-	if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
+	if (parser.mode === "async") return runParser(augmentedParser2, programName, args, options);
 	return Promise.resolve(runParser(augmentedParser2, programName, args, options));
 }
 /**
@@ -1490,7 +1490,7 @@ async function runWithBody(parser, programName, contexts, args, options) {
 async function runWith(parser, programName, contexts, options) {
 	const args = options?.args ?? [];
 	if (contexts.length === 0) {
-		if (parser.$mode === "async") return runParser(parser, programName, args, options);
+		if (parser.mode === "async") return runParser(parser, programName, args, options);
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
 	let result;
@@ -1567,7 +1567,7 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 * @since 0.10.0
 */
 function runWithSync(parser, programName, contexts, options) {
-	if (parser.$mode !== "sync") throw new TypeError("Cannot use an async parser with runWithSync(). Use runWith() or runWithAsync() instead.");
+	if (parser.mode !== "sync") throw new TypeError("Cannot use an async parser with runWithSync(). Use runWith() or runWithAsync() instead.");
 	const args = options?.args ?? [];
 	if (contexts.length === 0) return runParser(parser, programName, args, options);
 	let result;

package/dist/facade.d.cts

@@ -1,7 +1,7 @@
 import { Message } from "./message.cjs";
 import { HiddenVisibility, OptionName } from "./usage.cjs";
 import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.cjs";
-import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.cjs";
+import { InferMode, InferValue, Mode, ModeValue, Parser } from "./internal/parser.cjs";
 import { ShellCompletion } from "./completion.cjs";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.cjs";
 import { Program } from "./program.cjs";

package/dist/facade.d.ts

@@ -1,7 +1,7 @@
 import { Message } from "./message.js";
 import { HiddenVisibility, OptionName } from "./usage.js";
 import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.js";
-import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.js";
+import { InferMode, InferValue, Mode, ModeValue, Parser } from "./internal/parser.js";
 import { ShellCompletion } from "./completion.js";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.js";
 import { Program } from "./program.js";