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

package/dist/constructs.cjs

@@ -2,6 +2,7 @@ const require_annotations = require('./annotations.cjs');
 const require_message = require('./message.cjs');
 const require_dependency = require('./dependency.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
+const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
 const require_suggestion = require('./suggestion.cjs');
@@ -1001,6 +1002,7 @@ async function resolveDeferredParseStatesAsync(fieldStates, initialRegistry) {
 }
 function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	const label = typeof labelOrParsers === "string" ? labelOrParsers : void 0;
+	if (label != null) require_validate.validateLabel(label);
 	let parsers;
 	let options = {};
 	if (typeof labelOrParsers === "string") {
@@ -1410,6 +1412,7 @@ async function* suggestTupleAsync(context, prefix, parsers) {
 }
 function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	const label = typeof labelOrParsers === "string" ? labelOrParsers : void 0;
+	if (label != null) require_validate.validateLabel(label);
 	let parsers;
 	let options = {};
 	if (typeof labelOrParsers === "string") {
@@ -1723,6 +1726,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 }
 function merge(...args) {
 	const label = typeof args[0] === "string" ? args[0] : void 0;
+	if (label != null) require_validate.validateLabel(label);
 	const lastArg = args[args.length - 1];
 	const hasOptions = lastArg != null && typeof lastArg === "object" && !("$valueType" in lastArg);
 	const options = hasOptions ? lastArg : {};
@@ -2481,6 +2485,7 @@ function concat(...parsers) {
 	};
 }
 function group(label, parser, options = {}) {
+	require_validate.validateLabel(label);
 	const groupParser = {
 		$mode: parser.$mode,
 		$valueType: parser.$valueType,

package/dist/constructs.d.cts

@@ -1023,6 +1023,8 @@ declare function object<T extends {
  * @returns A {@link Parser} that produces an object with the same keys as
  *          the input, where each value is the result of the corresponding
  *          parser.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  */
 declare function object<T extends {
   readonly [key: string | symbol]: Parser<Mode, unknown, unknown>;
@@ -1040,6 +1042,8 @@ declare function object<T extends {
  * @returns A {@link Parser} that produces an object with the same keys as
  *          the input, where each value is the result of the corresponding
  *          parser.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.5.0
  */
 declare function object<T extends {
@@ -1084,6 +1088,8 @@ declare function tuple<const T extends readonly Parser<Mode, unknown, unknown>[]
  * @returns A {@link Parser} that produces a readonly tuple with the same length
  *          as the input array, where each element is the result of the
  *          corresponding parser.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  */
 declare function tuple<const T extends readonly Parser<Mode, unknown, unknown>[]>(label: string, parsers: T, options?: TupleOptions): Parser<CombineTupleModes<T>, { readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, { readonly [K in keyof T]: T[K]["$stateType"][number] extends (infer U2) ? U2 : never }>;
 /**
@@ -1152,6 +1158,8 @@ declare function merge<const TParsers extends MergeParsers>(...rest: [...parsers
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
  * @throws {TypeError} If no parser arguments are provided.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.4.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...parsers: EnsureMergeParsers<TParsers> & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1166,6 +1174,8 @@ declare function merge<const TParsers extends MergeParsers>(label: string, ...pa
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
  * @throws {TypeError} If no parser arguments are provided.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.7.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...rest: [...parsers: EnsureMergeParsers<TParsers>, options: MergeTailOptions] & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1271,6 +1281,8 @@ declare function concat<const TParsers extends ConcatParsers>(...parsers: TParse
  * @param options Optional visibility controls for the wrapped parser terms.
  * @returns A new parser that behaves identically to the input parser
  *          but generates documentation within a labeled section.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.4.0
  */
 /**

package/dist/constructs.d.ts

@@ -1023,6 +1023,8 @@ declare function object<T extends {
  * @returns A {@link Parser} that produces an object with the same keys as
  *          the input, where each value is the result of the corresponding
  *          parser.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  */
 declare function object<T extends {
   readonly [key: string | symbol]: Parser<Mode, unknown, unknown>;
@@ -1040,6 +1042,8 @@ declare function object<T extends {
  * @returns A {@link Parser} that produces an object with the same keys as
  *          the input, where each value is the result of the corresponding
  *          parser.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.5.0
  */
 declare function object<T extends {
@@ -1084,6 +1088,8 @@ declare function tuple<const T extends readonly Parser<Mode, unknown, unknown>[]
  * @returns A {@link Parser} that produces a readonly tuple with the same length
  *          as the input array, where each element is the result of the
  *          corresponding parser.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  */
 declare function tuple<const T extends readonly Parser<Mode, unknown, unknown>[]>(label: string, parsers: T, options?: TupleOptions): Parser<CombineTupleModes<T>, { readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, { readonly [K in keyof T]: T[K]["$stateType"][number] extends (infer U2) ? U2 : never }>;
 /**
@@ -1152,6 +1158,8 @@ declare function merge<const TParsers extends MergeParsers>(...rest: [...parsers
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
  * @throws {TypeError} If no parser arguments are provided.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.4.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...parsers: EnsureMergeParsers<TParsers> & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1166,6 +1174,8 @@ declare function merge<const TParsers extends MergeParsers>(label: string, ...pa
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
  * @throws {TypeError} If no parser arguments are provided.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.7.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...rest: [...parsers: EnsureMergeParsers<TParsers>, options: MergeTailOptions] & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1271,6 +1281,8 @@ declare function concat<const TParsers extends ConcatParsers>(...parsers: TParse
  * @param options Optional visibility controls for the wrapped parser terms.
  * @returns A new parser that behaves identically to the input parser
  *          but generates documentation within a labeled section.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.4.0
  */
 /**

package/dist/constructs.js

@@ -2,6 +2,7 @@ import { getAnnotations, inheritAnnotations, injectAnnotations } from "./annotat
 import { message, optionName, text, values } from "./message.js";
 import { DependencyRegistry, createDependencySourceState, dependencyId, isDeferredParseState, isDependencySourceState, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, wrappedDependencySourceMarker } from "./dependency.js";
 import { dispatchByMode, dispatchIterableByMode } from "./mode-dispatch.js";
+import { validateLabel } from "./validate.js";
 import { extractArgumentMetavars, extractCommandNames, extractOptionNames, isDocHidden, mergeHidden } from "./usage.js";
 import { deduplicateDocFragments } from "./doc.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, findSimilar } from "./suggestion.js";
@@ -1001,6 +1002,7 @@ async function resolveDeferredParseStatesAsync(fieldStates, initialRegistry) {
 }
 function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	const label = typeof labelOrParsers === "string" ? labelOrParsers : void 0;
+	if (label != null) validateLabel(label);
 	let parsers;
 	let options = {};
 	if (typeof labelOrParsers === "string") {
@@ -1410,6 +1412,7 @@ async function* suggestTupleAsync(context, prefix, parsers) {
 }
 function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	const label = typeof labelOrParsers === "string" ? labelOrParsers : void 0;
+	if (label != null) validateLabel(label);
 	let parsers;
 	let options = {};
 	if (typeof labelOrParsers === "string") {
@@ -1723,6 +1726,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 }
 function merge(...args) {
 	const label = typeof args[0] === "string" ? args[0] : void 0;
+	if (label != null) validateLabel(label);
 	const lastArg = args[args.length - 1];
 	const hasOptions = lastArg != null && typeof lastArg === "object" && !("$valueType" in lastArg);
 	const options = hasOptions ? lastArg : {};
@@ -2481,6 +2485,7 @@ function concat(...parsers) {
 	};
 }
 function group(label, parser, options = {}) {
+	validateLabel(label);
 	const groupParser = {
 		$mode: parser.$mode,
 		$valueType: parser.$valueType,

package/dist/doc.cjs

@@ -185,8 +185,8 @@ function defaultSectionOrder(a, b) {
 * @returns A formatted string representation of the documentation page
 * @throws {TypeError} If `programName` is not a string, is empty,
 * whitespace-only, or contains control characters, if any non-empty
-* section's title is empty, whitespace-only, or contains a CR or LF
-* character, or if `maxWidth` is not a finite integer.
+* section's title is not a string, is empty, whitespace-only, or contains
+* control characters, or if `maxWidth` is not a finite integer.
 * @throws {RangeError} If any entry needs a description column and `maxWidth`
 * is too small to fit the minimum layout (less than `termIndent + 4`), or if
 * `showChoices.maxItems` is less than `1`.
@@ -312,7 +312,7 @@ function formatDocPage(programName, page, options = {}) {
 		if (section.entries.length < 1) continue;
 		output += "\n";
 		if (section.title != null) {
-			if (section.title.trim() === "" || /[\r\n]/.test(section.title)) throw new TypeError("Section title must not be empty, whitespace-only, or contain newlines.");
+			require_validate.validateLabel(section.title);
 			const sectionLabel = options.colors ? `\x1b[1;2m${section.title}:\x1b[0m\n` : `${section.title}:\n`;
 			output += sectionLabel;
 		}

package/dist/doc.d.cts

@@ -313,8 +313,8 @@ interface DocPageFormatOptions {
  * @returns A formatted string representation of the documentation page
  * @throws {TypeError} If `programName` is not a string, is empty,
  * whitespace-only, or contains control characters, if any non-empty
- * section's title is empty, whitespace-only, or contains a CR or LF
- * character, or if `maxWidth` is not a finite integer.
+ * section's title is not a string, is empty, whitespace-only, or contains
+ * control characters, or if `maxWidth` is not a finite integer.
  * @throws {RangeError} If any entry needs a description column and `maxWidth`
  * is too small to fit the minimum layout (less than `termIndent + 4`), or if
  * `showChoices.maxItems` is less than `1`.

package/dist/doc.d.ts

@@ -313,8 +313,8 @@ interface DocPageFormatOptions {
  * @returns A formatted string representation of the documentation page
  * @throws {TypeError} If `programName` is not a string, is empty,
  * whitespace-only, or contains control characters, if any non-empty
- * section's title is empty, whitespace-only, or contains a CR or LF
- * character, or if `maxWidth` is not a finite integer.
+ * section's title is not a string, is empty, whitespace-only, or contains
+ * control characters, or if `maxWidth` is not a finite integer.
  * @throws {RangeError} If any entry needs a description column and `maxWidth`
  * is too small to fit the minimum layout (less than `termIndent + 4`), or if
  * `showChoices.maxItems` is less than `1`.

package/dist/doc.js

@@ -1,5 +1,5 @@
 import { cloneMessage, formatMessage, text } from "./message.js";
-import { validateProgramName } from "./validate.js";
+import { validateLabel, validateProgramName } from "./validate.js";
 import { cloneUsageTerm, formatUsage, formatUsageTerm, isDocHidden, isUsageHidden } from "./usage.js";
 
 //#region src/doc.ts
@@ -185,8 +185,8 @@ function defaultSectionOrder(a, b) {
 * @returns A formatted string representation of the documentation page
 * @throws {TypeError} If `programName` is not a string, is empty,
 * whitespace-only, or contains control characters, if any non-empty
-* section's title is empty, whitespace-only, or contains a CR or LF
-* character, or if `maxWidth` is not a finite integer.
+* section's title is not a string, is empty, whitespace-only, or contains
+* control characters, or if `maxWidth` is not a finite integer.
 * @throws {RangeError} If any entry needs a description column and `maxWidth`
 * is too small to fit the minimum layout (less than `termIndent + 4`), or if
 * `showChoices.maxItems` is less than `1`.
@@ -312,7 +312,7 @@ function formatDocPage(programName, page, options = {}) {
 		if (section.entries.length < 1) continue;
 		output += "\n";
 		if (section.title != null) {
-			if (section.title.trim() === "" || /[\r\n]/.test(section.title)) throw new TypeError("Section title must not be empty, whitespace-only, or contain newlines.");
+			validateLabel(section.title);
 			const sectionLabel = options.colors ? `\x1b[1;2m${section.title}:\x1b[0m\n` : `${section.title}:\n`;
 			output += sectionLabel;
 		}

package/dist/validate.cjs

@@ -147,9 +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

@@ -146,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, validateMetaNameCollisions, validateOptionNames, validateProgramName };
+export { validateCommandNames, validateLabel, validateMetaNameCollisions, validateOptionNames, validateProgramName };

package/package.json

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