@optique/core 1.0.0-dev.487 → 1.0.0-dev.489

package/dist/doc.cjs

@@ -27,9 +27,10 @@ function scoreSection(section) {
 /**
 * The default section comparator: command-only sections come first, then
 * mixed sections, then option/argument-only sections.  Untitled sections
-* receive a slight priority boost so the main (untitled) section appears
-* before titled sections of a similar classification.  Sections with the
-* same score preserve their original relative order (stable sort).
+* receive a score bonus of -1 via {@link scoreSection} so that untitled
+* command-only sections naturally sort before titled command-only sections.
+* Sections with the same score preserve their original relative order
+* (stable sort).
 */
 function defaultSectionOrder(a, b) {
 	return scoreSection(a) - scoreSection(b);
@@ -103,8 +104,7 @@ function formatDocPage(programName, page, options = {}) {
 	})).toSorted((a, b) => {
 		const cmp = comparator(a.section, b.section);
 		if (cmp !== 0) return cmp;
-		const titleCmp = (a.section.title == null ? 0 : 1) - (b.section.title == null ? 0 : 1);
-		return titleCmp !== 0 ? titleCmp : a.index - b.index;
+		return a.index - b.index;
 	}).map(({ section }) => section);
 	for (const section of sections) {
 		if (section.entries.length < 1) continue;

package/dist/doc.js

@@ -27,9 +27,10 @@ function scoreSection(section) {
 /**
 * The default section comparator: command-only sections come first, then
 * mixed sections, then option/argument-only sections.  Untitled sections
-* receive a slight priority boost so the main (untitled) section appears
-* before titled sections of a similar classification.  Sections with the
-* same score preserve their original relative order (stable sort).
+* receive a score bonus of -1 via {@link scoreSection} so that untitled
+* command-only sections naturally sort before titled command-only sections.
+* Sections with the same score preserve their original relative order
+* (stable sort).
 */
 function defaultSectionOrder(a, b) {
 	return scoreSection(a) - scoreSection(b);
@@ -103,8 +104,7 @@ function formatDocPage(programName, page, options = {}) {
 	})).toSorted((a, b) => {
 		const cmp = comparator(a.section, b.section);
 		if (cmp !== 0) return cmp;
-		const titleCmp = (a.section.title == null ? 0 : 1) - (b.section.title == null ? 0 : 1);
-		return titleCmp !== 0 ? titleCmp : a.index - b.index;
+		return a.index - b.index;
 	}).map(({ section }) => section);
 	for (const section of sections) {
 		if (section.entries.length < 1) continue;

package/dist/facade.d.cts

@@ -32,6 +32,7 @@ interface CommandSubConfig {
    * - `true`: Hidden from usage, documentation, and suggestions.
    * - `"usage"`: Hidden from usage lines only.
    * - `"doc"`: Hidden from documentation only.
+   * - `"help"`: Hidden from usage and documentation only.
    */
   readonly hidden?: HiddenVisibility;
 }
@@ -55,6 +56,7 @@ interface OptionSubConfig {
    * - `true`: Hidden from usage, documentation, and suggestions.
    * - `"usage"`: Hidden from usage lines only.
    * - `"doc"`: Hidden from documentation only.
+   * - `"help"`: Hidden from usage and documentation only.
    */
   readonly hidden?: HiddenVisibility;
 }

package/dist/facade.d.ts

@@ -32,6 +32,7 @@ interface CommandSubConfig {
    * - `true`: Hidden from usage, documentation, and suggestions.
    * - `"usage"`: Hidden from usage lines only.
    * - `"doc"`: Hidden from documentation only.
+   * - `"help"`: Hidden from usage and documentation only.
    */
   readonly hidden?: HiddenVisibility;
 }
@@ -55,6 +56,7 @@ interface OptionSubConfig {
    * - `true`: Hidden from usage, documentation, and suggestions.
    * - `"usage"`: Hidden from usage lines only.
    * - `"doc"`: Hidden from documentation only.
+   * - `"help"`: Hidden from usage and documentation only.
    */
   readonly hidden?: HiddenVisibility;
 }

package/dist/parser.cjs

@@ -387,14 +387,34 @@ function buildDocPage(parser, context, args) {
 		kind: "available",
 		state: context.state
 	}, void 0);
-	const entries = fragments.filter((f) => f.type === "entry");
-	const sections = [];
-	for (const fragment of fragments) {
-		if (fragment.type !== "section") continue;
-		if (fragment.title == null) entries.push(...fragment.entries);
-		else sections.push(fragment);
+	const buildingSections = [];
+	let untitledSection = null;
+	const titledSectionMap = /* @__PURE__ */ new Map();
+	for (const fragment of fragments) if (fragment.type === "entry") {
+		if (untitledSection == null) {
+			untitledSection = { entries: [] };
+			buildingSections.push(untitledSection);
+		}
+		untitledSection.entries.push(fragment);
+	} else if (fragment.type === "section") if (fragment.title == null) {
+		if (untitledSection == null) {
+			untitledSection = { entries: [] };
+			buildingSections.push(untitledSection);
+		}
+		untitledSection.entries.push(...fragment.entries);
+	} 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(...fragment.entries);
 	}
-	if (entries.length > 0) sections.push({ entries });
+	const sections = buildingSections;
 	const usage = [...require_usage.normalizeUsage(parser.usage)];
 	let i = 0;
 	for (const arg of args) {

package/dist/parser.js

@@ -387,14 +387,34 @@ function buildDocPage(parser, context, args) {
 		kind: "available",
 		state: context.state
 	}, void 0);
-	const entries = fragments.filter((f) => f.type === "entry");
-	const sections = [];
-	for (const fragment of fragments) {
-		if (fragment.type !== "section") continue;
-		if (fragment.title == null) entries.push(...fragment.entries);
-		else sections.push(fragment);
+	const buildingSections = [];
+	let untitledSection = null;
+	const titledSectionMap = /* @__PURE__ */ new Map();
+	for (const fragment of fragments) if (fragment.type === "entry") {
+		if (untitledSection == null) {
+			untitledSection = { entries: [] };
+			buildingSections.push(untitledSection);
+		}
+		untitledSection.entries.push(fragment);
+	} else if (fragment.type === "section") if (fragment.title == null) {
+		if (untitledSection == null) {
+			untitledSection = { entries: [] };
+			buildingSections.push(untitledSection);
+		}
+		untitledSection.entries.push(...fragment.entries);
+	} 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(...fragment.entries);
 	}
-	if (entries.length > 0) sections.push({ entries });
+	const sections = buildingSections;
 	const usage = [...normalizeUsage(parser.usage)];
 	let i = 0;
 	for (const arg of args) {

package/dist/primitives.d.cts

@@ -52,6 +52,7 @@ interface OptionOptions {
    * - `true`: hide from usage, docs, and suggestions
    * - `"usage"`: hide from usage only
    * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
    *
    * @since 0.9.0
    */
@@ -166,6 +167,7 @@ interface FlagOptions {
    * - `true`: hide from usage, docs, and suggestions
    * - `"usage"`: hide from usage only
    * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
    *
    * @since 0.9.0
    */
@@ -255,6 +257,7 @@ interface ArgumentOptions {
    * - `true`: hide from usage, docs, and suggestions
    * - `"usage"`: hide from usage only
    * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
    *
    * @since 0.9.0
    */
@@ -329,6 +332,7 @@ interface CommandOptions {
    * - `true`: hide from usage, docs, and suggestions
    * - `"usage"`: hide from usage only
    * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
    *
    * @since 0.9.0
    */
@@ -416,6 +420,7 @@ interface PassThroughOptions {
    * - `true`: hide from usage, docs, and suggestions
    * - `"usage"`: hide from usage only
    * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
    *
    * @since 0.9.0
    */

package/dist/primitives.d.ts

@@ -52,6 +52,7 @@ interface OptionOptions {
    * - `true`: hide from usage, docs, and suggestions
    * - `"usage"`: hide from usage only
    * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
    *
    * @since 0.9.0
    */
@@ -166,6 +167,7 @@ interface FlagOptions {
    * - `true`: hide from usage, docs, and suggestions
    * - `"usage"`: hide from usage only
    * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
    *
    * @since 0.9.0
    */
@@ -255,6 +257,7 @@ interface ArgumentOptions {
    * - `true`: hide from usage, docs, and suggestions
    * - `"usage"`: hide from usage only
    * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
    *
    * @since 0.9.0
    */
@@ -329,6 +332,7 @@ interface CommandOptions {
    * - `true`: hide from usage, docs, and suggestions
    * - `"usage"`: hide from usage only
    * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
    *
    * @since 0.9.0
    */
@@ -416,6 +420,7 @@ interface PassThroughOptions {
    * - `true`: hide from usage, docs, and suggestions
    * - `"usage"`: hide from usage only
    * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
    *
    * @since 0.9.0
    */

package/dist/usage.cjs

@@ -4,13 +4,13 @@
 * Returns whether the term should be hidden from usage output.
 */
 function isUsageHidden(hidden) {
-	return hidden === true || hidden === "usage";
+	return hidden === true || hidden === "usage" || hidden === "help";
 }
 /**
 * Returns whether the term should be hidden from documentation output.
 */
 function isDocHidden(hidden) {
-	return hidden === true || hidden === "doc";
+	return hidden === true || hidden === "doc" || hidden === "help";
 }
 /**
 * Returns whether the term should be hidden from suggestion/error candidates.
@@ -25,7 +25,11 @@ function mergeHidden(a, b) {
 	if (a == null) return b;
 	if (b == null) return a;
 	if (a === true || b === true) return true;
-	if (a !== b) return true;
+	if (a === false) return b;
+	if (b === false) return a;
+	if (a === b) return a;
+	if (a === "help" || b === "help") return "help";
+	if ((a === "usage" || a === "doc") && (b === "usage" || b === "doc")) return "help";
 	return a;
 }
 /**

package/dist/usage.d.cts

@@ -18,8 +18,9 @@ type OptionName = `--${string}` | `-${string}` | `/${string}` | `+${string}`;
  * - `true`: hidden from usage, documentation, and suggestions
  * - `"usage"`: hidden from usage only
  * - `"doc"`: hidden from documentation only
+ * - `"help"`: hidden from usage and documentation, but shown in suggestions
  */
-type HiddenVisibility = boolean | "usage" | "doc";
+type HiddenVisibility = boolean | "usage" | "doc" | "help";
 /**
  * Returns whether the term should be hidden from usage output.
  */

package/dist/usage.d.ts

@@ -18,8 +18,9 @@ type OptionName = `--${string}` | `-${string}` | `/${string}` | `+${string}`;
  * - `true`: hidden from usage, documentation, and suggestions
  * - `"usage"`: hidden from usage only
  * - `"doc"`: hidden from documentation only
+ * - `"help"`: hidden from usage and documentation, but shown in suggestions
  */
-type HiddenVisibility = boolean | "usage" | "doc";
+type HiddenVisibility = boolean | "usage" | "doc" | "help";
 /**
  * Returns whether the term should be hidden from usage output.
  */

package/dist/usage.js

@@ -3,13 +3,13 @@
 * Returns whether the term should be hidden from usage output.
 */
 function isUsageHidden(hidden) {
-	return hidden === true || hidden === "usage";
+	return hidden === true || hidden === "usage" || hidden === "help";
 }
 /**
 * Returns whether the term should be hidden from documentation output.
 */
 function isDocHidden(hidden) {
-	return hidden === true || hidden === "doc";
+	return hidden === true || hidden === "doc" || hidden === "help";
 }
 /**
 * Returns whether the term should be hidden from suggestion/error candidates.
@@ -24,7 +24,11 @@ function mergeHidden(a, b) {
 	if (a == null) return b;
 	if (b == null) return a;
 	if (a === true || b === true) return true;
-	if (a !== b) return true;
+	if (a === false) return b;
+	if (b === false) return a;
+	if (a === b) return a;
+	if (a === "help" || b === "help") return "help";
+	if ((a === "usage" || a === "doc") && (b === "usage" || b === "doc")) return "help";
 	return a;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.487+3c38bb65",
+  "version": "1.0.0-dev.489+709d13c5",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",