@ykdz/template 0.0.37 → 0.0.40

package/node_modules/@ykdz/cli-contract/dist/cli-invocation.d.ts

@@ -0,0 +1,174 @@
+import { type CliContract, type CliContractRawInput, type CliContractRoot } from "#/cli-contract";
+declare const cliInvocationType: unique symbol;
+/**
+ * 已通过调用语法检查的原始输入；契约模式尚未验证、转换或填充默认值。
+ * 业务处理器应使用执行内核交付的已验证输入，而不是直接消费此处的 input。
+ */
+export interface ParsedInvocation<Command extends string, Input = unknown> {
+    readonly kind: "parsed";
+    readonly command: Command;
+    readonly input: Input;
+    readonly outputFormat: "structured" | "text";
+}
+export interface HelpRequest<Command extends string> {
+    readonly kind: "help";
+    readonly command: Command;
+}
+export interface VersionRequest<Command extends string> {
+    readonly kind: "version";
+    readonly command: Command;
+}
+export interface UnexpectedPositionalIssue {
+    readonly code: "unexpectedPositional";
+    readonly position: number;
+    readonly value: string;
+}
+export interface UnknownOptionIssue {
+    readonly code: "unknownOption";
+    readonly position: number;
+    readonly option: string;
+    readonly suggestedOption?: string;
+}
+export interface UnknownCommandIssue {
+    readonly code: "unknownCommand";
+    readonly position: number;
+    readonly command: string;
+    readonly suggestedCommand?: string;
+}
+export interface MissingOptionValueIssue {
+    readonly code: "missingOptionValue";
+    readonly position: number;
+    readonly field: string;
+    readonly option: string;
+}
+export interface UnexpectedOptionValueIssue {
+    readonly code: "unexpectedOptionValue";
+    readonly position: number;
+    readonly field: string;
+    readonly option: string;
+    readonly value: string;
+}
+export interface OptionOccurrenceEvidence {
+    readonly position: number;
+    readonly option: string;
+}
+export interface MissingRequiredFieldIssue {
+    readonly code: "missingRequiredField";
+    readonly field: string;
+}
+export interface RepeatedOptionIssue {
+    readonly code: "repeatedOption";
+    readonly field: string;
+    readonly occurrences: readonly [
+        OptionOccurrenceEvidence,
+        OptionOccurrenceEvidence,
+        ...OptionOccurrenceEvidence[]
+    ];
+}
+export interface ConflictingFlagIssue {
+    readonly code: "conflictingFlag";
+    readonly field: string;
+    readonly positiveOccurrences: readonly [
+        OptionOccurrenceEvidence,
+        ...OptionOccurrenceEvidence[]
+    ];
+    readonly negativeOccurrences: readonly [
+        OptionOccurrenceEvidence,
+        ...OptionOccurrenceEvidence[]
+    ];
+}
+export interface RequiredByUsageConstraintIssue {
+    readonly code: "requiredByUsageConstraint";
+    readonly field: string;
+    readonly requires: string;
+}
+export interface ExclusiveUsageConstraintIssue {
+    readonly code: "exclusiveUsageConstraint";
+    readonly fields: readonly [string, string, ...string[]];
+}
+export interface ForbiddenUsageCombinationIssue {
+    readonly code: "forbiddenUsageCombination";
+    readonly values: readonly [
+        Readonly<{
+            readonly field: string;
+            readonly value: boolean | string;
+        }>,
+        Readonly<{
+            readonly field: string;
+            readonly value: boolean | string;
+        }>,
+        ...Readonly<{
+            readonly field: string;
+            readonly value: boolean | string;
+        }>[]
+    ];
+}
+export interface SchemaIssueEvidence {
+    readonly message: string;
+    readonly path?: readonly (number | string)[];
+}
+export interface InputRejectedIssue {
+    readonly code: "inputRejected";
+    readonly evidence: readonly SchemaIssueEvidence[];
+}
+export interface InvalidFieldChoiceIssue {
+    readonly code: "invalidFieldChoice";
+    readonly position: number;
+    readonly field: string;
+    readonly value: string;
+    readonly choices: readonly string[];
+}
+export interface InvalidOutputFormatIssue {
+    readonly code: "invalidOutputFormat";
+    readonly position: number;
+    readonly option: string;
+    readonly received: string | null;
+}
+export interface ConflictingOutputFormatIssue {
+    readonly code: "conflictingOutputFormat";
+    readonly occurrences: readonly [
+        Readonly<{
+            readonly position: number;
+            readonly option: string;
+            readonly format: "structured" | "text";
+        }>,
+        Readonly<{
+            readonly position: number;
+            readonly option: string;
+            readonly format: "structured" | "text";
+        }>,
+        ...Readonly<{
+            readonly position: number;
+            readonly option: string;
+            readonly format: "structured" | "text";
+        }>[]
+    ];
+}
+export type UsageIssue = ConflictingFlagIssue | ConflictingOutputFormatIssue | ExclusiveUsageConstraintIssue | ForbiddenUsageCombinationIssue | InputRejectedIssue | InvalidFieldChoiceIssue | InvalidOutputFormatIssue | MissingOptionValueIssue | MissingRequiredFieldIssue | RepeatedOptionIssue | RequiredByUsageConstraintIssue | UnexpectedOptionValueIssue | UnexpectedPositionalIssue | UnknownCommandIssue | UnknownOptionIssue;
+export type NonEmptyUsageIssues = readonly [UsageIssue, ...UsageIssue[]];
+export interface CommandUsage<Command extends string> {
+    readonly command: Command;
+    readonly synopsis: string;
+}
+export interface UsageFailure<Command extends string> {
+    readonly kind: "usageFailure";
+    readonly command: Command;
+    readonly issues: NonEmptyUsageIssues;
+    readonly usage: CommandUsage<Command>;
+}
+/** 解析器签发的闭合调用事实，只能交还产生它的同一个契约执行；不要自行拼装。 */
+export type CliInvocation<Contract extends CliContract = CliContract> = UnboundCliInvocation<Contract> & {
+    readonly [cliInvocationType]: Contract;
+};
+type UnboundCliInvocation<Contract extends CliContract> = ParsedInvocation<CliContractRoot<Contract>, CliContractRawInput<Contract>> | HelpRequest<CliContractRoot<Contract>> | VersionRequest<CliContractRoot<Contract>> | UsageFailure<CliContractRoot<Contract>>;
+/**
+ * 将宿主提供的参数 token 同步、无副作用地解析为同一契约的调用事实。
+ * 参数从命令路径或字段开始，不包含 Node 可执行文件和脚本路径；来源与 shell 拆词由宿主负责。
+ *
+ * 解析器检查调用语法与用法约束，保留帮助、版本和用法失败等闭合分支；
+ * 已解析的 raw input 尚未经过契约模式验证。它不读取进程或环境，不执行 handler，也不写输出。
+ * 将返回值交给 {@link executeCli}，由执行内核完成后续验证与投影。
+ */
+export declare function parseCliInvocation<const Contract extends CliContract>(cliContract: Contract, argv: readonly string[]): CliInvocation<Contract>;
+export declare function invocationBelongsTo(invocation: object, contract: object): boolean;
+export {};