@shell-shock/core 0.17.21 → 0.17.23

package/dist/plugin-utils/index.mjs

@@ -1,10 +1,346 @@
-import { getAppBin, getAppDescription, getAppName, getAppTitle, getDynamicPathSegmentName, getPathSegmentGroupName, getPathSegmentName, isDynamicPathSegment, isPathSegmentGroup, sortArgAliases } from "./context-helpers.mjs";
-import { sortOptions } from "./reflect.mjs";
-import { computeBin } from "./compute-bin.mjs";
-import { isCommandArgument, isCommandOption, isCommandParameter, isCommandParameterConfig, isCommandParameterType } from "./type-checks.mjs";
-import { extractReflectionKind, extractType } from "./deepkit.mjs";
-import { __ΩFormatDescriptionOptions, __ΩFormatShortDescriptionOptions, formatDescription, formatShortDescription } from "./description-helpers.mjs";
-import { traverseCommandTree, traverseCommands } from "./traverse-command-tree.mjs";
-import { getCommandList, getCommandPaths, getCommandSegments, getCommandTree } from "./get-command-tree.mjs";
-
-export { __ΩFormatDescriptionOptions, __ΩFormatShortDescriptionOptions, computeBin, extractReflectionKind, extractType, formatDescription, formatShortDescription, getAppBin, getAppDescription, getAppName, getAppTitle, getCommandList, getCommandPaths, getCommandSegments, getCommandTree, getDynamicPathSegmentName, getPathSegmentGroupName, getPathSegmentName, isCommandArgument, isCommandOption, isCommandParameter, isCommandParameterConfig, isCommandParameterType, isDynamicPathSegment, isPathSegmentGroup, sortArgAliases, sortOptions, traverseCommandTree, traverseCommands };
+import { a as getDynamicPathSegmentName, c as isDynamicPathSegment, i as getAppTitle, l as isPathSegmentGroup, n as getAppDescription, o as getPathSegmentGroupName, r as getAppName, s as getPathSegmentName, t as getAppBin, u as sortArgAliases } from "../context-helpers-D3EJxwbq.mjs";
+import { t as sortOptions } from "../reflect-DXKSFgvS.mjs";
+import { joinPaths } from "@stryke/path/join-paths";
+import { isSetObject } from "@stryke/type-checks/is-set-object";
+import { isSetString } from "@stryke/type-checks/is-set-string";
+import { ReflectionKind } from "@deepkit/type";
+import { isBoolean } from "@stryke/type-checks/is-boolean";
+
+//#region src/plugin-utils/compute-bin.ts
+/**
+* Computes the command tree for the root binary command based on the provided context.
+*
+* @param context - The plugin context containing the necessary information to compute the command tree.
+* @returns The computed command tree for the root binary command.
+*/
+function computeBin(context) {
+	return {
+		id: "",
+		name: getAppName(context),
+		title: getAppTitle(context),
+		description: getAppDescription(context),
+		virtual: true,
+		path: null,
+		segments: [],
+		alias: [],
+		tags: [],
+		options: Object.fromEntries(context.globalOptions.map((option) => [option.name, option])),
+		args: [],
+		entry: { file: joinPaths(context.entryPath, "bin.ts") },
+		parent: null,
+		children: context.commands,
+		docs: context.config.docs?.app
+	};
+}
+
+//#endregion
+//#region src/plugin-utils/type-checks.ts
+function isStringArray(value) {
+	return Array.isArray(value) && value.every((item) => isSetString(item));
+}
+function isNumberArray(value) {
+	return Array.isArray(value) && value.every((item) => typeof item === "number" && Number.isFinite(item));
+}
+function isBooleanArray(value) {
+	return Array.isArray(value) && value.every((item) => isBoolean(item));
+}
+function isAliasConfig(value) {
+	return isSetString(value) || isStringArray(value);
+}
+function isTypedDefaultValue(type, value, variadic) {
+	if (type === "string") {
+		if (variadic === true) return isStringArray(value);
+		if (variadic === false) return isSetString(value);
+		return isSetString(value) || isStringArray(value);
+	}
+	if (type === "number") {
+		if (variadic === true) return isNumberArray(value);
+		if (variadic === false) return typeof value === "number" && Number.isFinite(value);
+		return typeof value === "number" && Number.isFinite(value) || isNumberArray(value);
+	}
+	if (variadic === true) return isBooleanArray(value);
+	if (variadic === false) return isBoolean(value);
+	return isBoolean(value) || isBooleanArray(value);
+}
+function hasValidOptionalCommonFields(obj) {
+	if ("alias" in obj && obj.alias !== void 0 && !isAliasConfig(obj.alias)) return false;
+	if ("name" in obj && obj.name !== void 0 && !isSetString(obj.name)) return false;
+	if ("title" in obj && obj.title !== void 0 && !isSetString(obj.title)) return false;
+	if ("description" in obj && obj.description !== void 0 && !isSetString(obj.description)) return false;
+	if ("env" in obj && obj.env !== void 0 && !(isSetString(obj.env) || obj.env === false)) return false;
+	if ("required" in obj && obj.required !== void 0 && !isBoolean(obj.required)) return false;
+	if ("variadic" in obj && obj.variadic !== void 0 && !isBoolean(obj.variadic)) return false;
+	return true;
+}
+function hasValidTypeSpecificFields(obj, type) {
+	const variadic = isBoolean(obj.variadic) ? obj.variadic : void 0;
+	if ("default" in obj && obj.default !== void 0 && !isTypedDefaultValue(type, obj.default, variadic)) return false;
+	if (type === "string") {
+		if ("format" in obj && obj.format !== void 0 && !isSetString(obj.format)) return false;
+		if ("choices" in obj && obj.choices !== void 0 && !isStringArray(obj.choices)) return false;
+		return true;
+	}
+	if (type === "number") {
+		if ("choices" in obj && obj.choices !== void 0 && !isNumberArray(obj.choices)) return false;
+		return true;
+	}
+	if ("choices" in obj && obj.choices !== void 0) return false;
+	if ("format" in obj && obj.format !== void 0) return false;
+	return true;
+}
+/**
+* Type guard to check if a value is a valid {@link CommandParameterType} type.
+*
+* @param obj - The value to check.
+* @returns True if the value is a valid {@link CommandParameterType} type, false otherwise.
+*/
+function isCommandParameterType(obj) {
+	return isSetString(obj) && [
+		"string",
+		"number",
+		"boolean"
+	].includes(obj);
+}
+/**
+* Type guard to check if a value is a valid {@link CommandParameterConfig} type.
+*
+* @param obj - The value to check.
+* @returns True if the value is a valid {@link CommandParameterConfig} type, false otherwise.
+*/
+function isCommandParameterConfig(obj) {
+	if (!isSetObject(obj) || !("type" in obj) || !isCommandParameterType(obj.type)) return false;
+	return hasValidOptionalCommonFields(obj) && hasValidTypeSpecificFields(obj, obj.type);
+}
+/**
+* Type guard to check if a value is a valid {@link CommandParameter} type.
+*
+* @param obj - The value to check.
+* @returns True if the value is a valid {@link CommandParameter} type, false otherwise.
+*/
+function isCommandParameter(obj) {
+	if (!isCommandParameterConfig(obj)) return false;
+	if (!("name" in obj) || !isSetString(obj.name)) return false;
+	if (!("title" in obj) || !isSetString(obj.title)) return false;
+	if (!("description" in obj) || !isSetString(obj.description)) return false;
+	if (!("alias" in obj) || !isStringArray(obj.alias)) return false;
+	if (!("env" in obj) || !(isSetString(obj.env) || obj.env === false)) return false;
+	if (!("required" in obj) || !isBoolean(obj.required)) return false;
+	if (!("variadic" in obj) || !isBoolean(obj.variadic)) return false;
+	return hasValidTypeSpecificFields(obj, obj.type);
+}
+/**
+* Type guard to check if a value is a valid {@link CommandOption} type.
+*
+* @param obj - The value to check.
+* @returns True if the value is a valid {@link CommandOption} type, false otherwise.
+*/
+function isCommandOption(obj) {
+	if (!isCommandParameter(obj)) return false;
+	if (obj.type !== "boolean") return true;
+	if ("isNegativeOf" in obj && obj.isNegativeOf !== void 0 && !isSetString(obj.isNegativeOf)) return false;
+	if ("skipAddingNegative" in obj && obj.skipAddingNegative !== void 0 && !isBoolean(obj.skipAddingNegative)) return false;
+	return true;
+}
+/**
+* Type guard to check if a value is a valid {@link CommandArgument} type.
+*
+* @param obj - The value to check.
+* @returns True if the value is a valid {@link CommandArgument} type, false otherwise.
+*/
+function isCommandArgument(obj) {
+	return isCommandParameter(obj);
+}
+
+//#endregion
+//#region src/plugin-utils/deepkit.ts
+/**
+* Extracts a {@link ReflectionKind} from a {@link BaseCommandParameter} or {@link CommandParameterType}.
+*
+* @param command - The command parameter or kind to extract the reflection kind from.
+* @param checkVariadic - Whether to check for variadic parameters (arrays).
+* @returns The extracted {@link ReflectionKind}.
+*/
+function extractReflectionKind(command, checkVariadic = true) {
+	if (isCommandParameterType(command) && command === "string" || isSetObject(command) && command.type === "string") return checkVariadic && command.variadic ? ReflectionKind.array : ReflectionKind.string;
+	else if (isCommandParameterType(command) && command === "number" || isSetObject(command) && command.type === "number") return checkVariadic && command.variadic ? ReflectionKind.array : ReflectionKind.number;
+	else if (isCommandParameterType(command) && command === "boolean" || isSetObject(command) && command.type === "boolean") return ReflectionKind.boolean;
+	else return ReflectionKind.string;
+}
+/**
+* Extracts a {@link Type} from a {@link BaseCommandParameter} or {@link CommandParameterType}.
+*
+* @param command - The command parameter or kind to extract the type from.
+* @param checkVariadic - Whether to check for variadic parameters (arrays).
+* @returns The extracted {@link Type}.
+*/
+function extractType(command, checkVariadic = true) {
+	const reflectionKind = extractReflectionKind(command, checkVariadic);
+	if (reflectionKind === ReflectionKind.string) return { kind: ReflectionKind.string };
+	else if (reflectionKind === ReflectionKind.number) return { kind: ReflectionKind.number };
+	else if (reflectionKind === ReflectionKind.boolean) return { kind: ReflectionKind.boolean };
+	else if (reflectionKind === ReflectionKind.array) {
+		if (isCommandParameterType(command)) return {
+			kind: ReflectionKind.array,
+			type: extractType({ type: command }, false)
+		};
+		else if (isSetObject(command)) return {
+			kind: ReflectionKind.array,
+			type: extractType({
+				...command,
+				type: command.type
+			}, false)
+		};
+		else return {
+			kind: ReflectionKind.array,
+			type: { kind: ReflectionKind.string }
+		};
+	} else return { kind: ReflectionKind.string };
+}
+
+//#endregion
+//#region src/plugin-utils/description-helpers.ts
+/**
+* Formats a description string by trimming whitespace, replacing newlines with spaces (optionally), collapsing multiple spaces into a single space (optionally), and escaping special characters.
+*
+* @remarks
+* This is useful for ensuring that descriptions are concise and well-formatted when displayed in the CLI or documentation.
+*
+* @param description - The full description string.
+* @returns The formatted description string.
+*/
+function formatDescriptionWhitespace(description, options = {}) {
+	let formattedDescription = description.trim();
+	if (options.replaceNewlines) formattedDescription = formattedDescription.replace(/\s*\n\s*/g, " ");
+	if (options.collapseWhitespace) formattedDescription = formattedDescription.replace(/\s{2,}/g, " ");
+	return formattedDescription.trim();
+}
+/**
+* Formats a description string by trimming whitespace, replacing newlines with spaces (optionally), collapsing multiple spaces into a single space (optionally), and escaping special characters.
+*
+* @remarks
+* This is useful for ensuring that descriptions are concise and well-formatted when displayed in the CLI or documentation.
+*
+* @param description - The full description string.
+* @returns The formatted description string.
+*/
+function formatDescriptionEscapes(description) {
+	return description.replaceAll("'", "\\'").replaceAll("\"", "\\\"").replaceAll("`", "\\`").replace(/\$\{/g, "\\${");
+}
+/**
+* Formats a description string by trimming whitespace, replacing newlines with spaces (optionally), collapsing multiple spaces into a single space (optionally), and escaping special characters.
+*
+* @remarks
+* This is useful for ensuring that descriptions are concise and well-formatted when displayed in the CLI or documentation.
+*
+* @param description - The full description string.
+* @returns The formatted description string.
+*/
+function formatDescription(description, options = {}) {
+	return formatDescriptionEscapes(formatDescriptionWhitespace(description, options));
+}
+/**
+* Extracts the short description from a longer description string. The short description is typically the first sentence or the first line of the description.
+*
+* @param description - The full description string.
+* @param options - Options for formatting the short description, including the maximum length.
+* @returns The extracted short description.
+*/
+function formatShortDescription(description, options = {}) {
+	const length = options.length ?? 62;
+	const formattedDescription = formatDescriptionWhitespace(description, options);
+	let result = ((formattedDescription.indexOf("\n") < length - 3 || formattedDescription.search(/[.!?\n]\s*\S/) > length - 3 ? formattedDescription.match(/^.*[.!?\n]\s?\S/)?.[0]?.trim()?.slice(0, -1)?.trim() : void 0) || formattedDescription).trim();
+	if (result.trim().length > length) result = `${result.substring(0, Math.max(0, length - 3)).trim()}...`;
+	return formatDescriptionEscapes(result);
+}
+
+//#endregion
+//#region src/plugin-utils/traverse-command-tree.ts
+/**
+* Traverses a command tree and applies a visitor function to each node.
+*
+* @param commandTree - The command tree to traverse.
+* @param visitor - The visitor function to apply to each node.
+*/
+async function traverseCommandTree(commandTree, visitor) {
+	if (!commandTree.children) return;
+	await Promise.all(Object.values(commandTree.children).map(async (childTree) => {
+		await Promise.resolve(visitor(childTree));
+		await traverseCommandTree(childTree, visitor);
+	}));
+}
+/**
+* Traverses all commands in the context and applies a visitor function to each command tree.
+*
+* @param context - The build context containing the command definitions.
+* @param visitor - The visitor function to apply to each command tree.
+*/
+async function traverseCommands(context, visitor) {
+	if (!context.commands) return;
+	await Promise.all(Object.values(context.commands).map(async (childTree) => {
+		await Promise.resolve(visitor(childTree));
+		await traverseCommandTree(childTree, visitor);
+	}));
+}
+
+//#endregion
+//#region src/plugin-utils/get-command-tree.ts
+/**
+* Retrieves a specific command tree based on the provided path.
+*
+* @param context - The build context containing the command definitions.
+* @param path - An array of strings representing the command path.
+* @returns The command tree at the specified path, or null if not found.
+*/
+function getCommandTree(context, path = []) {
+	if (path.length === 0) return null;
+	let currentTree = context.commands[path[0]] ?? null;
+	if (path.length > 1) {
+		const segments = path.slice(1).filter((segment) => !isDynamicPathSegment(segment));
+		for (const segment of segments) if (currentTree?.children && Object.prototype.hasOwnProperty.call(currentTree.children, segment)) currentTree = currentTree.children[segment] ?? null;
+		else return null;
+	}
+	return currentTree;
+}
+/**
+* Retrieves a list of all command trees defined in the context.
+*
+* @param context - The build context containing the command definitions.
+* @returns A promise that resolves to an array of all command trees in the context.
+*/
+async function getCommandList(context) {
+	const commandList = [];
+	await traverseCommands(context, (commandTree) => {
+		commandList.push(commandTree);
+	});
+	return commandList;
+}
+/**
+* Retrieves a list of all command paths defined in the context.
+*
+* @param context - The build context containing the command definitions.
+* @returns A promise that resolves to an array of all command paths in the context.
+*/
+async function getCommandPaths(context) {
+	const commandPaths = [];
+	await traverseCommands(context, (commandTree) => {
+		if (commandTree.path) commandPaths.push(commandTree.path);
+	});
+	return commandPaths;
+}
+/**
+* Retrieves a list of all command segments defined in the context.
+*
+* @param context - The build context containing the command definitions.
+* @returns A promise that resolves to an array of all command segments in the context.
+*/
+async function getCommandSegments(context) {
+	const commandSegments = [];
+	await traverseCommands(context, (commandTree) => {
+		if (commandTree.path) commandSegments.push(commandTree.segments);
+	});
+	return commandSegments;
+}
+
+//#endregion
+export { computeBin, extractReflectionKind, extractType, formatDescription, formatShortDescription, getAppBin, getAppDescription, getAppName, getAppTitle, getCommandList, getCommandPaths, getCommandSegments, getCommandTree, getDynamicPathSegmentName, getPathSegmentGroupName, getPathSegmentName, isCommandArgument, isCommandOption, isCommandParameter, isCommandParameterConfig, isCommandParameterType, isDynamicPathSegment, isPathSegmentGroup, sortArgAliases, sortOptions, traverseCommandTree, traverseCommands };
+//# sourceMappingURL=index.mjs.map

package/dist/plugin-utils/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":[],"mappings":""}