SOVR Patch: Rule Engine v0.2

Stop grepping. Start patching.

sovr-patch is an AST-based code migration engine designed for safe, deterministic, and verifiable TypeScript refactoring.

It is built as the foundation for the AI Mechanical Work Compressor — shifting AI's role from writing unverified code to orchestrating deterministic AST rules.

Architecture

The engine is built around a 4-phase pipeline:

1. Locate: Find all AST nodes matching a rule's pattern
2. Classify: Categorize hits into safe, ambiguous, or unsafe based on syntax context
3. Transform: Generate patches (diffs) only for safe hits
4. Verify & Apply (safe-apply):
   • Apply patches to a temporary copy of the repository
   • Run the TypeScript compiler (tsc --noEmit) against the patched copy
   • Only if verification passes, write the changes to the real repository

Usage

1. List available rules

npx sovr-patch list-rules

2. Dry-run a rule (Preview)

npx sovr-patch run \
  --rule field-rename \
  --from "config.baseUrl" \
  --to "config.apiBaseUrl" \
  --repo ./my-repo \
  --report

3. Safe-apply a rule (Verify & Write)

npx sovr-patch run \
  --rule field-rename \
  --from "config.baseUrl" \
  --to "config.apiBaseUrl" \
  --repo ./my-repo \
  --apply \
  --report

4. Audit your codebase

npx sovr-patch audit --repo ./my-repo --report

5. CI Gate

npx sovr-patch ci-gate --repo ./my-repo

Rules (v0.2)

| Rule | Priority | Description | |------|----------|-------------| | field-rename | P0 | Safe TypeScript field rename across value refs, property keys, type fields, this. chains, destructuring, and shorthand properties | | nullish-fallback | P0 | Inject ?? fallback for repeated property access targets. Chain-aware, operator-precedence-aware | | design-token | P1 | Replace hardcoded hex color values with CSS custom property references. Supports presets and dual-mode audit | | inline-style | P1 | Convert JSX inline style objects to className strings. Supports presets and dual-mode audit |

The Rule Contract

Every rule in sovr-patch implements a strict interface:

export type RuleDefinition<TConfig> = {
  name: string;
  description: string;

  parseConfig(input: Record<string, unknown>): TConfig;

  locate(context: RuleContext<TConfig>): RuleLocateResult[];

  classify(located: RuleLocateResult, context: RuleContext<TConfig>): RuleScanHit;

  transform(hit: RuleScanHit, context: RuleContext<TConfig>): PatchOp | null;
};

This enforces the separation of concerns: locating nodes is separate from determining if they are safe to modify, which is separate from generating the actual text replacement.

Directory Structure

src/
├── cli/          # Command-line interface and argument parsing
├── commands/     # CLI command implementations (run, audit, ci-gate, list-rules, activate, status)
├── core/         # Core engine, types, report generation, safe-apply, license validation
├── audit/        # Dual-mode audit engine, packs, report generation
├── patch/        # Patch application, overlap detection, diff generation
└── rules/        # Rule implementations
    ├── field-rename/     # Rule: Safe object field renaming
    ├── nullish-fallback/ # Rule: Inject ?? fallback
    ├── design-token/     # Rule: Hardcoded hex → CSS custom properties
    ├── inline-style/     # Rule: JSX inline styles → className
    ├── registry.ts       # Rule registration
    └── types.ts          # Rule contract interface

Tests

npm run ci

Runs the CI gate, which includes:

• TypeScript build check
• Unit tests (scan, rewrite, safe-apply)
• Engine integration tests
• CLI smoke tests
• Trial regression tests

Pricing

| Tier | Price | Rules | |------|-------|-------| | Free | $0 | Scan + audit (all rules, read-only) | | Pack A — Safe TS Migration | $99 | field-rename + nullish-fallback | | Pack B — Frontend Refactor | $99 | design-token + inline-style | | Full Engine | $249 | All rules + CI Gate + presets |

Purchase at www.sovrpatch.com

License

Business Source License 1.1

Copyright (c) 2026 SOVR. Contact: [email protected]