@jsbot-tellus/core 2.5.0 → 2.6.0

package/src/core/plugin/command-params.ts

@@ -1,871 +1,8 @@
-import { parseSegments, type OneBotMessageEvent } from '@snowluma/sdk'
-
-export type CommandParamType =
-    | 'string'
-    | 'text'
-    | 'number'
-    | 'integer'
-    | 'boolean'
-    | 'at'
-    | 'reply'
-    | 'time'
-
-export interface ParsedCommandParams {
-    args: unknown[]
-    ignored: string[]
-}
-
-export interface CompiledCommandParams {
-    usage: string
-    parse(input: string, event?: OneBotMessageEvent): ParsedCommandParams
-}
-
-export class CommandParamsError extends Error {
-    readonly usage: string
-
-    constructor(message: string, usage: string) {
-        super(message)
-        this.name = 'CommandParamsError'
-        this.usage = usage
-    }
-}
-
-interface ParamSpec {
-    name: string
-    type: CommandParamType
-    required: boolean
-    rest: boolean
-    hasDefault: boolean
-    defaultValue?: unknown
-}
-
-interface InputToken {
-    value: string
-    start: number
-}
-
-const NAME_PATTERN = /^[\p{L}_][\p{L}\p{N}_-]*$/u
-
-function declarationError(message: string): Error {
-    return new Error(`参数声明错误：${message}`)
-}
-
-function parseType(value: string): CommandParamType {
-    switch (value) {
-        case 'string':
-        case 'text':
-        case 'number':
-        case 'integer':
-        case 'boolean':
-        case 'at':
-        case 'reply':
-        case 'time':
-            return value
-        default:
-            throw declarationError(`未知的参数类型 "${value}"`)
-    }
-}
-
-function validateName(value: string): string {
-    const name = value.trim()
-
-    if (!name) {
-        throw declarationError('参数名不能为空')
-    }
-
-    if (!NAME_PATTERN.test(name)) {
-        throw declarationError(`非法的参数名 "${name}"`)
-    }
-
-    return name
-}
-
-function splitDeclaration(input: string): string[] {
-    const parts: string[] = []
-    let index = 0
-
-    while (index < input.length) {
-        const char = input[index]
-
-        if (char === undefined) break
-
-        if (/\s/.test(char)) {
-            index += 1
-            continue
-        }
-
-        if (char !== '<' && char !== '[') {
-            throw declarationError(`无法识别的字符 "${char}"`)
-        }
-
-        const close = char === '<' ? '>' : ']'
-        let end = index + 1
-        let quote: string | null = null
-
-        for (; end < input.length; end += 1) {
-            const current = input[end]
-
-            if (current === undefined) break
-
-            if (quote !== null) {
-                if (current === '\\') {
-                    end += 1
-                    continue
-                }
-
-                if (current === quote) {
-                    quote = null
-                }
-
-                continue
-            }
-
-            if (current === '"' || current === "'") {
-                quote = current
-                continue
-            }
-
-            if (current === close) break
-        }
-
-        if (end >= input.length || input[end] !== close) {
-            throw declarationError(`参数 "${input.slice(index)}" 缺少 ${close}`)
-        }
-
-        parts.push(input.slice(index, end + 1))
-        index = end + 1
-    }
-
-    return parts
-}
-
-function unquote(value: string): string {
-    const trimmed = value.trim()
-    const quote = trimmed[0]
-
-    if (quote !== '"' && quote !== "'") {
-        return trimmed
-    }
-
-    if (trimmed.length < 2 || trimmed[trimmed.length - 1] !== quote) {
-        throw declarationError('默认值引号未闭合')
-    }
-
-    let result = ''
-
-    for (let index = 1; index < trimmed.length - 1; index += 1) {
-        const char = trimmed[index]
-
-        if (char === undefined) break
-
-        if (char === '\\') {
-            const next = trimmed[index + 1]
-
-            if (next !== undefined) {
-                result += next
-                index += 1
-            }
-
-            continue
-        }
-
-        result += char
-    }
-
-    return result
-}
-
-function parseBoolean(value: string): boolean | null {
-    const normalized = value.trim().toLowerCase()
-
-    if (['true', '1', 'yes', 'y', 'on'].includes(normalized)) {
-        return true
-    }
-
-    if (['false', '0', 'no', 'n', 'off'].includes(normalized)) {
-        return false
-    }
-
-    return null
-}
-
-function parseAt(value: string, name: string, usage: string): number {
-    const raw = value.trim()
-    const segments = parseSegments(raw)
-    const segment = segments[0]
-
-    if (segments.length === 1 && segment?.type === 'at') {
-        const qq = segment.data.qq
-
-        if (qq !== 'all') {
-            const parsed = Number(qq)
-
-            if (Number.isSafeInteger(parsed) && parsed > 0) {
-                return parsed
-            }
-        }
-    } else if (/^\d+$/.test(raw)) {
-        const parsed = Number(raw)
-
-        if (Number.isSafeInteger(parsed) && parsed > 0) {
-            return parsed
-        }
-    }
-
-    throw new CommandParamsError(
-        `参数 ${name} 需要 @ 一个用户或填写 QQ 号`,
-        usage
-    )
-}
-
-const TIME_UNITS: Record<string, number> = {
-    s: 1,
-    秒: 1,
-    m: 60,
-    分: 60,
-    分钟: 60,
-    h: 3600,
-    时: 3600,
-    小时: 3600,
-    d: 86400,
-    天: 86400,
-    w: 604800,
-    周: 604800,
-}
-
-const TIME_PART = /^(\d+(?:\.\d+)?)(分钟|小时|秒|分|时|天|周|[smhdw])/i
-
-function parseTimeValue(value: string): number | null {
-    const raw = value.trim()
-
-    if (/^\d+$/.test(raw)) {
-        const seconds = Number(raw)
-
-        return Number.isSafeInteger(seconds) ? seconds : null
-    }
-
-    let index = 0
-    let total = 0
-    let parsed = false
-
-    while (index < raw.length) {
-        const match = TIME_PART.exec(raw.slice(index))
-
-        if (!match) return null
-
-        const unit = TIME_UNITS[match[2]?.toLowerCase() ?? '']
-        const amount = Number(match[1])
-
-        if (unit === undefined) return null
-
-        total += amount * unit
-        index += match[0].length
-        parsed = true
-    }
-
-    if (!parsed || !Number.isSafeInteger(total) || total < 0) {
-        return null
-    }
-
-    return total
-}
-
-function parseTime(value: string, name: string, usage: string): number {
-    const seconds = parseTimeValue(value)
-
-    if (seconds === null) {
-        throw new CommandParamsError(
-            `参数 ${name} 需要是时间，例如 10s、5m、1h30m`,
-            usage
-        )
-    }
-
-    return seconds
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-    return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-function toMessageId(value: unknown): number | undefined {
-    const raw = typeof value === 'string' ? value.trim() : value
-
-    if (typeof raw !== 'number' && typeof raw !== 'string') {
-        return undefined
-    }
-
-    const parsed =
-        typeof raw === 'string'
-            ? /^-?\d+$/.test(raw)
-                ? Number(raw)
-                : Number.NaN
-            : raw
-
-    return Number.isSafeInteger(parsed) && parsed !== 0 ? parsed : undefined
-}
-
-function replyIdIn(segments: readonly unknown[]): number | undefined {
-    for (const segment of segments) {
-        if (!isRecord(segment) || segment.type !== 'reply') continue
-
-        const data = isRecord(segment.data) ? segment.data : undefined
-        const id = toMessageId(data?.id)
-
-        if (id !== undefined) return id
-    }
-
-    return undefined
-}
-
-function quoteIdOf(event: OneBotMessageEvent | undefined): number | undefined {
-    if (!event) return undefined
-
-    const message = event.message
-
-    if (typeof message === 'string') {
-        const id = replyIdIn(parseSegments(message))
-
-        if (id !== undefined) return id
-    } else if (Array.isArray(message)) {
-        const id = replyIdIn(message)
-
-        if (id !== undefined) return id
-    } else if (isRecord(message)) {
-        const id = replyIdIn([message])
-
-        if (id !== undefined) return id
-    }
-
-    return replyIdIn(parseSegments(event.raw_message))
-}
-
-function parseDefaultValue(
-    type: CommandParamType,
-    raw: string,
-    name: string
-): unknown {
-    const value = unquote(raw)
-
-    switch (type) {
-        case 'string':
-        case 'text':
-            return value
-        case 'number': {
-            const number = value.trim() === '' ? Number.NaN : Number(value)
-
-            if (!Number.isFinite(number)) {
-                throw declarationError(`参数 ${name} 的默认值不是数字`)
-            }
-
-            return number
-        }
-        case 'integer': {
-            const number = value.trim() === '' ? Number.NaN : Number(value)
-
-            if (!Number.isInteger(number)) {
-                throw declarationError(`参数 ${name} 的默认值不是整数`)
-            }
-
-            return number
-        }
-        case 'boolean': {
-            const boolean = parseBoolean(value)
-
-            if (boolean === null) {
-                throw declarationError(`参数 ${name} 的默认值不是布尔值`)
-            }
-
-            return boolean
-        }
-        case 'at':
-        case 'reply':
-            throw declarationError(`参数 ${name} 不支持默认值`)
-        case 'time': {
-            const seconds = parseTimeValue(value)
-
-            if (seconds === null) {
-                throw declarationError(`参数 ${name} 的默认值不是时间`)
-            }
-
-            return seconds
-        }
-    }
-}
-
-function parseToken(token: string): ParamSpec {
-    const open = token[0]
-    const close = token[token.length - 1]
-
-    if (
-        (open !== '<' && open !== '[') ||
-        (close !== '>' && close !== ']') ||
-        (open === '<') !== (close === '>')
-    ) {
-        throw declarationError(`非法的参数声明 "${token}"`)
-    }
-
-    const required = open === '<'
-    const inner = token.slice(1, -1).trim()
-
-    if (!inner) {
-        throw declarationError('参数名不能为空')
-    }
-
-    if (inner.startsWith('...')) {
-        if (required) {
-            throw declarationError('变长参数必须使用 [ ]')
-        }
-
-        const name = validateName(inner.slice(3))
-
-        return {
-            name,
-            type: 'string',
-            required: false,
-            rest: true,
-            hasDefault: false,
-        }
-    }
-
-    if (inner.includes('...')) {
-        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 = parseType(colon >= 0 ? head.slice(colon + 1).trim() : 'string')
-
-    if (required && defaultRaw !== undefined) {
-        throw declarationError(`必填参数不能有默认值：${token}`)
-    }
-
-    if (defaultRaw !== undefined) {
-        return {
-            name,
-            type,
-            required,
-            rest: false,
-            hasDefault: true,
-            defaultValue: parseDefaultValue(type, defaultRaw, name),
-        }
-    }
-
-    return {
-        name,
-        type,
-        required,
-        rest: false,
-        hasDefault: false,
-    }
-}
-
-function validateSpecs(specs: ParamSpec[]): void {
-    const names = new Set<string>()
-    let seenOptional = false
-    let seenRest = false
-    let seenText = false
-
-    for (let index = 0; index < specs.length; index += 1) {
-        const spec = specs[index]
-
-        if (!spec) continue
-
-        if (names.has(spec.name)) {
-            throw declarationError(`参数名重复 "${spec.name}"`)
-        }
-
-        names.add(spec.name)
-
-        if (seenRest) {
-            throw declarationError('变长参数后面不能再有参数')
-        }
-
-        if (seenText) {
-            throw declarationError('文本参数后面不能再有参数')
-        }
-
-        if (spec.rest) {
-            if (index !== specs.length - 1) {
-                throw declarationError('变长参数必须放在最后')
-            }
-
-            seenRest = true
-            continue
-        }
-
-        if (spec.type === 'text') {
-            if (index !== specs.length - 1) {
-                throw declarationError('文本参数必须放在最后')
-            }
-
-            seenText = true
-        }
-
-        if (spec.required) {
-            if (seenOptional) {
-                throw declarationError('必填参数不能出现在可选参数后面')
-            }
-        } else {
-            seenOptional = true
-        }
-    }
-}
-
-function usageOf(specs: ParamSpec[]): string {
-    return specs
-        .map((spec) => {
-            if (spec.rest) {
-                return `[...${spec.name}]`
-            }
-
-            const name = spec.type === 'text' ? `${spec.name}...` : spec.name
-
-            return spec.required ? `<${name}>` : `[${name}]`
-        })
-        .join(' ')
-}
-
-function tokenizeInput(input: string, usage: string): InputToken[] {
-    const tokens: InputToken[] = []
-    let index = 0
-
-    while (index < input.length) {
-        const char = input[index]
-
-        if (char === undefined) break
-
-        if (/\s/.test(char)) {
-            index += 1
-            continue
-        }
-
-        const start = index
-        let value = ''
-        let quote: string | null = null
-
-        while (index < input.length) {
-            const current = input[index]
-
-            if (current === undefined) break
-
-            if (quote !== null) {
-                if (current === '\\') {
-                    const next = input[index + 1]
-
-                    if (next !== undefined) {
-                        value += next
-                        index += 2
-                        continue
-                    }
-
-                    value += current
-                    index += 1
-                    continue
-                }
-
-                if (current === quote) {
-                    quote = null
-                    index += 1
-                    continue
-                }
-
-                value += current
-                index += 1
-                continue
-            }
-
-            if (/\s/.test(current)) break
-
-            if (current === '[' && input.startsWith('[CQ:', index)) {
-                const close = input.indexOf(']', index + 4)
-
-                if (close >= 0) {
-                    value += input.slice(index, close + 1)
-                    index = close + 1
-                    continue
-                }
-            }
-
-            if (current === '"' || current === "'") {
-                quote = current
-                index += 1
-                continue
-            }
-
-            if (current === '\\') {
-                const next = input[index + 1]
-
-                if (next !== undefined) {
-                    value += next
-                    index += 2
-                    continue
-                }
-
-                value += current
-                index += 1
-                continue
-            }
-
-            value += current
-            index += 1
-        }
-
-        if (quote !== null) {
-            throw new CommandParamsError('参数引号未闭合', usage)
-        }
-
-        tokens.push({ value, start })
-    }
-
-    return tokens
-}
-
-function parseValue(spec: ParamSpec, raw: string, usage: string): unknown {
-    switch (spec.type) {
-        case 'string':
-        case 'text':
-            return raw
-        case 'number': {
-            const value = raw.trim() === '' ? Number.NaN : Number(raw)
-
-            if (!Number.isFinite(value)) {
-                throw new CommandParamsError(
-                    `参数 ${spec.name} 需要是数字`,
-                    usage
-                )
-            }
-
-            return value
-        }
-        case 'integer': {
-            const value = raw.trim() === '' ? Number.NaN : Number(raw)
-
-            if (!Number.isInteger(value)) {
-                throw new CommandParamsError(
-                    `参数 ${spec.name} 需要是整数`,
-                    usage
-                )
-            }
-
-            return value
-        }
-        case 'boolean': {
-            const value = parseBoolean(raw)
-
-            if (value === null) {
-                throw new CommandParamsError(
-                    `参数 ${spec.name} 需要是布尔值`,
-                    usage
-                )
-            }
-
-            return value
-        }
-        case 'at':
-            return parseAt(raw, spec.name, usage)
-        case 'time':
-            return parseTime(raw, spec.name, usage)
-    }
-}
-
-function parseInput(
-    specs: ParamSpec[],
-    input: string,
-    usage: string,
-    quoteId: number | undefined
-): ParsedCommandParams {
-    const tokens = tokenizeInput(input, usage)
-    const args: unknown[] = []
-    let index = 0
-
-    for (const spec of specs) {
-        if (spec.type === 'reply') {
-            if (quoteId !== undefined) {
-                args.push(quoteId)
-            } else if (spec.required) {
-                throw new CommandParamsError(
-                    `参数 ${spec.name} 需要引用一条消息`,
-                    usage
-                )
-            } else {
-                args.push(undefined)
-            }
-
-            continue
-        }
-
-        if (spec.rest) {
-            for (
-                let tokenIndex = index;
-                tokenIndex < tokens.length;
-                tokenIndex += 1
-            ) {
-                const token = tokens[tokenIndex]
-
-                if (token) {
-                    args.push(token.value)
-                }
-            }
-
-            index = tokens.length
-            continue
-        }
-
-        if (spec.type === 'text') {
-            const token = tokens[index]
-
-            if (!token) {
-                if (spec.hasDefault) {
-                    args.push(spec.defaultValue)
-                } else if (spec.required) {
-                    throw new CommandParamsError(
-                        `缺少参数：${spec.name}`,
-                        usage
-                    )
-                } else {
-                    args.push(undefined)
-                }
-
-                continue
-            }
-
-            const remaining = tokens.length - index
-            const value =
-                remaining === 1 ? token.value : input.slice(token.start).trim()
-
-            args.push(value)
-            index = tokens.length
-            continue
-        }
-
-        const token = tokens[index]
-
-        if (!token) {
-            if (spec.hasDefault) {
-                args.push(spec.defaultValue)
-            } else if (spec.required) {
-                throw new CommandParamsError(`缺少参数：${spec.name}`, usage)
-            } else {
-                args.push(undefined)
-            }
-
-            continue
-        }
-
-        index += 1
-        args.push(parseValue(spec, token.value, usage))
-    }
-
-    while (args.length > 0 && args[args.length - 1] === undefined) {
-        args.pop()
-    }
-
-    const ignored =
-        index < tokens.length
-            ? tokens.slice(index).map((token) => token.value)
-            : []
-
-    return { args, ignored }
-}
-
-export function compileCommandParams(
-    declaration: string
-): CompiledCommandParams {
-    const trimmed = declaration.trim()
-
-    if (!trimmed) {
-        throw declarationError('参数声明不能为空')
-    }
-
-    const specs = splitDeclaration(trimmed).map(parseToken)
-
-    if (specs.length === 0) {
-        throw declarationError('参数声明不能为空')
-    }
-
-    validateSpecs(specs)
-
-    const usage = usageOf(specs)
-
-    return {
-        usage,
-        parse(input: string, event?: OneBotMessageEvent): ParsedCommandParams {
-            return parseInput(specs, input, usage, quoteIdOf(event))
-        },
-    }
-}
-
-type Whitespace = ' ' | '\n' | '\r' | '\t' | '\v' | '\f'
-
-type TrimLeft<Source extends string> =
-    Source extends `${Whitespace}${infer Rest}` ? TrimLeft<Rest> : Source
-
-type TrimRight<Source extends string> =
-    Source extends `${infer Rest}${Whitespace}` ? TrimRight<Rest> : Source
-
-type Trim<Source extends string> = TrimLeft<TrimRight<Source>>
-
-type ParamValue<Type extends string> =
-    Trim<Type> extends 'string' | 'text'
-        ? string
-        : Trim<Type> extends 'number' | 'integer' | 'at' | 'reply' | 'time'
-          ? number
-          : Trim<Type> extends 'boolean'
-            ? boolean
-            : unknown
-
-interface VariadicParam {
-    readonly variadic: true
-}
-
-type ParamType<Head extends string> = Head extends `${string}:${infer Type}`
-    ? ParamValue<Type>
-    : string
-
-type ParamElement<Body extends string, Required extends boolean> =
-    Trim<Body> extends `...${string}`
-        ? VariadicParam
-        : Trim<Body> extends `${infer Head}=${string}`
-          ? ParamType<Head>
-          : Required extends true
-            ? ParamType<Body>
-            : ParamType<Body> | undefined
-
-type AppendParam<Acc extends unknown[], Element> = [Element] extends [
-    VariadicParam,
-]
-    ? [...Acc, ...string[]]
-    : [...Acc, Element]
-
-type ParseCommandParams<Source extends string, Acc extends unknown[] = []> =
-    Trim<Source> extends ''
-        ? Acc
-        : Trim<Source> extends `<${infer Body}>${infer Rest}`
-          ? ParamElement<Body, true> extends VariadicParam
-              ? any[]
-              : ParseCommandParams<
-                    Rest,
-                    AppendParam<Acc, ParamElement<Body, true>>
-                >
-          : Trim<Source> extends `[${infer Body}]${infer Rest}`
-            ? ParamElement<Body, false> extends VariadicParam
-                ? Trim<Rest> extends ''
-                    ? [...Acc, ...string[]]
-                    : any[]
-                : ParseCommandParams<
-                      Rest,
-                      AppendParam<Acc, ParamElement<Body, false>>
-                  >
-            : any[]
-
-/**
- * 把 `params` 声明字符串推导成 handler 的位置参数 tuple。
- *
- * 非字面量声明（例如运行时拼接的 `string`）或无法解析的声明会回退为
- * `any[]`，以保证现有插件仍然可以编译。
- */
-export type CommandParamArgs<Declaration extends string> =
-    string extends Declaration ? any[] : ParseCommandParams<Declaration>
+export {
+    CommandParamsError,
+    type CommandParamType,
+    type CompiledCommandParams,
+    type ParsedCommandParams,
+} from './params/types.js'
+export { compileCommandParams } from './params/compile.js'
+export type { CommandParamArgs } from './params/type-level.js'