@jsbot-tellus/core 2.9.0 → 2.10.0

package/src/core/plugin/params/declaration.ts

@@ -1,8 +1,12 @@
 import {
+    candidateLabel,
     declarationError,
+    joinCandidateLabels,
     type CommandParamType,
+    type ParamCandidate,
     type ParamLength,
     type ParamSpec,
+    type ParamTypeCandidate,
 } from './types.js'
 import {
     measureLength,
@@ -30,11 +34,6 @@ export function parseType(value: string): CommandParamType {
     }
 }
 
-interface ParsedType {
-    type: CommandParamType
-    length?: ParamLength | undefined
-}
-
 function parseLengthNumber(raw: string, token: string): number {
     const value = Number(raw)
 
@@ -70,12 +69,34 @@ function parseLength(raw: string, token: string): ParamLength {
     return { min, max }
 }
 
-function parseTypeDeclaration(raw: string, token: string): ParsedType {
-    const value = raw.trim()
+function isQuoted(value: string): boolean {
+    const quote = value[0]
+
+    return quote === '"' || quote === "'"
+}
+
+function parseLiteral(value: string, token: string): string {
+    const quote = value[0]
+
+    if (
+        (quote !== '"' && quote !== "'") ||
+        value.length < 2 ||
+        value[value.length - 1] !== quote
+    ) {
+        throw declarationError(`非法的字面量 "${value}"：${token}`)
+    }
+
+    return unquote(value)
+}
+
+function parseBuiltinCandidate(
+    value: string,
+    token: string
+): ParamTypeCandidate {
     const open = value.indexOf('(')
 
     if (open < 0) {
-        return { type: parseType(value) }
+        return { kind: 'type', type: parseType(value) }
     }
 
     if (!value.endsWith(')')) {
@@ -89,7 +110,112 @@ function parseTypeDeclaration(raw: string, token: string): ParsedType {
         throw declarationError(`只有 string/text 参数支持长度限制：${token}`)
     }
 
-    return { type, length }
+    return { kind: 'type', type, length }
+}
+
+function candidateKey(candidate: ParamCandidate): string {
+    if (candidate.kind === 'literal') {
+        return `literal:${candidate.value}`
+    }
+
+    const length = candidate.length
+    const range =
+        length === undefined ? '' : `${length.min ?? ''}..${length.max ?? ''}`
+
+    return `type:${candidate.type}:${range}`
+}
+
+function splitUnion(raw: string, token: string): string[] {
+    const parts: string[] = []
+    let current = ''
+    let quote: string | null = null
+
+    for (let index = 0; index < raw.length; index += 1) {
+        const char = raw[index]
+
+        if (char === undefined) break
+
+        if (quote !== null) {
+            current += char
+
+            if (char === '\\') {
+                const next = raw[index + 1]
+
+                if (next !== undefined) {
+                    current += next
+                    index += 1
+                }
+
+                continue
+            }
+
+            if (char === quote) {
+                quote = null
+            }
+
+            continue
+        }
+
+        if (char === '"' || char === "'") {
+            quote = char
+            current += char
+            continue
+        }
+
+        if (char === '|') {
+            parts.push(current)
+            current = ''
+            continue
+        }
+
+        current += char
+    }
+
+    if (quote !== null) {
+        throw declarationError(`参数 "${token}" 的引号未闭合`)
+    }
+
+    parts.push(current)
+
+    return parts
+}
+
+function parseCandidates(raw: string, token: string): ParamCandidate[] {
+    const candidates: ParamCandidate[] = []
+    const seen = new Set<string>()
+
+    for (const part of splitUnion(raw, token)) {
+        const value = part.trim()
+
+        if (!value) {
+            throw declarationError(`联合类型中存在空的类型：${token}`)
+        }
+
+        const candidate = isQuoted(value)
+            ? { kind: 'literal' as const, value: parseLiteral(value, token) }
+            : parseBuiltinCandidate(value, token)
+        const key = candidateKey(candidate)
+
+        if (seen.has(key)) continue
+
+        seen.add(key)
+        candidates.push(candidate)
+    }
+
+    if (candidates.length > 1) {
+        for (const candidate of candidates) {
+            if (
+                candidate.kind === 'type' &&
+                (candidate.type === 'text' || candidate.type === 'reply')
+            ) {
+                throw declarationError(
+                    `${candidate.type} 不能用于联合类型：${token}`
+                )
+            }
+        }
+    }
+
+    return candidates
 }
 
 function validateDefaultLength(
@@ -187,6 +313,84 @@ export function splitDeclaration(input: string): string[] {
     return parts
 }
 
+function hasUnquotedEllipsis(value: string): boolean {
+    let quote: string | null = null
+
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index]
+
+        if (char === undefined) break
+
+        if (quote !== null) {
+            if (char === '\\') {
+                index += 1
+                continue
+            }
+
+            if (char === quote) {
+                quote = null
+            }
+
+            continue
+        }
+
+        if (char === '"' || char === "'") {
+            quote = char
+            continue
+        }
+
+        if (value.startsWith('...', index)) {
+            return true
+        }
+    }
+
+    return false
+}
+
+function splitDefault(
+    inner: string,
+    token: string
+): { head: string; defaultRaw?: string | undefined } {
+    let quote: string | null = null
+
+    for (let index = 0; index < inner.length; index += 1) {
+        const char = inner[index]
+
+        if (char === undefined) break
+
+        if (quote !== null) {
+            if (char === '\\') {
+                index += 1
+                continue
+            }
+
+            if (char === quote) {
+                quote = null
+            }
+
+            continue
+        }
+
+        if (char === '"' || char === "'") {
+            quote = char
+            continue
+        }
+
+        if (char === '=') {
+            return {
+                head: inner.slice(0, index).trim(),
+                defaultRaw: inner.slice(index + 1).trim(),
+            }
+        }
+    }
+
+    if (quote !== null) {
+        throw declarationError(`参数 "${token}" 的引号未闭合`)
+    }
+
+    return { head: inner.trim() }
+}
+
 export function parseToken(token: string): ParamSpec {
     const open = token[0]
     const close = token[token.length - 1]
@@ -221,23 +425,22 @@ export function parseToken(token: string): ParamSpec {
 
         return {
             name,
-            type: 'string',
+            candidates: [{ kind: 'type', type: 'string' }],
             required: false,
             rest: true,
             hasDefault: false,
         }
     }
 
-    if (inner.includes('...')) {
+    const { head, defaultRaw } = splitDefault(inner, token)
+
+    if (hasUnquotedEllipsis(head)) {
         throw declarationError(`非法的参数声明 "${token}"`)
     }
 
-    const equals = inner.indexOf('=')
-    const head = equals >= 0 ? inner.slice(0, equals).trim() : inner.trim()
-    const defaultRaw = equals >= 0 ? inner.slice(equals + 1).trim() : undefined
     const colon = head.indexOf(':')
     const name = validateName(colon >= 0 ? head.slice(0, colon) : head)
-    const { type, length } = parseTypeDeclaration(
+    const candidates = parseCandidates(
         colon >= 0 ? head.slice(colon + 1) : 'string',
         token
     )
@@ -247,33 +450,33 @@ export function parseToken(token: string): ParamSpec {
     }
 
     if (defaultRaw !== undefined) {
-        const defaultValue = parseDefaultValue(type, defaultRaw, name)
-
-        if (typeof defaultValue === 'string') {
-            validateDefaultLength(name, defaultValue, length)
-        }
+        const defaultValue = parseDefaultValue(candidates, defaultRaw, name)
 
         return {
             name,
-            type,
+            candidates,
             required,
             rest: false,
             hasDefault: true,
             defaultValue,
-            length,
         }
     }
 
     return {
         name,
-        type,
+        candidates,
         required,
         rest: false,
         hasDefault: false,
-        length,
     }
 }
 
+function hasTextCandidate(spec: ParamSpec): boolean {
+    return spec.candidates.some(
+        (candidate) => candidate.kind === 'type' && candidate.type === 'text'
+    )
+}
+
 export function validateSpecs(specs: ParamSpec[]): void {
     const names = new Set<string>()
     let seenOptional = false
@@ -308,7 +511,7 @@ export function validateSpecs(specs: ParamSpec[]): void {
             continue
         }
 
-        if (spec.type === 'text') {
+        if (hasTextCandidate(spec)) {
             if (index !== specs.length - 1) {
                 throw declarationError('文本参数必须放在最后')
             }
@@ -333,23 +536,32 @@ export function usageOf(specs: ParamSpec[]): string {
                 return `[...${spec.name}]`
             }
 
-            const name = spec.type === 'text' ? `${spec.name}...` : spec.name
+            const name = hasTextCandidate(spec) ? `${spec.name}...` : spec.name
 
             return spec.required ? `<${name}>` : `[${name}]`
         })
         .join(' ')
 }
 
-export function parseDefaultValue(
-    type: CommandParamType,
-    raw: string,
+function parseDefaultCandidate(
+    candidate: ParamCandidate,
+    value: string,
     name: string
 ): unknown {
-    const value = unquote(raw)
+    if (candidate.kind === 'literal') {
+        if (value === candidate.value) {
+            return value
+        }
+
+        throw declarationError(
+            `参数 ${name} 的默认值需要是 ${candidateLabel(candidate)}`
+        )
+    }
 
-    switch (type) {
+    switch (candidate.type) {
         case 'string':
         case 'text':
+            validateDefaultLength(name, value, candidate.length)
             return value
         case 'number': {
             const number = value.trim() === '' ? Number.NaN : Number(value)
@@ -392,3 +604,29 @@ export function parseDefaultValue(
         }
     }
 }
+
+export function parseDefaultValue(
+    candidates: ParamCandidate[],
+    raw: string,
+    name: string
+): unknown {
+    const value = unquote(raw)
+
+    if (candidates.length === 1) {
+        return parseDefaultCandidate(candidates[0]!, value, name)
+    }
+
+    for (const candidate of candidates) {
+        try {
+            return parseDefaultCandidate(candidate, value, name)
+        } catch (error) {
+            if (!(error instanceof Error)) {
+                throw error
+            }
+        }
+    }
+
+    throw declarationError(
+        `参数 ${name} 的默认值需要是 ${joinCandidateLabels(candidates)}`
+    )
+}

package/src/core/plugin/params/input.ts

@@ -1,6 +1,10 @@
 import {
+    candidateLabel,
     CommandParamsError,
+    joinCandidateLabels,
     type InputToken,
+    type ParamCandidate,
+    type ParamLength,
     type ParamSpec,
     type ParsedCommandParams,
 } from './types.js'
@@ -101,9 +105,12 @@ export function tokenizeInput(input: string, usage: string): InputToken[] {
     return tokens
 }
 
-function enforceLength(spec: ParamSpec, value: string, usage: string): string {
-    const length = spec.length
-
+function enforceLength(
+    name: string,
+    length: ParamLength | undefined,
+    value: string,
+    usage: string
+): string {
     if (length === undefined) {
         return value
     }
@@ -112,14 +119,14 @@ function enforceLength(spec: ParamSpec, value: string, usage: string): string {
 
     if (length.min !== undefined && measured < length.min) {
         throw new CommandParamsError(
-            `参数 ${spec.name} 至少需要 ${length.min} 个字符`,
+            `参数 ${name} 至少需要 ${length.min} 个字符`,
             usage
         )
     }
 
     if (length.max !== undefined && measured > length.max) {
         throw new CommandParamsError(
-            `参数 ${spec.name} 不能超过 ${length.max} 个字符`,
+            `参数 ${name} 不能超过 ${length.max} 个字符`,
             usage
         )
     }
@@ -127,16 +134,27 @@ function enforceLength(spec: ParamSpec, value: string, usage: string): string {
     return value
 }
 
-export function parseValue(
+function parseCandidate(
+    candidate: ParamCandidate,
     spec: ParamSpec,
     raw: string,
     usage: string
 ): unknown {
-    switch (spec.type) {
+    if (candidate.kind === 'literal') {
+        if (raw === candidate.value) {
+            return raw
+        }
+
+        throw new CommandParamsError(
+            `参数 ${spec.name} 需要是 ${candidateLabel(candidate)}`,
+            usage
+        )
+    }
+
+    switch (candidate.type) {
         case 'string':
-            return enforceLength(spec, raw, usage)
         case 'text':
-            return raw
+            return enforceLength(spec.name, candidate.length, raw, usage)
         case 'number': {
             const value = raw.trim() === '' ? Number.NaN : Number(raw)
 
@@ -175,11 +193,41 @@ export function parseValue(
         }
         case 'at':
             return parseAt(raw, spec.name, usage)
+        case 'reply':
+            throw new CommandParamsError(
+                `参数 ${spec.name} 需要引用一条消息`,
+                usage
+            )
         case 'time':
             return parseTime(raw, spec.name, usage)
     }
 }
 
+export function parseValue(
+    spec: ParamSpec,
+    raw: string,
+    usage: string
+): unknown {
+    if (spec.candidates.length === 1) {
+        return parseCandidate(spec.candidates[0]!, spec, raw, usage)
+    }
+
+    for (const candidate of spec.candidates) {
+        try {
+            return parseCandidate(candidate, spec, raw, usage)
+        } catch (error) {
+            if (!(error instanceof CommandParamsError)) {
+                throw error
+            }
+        }
+    }
+
+    throw new CommandParamsError(
+        `参数 ${spec.name} 需要是 ${joinCandidateLabels(spec.candidates)}`,
+        usage
+    )
+}
+
 export function parseInput(
     specs: ParamSpec[],
     input: string,
@@ -191,7 +239,10 @@ export function parseInput(
     let index = 0
 
     for (const spec of specs) {
-        if (spec.type === 'reply') {
+        const sole =
+            spec.candidates.length === 1 ? spec.candidates[0] : undefined
+
+        if (sole?.kind === 'type' && sole.type === 'reply') {
             if (quoteId !== undefined) {
                 args.push(quoteId)
             } else if (spec.required) {
@@ -223,7 +274,7 @@ export function parseInput(
             continue
         }
 
-        if (spec.type === 'text') {
+        if (sole?.kind === 'type' && sole.type === 'text') {
             const token = tokens[index]
 
             if (!token) {
@@ -245,7 +296,7 @@ export function parseInput(
             const value =
                 remaining === 1 ? token.value : input.slice(token.start).trim()
 
-            args.push(enforceLength(spec, value, usage))
+            args.push(enforceLength(spec.name, sole.length, value, usage))
             index = tokens.length
             continue
         }

package/src/core/plugin/params/type-level.ts

@@ -11,7 +11,46 @@ type Trim<Source extends string> = TrimLeft<TrimRight<Source>>
 type StripLength<Type extends string> =
     Trim<Type> extends `${infer Base}(${string})` ? Trim<Base> : Trim<Type>
 
-type ParamValue<Type extends string> =
+type Unescape<Source extends string> =
+    Source extends `${infer Head}\\${infer Next}${infer Rest}`
+        ? `${Head}${Next}${Unescape<Rest>}`
+        : Source
+
+type SplitUnionScan<
+    Source extends string,
+    Quote extends string | null = null,
+    Current extends string = '',
+    Acc extends string[] = [],
+> = Source extends `${infer Char}${infer Rest}`
+    ? Char extends '\\'
+        ? Rest extends `${infer Next}${infer Tail}`
+            ? SplitUnionScan<Tail, Quote, `${Current}${Char}${Next}`, Acc>
+            : [...Acc, `${Current}${Char}`]
+        : Char extends '"' | "'"
+          ? Quote extends null
+              ? SplitUnionScan<Rest, Char, `${Current}${Char}`, Acc>
+              : Char extends Quote
+                ? SplitUnionScan<Rest, null, `${Current}${Char}`, Acc>
+                : SplitUnionScan<Rest, Quote, `${Current}${Char}`, Acc>
+          : Char extends '|'
+            ? Quote extends null
+                ? SplitUnionScan<Rest, null, '', [...Acc, Current]>
+                : SplitUnionScan<Rest, Quote, `${Current}${Char}`, Acc>
+            : SplitUnionScan<Rest, Quote, `${Current}${Char}`, Acc>
+    : [...Acc, Current]
+
+type SplitUnion<Source extends string> = Source extends `${string}|${string}`
+    ? SplitUnionScan<Source>
+    : [Source]
+
+type LiteralValue<Type extends string> =
+    Trim<Type> extends `'${infer Inner}'`
+        ? Unescape<Inner>
+        : Trim<Type> extends `"${infer Inner}"`
+          ? Unescape<Inner>
+          : never
+
+type BuiltinValue<Type extends string> =
     StripLength<Type> extends 'string' | 'text'
         ? string
         : StripLength<Type> extends
@@ -21,19 +60,88 @@ type ParamValue<Type extends string> =
             ? boolean
             : unknown
 
+type ParamValuePart<Type extends string> =
+    Trim<Type> extends `'${string}'` | `"${string}"`
+        ? LiteralValue<Type>
+        : BuiltinValue<Type>
+
+type ParamValue<Type extends string> =
+    SplitUnion<Type>[number] extends infer Part
+        ? Part extends string
+            ? ParamValuePart<Part>
+            : never
+        : never
+
+type SplitTypeScan<
+    Source extends string,
+    Quote extends string | null = null,
+    Name extends string = '',
+> = Source extends `${infer Char}${infer Rest}`
+    ? Char extends '\\'
+        ? Rest extends `${infer Next}${infer Tail}`
+            ? SplitTypeScan<Tail, Quote, `${Name}${Char}${Next}`>
+            : [Name, null]
+        : Char extends '"' | "'"
+          ? Quote extends null
+              ? SplitTypeScan<Rest, Char, `${Name}${Char}`>
+              : Char extends Quote
+                ? SplitTypeScan<Rest, null, `${Name}${Char}`>
+                : SplitTypeScan<Rest, Quote, `${Name}${Char}`>
+          : Char extends ':'
+            ? Quote extends null
+                ? [Name, Rest]
+                : SplitTypeScan<Rest, Quote, `${Name}${Char}`>
+            : SplitTypeScan<Rest, Quote, `${Name}${Char}`>
+    : [Name, null]
+
+type SplitType<Source extends string> = Source extends `${string}:${string}`
+    ? SplitTypeScan<Source>
+    : [Source, null]
+
+type SplitDefaultScan<
+    Source extends string,
+    Quote extends string | null = null,
+    Head extends string = '',
+> = Source extends `${infer Char}${infer Rest}`
+    ? Char extends '\\'
+        ? Rest extends `${infer Next}${infer Tail}`
+            ? SplitDefaultScan<Tail, Quote, `${Head}${Char}${Next}`>
+            : [Head, false]
+        : Char extends '"' | "'"
+          ? Quote extends null
+              ? SplitDefaultScan<Rest, Char, `${Head}${Char}`>
+              : Char extends Quote
+                ? SplitDefaultScan<Rest, null, `${Head}${Char}`>
+                : SplitDefaultScan<Rest, Quote, `${Head}${Char}`>
+          : Char extends '='
+            ? Quote extends null
+                ? [Head, true]
+                : SplitDefaultScan<Rest, Quote, `${Head}${Char}`>
+            : SplitDefaultScan<Rest, Quote, `${Head}${Char}`>
+    : [Head, false]
+
+type SplitDefault<Source extends string> = Source extends `${string}=${string}`
+    ? SplitDefaultScan<Source>
+    : [Source, false]
+
 interface VariadicParam {
     readonly variadic: true
 }
 
-type ParamType<Head extends string> = Head extends `${string}:${infer Type}`
-    ? ParamValue<Type>
-    : string
+type ParamType<Head extends string> =
+    SplitType<Head> extends [unknown, infer Type]
+        ? Type extends string
+            ? ParamValue<Type>
+            : string
+        : string
 
 type ParamElement<Body extends string, Required extends boolean> =
     Trim<Body> extends `...${string}`
         ? VariadicParam
-        : Trim<Body> extends `${infer Head}=${string}`
-          ? ParamType<Head>
+        : SplitDefault<Trim<Body>> extends [infer Head, true]
+          ? Head extends string
+              ? ParamType<Head>
+              : never
           : Required extends true
             ? ParamType<Body>
             : ParamType<Body> | undefined