@ykdz/template 0.0.42 → 0.1.0-experimental.0

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

@@ -7,10 +7,10 @@ import { deepFreeze } from "#/json-value";
 import { isIssuedTextProjection } from "#/outcome-fact";
 import { createCompletionWireSchema, createDataWireSchema, createFailureWireSchema, createStreamHeaderWireSchema, createStreamRecordWireSchema, createStreamSuccessWireSchema, createUsageFailureWireSchema, } from "#/outcome-wire";
 import { compileStreamRecords, } from "#/stream-variant-compiler";
-export { createCompletionFact, createDataFact, createFailureFact, createStreamRecordFact, createStreamSuccessFact, isIssuedOutcomeFact, text, } from "#/outcome-fact";
+export { createCompletionFact, createDataFact, createFailureFact, createStreamRecordFact, createStreamSuccessFact, isIssuedOutcomeFact, TextValueError, text, } from "#/outcome-fact";
 const cliContractType = Symbol("CliContract.type");
-const executableCommandType = Symbol("ExecutableCommand.type");
 const helpCapabilities = new WeakSet();
+const invalidHelpFactWordingValues = new WeakMap();
 const outputCapabilities = new WeakSet();
 const versionCapabilities = new WeakSet();
 const compiledCliContracts = new WeakMap();
@@ -59,10 +59,14 @@ const definitionPropertyKeys = {
         positional: ["kind", "description"],
     },
     usage: {
-        requires: ["kind", "field", "requires"],
-        exclusive: ["kind", "fields"],
-        forbiddenCombination: ["kind", "values"],
-        value: ["field", "value"],
+        count: ["kind", "fields", "min", "max"],
+        when: ["kind", "all", "onMatch", "otherwise"],
+        effect: ["require", "forbid"],
+        forbiddenCombination: ["kind", "all"],
+        fact: {
+            present: ["kind", "field"],
+            equals: ["kind", "field", "value"],
+        },
     },
     success: {
         completion: ["kind", "text"],
@@ -77,6 +81,54 @@ const definitionPropertyKeys = {
         output: ["defaultFormat", "text", "compatibilityFlags"],
     },
 };
+/** 帮助事实槽位及其必需替换参数的唯一规格。 */
+export const helpTemplateSpecifications = {
+    commandPlaceholder: { placeholders: [] },
+    choices: { placeholders: ["choices"] },
+    default: { placeholders: ["value"] },
+    whenOnMatch: { placeholders: ["facts", "onMatch"] },
+    whenOtherwise: { placeholders: ["facts", "otherwise"] },
+    whenOnMatchOtherwise: { placeholders: ["facts", "onMatch", "otherwise"] },
+    require: { placeholders: ["fields"] },
+    forbid: { placeholders: ["fields"] },
+    present: { placeholders: ["field"] },
+    equals: { placeholders: ["field", "value"] },
+    forbiddenCombination: { placeholders: ["facts"] },
+    countExactly: { placeholders: ["fields", "count"] },
+    countAtLeast: { placeholders: ["fields", "min"] },
+    countAtMost: { placeholders: ["fields", "max"] },
+    countBetween: { placeholders: ["fields", "min", "max"] },
+};
+/** 选择 count 事实实际使用的帮助模板及其占位符值。 */
+export function countHelpFactForConstraint(constraint) {
+    const fields = constraint.fields.join(", ");
+    if (constraint.min === constraint.max) {
+        return {
+            slot: "countExactly",
+            values: { fields, count: String(constraint.min) },
+        };
+    }
+    if (constraint.max === constraint.fields.length) {
+        return {
+            slot: "countAtLeast",
+            values: { fields, min: String(constraint.min) },
+        };
+    }
+    if (constraint.min === 0) {
+        return {
+            slot: "countAtMost",
+            values: { fields, max: String(constraint.max) },
+        };
+    }
+    return {
+        slot: "countBetween",
+        values: {
+            fields,
+            min: String(constraint.min),
+            max: String(constraint.max),
+        },
+    };
+}
 export function isCompiledExecutable(command) {
     return command.kind === "rootCommand" || command.kind === "command";
 }
