@crustjs/core 0.0.19 → 0.2.0

package/dist/tooling.d.ts

@@ -0,0 +1,160 @@
+import { D as CommandSnapshot, O as FlagSnapshot, V as ExtensionId, i as CommandSection, o as DeclaredDefault } from "./types-DjMHz7M6.js";
+//#region src/command/invocation.d.ts
+/**
+ * Snapshot subprocess protocol used by first-party build tooling.
+ *
+ * When set to a non-empty file path, `.execute()` prepares the command tree,
+ * validates its documentation sections, optionally runs Extension build hooks when the
+ * build output directory is set, writes its final JSON snapshot and Build Report, and exits
+ * without dispatching a Command Action. In-process callers use `Crust.snapshot()`.
+ */
+export declare const SNAPSHOT_PATH_ENV = "CRUST_INTERNAL_SNAPSHOT_PATH";
+export declare const BUILD_OUT_DIR_ENV = "CRUST_INTERNAL_BUILD_OUT_DIR";
+//#endregion
+//#region src/command/documentation.d.ts
+/** Format a declared default value for command documentation. */
+export declare function formatDefault(value: DeclaredDefault): string;
+/** Format a definition's description and optional default/choice annotations. */
+export declare function formatDescription(description: string | undefined, defaultValue: DeclaredDefault, choices: readonly string[] | undefined, formatAnnotation?: (annotation: string) => string): string;
+/**
+ * Presentation-ready view of one positional argument.
+ *
+ * Same data as {@link ArgSnapshot} but normalized for renderers: booleans are
+ * always present (never `undefined`) and the display token is pre-formatted.
+ */
+interface DocumentationArg {
+  /** Argument name as defined, e.g. `"file"`. */
+  readonly name: string;
+  /**
+   * Pre-formatted usage token: `<name>` if required, `[name]` if optional,
+   * with `...` appended when variadic — e.g. `"<file>"`, `"[files...]"`.
+   */
+  readonly token: string;
+  /** Value type (`"string"`, `"number"`, …); `undefined` for schema-backed args. */
+  readonly type?: CommandSnapshot["args"][number]["type"];
+  /** Human-readable description from the arg definition. */
+  readonly description?: string;
+  /** `true` when parsing fails if the argument is missing. */
+  readonly required: boolean;
+  /** `true` when the argument collects all remaining positionals into an array. */
+  readonly variadic: boolean;
+  /** Static enum of accepted values, e.g. `["json", "text"]`, if declared. */
+  readonly choices?: readonly string[];
+  /** Default value used when the argument is omitted, e.g. `3000`. */
+  readonly default?: unknown;
+}
+/**
+ * Presentation-ready view of one flag.
+ *
+ * @example
+ * For `{ output: { type: "string", short: "o", aliases: ["out"] } }`:
+ * ```ts
+ * {
+ *   name: "output",
+ *   spellings: ["-o", "--output", "--out"],
+ *   short: "o",
+ *   aliases: ["out"],
+ *   negatable: false,
+ *   type: "string",
+ *   required: false,
+ *   multiple: false,
+ * }
+ * ```
+ */
+interface DocumentationFlag {
+  /** Canonical flag name (the key in the flags definition), e.g. `"output"`. */
+  readonly name: string;
+  /**
+   * All accepted CLI spellings with dashes, ordered short, canonical, aliases,
+   * then negations — e.g. `["-v", "--verbose", "--no-verbose"]`.
+   */
+  readonly spellings: readonly string[];
+  /** Single-character short alias without the dash, e.g. `"v"` for `-v`. */
+  readonly short?: string;
+  /** Additional long aliases without dashes, e.g. `["out"]` for `--out`. */
+  readonly aliases: readonly string[];
+  /** `true` for boolean flags that also accept `--no-<name>` (i.e. `noNegate` unset). */
+  readonly negatable: boolean;
+  /** Value type, e.g. `"boolean"`, `"string"`, `"number"`. */
+  readonly type: FlagSnapshot["type"];
+  /** Human-readable description from the flag definition. */
+  readonly description?: string;
+  /** `true` when parsing fails if the flag is not provided. */
+  readonly required: boolean;
+  /** `true` when the flag can repeat and collects values into an array. */
+  readonly multiple: boolean;
+  /** Static enum of accepted values, e.g. `["debug", "info", "error"]`, if declared. */
+  readonly choices?: readonly string[];
+  /** Default value used when the flag is omitted, e.g. `false`. */
+  readonly default?: unknown;
+}
+/**
+ * One renderer-colorable piece of a usage line. `custom` is the sole segment
+ * when the author supplied `meta.usage`; generated usage lines are composed
+ * of the other kinds so renderers can style parts without re-deriving the
+ * assembly policy (when `<command>`/`[options]` appear, argument ordering).
+ */
+type UsageSegment = {
+  readonly kind: "path";
+  readonly text: string;
+} | {
+  readonly kind: "command";
+  readonly text: "<command>";
+} | {
+  readonly kind: "arg";
+  readonly text: string;
+  readonly required: boolean;
+} | {
+  readonly kind: "options";
+  readonly text: "[options]";
+} | {
+  readonly kind: "custom";
+  readonly text: string;
+};
+/**
+ * Presentation-neutral documentation model for one command (and, via
+ * `children`, its visible subtree). Renderers (help, man pages, …) consume
+ * this instead of re-deriving usage/spelling policy from raw definitions.
+ */
+interface CommandDocumentation {
+  /** Canonical command name, e.g. `"add"`. */
+  readonly name: string;
+  /** Full invocation path from the root CLI, e.g. `["mycli", "remote", "add"]`. */
+  readonly path: readonly string[];
+  /** Human-readable description from `meta.description`. */
+  readonly description?: string;
+  /** Alternative names that route to this command, e.g. `["i"]` for `install`. */
+  readonly aliases: readonly string[];
+  /**
+   * Plain usage line: `usageSegments` texts joined with spaces —
+   * e.g. `"mycli remote add <name> [url] [options]"`.
+   */
+  readonly usage: string;
+  /** Structured pieces of `usage` so renderers can color parts individually. */
+  readonly usageSegments: readonly UsageSegment[];
+  /** `true` when the command has its own action (not just a subcommand container). */
+  readonly hasAction: boolean;
+  /** Positional arguments in declaration order. */
+  readonly args: readonly DocumentationArg[];
+  /** Effective flags (Context-owned + local), in definition order. */
+  readonly flags: readonly DocumentationFlag[];
+  /** Unfiltered command-authored and Extension-contributed documentation sections. */
+  readonly sections: readonly CommandSection[];
+  /** Visible children only; hidden commands remain invocable but are not documentation. */
+  readonly children: readonly CommandDocumentation[];
+}
+/** Build the presentation-neutral documentation model for a full command tree. */
+export declare function buildCommandDocumentation(command: CommandSnapshot, path?: readonly string[]): CommandDocumentation;
+//#endregion
+//#region src/sections.d.ts
+/** Whether a command belongs in user-facing listings. */
+export declare function isListed(command: CommandSnapshot): boolean;
+/** Select and merge sections visible to the given consumer. */
+export declare function sectionsFor(sections: readonly CommandSection[] | undefined, consumer: ExtensionId): readonly CommandSection[];
+/** Collect section-bearing visible commands in canonical path order. The root path is `[]`. */
+export declare function visibleSectionsFor(snapshot: CommandSnapshot, consumer: ExtensionId): readonly {
+  readonly path: readonly string[];
+  readonly sections: readonly CommandSection[];
+}[];
+//#endregion
+export type { CommandDocumentation, CommandSnapshot, DocumentationArg, DocumentationFlag, UsageSegment };

