@optique/core 1.0.0-dev.1452 → 1.0.0-dev.1461

package/dist/doc.cjs

@@ -2,6 +2,20 @@ const require_message = require('./message.cjs');
 const require_usage = require('./usage.cjs');
 
 //#region src/doc.ts
+/**
+* Returns whether a doc entry's term is hidden from documentation.
+* Only term types with a `hidden` field (argument, option, command,
+* passthrough) are checked; other types always return `false`.
+*
+* @param entry The doc entry to check.
+* @returns `true` if the entry should be hidden from documentation.
+* @since 1.0.0
+*/
+function isDocEntryHidden(entry) {
+	const term = entry.term;
+	if (term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") return require_usage.isDocHidden(term.hidden);
+	return false;
+}
 function getDocEntryKey(entry) {
 	const term = entry.term;
 	switch (term.type) {
@@ -13,21 +27,25 @@ function getDocEntryKey(entry) {
 }
 /**
 * Removes duplicate {@link DocEntry} values that share the same surface
-* syntax (same term type and identifying names).  When duplicates exist,
-* the first occurrence is kept and later ones are discarded.
+* syntax (same term type and identifying names).  Doc-hidden entries are
+* filtered out first so they cannot influence the ordering of visible
+* entries.  Among the remaining visible entries, the first occurrence is
+* kept and later duplicates are discarded.
 *
 * Positional argument entries are never deduplicated because they are
 * distinguished by position, not by metavar, and {@link DocEntry} does
 * not carry position information.
 *
 * @param entries The entries to deduplicate.
-* @returns A new array with duplicates removed, preserving insertion order.
+* @returns A new array with hidden entries removed and duplicates
+*   collapsed, preserving insertion order of visible entries.
 * @since 1.0.0
 */
 function deduplicateDocEntries(entries) {
 	const seen = /* @__PURE__ */ new Set();
 	const result = [];
 	for (const entry of entries) {
+		if (isDocEntryHidden(entry)) continue;
 		if (entry.term.type === "argument") {
 			result.push(entry);
 			continue;
@@ -52,18 +70,22 @@ function deduplicateDocEntries(entries) {
 function deduplicateDocFragments(fragments) {
 	const untitledSeen = /* @__PURE__ */ new Set();
 	const titledSectionMap = /* @__PURE__ */ new Map();
+	const titledSectionPositioned = /* @__PURE__ */ new Set();
 	const slots = [];
-	for (const fragment of fragments) if (fragment.type === "entry") if (fragment.term.type === "argument") slots.push(fragment);
-	else {
-		const key = getDocEntryKey(fragment);
-		if (!untitledSeen.has(key)) {
-			untitledSeen.add(key);
-			slots.push(fragment);
+	for (const fragment of fragments) if (fragment.type === "entry") {
+		if (isDocEntryHidden(fragment)) continue;
+		if (fragment.term.type === "argument") slots.push(fragment);
+		else {
+			const key = getDocEntryKey(fragment);
+			if (!untitledSeen.has(key)) {
+				untitledSeen.add(key);
+				slots.push(fragment);
+			}
 		}
-	}
-	else if (fragment.title == null) {
+	} else if (fragment.title == null) {
 		const dedupedEntries = [];
 		for (const entry of fragment.entries) {
+			if (isDocEntryHidden(entry)) continue;
 			if (entry.term.type === "argument") {
 				dedupedEntries.push(entry);
 				continue;
@@ -80,8 +102,9 @@ function deduplicateDocFragments(fragments) {
 			entries: dedupedEntries
 		});
 	} else {
-		if (!titledSectionMap.has(fragment.title)) {
-			titledSectionMap.set(fragment.title, []);
+		if (!titledSectionMap.has(fragment.title)) titledSectionMap.set(fragment.title, []);
+		if (!titledSectionPositioned.has(fragment.title) && fragment.entries.some((e) => !isDocEntryHidden(e))) {
+			titledSectionPositioned.add(fragment.title);
 			slots.push(fragment.title);
 		}
 		titledSectionMap.get(fragment.title).push(...fragment.entries);
@@ -442,4 +465,5 @@ function lastLineVisibleLength(text$1) {
 exports.cloneDocEntry = cloneDocEntry;
 exports.deduplicateDocEntries = deduplicateDocEntries;
 exports.deduplicateDocFragments = deduplicateDocFragments;
-exports.formatDocPage = formatDocPage;
+exports.formatDocPage = formatDocPage;
+exports.isDocEntryHidden = isDocEntryHidden;

package/dist/doc.d.cts

@@ -103,17 +103,30 @@ interface DocFragments {
    */
   readonly footer?: Message;
 }
+/**
+ * Returns whether a doc entry's term is hidden from documentation.
+ * Only term types with a `hidden` field (argument, option, command,
+ * passthrough) are checked; other types always return `false`.
+ *
+ * @param entry The doc entry to check.
+ * @returns `true` if the entry should be hidden from documentation.
+ * @since 1.0.0
+ */
+declare function isDocEntryHidden(entry: DocEntry): boolean;
 /**
  * Removes duplicate {@link DocEntry} values that share the same surface
- * syntax (same term type and identifying names).  When duplicates exist,
- * the first occurrence is kept and later ones are discarded.
+ * syntax (same term type and identifying names).  Doc-hidden entries are
+ * filtered out first so they cannot influence the ordering of visible
+ * entries.  Among the remaining visible entries, the first occurrence is
+ * kept and later duplicates are discarded.
  *
  * Positional argument entries are never deduplicated because they are
  * distinguished by position, not by metavar, and {@link DocEntry} does
  * not carry position information.
  *
  * @param entries The entries to deduplicate.
- * @returns A new array with duplicates removed, preserving insertion order.
+ * @returns A new array with hidden entries removed and duplicates
+ *   collapsed, preserving insertion order of visible entries.
  * @since 1.0.0
  */
 declare function deduplicateDocEntries(entries: readonly DocEntry[]): DocEntry[];
@@ -325,4 +338,4 @@ interface DocPageFormatOptions {
  */
 declare function formatDocPage(programName: string, page: DocPage, options?: DocPageFormatOptions): string;
 //#endregion
-export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage };
+export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden };

package/dist/doc.d.ts

@@ -103,17 +103,30 @@ interface DocFragments {
    */
   readonly footer?: Message;
 }
+/**
+ * Returns whether a doc entry's term is hidden from documentation.
+ * Only term types with a `hidden` field (argument, option, command,
+ * passthrough) are checked; other types always return `false`.
+ *
+ * @param entry The doc entry to check.
+ * @returns `true` if the entry should be hidden from documentation.
+ * @since 1.0.0
+ */
+declare function isDocEntryHidden(entry: DocEntry): boolean;
 /**
  * Removes duplicate {@link DocEntry} values that share the same surface
- * syntax (same term type and identifying names).  When duplicates exist,
- * the first occurrence is kept and later ones are discarded.
+ * syntax (same term type and identifying names).  Doc-hidden entries are
+ * filtered out first so they cannot influence the ordering of visible
+ * entries.  Among the remaining visible entries, the first occurrence is
+ * kept and later duplicates are discarded.
  *
  * Positional argument entries are never deduplicated because they are
  * distinguished by position, not by metavar, and {@link DocEntry} does
  * not carry position information.
  *
  * @param entries The entries to deduplicate.
- * @returns A new array with duplicates removed, preserving insertion order.
+ * @returns A new array with hidden entries removed and duplicates
+ *   collapsed, preserving insertion order of visible entries.
  * @since 1.0.0
  */
 declare function deduplicateDocEntries(entries: readonly DocEntry[]): DocEntry[];
@@ -325,4 +338,4 @@ interface DocPageFormatOptions {
  */
 declare function formatDocPage(programName: string, page: DocPage, options?: DocPageFormatOptions): string;
 //#endregion
-export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage };
+export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden };

package/dist/doc.js

@@ -1,7 +1,21 @@
 import { cloneMessage, formatMessage, text } from "./message.js";
-import { cloneUsageTerm, formatUsage, formatUsageTerm } from "./usage.js";
+import { cloneUsageTerm, formatUsage, formatUsageTerm, isDocHidden } from "./usage.js";
 
 //#region src/doc.ts
+/**
+* Returns whether a doc entry's term is hidden from documentation.
+* Only term types with a `hidden` field (argument, option, command,
+* passthrough) are checked; other types always return `false`.
+*
+* @param entry The doc entry to check.
+* @returns `true` if the entry should be hidden from documentation.
+* @since 1.0.0
+*/
+function isDocEntryHidden(entry) {
+	const term = entry.term;
+	if (term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") return isDocHidden(term.hidden);
+	return false;
+}
 function getDocEntryKey(entry) {
 	const term = entry.term;
 	switch (term.type) {
@@ -13,21 +27,25 @@ function getDocEntryKey(entry) {
 }
 /**
 * Removes duplicate {@link DocEntry} values that share the same surface
-* syntax (same term type and identifying names).  When duplicates exist,
-* the first occurrence is kept and later ones are discarded.
+* syntax (same term type and identifying names).  Doc-hidden entries are
+* filtered out first so they cannot influence the ordering of visible
+* entries.  Among the remaining visible entries, the first occurrence is
+* kept and later duplicates are discarded.
 *
 * Positional argument entries are never deduplicated because they are
 * distinguished by position, not by metavar, and {@link DocEntry} does
 * not carry position information.
 *
 * @param entries The entries to deduplicate.
-* @returns A new array with duplicates removed, preserving insertion order.
+* @returns A new array with hidden entries removed and duplicates
+*   collapsed, preserving insertion order of visible entries.
 * @since 1.0.0
 */
 function deduplicateDocEntries(entries) {
 	const seen = /* @__PURE__ */ new Set();
 	const result = [];
 	for (const entry of entries) {
+		if (isDocEntryHidden(entry)) continue;
 		if (entry.term.type === "argument") {
 			result.push(entry);
 			continue;
@@ -52,18 +70,22 @@ function deduplicateDocEntries(entries) {
 function deduplicateDocFragments(fragments) {
 	const untitledSeen = /* @__PURE__ */ new Set();
 	const titledSectionMap = /* @__PURE__ */ new Map();
+	const titledSectionPositioned = /* @__PURE__ */ new Set();
 	const slots = [];
-	for (const fragment of fragments) if (fragment.type === "entry") if (fragment.term.type === "argument") slots.push(fragment);
-	else {
-		const key = getDocEntryKey(fragment);
-		if (!untitledSeen.has(key)) {
-			untitledSeen.add(key);
-			slots.push(fragment);
+	for (const fragment of fragments) if (fragment.type === "entry") {
+		if (isDocEntryHidden(fragment)) continue;
+		if (fragment.term.type === "argument") slots.push(fragment);
+		else {
+			const key = getDocEntryKey(fragment);
+			if (!untitledSeen.has(key)) {
+				untitledSeen.add(key);
+				slots.push(fragment);
+			}
 		}
-	}
-	else if (fragment.title == null) {
+	} else if (fragment.title == null) {
 		const dedupedEntries = [];
 		for (const entry of fragment.entries) {
+			if (isDocEntryHidden(entry)) continue;
 			if (entry.term.type === "argument") {
 				dedupedEntries.push(entry);
 				continue;
@@ -80,8 +102,9 @@ function deduplicateDocFragments(fragments) {
 			entries: dedupedEntries
 		});
 	} else {
-		if (!titledSectionMap.has(fragment.title)) {
-			titledSectionMap.set(fragment.title, []);
+		if (!titledSectionMap.has(fragment.title)) titledSectionMap.set(fragment.title, []);
+		if (!titledSectionPositioned.has(fragment.title) && fragment.entries.some((e) => !isDocEntryHidden(e))) {
+			titledSectionPositioned.add(fragment.title);
 			slots.push(fragment.title);
 		}
 		titledSectionMap.get(fragment.title).push(...fragment.entries);
@@ -439,4 +462,4 @@ function lastLineVisibleLength(text$1) {
 }
 
 //#endregion
-export { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage };
+export { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden };

package/dist/index.cjs

@@ -79,6 +79,7 @@ exports.isDeferredParseState = require_dependency.isDeferredParseState;
 exports.isDependencySource = require_dependency.isDependencySource;
 exports.isDependencySourceState = require_dependency.isDependencySourceState;
 exports.isDerivedValueParser = require_dependency.isDerivedValueParser;
+exports.isDocEntryHidden = require_doc.isDocEntryHidden;
 exports.isDocHidden = require_usage.isDocHidden;
 exports.isNonEmptyString = require_nonempty.isNonEmptyString;
 exports.isPendingDependencySourceState = require_dependency.isPendingDependencySourceState;

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { Annotations, ParseOptions, annotationKey, getAnnotations } from "./anno
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.cjs";
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.cjs";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.cjs";
-import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage } from "./doc.cjs";
+import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.cjs";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.cjs";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
@@ -12,4 +12,4 @@ import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, Mode
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { ParserValuePlaceholder, SourceContext } from "./context.cjs";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { Annotations, ParseOptions, annotationKey, getAnnotations } from "./anno
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
-import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage } from "./doc.js";
+import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.js";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
@@ -12,4 +12,4 @@ import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, Mode
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { ParserValuePlaceholder, SourceContext } from "./context.js";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.js

@@ -3,7 +3,7 @@ import { commandLine, envVar, formatMessage, lineBreak, link, message, metavar,
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { DependencyRegistry, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.js";
 import { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
-import { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage } from "./doc.js";
+import { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
@@ -12,4 +12,4 @@ import { argument, command, constant, fail, flag, option, passThrough } from "./
 import { getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/parser.cjs

@@ -385,28 +385,33 @@ function buildDocPage(parser, context, args) {
 	let untitledSection = null;
 	const titledSectionMap = /* @__PURE__ */ new Map();
 	for (const fragment of fragments) if (fragment.type === "entry") {
+		if (require_doc.isDocEntryHidden(fragment)) continue;
 		if (untitledSection == null) {
 			untitledSection = { entries: [] };
 			buildingSections.push(untitledSection);
 		}
 		untitledSection.entries.push(require_doc.cloneDocEntry(fragment));
-	} else if (fragment.type === "section") if (fragment.title == null) {
-		if (untitledSection == null) {
-			untitledSection = { entries: [] };
-			buildingSections.push(untitledSection);
-		}
-		untitledSection.entries.push(...fragment.entries.map(require_doc.cloneDocEntry));
-	} else {
-		let section = titledSectionMap.get(fragment.title);
-		if (section == null) {
-			section = {
-				title: fragment.title,
-				entries: []
-			};
-			titledSectionMap.set(fragment.title, section);
-			buildingSections.push(section);
+	} else if (fragment.type === "section") {
+		const visible = fragment.entries.filter((e) => !require_doc.isDocEntryHidden(e));
+		if (visible.length === 0) continue;
+		if (fragment.title == null) {
+			if (untitledSection == null) {
+				untitledSection = { entries: [] };
+				buildingSections.push(untitledSection);
+			}
+			untitledSection.entries.push(...visible.map(require_doc.cloneDocEntry));
+		} else {
+			let section = titledSectionMap.get(fragment.title);
+			if (section == null) {
+				section = {
+					title: fragment.title,
+					entries: []
+				};
+				titledSectionMap.set(fragment.title, section);
+				buildingSections.push(section);
+			}
+			section.entries.push(...visible.map(require_doc.cloneDocEntry));
 		}
-		section.entries.push(...fragment.entries.map(require_doc.cloneDocEntry));
 	}
 	const sections = buildingSections;
 	const usage = require_usage.cloneUsage(require_usage.normalizeUsage(parser.usage));

package/dist/parser.js

@@ -2,7 +2,7 @@ import { injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotatio
 import { cloneMessage, message } from "./message.js";
 import { dispatchByMode } from "./mode-dispatch.js";
 import { cloneUsage, normalizeUsage } from "./usage.js";
-import { cloneDocEntry } from "./doc.js";
+import { cloneDocEntry, isDocEntryHidden } from "./doc.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
@@ -385,28 +385,33 @@ function buildDocPage(parser, context, args) {
 	let untitledSection = null;
 	const titledSectionMap = /* @__PURE__ */ new Map();
 	for (const fragment of fragments) if (fragment.type === "entry") {
+		if (isDocEntryHidden(fragment)) continue;
 		if (untitledSection == null) {
 			untitledSection = { entries: [] };
 			buildingSections.push(untitledSection);
 		}
 		untitledSection.entries.push(cloneDocEntry(fragment));
-	} else if (fragment.type === "section") if (fragment.title == null) {
-		if (untitledSection == null) {
-			untitledSection = { entries: [] };
-			buildingSections.push(untitledSection);
-		}
-		untitledSection.entries.push(...fragment.entries.map(cloneDocEntry));
-	} else {
-		let section = titledSectionMap.get(fragment.title);
-		if (section == null) {
-			section = {
-				title: fragment.title,
-				entries: []
-			};
-			titledSectionMap.set(fragment.title, section);
-			buildingSections.push(section);
+	} else if (fragment.type === "section") {
+		const visible = fragment.entries.filter((e) => !isDocEntryHidden(e));
+		if (visible.length === 0) continue;
+		if (fragment.title == null) {
+			if (untitledSection == null) {
+				untitledSection = { entries: [] };
+				buildingSections.push(untitledSection);
+			}
+			untitledSection.entries.push(...visible.map(cloneDocEntry));
+		} else {
+			let section = titledSectionMap.get(fragment.title);
+			if (section == null) {
+				section = {
+					title: fragment.title,
+					entries: []
+				};
+				titledSectionMap.set(fragment.title, section);
+				buildingSections.push(section);
+			}
+			section.entries.push(...visible.map(cloneDocEntry));
 		}
-		section.entries.push(...fragment.entries.map(cloneDocEntry));
 	}
 	const sections = buildingSections;
 	const usage = cloneUsage(normalizeUsage(parser.usage));

package/dist/valueparser.cjs

@@ -2636,6 +2636,90 @@ function compressIpv6(groups) {
 	else return before.join(":") + "::" + after.join(":");
 }
 /**
+* Extracts IPv4 octets from an IPv4-mapped IPv6 address.
+* Returns null if the address is not an IPv4-mapped address
+* (i.e., not in the `::ffff:x.x.x.x` range).
+*/
+function extractIpv4FromMapped(normalizedIpv6) {
+	const groups = expandIpv6(normalizedIpv6);
+	if (groups === null) return null;
+	for (let i = 0; i < 5; i++) if (parseInt(groups[i], 16) !== 0) return null;
+	if (parseInt(groups[5], 16) !== 65535) return null;
+	const high = parseInt(groups[6], 16);
+	const low = parseInt(groups[7], 16);
+	return [
+		high >> 8 & 255,
+		high & 255,
+		low >> 8 & 255,
+		low & 255
+	];
+}
+/**
+* Checks IPv4 restrictions against octets extracted from an IPv4-mapped
+* IPv6 address.  The check uses the base address, consistent with how
+* the `ipv4()` parser validates the address part of a regular IPv4 CIDR.
+*
+* Returns an error result if a restriction is violated, or null if all
+* checks pass.
+*/
+function checkIpv4MappedRestrictions(octets, normalizedIpv6, ipv4Opts, errors) {
+	const allowPrivate = ipv4Opts?.allowPrivate ?? true;
+	const allowLoopback = ipv4Opts?.allowLoopback ?? true;
+	const allowLinkLocal = ipv4Opts?.allowLinkLocal ?? true;
+	const allowMulticast = ipv4Opts?.allowMulticast ?? true;
+	const allowBroadcast = ipv4Opts?.allowBroadcast ?? true;
+	const allowZero = ipv4Opts?.allowZero ?? true;
+	if (!allowPrivate && isPrivateIp(octets)) {
+		const errorMsg = errors?.privateNotAllowed;
+		const msg = typeof errorMsg === "function" ? errorMsg(normalizedIpv6) : errorMsg ?? require_message.message`${normalizedIpv6} is a private IP address.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	if (!allowLoopback && isLoopbackIp(octets)) {
+		const errorMsg = errors?.loopbackNotAllowed;
+		const msg = typeof errorMsg === "function" ? errorMsg(normalizedIpv6) : errorMsg ?? require_message.message`${normalizedIpv6} is a loopback address.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	if (!allowLinkLocal && isLinkLocalIp(octets)) {
+		const errorMsg = errors?.linkLocalNotAllowed;
+		const msg = typeof errorMsg === "function" ? errorMsg(normalizedIpv6) : errorMsg ?? require_message.message`${normalizedIpv6} is a link-local address.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	if (!allowMulticast && isMulticastIp(octets)) {
+		const errorMsg = errors?.multicastNotAllowed;
+		const msg = typeof errorMsg === "function" ? errorMsg(normalizedIpv6) : errorMsg ?? require_message.message`${normalizedIpv6} is a multicast address.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	if (!allowBroadcast && isBroadcastIp(octets)) {
+		const errorMsg = errors?.broadcastNotAllowed;
+		const msg = typeof errorMsg === "function" ? errorMsg(normalizedIpv6) : errorMsg ?? require_message.message`${normalizedIpv6} is the broadcast address.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	if (!allowZero && isZeroIp(octets)) {
+		const errorMsg = errors?.zeroNotAllowed;
+		const msg = typeof errorMsg === "function" ? errorMsg(normalizedIpv6) : errorMsg ?? require_message.message`${normalizedIpv6} is the zero address.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	return null;
+}
+/**
 * Creates a value parser that accepts both IPv4 and IPv6 addresses.
 *
 * By default, accepts both IPv4 and IPv6 addresses. Use the `version` option
@@ -2688,6 +2772,22 @@ function ip(options) {
 			zeroNotAllowed: errors?.zeroNotAllowed
 		}
 	}) : null;
+	const mappedIpv4Opts = version === "both" ? {
+		allowPrivate: options?.ipv4?.allowPrivate,
+		allowLoopback: options?.ipv4?.allowLoopback,
+		allowLinkLocal: options?.ipv4?.allowLinkLocal,
+		allowMulticast: options?.ipv4?.allowMulticast,
+		allowBroadcast: options?.ipv4?.allowBroadcast,
+		allowZero: options?.ipv4?.allowZero
+	} : void 0;
+	const mappedIpv4Errors = version === "both" ? {
+		privateNotAllowed: errors?.privateNotAllowed,
+		loopbackNotAllowed: errors?.loopbackNotAllowed,
+		linkLocalNotAllowed: errors?.linkLocalNotAllowed,
+		multicastNotAllowed: errors?.multicastNotAllowed,
+		broadcastNotAllowed: errors?.broadcastNotAllowed,
+		zeroNotAllowed: errors?.zeroNotAllowed
+	} : void 0;
 	return {
 		$mode: "sync",
 		metavar,
@@ -2702,7 +2802,16 @@ function ip(options) {
 			}
 			if (ipv6Parser !== null) {
 				const result = ipv6Parser.parse(input);
-				if (result.success) return result;
+				if (result.success) {
+					if (version === "both") {
+						const mappedOctets = extractIpv4FromMapped(result.value);
+						if (mappedOctets !== null) {
+							const restrictionError = checkIpv4MappedRestrictions(mappedOctets, result.value, mappedIpv4Opts, mappedIpv4Errors);
+							if (restrictionError !== null) return restrictionError;
+						}
+					}
+					return result;
+				}
 				ipv6Error = result;
 				if (version === 6) return result;
 			}
@@ -2804,6 +2913,22 @@ function cidr(options) {
 			uniqueLocalNotAllowed: errors?.uniqueLocalNotAllowed
 		}
 	}) : null;
+	const mappedIpv4Opts = version === "both" ? {
+		allowPrivate: options?.ipv4?.allowPrivate,
+		allowLoopback: options?.ipv4?.allowLoopback,
+		allowLinkLocal: options?.ipv4?.allowLinkLocal,
+		allowMulticast: options?.ipv4?.allowMulticast,
+		allowBroadcast: options?.ipv4?.allowBroadcast,
+		allowZero: options?.ipv4?.allowZero
+	} : void 0;
+	const mappedIpv4Errors = version === "both" ? {
+		privateNotAllowed: errors?.privateNotAllowed,
+		loopbackNotAllowed: errors?.loopbackNotAllowed,
+		linkLocalNotAllowed: errors?.linkLocalNotAllowed,
+		multicastNotAllowed: errors?.multicastNotAllowed,
+		broadcastNotAllowed: errors?.broadcastNotAllowed,
+		zeroNotAllowed: errors?.zeroNotAllowed
+	} : void 0;
 	return {
 		$mode: "sync",
 		metavar,
@@ -3148,6 +3273,13 @@ function cidr(options) {
 					error: msg
 				};
 			}
+			if (version === "both" && ipVersion === 6 && normalizedIp !== null) {
+				const mappedOctets = extractIpv4FromMapped(normalizedIp);
+				if (mappedOctets !== null) {
+					const restrictionError = checkIpv4MappedRestrictions(mappedOctets, normalizedIp, mappedIpv4Opts, mappedIpv4Errors);
+					if (restrictionError !== null) return restrictionError;
+				}
+			}
 			return {
 				success: true,
 				value: {

package/dist/valueparser.js

@@ -2636,6 +2636,90 @@ function compressIpv6(groups) {
 	else return before.join(":") + "::" + after.join(":");
 }
 /**
+* Extracts IPv4 octets from an IPv4-mapped IPv6 address.
+* Returns null if the address is not an IPv4-mapped address
+* (i.e., not in the `::ffff:x.x.x.x` range).
+*/
+function extractIpv4FromMapped(normalizedIpv6) {
+	const groups = expandIpv6(normalizedIpv6);
+	if (groups === null) return null;
+	for (let i = 0; i < 5; i++) if (parseInt(groups[i], 16) !== 0) return null;
+	if (parseInt(groups[5], 16) !== 65535) return null;
+	const high = parseInt(groups[6], 16);
+	const low = parseInt(groups[7], 16);
+	return [
+		high >> 8 & 255,
+		high & 255,
+		low >> 8 & 255,
+		low & 255
+	];
+}
+/**
+* Checks IPv4 restrictions against octets extracted from an IPv4-mapped
+* IPv6 address.  The check uses the base address, consistent with how
+* the `ipv4()` parser validates the address part of a regular IPv4 CIDR.
+*
+* Returns an error result if a restriction is violated, or null if all
+* checks pass.
+*/
+function checkIpv4MappedRestrictions(octets, normalizedIpv6, ipv4Opts, errors) {
+	const allowPrivate = ipv4Opts?.allowPrivate ?? true;
+	const allowLoopback = ipv4Opts?.allowLoopback ?? true;
+	const allowLinkLocal = ipv4Opts?.allowLinkLocal ?? true;
+	const allowMulticast = ipv4Opts?.allowMulticast ?? true;
+	const allowBroadcast = ipv4Opts?.allowBroadcast ?? true;
+	const allowZero = ipv4Opts?.allowZero ?? true;
+	if (!allowPrivate && isPrivateIp(octets)) {
+		const errorMsg = errors?.privateNotAllowed;
+		const msg = typeof errorMsg === "function" ? errorMsg(normalizedIpv6) : errorMsg ?? message`${normalizedIpv6} is a private IP address.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	if (!allowLoopback && isLoopbackIp(octets)) {
+		const errorMsg = errors?.loopbackNotAllowed;
+		const msg = typeof errorMsg === "function" ? errorMsg(normalizedIpv6) : errorMsg ?? message`${normalizedIpv6} is a loopback address.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	if (!allowLinkLocal && isLinkLocalIp(octets)) {
+		const errorMsg = errors?.linkLocalNotAllowed;
+		const msg = typeof errorMsg === "function" ? errorMsg(normalizedIpv6) : errorMsg ?? message`${normalizedIpv6} is a link-local address.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	if (!allowMulticast && isMulticastIp(octets)) {
+		const errorMsg = errors?.multicastNotAllowed;
+		const msg = typeof errorMsg === "function" ? errorMsg(normalizedIpv6) : errorMsg ?? message`${normalizedIpv6} is a multicast address.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	if (!allowBroadcast && isBroadcastIp(octets)) {
+		const errorMsg = errors?.broadcastNotAllowed;
+		const msg = typeof errorMsg === "function" ? errorMsg(normalizedIpv6) : errorMsg ?? message`${normalizedIpv6} is the broadcast address.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	if (!allowZero && isZeroIp(octets)) {
+		const errorMsg = errors?.zeroNotAllowed;
+		const msg = typeof errorMsg === "function" ? errorMsg(normalizedIpv6) : errorMsg ?? message`${normalizedIpv6} is the zero address.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	return null;
+}
+/**
 * Creates a value parser that accepts both IPv4 and IPv6 addresses.
 *
 * By default, accepts both IPv4 and IPv6 addresses. Use the `version` option
@@ -2688,6 +2772,22 @@ function ip(options) {
 			zeroNotAllowed: errors?.zeroNotAllowed
 		}
 	}) : null;
+	const mappedIpv4Opts = version === "both" ? {
+		allowPrivate: options?.ipv4?.allowPrivate,
+		allowLoopback: options?.ipv4?.allowLoopback,
+		allowLinkLocal: options?.ipv4?.allowLinkLocal,
+		allowMulticast: options?.ipv4?.allowMulticast,
+		allowBroadcast: options?.ipv4?.allowBroadcast,
+		allowZero: options?.ipv4?.allowZero
+	} : void 0;
+	const mappedIpv4Errors = version === "both" ? {
+		privateNotAllowed: errors?.privateNotAllowed,
+		loopbackNotAllowed: errors?.loopbackNotAllowed,
+		linkLocalNotAllowed: errors?.linkLocalNotAllowed,
+		multicastNotAllowed: errors?.multicastNotAllowed,
+		broadcastNotAllowed: errors?.broadcastNotAllowed,
+		zeroNotAllowed: errors?.zeroNotAllowed
+	} : void 0;
 	return {
 		$mode: "sync",
 		metavar,
@@ -2702,7 +2802,16 @@ function ip(options) {
 			}
 			if (ipv6Parser !== null) {
 				const result = ipv6Parser.parse(input);
-				if (result.success) return result;
+				if (result.success) {
+					if (version === "both") {
+						const mappedOctets = extractIpv4FromMapped(result.value);
+						if (mappedOctets !== null) {
+							const restrictionError = checkIpv4MappedRestrictions(mappedOctets, result.value, mappedIpv4Opts, mappedIpv4Errors);
+							if (restrictionError !== null) return restrictionError;
+						}
+					}
+					return result;
+				}
 				ipv6Error = result;
 				if (version === 6) return result;
 			}
@@ -2804,6 +2913,22 @@ function cidr(options) {
 			uniqueLocalNotAllowed: errors?.uniqueLocalNotAllowed
 		}
 	}) : null;
+	const mappedIpv4Opts = version === "both" ? {
+		allowPrivate: options?.ipv4?.allowPrivate,
+		allowLoopback: options?.ipv4?.allowLoopback,
+		allowLinkLocal: options?.ipv4?.allowLinkLocal,
+		allowMulticast: options?.ipv4?.allowMulticast,
+		allowBroadcast: options?.ipv4?.allowBroadcast,
+		allowZero: options?.ipv4?.allowZero
+	} : void 0;
+	const mappedIpv4Errors = version === "both" ? {
+		privateNotAllowed: errors?.privateNotAllowed,
+		loopbackNotAllowed: errors?.loopbackNotAllowed,
+		linkLocalNotAllowed: errors?.linkLocalNotAllowed,
+		multicastNotAllowed: errors?.multicastNotAllowed,
+		broadcastNotAllowed: errors?.broadcastNotAllowed,
+		zeroNotAllowed: errors?.zeroNotAllowed
+	} : void 0;
 	return {
 		$mode: "sync",
 		metavar,
@@ -3148,6 +3273,13 @@ function cidr(options) {
 					error: msg
 				};
 			}
+			if (version === "both" && ipVersion === 6 && normalizedIp !== null) {
+				const mappedOctets = extractIpv4FromMapped(normalizedIp);
+				if (mappedOctets !== null) {
+					const restrictionError = checkIpv4MappedRestrictions(mappedOctets, normalizedIp, mappedIpv4Opts, mappedIpv4Errors);
+					if (restrictionError !== null) return restrictionError;
+				}
+			}
 			return {
 				success: true,
 				value: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1452+b060cbd3",
+  "version": "1.0.0-dev.1461+fd58e837",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",