@ykdz/template 0.0.42 → 0.1.0-experimental.0

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

@@ -1,5 +1,5 @@
 import { type CliContract, type CliContractDependencies, type CliContractResult, type CliContractRoot } from "#/cli-contract";
-import { type CliInvocation, type NonEmptyUsageIssues } from "#/cli-invocation";
+import { type CliInvocation, type NonEmptyCliUsageIssues } from "#/cli-invocation";
 export type CliOutputDestination = "stderr" | "stdout";
 /** 核心已完成投影和通道路由的非空文本 chunk；宿主写入时不再改写格式或目的通道。 */
 export interface CliOutput {
@@ -29,12 +29,15 @@ export type CliTermination<Contract extends CliContract = CliContract> = Readonl
     readonly kind: "version";
     readonly command: CliContractRoot<Contract>;
     readonly exitCode: 0;
-}> | Readonly<{
-    readonly kind: "usageFailure";
-    readonly command: CliContractRoot<Contract>;
-    readonly issues: NonEmptyUsageIssues;
-    readonly exitCode: number;
-}>;
+}> | UsageFailureTermination<Contract>;
+type UsageFailureTermination<Contract extends CliContract> = {
+    [Command in CliContractRoot<Contract>]: Readonly<{
+        readonly kind: "usageFailure";
+        readonly command: Command;
+        readonly issues: NonEmptyCliUsageIssues<Contract, Command>;
+        readonly exitCode: number;
+    }>;
+}[CliContractRoot<Contract>];
 export interface ExecuteCliOptions<Contract extends CliContract> {
     readonly invocation: CliInvocation<NoInfer<Contract>>;
     readonly dependencies: CliContractDependencies<Contract>;
@@ -52,3 +55,4 @@ export interface ExecuteCliOptions<Contract extends CliContract> {
  * 活动流会执行必要清理，已经写出的合法前缀不会撤回，也不会追加伪造的成功终态。
  */
 export declare function executeCli<const Contract extends CliContract>(cliContract: Contract, options: ExecuteCliOptions<Contract>): Promise<CliTermination<Contract>>;
+export {};

package/node_modules/@ykdz/cli-contract/dist/cli-execution.js

@@ -1,4 +1,4 @@
-import { createCompletionFact, createDataFact, createFailureFact, createStreamRecordFact, createStreamSuccessFact, formatFieldUsage, getCompiledCli, isCompiledExecutable, isIssuedOutcomeFact, usageFailureHelpArgv, } from "#/cli-contract";
+import { createCompletionFact, createDataFact, createFailureFact, createStreamRecordFact, createStreamSuccessFact, countHelpFactForConstraint, formatFieldUsage, getCompiledCli, helpTemplateSpecifications, isCompiledExecutable, isIssuedOutcomeFact, usageFailureHelpArgv, } from "#/cli-contract";
 import { invocationBelongsTo, } from "#/cli-invocation";
 import { CliWriteError } from "#/cli-write-error";
 import { ContractExecutionError, } from "#/contract-execution-error";
@@ -176,7 +176,7 @@ function formatCoreControls(compiled) {
         ...(output.selector === undefined
             ? []
             : [
-                helpLine(`${output.selector} <${output.formats.join("|")}> ${renderHelpFactTemplate(help.wording?.choices, { choices: output.formats.map((format) => JSON.stringify(format)).join(", ") })} ${renderHelpFactTemplate(help.wording?.default, { value: JSON.stringify(output.defaultFormat) })}`),
+                helpLine(`${output.selector} <${output.formats.join("|")}> ${renderHelpFactTemplate("choices", help.wording?.choices, { choices: output.formats.map((format) => JSON.stringify(format)).join(", ") })} ${renderHelpFactTemplate("default", help.wording?.default, { value: JSON.stringify(output.defaultFormat) })}`),
             ]),
         ...Object.entries(output.compatibilityFlags ?? {}).map(([flag, format]) => helpLine(output.selector === undefined
             ? `${flag} = ${format}`
@@ -190,25 +190,75 @@ async function writeUsageFailure(compiled, write, failure) {
     });
 }
 function formatUsageConstraint(constraint, wording) {
-    if (constraint.kind === "requires")
-        return renderHelpFactTemplate(wording?.requires, {
-            field: constraint.field,
-            requires: constraint.requires,
+    if (constraint.kind === "count") {
+        const { slot, values } = countHelpFactForConstraint(constraint);
+        return renderHelpFactTemplate(slot, wording?.[slot], values);
+    }
+    const facts = constraint.all
+        .map((fact) => formatUsageFact(fact, wording))
+        .join(", ");
+    if (constraint.kind === "when") {
+        const onMatch = constraint.onMatch === undefined
+            ? ""
+            : formatUsageEffect(constraint.onMatch, wording);
+        const otherwise = constraint.otherwise === undefined
+            ? ""
+            : formatUsageEffect(constraint.otherwise, wording);
+        if (onMatch.length > 0 && otherwise.length > 0) {
+            return renderHelpFactTemplate("whenOnMatchOtherwise", wording?.whenOnMatchOtherwise, { facts, onMatch, otherwise });
+        }
+        if (onMatch.length > 0) {
+            return renderHelpFactTemplate("whenOnMatch", wording?.whenOnMatch, {
+                facts,
+                onMatch,
+            });
+        }
+        return renderHelpFactTemplate("whenOtherwise", wording?.whenOtherwise, {
+            facts,
+            otherwise,
         });
-    if (constraint.kind === "exclusive")
-        return renderHelpFactTemplate(wording?.exclusive, {
-            fields: constraint.fields.join(", "),
+    }
+    return renderHelpFactTemplate("forbiddenCombination", wording?.forbiddenCombination, { facts });
+}
+function formatUsageEffect(effect, wording) {
+    const parts = [];
+    const required = effect.require ?? [];
+    const forbidden = effect.forbid ?? [];
+    if (required.length > 0) {
+        parts.push(renderHelpFactTemplate("require", wording?.require, {
+            fields: required.join(", "),
+        }));
+    }
+    if (forbidden.length > 0) {
+        parts.push(renderHelpFactTemplate("forbid", wording?.forbid, {
+            fields: forbidden.join(", "),
+        }));
+    }
+    return parts.join(", ");
+}
+function formatUsageFact(fact, wording) {
+    return fact.kind === "present"
+        ? renderHelpFactTemplate("present", wording?.present, {
+            field: fact.field,
+        })
+        : renderHelpFactTemplate("equals", wording?.equals, {
+            field: fact.field,
+            value: JSON.stringify(fact.value),
         });
-    return renderHelpFactTemplate(wording?.forbiddenCombination, {
-        values: constraint.values
-            .map(({ field, value }) => `${field}=${JSON.stringify(value)}`)
-            .join(", "),
-    });
 }
-function renderHelpFactTemplate(template, values) {
+function renderHelpFactTemplate(slot, template, values) {
     const factTemplate = requireHelpFactWording(template);
+    const replacements = new Map();
+    for (const key of Object.keys(values)) {
+        const value = Reflect.get(values, key);
+        if (typeof value === "string")
+            replacements.set(key, value);
+    }
+    if (helpTemplateSpecifications[slot].placeholders.some((placeholder) => !replacements.has(placeholder))) {
+        throw new ContractExecutionError([{ code: "invalidCliContract" }]);
+    }
     return factTemplate.replace(/\{([A-Za-z][A-Za-z0-9]*)\}/g, (_match, key) => {
-        const value = values[key];
+        const value = replacements.get(key);
         if (value === undefined) {
             throw new ContractExecutionError([{ code: "invalidCliContract" }]);
         }
@@ -225,10 +275,10 @@ function formatHelpField(field, wording) {
     const cardinality = formatFieldUsage(field, true);
     const choices = field.choices === undefined
         ? ""
-        : ` ${renderHelpFactTemplate(wording?.choices, { choices: field.choices.map((choice) => JSON.stringify(choice)).join(", ") })}`;
+        : ` ${renderHelpFactTemplate("choices", wording?.choices, { choices: field.choices.map((choice) => JSON.stringify(choice)).join(", ") })}`;
     const defaultValue = field.default === undefined
         ? ""
-        : ` ${renderHelpFactTemplate(wording?.default, { value: JSON.stringify(field.default) })}`;
+        : ` ${renderHelpFactTemplate("default", wording?.default, { value: JSON.stringify(field.default) })}`;
     return helpDetail(`${cardinality}${choices}${defaultValue}`, field.description);
 }
 async function executeApplicationResult(compiled, input, options, outputFormat) {
@@ -654,10 +704,7 @@ function isStandardResult(value) {
     if (!("issues" in value) || value.issues === undefined) {
         return "value" in value;
     }
-    return (!("value" in value) &&
-        Array.isArray(value.issues) &&
-        value.issues.length > 0 &&
-        value.issues.every(isStandardIssue));
+    return Array.isArray(value.issues) && value.issues.every(isStandardIssue);
 }
 function isStandardIssue(value) {
     if (typeof value !== "object" ||

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

@@ -1,4 +1,4 @@
-import { type CliContract, type CliContractRawInput, type CliContractRoot } from "#/cli-contract";
+import { type CliContract, type CliContractRawInput, type CliContractRoot, type CliContractUsageFacts, type FieldDefinitions, type WhenUsageConstraint, type UsageFact } from "#/cli-contract";
 declare const cliInvocationType: unique symbol;
 /**
  * 已通过调用语法检查的原始输入；契约模式尚未验证、转换或填充默认值。
@@ -77,32 +77,81 @@ export interface ConflictingFlagIssue {
         ...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;
-        }>[]
-    ];
-}
+/** 一条数量规则失败，按字段声明顺序划分 raw 输入中出现与缺席的字段。 */
+export interface CountConstraintViolationIssue {
+    readonly code: "countConstraintViolation";
+    readonly min: number;
+    readonly max: number;
+    readonly presentFields: readonly string[];
+    readonly absentFields: readonly string[];
+}
+/** 禁配事实组全部在 raw argv 中成立时发出的单条用法问题。 */
+export interface ForbiddenCombinationViolationIssue {
+    readonly code: "forbiddenCombinationViolation";
+    readonly facts: readonly [UsageFact, ...UsageFact[]];
+}
+/** present 事实的 raw argv 观察只报告字段和是否出现。 */
+export interface PresentUsageObservation<Field extends string = string> {
+    readonly kind: "present";
+    readonly field: Field;
+    readonly present: boolean;
+}
+/** equals 观察在字段缺席时省略 actual；出现时 actual 保持 raw 基础标量域。 */
+export type EqualsUsageObservation<Field extends string = string, Expected extends boolean | string = boolean | string> = Readonly<{
+    readonly kind: "equals";
+    readonly field: Field;
+    readonly expected: Expected;
+    readonly present: false;
+}> | Readonly<{
+    readonly kind: "equals";
+    readonly field: Field;
+    readonly expected: Expected;
+    readonly present: true;
+    readonly actual: boolean | string;
+}>;
+export type UsageConstraintObservation<Fact = UsageFact> = Fact extends Readonly<{
+    readonly kind: "present";
+    readonly field: infer Field extends string;
+}> ? PresentUsageObservation<Field> : Fact extends Readonly<{
+    readonly kind: "equals";
+    readonly field: infer Field extends string;
+    readonly value: infer Expected extends boolean | string;
+}> ? EqualsUsageObservation<Field, Expected> : never;
+type UsageConstraintObservationTuple<Facts extends readonly unknown[]> = {
+    readonly [Index in keyof Facts]: UsageConstraintObservation<Facts[Index]>;
+};
+type EffectFields<Effect, Member extends "require" | "forbid"> = Effect extends object ? Member extends keyof Effect ? Exclude<Effect[Member], undefined> extends readonly (infer Field extends string)[] ? Field : never : never : never;
+/** 一条条件规则的完整 raw 观察和分支效果；每条失败规则只产生这一条问题。 */
+export interface ConditionalConstraintViolationIssue<Conditions extends readonly unknown[] = readonly UsageConstraintObservation[], Branch extends "onMatch" | "otherwise" = "onMatch" | "otherwise", MissingField extends string = string, ForbiddenField extends string = string> {
+    readonly code: "conditionalConstraintViolation";
+    readonly branch: Branch;
+    readonly conditions: Conditions;
+    readonly missingRequiredFields: readonly MissingField[];
+    readonly presentForbiddenFields: readonly ForbiddenField[];
+}
+type WhenConstraintUnion<Constraints> = Constraints extends readonly (infer Constraint)[] ? Extract<Constraint, Readonly<{
+    readonly kind: "when";
+}>> : Extract<Constraints, Readonly<{
+    readonly kind: "when";
+}>>;
+type ConditionalConstraintEffectFields<Constraints, Member extends "require" | "forbid"> = WhenConstraintUnion<Constraints> extends infer Constraint ? Constraint extends Readonly<{
+    readonly kind: "when";
+    readonly onMatch?: infer OnMatch;
+    readonly otherwise?: infer Otherwise;
+}> ? EffectFields<OnMatch, Member> | EffectFields<Otherwise, Member> : never : never;
+type ConditionalConstraintIssueFor<Constraint, MissingField extends string, ForbiddenField extends string> = Constraint extends WhenUsageConstraint<FieldDefinitions, unknown> ? ConditionalConstraintViolationIssue<UsageConstraintObservationTuple<Constraint["all"]>, "onMatch" | "otherwise", MissingField, ForbiddenField> : never;
+type ConditionalConstraintIssues<Constraints> = WhenConstraintUnion<Constraints> extends infer Constraint ? Constraint extends unknown ? ConditionalConstraintIssueFor<Constraint, ConditionalConstraintEffectFields<Constraints, "require">, ConditionalConstraintEffectFields<Constraints, "forbid">> : never : never;
+type ContractConditionalUsageIssue<Contract, Command extends string> = string extends keyof CliContractUsageFacts<Contract> ? ConditionalConstraintViolationIssue : CliContractUsageFacts<Contract> extends Readonly<Record<Command, infer Constraints>> ? ConditionalConstraintIssues<Constraints> : never;
+export type CliUsageIssue<Contract extends CliContract = CliContract, Command extends string = CliContractRoot<Contract>> = Exclude<UsageIssue, {
+    readonly code: "conditionalConstraintViolation";
+}> | ContractConditionalUsageIssue<Contract, Command>;
+export type NonEmptyCliUsageIssues<Contract extends CliContract = CliContract, Command extends string = CliContractRoot<Contract>> = readonly [
+    CliUsageIssue<Contract, Command>,
+    ...CliUsageIssue<Contract, Command>[]
+];
+type UsageFailuresForContract<Contract extends CliContract> = {
+    [Command in CliContractRoot<Contract>]: UsageFailure<Command, NonEmptyCliUsageIssues<Contract, Command>>;
+}[CliContractRoot<Contract>];
 export interface SchemaIssueEvidence {
     readonly message: string;
     readonly path?: readonly (number | string)[];
@@ -144,23 +193,23 @@ export interface ConflictingOutputFormatIssue {
         }>[]
     ];
 }
-export type UsageIssue = ConflictingFlagIssue | ConflictingOutputFormatIssue | ExclusiveUsageConstraintIssue | ForbiddenUsageCombinationIssue | InputRejectedIssue | InvalidFieldChoiceIssue | InvalidOutputFormatIssue | MissingOptionValueIssue | MissingRequiredFieldIssue | RepeatedOptionIssue | RequiredByUsageConstraintIssue | UnexpectedOptionValueIssue | UnexpectedPositionalIssue | UnknownCommandIssue | UnknownOptionIssue;
+export type UsageIssue = ConflictingFlagIssue | ConflictingOutputFormatIssue | CountConstraintViolationIssue | ForbiddenCombinationViolationIssue | ConditionalConstraintViolationIssue | InputRejectedIssue | InvalidFieldChoiceIssue | InvalidOutputFormatIssue | MissingOptionValueIssue | MissingRequiredFieldIssue | RepeatedOptionIssue | 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> {
+export interface UsageFailure<Command extends string, Issues extends NonEmptyUsageIssues = NonEmptyUsageIssues> {
     readonly kind: "usageFailure";
     readonly command: Command;
-    readonly issues: NonEmptyUsageIssues;
+    readonly issues: Issues;
     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>>;
+type UnboundCliInvocation<Contract extends CliContract> = ParsedInvocation<CliContractRoot<Contract>, CliContractRawInput<Contract>> | HelpRequest<CliContractRoot<Contract>> | VersionRequest<CliContractRoot<Contract>> | UsageFailuresForContract<Contract>;
 /**
  * 将宿主提供的参数 token 同步、无副作用地解析为同一契约的调用事实。
  * 参数从命令路径或字段开始，不包含 Node 可执行文件和脚本路径；来源与 shell 拆词由宿主负责。

package/node_modules/@ykdz/cli-contract/dist/cli-invocation.js

@@ -361,41 +361,99 @@ function collectStructuralIssues(fields, input, occurrencesByField, valueOccurre
         return issues;
     });
     const constraintIssues = usageConstraints.flatMap((constraint) => {
-        if (constraint.kind === "requires") {
-            return Object.hasOwn(input, constraint.field) &&
-                !Object.hasOwn(input, constraint.requires)
-                ? [
-                    {
-                        code: "requiredByUsageConstraint",
-                        field: constraint.field,
-                        requires: constraint.requires,
-                    },
-                ]
-                : [];
+        if (constraint.kind === "count") {
+            const presentFields = constraint.fields.filter((field) => Object.hasOwn(input, field));
+            if (presentFields.length >= constraint.min &&
+                presentFields.length <= constraint.max) {
+                return [];
+            }
+            const present = new Set(presentFields);
+            return [
+                {
+                    code: "countConstraintViolation",
+                    min: constraint.min,
+                    max: constraint.max,
+                    presentFields: Object.freeze(presentFields),
+                    absentFields: Object.freeze(constraint.fields.filter((field) => !present.has(field))),
+                },
+            ];
         }
-        if (constraint.kind === "exclusive") {
-            const present = constraint.fields.filter((field) => Object.hasOwn(input, field));
-            return present.length > 1
-                ? [
-                    {
-                        code: "exclusiveUsageConstraint",
-                        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- present.length 已检查大于一。
-                        fields: Object.freeze(present),
-                    },
-                ]
-                : [];
+        if (constraint.kind === "when") {
+            const observed = constraint.all.map((fact) => observeUsageFact(fact, input));
+            const branch = observed.every(({ matches }) => matches)
+                ? "onMatch"
+                : "otherwise";
+            const effect = constraint[branch];
+            if (effect === undefined)
+                return [];
+            const missingRequiredFields = (effect.require ?? []).filter((field) => !Object.hasOwn(input, field));
+            const presentForbiddenFields = (effect.forbid ?? []).filter((field) => Object.hasOwn(input, field));
+            if (missingRequiredFields.length === 0 &&
+                presentForbiddenFields.length === 0) {
+                return [];
+            }
+            return [
+                {
+                    code: "conditionalConstraintViolation",
+                    branch,
+                    conditions: Object.freeze(observed.map(({ observation }) => observation)),
+                    missingRequiredFields: Object.freeze(missingRequiredFields),
+                    presentForbiddenFields: Object.freeze(presentForbiddenFields),
+                },
+            ];
         }
-        return constraint.values.every(({ field, value }) => input[field] === value)
+        return constraint.all.every((fact) => fact.kind === "present"
+            ? Object.hasOwn(input, fact.field)
+            : Object.hasOwn(input, fact.field) &&
+                input[fact.field] === fact.value)
             ? [
                 {
-                    code: "forbiddenUsageCombination",
-                    values: constraint.values,
+                    code: "forbiddenCombinationViolation",
+                    facts: constraint.all,
                 },
             ]
             : [];
     });
     return [...fieldIssues, ...constraintIssues];
 }
+function observeUsageFact(fact, input) {
+    const present = Object.hasOwn(input, fact.field);
+    if (fact.kind === "present") {
+        return {
+            matches: present,
+            observation: Object.freeze({
+                kind: "present",
+                field: fact.field,
+                present,
+            }),
+        };
+    }
+    if (!present) {
+        return {
+            matches: false,
+            observation: Object.freeze({
+                kind: "equals",
+                field: fact.field,
+                expected: fact.value,
+                present: false,
+            }),
+        };
+    }
+    const actual = input[fact.field];
+    if (typeof actual !== "boolean" && typeof actual !== "string") {
+        throw new ContractExecutionError([{ code: "invalidCliContract" }]);
+    }
+    return {
+        matches: actual === fact.value,
+        observation: Object.freeze({
+            kind: "equals",
+            field: fact.field,
+            expected: fact.value,
+            present: true,
+            actual,
+        }),
+    };
+}
 function freezeOccurrenceEvidence(occurrences) {
     return Object.freeze(occurrences.map(({ position, option }) => Object.freeze({ position, option })));
 }
@@ -508,7 +566,7 @@ function usageFailureFromIssues(contract, command, usage, issues) {
     return bindInvocation(contract, {
         kind: "usageFailure",
         command,
-        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 输入参数是非空元组，映射后长度不变。
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 每个条件问题都由同一已编译契约的 raw 字段事实生成。
         issues: Object.freeze(issues.map((issue) => Object.freeze(issue))),
         usage,
     });

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

@@ -1,3 +1,4 @@
+import type { JsonValue } from "#/contract-schema";
 export type SchemaDefinitionTarget = Readonly<{
     readonly command: string;
     readonly location: "input";
@@ -16,7 +17,13 @@ export type ContractDefinitionIssue = Readonly<{
 }> | Readonly<{
     readonly code: "missingHelpFactTemplate";
     readonly command: string;
-    readonly slot: "commandPlaceholder" | "choices" | "default" | "requires" | "exclusive" | "forbiddenCombination";
+    readonly slot: "commandPlaceholder" | "choices" | "default" | "forbiddenCombination" | "countExactly" | "countAtLeast" | "countAtMost" | "countBetween" | "whenOnMatch" | "whenOtherwise" | "whenOnMatchOtherwise" | "require" | "forbid" | "present" | "equals";
+}> | Readonly<{
+    readonly code: "invalidHelpFactTemplate";
+    readonly path: readonly string[];
+    readonly slot: string;
+    readonly received: unknown;
+    readonly reason: "singleLine" | "empty" | "placeholder";
 }> | Readonly<SchemaDefinitionTarget & {
     readonly code: "missingSchemaCapability";
     readonly capability: "standard" | "validation" | "jsonSchema";
@@ -42,7 +49,12 @@ export type ContractDefinitionIssue = Readonly<{
     readonly location: "input";
     readonly fields: readonly Readonly<{
         readonly field: string;
+        /** 指向命令声明中对应输入模式属性的位置。 */
+        readonly path: readonly string[];
+        /** CLI 字段解析器产生的 raw 值形态。 */
         readonly expected: "boolean" | "string" | "stringArray";
+        /** 实际 JSON Schema Input 投影，不代表 Standard Schema 的 TypeScript Input。 */
+        readonly received: JsonValue;
     }>[];
 }> | Readonly<{
     readonly code: "invalidInputSchemaShape";
@@ -169,6 +181,7 @@ export type ContractDefinitionIssue = Readonly<{
     readonly code: "invalidFieldIdentity";
     readonly command: string;
     readonly field: string;
+    readonly reason: "lowerCamelCase" | "reservedName";
 }> | Readonly<{
     readonly code: "invalidFieldKind";
     readonly command: string;
@@ -220,29 +233,49 @@ export type ContractDefinitionIssue = Readonly<{
     readonly command: string;
     readonly index: number | null;
     readonly aspect: "collection" | "entry" | "kind" | "members";
-    readonly received: string | null;
+    readonly received: unknown;
+    readonly member?: string;
+    readonly path?: readonly (string | number)[];
+    readonly expected?: string;
+}> | Readonly<{
+    readonly code: "invalidCountConstraint";
+    readonly command: string;
+    readonly index: number;
+    readonly member: "fields" | "min" | "max";
+    readonly reason: "nonEmpty" | "fieldName" | "duplicateFields" | "endpointRequired" | "finite" | "integer" | "nonNegative" | "fieldCount" | "ordered";
+    readonly actual?: number;
+    readonly maximum?: number;
+    readonly fields?: readonly string[];
 }> | Readonly<{
     readonly code: "unknownUsageConstraintField";
     readonly command: string;
-    readonly constraint: "requires" | "exclusive" | "forbiddenCombination";
+    readonly constraint: "count" | "forbiddenCombination" | "when";
     readonly index: number;
-    readonly member: "field" | "requires" | "fields" | "values.field";
+    readonly member: "fields" | "all.field" | "onMatch.require" | "onMatch.forbid" | "otherwise.require" | "otherwise.forbid";
     readonly field: string;
 }> | Readonly<{
     readonly code: "inapplicableUsageConstraintField";
     readonly command: string;
-    readonly constraint: "requires" | "exclusive" | "forbiddenCombination";
+    readonly constraint: "forbiddenCombination" | "when";
+    readonly index?: number;
+    readonly member?: "all.field";
     readonly field: string;
     readonly kind: FieldKind;
 }> | Readonly<{
     readonly code: "invalidUsageConstraintValue";
     readonly command: string;
+    readonly constraint: "forbiddenCombination" | "when";
+    readonly index: number;
+    readonly member: "all.value";
     readonly field: string;
-    readonly expected: "boolean" | "string";
+    readonly actual: unknown;
+    readonly expected: boolean | string | readonly string[];
 }> | Readonly<{
     readonly code: "contradictoryUsageConstraint";
     readonly command: string;
-    readonly constraint: "requires" | "exclusive" | "forbiddenCombination";
+    readonly constraint: "forbiddenCombination" | "when";
+    readonly index?: number;
+    readonly member?: "all" | "onMatch" | "otherwise";
     readonly fields: readonly string[];
 }>;
 type FieldKind = "positional" | "variadicPositional" | "flag" | "valueOption" | "repeatableOption";

package/node_modules/@ykdz/cli-contract/dist/contract-definition-error.js

@@ -21,6 +21,8 @@ function formatContractDefinitionIssue(issue) {
             return `CLI 声明包含未知属性 ${issue.path.join(".")}`;
         case "missingHelpFactTemplate":
             return `命令 ${issue.command} 的帮助事实缺少 ${issue.slot} 模板`;
+        case "invalidHelpFactTemplate":
+            return `帮助事实模板 ${issue.slot} 无效：${issue.reason}`;
         case "missingSchemaCapability":
             return `${formatSchemaTarget(issue)} 缺少 ${issue.capability} 能力`;
         case "schemaDialectMismatch":
@@ -32,7 +34,7 @@ function formatContractDefinitionIssue(issue) {
         case "schemaFieldSetMismatch":
             return `命令 ${issue.command} 的字段与输入模式属性不一致`;
         case "schemaFieldDoesNotAcceptRawValue":
-            return `命令 ${issue.command} 的输入字段 ${issue.fields.map(({ field, expected }) => `${field} 不接受 raw ${expected}`).join(", ")}`;
+            return `命令 ${issue.command} 的输入字段 ${issue.fields.map(({ field, path, expected, received }) => `${field}（${path.join(".")}）需要 raw ${expected}，实际输入模式属性为 ${JSON.stringify(received)}`).join(", ")}`;
         case "invalidInputSchemaShape":
             return `命令 ${issue.command} 的输入模式 ${issue.aspect} 无效`;
         case "missingInputDefault":
@@ -94,7 +96,9 @@ function formatContractDefinitionIssue(issue) {
         case "invalidFieldLongOption":
             return `命令 ${issue.command} 的字段 ${issue.field} long option 无效`;
         case "invalidFieldIdentity":
-            return `命令 ${issue.command} 的字段身份 ${issue.field} 无效`;
+            return issue.reason === "reservedName"
+                ? `命令 ${issue.command} 的字段身份 ${issue.field} 为保留名称；请更换字段键，并同步模式 Input 键及相关引用；CLI 拼写可保留`
+                : `命令 ${issue.command} 的字段身份 ${issue.field} 必须符合 lowerCamelCase（小写字母开头，仅含字母和数字）`;
         case "invalidFieldKind":
             return `命令 ${issue.command} 的字段 ${issue.field} kind 无效`;
         case "invalidFieldShortAlias":
@@ -112,15 +116,33 @@ function formatContractDefinitionIssue(issue) {
         case "missingDataVariant":
             return `命令 ${issue.command} 必须声明至少一个 data 变体`;
         case "invalidUsageConstraint":
-            return `命令 ${issue.command} 的 usage constraint ${issue.received ?? "非字符串"} 无效`;
+            return `命令 ${issue.command} 的 usage constraint${issue.index === null ? "" : `[${issue.index}]`}${issue.member === undefined ? "" : ` ${issue.member}`} ${formatIssueValue(issue.received)} 无效${issue.expected === undefined ? "" : `，期望 ${issue.expected}`}${issue.path === undefined ? "" : `（${issue.path.join(".")}）`}`;
+        case "invalidCountConstraint":
+            return `命令 ${issue.command} 的 count ${issue.member} 无效（${issue.reason}）`;
         case "unknownUsageConstraintField":
             return `命令 ${issue.command} 的 usage constraint[${issue.index}] ${issue.constraint}.${issue.member} 引用了不存在字段 ${issue.field}`;
         case "inapplicableUsageConstraintField":
-            return `命令 ${issue.command} 的 ${issue.constraint} usage constraint 不适用于字段 ${issue.field}（${issue.kind}）`;
+            return `命令 ${issue.command} 的 ${issue.constraint} usage constraint${issue.member === undefined ? "" : ` ${issue.member}`} 不适用于字段 ${issue.field}（${issue.kind}）`;
         case "invalidUsageConstraintValue":
-            return `命令 ${issue.command} 的 usage constraint 字段 ${issue.field} 必须使用 ${issue.expected} 离散值`;
+            return `命令 ${issue.command} 的 ${issue.constraint} 等值事实 ${issue.field}=${formatIssueValue(issue.actual)} 不属于可接受值 ${JSON.stringify(issue.expected)}`;
         case "contradictoryUsageConstraint":
-            return `命令 ${issue.command} 的 ${issue.constraint} usage constraint 内部矛盾：${issue.fields.join(", ")}`;
+            return `命令 ${issue.command} 的 ${issue.constraint} usage constraint${issue.member === undefined ? "" : ` ${issue.member}`} 内部矛盾：${issue.fields.join(", ")}`;
+    }
+}
+function formatIssueValue(value) {
+    if (typeof value === "number" && !Number.isFinite(value)) {
+        return String(value);
+    }
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        try {
+            return String(value);
+        }
+        catch {
+            return "<无法显示>";
+        }
     }
 }
 function formatSchemaTarget(target) {

package/node_modules/@ykdz/cli-contract/dist/contract-schema-compiler.js

@@ -1,4 +1,5 @@
 import { isSingleLineText } from "#/description";
+import { invalidFieldIdentityReason } from "#/field-identity";
 import { copyJsonObject, deepFreeze } from "#/json-value";
 export function compileContractSchema(schema, target, issues, description) {
     const initialIssueCount = issues.length;
@@ -114,7 +115,14 @@ export function compileInputFields(definitions, inputSchema, command, issues) {
                 : "string";
         return schemaPropertyAcceptsRawValue(schemaProperties[field], expected)
             ? []
-            : [{ field, expected }];
+            : [
+                {
+                    field,
+                    path: ["commands", command, "input", "properties", field],
+                    expected,
+                    received: schemaProperties[field] ?? null,
+                },
+            ];
     });
     if (incompatibleFields.length > 0) {
         issues.push({
@@ -126,8 +134,14 @@ export function compileInputFields(definitions, inputSchema, command, issues) {
         return [];
     }
     const fields = Object.entries(definitions).map(([key, field]) => {
-        if (!/^[a-z][A-Za-z0-9]*$/.test(key)) {
-            issues.push({ code: "invalidFieldIdentity", command, field: key });
+        const identityReason = invalidFieldIdentityReason(key);
+        if (identityReason !== undefined) {
+            issues.push({
+                code: "invalidFieldIdentity",
+                command,
+                field: key,
+                reason: identityReason,
+            });
         }
         const invalidKind = readInvalidFieldKind(field);
         if (invalidKind !== undefined) {