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:
```bash
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:

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

Test cases format:
```json
{
  "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

```bash
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:

```bash
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:

```bash
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:
```json
{
  "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:
```bash
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:
```typescript
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](reference.md) - API documentation and AST structure
- [examples.md](examples.md) - Comprehensive usage examples
- [../../../README.md](../../../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