politty 0.8.0 → 0.9.0

package/dist/schema-extractor-BxSRwLrx.cjs

@@ -1,710 +0,0 @@
-let zod = require("zod");
-
-//#region src/core/arg-registry.ts
-/**
-* Custom registry for politty argument metadata
-* This avoids polluting Zod's GlobalMeta
-*/
-const argRegistry = zod.z.registry();
-function arg(schema, meta) {
-	if (meta) argRegistry.add(schema, meta);
-	return schema;
-}
-/**
-* Get metadata for a schema from the registry
-*
-* @param schema - The Zod schema
-* @returns The metadata if registered, undefined otherwise
-*/
-function getArgMeta$1(schema) {
-	return argRegistry.get(schema);
-}
-
-//#endregion
-//#region src/lazy.ts
-/**
-* Marker property for LazyCommand identification
-*/
-const LAZY_BRAND = "__politty_lazy__";
-/**
-* Type guard: check if a value is a LazyCommand
-*/
-function isLazyCommand(value) {
-	return typeof value === "object" && value !== null && LAZY_BRAND in value && value[LAZY_BRAND] === true;
-}
-/**
-* Create a lazily-loaded subcommand with synchronous metadata.
-*
-* The `meta` command provides names, descriptions, and args schema
-* for static analysis (completion scripts, help text) without loading
-* the full command module.
-*
-* The `load` function is called only at execution time.
-*
-* @example
-* ```ts
-* import { lazy, defineCommand } from "politty";
-*
-* const cli = defineCommand({
-*   name: "mycli",
-*   subCommands: {
-*     deploy: lazy(
-*       defineCommand({
-*         name: "deploy",
-*         description: "Deploy the application",
-*         args: z.object({ env: arg(z.string()) }),
-*       }),
-*       () => import("./deploy.js").then((m) => m.deployCommand),
-*     ),
-*   },
-* });
-* ```
-*/
-function lazy(meta, load) {
-	return {
-		[LAZY_BRAND]: true,
-		meta,
-		load
-	};
-}
-/**
-* Resolve synchronous metadata from a SubCommandValue.
-* Returns null for legacy async subcommands whose metadata is unavailable.
-*/
-function resolveSubCommandMeta(subCmd) {
-	if (isLazyCommand(subCmd)) return subCmd.meta;
-	if (typeof subCmd === "function") return null;
-	return subCmd;
-}
-
-//#endregion
-//#region src/executor/subcommand-router.ts
-/**
-* Resolve a lazy-loaded command (sync or async)
-*
-* @param cmd - The command or lazy loader function
-* @returns The resolved command
-*/
-async function resolveLazyCommand(cmd) {
-	if (isLazyCommand(cmd)) return await cmd.load();
-	if (typeof cmd === "function") return await cmd();
-	return cmd;
-}
-/**
-* Resolve a subcommand by name (including alias lookup) and return both the
-* resolved command and the canonical name if accessed via alias.
-*
-* This avoids a redundant alias scan when the caller needs both pieces of info.
-*/
-async function resolveSubcommandWithAlias(command, name) {
-	if (!command.subCommands) return;
-	const subCmd = command.subCommands[name];
-	if (subCmd) return {
-		command: await resolveLazyCommand(subCmd),
-		aliasFor: void 0
-	};
-	const canonicalName = resolveSubCommandAlias(command, name);
-	if (canonicalName) return {
-		command: await resolveLazyCommand(command.subCommands[canonicalName]),
-		aliasFor: canonicalName
-	};
-}
-/**
-* Resolve an alias to the canonical subcommand name.
-* Returns the canonical name if the given name is an alias, or undefined.
-*
-* Note: Aliases are only recognized for eagerly-defined commands and
-* `lazy()` commands (which carry synchronous metadata). Pure async
-* subcommand functions do not expose metadata synchronously, so their
-* aliases cannot be resolved without loading the module.
-*
-* @param command - The parent command
-* @param alias - The alias to look up
-* @returns The canonical subcommand name, or undefined
-*/
-function resolveSubCommandAlias(command, alias) {
-	if (!command.subCommands) return void 0;
-	for (const [name, subCmd] of Object.entries(command.subCommands)) if (resolveSubCommandMeta(subCmd)?.aliases?.includes(alias)) return name;
-}
-/**
-* Build a set of all recognized subcommand names including aliases.
-*
-* @param command - The parent command
-* @returns Set of all names (canonical + aliases)
-*/
-function listSubCommandNamesWithAliases(command) {
-	const names = /* @__PURE__ */ new Set();
-	if (!command.subCommands) return names;
-	for (const [name, subCmd] of Object.entries(command.subCommands)) {
-		names.add(name);
-		const meta = resolveSubCommandMeta(subCmd);
-		if (meta?.aliases) for (const alias of meta.aliases) names.add(alias);
-	}
-	return names;
-}
-/**
-* List all subcommand names for a command
-*
-* @param command - The parent command
-* @returns Array of subcommand names
-*/
-function listSubCommands(command) {
-	if (!command.subCommands) return [];
-	return Object.keys(command.subCommands);
-}
-
-//#endregion
-//#region src/core/schema-extractor.ts
-/**
-* Get ArgMeta from both the custom registry and Zod's _def
-* Priority: custom registry > _def.argMeta
-*/
-function getArgMeta(schema) {
-	const fromRegistry = getArgMeta$1(schema);
-	if (fromRegistry) return fromRegistry;
-	if (typeof schema.meta === "function") {
-		const meta = schema.meta();
-		if (meta && typeof meta === "object") return meta;
-	}
-	const def = schema._def;
-	if (def?.argMeta) return def.argMeta;
-	if (def?.meta) return def.meta;
-}
-/**
-* Long flag names reserved for built-in handling (parseArgs / scanForSubcommand
-* intercept these before option parsing), so custom negation names must avoid them.
-*/
-const RESERVED_NEGATION_NAMES = new Set([
-	"help",
-	"help-all",
-	"version"
-]);
-/**
-* Get the type name from a zod schema (v4 compatible)
-*/
-function getTypeName(schema) {
-	const s = schema;
-	return s.def?.type ?? s._def?.type ?? s.type;
-}
-/**
-* Detect unknown keys handling mode from a Zod object schema
-*
-* In Zod v4:
-* - Default (strip): _def.catchall is undefined
-* - strict: _def.catchall is ZodNever (type = "never")
-* - passthrough: _def.catchall is ZodUnknown (type = "unknown")
-*/
-function getUnknownKeysMode(schema) {
-	const s = schema;
-	const catchall = (s.def ?? s._def)?.catchall;
-	if (!catchall) return "strip";
-	const catchallType = getTypeName(catchall);
-	if (catchallType === "never") return "strict";
-	if (catchallType === "unknown" || catchallType === "any") return "passthrough";
-	return "strip";
-}
-/**
-* Get the inner schema, unwrapping optional, nullable, default, etc.
-*/
-function unwrapSchema(schema) {
-	const typeName = getTypeName(schema);
-	const s = schema;
-	const def = s.def ?? s._def;
-	if (typeName === "optional" || typeName === "nullable" || typeName === "default") {
-		const innerSchema = def?.innerType;
-		if (innerSchema) return unwrapSchema(innerSchema);
-	}
-	if (typeName === "pipe") {
-		const innerSchema = def?.in ?? def?.schema;
-		if (innerSchema) return unwrapSchema(innerSchema);
-	}
-	return schema;
-}
-/**
-* Detect the base type of a schema
-*/
-function detectType(schema) {
-	switch (getTypeName(unwrapSchema(schema))) {
-		case "string":
-		case "enum": return "string";
-		case "number":
-		case "int": return "number";
-		case "boolean": return "boolean";
-		case "array": return "array";
-		default: return "unknown";
-	}
-}
-/**
-* Extract enum values from a schema if it's an enum type
-*
-* @param schema - The Zod schema to extract enum values from
-* @returns Array of enum values if schema is an enum, undefined otherwise
-*/
-function extractEnumValues(schema) {
-	const innerSchema = unwrapSchema(schema);
-	const typeName = getTypeName(innerSchema);
-	const s = innerSchema;
-	const def = s.def ?? s._def;
-	if (typeName === "enum") {
-		const entries = def?.entries;
-		if (entries && typeof entries === "object") return Object.values(entries);
-		const values = def?.values;
-		if (Array.isArray(values)) return values;
-		const options = s.options;
-		if (Array.isArray(options)) return options;
-	}
-	if (typeName === "array") {
-		const element = def?.element;
-		if (element) return extractEnumValues(element);
-	}
-	if (typeName === "union") {
-		const options = def?.options;
-		if (Array.isArray(options)) {
-			const literalValues = [];
-			for (const option of options) if (getTypeName(option) === "literal") {
-				const optionDef = option.def ?? option._def;
-				const value = optionDef?.value;
-				const values = optionDef?.values;
-				const literalValue = value ?? values?.[0];
-				if (typeof literalValue === "string") literalValues.push(literalValue);
-			}
-			if (literalValues.length === options.length && literalValues.length > 0) return literalValues;
-		}
-	}
-}
-/**
-* Convert camelCase to kebab-case
-* @example toKebabCase("dryRun") => "dry-run"
-* @example toKebabCase("outputDir") => "output-dir"
-* @example toKebabCase("XMLParser") => "xml-parser"
-*/
-function toKebabCase(str) {
-	return str.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2").toLowerCase();
-}
-/**
-* Convert hyphen-separated sequences to camelCase.
-*
-* Replaces `-x` (hyphen followed by a lowercase letter) with the uppercase
-* variant. Non-hyphenated input (e.g., already camelCase) is returned as-is.
-*
-* @param str - A string that may contain hyphens
-* @example toCamelCase("dry-run") => "dryRun"
-* @example toCamelCase("output-dir") => "outputDir"
-* @example toCamelCase("dryRun") => "dryRun"
-*/
-function toCamelCase(str) {
-	return str.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
-}
-/**
-* Check if a schema is required (not optional or has default)
-*
-* Note: We only check isOptional(), not isNullable(), because CLI arguments
-* are either present (string value) or absent (undefined), never null.
-* Also, some coerce types incorrectly report isNullable()=true.
-*/
-function isRequired(schema) {
-	return !schema.isOptional();
-}
-/**
-* Extract default value from schema if present
-*/
-function extractDefaultValue(schema) {
-	const typeName = getTypeName(schema);
-	const s = schema;
-	const def = s.def ?? s._def;
-	if (typeName === "default") {
-		const defaultValue = def?.defaultValue;
-		if (typeof defaultValue === "function") return defaultValue();
-		return defaultValue;
-	}
-	if (typeName === "optional" || typeName === "nullable") {
-		const innerSchema = def?.innerType;
-		if (innerSchema) return extractDefaultValue(innerSchema);
-	}
-}
-/**
-* Extract description from schema
-*/
-function extractDescription(schema) {
-	if (schema.description) return schema.description;
-	const typeName = getTypeName(schema);
-	const s = schema;
-	const def = s.def ?? s._def;
-	if (typeName === "optional" || typeName === "nullable" || typeName === "default") {
-		const innerSchema = def?.innerType;
-		if (innerSchema) return extractDescription(innerSchema);
-	}
-}
-/**
-* Resolve field metadata from schema and argRegistry
-*/
-function resolveFieldMeta(name, schema) {
-	const argMeta = getArgMeta(schema) ?? getArgMeta(unwrapSchema(schema));
-	const description = argMeta?.description ?? extractDescription(schema);
-	const cliName = toKebabCase(name);
-	const enumValues = extractEnumValues(schema);
-	const aliasPattern = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
-	const normalizeAliasList = (input, metaKey) => {
-		if (input == null) return void 0;
-		const normalized = (Array.isArray(input) ? input : [input]).map((a) => {
-			if (typeof a !== "string") throw new Error(`Invalid ${metaKey} for field "${name}": expected string or string[], received ${typeof a}.`);
-			const candidate = a.trim().replace(/^-+/, "");
-			if (candidate.length === 0 || !aliasPattern.test(candidate)) throw new Error(`Invalid ${metaKey} "${a}" for field "${name}": aliases must match ${aliasPattern}.`);
-			return candidate;
-		});
-		const result = Array.from(new Set(normalized));
-		return result.length > 0 ? result : void 0;
-	};
-	const alias = normalizeAliasList(argMeta?.alias, "alias");
-	const visibleSet = new Set(alias ?? []);
-	const hiddenAlias = normalizeAliasList(argMeta?.hiddenAlias, "hiddenAlias")?.filter((a) => !visibleSet.has(a));
-	const hiddenAliasFinal = hiddenAlias && hiddenAlias.length > 0 ? hiddenAlias : void 0;
-	const fieldType = detectType(schema);
-	const rawNegation = argMeta?.negation;
-	let negation;
-	if (rawNegation !== void 0 && rawNegation !== null) if (typeof rawNegation === "boolean") {
-		if (fieldType !== "boolean") throw new Error(`Invalid negation for field "${name}": negation can only be used on boolean fields.`);
-		negation = rawNegation;
-	} else {
-		if (typeof rawNegation !== "string") throw new Error(`Invalid negation for field "${name}": expected string or boolean, received ${typeof rawNegation}.`);
-		const candidate = rawNegation.trim().replace(/^-+/, "");
-		if (candidate.length === 0 || !aliasPattern.test(candidate)) throw new Error(`Invalid negation "${rawNegation}" for field "${name}": negation names must match ${aliasPattern}.`);
-		if (RESERVED_NEGATION_NAMES.has(candidate)) throw new Error(`Invalid negation "${rawNegation}" for field "${name}": negation cannot use reserved built-in flag names (${[...RESERVED_NEGATION_NAMES].map((n) => `--${n}`).join(", ")}).`);
-		if (fieldType !== "boolean") throw new Error(`Invalid negation for field "${name}": negation can only be used on boolean fields.`);
-		negation = candidate;
-	}
-	const rawNegationDescription = argMeta?.negationDescription;
-	let negationDescription;
-	if (rawNegationDescription !== void 0 && rawNegationDescription !== null) {
-		if (typeof rawNegationDescription !== "string") throw new Error(`Invalid negationDescription for field "${name}": expected string, received ${typeof rawNegationDescription}.`);
-		if (negation === false) throw new Error(`Invalid negationDescription for field "${name}": negationDescription cannot be used when negation is false.`);
-		if (negation === void 0) throw new Error(`Invalid negationDescription for field "${name}": negationDescription requires \`negation\` to be set (string or true).`);
-		const trimmed = rawNegationDescription.trim();
-		if (trimmed.length === 0) throw new Error(`Invalid negationDescription for field "${name}": negationDescription must be a non-empty string.`);
-		negationDescription = trimmed;
-	}
-	const negationDisplay = typeof negation === "string" ? negation : negation === true ? `no-${cliName}` : void 0;
-	const meta = {
-		name,
-		cliName,
-		alias,
-		hiddenAlias: hiddenAliasFinal,
-		description,
-		positional: argMeta?.positional ?? false,
-		placeholder: argMeta?.placeholder,
-		env: argMeta?.env,
-		required: isRequired(schema),
-		defaultValue: extractDefaultValue(schema),
-		type: fieldType,
-		schema,
-		enumValues,
-		completion: argMeta?.completion,
-		prompt: argMeta?.prompt,
-		negation,
-		negationDisplay,
-		negationDescription,
-		effect: argMeta?.effect
-	};
-	if (argMeta && "overrideBuiltinAlias" in argMeta && argMeta.overrideBuiltinAlias === true) meta.overrideBuiltinAlias = true;
-	return meta;
-}
-/**
-* Get the combined list of visible + hidden aliases for a field.
-* Used by the parser and validators which treat both equally,
-* while help/docs/completion rely on `field.alias` only.
-*/
-function getAllAliases(field) {
-	if (!field.alias && !field.hiddenAlias) return [];
-	return [...field.alias ?? [], ...field.hiddenAlias ?? []];
-}
-/**
-* Get shape from a ZodObject
-*/
-function getObjectShape(schema) {
-	const s = schema;
-	return (s.def ?? s._def)?.shape ?? s.shape ?? {};
-}
-/**
-* Extract fields from a ZodObject
-*/
-function extractFromObject(schema) {
-	const shape = getObjectShape(schema);
-	return Object.entries(shape).map(([name, fieldSchema]) => resolveFieldMeta(name, fieldSchema));
-}
-/**
-* Extract fields from a discriminated union
-*/
-function extractFromDiscriminatedUnion(schema) {
-	const s = schema;
-	const def = s.def ?? s._def;
-	const discriminator = def?.discriminator ?? "";
-	const options = def?.options ?? [];
-	const allFieldsMap = /* @__PURE__ */ new Map();
-	const variants = [];
-	for (const option of options) {
-		const shape = getObjectShape(option);
-		const variantFields = [];
-		let discriminatorValue = "";
-		const discriminatorSchema = shape[discriminator];
-		if (discriminatorSchema) {
-			const typeName = getTypeName(discriminatorSchema);
-			if (typeName === "literal") {
-				const litDef = discriminatorSchema.def ?? discriminatorSchema._def;
-				const value = litDef?.value;
-				const values = litDef?.values;
-				discriminatorValue = String(value ?? values?.[0] ?? "");
-			} else if (typeName === "enum") {
-				const enumValues = extractEnumValues(discriminatorSchema);
-				if (enumValues && enumValues.length === 1) discriminatorValue = enumValues[0];
-			}
-		}
-		for (const [name, fieldSchema] of Object.entries(shape)) {
-			const fieldMeta = resolveFieldMeta(name, fieldSchema);
-			variantFields.push(fieldMeta);
-			if (!allFieldsMap.has(name)) allFieldsMap.set(name, fieldMeta);
-		}
-		const variantDescription = extractDescription(option);
-		variants.push({
-			discriminatorValue,
-			fields: variantFields,
-			...variantDescription ? { description: variantDescription } : {}
-		});
-	}
-	const description = extractDescription(schema);
-	return {
-		fields: Array.from(allFieldsMap.values()),
-		schema,
-		schemaType: "discriminatedUnion",
-		unknownKeysMode: getUnknownKeysMode(schema),
-		discriminator,
-		variants,
-		...description ? { description } : {}
-	};
-}
-/**
-* Extract fields from a union-like schema (union or xor)
-*/
-function extractFromUnionLike(schema, schemaType) {
-	const s = schema;
-	const options = (s.def ?? s._def)?.options ?? [];
-	const allFieldsMap = /* @__PURE__ */ new Map();
-	const unionOptions = [];
-	for (const option of options) {
-		const extracted = extractFields(option);
-		unionOptions.push(extracted);
-		for (const field of extracted.fields) if (!allFieldsMap.has(field.name)) allFieldsMap.set(field.name, field);
-	}
-	const description = extractDescription(schema);
-	return {
-		fields: Array.from(allFieldsMap.values()),
-		schema,
-		schemaType,
-		unknownKeysMode: getUnknownKeysMode(schema),
-		unionOptions,
-		...description ? { description } : {}
-	};
-}
-/**
-* Extract fields from an intersection
-*/
-function extractFromIntersection(schema) {
-	const s = schema;
-	const def = s.def ?? s._def;
-	const left = def?.left;
-	const right = def?.right;
-	const allFieldsMap = /* @__PURE__ */ new Map();
-	const extractSubFields = (subSchema) => {
-		if (!subSchema) return;
-		const extracted = extractFields(subSchema);
-		for (const field of extracted.fields) if (!allFieldsMap.has(field.name)) allFieldsMap.set(field.name, field);
-	};
-	extractSubFields(left);
-	extractSubFields(right);
-	const description = extractDescription(schema);
-	return {
-		fields: Array.from(allFieldsMap.values()),
-		schema,
-		schemaType: "intersection",
-		unknownKeysMode: getUnknownKeysMode(schema),
-		...description ? { description } : {}
-	};
-}
-/**
-* Cache for extractFields results to avoid redundant schema extraction
-*/
-const extractFieldsCache = /* @__PURE__ */ new WeakMap();
-/**
-* Extract all fields from a schema
-*
-* @param schema - The args schema (ZodObject, ZodDiscriminatedUnion, etc.)
-* @returns Extracted field information
-*/
-function extractFields(schema) {
-	const cached = extractFieldsCache.get(schema);
-	if (cached) return cached;
-	let result;
-	const typeName = getTypeName(schema);
-	const s = schema;
-	const def = s.def ?? s._def;
-	switch (typeName) {
-		case "object": {
-			const description = extractDescription(schema);
-			result = {
-				fields: extractFromObject(schema),
-				schema,
-				schemaType: "object",
-				unknownKeysMode: getUnknownKeysMode(schema),
-				...description ? { description } : {}
-			};
-			break;
-		}
-		case "union":
-			if (def?.discriminator) result = extractFromDiscriminatedUnion(schema);
-			else result = extractFromUnionLike(schema, "union");
-			break;
-		case "xor":
-			result = extractFromUnionLike(schema, "xor");
-			break;
-		case "intersection":
-			result = extractFromIntersection(schema);
-			break;
-		case "pipe": {
-			const pipeInner = def?.in ?? def?.schema;
-			if (pipeInner) {
-				const innerResult = extractFields(pipeInner);
-				const pipeDescription = extractDescription(schema);
-				result = {
-					...innerResult,
-					schema,
-					...pipeDescription ? { description: pipeDescription } : {}
-				};
-				break;
-			}
-			const pipeDescription = extractDescription(schema);
-			result = {
-				fields: [],
-				schema,
-				schemaType: "object",
-				unknownKeysMode: getUnknownKeysMode(schema),
-				...pipeDescription ? { description: pipeDescription } : {}
-			};
-			break;
-		}
-		default: {
-			const description = extractDescription(schema);
-			result = {
-				fields: [],
-				schema,
-				schemaType: "object",
-				unknownKeysMode: getUnknownKeysMode(schema),
-				...description ? { description } : {}
-			};
-			break;
-		}
-	}
-	extractFieldsCache.set(schema, result);
-	return result;
-}
-/**
-* Get extracted fields from a command
-*
-* @param command - The command to extract fields from
-* @returns Extracted field information, or null if command has no args schema
-*/
-function getExtractedFields(command) {
-	if (!command.args) return null;
-	return extractFields(command.args);
-}
-
-//#endregion
-Object.defineProperty(exports, 'arg', {
-  enumerable: true,
-  get: function () {
-    return arg;
-  }
-});
-Object.defineProperty(exports, 'extractFields', {
-  enumerable: true,
-  get: function () {
-    return extractFields;
-  }
-});
-Object.defineProperty(exports, 'getAllAliases', {
-  enumerable: true,
-  get: function () {
-    return getAllAliases;
-  }
-});
-Object.defineProperty(exports, 'getExtractedFields', {
-  enumerable: true,
-  get: function () {
-    return getExtractedFields;
-  }
-});
-Object.defineProperty(exports, 'getUnknownKeysMode', {
-  enumerable: true,
-  get: function () {
-    return getUnknownKeysMode;
-  }
-});
-Object.defineProperty(exports, 'isLazyCommand', {
-  enumerable: true,
-  get: function () {
-    return isLazyCommand;
-  }
-});
-Object.defineProperty(exports, 'lazy', {
-  enumerable: true,
-  get: function () {
-    return lazy;
-  }
-});
-Object.defineProperty(exports, 'listSubCommandNamesWithAliases', {
-  enumerable: true,
-  get: function () {
-    return listSubCommandNamesWithAliases;
-  }
-});
-Object.defineProperty(exports, 'listSubCommands', {
-  enumerable: true,
-  get: function () {
-    return listSubCommands;
-  }
-});
-Object.defineProperty(exports, 'resolveLazyCommand', {
-  enumerable: true,
-  get: function () {
-    return resolveLazyCommand;
-  }
-});
-Object.defineProperty(exports, 'resolveSubCommandAlias', {
-  enumerable: true,
-  get: function () {
-    return resolveSubCommandAlias;
-  }
-});
-Object.defineProperty(exports, 'resolveSubCommandMeta', {
-  enumerable: true,
-  get: function () {
-    return resolveSubCommandMeta;
-  }
-});
-Object.defineProperty(exports, 'resolveSubcommandWithAlias', {
-  enumerable: true,
-  get: function () {
-    return resolveSubcommandWithAlias;
-  }
-});
-Object.defineProperty(exports, 'toCamelCase', {
-  enumerable: true,
-  get: function () {
-    return toCamelCase;
-  }
-});
-Object.defineProperty(exports, 'toKebabCase', {
-  enumerable: true,
-  get: function () {
-    return toKebabCase;
-  }
-});
-//# sourceMappingURL=schema-extractor-BxSRwLrx.cjs.map