@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/program.cjs

@@ -1,3 +1,4 @@
+const require_validate = require('./validate.cjs');
 
 //#region src/program.ts
 /**
@@ -11,6 +12,8 @@
 * @template T - The type of value produced by the parser.
 * @param program - The program definition with parser and metadata.
 * @returns The same program object with inferred types.
+* @throws {TypeError} If `program.metadata.name` is not a string, is empty,
+*         is whitespace-only, or contains control characters.
 *
 * @example
 * ```typescript
@@ -34,9 +37,10 @@
 * // Program<"sync", { readonly name: string }>
 * ```
 *
-* @since 0.11.0
+* @since 1.0.0
 */
 function defineProgram(program) {
+	require_validate.validateProgramName(program.metadata.name);
 	return program;
 }
 

package/dist/program.d.cts

@@ -1,5 +1,5 @@
 import { Message } from "./message.cjs";
-import { Mode, Parser } from "./parser.cjs";
+import { Mode, Parser } from "./internal/parser.cjs";
 
 //#region src/program.d.ts
 
@@ -71,7 +71,7 @@ interface ProgramMetadata {
  * };
  * ```
  *
- * @since 0.11.0
+ * @since 1.0.0
  */
 interface Program<M extends Mode, T> {
   /**
@@ -94,6 +94,8 @@ interface Program<M extends Mode, T> {
  * @template T - The type of value produced by the parser.
  * @param program - The program definition with parser and metadata.
  * @returns The same program object with inferred types.
+ * @throws {TypeError} If `program.metadata.name` is not a string, is empty,
+ *         is whitespace-only, or contains control characters.
  *
  * @example
  * ```typescript
