@optique/core 1.0.0-dev.1514 → 1.0.0-dev.1523

package/dist/validate.cjs

@@ -63,6 +63,75 @@ function validateCommandNames(names, label) {
 	}
 }
 /**
+* Validates that there are no name collisions among meta features
+* (help, version, completion) and between meta features and user parsers.
+*
+* 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.
+*
+* 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.
+* @since 1.0.0
+*/
+function validateMetaNameCollisions(userNames, metaEntries) {
+	for (const [, label, names] of metaEntries) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const name of names) {
+			if (seen.has(name)) throw new TypeError(`${capitalize(label)} has a duplicate name: "${name}"`);
+			seen.add(name);
+		}
+	}
+	const nameToLabel = /* @__PURE__ */ new Map();
+	for (const [, label, names] of metaEntries) for (const name of names) {
+		const existingLabel = nameToLabel.get(name);
+		if (existingLabel != null) throw new TypeError(`Name "${name}" is used by both ${existingLabel} and ${label}.`);
+		nameToLabel.set(name, label);
+	}
+	for (let i = 0; i < metaEntries.length; i++) {
+		const [, label, names, prefixMatch] = metaEntries[i];
+		if (!prefixMatch) continue;
+		for (const name of names) {
+			const prefix = name + "=";
+			for (let j = 0; j < metaEntries.length; j++) {
+				const [, otherLabel, otherNames] = metaEntries[j];
+				for (const otherName of otherNames) {
+					if (i === j && otherName === name) continue;
+					if (!otherName.startsWith(prefix)) continue;
+					throw new TypeError("The prefix form of name \"" + name + "\" in " + label + " shadows \"" + otherName + "\" in " + otherLabel + ".");
+				}
+			}
+		}
+	}
+	for (const [kind, label, names, prefixMatch] of metaEntries) {
+		const optionNames = kind === "command" ? userNames.leadingOptions : userNames.allOptions;
+		const commandNames = kind === "command" ? userNames.leadingCommands : userNames.allCommands;
+		for (const name of names) {
+			if (optionNames.has(name)) throw new TypeError(`User-defined option "${name}" conflicts with the built-in ${label}.`);
+			if (commandNames.has(name)) throw new TypeError(`User-defined command "${name}" conflicts with the built-in ${label}.`);
+			if (kind === "option" && userNames.allLiterals.has(name)) throw new TypeError(`Literal value "${name}" conflicts with the built-in ${label}.`);
+			if (prefixMatch) {
+				const prefix = name + "=";
+				for (const userName of optionNames) if (userName.startsWith(prefix)) throw new TypeError(`User-defined option "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+				for (const userName of commandNames) if (userName.startsWith(prefix)) throw new TypeError(`User-defined command "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+				for (const literal of userNames.allLiterals) if (literal.startsWith(prefix)) throw new TypeError(`Literal value "${literal}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+			}
+		}
+	}
+}
+function capitalize(s) {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
+/**
 * Validates a program name at runtime.
 *
 * Program names may contain spaces (e.g., file paths), but must not be empty,
@@ -78,8 +147,28 @@ function validateProgramName(programName) {
 	if (/^\s+$/.test(programName)) throw new TypeError(`Program name must not be whitespace-only: "${escapeControlChars(programName)}".`);
 	if (CONTROL_CHAR_RE.test(programName)) throw new TypeError(`Program name must not contain control characters: "${escapeControlChars(programName)}".`);
 }
+/**
+* Validates a label at runtime.
+*
+* Labels are used as section titles in documentation output.  They may contain
+* spaces (e.g., "Connection options"), but must not be empty, whitespace-only,
+* or contain control characters.
+*
+* @param label The label to validate.
+* @throws {TypeError} If the label is not a string, is empty,
+*         whitespace-only, or contains control characters.
+* @since 1.0.0
+*/
+function validateLabel(label) {
+	if (typeof label !== "string") throw new TypeError("Label must be a string.");
+	if (label === "") throw new TypeError("Label must not be empty.");
+	if (/^\s+$/.test(label)) throw new TypeError(`Label must not be whitespace-only: "${escapeControlChars(label)}".`);
+	if (CONTROL_CHAR_RE.test(label)) throw new TypeError(`Label must not contain control characters: "${escapeControlChars(label)}".`);
+}
 
 //#endregion
 exports.validateCommandNames = validateCommandNames;
+exports.validateLabel = validateLabel;
+exports.validateMetaNameCollisions = validateMetaNameCollisions;
 exports.validateOptionNames = validateOptionNames;
 exports.validateProgramName = validateProgramName;

package/dist/validate.js

@@ -62,6 +62,75 @@ function validateCommandNames(names, label) {
 	}
 }
 /**
+* Validates that there are no name collisions among meta features
+* (help, version, completion) and between meta features and user parsers.
+*
+* 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.
+*
+* 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.
+* @since 1.0.0
+*/
+function validateMetaNameCollisions(userNames, metaEntries) {
+	for (const [, label, names] of metaEntries) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const name of names) {
+			if (seen.has(name)) throw new TypeError(`${capitalize(label)} has a duplicate name: "${name}"`);
+			seen.add(name);
+		}
+	}
+	const nameToLabel = /* @__PURE__ */ new Map();
+	for (const [, label, names] of metaEntries) for (const name of names) {
+		const existingLabel = nameToLabel.get(name);
+		if (existingLabel != null) throw new TypeError(`Name "${name}" is used by both ${existingLabel} and ${label}.`);
+		nameToLabel.set(name, label);
+	}
+	for (let i = 0; i < metaEntries.length; i++) {
+		const [, label, names, prefixMatch] = metaEntries[i];
+		if (!prefixMatch) continue;
+		for (const name of names) {
+			const prefix = name + "=";
+			for (let j = 0; j < metaEntries.length; j++) {
+				const [, otherLabel, otherNames] = metaEntries[j];
+				for (const otherName of otherNames) {
+					if (i === j && otherName === name) continue;
+					if (!otherName.startsWith(prefix)) continue;
+					throw new TypeError("The prefix form of name \"" + name + "\" in " + label + " shadows \"" + otherName + "\" in " + otherLabel + ".");
+				}
+			}
+		}
+	}
+	for (const [kind, label, names, prefixMatch] of metaEntries) {
+		const optionNames = kind === "command" ? userNames.leadingOptions : userNames.allOptions;
+		const commandNames = kind === "command" ? userNames.leadingCommands : userNames.allCommands;
+		for (const name of names) {
+			if (optionNames.has(name)) throw new TypeError(`User-defined option "${name}" conflicts with the built-in ${label}.`);
+			if (commandNames.has(name)) throw new TypeError(`User-defined command "${name}" conflicts with the built-in ${label}.`);
+			if (kind === "option" && userNames.allLiterals.has(name)) throw new TypeError(`Literal value "${name}" conflicts with the built-in ${label}.`);
+			if (prefixMatch) {
+				const prefix = name + "=";
+				for (const userName of optionNames) if (userName.startsWith(prefix)) throw new TypeError(`User-defined option "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+				for (const userName of commandNames) if (userName.startsWith(prefix)) throw new TypeError(`User-defined command "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+				for (const literal of userNames.allLiterals) if (literal.startsWith(prefix)) throw new TypeError(`Literal value "${literal}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+			}
+		}
+	}
+}
+function capitalize(s) {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
+/**
 * Validates a program name at runtime.
 *
 * Program names may contain spaces (e.g., file paths), but must not be empty,
@@ -77,6 +146,24 @@ function validateProgramName(programName) {
 	if (/^\s+$/.test(programName)) throw new TypeError(`Program name must not be whitespace-only: "${escapeControlChars(programName)}".`);
 	if (CONTROL_CHAR_RE.test(programName)) throw new TypeError(`Program name must not contain control characters: "${escapeControlChars(programName)}".`);
 }
+/**
+* Validates a label at runtime.
+*
+* Labels are used as section titles in documentation output.  They may contain
+* spaces (e.g., "Connection options"), but must not be empty, whitespace-only,
+* or contain control characters.
+*
+* @param label The label to validate.
+* @throws {TypeError} If the label is not a string, is empty,
+*         whitespace-only, or contains control characters.
+* @since 1.0.0
+*/
+function validateLabel(label) {
+	if (typeof label !== "string") throw new TypeError("Label must be a string.");
+	if (label === "") throw new TypeError("Label must not be empty.");
+	if (/^\s+$/.test(label)) throw new TypeError(`Label must not be whitespace-only: "${escapeControlChars(label)}".`);
+	if (CONTROL_CHAR_RE.test(label)) throw new TypeError(`Label must not contain control characters: "${escapeControlChars(label)}".`);
+}
 
 //#endregion
-export { validateCommandNames, validateOptionNames, validateProgramName };
+export { validateCommandNames, validateLabel, validateMetaNameCollisions, validateOptionNames, validateProgramName };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1514+78606b85",
+  "version": "1.0.0-dev.1523+edc4d966",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",