clap-ts 0.2.0 → 0.3.0

package/dist/validation.js

@@ -4,7 +4,59 @@
  * valueParser, numArgs, requiredUnlessPresent, requiredIfEq, groups.
  * Includes typo suggestion via Levenshtein distance.
  */
-import { CliParseError } from './parser.js';
+import { CliParseError, matchesPossibleValue, possibleValues, subCommandsOf, } from './parser.js';
+const specCache = new WeakMap();
+function buildValidationSpec(command) {
+    const entries = [];
+    const exclusive = [];
+    const required = [];
+    const requiredIfEq = [];
+    const valueParser = [];
+    const conflicts = [];
+    const requires = [];
+    const numArgs = [];
+    const argsDef = command.args ?? {};
+    for (const key of Object.keys(argsDef)) {
+        const def = argsDef[key];
+        const entry = [key, def];
+        entries.push(entry);
+        if (def.exclusive) {
+            exclusive.push(entry);
+        }
+        if (def.required && def.default === undefined) {
+            required.push(entry);
+        }
+        if (def.requiredIfEq || def.requiredIfEqAny || def.requiredIfEqAll) {
+            requiredIfEq.push(entry);
+        }
+        if (def.valueParser) {
+            valueParser.push(entry);
+        }
+        if (def.conflictsWith && def.conflictsWith.length > 0) {
+            conflicts.push(entry);
+        }
+        if ((def.requires && def.requires.length > 0) ||
+            def.requiresIf !== undefined ||
+            def.requiresIfs !== undefined) {
+            requires.push(entry);
+        }
+        // The parser enforces numArgs per occurrence while consuming tokens, the
+        // way clap does. Only positionals and delimiter-split values reach here
+        // without having been counted.
+        if (def.numArgs && (def.type === 'positional' || def.valueDelimiter !== undefined)) {
+            numArgs.push(entry);
+        }
+    }
+    return { entries, exclusive, required, requiredIfEq, valueParser, conflicts, requires, numArgs };
+}
+function getValidationSpec(command) {
+    let spec = specCache.get(command);
+    if (spec === undefined) {
+        spec = buildValidationSpec(command);
+        specCache.set(command, spec);
+    }
+    return spec;
+}
 // ---- Levenshtein Distance ----
 /**
  * Calculate Levenshtein distance between two strings.
@@ -91,10 +143,7 @@ function collectKnownFlags(argsDef) {
  */
 function collectKnownSubcommands(command) {
     const names = [];
-    if (!command.subCommands) {
-        return names;
-    }
-    for (const [name, def] of Object.entries(command.subCommands)) {
+    for (const [name, def] of Object.entries(subCommandsOf(command))) {
         names.push(name);
         if (def.meta.aliases) {
             for (const alias of def.meta.aliases) {
@@ -135,11 +184,8 @@ function validateUnknownFlags(unknown, argsDef, command) {
     }
 }
 /** Validate exclusive args -- cannot be used with any other arg. */
-function validateExclusive(argsDef, args, explicitlySet) {
-    for (const [key, def] of Object.entries(argsDef)) {
-        if (!def.exclusive) {
-            continue;
-        }
+function validateExclusive(spec, argsDef, explicitlySet) {
+    for (const [key, def] of spec.exclusive) {
         if (!explicitlySet.has(key)) {
             continue;
         }
@@ -162,19 +208,13 @@ function validateExclusive(argsDef, args, explicitlySet) {
  * Validate that all required args are present.
  * Respects requiredUnlessPresent and subcommandNegatesReqs.
  */
-function validateRequired(argsDef, args, skipRequired) {
+function validateRequired(spec, argsDef, args, skipRequired) {
     if (skipRequired) {
         return;
     }
     const missing = [];
-    for (const [key, def] of Object.entries(argsDef)) {
-        if (!def.required) {
-            continue;
-        }
-        if (def.default !== undefined) {
-            continue;
-        }
-        // requiredUnlessPresent: skip if the named arg(s) are present
+    for (const [key, def] of spec.required) {
+        // requiredUnlessPresent: skip if any of the named args is present
         if (def.requiredUnlessPresent) {
             const unlessArgs = Array.isArray(def.requiredUnlessPresent)
                 ? def.requiredUnlessPresent
@@ -183,6 +223,12 @@ function validateRequired(argsDef, args, skipRequired) {
                 continue;
             }
         }
+        // requiredUnlessPresentAll: skip only when every named arg is present
+        if (def.requiredUnlessPresentAll &&
+            def.requiredUnlessPresentAll.length > 0 &&
+            def.requiredUnlessPresentAll.every((name) => isArgSet(args[name], argsDef[name]?.type))) {
+            continue;
+        }
         const value = args[key];
         if (value === undefined) {
             const displayName = def.type === 'positional' ? `<${def.valueName ?? key}>` : `--${def.long ?? key}`;
@@ -195,28 +241,28 @@ function validateRequired(argsDef, args, skipRequired) {
     }
 }
 /** Validate requiredIfEq -- arg required when another arg equals a specific value. */
-function validateRequiredIfEq(argsDef, args) {
-    for (const [key, def] of Object.entries(argsDef)) {
-        if (!def.requiredIfEq) {
-            continue;
-        }
-        const [otherKey, otherValue] = def.requiredIfEq;
-        const otherArgValue = args[otherKey];
-        // Check if the other arg's value matches the condition
-        if (otherArgValue !== undefined && String(otherArgValue) === otherValue) {
-            if (!isArgSet(args[key], def.type)) {
-                const displayName = def.type === 'positional' ? `<${def.valueName ?? key}>` : `--${def.long ?? key}`;
-                throw new CliParseError(`the following required arguments were not provided:\n  ${displayName}`);
-            }
+function validateRequiredIfEq(spec, args) {
+    const holds = (args, [otherKey, otherValue]) => {
+        const actual = args[otherKey];
+        return actual !== undefined && String(actual) === otherValue;
+    };
+    for (const [key, def] of spec.requiredIfEq) {
+        let isRequired = def.requiredIfEq !== undefined && holds(args, def.requiredIfEq);
+        if (!isRequired && def.requiredIfEqAny) {
+            isRequired = def.requiredIfEqAny.some((condition) => holds(args, condition));
+        }
+        if (!isRequired && def.requiredIfEqAll && def.requiredIfEqAll.length > 0) {
+            isRequired = def.requiredIfEqAll.every((condition) => holds(args, condition));
+        }
+        if (isRequired && !isArgSet(args[key], def.type)) {
+            const displayName = def.type === 'positional' ? `<${def.valueName ?? key}>` : `--${def.long ?? key}`;
+            throw new CliParseError(`the following required arguments were not provided:\n  ${displayName}`);
         }
     }
 }
 /** Validate valueParser (enum-like restricted values). */
-function validateValueParser(argsDef, args) {
-    for (const [key, def] of Object.entries(argsDef)) {
-        if (!def.valueParser) {
-            continue;
-        }
+function validateValueParser(spec, args) {
+    for (const [key, def] of spec.valueParser) {
         const value = args[key];
         if (value === undefined) {
             continue;
@@ -227,15 +273,22 @@ function validateValueParser(argsDef, args) {
             continue;
         }
         // Enum-style value parser: validate against allowed values
-        if (def.valueParser.length === 0) {
+        const possible = possibleValues(def);
+        if (possible.length === 0) {
             continue;
         }
+        const ignoreCase = def.ignoreCase === true;
         const valueName = def.valueName ?? longName.toUpperCase();
+        // A positional has no flag to name, so it is shown as just its placeholder.
+        const target = def.type === 'positional' ? `<${valueName}>` : `--${longName} <${valueName}>`;
         const values = Array.isArray(value) ? value : [String(value)];
         for (const v of values) {
-            if (!def.valueParser.includes(v)) {
-                const possibleStr = def.valueParser.join(', ');
-                throw new CliParseError(`invalid value '${v}' for '--${longName} <${valueName}>'\n  [possible values: ${possibleStr}]`);
+            if (!possible.some((candidate) => matchesPossibleValue(candidate, v, ignoreCase))) {
+                const possibleStr = possible
+                    .filter((candidate) => !candidate.hidden)
+                    .map((candidate) => candidate.name)
+                    .join(', ');
+                throw new CliParseError(`invalid value '${v}' for '${target}'\n  [possible values: ${possibleStr}]`);
             }
         }
     }
@@ -250,11 +303,8 @@ function formatFlagForError(key, def) {
     return `'--${longName}'`;
 }
 /** Validate conflictsWith constraints. */
-function validateConflicts(argsDef, args) {
-    for (const [key, def] of Object.entries(argsDef)) {
-        if (!def.conflictsWith || def.conflictsWith.length === 0) {
-            continue;
-        }
+function validateConflicts(spec, argsDef, args) {
+    for (const [key, def] of spec.conflicts) {
         if (!isArgSet(args[key], def.type)) {
             continue;
         }
@@ -272,16 +322,28 @@ function validateConflicts(argsDef, args) {
     }
 }
 /** Validate requires constraints. */
-function validateRequires(argsDef, args) {
-    for (const [key, def] of Object.entries(argsDef)) {
-        if (!def.requires || def.requires.length === 0) {
+function validateRequires(spec, argsDef, args) {
+    for (const [key, def] of spec.requires) {
+        const own = args[key];
+        if (!isArgSet(own, def.type)) {
             continue;
         }
-        if (!isArgSet(args[key], def.type)) {
-            continue;
+        // requires applies whenever the arg is present; requiresIf only when it
+        // holds a particular value.
+        const needed = [...(def.requires ?? [])];
+        const ownValue = String(own);
+        if (def.requiresIf && def.requiresIf[0] === ownValue) {
+            needed.push(def.requiresIf[1]);
+        }
+        if (def.requiresIfs) {
+            for (const [whenValue, requiredKey] of def.requiresIfs) {
+                if (whenValue === ownValue) {
+                    needed.push(requiredKey);
+                }
+            }
         }
         const missing = [];
-        for (const requiredKey of def.requires) {
+        for (const requiredKey of needed) {
             const requiredDef = argsDef[requiredKey];
             if (!isArgSet(args[requiredKey], requiredDef?.type)) {
                 missing.push(`--${requiredDef?.long ?? requiredKey}`);
@@ -294,11 +356,8 @@ function validateRequires(argsDef, args) {
     }
 }
 /** Validate numArgs constraints. */
-function validateNumArgs(argsDef, args) {
-    for (const [key, def] of Object.entries(argsDef)) {
-        if (!def.numArgs) {
-            continue;
-        }
+function validateNumArgs(spec, args) {
+    for (const [key, def] of spec.numArgs) {
         const value = args[key];
         if (value === undefined) {
             continue;
@@ -312,21 +371,81 @@ function validateNumArgs(argsDef, args) {
         }
     }
 }
+/**
+ * Collect the effective groups: those declared on the command, widened by any
+ * arg that names the group itself via `groups`.
+ */
+function collectGroups(command, argsDef) {
+    const declared = command.groups ?? [];
+    const byName = new Map();
+    for (const key of Object.keys(argsDef)) {
+        const def = argsDef[key];
+        if (def.group === undefined && def.groups === undefined) {
+            continue;
+        }
+        const memberships = def.group === undefined ? def.groups : [def.group, ...(def.groups ?? [])];
+        for (const name of memberships) {
+            const members = byName.get(name);
+            if (members === undefined) {
+                byName.set(name, [key]);
+            }
+            else {
+                members.push(key);
+            }
+        }
+    }
+    if (byName.size === 0) {
+        return declared;
+    }
+    const merged = [];
+    for (const group of declared) {
+        const extra = byName.get(group.name);
+        if (extra === undefined) {
+            merged.push(group);
+            continue;
+        }
+        byName.delete(group.name);
+        merged.push({ ...group, args: [...group.args, ...extra.filter((a) => !group.args.includes(a))] });
+    }
+    for (const [name, members] of byName) {
+        merged.push({ name, args: members });
+    }
+    return merged;
+}
 /** Validate argument groups. */
 function validateGroups(command, argsDef, args) {
-    if (!command.groups) {
+    const groups = collectGroups(command, argsDef);
+    if (groups.length === 0) {
         return;
     }
-    for (const group of command.groups) {
+    const flagName = (name) => `'--${argsDef[name]?.long ?? name}'`;
+    for (const group of groups) {
         const setArgs = group.args.filter((argName) => isArgSet(args[argName], argsDef[argName]?.type));
         if (group.required && setArgs.length === 0) {
-            const argList = group.args.map((a) => `'--${argsDef[a]?.long ?? a}'`).join(', ');
+            const argList = group.args.map(flagName).join(', ');
             throw new CliParseError(`one of the following arguments must be provided: ${argList}`);
         }
         if (!group.multiple && setArgs.length > 1) {
-            const argList = setArgs.map((a) => `'--${argsDef[a]?.long ?? a}'`).join(', ');
+            const argList = setArgs.map(flagName).join(', ');
             throw new CliParseError(`the following arguments cannot be used together: ${argList}`);
         }
+        if (setArgs.length === 0) {
+            continue;
+        }
+        if (group.conflictsWith) {
+            for (const other of group.conflictsWith) {
+                if (isArgSet(args[other], argsDef[other]?.type)) {
+                    throw new CliParseError(`the argument ${flagName(setArgs[0])} cannot be used with ${flagName(other)}`);
+                }
+            }
+        }
+        if (group.requires) {
+            const missing = group.requires.filter((other) => !isArgSet(args[other], argsDef[other]?.type));
+            if (missing.length > 0) {
+                const lines = missing.map((m) => `  --${argsDef[m]?.long ?? m}`).join('\n');
+                throw new CliParseError(`the following required arguments were not provided:\n${lines}`);
+            }
+        }
     }
 }
 /**
@@ -338,15 +457,18 @@ export function validate(parseResult, command) {
     const { args, unknown, explicitlySet } = parseResult;
     // Determine if required validation should be skipped (subcommandNegatesReqs)
     const skipRequired = command.meta.subcommandNegatesReqs === true && parseResult.subCommand !== undefined;
-    validateUnknownFlags(unknown, argsDef, command);
-    validateExclusive(argsDef, args, explicitlySet);
-    validateRequired(argsDef, args, skipRequired);
+    const spec = getValidationSpec(command);
+    if (unknown.length > 0) {
+        validateUnknownFlags(unknown, argsDef, command);
+    }
+    validateExclusive(spec, argsDef, explicitlySet);
+    validateRequired(spec, argsDef, args, skipRequired);
     if (!skipRequired) {
-        validateRequiredIfEq(argsDef, args);
+        validateRequiredIfEq(spec, args);
     }
-    validateValueParser(argsDef, args);
-    validateConflicts(argsDef, args);
-    validateRequires(argsDef, args);
-    validateNumArgs(argsDef, args);
+    validateValueParser(spec, args);
+    validateConflicts(spec, argsDef, args);
+    validateRequires(spec, argsDef, args);
+    validateNumArgs(spec, args);
     validateGroups(command, argsDef, args);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clap-ts",
-  "version": "0.2.0",
-  "description": "A type-safe CLI argument parser for TypeScript, inspired by Rust's clap crate. Full clap-style parsing, validation, help generation, and subcommand support with zero dependencies.",
+  "version": "0.3.0",
+  "description": "A type-safe CLI argument parser for TypeScript, inspired by Rust's clap crate. Full clap-style parsing, validation, help, subcommands, shell completions, man pages and markdown docs, with zero dependencies.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,6 +9,58 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./completions": {
+      "types": "./dist/completions.d.ts",
+      "import": "./dist/completions.js"
+    },
+    "./man": {
+      "types": "./dist/man.d.ts",
+      "import": "./dist/man.js"
+    },
+    "./markdown": {
+      "types": "./dist/markdown.d.ts",
+      "import": "./dist/markdown.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    },
+    "./argfile": {
+      "types": "./dist/argfile.d.ts",
+      "import": "./dist/argfile.js"
+    },
+    "./spec": {
+      "types": "./dist/spec.d.ts",
+      "import": "./dist/spec.js"
+    },
+    "./install": {
+      "types": "./dist/install.d.ts",
+      "import": "./dist/install.js"
+    },
+    "./plugins": {
+      "types": "./dist/plugins.d.ts",
+      "import": "./dist/plugins.js"
+    },
+    "./output": {
+      "types": "./dist/output.d.ts",
+      "import": "./dist/output.js"
+    },
+    "./log": {
+      "types": "./dist/log.d.ts",
+      "import": "./dist/log.js"
+    },
+    "./progress": {
+      "types": "./dist/progress.d.ts",
+      "import": "./dist/progress.js"
+    },
+    "./prompt": {
+      "types": "./dist/prompt.d.ts",
+      "import": "./dist/prompt.js"
     }
   },
   "files": [
@@ -20,8 +72,11 @@
     "build": "tsc",
     "test": "bun test",
     "bench": "bun run bench/parse.bench.ts",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "prepublishOnly": "npm run build",
+    "check:readme": "python3 scripts/check-readme.py",
+    "check:package": "node scripts/check-package.mjs",
+    "ready": "bun run typecheck && bun test && bun run build && bun run check:readme && bun run check:package"
   },
   "keywords": [
     "cli",
@@ -33,6 +88,8 @@
     "subcommands",
     "arg-parser",
     "flag-parser",
+    "shell-completions",
+    "man-page",
     "bun",
     "node"
   ],
@@ -50,8 +107,8 @@
     "node": ">=20.0.0"
   },
   "devDependencies": {
-    "@types/bun": "latest",
+    "@types/bun": "^1.4.0",
     "mitata": "^1.0.34",
-    "typescript": "^6.0.2"
+    "typescript": "^7.0.2"
   }
 }