@@ -117,7 +119,7 @@ interface Program<M extends Mode, T> {
  * // Program<"sync", { readonly name: string }>
  * ```
  *
- * @since 0.11.0
+ * @since 1.0.0
  */
 declare function defineProgram<M extends Mode, T>(program: Program<M, T>): Program<M, T>;
 //#endregion

package/dist/program.d.ts

@@ -1,5 +1,5 @@
 import { Message } from "./message.js";
-import { Mode, Parser } from "./parser.js";
+import { Mode, Parser } from "./internal/parser.js";
 
 //#region src/program.d.ts
 
@@ -71,7 +71,7 @@ interface ProgramMetadata {
  * };
  * ```
  *
- * @since 0.11.0
+ * @since 1.0.0
  */
 interface Program<M extends Mode, T> {
   /**
@@ -94,6 +94,8 @@ interface Program<M extends Mode, T> {
  * @template T - The type of value produced by the parser.
  * @param program - The program definition with parser and metadata.
  * @returns The same program object with inferred types.
+ * @throws {TypeError} If `program.metadata.name` is not a string, is empty,
+ *         is whitespace-only, or contains control characters.
  *
  * @example
  * ```typescript
@@ -117,7 +119,7 @@ interface Program<M extends Mode, T> {
  * // Program<"sync", { readonly name: string }>
  * ```
  *
- * @since 0.11.0
+ * @since 1.0.0
  */
 declare function defineProgram<M extends Mode, T>(program: Program<M, T>): Program<M, T>;
 //#endregion

package/dist/program.js

@@ -1,3 +1,5 @@
+import { validateProgramName } from "./validate.js";
+
 //#region src/program.ts
 /**
 * Defines a CLI program with a parser and metadata.
@@ -10,6 +12,8 @@
 * @template T - The type of value produced by the parser.
 * @param program - The program definition with parser and metadata.
 * @returns The same program object with inferred types.
+* @throws {TypeError} If `program.metadata.name` is not a string, is empty,
+*         is whitespace-only, or contains control characters.
 *
 * @example
 * ```typescript
@@ -33,9 +37,10 @@
 * // Program<"sync", { readonly name: string }>
 * ```
 *
-* @since 0.11.0
+* @since 1.0.0
 */
 function defineProgram(program) {
+	validateProgramName(program.metadata.name);
 	return program;
 }
 

package/dist/suggestion.cjs

@@ -81,8 +81,11 @@ function findSimilar(input, candidates, options = {}) {
 	if (input.length === 0) return [];
 	const normalizedInput = caseSensitive ? input : input.toLowerCase();
 	const matches = [];
+	const seen = /* @__PURE__ */ new Set();
 	for (const candidate of candidates) {
 		const normalizedCandidate = caseSensitive ? candidate : candidate.toLowerCase();
+		if (seen.has(candidate)) continue;
+		seen.add(candidate);
 		const distance = levenshteinDistance(normalizedInput, normalizedCandidate);
 		if (distance === 0) return [candidate];
 		const distanceRatio = distance / input.length;
@@ -192,7 +195,7 @@ function createErrorWithSuggestions(baseError, invalidInput, usage, type = "both
 */
 function getSuggestionKey(suggestion) {
 	if (suggestion.kind === "literal") return suggestion.text;
-	return `__FILE__:${suggestion.type}:${suggestion.extensions?.join(",") ?? ""}:${suggestion.pattern ?? ""}`;
+	return `__FILE__:${suggestion.type}:${suggestion.extensions?.toSorted().join(",") ?? ""}:${suggestion.pattern ?? ""}`;
 }
 /**
 * Removes duplicate suggestions from an array while preserving order.
@@ -201,7 +204,11 @@ function getSuggestionKey(suggestion) {
 * - Literal suggestions: same text
 * - File suggestions: same type, extensions, and pattern
 *
-* The first occurrence of each unique suggestion is kept.
+* The first occurrence of each unique suggestion is kept.  For file
+* suggestions, `includeHidden` is merged across duplicates: if any
+* duplicate has `includeHidden: true`, the kept suggestion is upgraded
+* to `includeHidden: true` because it is a superset of the non-hidden
+* variant.
 *
 * @param suggestions Array of suggestions that may contain duplicates
 * @returns A new array with duplicates removed, preserving order of first occurrences
@@ -220,13 +227,20 @@ function getSuggestionKey(suggestion) {
 * @since 0.9.0
 */
 function deduplicateSuggestions(suggestions) {
-	const seen = /* @__PURE__ */ new Set();
-	return suggestions.filter((suggestion) => {
+	const entries = /* @__PURE__ */ new Map();
+	const order = [];
+	for (const suggestion of suggestions) {
 		const key = getSuggestionKey(suggestion);
-		if (seen.has(key)) return false;
-		seen.add(key);
-		return true;
-	});
+		const existing = entries.get(key);
+		if (existing == null) {
+			entries.set(key, suggestion);
+			order.push(key);
+		} else if (suggestion.kind === "file" && existing.kind === "file" && suggestion.includeHidden === true && existing.includeHidden !== true) entries.set(key, {
+			...existing,
+			includeHidden: true
+		});
+	}
+	return order.map((key) => entries.get(key));
 }
 
 //#endregion

package/dist/suggestion.js

@@ -81,8 +81,11 @@ function findSimilar(input, candidates, options = {}) {
 	if (input.length === 0) return [];
 	const normalizedInput = caseSensitive ? input : input.toLowerCase();
 	const matches = [];
+	const seen = /* @__PURE__ */ new Set();
 	for (const candidate of candidates) {
 		const normalizedCandidate = caseSensitive ? candidate : candidate.toLowerCase();
+		if (seen.has(candidate)) continue;
+		seen.add(candidate);
 		const distance = levenshteinDistance(normalizedInput, normalizedCandidate);
 		if (distance === 0) return [candidate];
 		const distanceRatio = distance / input.length;
@@ -192,7 +195,7 @@ function createErrorWithSuggestions(baseError, invalidInput, usage, type = "both
 */
 function getSuggestionKey(suggestion) {
 	if (suggestion.kind === "literal") return suggestion.text;
-	return `__FILE__:${suggestion.type}:${suggestion.extensions?.join(",") ?? ""}:${suggestion.pattern ?? ""}`;
+	return `__FILE__:${suggestion.type}:${suggestion.extensions?.toSorted().join(",") ?? ""}:${suggestion.pattern ?? ""}`;
 }
 /**
 * Removes duplicate suggestions from an array while preserving order.
@@ -201,7 +204,11 @@ function getSuggestionKey(suggestion) {
 * - Literal suggestions: same text
 * - File suggestions: same type, extensions, and pattern
 *
-* The first occurrence of each unique suggestion is kept.
+* The first occurrence of each unique suggestion is kept.  For file
+* suggestions, `includeHidden` is merged across duplicates: if any
+* duplicate has `includeHidden: true`, the kept suggestion is upgraded
+* to `includeHidden: true` because it is a superset of the non-hidden
+* variant.
 *
 * @param suggestions Array of suggestions that may contain duplicates
 * @returns A new array with duplicates removed, preserving order of first occurrences
@@ -220,13 +227,20 @@ function getSuggestionKey(suggestion) {
 * @since 0.9.0
 */
 function deduplicateSuggestions(suggestions) {
-	const seen = /* @__PURE__ */ new Set();
-	return suggestions.filter((suggestion) => {
+	const entries = /* @__PURE__ */ new Map();
+	const order = [];
+	for (const suggestion of suggestions) {
 		const key = getSuggestionKey(suggestion);
-		if (seen.has(key)) return false;
-		seen.add(key);
-		return true;
-	});
+		const existing = entries.get(key);
+		if (existing == null) {
+			entries.set(key, suggestion);
+			order.push(key);
+		} else if (suggestion.kind === "file" && existing.kind === "file" && suggestion.includeHidden === true && existing.includeHidden !== true) entries.set(key, {
+			...existing,
+			includeHidden: true
+		});
+	}
+	return order.map((key) => entries.get(key));
 }
 
 //#endregion

package/dist/usage-internals.cjs

@@ -1,3 +1,4 @@
+const require_usage = require('./usage.cjs');
 
 //#region src/usage-internals.ts
 /**
@@ -19,11 +20,11 @@ function collectLeadingCandidates(terms, optionNames, commandNames) {
 	if (!terms || !Array.isArray(terms)) return true;
 	for (const term of terms) {
 		if (term.type === "option") {
-			for (const name of term.names) optionNames.add(name);
+			if (!require_usage.isSuggestionHidden(term.hidden)) for (const name of term.names) optionNames.add(name);
 			return false;
 		}
 		if (term.type === "command") {
-			commandNames.add(term.name);
+			if (!require_usage.isSuggestionHidden(term.hidden)) commandNames.add(term.name);
 			return false;
 		}
 		if (term.type === "argument") return false;

package/dist/usage-internals.js

@@ -1,3 +1,5 @@
+import { isSuggestionHidden } from "./usage.js";
+
 //#region src/usage-internals.ts
 /**
 * Collects option names and command names that are valid as the *immediate*
@@ -18,11 +20,11 @@ function collectLeadingCandidates(terms, optionNames, commandNames) {
 	if (!terms || !Array.isArray(terms)) return true;
 	for (const term of terms) {
 		if (term.type === "option") {
-			for (const name of term.names) optionNames.add(name);
+			if (!isSuggestionHidden(term.hidden)) for (const name of term.names) optionNames.add(name);
 			return false;
 		}
 		if (term.type === "command") {
-			commandNames.add(term.name);
+			if (!isSuggestionHidden(term.hidden)) commandNames.add(term.name);
 			return false;
 		}
 		if (term.type === "argument") return false;