Implementing Lz77 Cli Compressor

Common Pitfalls

• Rebinding outer variables inside nested functions (Python closure trap).
  In one run, out += ... inside a nested flush_literals() caused: cannot access local variable 'out' where it is not associated with a value.
  Prevent this by mutating instead of rebinding (out.extend(...)) or declaring scope explicitly.

• Continuing pipeline after compression failed.
  When .lz files were never produced, downstream decompress and ratio steps failed with FileNotFoundError.
  Gate each stage: stop and fix the first failure before computing ratios.

• Writing ratios not tied to produced artifacts.
  Tests checked that reported JSON ratios matched actual compressed files.
  Compute ratios directly from filesystem sizes after successful compression.

• Skipping binary-safe handling.
  Text-mode I/O can silently corrupt non-text fixtures. Always use byte mode.

Verification Strategy

Run verification in the same order tests logically require:

1. Artifact existence

   • Confirm compressor.py exists at required path.
   • Confirm results.json exists.

2. Round-trip correctness (per file)

   • For each fixture (small/medium/large/binary):
     • compress
     • decompress
     • cmp -s original decompressed and require exit code 0.

3. Compression-ratio requirement

   • Compute all ratios from real output sizes.
   • Ensure at least one ratio is <= 0.70.

4. JSON format + consistency

   • Ensure required keys are present and numeric.
   • Recompute ratios and confirm they match results.json values.

This strategy matched all observed successful runs and directly prevents the only observed failure mode.

References to Load On Demand

• LZ77/LZSS token design patterns (literal-run + match tokens)
• Python bytearray mutation vs rebinding behavior in closures
• Fast match-finding structures (hash chains, deque/list pruning)