# Does Caveman Preserve Code Blocks, Error Strings, and CLI Commands Exactly?

> Caveman ensures precise preservation of code blocks, error strings, and CLI commands. Experience byte-for-byte identity for your original Markdown content.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: deep-dive
- Published: 2026-07-08

---

**Caveman validates every compression to ensure that fenced code blocks, inline code, and CLI commands remain byte-for-byte identical to the original Markdown.**

When compressing Markdown documentation, maintaining the integrity of executable content is critical. The **Caveman** tool developed by JuliusBrussee includes a rigorous validation step that explicitly checks whether **code blocks, error strings, and CLI commands** survive the compression process unchanged. This verification ensures that developers receive compressed files where every back-ticked command and fenced block remains exactly as it was in the source.

## How Caveman Validates Code Block Preservation

### Extracting and Comparing Fenced Code Blocks

Inside [`skills/caveman-compress/scripts/validate.py`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/validate.py), the **`extract_code_blocks`** function pulls every fenced code block from both the original and compressed Markdown. The validator compares these two lists directly, and if any discrepancy appears, it records the error *"Code blocks not preserved exactly"* (lines 121-124). This comparison runs character-by-character, ensuring that error strings and command outputs inside triple backticks remain untouched.

### Monitoring Inline Code and CLI Commands

For inline snippets, the **`extract_inline_codes`** function gathers all back-ticked content—including CLI commands like `` `git commit` ``. The validator uses a Python **`Counter`** to compare the original and compressed sets (lines 154-166). If a command disappears or changes, Caveman emits an error such as *"Inline code lost …"* and flags the compression as invalid.

## The Validation Workflow

The validation step executes automatically after every compression attempt. In [`skills/caveman-compress/scripts/compress.py`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/compress.py), the **`compress_file`** function invokes the validator immediately after writing output. The CLI entry point in [`skills/caveman-compress/scripts/cli.py`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/cli.py) surfaces these results to the user, preventing delivery of corrupted Markdown.

```python

# Example: Run Caveman compression on a Markdown file

from pathlib import Path
from skills.caveman_compress.scripts.compress import compress_file
from skills.caveman_compress.scripts.validate import validate

orig = Path("example.md")
compressed = Path("example.caveman.md")

# Compress the file

compress_file(orig, compressed)

# Validate that code blocks and CLI commands stayed intact

result = validate(orig, compressed)
if not result.is_valid:
    # Will include "Code blocks not preserved exactly" if any block changed

    print("Validation failed:", result.errors)
else:
    print("Compression succeeded – all code blocks and CLI commands preserved.")

```

Running the above produces an error list such as:

```

Validation failed: ['Code blocks not preserved exactly']

```

if any fenced block differs, or:

```

Validation failed: ['Inline code lost: {'git commit -m "msg"'}']

```

when an inline CLI command is lost or altered.

## Summary

- Caveman extracts fenced code blocks using `extract_code_blocks` and requires exact matches between original and compressed files.
- Inline CLI commands are tracked via `extract_inline_codes` and compared with a `Counter` to detect any loss or alteration.
- Validation runs automatically after every compression in [`compress.py`](https://github.com/JuliusBrussee/caveman/blob/main/compress.py) and [`cli.py`](https://github.com/JuliusBrussee/caveman/blob/main/cli.py), halting delivery if code blocks or error strings are not preserved exactly.

## Frequently Asked Questions

### What happens if Caveman changes a code block during compression?

If any fenced code block differs between the original and compressed file, the validator in [`validate.py`](https://github.com/JuliusBrussee/caveman/blob/main/validate.py) records the error *"Code blocks not preserved exactly"* and marks the compression as invalid. The user receives an error message instead of the broken output.

### Does Caveman check single backtick inline commands like `npm install`?

Yes. The `extract_inline_codes` function captures all inline code wrapped in single backticks, including CLI commands. The validator compares these using a `Counter` and reports *"Inline code lost …"* if any command is altered or missing.

### Where does the validation occur in the Caveman source code?

The validation logic lives in [`skills/caveman-compress/scripts/validate.py`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/validate.py), while the compression orchestration that triggers validation is in [`skills/caveman-compress/scripts/compress.py`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/compress.py) and the CLI interface in [`skills/caveman-compress/scripts/cli.py`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/cli.py).

### Can Caveman compression succeed if error strings inside code blocks are modified?

No. Because the validation requires exact preservation of code block content, any modification to error strings, stack traces, or command outputs inside triple backticks causes the validation to fail and prevents the compression from being accepted.