Pattern Reference
Overview
Karandash supports a 5-tier pattern system for text matching. Each tier compiles to standard regex at config-parse time. The validation engine is unchanged - it receives compiled Regex objects regardless of which tier produced them.
Pattern Tiers
1. Named Patterns (@name)
Zero-regex patterns that expand to well-tested regex. Use @ prefix.
Core Patterns (always available)
Case patterns:
| Pattern | Matches | Example |
|---|---|---|
@kebab-case |
lowercase with hyphens | my-feature |
@snake-case |
lowercase with underscores | my_feature |
@camel-case |
camelCase | myFeature |
@pascal-case |
PascalCase | MyFeature |
@screaming-snake |
UPPER_SNAKE | MY_FEATURE |
@sentence-case |
Starts with uppercase | My feature |
@lower |
all lowercase | feature |
@upper |
all uppercase | FEATURE |
@slug |
URL-safe slug | my-feature-123 |
Structural patterns:
| Pattern | Expands to | Usage |
|---|---|---|
@optional(P) |
(?:P)? |
@optional(@jira-ticket) |
@bracketed(P) |
\[P\] |
@bracketed(ios\|android) |
@parens(P) |
\(P\) |
Wrap in parentheses |
@one-or-more(P) |
(?:P)+ |
One or more occurrences |
@separated-list(P, S) |
P(?:SP)* |
Separated list |
Format patterns:
| Pattern | Matches |
|---|---|
@semver |
1.2.3, 1.0.0-beta.1 |
@email |
user@example.com |
@url |
https://example.com |
@uuid |
UUID v4 |
@date-iso |
2024-01-15 |
@ipv4 |
192.168.1.1 |
Plugin-Registered Patterns
These patterns are available when their plugin module is loaded. When a plugin is published to the registry and installed, its patterns ship with it.
| Pattern | Plugin | Matches |
|---|---|---|
@jira-ticket |
jira-ticket | PROJ-123 |
@jira-ticket(@project:MAPS) |
jira-ticket | MAPS-123 |
@github-issue |
jira-ticket | #42 |
@linear-ticket |
jira-ticket | TEAM-123 |
@shortcut-ticket |
jira-ticket | sc-123 |
@youtrack-ticket |
jira-ticket | PROJ-123 |
@any-ticket |
jira-ticket | Any ticket format |
@conventional-commit |
title-format | feat: add feature |
@conventional-commit(@types:feat,fix) |
title-format | Restricted types |
@branch-prefix(@prefixes:feature,bugfix) |
branch-naming | feature/... |
@wip-marker |
draft | WIP, [WIP], Draft: |
2. Structured Validators
Domain-specific config fields that eliminate regex entirely. Each rule module provides structured alternatives to pattern:.
# title-format - structured config
title-format:
type:
allowed: [feat, fix, docs, chore]
scope:
required: false
subject:
min-length: 10
no-period: true
separator: ": "
# branch-naming - structured config
branch-naming:
prefix-one-of: [feature/, bugfix/, hotfix/]
case: kebab
max-length: 60
# jira-ticket - structured config
jira-ticket:
projects: [MAPS, CORE]
format: jira
# commit-messages - structured config
commit-messages:
type:
allowed: [feat, fix, docs]
subject:
max-length: 72
# draft - structured config
draft:
wip-markers: [WIP, DRAFT, "DO NOT MERGE"]
When structured fields are present and pattern: is not set, the rule builds regex internally from the structured fields. If pattern: is also set, it takes precedence (override escape hatch).
3. Text Glob (glob:)
Simple wildcard matching for text (not file paths):
*- any characters?- single character{a,b,c}- alternation[abc]- character class
Automatically anchored (^...$).
title-format:
pattern: "glob:{feat,fix,chore}: *"
branch-naming:
pattern: "glob:{feature,bugfix,hotfix}/*"
4. Pomsky (pomsky:)
Human-readable regex DSL (language guide). The compiler is built in
(the pomsky-kt library) on every target; no pomsky binary is needed.
title-format:
pattern: "pomsky: let type = 'feat' | 'fix' | 'docs'; ^ type ': ' .+"
karandash config validate and karandash doctor compile every pomsky: value of the config with the pomsky
linter on:
- a compile error fails, naming the config key and marking the bad part with carets;
- a lint diagnostic (unreachable alternative, nested repetition, ReDoS risk) is a warning;
- a pattern whose complexity score is
HIGHis a warning.
The pomsky help text, when there is one, follows on a → How to fix: line:
Config validation failed: rules.titleFormat.pattern: pomsky pattern does not compile: Variable `unknown_ref` doesn't exist
'a' unknown_ref
^^^^^^^^^^^
→ How to fix: Fix the pomsky expression at the marked position.
Warning: rules.branchNaming.patterns[1]: This expression may cause catastrophic backtracking (ReDoS) due to nested quantifiers
→ How to fix: Rewrite to avoid nesting unbounded quantifiers. Use atomic groups or ensure alternatives don't overlap.
doctor lists these under [Patterns] as FAIL: (the run exits 1) and WARN: (does not fail the run).
Fix hints in findings
When a value does not match its format (titleFormat, commitMessages, branchNaming, descriptionFormat,
jiraTicket, contextTag), the finding's message states only the problem. How to fix it is in suggestion:
Change the title to `feat: add login`.- the value with the missing literal parts inserted. Only this kind of fix is applied by--fix(titles only).Change the title to match the format, e.g. `fix: crash on start`.- an example: the pattern's owntest { match ... }case first, else a generated one.
The finding's metadata carries the format for reporters: expectedFormat (readable pomsky, regex patterns
decompiled), mismatch (where the value diverges), formatExplain (the format in words)
and formatDiagram (a text railroad diagram). formatExplain is always English: the built-in rules do not pass
the output language yet, and pomsky-kt explains only in English and Russian, so a pl report would get English
even then.
5. Regex (regex: or bare string)
Standard regex. Bare strings (without prefix) are treated as regex for backward compatibility.
# Explicit regex prefix:
title-format:
pattern: "regex:^(feat|fix): .+"
# Bare string (backward compatible):
title-format:
pattern: "^(feat|fix): .+"
User-Defined Patterns
Define reusable patterns in the patterns: config block. They can reference built-in patterns, plugin patterns, and other user patterns.
patterns:
my-ticket: "@jira-ticket(@project:MAPS)"
my-tag: "@bracketed(ios|android|core)"
my-title: "@optional(@my-tag) @conventional-commit(@types:feat,fix)"
Use in rules:
title-format:
pattern: "@my-title"
jira-ticket:
pattern: "@my-ticket"
Inside a pattern body, an @name that is not a registered pattern is kept as literal text, so an email-like
renovate@bot\.example works. A pattern used directly in a rule (pattern: "@my-titel") must exist.
Condition Operators
Use patterns in conditional expressions alongside existing function syntax:
conditional:
# Glob match (new)
- condition: 'title *= "feat:*"'
- condition: 'branch *= "feature/*"'
# Regex match (new)
- condition: 'title ~= "^(feat|fix):"'
# Exact match (new)
- condition: 'author = "dependabot"'
# Structured predicates (new)
- condition: 'has_ticket("MAPS")'
- condition: 'has_tag("ios")'
# Function syntax (existing, kept)
- condition: 'title_matches("^feat:")'
- condition: 'branch_matches("feature/")'
Multi-Glob Expansion
File-path glob patterns support brace expansion:
ai:
scopes:
backend:
paths: "{src,lib}/**/*.{kt,java}"
# Expands to: src/**/*.kt, src/**/*.java, lib/**/*.kt, lib/**/*.java
Custom Plugin Patterns
Plugin authors can register named patterns via the registerPatterns() lifecycle method:
class MyRuleModule : AbstractTypedSingleRuleModule<MyConfig>() {
override fun registerPatterns(registry: PatternRegistry) {
registry.register("my-pattern", PatternDefinition(
name = "my-pattern",
description = "Matches my custom format",
parameters = listOf(PatternParam(name = "prefix", default = "X")),
expand = { params ->
val prefix = params["prefix"] ?: "X"
"$prefix-\\d+"
},
))
}
}
Users can then use @my-pattern or @my-pattern(@prefix:Y) in their config.
External plugins (JS, WASM, native) register patterns via their respective bridge APIs:
- JS:
context.registerPattern("name", "regex", "description") - WASM:
karandash_register_pattern(name_ptr, name_len, regex_ptr, regex_len) - Native:
karandash_register_pattern(name, regex_string)