| 1 | /** |
| 2 | * Matcher shared by both hook dialects. Claude treats alphanumeric/underscore/ |
| 3 | * pipe patterns as literal alternatives and other patterns as regex; Codex |
| 4 | * treats every non-empty pattern as an unanchored regex. Missing, empty, and |
| 5 | * `*` match all. Runtime matching contains invalid regexes as non-matches; |
| 6 | * config parsers use {@link matcherDiagnostic} to reject them with a diagnostic. |
| 7 | * @module @deepseek-ai/dsh-hook-protocol/matcher |
| 8 | */ |
| 9 | |
| 10 | import type { MatcherMode } from './types.ts' |
| 11 | |
| 12 | /** True for an absent / empty / `'*'` pattern — the match-all sentinels. */ |
| 13 | function isMatchAll(matcher: string | undefined): boolean { |
| 14 | return matcher === undefined || matcher === '' || matcher === '*' |
| 15 | } |
| 16 | |
| 17 | /** A Claude-literal pattern is purely word chars + `|` (the regex-vs-literal discriminator). */ |
| 18 | const CLAUDE_LITERAL = /^[A-Za-z0-9_|]+$/ |
| 19 | |
| 20 | /** Compile an unanchored matcher regex; invalid patterns return `undefined`. */ |
| 21 | function compileRegex(pattern: string): RegExp | undefined { |
| 22 | try { |
| 23 | return new RegExp(pattern) |
| 24 | } catch (_syntaxError) { |
| 25 | // RegExp construction is the try's only operation, so malformed pattern |
| 26 | // syntax is the only expected failure. |
| 27 | return undefined |
| 28 | } |
| 29 | } |
| 30 | |
| 31 | /** |
| 32 | * Validate one matcher before a bridge accepts its config group. |
| 33 | * @param matcher - configured pattern; match-all sentinels are valid. |
| 34 | * @param mode - dialect deciding whether a word-and-pipe pattern is literal. |
| 35 | * @returns `undefined` for a valid matcher, otherwise a stable diagnostic. |
| 36 | */ |
| 37 | export function matcherDiagnostic(matcher: string | undefined, mode: MatcherMode): string | undefined { |
| 38 | if (isMatchAll(matcher)) return undefined |
| 39 | const pattern = matcher as string |
| 40 | if (mode === 'claude-code' && CLAUDE_LITERAL.test(pattern)) return undefined |
| 41 | return compileRegex(pattern) === undefined |
| 42 | ? `invalid ${mode} regex matcher ${JSON.stringify(pattern)}` |
| 43 | : undefined |
| 44 | } |
| 45 | |
| 46 | /** |
| 47 | * Whether `matcher` selects `query` under the given dialect. Claude literal |
| 48 | * patterns exact-match pipe-separated alternatives; all other patterns are |
| 49 | * unanchored regexes. Invalid regexes return `false` rather than throwing; |
| 50 | * bridge config parsers surface them through {@link matcherDiagnostic} before use. |
| 51 | * @param matcher - the configured pattern; absent/empty/`'*'` are the match-all sentinels. |
| 52 | * @param query - the candidate value (a tool name, a session source, …). |
| 53 | * @param mode - the dialect deciding literal-vs-regex interpretation of the pattern. |
| 54 | * @returns `true` when the pattern selects the query; `false` on a non-match or an invalid |
| 55 | * regex. |
| 56 | */ |
| 57 | export function matchesMatcher(matcher: string | undefined, query: string, mode: MatcherMode): boolean { |
| 58 | if (isMatchAll(matcher)) return true |
| 59 | // matcher is a non-empty string past the match-all guard. |
| 60 | const pattern = matcher as string |
| 61 | if (mode === 'claude-code' && CLAUDE_LITERAL.test(pattern)) { |
| 62 | return pattern.split('|').includes(query) |
| 63 | } |
| 64 | return compileRegex(pattern)?.test(query) ?? false |
| 65 | } |
| 66 |