@jsbot-tellus/core 2.5.0 → 2.6.0

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,75 @@
+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 StripLength<Type extends string> =
+    Trim<Type> extends `${infer Base}(${string})` ? Trim<Base> : Trim<Type>
+
+type ParamValue<Type extends string> =
+    StripLength<Type> extends 'string' | 'text'
+        ? string
+        : StripLength<Type> extends
+                'number' | 'integer' | 'at' | 'reply' | 'time'
+          ? number
+          : StripLength<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,55 @@
+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 ParamLength {
+    min?: number | undefined
+    max?: number | undefined
+}
+
+export interface ParamSpec {
+    name: string
+    type: CommandParamType
+    required: boolean
+    rest: boolean
+    hasDefault: boolean
+    defaultValue?: unknown
+    length?: ParamLength | undefined
+}
+
+export interface InputToken {
+    value: string
+    start: number
+}
+
+export function declarationError(message: string): Error {
+    return new Error(`参数声明错误：${message}`)
+}

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

@@ -0,0 +1,150 @@
+import { parseSegments } from '@snowluma/sdk'
+import { CommandParamsError, declarationError } from './types.js'
+
+export 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
+}
+
+export function measureLength(value: string): number {
+    return Array.from(value).length
+}
+
+export 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
+}
+
+export 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
+
+export 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
+}
+
+export 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
+}