The Healing Engine

Yamlr consists of two core utilities: The Scanner and The Healer.

The Healing Engine was built to execute massive, multi-file codebase refactors without ever introducing a single breaking typographical error into a proprietary production architecture.

1. Visual Diffing & Interactive Flow

By default, the yamlr heal . command is highly interactive.

Before writing a single byte to disk, the engine formats a color-coded visual diff directly in your terminal. For batch operations, it will request explicit confirmation before applying mutations:

bash
? Apply these 14 structural repairs across 3 files? (y/N)

(Type CONFIRM for batch sessions or y for single files).

(Note: In automated pipelines, this can be bypassed using the --yes-all automated healing flag).

2. 3-Tier Status Verification

The Healing Engine operates on a principle of absolute architectural integrity. When a file is modified, Yamlr performs a real-time, 3-tier analysis on the new Abstract Syntax Tree.

Every mutation must pass:

[PHY] (The Physics Layer): Validates YAML syntax, indentation, and list-marker closures.
[KBS] (The Schema Layer): Validates against the strict Kubernetes OpenAPI catalog for the target cluster version.
[SEM] (The Semantic Layer): Validates the ResourceGraph for internal consistency (e.g., ensuring a newly injected Selector still binds to a valid Pod).

If an automated fix breaks any of these three tiers in the resulting output, Yamlr will abort the write and report the file as FAILED TO HEAL. We prioritize safety over convenience.

3. Map vs. List Conversion (Structural Trauma)

A common point of silent failure in Kubernetes is providing a YAML Map where a YAML List is expected (or vice versa). E.g., providing env: { name: "DB" } instead of env: [ { name: "DB" } ].

The Healing Engine includes a dedicated sub-graph engine capable of seamlessly converting these nested data structures in-place without deleting the inner context.

4. Unbreakable Snapshots

Even with algorithmic guarantees, engineers need absolute confidence before allowing a CLI tool to mutate infrastructure code.

Yamlr features a multi-layered State Recovery system:

Atomic Rollback: To revert an entire mass-healing session into its pre-mutation state using the forensic session journal, execute:
```
bash
yamlr rollback [session_id]
```
Individual Restore: To recover a specific file from its most recent backup in .yamlr/backups/, execute:
```
bash
yamlr restore <target-file>
```

(Note: Yamlr strictly retains the last 5 healing snapshots by default).