@jsbot-tellus/core 2.4.0 → 2.5.1

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

@@ -0,0 +1,286 @@
+import {
+    declarationError,
+    type CommandParamType,
+    type ParamSpec,
+} from './types.js'
+import { parseBoolean, parseTimeValue, unquote } from './values.js'
+
+const NAME_PATTERN = /^[\p{L}_][\p{L}\p{N}_-]*$/u
+
+export 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}"`)
+    }
+}
+
+export function validateName(value: string): string {
+    const name = value.trim()
+
+    if (!name) {
+        throw declarationError('参数名不能为空')
+    }
+
+    if (!NAME_PATTERN.test(name)) {
+        throw declarationError(`非法的参数名 "${name}"`)
+    }
+
+    return name
+}
+
+export 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
+}
+
+export 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,
+    }
+}
+
+export 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
+        }
+    }
+}
+
+export 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(' ')
+}
+
+export 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
+        }
+    }
+}

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

@@ -0,0 +1,254 @@
+import {
+    CommandParamsError,
+    type InputToken,
+    type ParamSpec,
+    type ParsedCommandParams,
+} from './types.js'
+import { parseAt, parseBoolean, parseTime } from './values.js'
+
+export 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
+}
+
+export 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)
+    }
+}
+
+export 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 }
+}

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

@@ -0,0 +1,59 @@
+import { parseSegments, type OneBotMessageEvent } from '@snowluma/sdk'
+
+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
+}
+
+export 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))
+}

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

@@ -0,0 +1,71 @@
+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>

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

@@ -0,0 +1,49 @@
+import 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
+    }
+}
+
+export interface ParamSpec {
+    name: string
+    type: CommandParamType
+    required: boolean
+    rest: boolean
+    hasDefault: boolean
+    defaultValue?: unknown
+}
+
+export interface InputToken {
+    value: string
+    start: number
+}
+
+export function declarationError(message: string): Error {
+    return new Error(`参数声明错误：${message}`)
+}