@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/validate.cjs

@@ -0,0 +1,170 @@
+
+//#region src/validate.ts
+/**
+* Matches Unicode control characters: C0 (U+0000–U+001F), DEL (U+007F),
+* C1 (U+0080–U+009F), and line separators (U+2028, U+2029).
+*/
+const CONTROL_CHAR_RE = /[\x00-\x1f\x7f-\x9f\u2028\u2029]/;
+const CONTROL_CHAR_RE_GLOBAL = new RegExp(CONTROL_CHAR_RE.source, "g");
+/**
+* Escapes control characters in a string for readable error messages.
+*
+* @param value The string to escape.
+* @returns The escaped string with control characters replaced by escape
+*          sequences.
+*/
+function escapeControlChars(value) {
+	return value.replace(CONTROL_CHAR_RE_GLOBAL, (ch) => {
+		const code = ch.charCodeAt(0);
+		switch (code) {
+			case 9: return "\\t";
+			case 10: return "\\n";
+			case 13: return "\\r";
+			default: return code > 255 ? `\\u${code.toString(16).padStart(4, "0")}` : `\\x${code.toString(16).padStart(2, "0")}`;
+		}
+	});
+}
+/**
+* Validates option names at runtime.
+*
+* @param names The option names to validate.
+* @param label A human-readable label for error messages (e.g.,
+*              `"Option"`, `"Flag"`, `"Help option"`).
+* @throws {TypeError} If the names array is empty, or any name is empty,
+*         lacks a valid prefix, or contains whitespace or control characters.
+*/
+function validateOptionNames(names, label) {
+	if (names.length === 0) throw new TypeError(`Expected at least one ${label.toLowerCase()} name.`);
+	for (const name of names) {
+		if (name === "") throw new TypeError(`${label} name must not be empty.`);
+		if (/^\s+$/.test(name)) throw new TypeError(`${label} name must not be whitespace-only: "${escapeControlChars(name)}".`);
+		if (CONTROL_CHAR_RE.test(name)) throw new TypeError(`${label} name must not contain control characters: "${escapeControlChars(name)}".`);
+		if (/\s/.test(name)) throw new TypeError(`${label} name must not contain whitespace: "${escapeControlChars(name)}".`);
+		if (!/^(--|[-/+])/.test(name)) throw new TypeError(`${label} name must start with "--", "-", "/", or "+": "${name}".`);
+		if (name === "--") throw new TypeError(`${label} name must not be the options terminator "--".`);
+	}
+}
+/**
+* Validates command names at runtime.
+*
+* @param names The command names to validate.
+* @param label A human-readable label for error messages (e.g.,
+*              `"Help command"`).
+* @throws {TypeError} If the names array is empty, or any name is empty,
+*         whitespace-only, or contains whitespace or control characters.
+*/
+function validateCommandNames(names, label) {
+	if (names.length === 0) throw new TypeError(`Expected at least one ${label.toLowerCase()} name.`);
+	for (const name of names) {
+		if (name === "") throw new TypeError(`${label} name must not be empty.`);
+		if (/^\s+$/.test(name)) throw new TypeError(`${label} name must not be whitespace-only: "${escapeControlChars(name)}".`);
+		if (CONTROL_CHAR_RE.test(name)) throw new TypeError(`${label} name must not contain control characters: "${escapeControlChars(name)}".`);
+		if (/\s/.test(name)) throw new TypeError(`${label} name must not contain whitespace: "${escapeControlChars(name)}".`);
+	}
+}
+/**
+* Validates that there are no name collisions among active meta features
+* (help, version, completion).
+*
+* 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 metaEntries Active meta feature entries annotated with their kind.
+* @throws {TypeError} If any meta/meta collision or duplicate is detected.
+* @since 1.0.0
+*/
+function validateMetaNameCollisions(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 + ".");
+				}
+			}
+		}
+	}
+}
+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,
+* whitespace-only, or contain control characters.
+*
+* @param programName The program name to validate.
+* @throws {TypeError} If the value is not a string, is empty,
+*         whitespace-only, or contains control characters.
+*/
+function validateProgramName(programName) {
+	if (typeof programName !== "string") throw new TypeError("Program name must be a string.");
+	if (programName === "") throw new TypeError("Program name must not be empty.");
+	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)}".`);
+}
+/**
+* Validates that all source contexts have unique
+* {@link import("./context.ts").SourceContext.id | id} values.
+*
+* @param contexts The source contexts to validate.
+* @throws {TypeError} If two or more contexts share the same id.
+* @since 1.0.0
+*/
+function validateContextIds(contexts) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const context of contexts) {
+		if (seen.has(context.id)) throw new TypeError(`Duplicate SourceContext id: ${String(context.id)}`);
+		seen.add(context.id);
+	}
+}
+
+//#endregion
+exports.validateCommandNames = validateCommandNames;
+exports.validateContextIds = validateContextIds;
+exports.validateLabel = validateLabel;
+exports.validateMetaNameCollisions = validateMetaNameCollisions;
+exports.validateOptionNames = validateOptionNames;
+exports.validateProgramName = validateProgramName;

