effect-regex

name	Effect Regex
description	Expert regex pattern generation, optimization, testing, and explanation using deterministic AST-based construction. Use when user needs to create, test, optimize, or understand regex patterns, parse CLI commands, validate inputs, or build complex text matching patterns.
allowed-tools	Bash, Read, Write, Edit

Effect Regex Skill

Overview

The Effect Regex skill provides expert assistance with regex pattern development using a deterministic, AST-based approach. It excels at creating maintainable, testable regex patterns with multi-dialect support (JavaScript, RE2, PCRE).

When to Use This Skill

Use Effect Regex when the user needs to:

• Create regex patterns from natural language descriptions
• Test regex patterns against test cases
• Optimize existing regex patterns for performance
• Explain complex regex patterns in human terms
• Parse CLI command structures
• Build patterns for log parsing, input validation, or data extraction
• Convert patterns between regex dialects (JS, RE2, PCRE)
• Generate AI-powered patterns from examples

Core Capabilities

1. Pattern Building from Standard Library

Build vetted patterns instantly from the standard library:

Tier 1 (CLI-focused):

• quotedString - Single/double quoted strings with escape handling
• keyValue - Key-value pairs (key=value)
• pathSegment - Directory/file names
• filePathBasic - Unix/Windows file paths
• csvList - Comma-separated values
• integer - Signed integers

Tier 2 (Advanced):

• uuidV4 - UUID version 4 format
• semverStrict - Semantic versioning (strict)

Tier 3 (Utility):

• ipv4 - IPv4 addresses
• ipv6Compressed - IPv6 addresses (compressed format)
• float - Floating-point numbers
• isoDate - ISO 8601 dates (YYYY-MM-DD)
• isoDateTime - ISO 8601 date-times

Command:

cd effect-regex/effect-regex
node dist/bin.cjs build-pattern <pattern-name>

2. Pattern Testing

Test patterns against positive and negative test cases with timeout protection:

cd effect-regex/effect-regex
node dist/bin.cjs test "<pattern>" test-cases.json

Test cases format:

{
  "positive": ["match1", "match2"],
  "negative": ["nomatch1", "nomatch2"]
}

3. Pattern Optimization

Optimize patterns using 4 AST transformation passes:

• Constant Folding: Merge adjacent literals
• Quantifier Simplification: Remove redundant nested quantifiers
• Character Class Merging: Combine alternating character classes
• Alternation Deduplication: Remove duplicate alternatives

cd effect-regex/effect-regex
node dist/bin.cjs optimize <pattern-name>

Returns before/after patterns with metrics (nodes reduced, reduction percentage).

4. Pattern Linting

Validate patterns for syntax errors and dialect compatibility:

cd effect-regex/effect-regex
node dist/bin.cjs lint "<pattern>"

Returns validation results with severity levels (error, warning, info).

5. Pattern Explanation

Get human-readable explanations of pattern structure:

cd effect-regex/effect-regex
node dist/bin.cjs explain "<pattern>"

Working with Effect Regex

Setup

The CLI is pre-built in effect-regex/effect-regex/dist/bin.cjs. Always run commands from the effect-regex/effect-regex directory.

Output Format

All commands output JSON for easy parsing:

{
  "pattern": "/regex/pattern/",
  "notes": ["any warnings or notes"],
  "captureMap": {"groupName": 1}
}

Best Practices

1. Start with Standard Library: Check if a standard pattern exists before building custom ones
2. Test Early: Always test patterns with real examples
3. Optimize After Testing: Run optimization after confirming correctness
4. Consider Dialect: Specify target dialect (js/re2/pcre) for compatibility
5. Use Linting: Validate patterns before deployment

Common Workflows

Creating a New Pattern

1. Check standard library: node dist/bin.cjs build-pattern <name>
2. If custom needed, describe requirements to user
3. Build pattern using programmatic API or MCP tools
4. Test with sample data
5. Optimize for performance
6. Validate with linting

Debugging a Pattern

1. Explain pattern structure: node dist/bin.cjs explain "<pattern>"
2. Test with failing cases
3. Identify issues from test results
4. Refine and re-test

Optimizing Performance

1. Run optimizer: node dist/bin.cjs optimize <pattern-name>
2. Review metrics (nodes reduced, passes applied)
3. Test optimized pattern for correctness
4. Use RE2 dialect for production if backtracking concerns exist

Integration Options

MCP Server (for AI Assistants)

The MCP server provides 8 tools for AI-powered pattern development:

cd effect-regex/effect-regex
node dist/server.cjs

Available via MCP protocol for Claude Desktop, Cline, etc.

Programmatic API

Import and use Effect-based TypeScript API:

import { RegexBuilder, emit } from "./core/builder.js"
import { optimize } from "./core/optimizer.js"
import { testRegex } from "./core/tester.js"

Technical Reference

For detailed technical information, see:

• reference.md - API documentation and AST structure
• examples.md - Comprehensive usage examples
• ../../../README.md - Project overview and setup

Error Handling

• Pattern too complex: Use optimization to reduce complexity
• Catastrophic backtracking: Add timeout protection or use RE2 dialect
• Dialect incompatibility: Check lint warnings and convert to compatible dialect
• Test failures: Review test output for specific failure details

Advanced Features

CommandSpec Builder

Generate regex from CLI command specifications:

• Parse command syntax (flags, options, arguments)
• Generate matching patterns with semantic capture maps
• Useful for CLI parsers and command validators

AI-Powered Generation

The MCP server includes propose_pattern tool that uses Anthropic Claude API:

• Generates patterns from natural language descriptions
• Provides confidence scores
• Iterative refinement based on test results
• Automatic fallback to heuristic generation

Performance Characteristics

• Pattern emission: <5ms average
• Test execution: ~2ms per test case (excluding timeout cases)
• Optimization: Fixed-point iteration (max 5 passes)
• Timeout protection: 100ms default for backtracking detection

Support and Resources

• Standard library: 13 vetted patterns across 3 tiers
• Test coverage: >90% across core functionality
• Effect-based architecture for type safety and composability
• Multi-dialect support: JavaScript, RE2, PCRE