@ykdz/template 0.0.37 → 0.0.40

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

@@ -0,0 +1,524 @@
+import { getCompiledCli, isCompiledExecutable, } from "#/cli-contract";
+import { ContractExecutionError } from "#/contract-execution-error";
+const cliInvocationType = Symbol("CliInvocation.type");
+const invocationContracts = new WeakMap();
+/**
+ * 将宿主提供的参数 token 同步、无副作用地解析为同一契约的调用事实。
+ * 参数从命令路径或字段开始，不包含 Node 可执行文件和脚本路径；来源与 shell 拆词由宿主负责。
+ *
+ * 解析器检查调用语法与用法约束，保留帮助、版本和用法失败等闭合分支；
+ * 已解析的 raw input 尚未经过契约模式验证。它不读取进程或环境，不执行 handler，也不写输出。
+ * 将返回值交给 {@link executeCli}，由执行内核完成后续验证与投影。
+ */
+export function parseCliInvocation(cliContract, argv) {
+    const compiled = getCompiledCli(cliContract);
+    const input = {};
+    const occurrencesByField = new Map();
+    const valueOccurrencesByField = new Map();
+    const outputOccurrences = [];
+    let selected = compiled.commands[compiled.root];
+    if (selected === undefined)
+        throw new ContractExecutionError([{ code: "invalidCliContract" }]);
+    let position = 0;
+    while (!isCompiledExecutable(selected)) {
+        const token = argv[position];
+        if (token === undefined) {
+            return bindInvocation(cliContract, {
+                kind: "help",
+                // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 命令 id 来自当前 Contract 编译结果，泛型身份在此恢复。
+                command: selected.id,
+            });
+        }
+        const eager = detectEagerControl(compiled, token);
+        if (eager !== undefined) {
+            return bindInvocation(cliContract, {
+                kind: eager,
+                // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 命令 id 来自当前 Contract 编译结果，泛型身份在此恢复。
+                command: selected.id,
+            });
+        }
+        const output = consumeOutputControl(compiled, argv, position, outputOccurrences);
+        if (output.kind === "issue") {
+            return usageFailure(cliContract, 
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 命令 id 来自当前 Contract 编译结果，泛型身份在此恢复。
+            selected.id, 
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- usage 与同一已编译命令一同产生，泛型身份在此恢复。
+            selected.usage, output.issue);
+        }
+        if (output.kind === "consumed") {
+            position = output.nextPosition;
+            continue;
+        }
+        if (token.startsWith("-") && token !== "-") {
+            const option = consumeOption(compiled, [], argv, position, input, occurrencesByField, valueOccurrencesByField);
+            if (option.kind === "issue") {
+                return usageFailure(cliContract, 
+                // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 命令 id 来自当前 Contract 编译结果，泛型身份在此恢复。
+                selected.id, 
+                // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- usage 与同一已编译命令一同产生，泛型身份在此恢复。
+                selected.usage, option.issue);
+            }
+            position = option.nextPosition;
+            continue;
+        }
+        const child = Object.values(compiled.commands).find((candidate) => candidate.parent === selected?.id &&
+            (candidate.name === token || candidate.aliases.includes(token)));
+        if (child === undefined) {
+            const selectedId = selected.id;
+            const issue = {
+                code: "unknownCommand",
+                position,
+                command: token,
+                ...suggestionProperty("suggestedCommand", selectUniqueNeighbor(token, Object.values(compiled.commands)
+                    .filter((candidate) => candidate.parent === selectedId)
+                    .flatMap((candidate) => [candidate.name, ...candidate.aliases]))),
+            };
+            return usageFailure(cliContract, 
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 命令 id 来自当前 Contract 编译结果，泛型身份在此恢复。
+            selected.id, 
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- usage 与同一已编译命令一同产生，泛型身份在此恢复。
+            selected.usage, issue);
+        }
+        selected = child;
+        position += 1;
+    }
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 命令 id 来自当前 Contract 编译结果，泛型身份在此恢复。
+    const command = selected.id;
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- usage 与同一已编译命令一同产生，泛型身份在此恢复。
+    const usage = selected.usage;
+    const fields = selected.fields;
+    const positionals = fields.filter((field) => field.kind === "positional" || field.kind === "variadicPositional");
+    let positionalIndex = 0;
+    let optionsEnabled = true;
+    for (; position < argv.length; position += 1) {
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- position 受 argv.length 限制，argv 的公共类型保证元素为字符串。
+        const token = argv[position];
+        if (optionsEnabled && token === "--") {
+            optionsEnabled = false;
+            continue;
+        }
+        const eager = optionsEnabled
+            ? detectEagerControl(compiled, token)
+            : undefined;
+        if (eager !== undefined) {
+            return bindInvocation(cliContract, {
+                kind: eager,
+                command,
+            });
+        }
+        if (optionsEnabled) {
+            const output = consumeOutputControl(compiled, argv, position, outputOccurrences);
+            if (output.kind === "issue") {
+                return usageFailure(cliContract, command, usage, output.issue);
+            }
+            if (output.kind === "consumed") {
+                position = output.nextPosition - 1;
+                continue;
+            }
+        }
+        if (optionsEnabled && token.startsWith("-") && token !== "-") {
+            const option = consumeOption(compiled, fields, argv, position, input, occurrencesByField, valueOccurrencesByField);
+            if (option.kind === "issue") {
+                return usageFailure(cliContract, command, usage, option.issue);
+            }
+            position = option.nextPosition - 1;
+            continue;
+        }
+        const positional = positionals[positionalIndex];
+        if (positional === undefined) {
+            return unexpectedPositional(cliContract, command, usage, position, token);
+        }
+        if (positional.kind === "variadicPositional") {
+            const values = input[positional.key];
+            input[positional.key] = Array.isArray(values)
+                ? [...values, token]
+                : [token];
+        }
+        else {
+            input[positional.key] = token;
+            positionalIndex += 1;
+        }
+        addFieldValueOccurrence(valueOccurrencesByField, positional.key, position, token);
+    }
+    const structuralIssues = collectStructuralIssues(fields, input, occurrencesByField, valueOccurrencesByField, selected.usageConstraints);
+    if (structuralIssues.length > 0) {
+        return usageFailureFromIssues(cliContract, command, usage, 
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- structuralIssues.length 已检查为正数。
+        structuralIssues);
+    }
+    return bindInvocation(cliContract, {
+        kind: "parsed",
+        command,
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- raw input 由此 Contract 的字段语法解析并冻结，泛型形状在此恢复。
+        input: freezeRawInput(input),
+        outputFormat: outputOccurrences[0]?.format ??
+            compiled.contract.grammar.controls.output.defaultFormat,
+    });
+}
+function detectEagerControl(compiled, token) {
+    const help = compiled.contract.grammar.controls.help;
+    if (token === help.longOption || token === help.shortAlias) {
+        return "help";
+    }
+    const version = compiled.contract.grammar.controls.version;
+    return version !== undefined &&
+        (token === version.longOption || token === version.shortAlias)
+        ? "version"
+        : undefined;
+}
+function consumeOutputControl(compiled, argv, position, occurrences) {
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 调用点均传入当前位置的 argv token，公共类型保证字符串。
+    const token = argv[position];
+    const option = readOptionToken(token);
+    const output = compiled.contract.grammar.controls.output;
+    if (output.selector === option.spelling) {
+        const nextToken = argv[position + 1];
+        if (option.value === undefined &&
+            nextToken !== undefined &&
+            detectEagerControl(compiled, nextToken) !== undefined) {
+            return { kind: "consumed", nextPosition: position + 1 };
+        }
+        const value = option.value ?? argv[position + 1];
+        if (value === undefined ||
+            !isOutputFormat(value) ||
+            !output.formats.includes(value)) {
+            return {
+                kind: "issue",
+                issue: {
+                    code: "invalidOutputFormat",
+                    position,
+                    option: option.spelling,
+                    received: value ?? null,
+                },
+            };
+        }
+        const nextPosition = option.value === undefined ? position + 2 : position + 1;
+        return selectOutputFormat(occurrences, {
+            position,
+            option: option.spelling,
+            format: value,
+        }, nextPosition);
+    }
+    const format = output.compatibilityFlags?.[option.spelling];
+    if (format === undefined)
+        return { kind: "notControl" };
+    if (option.value !== undefined) {
+        return {
+            kind: "issue",
+            issue: {
+                code: "invalidOutputFormat",
+                position,
+                option: option.spelling,
+                received: option.value,
+            },
+        };
+    }
+    return selectOutputFormat(occurrences, { position, option: option.spelling, format }, position + 1);
+}
+function isOutputFormat(value) {
+    return value === "structured" || value === "text";
+}
+function selectOutputFormat(occurrences, occurrence, nextPosition) {
+    occurrences.push(occurrence);
+    if (occurrences.length === 1)
+        return { kind: "consumed", nextPosition };
+    return {
+        kind: "issue",
+        issue: {
+            code: "conflictingOutputFormat",
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 此前已排除单次出现，冲突证据至少有两项。
+            occurrences: Object.freeze([
+                ...occurrences,
+            ]),
+        },
+    };
+}
+function consumeOption(compiled, fields, argv, position, input, occurrencesByField, valueOccurrencesByField) {
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 调用点均传入当前位置的 argv token，公共类型保证字符串。
+    const token = argv[position];
+    const option = readOptionToken(token);
+    const field = fields.find((candidate) => candidate.kind !== "positional" &&
+        candidate.kind !== "variadicPositional" &&
+        (candidate.longOption === option.spelling ||
+            candidate.shortAlias === option.spelling ||
+            (candidate.kind === "flag" &&
+                candidate.negatedLongOption === option.spelling)));
+    if (field === undefined) {
+        return {
+            kind: "issue",
+            issue: {
+                code: "unknownOption",
+                position,
+                option: token,
+                ...suggestionProperty("suggestedOption", token.startsWith("--")
+                    ? selectUniqueNeighbor(option.spelling, longOptionsInScope(compiled, fields))
+                    : undefined),
+            },
+        };
+    }
+    if (field.kind === "flag") {
+        if (option.value !== undefined) {
+            return {
+                kind: "issue",
+                issue: {
+                    code: "unexpectedOptionValue",
+                    position,
+                    field: field.key,
+                    option: option.spelling,
+                    value: option.value,
+                },
+            };
+        }
+        const polarity = option.spelling === field.negatedLongOption ? "negative" : "positive";
+        input[field.key] = polarity === "positive";
+        addOptionOccurrence(occurrencesByField, field.key, position, option.spelling, polarity);
+        return { kind: "consumed", nextPosition: position + 1 };
+    }
+    if (option.value !== undefined) {
+        addOptionValue(input, field.key, option.value, field.kind);
+        addFieldValueOccurrence(valueOccurrencesByField, field.key, position, option.value);
+        addOptionOccurrence(occurrencesByField, field.key, position, option.spelling, "value");
+        return { kind: "consumed", nextPosition: position + 1 };
+    }
+    const value = argv[position + 1];
+    if (value !== undefined &&
+        detectEagerControl(compiled, value) !== undefined) {
+        return { kind: "consumed", nextPosition: position + 1 };
+    }
+    if (value === undefined || (value.startsWith("-") && value !== "-")) {
+        return {
+            kind: "issue",
+            issue: {
+                code: "missingOptionValue",
+                position,
+                field: field.key,
+                option: option.spelling,
+            },
+        };
+    }
+    addOptionValue(input, field.key, value, field.kind);
+    addFieldValueOccurrence(valueOccurrencesByField, field.key, position + 1, value);
+    addOptionOccurrence(occurrencesByField, field.key, position, option.spelling, "value");
+    return { kind: "consumed", nextPosition: position + 2 };
+}
+function addFieldValueOccurrence(valueOccurrencesByField, field, position, value) {
+    const occurrences = valueOccurrencesByField.get(field) ?? [];
+    occurrences.push({ position, value });
+    valueOccurrencesByField.set(field, occurrences);
+}
+function addOptionOccurrence(occurrencesByField, field, position, option, polarity) {
+    const occurrences = occurrencesByField.get(field) ?? [];
+    occurrences.push({ position, option, polarity });
+    occurrencesByField.set(field, occurrences);
+}
+function collectStructuralIssues(fields, input, occurrencesByField, valueOccurrencesByField, usageConstraints) {
+    const fieldIssues = fields.flatMap((field) => {
+        const issues = [];
+        if (field.required && !Object.hasOwn(input, field.key)) {
+            issues.push({ code: "missingRequiredField", field: field.key });
+        }
+        const occurrences = occurrencesByField.get(field.key) ?? [];
+        if (field.kind !== "positional" &&
+            field.kind !== "variadicPositional" &&
+            field.kind !== "repeatableOption") {
+            if (field.kind === "flag") {
+                const positiveOccurrences = occurrences.filter(({ polarity }) => polarity === "positive");
+                const negativeOccurrences = occurrences.filter(({ polarity }) => polarity === "negative");
+                if (positiveOccurrences.length > 0 && negativeOccurrences.length > 0) {
+                    issues.push({
+                        code: "conflictingFlag",
+                        field: field.key,
+                        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 正负出现次数均已检查为正数。
+                        positiveOccurrences: freezeOccurrenceEvidence(positiveOccurrences),
+                        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 正负出现次数均已检查为正数。
+                        negativeOccurrences: freezeOccurrenceEvidence(negativeOccurrences),
+                    });
+                    return issues;
+                }
+            }
+            if (occurrences.length > 1) {
+                issues.push({
+                    code: "repeatedOption",
+                    field: field.key,
+                    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- occurrences.length 已检查大于一。
+                    occurrences: freezeOccurrenceEvidence(occurrences),
+                });
+            }
+        }
+        if (field.choices !== undefined) {
+            for (const occurrence of valueOccurrencesByField.get(field.key) ?? []) {
+                if (!field.choices.includes(occurrence.value)) {
+                    issues.push({
+                        code: "invalidFieldChoice",
+                        position: occurrence.position,
+                        field: field.key,
+                        value: occurrence.value,
+                        choices: Object.freeze([...field.choices]),
+                    });
+                }
+            }
+        }
+        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 === "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),
+                    },
+                ]
+                : [];
+        }
+        return constraint.values.every(({ field, value }) => input[field] === value)
+            ? [
+                {
+                    code: "forbiddenUsageCombination",
+                    values: constraint.values,
+                },
+            ]
+            : [];
+    });
+    return [...fieldIssues, ...constraintIssues];
+}
+function freezeOccurrenceEvidence(occurrences) {
+    return Object.freeze(occurrences.map(({ position, option }) => Object.freeze({ position, option })));
+}
+function freezeRawInput(input) {
+    for (const value of Object.values(input)) {
+        if (Array.isArray(value))
+            Object.freeze(value);
+    }
+    return Object.freeze(input);
+}
+function addOptionValue(input, field, value, kind) {
+    if (kind === "valueOption") {
+        input[field] = value;
+        return;
+    }
+    const values = input[field];
+    input[field] = Array.isArray(values) ? [...values, value] : [value];
+}
+function readOptionToken(token) {
+    if (!token.startsWith("--"))
+        return { spelling: token };
+    const equals = token.indexOf("=");
+    return equals === -1
+        ? { spelling: token }
+        : { spelling: token.slice(0, equals), value: token.slice(equals + 1) };
+}
+function longOptionsInScope(compiled, fields) {
+    return [
+        ...fields.flatMap((field) => field.kind === "positional" || field.kind === "variadicPositional"
+            ? []
+            : [
+                field.longOption,
+                ...(field.kind === "flag" && field.negatedLongOption !== undefined
+                    ? [field.negatedLongOption]
+                    : []),
+            ]),
+        compiled.contract.grammar.controls.help.longOption,
+        ...(compiled.contract.grammar.controls.version === undefined
+            ? []
+            : [compiled.contract.grammar.controls.version.longOption]),
+        ...(compiled.contract.grammar.controls.output.selector === undefined
+            ? []
+            : [compiled.contract.grammar.controls.output.selector]),
+        ...Object.keys(compiled.contract.grammar.controls.output.compatibilityFlags ?? {}),
+    ];
+}
+function suggestionProperty(key, value) {
+    return value === undefined ? {} : { [key]: value };
+}
+function selectUniqueNeighbor(received, candidates) {
+    const receivedBody = visibleBody(received);
+    const scored = candidates.map((candidate) => ({
+        candidate,
+        distance: damerauLevenshteinDistance(receivedBody, visibleBody(candidate)),
+    }));
+    const nearestDistance = Math.min(...scored.map(({ distance }) => distance));
+    const nearest = scored.filter(({ distance }) => distance === nearestDistance);
+    if (nearest.length !== 1 ||
+        nearestDistance >
+            (Math.max(receivedBody.length, visibleBody(nearest[0].candidate).length) <= 4
+                ? 1
+                : 2)) {
+        return undefined;
+    }
+    return nearest[0].candidate;
+}
+function visibleBody(spelling) {
+    return spelling.startsWith("--") ? spelling.slice(2) : spelling;
+}
+function damerauLevenshteinDistance(left, right) {
+    const maximumDistance = left.length + right.length;
+    const matrix = Array.from({ length: left.length + 2 }, () => Array(right.length + 2).fill(0));
+    matrix[0][0] = maximumDistance;
+    for (let index = 0; index <= left.length; index += 1) {
+        matrix[index + 1][0] = maximumDistance;
+        matrix[index + 1][1] = index;
+    }
+    for (let index = 0; index <= right.length; index += 1) {
+        matrix[0][index + 1] = maximumDistance;
+        matrix[1][index + 1] = index;
+    }
+    const lastRowByCharacter = new Map();
+    for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+        let lastMatchingColumn = 0;
+        for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+            const matchingRow = lastRowByCharacter.get(right[rightIndex - 1]) ?? 0;
+            const cost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
+            if (cost === 0)
+                lastMatchingColumn = rightIndex;
+            matrix[leftIndex + 1][rightIndex + 1] = Math.min(matrix[leftIndex][rightIndex] + cost, matrix[leftIndex + 1][rightIndex] + 1, matrix[leftIndex][rightIndex + 1] + 1, matrix[matchingRow][lastMatchingColumn] +
+                (leftIndex - matchingRow - 1) +
+                1 +
+                (rightIndex - lastMatchingColumn - 1));
+        }
+        lastRowByCharacter.set(left[leftIndex - 1], leftIndex);
+    }
+    return matrix[left.length + 1][right.length + 1];
+}
+function unexpectedPositional(contract, command, usage, position, value) {
+    return usageFailure(contract, command, usage, {
+        code: "unexpectedPositional",
+        position,
+        value,
+    });
+}
+function usageFailure(contract, command, usage, issue) {
+    return usageFailureFromIssues(contract, command, usage, [issue]);
+}
+function usageFailureFromIssues(contract, command, usage, issues) {
+    return bindInvocation(contract, {
+        kind: "usageFailure",
+        command,
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 输入参数是非空元组，映射后长度不变。
+        issues: Object.freeze(issues.map((issue) => Object.freeze(issue))),
+        usage,
+    });
+}
+export function invocationBelongsTo(invocation, contract) {
+    return invocationContracts.get(invocation) === contract;
+}
+function bindInvocation(contract, invocation) {
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 调用事实由本工厂签发并登记到 invocationContracts。
+    const bound = Object.freeze(invocation);
+    invocationContracts.set(bound, contract);
+    return bound;
+}

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

@@ -0,0 +1,10 @@
+import type { CliOutputDestination } from "#/cli-execution";
+/**
+ * 宿主输出端口未能完成写入，保留目的通道和原始 cause；它不是应用失败或正常终止结果。
+ * chunk 可能已部分写出，核心不自动重试，也不借失败端口补写诊断；后续处置由宿主决定。
+ */
+export declare class CliWriteError extends Error {
+    readonly destination: CliOutputDestination;
+    readonly cause: unknown;
+    constructor(destination: CliOutputDestination, cause: unknown);
+}

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

@@ -0,0 +1,14 @@
+/**
+ * 宿主输出端口未能完成写入，保留目的通道和原始 cause；它不是应用失败或正常终止结果。
+ * chunk 可能已部分写出，核心不自动重试，也不借失败端口补写诊断；后续处置由宿主决定。
+ */
+export class CliWriteError extends Error {
+    destination;
+    cause;
+    constructor(destination, cause) {
+        super("cliWriteError", { cause });
+        this.name = "CliWriteError";
+        this.destination = destination;
+        this.cause = cause;
+    }
+}