package/dist/tooling.js

@@ -0,0 +1,96 @@
+import { c as sectionsFor, l as visibleSectionsFor, n as SNAPSHOT_PATH_ENV, s as isListed, t as BUILD_OUT_DIR_ENV } from "./invocation-DcA5FqF7.js";
+//#region src/command/documentation.ts
+function isNonFiniteNumber(value) {
+	return typeof value === "number" && !Number.isFinite(value);
+}
+/** Format a declared default value for command documentation. */
+function formatDefault(value) {
+	if (isNonFiniteNumber(value)) return String(value);
+	if (Array.isArray(value)) return value.map(String).join(", ");
+	return JSON.stringify(value) ?? String(value);
+}
+/** Format a definition's description and optional default/choice annotations. */
+function formatDescription(description, defaultValue, choices, formatAnnotation = (annotation) => annotation) {
+	const parts = description ? [description] : [];
+	if (defaultValue !== void 0) parts.push(formatAnnotation(`[default: ${formatDefault(defaultValue)}]`));
+	if (choices?.length) parts.push(formatAnnotation(`[choices: ${choices.join(", ")}]`));
+	return parts.join(" ");
+}
+function argToken(arg) {
+	const name = arg.variadic ? `${arg.name}...` : arg.name;
+	return arg.required ? `<${name}>` : `[${name}]`;
+}
+function documentationFlags(flags) {
+	return Object.entries(flags).map(([name, def]) => {
+		const long = [name, ...def.aliases ?? []];
+		return Object.freeze({
+			name,
+			spellings: Object.freeze([
+				...def.short ? [`-${def.short}`] : [],
+				...long.map((spelling) => `--${spelling}`),
+				...def.negatable ? long.map((spelling) => `--no-${spelling}`) : []
+			]),
+			short: def.short,
+			aliases: Object.freeze([...def.aliases ?? []]),
+			negatable: def.negatable,
+			type: def.type,
+			description: def.description,
+			required: def.required === true,
+			multiple: def.multiple === true,
+			choices: def.choices,
+			default: def.default
+		});
+	});
+}
+function buildNode(command, path) {
+	const args = command.args.map((arg) => Object.freeze({
+		...arg,
+		token: argToken(arg),
+		required: arg.required === true,
+		variadic: arg.variadic === true
+	}));
+	const children = Object.entries(command.subCommands).flatMap(([name, child]) => isListed(child) ? [buildNode(child, [...path, name])] : []);
+	const flags = documentationFlags(command.flags);
+	const usageSegments = command.meta.usage ? [{
+		kind: "custom",
+		text: command.meta.usage
+	}] : [
+		{
+			kind: "path",
+			text: path.join(" ")
+		},
+		...children.length > 0 && !command.hasAction ? [{
+			kind: "command",
+			text: "<command>"
+		}] : [],
+		...args.map((arg) => ({
+			kind: "arg",
+			text: arg.token,
+			required: arg.required
+		})),
+		...flags.length > 0 ? [{
+			kind: "options",
+			text: "[options]"
+		}] : []
+	];
+	const usage = usageSegments.map((segment) => segment.text).join(" ");
+	return Object.freeze({
+		name: command.meta.name,
+		path: Object.freeze([...path]),
+		description: command.meta.description,
+		aliases: Object.freeze([...command.meta.aliases ?? []]),
+		usage,
+		usageSegments: Object.freeze(usageSegments.map((segment) => Object.freeze(segment))),
+		hasAction: command.hasAction,
+		args: Object.freeze(args),
+		flags: Object.freeze(flags),
+		sections: Object.freeze([...command.meta.sections ?? []]),
+		children: Object.freeze(children)
+	});
+}
+/** Build the presentation-neutral documentation model for a full command tree. */
+function buildCommandDocumentation(command, path = [command.meta.name]) {
+	return buildNode(command, path);
+}
+//#endregion
+export { BUILD_OUT_DIR_ENV, SNAPSHOT_PATH_ENV, buildCommandDocumentation, formatDefault, formatDescription, isListed, sectionsFor, visibleSectionsFor };