package/dist/validate.js

@@ -0,0 +1,164 @@
+//#region src/validate.ts
+/**
+* Matches Unicode control characters: C0 (U+0000–U+001F), DEL (U+007F),
+* C1 (U+0080–U+009F), and line separators (U+2028, U+2029).
+*/
+const CONTROL_CHAR_RE = /[\x00-\x1f\x7f-\x9f\u2028\u2029]/;
+const CONTROL_CHAR_RE_GLOBAL = new RegExp(CONTROL_CHAR_RE.source, "g");
+/**
+* Escapes control characters in a string for readable error messages.
+*
+* @param value The string to escape.
+* @returns The escaped string with control characters replaced by escape
+*          sequences.
+*/
+function escapeControlChars(value) {
+	return value.replace(CONTROL_CHAR_RE_GLOBAL, (ch) => {
+		const code = ch.charCodeAt(0);
+		switch (code) {
+			case 9: return "\\t";
+			case 10: return "\\n";
+			case 13: return "\\r";
+			default: return code > 255 ? `\\u${code.toString(16).padStart(4, "0")}` : `\\x${code.toString(16).padStart(2, "0")}`;
+		}
+	});
+}
+/**
+* Validates option names at runtime.
+*
+* @param names The option names to validate.
+* @param label A human-readable label for error messages (e.g.,
+*              `"Option"`, `"Flag"`, `"Help option"`).
+* @throws {TypeError} If the names array is empty, or any name is empty,
+*         lacks a valid prefix, or contains whitespace or control characters.
+*/
+function validateOptionNames(names, label) {
+	if (names.length === 0) throw new TypeError(`Expected at least one ${label.toLowerCase()} name.`);
+	for (const name of names) {
+		if (name === "") throw new TypeError(`${label} name must not be empty.`);
+		if (/^\s+$/.test(name)) throw new TypeError(`${label} name must not be whitespace-only: "${escapeControlChars(name)}".`);
+		if (CONTROL_CHAR_RE.test(name)) throw new TypeError(`${label} name must not contain control characters: "${escapeControlChars(name)}".`);
+		if (/\s/.test(name)) throw new TypeError(`${label} name must not contain whitespace: "${escapeControlChars(name)}".`);
+		if (!/^(--|[-/+])/.test(name)) throw new TypeError(`${label} name must start with "--", "-", "/", or "+": "${name}".`);
+		if (name === "--") throw new TypeError(`${label} name must not be the options terminator "--".`);
+	}
+}
+/**
+* Validates command names at runtime.
+*
+* @param names The command names to validate.
+* @param label A human-readable label for error messages (e.g.,
+*              `"Help command"`).
+* @throws {TypeError} If the names array is empty, or any name is empty,
+*         whitespace-only, or contains whitespace or control characters.
+*/
+function validateCommandNames(names, label) {
+	if (names.length === 0) throw new TypeError(`Expected at least one ${label.toLowerCase()} name.`);
+	for (const name of names) {
+		if (name === "") throw new TypeError(`${label} name must not be empty.`);
+		if (/^\s+$/.test(name)) throw new TypeError(`${label} name must not be whitespace-only: "${escapeControlChars(name)}".`);
+		if (CONTROL_CHAR_RE.test(name)) throw new TypeError(`${label} name must not contain control characters: "${escapeControlChars(name)}".`);
+		if (/\s/.test(name)) throw new TypeError(`${label} name must not contain whitespace: "${escapeControlChars(name)}".`);
+	}
+}
+/**
+* Validates that there are no name collisions among active meta features
+* (help, version, completion).
+*
+* 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 metaEntries Active meta feature entries annotated with their kind.
+* @throws {TypeError} If any meta/meta collision or duplicate is detected.
+* @since 1.0.0
+*/
+function validateMetaNameCollisions(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 + ".");
+				}
+			}
+		}
+	}
+}
+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,
+* whitespace-only, or contain control characters.
+*
+* @param programName The program name to validate.
+* @throws {TypeError} If the value is not a string, is empty,
+*         whitespace-only, or contains control characters.
+*/
+function validateProgramName(programName) {
+	if (typeof programName !== "string") throw new TypeError("Program name must be a string.");
+	if (programName === "") throw new TypeError("Program name must not be empty.");
+	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)}".`);
+}
+/**
+* Validates that all source contexts have unique
+* {@link import("./context.ts").SourceContext.id | id} values.
+*
+* @param contexts The source contexts to validate.
+* @throws {TypeError} If two or more contexts share the same id.
+* @since 1.0.0
+*/
+function validateContextIds(contexts) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const context of contexts) {
+		if (seen.has(context.id)) throw new TypeError(`Duplicate SourceContext id: ${String(context.id)}`);
+		seen.add(context.id);
+	}
+}
+
+//#endregion
+export { validateCommandNames, validateContextIds, validateLabel, validateMetaNameCollisions, validateOptionNames, validateProgramName };