@optique/core 1.1.0-dev.2096 → 1.1.0-dev.2146

package/dist/validate.d.cts

@@ -0,0 +1,99 @@
+//#region src/validate.d.ts
+/**
+ * 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.
+ */
+declare function escapeControlChars(value: string): string;
+/**
+ * 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.
+ */
+declare function validateOptionNames(names: readonly string[], label: string): void;
+/**
+ * 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.
+ */
+declare function validateCommandNames(names: readonly string[], label: string): void;
+/**
+ * A meta entry describes one active meta feature for collision checking.
+ *
+ * The tuple elements are:
+ *
+ * 1. `kind` — `"command"` if this meta feature matches at `args[0]` only,
+ *    or `"option"` if a lenient scanner matches the name anywhere in `argv`.
+ * 2. `label` — human-readable label for error messages (e.g., `"help option"`).
+ * 3. `names` — the configured name(s) for this meta feature.
+ * 4. `prefixMatch` — when `true`, the runtime also intercepts tokens
+ *    starting with `name=` (e.g., `--completion=bash`).  Only the
+ *    completion option uses this form; help/version use exact matching.
+ *
+ * @since 1.0.0
+ */
+type MetaEntry = readonly [kind: "command" | "option", label: string, names: readonly string[], prefixMatch?: boolean];
+/**
+ * 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
+ */
+declare function validateMetaNameCollisions(metaEntries: readonly MetaEntry[]): void;
+/**
+ * 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.
+ */
+declare function validateProgramName(programName: string): void;
+/**
+ * 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
+ */
+declare function validateLabel(label: string): void;
+/**
+ * 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
+ */
+declare function validateContextIds(contexts: readonly {
+  readonly id: symbol;
+}[]): void;
+//#endregion
+export { MetaEntry, escapeControlChars, validateCommandNames, validateContextIds, validateLabel, validateMetaNameCollisions, validateOptionNames, validateProgramName };

package/dist/validate.d.ts

@@ -0,0 +1,99 @@
+//#region src/validate.d.ts
+/**
+ * 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.
+ */
+declare function escapeControlChars(value: string): string;
+/**
+ * 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.
+ */
+declare function validateOptionNames(names: readonly string[], label: string): void;
+/**
+ * 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.
+ */
+declare function validateCommandNames(names: readonly string[], label: string): void;
+/**
+ * A meta entry describes one active meta feature for collision checking.
+ *
+ * The tuple elements are:
+ *
+ * 1. `kind` — `"command"` if this meta feature matches at `args[0]` only,
+ *    or `"option"` if a lenient scanner matches the name anywhere in `argv`.
+ * 2. `label` — human-readable label for error messages (e.g., `"help option"`).
+ * 3. `names` — the configured name(s) for this meta feature.
+ * 4. `prefixMatch` — when `true`, the runtime also intercepts tokens
+ *    starting with `name=` (e.g., `--completion=bash`).  Only the
+ *    completion option uses this form; help/version use exact matching.
+ *
+ * @since 1.0.0
+ */
+type MetaEntry = readonly [kind: "command" | "option", label: string, names: readonly string[], prefixMatch?: boolean];
+/**
+ * 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
+ */
+declare function validateMetaNameCollisions(metaEntries: readonly MetaEntry[]): void;
+/**
+ * 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.
+ */
+declare function validateProgramName(programName: string): void;
+/**
+ * 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
+ */
+declare function validateLabel(label: string): void;
+/**
+ * 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
+ */
+declare function validateContextIds(contexts: readonly {
+  readonly id: symbol;
+}[]): void;
+//#endregion
+export { MetaEntry, escapeControlChars, validateCommandNames, validateContextIds, validateLabel, validateMetaNameCollisions, validateOptionNames, validateProgramName };

package/dist/validate.js

@@ -161,4 +161,4 @@ function validateContextIds(contexts) {
 }
 
 //#endregion
-export { validateCommandNames, validateContextIds, validateLabel, validateMetaNameCollisions, validateOptionNames, validateProgramName };
+export { escapeControlChars, validateCommandNames, validateContextIds, validateLabel, validateMetaNameCollisions, validateOptionNames, validateProgramName };