@@ -85,6 +137,9 @@ export function helpCapability(definition = {}) {
     if (definition.shortAlias !== undefined && definition.shortAlias !== "-h") {
         throw new TypeError("帮助短别名必须是 -h");
     }
+    const copiedWording = definition.wording === undefined
+        ? undefined
+        : copyHelpFactWording(definition.wording);
     // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- helpCapability 由本工厂签发并登记到 WeakSet，类型品牌不在运行时输出。
     const capability = Object.freeze({
         kind: "helpCapability",
@@ -95,11 +150,12 @@ export function helpCapability(definition = {}) {
         ...(definition.headings === undefined
             ? {}
             : { headings: copyHelpHeadings(definition.headings) }),
-        ...(definition.wording === undefined
-            ? {}
-            : { wording: copyHelpFactWording(definition.wording) }),
+        ...(copiedWording === undefined ? {} : { wording: copiedWording.wording }),
     });
     helpCapabilities.add(capability);
+    if (copiedWording !== undefined && copiedWording.invalidValues.size > 0) {
+        invalidHelpFactWordingValues.set(capability, copiedWording.invalidValues);
+    }
     return capability;
 }
 function copyHelpHeadings(value) {
@@ -122,51 +178,84 @@ function copyHelpHeadings(value) {
     }
     return Object.freeze(headings);
 }
-const helpTemplatePlaceholders = {
-    choices: ["choices"],
-    default: ["value"],
-    requires: ["field", "requires"],
-    exclusive: ["fields"],
-    forbiddenCombination: ["values"],
-};
 function copyHelpFactWording(value) {
     if (!isPlainRecord(value)) {
         throw new TypeError("帮助事实文案必须是对象");
     }
     const wording = {};
+    const invalidValues = new Map();
+    const unknownSlotIssues = [];
     for (const [slot, raw] of Object.entries(value)) {
-        if (slot === "commandPlaceholder") {
-            const label = copySingleLineText(raw, "命令组占位词");
-            if (label.trim().length === 0 ||
-                label.includes("<") ||
-                label.includes(">")) {
-                throw new TypeError("命令组占位词无效");
-            }
-            wording[slot] = label;
+        if (!isHelpTemplateSlot(slot)) {
+            unknownSlotIssues.push({
+                code: "unknownDefinitionProperty",
+                path: ["help", "wording", slot],
+            });
             continue;
         }
-        if (!isHelpTemplateSlot(slot)) {
-            throw new TypeError(`帮助事实文案包含未知槽位 ${slot}`);
+        if (typeof raw === "string") {
+            wording[slot] = raw;
         }
-        const template = copySingleLineText(raw, `帮助事实模板 ${slot}`);
-        const required = new Set(helpTemplatePlaceholders[slot]);
-        const placeholders = [
-            ...template.matchAll(/\{([A-Za-z][A-Za-z0-9]*)\}/g),
-        ].map((match) => match[1] ?? "");
-        const outside = template.replace(/\{[A-Za-z][A-Za-z0-9]*\}/g, "");
-        if (template.trim().length === 0 ||
-            outside.includes("{") ||
-            outside.includes("}") ||
-            placeholders.some((placeholder) => !required.has(placeholder)) ||
-            [...required].some((placeholder) => !placeholders.includes(placeholder))) {
-            throw new TypeError(`帮助事实模板 ${slot} 的占位符无效`);
+        else {
+            invalidValues.set(slot, raw);
+            wording[slot] = "";
         }
-        wording[slot] = template;
     }
-    return Object.freeze(wording);
+    const [firstUnknownSlotIssue, ...otherUnknownSlotIssues] = unknownSlotIssues;
+    if (firstUnknownSlotIssue !== undefined) {
+        const templateIssues = [];
+        collectHelpFactTemplateIssues(wording, templateIssues, invalidValues);
+        throw new ContractDefinitionError([
+            firstUnknownSlotIssue,
+            ...otherUnknownSlotIssues,
+            ...templateIssues,
+        ]);
+    }
+    return Object.freeze({
+        wording: Object.freeze(wording),
+        invalidValues,
+    });
 }
 function isHelpTemplateSlot(slot) {
-    return Object.hasOwn(helpTemplatePlaceholders, slot);
+    return Object.hasOwn(helpTemplateSpecifications, slot);
+}
+function collectHelpFactTemplateIssues(wording, issues, invalidValues = new Map()) {
+    for (const [slot, template] of Object.entries(wording)) {
+        if (!isHelpTemplateSlot(slot))
+            continue;
+        const path = ["help", "wording", slot];
+        let reason;
+        if (invalidValues.has(slot) || !isSingleLineText(template)) {
+            reason = "singleLine";
+        }
+        else if (template.trim().length === 0) {
+            reason = "empty";
+        }
+        else {
+            const allowed = new Set(helpTemplateSpecifications[slot].placeholders);
+            const placeholders = [
+                ...template.matchAll(/\{([A-Za-z][A-Za-z0-9]*)\}/g),
+            ].map((match) => match[1] ?? "");
+            const outside = template.replace(/\{[A-Za-z][A-Za-z0-9]*\}/g, "");
+            if (outside.includes("{") ||
+                outside.includes("}") ||
+                placeholders.some((placeholder) => !allowed.has(placeholder)) ||
+                [...allowed].some((placeholder) => !placeholders.includes(placeholder)) ||
+                (slot === "commandPlaceholder" &&
+                    (template.includes("<") || template.includes(">")))) {
+                reason = "placeholder";
+            }
+        }
+        if (reason !== undefined) {
+            issues.push({
+                code: "invalidHelpFactTemplate",
+                path,
+                slot,
+                received: invalidValues.has(slot) ? invalidValues.get(slot) : template,
+                reason,
+            });
+        }
+    }
 }
 /**
  * 在根契约显式装配版本提前请求，并自动覆盖整棵命令树。`value` 与可选
@@ -291,8 +380,10 @@ function assertKnownCapabilityOptions(definition, allowed, capability) {
 }
 /**
  * 定义一个闭合 CLI 契约。根级 help 与 output 能力在此处一次装配，并据此约束根命令的结果投影；
+ * 最终根装配会逐个检查整棵命令树的 completion、data/failure variant、stream record 与 stream success
+ * 是否满足 text 能力要求的同位 presenter；structured-only 禁止 presenter，`define.command()` 组合也在此检查。
  * 动态声明仍会在定义期报告 `ContractDefinitionError`，不能以它替代静态可判定声明的类型检查。
- * @see {@link https://github.com/YKDZ/cli-contract/tree/v0.2.1/packages/example | 端到端示例}
+ * @see {@link https://github.com/YKDZ/cli-contract/tree/v0.3.0/packages/example | 端到端示例}
  */
 export function defineCli() {
     // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 公共泛型定义接口由此运行时编译入口实现，类型参数只约束调用方。
@@ -302,7 +393,6 @@ export function defineCli() {
         value: (command) => (definition) => Object.freeze({
             [command]: Object.freeze({
                 ...definition,
-                [executableCommandType]: true,
             }),
         }),
     });
@@ -315,6 +405,9 @@ function compileCli(definition) {
     const helpWording = helpCapabilities.has(definition.help)
         ? definition.help.wording
         : undefined;
+    if (helpWording !== undefined) {
+        collectHelpFactTemplateIssues(helpWording, issues, invalidHelpFactWordingValues.get(definition.help));
+    }
     if (isTextOutputEnabled(definition.output)) {
         for (const slot of ["choices", "default"]) {
             if (helpWording?.[slot] === undefined) {
@@ -336,7 +429,7 @@ function compileCli(definition) {
                 ? []
                 : [definition.root];
     }
-    if (isHierarchy && issues.length > 0) {
+    if (isHierarchy && hasUnsafeCommandHierarchyIssue(issues)) {
         throw new ContractDefinitionError(
         // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- issues.length 已检查为正数，动态数组在此恢复非空元组类型。
         issues);
@@ -415,7 +508,44 @@ function compileCli(definition) {
         const usageConstraints = compileUsageConstraints(executable.usageConstraints === undefined
             ? []
             : executable.usageConstraints, fields, id, issues);
-        for (const slot of new Set(usageConstraints.map((constraint) => constraint.kind))) {
+        const requiredUsageTemplates = new Set();
+        for (const constraint of usageConstraints) {
+            if (constraint.kind === "count") {
+                requiredUsageTemplates.add(countHelpFactForConstraint(constraint).slot);
+            }
+            if (constraint.kind === "when") {
+                const hasOnMatch = (constraint.onMatch?.require?.length ?? 0) > 0 ||
+                    (constraint.onMatch?.forbid?.length ?? 0) > 0;
+                const hasOtherwise = (constraint.otherwise?.require?.length ?? 0) > 0 ||
+                    (constraint.otherwise?.forbid?.length ?? 0) > 0;
+                if (hasOnMatch && hasOtherwise) {
+                    requiredUsageTemplates.add("whenOnMatchOtherwise");
+                }
+                else if (hasOnMatch) {
+                    requiredUsageTemplates.add("whenOnMatch");
+                }
+                else {
+                    requiredUsageTemplates.add("whenOtherwise");
+                }
+                for (const fact of constraint.all) {
+                    requiredUsageTemplates.add(fact.kind);
+                }
+                if ((constraint.onMatch?.require?.length ?? 0) > 0 ||
+                    (constraint.otherwise?.require?.length ?? 0) > 0) {
+                    requiredUsageTemplates.add("require");
+                }
+                if ((constraint.onMatch?.forbid?.length ?? 0) > 0 ||
+                    (constraint.otherwise?.forbid?.length ?? 0) > 0) {
+                    requiredUsageTemplates.add("forbid");
+                }
+            }
+            if (constraint.kind === "forbiddenCombination") {
+                requiredUsageTemplates.add("forbiddenCombination");
+                for (const fact of constraint.all)
+                    requiredUsageTemplates.add(fact.kind);
+            }
+        }
+        for (const slot of requiredUsageTemplates) {
             if (helpWording?.[slot] === undefined) {
                 reportMissingHelpFactTemplate(issues, id, slot);
             }
@@ -527,7 +657,7 @@ function compileCli(definition) {
         controls,
     });
     const manifest = deepFreeze({
-        schemaVersion: "3",
+        schemaVersion: "4",
         root: definition.root,
         commands: manifestCommands,
         controls,
@@ -563,6 +693,12 @@ function reportMissingHelpFactTemplate(issues, command, slot) {
     }
     issues.push({ code: "missingHelpFactTemplate", command, slot });
 }
+function hasUnsafeCommandHierarchyIssue(issues) {
+    return issues.some((issue) => issue.code === "invalidCommandParent" ||
+        issue.code === "invalidRootCommandKind" ||
+        issue.code === "invalidCommandNodeKind" ||
+        issue.code === "commandHierarchyCycle");
+}
 function collectUnknownProperties(value, path, allowed, issues) {
     if (!isPlainRecord(value))
         return;
@@ -621,19 +757,39 @@ function collectUnknownDefinitionProperties(definition, issues) {
                 const constraintPath = [...path, "usageConstraints", String(index)];
                 if (!isPlainRecord(constraint))
                     return;
-                const allowed = constraint.kind === "requires"
-                    ? definitionPropertyKeys.usage.requires
-                    : constraint.kind === "exclusive"
-                        ? definitionPropertyKeys.usage.exclusive
+                const allowed = constraint.kind === "when"
+                    ? definitionPropertyKeys.usage.when
+                    : constraint.kind === "count"
+                        ? definitionPropertyKeys.usage.count
                         : constraint.kind === "forbiddenCombination"
                             ? definitionPropertyKeys.usage.forbiddenCombination
                             : undefined;
                 if (allowed === undefined)
                     return;
                 collectUnknownProperties(constraint, constraintPath, allowed, issues);
-                if (constraint.kind === "forbiddenCombination" &&
-                    Array.isArray(constraint.values)) {
-                    constraint.values.forEach((value, valueIndex) => collectUnknownProperties(value, [...constraintPath, "values", String(valueIndex)], definitionPropertyKeys.usage.value, issues));
+                if ((constraint.kind === "forbiddenCombination" ||
+                    constraint.kind === "when") &&
+                    Array.isArray(constraint.all)) {
+                    constraint.all.forEach((fact, factIndex) => {
+                        if (!isPlainRecord(fact))
+                            return;
+                        const allowedFact = fact.kind === "present"
+                            ? definitionPropertyKeys.usage.fact.present
+                            : fact.kind === "equals"
+                                ? definitionPropertyKeys.usage.fact.equals
+                                : undefined;
+                        if (allowedFact !== undefined) {
+                            collectUnknownProperties(fact, [...constraintPath, "all", String(factIndex)], allowedFact, issues);
+                        }
+                    });
+                }
+                if (constraint.kind === "when") {
+                    for (const branch of ["onMatch", "otherwise"]) {
+                        const effect = constraint[branch];
+                        if (!isPlainRecord(effect))
+                            continue;
+                        collectUnknownProperties(effect, [...constraintPath, branch], definitionPropertyKeys.usage.effect, issues);
+                    }
                 }
             });
         }
@@ -934,8 +1090,8 @@ function compileUsageConstraints(definitions, fields, command, issues) {
         }
         // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 定义条目已通过非 null 对象检查，此处读取动态属性。
         const candidate = definition;
-        if (candidate.kind !== "requires" &&
-            candidate.kind !== "exclusive" &&
+        if (candidate.kind !== "count" &&
+            candidate.kind !== "when" &&
             candidate.kind !== "forbiddenCombination") {
             issues.push({
                 code: "invalidUsageConstraint",
@@ -946,255 +1102,608 @@ function compileUsageConstraints(definitions, fields, command, issues) {
             });
             continue;
         }
-        if (candidate.kind === "requires") {
-            if (typeof candidate.field !== "string" ||
-                typeof candidate.requires !== "string") {
+        if (candidate.kind === "count") {
+            const compiledCount = compileCountUsageConstraint(candidate, fields, command, index, issues);
+            if (compiledCount !== undefined)
+                compiled.push(compiledCount);
+            continue;
+        }
+        if (candidate.kind === "when") {
+            const facts = compileUsageFacts(candidate.all, "when", index, command, fieldsByKey, issues);
+            const onMatch = compileUsageEffect(candidate.onMatch, "onMatch", index, command, fieldsByKey, issues);
+            const otherwise = compileUsageEffect(candidate.otherwise, "otherwise", index, command, fieldsByKey, issues);
+            const hasEffect = onMatch.hasEffect || otherwise.hasEffect;
+            if (onMatch.valid && otherwise.valid && !hasEffect) {
                 issues.push({
                     code: "invalidUsageConstraint",
                     command,
                     index,
                     aspect: "members",
-                    received: "requires",
+                    received: "when",
+                    member: "effects",
+                    path: ["commands", command, "usageConstraints", index],
+                    expected: "至少一个分支包含非空 require 或 forbid 字段组",
                 });
-                continue;
             }
-            const field = fieldsByKey.get(candidate.field);
-            const required = fieldsByKey.get(candidate.requires);
-            if (field === undefined)
-                issues.push({
-                    code: "unknownUsageConstraintField",
-                    command,
-                    constraint: "requires",
-                    index,
-                    member: "field",
-                    field: candidate.field,
-                });
-            if (required === undefined)
-                issues.push({
-                    code: "unknownUsageConstraintField",
-                    command,
-                    constraint: "requires",
-                    index,
-                    member: "requires",
-                    field: candidate.requires,
-                });
-            if (field !== undefined && required !== undefined) {
-                if (!isOptionalOption(field) || !isOptionalOption(required)) {
-                    for (const offendingField of [field, required])
-                        if (!isOptionalOption(offendingField))
-                            issues.push({
-                                code: "inapplicableUsageConstraintField",
-                                command,
-                                constraint: "requires",
-                                field: offendingField.key,
-                                kind: offendingField.kind,
-                            });
-                }
-                if (field.key === required.key)
-                    issues.push({
-                        code: "contradictoryUsageConstraint",
-                        command,
-                        constraint: "requires",
-                        fields: Object.freeze([field.key]),
-                    });
+            if (facts.valid && onMatch.valid && otherwise.valid && hasEffect) {
                 compiled.push(deepFreeze({
-                    kind: "requires",
-                    field: field.key,
-                    requires: required.key,
+                    kind: "when",
+                    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- compileUsageFacts仅在all非空且所有事实合法时返回valid。
+                    all: facts.facts,
+                    ...(onMatch.effect === undefined
+                        ? {}
+                        : { onMatch: onMatch.effect }),
+                    ...(otherwise.effect === undefined
+                        ? {}
+                        : { otherwise: otherwise.effect }),
                 }));
             }
             continue;
         }
-        if (candidate.kind === "exclusive") {
-            if (!Array.isArray(candidate.fields) ||
-                candidate.fields.length < 2 ||
-                !candidate.fields.every((field) => typeof field === "string")) {
+        if (candidate.kind === "forbiddenCombination") {
+            const facts = compileUsageFacts(candidate.all, "forbiddenCombination", index, command, fieldsByKey, issues);
+            if (facts.valid)
+                compiled.push(deepFreeze({
+                    kind: "forbiddenCombination",
+                    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- compileUsageFacts仅在all非空且所有事实合法时返回valid。
+                    all: facts.facts,
+                }));
+            continue;
+        }
+        issues.push({
+            code: "invalidUsageConstraint",
+            command,
+            index,
+            aspect: "kind",
+            received: null,
+        });
+    }
+    return deepFreeze(compiled);
+}
+function compileUsageFacts(definitions, constraint, index, command, fieldsByKey, issues) {
+    if (!Array.isArray(definitions) || definitions.length === 0) {
+        issues.push({
+            code: "invalidUsageConstraint",
+            command,
+            index,
+            aspect: "members",
+            received: constraint,
+            member: "all",
+            path: ["commands", command, "usageConstraints", index, "all"],
+            expected: "非空字段事实数组",
+        });
+        return { facts: [], valid: false };
+    }
+    const facts = [];
+    const factsForValidation = [];
+    let valid = true;
+    for (const [factIndex, candidateFact] of definitions.entries()) {
+        const path = [
+            "commands",
+            command,
+            "usageConstraints",
+            index,
+            "all",
+            factIndex,
+        ];
+        if (!isPlainRecord(candidateFact)) {
+            valid = false;
+            issues.push({
+                code: "invalidUsageConstraint",
+                command,
+                index,
+                aspect: "members",
+                received: candidateFact,
+                member: "all",
+                path,
+                expected: "present 或 equals 字段事实对象",
+            });
+            continue;
+        }
+        if (candidateFact.kind === "present" &&
+            typeof candidateFact.field === "string") {
+            const fact = { kind: "present", field: candidateFact.field };
+            facts.push(fact);
+            factsForValidation.push(fact);
+            continue;
+        }
+        if (candidateFact.kind === "equals" &&
+            typeof candidateFact.field === "string" &&
+            Object.hasOwn(candidateFact, "value")) {
+            if (typeof candidateFact.value === "boolean" ||
+                typeof candidateFact.value === "string") {
+                const fact = {
+                    kind: "equals",
+                    field: candidateFact.field,
+                    value: candidateFact.value,
+                };
+                facts.push(fact);
+                factsForValidation.push(fact);
+            }
+            else {
+                factsForValidation.push({
+                    kind: "invalidEqualsValue",
+                    field: candidateFact.field,
+                    value: candidateFact.value,
+                });
+            }
+            continue;
+        }
+        valid = false;
+        issues.push({
+            code: "invalidUsageConstraint",
+            command,
+            index,
+            aspect: "members",
+            received: candidateFact.kind,
+            member: "all",
+            path,
+            expected: "present{field} 或 equals{field,value}",
+        });
+    }
+    let invalidFactCount = 0;
+    for (const fact of factsForValidation) {
+        if (fact.kind === "invalidEqualsValue") {
+            const field = fieldsByKey.get(fact.field);
+            if (field === undefined) {
+                invalidFactCount += 1;
                 issues.push({
-                    code: "invalidUsageConstraint",
+                    code: "unknownUsageConstraintField",
                     command,
+                    constraint,
                     index,
-                    aspect: "members",
-                    received: "exclusive",
+                    member: "all.field",
+                    field: fact.field,
                 });
                 continue;
             }
-            const selected = candidate.fields.map((key) => fieldsByKey.get(key));
-            for (const [fieldIndex, field] of selected.entries()) {
-                if (field === undefined) {
-                    issues.push({
-                        code: "unknownUsageConstraintField",
-                        command,
-                        constraint: "exclusive",
-                        index,
-                        member: "fields",
-                        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- fields 已逐项检查为字符串，索引来自对应 selected 数组。
-                        field: candidate.fields[fieldIndex],
-                    });
-                }
-                else if (!isOptionalOption(field)) {
-                    issues.push({
-                        code: "inapplicableUsageConstraintField",
-                        command,
-                        constraint: "exclusive",
-                        field: field.key,
-                        kind: field.kind,
-                    });
-                }
-            }
-            const fieldsInConstraint = candidate.fields;
-            if (new Set(fieldsInConstraint).size !== fieldsInConstraint.length)
+            if (field.kind !== "flag" &&
+                field.kind !== "valueOption" &&
+                field.kind !== "positional") {
+                invalidFactCount += 1;
                 issues.push({
-                    code: "contradictoryUsageConstraint",
+                    code: "inapplicableUsageConstraintField",
                     command,
-                    constraint: "exclusive",
-                    fields: Object.freeze([...fieldsInConstraint]),
+                    constraint,
+                    index,
+                    member: "all.field",
+                    field: field.key,
+                    kind: field.kind,
                 });
-            if (selected.every((field) => field !== undefined))
-                compiled.push(deepFreeze({
-                    kind: "exclusive",
-                    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- fields 已检查至少两个字符串，冻结后保留非空元组长度。
-                    fields: Object.freeze([...fieldsInConstraint]),
-                }));
+                continue;
+            }
+            invalidFactCount += 1;
+            const expected = field.kind === "flag"
+                ? field.negatedLongOption === undefined
+                    ? true
+                    : "boolean"
+                : field.choices === undefined
+                    ? "string"
+                    : Object.freeze([...field.choices]);
+            issues.push({
+                code: "invalidUsageConstraintValue",
+                command,
+                constraint,
+                index,
+                member: "all.value",
+                field: field.key,
+                actual: fact.value,
+                expected,
+            });
             continue;
         }
-        if (candidate.kind === "forbiddenCombination") {
-            if (!Array.isArray(candidate.values) ||
-                candidate.values.length < 2 ||
-                !candidate.values.every((value) => typeof value === "object" &&
-                    value !== null &&
-                    typeof value.field === "string" &&
-                    (typeof value.value === "string" ||
-                        typeof value.value === "boolean"))) {
+        const field = fieldsByKey.get(fact.field);
+        if (field === undefined) {
+            invalidFactCount += 1;
+            issues.push({
+                code: "unknownUsageConstraintField",
+                command,
+                constraint,
+                index,
+                member: "all.field",
+                field: fact.field,
+            });
+            continue;
+        }
+        if (fact.kind === "equals" &&
+            field.kind !== "flag" &&
+            field.kind !== "valueOption" &&
+            field.kind !== "positional") {
+            invalidFactCount += 1;
+            issues.push({
+                code: "inapplicableUsageConstraintField",
+                command,
+                constraint,
+                index,
+                member: "all.field",
+                field: field.key,
+                kind: field.kind,
+            });
+            continue;
+        }
+        if (fact.kind !== "equals")
+            continue;
+        const expectedKind = field.kind === "flag" ? "boolean" : "string";
+        const hasExpectedType = expectedKind === "boolean"
+            ? typeof fact.value === "boolean"
+            : typeof fact.value === "string";
+        const onlyTrue = field.kind === "flag" &&
+            field.negatedLongOption === undefined &&
+            fact.value !== true;
+        const outsideChoices = typeof fact.value === "string" &&
+            field.choices !== undefined &&
+            !field.choices.includes(fact.value);
+        if (!hasExpectedType || onlyTrue || outsideChoices) {
+            invalidFactCount += 1;
+            issues.push({
+                code: "invalidUsageConstraintValue",
+                command,
+                constraint,
+                index,
+                member: "all.value",
+                field: field.key,
+                actual: fact.value,
+                expected: outsideChoices && field.choices !== undefined
+                    ? Object.freeze([...field.choices])
+                    : onlyTrue
+                        ? true
+                        : expectedKind === "boolean"
+                            ? "boolean"
+                            : "string",
+            });
+        }
+    }
+    const conflictingFields = new Set();
+    for (const [factIndex, fact] of facts.entries()) {
+        if (fact.kind !== "equals")
+            continue;
+        if (facts.some((other, otherIndex) => otherIndex !== factIndex &&
+            other.kind === "equals" &&
+            other.field === fact.field &&
+            other.value !== fact.value)) {
+            conflictingFields.add(fact.field);
+        }
+    }
+    if (conflictingFields.size > 0) {
+        issues.push({
+            code: "contradictoryUsageConstraint",
+            command,
+            constraint,
+            index,
+            member: "all",
+            fields: Object.freeze([...conflictingFields]),
+        });
+    }
+    valid &&=
+        invalidFactCount === 0 &&
+            conflictingFields.size === 0 &&
+            facts.length === definitions.length;
+    return { facts: deepFreeze(facts), valid };
+}
+function compileUsageEffect(definition, branch, index, command, fieldsByKey, issues) {
+    if (definition === undefined)
+        return { valid: true, hasEffect: false };
+    const path = ["commands", command, "usageConstraints", index, branch];
+    if (!isPlainRecord(definition)) {
+        issues.push({
+            code: "invalidUsageConstraint",
+            command,
+            index,
+            aspect: "members",
+            received: definition,
+            member: branch,
+            path,
+            expected: "只包含 require 和 forbid 字段数组的效果对象",
+        });
+        return { valid: false, hasEffect: false };
+    }
+    let valid = true;
+    let hasEffect = false;
+    const compiled = {};
+    for (const member of ["require", "forbid"]) {
+        if (!Object.hasOwn(definition, member))
+            continue;
+        const values = definition[member];
+        if (!Array.isArray(values)) {
+            valid = false;
+            issues.push({
+                code: "invalidUsageConstraint",
+                command,
+                index,
+                aspect: "members",
+                received: values,
+                member: `${branch}.${member}`,
+                path: [...path, member],
+                expected: "字段名称数组",
+            });
+            continue;
+        }
+        if (values.length > 0)
+            hasEffect = true;
+        const compiledFields = [];
+        for (const [fieldIndex, field] of values.entries()) {
+            if (typeof field !== "string") {
+                valid = false;
                 issues.push({
                     code: "invalidUsageConstraint",
                     command,
                     index,
                     aspect: "members",
-                    received: "forbiddenCombination",
+                    received: field,
+                    member: `${branch}.${member}`,
+                    path: [...path, member, fieldIndex],
+                    expected: "字段名称字符串",
                 });
                 continue;
             }
-            const values = [];
-            for (const value of candidate.values) {
-                // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- values 已逐项检查 field 和 value 的运行时类型。
-                const discreteValue = value;
-                const field = fieldsByKey.get(discreteValue.field);
-                if (field === undefined) {
-                    issues.push({
-                        code: "unknownUsageConstraintField",
-                        command,
-                        constraint: "forbiddenCombination",
-                        index,
-                        member: "values.field",
-                        field: discreteValue.field,
-                    });
-                    continue;
-                }
-                if (field.kind !== "flag" && field.kind !== "valueOption") {
-                    issues.push({
-                        code: "inapplicableUsageConstraintField",
-                        command,
-                        constraint: "forbiddenCombination",
-                        field: field.key,
-                        kind: field.kind,
-                    });
-                    continue;
-                }
-                if ((field.kind === "flag" && typeof discreteValue.value !== "boolean") ||
-                    (field.kind === "valueOption" &&
-                        typeof discreteValue.value !== "string")) {
-                    issues.push({
-                        code: "invalidUsageConstraintValue",
-                        command,
-                        field: field.key,
-                        expected: field.kind === "flag" ? "boolean" : "string",
-                    });
-                    continue;
-                }
-                values.push({ field: field.key, value: discreteValue.value });
-            }
-            const duplicateValueField = values.some((value, valueIndex) => values.findIndex(({ field }) => field === value.field) !== valueIndex);
-            if (duplicateValueField)
+            if (!fieldsByKey.has(field)) {
+                valid = false;
                 issues.push({
-                    code: "contradictoryUsageConstraint",
+                    code: "unknownUsageConstraintField",
                     command,
-                    constraint: "forbiddenCombination",
-                    fields: Object.freeze(values.map(({ field }) => field)),
+                    constraint: "when",
+                    index,
+                    member: `${branch}.${member}`,
+                    field,
                 });
-            if (values.length === candidate.values.length)
-                compiled.push(deepFreeze({
-                    kind: "forbiddenCombination",
-                    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 源 values 至少两项，且映射长度相等才进入此分支。
-                    values: Object.freeze(values),
-                }));
-            continue;
+                continue;
+            }
+            compiledFields.push(field);
         }
+        compiled[member] = compiledFields;
+    }
+    const forbidden = new Set(compiled.forbid ?? []);
+    const conflictingFields = [...new Set(compiled.require ?? [])].filter((field) => forbidden.has(field));
+    if (conflictingFields.length > 0) {
+        valid = false;
         issues.push({
-            code: "invalidUsageConstraint",
+            code: "contradictoryUsageConstraint",
             command,
+            constraint: "when",
             index,
-            aspect: "kind",
-            received: null,
+            member: branch,
+            fields: Object.freeze(conflictingFields),
         });
     }
-    for (const constraint of compiled) {
-        if (constraint.kind !== "requires")
-            continue;
-        if (constraint.field === constraint.requires)
-            continue;
-        const exclusive = compiled.find((candidate) => candidate.kind === "exclusive" &&
-            candidate.fields.includes(constraint.field) &&
-            candidate.fields.includes(constraint.requires));
-        if (exclusive !== undefined)
+    return {
+        effect: deepFreeze(compiled),
+        valid,
+        hasEffect,
+    };
+}
+function compileCountUsageConstraint(candidate, fields, command, index, issues) {
+    const fieldsCandidate = candidate.fields;
+    const hasFieldArray = Array.isArray(fieldsCandidate);
+    const rawFieldNames = hasFieldArray
+        ? fieldsCandidate
+        : [];
+    let valid = true;
+    if (!hasFieldArray || rawFieldNames.length === 0) {
+        issues.push({
+            code: "invalidCountConstraint",
+            command,
+            index,
+            member: "fields",
+            reason: "nonEmpty",
+        });
+        valid = false;
+    }
+    const stringFieldNames = [];
+    let hasInvalidFieldName = false;
+    for (const field of rawFieldNames) {
+        if (typeof field === "string") {
+            stringFieldNames.push(field);
+        }
+        else {
+            hasInvalidFieldName = true;
+        }
+    }
+    if (hasInvalidFieldName) {
+        issues.push({
+            code: "invalidCountConstraint",
+            command,
+            index,
+            member: "fields",
+            reason: "fieldName",
+        });
+        valid = false;
+    }
+    const fieldsByKey = new Set(fields.map(({ key }) => key));
+    for (const field of stringFieldNames) {
+        if (!fieldsByKey.has(field)) {
             issues.push({
-                code: "contradictoryUsageConstraint",
+                code: "unknownUsageConstraintField",
                 command,
-                constraint: "requires",
-                fields: Object.freeze([constraint.field, constraint.requires]),
+                constraint: "count",
+                index,
+                member: "fields",
+                field,
             });
+            valid = false;
+        }
     }
-    return deepFreeze(compiled);
+    const duplicateFields = stringFieldNames.filter((field, fieldIndex) => stringFieldNames.indexOf(field) !== fieldIndex);
+    if (duplicateFields.length > 0) {
+        issues.push({
+            code: "invalidCountConstraint",
+            command,
+            index,
+            member: "fields",
+            reason: "duplicateFields",
+            fields: Object.freeze([...new Set(duplicateFields)]),
+        });
+        valid = false;
+    }
+    const hasMin = Object.hasOwn(candidate, "min");
+    const hasMax = Object.hasOwn(candidate, "max");
+    if (!hasMin && !hasMax) {
+        issues.push({
+            code: "invalidCountConstraint",
+            command,
+            index,
+            member: "min",
+            reason: "endpointRequired",
+        });
+        valid = false;
+    }
+    const min = hasMin ? candidate.min : 0;
+    const fieldCount = hasFieldArray ? rawFieldNames.length : undefined;
+    const normalizedMin = normalizeCountEndpoint(min, "min", fieldCount, command, index, issues);
+    const normalizedMax = hasMax
+        ? normalizeCountEndpoint(candidate.max, "max", fieldCount, command, index, issues)
+        : fieldCount === undefined
+            ? undefined
+            : { value: fieldCount, valid: true };
+    if (!normalizedMin.valid || normalizedMax?.valid === false)
+        valid = false;
+    if (normalizedMin.value !== undefined &&
+        normalizedMax?.value !== undefined &&
+        normalizedMin.value > normalizedMax.value) {
+        issues.push({
+            code: "invalidCountConstraint",
+            command,
+            index,
+            member: "min",
+            reason: "ordered",
+            actual: normalizedMin.value,
+            maximum: normalizedMax.value,
+        });
+        valid = false;
+    }
+    if (!valid ||
+        normalizedMin.value === undefined ||
+        normalizedMax?.value === undefined) {
+        return undefined;
+    }
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- fields 已检查非空且每项都是字符串。
+    const nonEmptyFields = Object.freeze([...stringFieldNames]);
+    return deepFreeze({
+        kind: "count",
+        fields: nonEmptyFields,
+        min: normalizedMin.value,
+        max: normalizedMax.value,
+    });
 }
-function isOptionalOption(field) {
-    return (!field.required &&
-        field.kind !== "positional" &&
-        field.kind !== "variadicPositional");
+function normalizeCountEndpoint(value, member, fieldCount, command, index, issues) {
+    if (typeof value !== "number") {
+        issues.push({
+            code: "invalidCountConstraint",
+            command,
+            index,
+            member,
+            reason: "integer",
+        });
+        return { value: undefined, valid: false };
+    }
+    if (value < 0) {
+        issues.push({
+            code: "invalidCountConstraint",
+            command,
+            index,
+            member,
+            reason: "nonNegative",
+            actual: value,
+        });
+        return {
+            value: Number.isFinite(value) ? value : undefined,
+            valid: false,
+        };
+    }
+    if (!Number.isFinite(value)) {
+        issues.push({
+            code: "invalidCountConstraint",
+            command,
+            index,
+            member,
+            reason: "finite",
+            actual: value,
+        });
+        return { value: undefined, valid: false };
+    }
+    if (!Number.isInteger(value)) {
+        issues.push({
+            code: "invalidCountConstraint",
+            command,
+            index,
+            member,
+            reason: "integer",
+            actual: value,
+        });
+        return { value, valid: false };
+    }
+    if (fieldCount !== undefined && value > fieldCount) {
+        issues.push({
+            code: "invalidCountConstraint",
+            command,
+            index,
+            member,
+            reason: "fieldCount",
+            actual: value,
+            maximum: fieldCount,
+        });
+        return { value, valid: false };
+    }
+    return { value, valid: true };
 }
 function projectUsageConstraints(schema, constraints) {
-    if (constraints.length === 0)
+    const projectedConstraints = constraints.filter((constraint) => constraint.kind !== "count" ||
+        constraint.min !== 0 ||
+        constraint.max !== constraint.fields.length);
+    if (projectedConstraints.length === 0)
         return schema;
     const constraintSchemas = [];
-    for (const constraint of constraints) {
-        if (constraint.kind === "requires") {
-            constraintSchemas.push(Object.fromEntries([
-                ["if", { required: [constraint.field] }],
-                // oxlint-disable-next-line unicorn/no-thenable -- Draft 2020-12 固定关键字。
-                ["then", { required: [constraint.requires] }],
-            ]));
+    const countDefinitions = isPlainRecord(schema.inputSchema.$defs)
+        ? // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- inputSchema 的 $defs 是已验证 JSON Schema 对象。
+            { ...schema.inputSchema.$defs }
+        : {};
+    let countConstraintIndex = 0;
+    for (const constraint of projectedConstraints) {
+        if (constraint.kind === "count") {
+            constraintSchemas.push(projectCountConstraint(constraint, countDefinitions, countConstraintIndex));
+            countConstraintIndex += 1;
             continue;
         }
-        if (constraint.kind === "exclusive") {
-            constraintSchemas.push({
-                not: {
-                    anyOf: constraint.fields.flatMap((field, index) => constraint.fields.slice(index + 1).map((other) => ({
-                        required: [field, other],
-                    }))),
-                },
-            });
+        if (constraint.kind === "when") {
+            const condition = {
+                allOf: constraint.all.map((fact) => fact.kind === "present"
+                    ? { required: [fact.field] }
+                    : {
+                        properties: { [fact.field]: { const: fact.value } },
+                        required: [fact.field],
+                    }),
+            };
+            const effects = {};
+            const onMatch = constraint.onMatch;
+            if (onMatch !== undefined &&
+                ((onMatch.require?.length ?? 0) > 0 ||
+                    (onMatch.forbid?.length ?? 0) > 0)) {
+                // oxlint-disable-next-line unicorn/no-thenable -- Draft 2020-12 固定关键字。
+                effects.then = usageEffectSchema(onMatch);
+            }
+            const otherwise = constraint.otherwise;
+            if (otherwise !== undefined &&
+                ((otherwise.require?.length ?? 0) > 0 ||
+                    (otherwise.forbid?.length ?? 0) > 0)) {
+                effects.else = usageEffectSchema(otherwise);
+            }
+            constraintSchemas.push({ if: condition, ...effects });
             continue;
         }
         constraintSchemas.push({
             not: {
-                allOf: constraint.values.map(({ field, value }) => ({
-                    properties: { [field]: { const: value } },
-                    required: [field],
-                })),
+                allOf: constraint.all.map((fact) => fact.kind === "present"
+                    ? { required: [fact.field] }
+                    : {
+                        properties: { [fact.field]: { const: fact.value } },
+                        required: [fact.field],
+                    }),
             },
         });
     }
     return deepFreeze({
         inputSchema: {
             ...schema.inputSchema,
+            ...(countConstraintIndex === 0 ? {} : { $defs: countDefinitions }),
             allOf: [
                 ...(Array.isArray(schema.inputSchema.allOf)
                     ? schema.inputSchema.allOf
@@ -1205,6 +1714,70 @@ function projectUsageConstraints(schema, constraints) {
         outputSchema: schema.outputSchema,
     });
 }
+function projectCountConstraint(constraint, definitions, index) {
+    const prefix = uniqueCountDefinitionPrefix(definitions, index, constraint.fields.length);
+    const fieldCount = constraint.fields.length;
+    for (let position = 0; position <= fieldCount; position += 1) {
+        for (let present = 0; present <= position; present += 1) {
+            const definitionName = countStateDefinitionName(prefix, position, present);
+            const remaining = fieldCount - position;
+            if (present > constraint.max || present + remaining < constraint.min) {
+                definitions[definitionName] = { not: {} };
+                continue;
+            }
+            if (position === fieldCount) {
+                definitions[definitionName] = {};
+                continue;
+            }
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- position < fieldCount，索引来自已校验的非空元组。
+            const field = constraint.fields[position];
+            definitions[definitionName] = {
+                if: { required: [field] },
+                // oxlint-disable-next-line unicorn/no-thenable -- Draft 2020-12 固定关键字。
+                then: {
+                    $ref: `#/$defs/${countStateDefinitionName(prefix, position + 1, present + 1)}`,
+                },
+                else: {
+                    $ref: `#/$defs/${countStateDefinitionName(prefix, position + 1, present)}`,
+                },
+            };
+        }
+    }
+    return {
+        $ref: `#/$defs/${countStateDefinitionName(prefix, 0, 0)}`,
+    };
+}
+function uniqueCountDefinitionPrefix(definitions, index, fieldCount) {
+    let prefix = `__cliContract_count_${index}`;
+    while (Array.from({ length: fieldCount + 1 }, (_, position) => Array.from({ length: position + 1 }, (_unused, present) => countStateDefinitionName(prefix, position, present)))
+        .flat()
+        .some((name) => Object.hasOwn(definitions, name))) {
+        prefix += "_";
+    }
+    return prefix;
+}
+function countStateDefinitionName(prefix, position, present) {
+    return `${prefix}_state_${position}_${present}`;
+}
+function usageEffectSchema(effect) {
+    const required = effect.require ?? [];
+    const forbidden = effect.forbid ?? [];
+    const hasRepeatedRequiredField = new Set(required).size < required.length;
+    return {
+        ...(required.length === 0
+            ? {}
+            : hasRepeatedRequiredField
+                ? { allOf: required.map((field) => ({ required: [field] })) }
+                : { required: [...required] }),
+        ...(forbidden.length === 0
+            ? {}
+            : {
+                not: {
+                    anyOf: forbidden.map((field) => ({ required: [field] })),
+                },
+            }),
+    };
+}
 function compileFailures(command, failures, issues) {
     const compiled = compileAtomicVariants(command, "failure", failures, 1, createFailureWireSchema, issues);
     return {