@optique/core 1.0.0-dev.1808 → 1.0.0-dev.1818

package/dist/parser.d.ts

@@ -378,6 +378,16 @@ interface ExecutionContext {
    * resolution and completion.
    */
   readonly path: readonly PropertyKey[];
+  /**
+   * Matched command names in parse order.
+   *
+   * This is tracked separately from {@link path} because parse-tree paths also
+   * include object fields and other wrapper segments.  Runners use it to
+   * recover subcommand help context from partial parses.
+   *
+   * @internal
+   */
+  readonly commandPath?: readonly string[];
   /**
    * Immutable trace of raw primitive inputs recorded during parsing.
    *

package/dist/primitives.cjs

@@ -33,6 +33,7 @@ function mergeChildExec(parent, child) {
 		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
 	};
@@ -1180,6 +1181,13 @@ function getCommandChildState(commandState, childState, parser) {
 function createCommandState(sourceState, state) {
 	return require_annotations.annotateFreshArray(sourceState, state);
 }
+function appendCommandPath(exec, name) {
+	if (exec == null) return void 0;
+	return {
+		...exec,
+		commandPath: [...exec.commandPath ?? [], name]
+	};
+}
 function* suggestCommandSync(context, prefix, name, parser, options) {
 	if (require_usage.isSuggestionHidden(options.hidden)) return;
 	const state = normalizeCommandState(context.state);
@@ -1293,7 +1301,8 @@ function command(name, parser, options = {}) {
 					next: {
 						...context,
 						buffer: context.buffer.slice(1),
-						state: createCommandState(context.state, ["matched", name])
+						state: createCommandState(context.state, ["matched", name]),
+						...context.exec != null ? { exec: appendCommandPath(context.exec, name) } : {}
 					},
 					consumed: context.buffer.slice(0, 1)
 				};

package/dist/primitives.js

@@ -33,6 +33,7 @@ function mergeChildExec(parent, child) {
 		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
 	};
@@ -1180,6 +1181,13 @@ function getCommandChildState(commandState, childState, parser) {
 function createCommandState(sourceState, state) {
 	return annotateFreshArray(sourceState, state);
 }
+function appendCommandPath(exec, name) {
+	if (exec == null) return void 0;
+	return {
+		...exec,
+		commandPath: [...exec.commandPath ?? [], name]
+	};
+}
 function* suggestCommandSync(context, prefix, name, parser, options) {
 	if (isSuggestionHidden(options.hidden)) return;
 	const state = normalizeCommandState(context.state);
@@ -1293,7 +1301,8 @@ function command(name, parser, options = {}) {
 					next: {
 						...context,
 						buffer: context.buffer.slice(1),
-						state: createCommandState(context.state, ["matched", name])
+						state: createCommandState(context.state, ["matched", name]),
+						...context.exec != null ? { exec: appendCommandPath(context.exec, name) } : {}
 					},
 					consumed: context.buffer.slice(0, 1)
 				};

package/dist/validate.cjs

@@ -63,27 +63,22 @@ function validateCommandNames(names, label) {
 	}
 }
 /**
-* Validates that there are no name collisions among meta features
-* (help, version, completion) and between meta features and user parsers.
+* Validates that there are no name collisions among active meta features
+* (help, version, completion).
 *
-* The collision check is *position-aware*:
-*
-* - Meta **command** entries match at `args[0]` only, so they are checked
-*   against *leading* user names (those reachable before any positional gate).
-* - Meta **option** entries use lenient scanners that match anywhere in
-*   `argv`, so they are checked against *all* user names at every depth,
-*   including literal values from conditional discriminators.
+* User parser names are accepted even when they overlap with meta names.
+* Runtime parsing resolves those cases parser-first so ordinary parser data
+* can shadow built-in meta behavior.
 *
 * Meta-vs-meta collisions are always checked in a unified namespace,
 * because a meta command named `"--help"` and a meta option named
 * `"--help"` both compete for the same token.
 *
-* @param userNames User parser names extracted at different scopes.
 * @param metaEntries Active meta feature entries annotated with their kind.
-* @throws {TypeError} If any collision or duplicate is detected.
+* @throws {TypeError} If any meta/meta collision or duplicate is detected.
 * @since 1.0.0
 */
-function validateMetaNameCollisions(userNames, metaEntries) {
+function validateMetaNameCollisions(metaEntries) {
 	for (const [, label, names] of metaEntries) {
 		const seen = /* @__PURE__ */ new Set();
 		for (const name of names) {
@@ -112,33 +107,6 @@ function validateMetaNameCollisions(userNames, metaEntries) {
 			}
 		}
 	}
-	for (const [kind, label, names, prefixMatch] of metaEntries) for (const name of names) {
-		if (kind === "command") {
-			if (userNames.leadingNames.has(name)) if (userNames.allOptions.has(name)) throw new TypeError(`User-defined option "${name}" conflicts with the built-in ${label}.`);
-			else if (userNames.allCommands.has(name)) throw new TypeError(`User-defined command "${name}" conflicts with the built-in ${label}.`);
-			else if (userNames.allLiterals.has(name)) throw new TypeError(`Literal value "${name}" conflicts with the built-in ${label}.`);
-			else throw new TypeError(`User-defined name "${name}" conflicts with the built-in ${label}.`);
-		} else {
-			if (userNames.allOptions.has(name)) throw new TypeError(`User-defined option "${name}" conflicts with the built-in ${label}.`);
-			if (userNames.allCommands.has(name)) throw new TypeError(`User-defined command "${name}" conflicts with the built-in ${label}.`);
-			if (userNames.allLiterals.has(name)) throw new TypeError(`Literal value "${name}" conflicts with the built-in ${label}.`);
-		}
-		if (prefixMatch) {
-			const prefix = name + "=";
-			const checkSets = kind === "command" ? [userNames.leadingNames] : [
-				userNames.allOptions,
-				userNames.allCommands,
-				userNames.allLiterals
-			];
-			for (const nameSet of checkSets) for (const userName of nameSet) {
-				if (!userName.startsWith(prefix)) continue;
-				if (userNames.allOptions.has(userName)) throw new TypeError(`User-defined option "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
-				else if (userNames.allCommands.has(userName)) throw new TypeError(`User-defined command "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
-				else if (userNames.allLiterals.has(userName)) throw new TypeError(`Literal value "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
-				else throw new TypeError(`User-defined name "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
-			}
-		}
-	}
 }
 function capitalize(s) {
 	return s.charAt(0).toUpperCase() + s.slice(1);

package/dist/validate.js

@@ -62,27 +62,22 @@ function validateCommandNames(names, label) {
 	}
 }
 /**
-* Validates that there are no name collisions among meta features
-* (help, version, completion) and between meta features and user parsers.
+* Validates that there are no name collisions among active meta features
+* (help, version, completion).
 *
-* The collision check is *position-aware*:
-*
-* - Meta **command** entries match at `args[0]` only, so they are checked
-*   against *leading* user names (those reachable before any positional gate).
-* - Meta **option** entries use lenient scanners that match anywhere in
-*   `argv`, so they are checked against *all* user names at every depth,
-*   including literal values from conditional discriminators.
+* User parser names are accepted even when they overlap with meta names.
+* Runtime parsing resolves those cases parser-first so ordinary parser data
+* can shadow built-in meta behavior.
 *
 * Meta-vs-meta collisions are always checked in a unified namespace,
 * because a meta command named `"--help"` and a meta option named
 * `"--help"` both compete for the same token.
 *
-* @param userNames User parser names extracted at different scopes.
 * @param metaEntries Active meta feature entries annotated with their kind.
-* @throws {TypeError} If any collision or duplicate is detected.
+* @throws {TypeError} If any meta/meta collision or duplicate is detected.
 * @since 1.0.0
 */
-function validateMetaNameCollisions(userNames, metaEntries) {
+function validateMetaNameCollisions(metaEntries) {
 	for (const [, label, names] of metaEntries) {
 		const seen = /* @__PURE__ */ new Set();
 		for (const name of names) {
@@ -111,33 +106,6 @@ function validateMetaNameCollisions(userNames, metaEntries) {
 			}
 		}
 	}
-	for (const [kind, label, names, prefixMatch] of metaEntries) for (const name of names) {
-		if (kind === "command") {
-			if (userNames.leadingNames.has(name)) if (userNames.allOptions.has(name)) throw new TypeError(`User-defined option "${name}" conflicts with the built-in ${label}.`);
-			else if (userNames.allCommands.has(name)) throw new TypeError(`User-defined command "${name}" conflicts with the built-in ${label}.`);
-			else if (userNames.allLiterals.has(name)) throw new TypeError(`Literal value "${name}" conflicts with the built-in ${label}.`);
-			else throw new TypeError(`User-defined name "${name}" conflicts with the built-in ${label}.`);
-		} else {
-			if (userNames.allOptions.has(name)) throw new TypeError(`User-defined option "${name}" conflicts with the built-in ${label}.`);
-			if (userNames.allCommands.has(name)) throw new TypeError(`User-defined command "${name}" conflicts with the built-in ${label}.`);
-			if (userNames.allLiterals.has(name)) throw new TypeError(`Literal value "${name}" conflicts with the built-in ${label}.`);
-		}
-		if (prefixMatch) {
-			const prefix = name + "=";
-			const checkSets = kind === "command" ? [userNames.leadingNames] : [
-				userNames.allOptions,
-				userNames.allCommands,
-				userNames.allLiterals
-			];
-			for (const nameSet of checkSets) for (const userName of nameSet) {
-				if (!userName.startsWith(prefix)) continue;
-				if (userNames.allOptions.has(userName)) throw new TypeError(`User-defined option "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
-				else if (userNames.allCommands.has(userName)) throw new TypeError(`User-defined command "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
-				else if (userNames.allLiterals.has(userName)) throw new TypeError(`Literal value "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
-				else throw new TypeError(`User-defined name "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
-			}
-		}
-	}
 }
 function capitalize(s) {
 	return s.charAt(0).toUpperCase() + s.slice(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1808+e840dccd",
+  "version": "1.0.0-dev.1818+1aa43bd4",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",