alemonjs 2.1.68 → 2.1.70

package/lib/app/router/fallback.d.ts

@@ -0,0 +1,12 @@
+export type FallbackHint = {
+    matched: boolean;
+    message?: string;
+    suggestedKey?: string;
+};
+export type FallbackSuggestOptions = {
+    suggest?: boolean;
+    maxDistance?: number;
+    minInputLength?: number;
+    allowPrefixMatch?: boolean;
+};
+export declare function checkFallbackHint(messageText: string | undefined, routeKeys: string[], options?: FallbackSuggestOptions): FallbackHint;

package/lib/app/router/fallback.js

@@ -0,0 +1,85 @@
+import { parseMessageText } from './parser.js';
+
+function levenshteinDistance(a, b) {
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    const matrix = Array.from({ length: rows }, () => Array(cols).fill(0));
+    for (let row = 0; row < rows; row += 1) {
+        matrix[row][0] = row;
+    }
+    for (let col = 0; col < cols; col += 1) {
+        matrix[0][col] = col;
+    }
+    for (let row = 1; row < rows; row += 1) {
+        for (let col = 1; col < cols; col += 1) {
+            const cost = a[row - 1] === b[col - 1] ? 0 : 1;
+            matrix[row][col] = Math.min(matrix[row - 1][col] + 1, matrix[row][col - 1] + 1, matrix[row - 1][col - 1] + cost);
+        }
+    }
+    return matrix[a.length][b.length];
+}
+function normalizeForCompare(text) {
+    return text.replace(/^([!！/#＃])\s*/, '').trim();
+}
+function getAdaptiveMaxDistance(input) {
+    if (input.length <= 2) {
+        return 1;
+    }
+    if (input.length <= 4) {
+        return 2;
+    }
+    return 3;
+}
+function shouldAcceptSuggestion(input, candidate, distance, options = {}) {
+    if (input === candidate) {
+        return false;
+    }
+    if (options.allowPrefixMatch !== false && (candidate.startsWith(input) || input.startsWith(candidate))) {
+        return true;
+    }
+    const maxDistance = typeof options.maxDistance === 'number' ? options.maxDistance : getAdaptiveMaxDistance(input);
+    return distance <= maxDistance;
+}
+function checkFallbackHint(messageText, routeKeys, options = {}) {
+    if (options.suggest === false) {
+        return { matched: false };
+    }
+    const parsed = parseMessageText(messageText);
+    if (!parsed) {
+        return { matched: false };
+    }
+    const oneKey = parsed.tokens[0] ?? '';
+    const twoKey = parsed.tokens.length >= 2 ? `${parsed.tokens[0]} ${parsed.tokens[1]}` : '';
+    const attemptedKey = twoKey || oneKey;
+    if (!attemptedKey) {
+        return { matched: false };
+    }
+    if (typeof options.minInputLength === 'number' && attemptedKey.length < options.minInputLength) {
+        return { matched: false };
+    }
+    let bestMatch = null;
+    for (const routeKey of routeKeys) {
+        const normalizedKey = normalizeForCompare(routeKey);
+        const distance = levenshteinDistance(attemptedKey, normalizedKey);
+        if (!bestMatch || distance < bestMatch.distance) {
+            bestMatch = {
+                key: routeKey,
+                distance
+            };
+        }
+    }
+    if (!bestMatch) {
+        return { matched: false };
+    }
+    const normalizedBestKey = normalizeForCompare(bestMatch.key);
+    if (!shouldAcceptSuggestion(attemptedKey, normalizedBestKey, bestMatch.distance, options)) {
+        return { matched: false };
+    }
+    return {
+        matched: true,
+        suggestedKey: bestMatch.key,
+        message: `你输入的内容更接近指令 \`${bestMatch.key}\`，请改用这个指令。`
+    };
+}
+
+export { checkFallbackHint };

package/lib/app/router/main.d.ts

@@ -0,0 +1,7 @@
+export { Router } from './dsl';
+export type { RouterOptions } from './dsl';
+export { checkFallbackHint } from './fallback';
+export { normalizeRoutePath, parseMessageText } from './parser';
+export type { AppMatchResult, RegisteredRoute, RouteDefinition, RouteHandlerConfig, RouteImporter } from './types';
+export { validateRouteArgs } from './validator';
+export type { RouteArgSchema, RouteRangeValue, RouteSchema, RouteSchemaValue, RouteValidationResult, SchemaValueType } from './validator';

package/lib/app/router/main.js

@@ -0,0 +1,4 @@
+export { Router } from './dsl.js';
+export { checkFallbackHint } from './fallback.js';
+export { normalizeRoutePath, parseMessageText } from './parser.js';
+export { validateRouteArgs } from './validator.js';

package/lib/app/router/parser.d.ts

@@ -0,0 +1,8 @@
+export type ParsedMessage = {
+    prefix: string;
+    rawText: string;
+    normalizedText: string;
+    tokens: string[];
+};
+export declare function parseMessageText(messageText?: string): ParsedMessage | null;
+export declare function normalizeRoutePath(path: string): string;

package/lib/app/router/parser.js

@@ -0,0 +1,24 @@
+const COMMAND_PREFIX_REGEXP = /^([!！/#＃])\s*/;
+function parseMessageText(messageText) {
+    const rawText = String(messageText ?? '').trim();
+    if (!rawText) {
+        return null;
+    }
+    const prefixMatch = rawText.match(COMMAND_PREFIX_REGEXP);
+    const prefix = prefixMatch?.[1] ?? '';
+    const normalizedText = rawText.replace(COMMAND_PREFIX_REGEXP, '').trim();
+    if (!normalizedText) {
+        return null;
+    }
+    return {
+        prefix,
+        rawText,
+        normalizedText,
+        tokens: normalizedText.split(/\s+/).filter(Boolean)
+    };
+}
+function normalizeRoutePath(path) {
+    return path.replace(COMMAND_PREFIX_REGEXP, '').trim();
+}
+
+export { normalizeRoutePath, parseMessageText };

package/lib/app/router/types.d.ts

@@ -0,0 +1,102 @@
+import type { RouteSchema, RouteSchemaValue, RouteValidationResult } from './validator';
+export type RouteParams = Record<string, RouteSchemaValue | undefined>;
+export type RouteContext = {
+    key: string;
+    text: string;
+    rawArgs: string[];
+    parsedArgs: RouteSchemaValue[];
+    params: RouteParams;
+};
+export type RouteTextRule = {
+    prefixes?: readonly string[];
+    stripPrefix?: boolean;
+    allowBare?: boolean;
+};
+export type RouteTextConfig<P extends string = string> = RouteTextRule & {
+    byPlatform?: Partial<Record<P, RouteTextRule>>;
+};
+export type RouteImporter = () => Promise<unknown>;
+export type RouteNext = () => Promise<void> | undefined;
+export type RouteExecutable = (event: Record<string, unknown>, next: RouteNext) => Promise<boolean | undefined> | boolean | undefined;
+export type RouteHandlerConfig<P extends string = string, E extends string = string> = {
+    path?: string;
+    events?: readonly E[];
+    platforms?: readonly P[];
+    schema?: RouteSchema;
+};
+export type RouteGroupConditions<P extends string = string, E extends string = string> = {
+    path?: string;
+    events?: readonly E[];
+    platforms?: readonly P[];
+    routeText?: RouteTextConfig<P>;
+    keyPolicy?: {
+        maxWords?: 1 | 2;
+    };
+    duplicateKey?: 'ignore' | 'warn' | 'throw';
+    fallback?: {
+        suggest?: boolean;
+        maxDistance?: number;
+        minInputLength?: number;
+        allowPrefixMatch?: boolean;
+    };
+    redispatch?: {
+        maxDepth?: number;
+    };
+};
+export type RouteResConfig<P extends string = string, E extends string = string> = {
+    events?: readonly E[];
+    platforms?: readonly P[];
+    regular?: RegExp;
+};
+export type RouteDefinition<P extends string = string, E extends string = string> = string | RouteHandlerConfig<P, E>;
+export type RouteDefinitions<P extends string = string, E extends string = string> = RouteDefinition<P, E> | RouteDefinition<P, E>[];
+export type NormalizedRouteConfig<P extends string = string, E extends string = string> = {
+    path?: string;
+    events?: readonly E[];
+    platforms?: readonly P[];
+    schema?: RouteSchema;
+};
+export type RegisteredRoute<P extends string = string, E extends string = string> = {
+    config: NormalizedRouteConfig<P, E> & {
+        path: string;
+    };
+    scopeId: string;
+    keyLength: 1 | 2;
+    importers: RouteImporter[];
+    inheritedImporters: RouteImporter[];
+};
+export type RegisteredRes<P extends string = string, E extends string = string> = {
+    config: RouteResConfig<P, E>;
+    importers: RouteImporter[];
+};
+export type AppMatchResult = {
+    matched: false;
+} | {
+    matched: true;
+    route: RegisteredRoute;
+    eventName: string;
+    normalizedCommand: string;
+    rawArgs: string[];
+    parsedArgs: RouteSchemaValue[];
+    validation: RouteValidationResult;
+    matchedPath: string;
+    importerCount: number;
+    importerLabels: string[];
+};
+export type DispatchStopReason = 'unmatched' | 'validation_failed' | 'handler_returned_false' | 'handler_completed' | 'redispatch_limit' | 'unsupported_handler';
+export type AppDispatchResult = {
+    matched: boolean;
+    stopped: boolean;
+    reason: DispatchStopReason;
+    eventName: string;
+    commandKey?: string;
+    matchedPath?: string;
+    normalizedCommand?: string;
+    rawArgs: string[];
+    parsedArgs: RouteSchemaValue[];
+    params?: RouteParams;
+    importerCount: number;
+    importerLabels: string[];
+    validation?: RouteValidationResult;
+    rewrittenMessageText?: string;
+};

package/lib/app/router/types.js

@@ -0,0 +1 @@
+

package/lib/app/router/validator.d.ts

@@ -0,0 +1,50 @@
+export type RouteRangeValue = {
+    start: number;
+    end: number;
+};
+export type SchemaValueType = 'string' | 'number' | 'enum' | 'range' | 'rest';
+export type RouteSchemaValue = string | number | RouteRangeValue;
+export type RouteRuleValidatorContext = {
+    commandPath?: string;
+    argName: string;
+    argIndex: number;
+    displayIndex: number;
+    rawArgs: string[];
+    parsedArgs: RouteSchemaValue[];
+    rawValue: string;
+};
+export type RouteRule = {
+    required?: boolean;
+    type?: SchemaValueType;
+    enum?: string[];
+    pattern?: RegExp;
+    min?: number;
+    max?: number;
+    separators?: string[];
+    normalizeMap?: Record<string, string>;
+    message?: string;
+    validator?: (value: RouteSchemaValue, context: RouteRuleValidatorContext) => string | undefined;
+};
+export type RouteArgSchema = {
+    name: string;
+    defaultValue?: RouteSchemaValue;
+    rules?: RouteRule[];
+};
+export type RouteSchema = {
+    args?: RouteArgSchema[];
+    usage?: string;
+    messages?: {
+        tooFewArgs?: string;
+        tooManyArgs?: string;
+    };
+};
+export type RouteValidationResult = {
+    valid: true;
+    parsedArgs: RouteSchemaValue[];
+} | {
+    valid: false;
+    error: string;
+    usage?: string;
+};
+export declare function validateRouteArgs(rawArgs: string[], schema?: RouteSchema): RouteValidationResult;
+export declare function validateRouteArgsForCommand(commandPath: string | undefined, rawArgs: string[], schema?: RouteSchema): RouteValidationResult;

package/lib/app/router/validator.js

@@ -0,0 +1,306 @@
+function getRequiredRule(arg) {
+    return arg?.rules?.find(rule => rule.required);
+}
+function getRestRule(arg) {
+    return arg?.rules?.find(rule => rule.type === 'rest');
+}
+function getMinArgs(schema) {
+    if (!schema) {
+        return 0;
+    }
+    return (schema.args ?? []).filter(arg => Boolean(getRequiredRule(arg))).length;
+}
+function getMaxArgs(schema) {
+    if (!schema) {
+        return undefined;
+    }
+    const args = schema.args ?? [];
+    if (args.some(arg => Boolean(getRestRule(arg)))) {
+        return undefined;
+    }
+    return args.length > 0 ? args.length : undefined;
+}
+function parseRange(rawValue, rule) {
+    const separators = rule.separators ?? ['-', '－'];
+    const separator = separators.find(item => rawValue.includes(item));
+    if (!separator) {
+        return null;
+    }
+    const [rawStart = '', rawEnd = ''] = rawValue.split(separator).map(item => item.trim());
+    const start = Number(rawStart);
+    const end = Number(rawEnd);
+    if (!rawStart || !rawEnd || Number.isNaN(start) || Number.isNaN(end)) {
+        return null;
+    }
+    return { start, end };
+}
+function validateTypedRule(rawValue, rule, context, usage) {
+    const messagePrefix = `参数${context.displayIndex}`;
+    const normalizedValue = rule.normalizeMap?.[rawValue] ?? rawValue;
+    if (rule.pattern) {
+        rule.pattern.lastIndex = 0;
+        if (!rule.pattern.test(normalizedValue)) {
+            return {
+                valid: false,
+                error: rule.message ?? `${messagePrefix}格式不正确`,
+                usage
+            };
+        }
+    }
+    if (!rule.type || rule.type === 'string') {
+        const value = String(normalizedValue);
+        if (rule.validator) {
+            const customError = rule.validator(value, { ...context, rawValue: normalizedValue });
+            if (customError) {
+                return {
+                    valid: false,
+                    error: customError,
+                    usage
+                };
+            }
+        }
+        return {
+            valid: true,
+            parsedArgs: [value]
+        };
+    }
+    if (rule.type === 'number') {
+        const value = Number(normalizedValue);
+        if (Number.isNaN(value)) {
+            return {
+                valid: false,
+                error: rule.message ?? `${messagePrefix}必须是数字`,
+                usage
+            };
+        }
+        if (typeof rule.min === 'number' && value < rule.min) {
+            return {
+                valid: false,
+                error: rule.message ?? `${messagePrefix}不能小于${rule.min}`,
+                usage
+            };
+        }
+        if (typeof rule.max === 'number' && value > rule.max) {
+            return {
+                valid: false,
+                error: rule.message ?? `${messagePrefix}不能大于${rule.max}`,
+                usage
+            };
+        }
+        if (rule.validator) {
+            const customError = rule.validator(value, { ...context, rawValue: normalizedValue });
+            if (customError) {
+                return {
+                    valid: false,
+                    error: customError,
+                    usage
+                };
+            }
+        }
+        return {
+            valid: true,
+            parsedArgs: [value]
+        };
+    }
+    if (rule.type === 'enum') {
+        const enumValues = rule.enum ?? [];
+        if (!enumValues.includes(normalizedValue)) {
+            return {
+                valid: false,
+                error: rule.message ?? `${messagePrefix}只能是 ${enumValues.join(' / ')}`,
+                usage
+            };
+        }
+        if (rule.validator) {
+            const customError = rule.validator(normalizedValue, { ...context, rawValue: normalizedValue });
+            if (customError) {
+                return {
+                    valid: false,
+                    error: customError,
+                    usage
+                };
+            }
+        }
+        return {
+            valid: true,
+            parsedArgs: [normalizedValue]
+        };
+    }
+    if (rule.type === 'range') {
+        const value = parseRange(normalizedValue, rule);
+        if (!value) {
+            return {
+                valid: false,
+                error: rule.message ?? `${messagePrefix}必须是区间，例如 1-10`,
+                usage
+            };
+        }
+        if (value.start > value.end) {
+            return {
+                valid: false,
+                error: rule.message ?? `${messagePrefix}的起点不能大于终点`,
+                usage
+            };
+        }
+        if (typeof rule.min === 'number' && (value.start < rule.min || value.end < rule.min)) {
+            return {
+                valid: false,
+                error: rule.message ?? `${messagePrefix}不能小于${rule.min}`,
+                usage
+            };
+        }
+        if (typeof rule.max === 'number' && (value.start > rule.max || value.end > rule.max)) {
+            return {
+                valid: false,
+                error: rule.message ?? `${messagePrefix}不能大于${rule.max}`,
+                usage
+            };
+        }
+        if (rule.validator) {
+            const customError = rule.validator(value, { ...context, rawValue: normalizedValue });
+            if (customError) {
+                return {
+                    valid: false,
+                    error: customError,
+                    usage
+                };
+            }
+        }
+        return {
+            valid: true,
+            parsedArgs: [value]
+        };
+    }
+    if (rule.type === 'rest') {
+        const value = String(normalizedValue);
+        if (rule.validator) {
+            const customError = rule.validator(value, { ...context, rawValue: normalizedValue });
+            if (customError) {
+                return {
+                    valid: false,
+                    error: customError,
+                    usage
+                };
+            }
+        }
+        return {
+            valid: true,
+            parsedArgs: [value]
+        };
+    }
+    return {
+        valid: true,
+        parsedArgs: [String(normalizedValue)]
+    };
+}
+function validateArgValue(commandPath, arg, rawValue, rawArgs, parsedArgs, argIndex, displayIndex, usage) {
+    const rules = arg.rules ?? [];
+    const context = {
+        commandPath,
+        argName: arg.name,
+        argIndex,
+        displayIndex,
+        rawArgs,
+        parsedArgs,
+        rawValue
+    };
+    for (const rule of rules) {
+        const result = validateTypedRule(rawValue, rule, context, usage);
+        if (!result.valid) {
+            return result;
+        }
+        if (rule.type) {
+            return result;
+        }
+    }
+    return {
+        valid: true,
+        parsedArgs: [rawValue]
+    };
+}
+function validateRouteArgs(rawArgs, schema) {
+    return validateRouteArgsForCommand(undefined, rawArgs, schema);
+}
+function validateRouteArgsForCommand(commandPath, rawArgs, schema) {
+    const minArgs = getMinArgs(schema);
+    const maxArgs = getMaxArgs(schema);
+    const usage = schema?.usage;
+    if (rawArgs.length < minArgs) {
+        return {
+            valid: false,
+            error: schema?.messages?.tooFewArgs ?? `至少需要 ${minArgs} 个参数`,
+            usage
+        };
+    }
+    if (typeof maxArgs === 'number' && rawArgs.length > maxArgs) {
+        return {
+            valid: false,
+            error: schema?.messages?.tooManyArgs ?? `最多需要 ${maxArgs} 个参数`,
+            usage
+        };
+    }
+    const args = schema?.args ?? [];
+    const parsedArgs = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        const displayIndex = index + 1;
+        const restRule = getRestRule(arg);
+        if (restRule) {
+            const rawValue = rawArgs.slice(index).join(' ').trim();
+            const requiredRule = getRequiredRule(arg);
+            if (!rawValue) {
+                if (requiredRule) {
+                    return {
+                        valid: false,
+                        error: requiredRule.message ?? `参数${displayIndex}是必填的`,
+                        usage
+                    };
+                }
+                if (arg.defaultValue !== undefined) {
+                    parsedArgs.push(arg.defaultValue);
+                }
+                continue;
+            }
+            const result = validateTypedRule(rawValue, restRule, {
+                commandPath,
+                argName: arg.name,
+                argIndex: index,
+                displayIndex,
+                rawArgs,
+                parsedArgs,
+                rawValue
+            }, usage);
+            if (!result.valid) {
+                return result;
+            }
+            parsedArgs.push(...result.parsedArgs);
+            break;
+        }
+        const rawValue = rawArgs[index];
+        if (rawValue === undefined) {
+            const requiredRule = getRequiredRule(arg);
+            if (requiredRule) {
+                return {
+                    valid: false,
+                    error: requiredRule.message ?? `参数${displayIndex}是必填的`,
+                    usage
+                };
+            }
+            if (arg.defaultValue !== undefined) {
+                parsedArgs.push(arg.defaultValue);
+            }
+            continue;
+        }
+        const result = validateArgValue(commandPath, arg, rawValue, rawArgs, parsedArgs, index, displayIndex, usage);
+        if (!result.valid) {
+            return result;
+        }
+        parsedArgs.push(...result.parsedArgs);
+    }
+    return {
+        valid: true,
+        parsedArgs
+    };
+}
+
+export { validateRouteArgs, validateRouteArgsForCommand };

package/lib/index.js

@@ -46,5 +46,9 @@ export { registerAppDir, scheduleCancel, scheduleCancelAll, scheduleCancelByApp,
 export { createEventValue, createSelects, onSelects, onState, unChildren, unState, useState } from './app/event-utils.js';
 export { MessageDirect, createDataFormat, format, getMessageIntent, sendToChannel, sendToUser } from './app/message-api.js';
 export { Format, FormatButtonGroup, FormatMarkDown, FormatSelect } from './app/message-format.js';
+export { Router } from './app/router/dsl.js';
+export { checkFallbackHint } from './app/router/fallback.js';
+export { normalizeRoutePath, parseMessageText } from './app/router/parser.js';
+export { validateRouteArgs } from './app/router/validator.js';
 export { start } from './main.js';
 export { Attachment, Audio, BT, Button, Image, ImageFile, ImageURL, Link, MD, Markdown, MarkdownOriginal, Mention, Text, Video } from './app/message-format-old.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alemonjs",
-  "version": "2.1.68",
+  "version": "2.1.70",
   "description": "bot script",
   "author": "lemonade",
   "license": "MIT",