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

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, 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, the compress_file function invokes the validator immediately after writing output. The CLI entry point in skills/caveman-compress/scripts/cli.py surfaces these results to the user, preventing delivery of corrupted Markdown.

# 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 and 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 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, while the compression orchestration that triggers validation is in skills/caveman-compress/scripts/compress.py and the CLI interface in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}