sovr-patch

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:

• Locate: Find all AST nodes matching a rule's pattern
• Classify: Categorize hits into safe, ambiguous, or unsafe based on syntax context
• Transform: Generate patches (diffs) only for safe hits
• 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: [e-mail]