pdftract/notes/bf-a8031-audit.md

Repository Debris Audit

Bead: bf-a8031
Date: 2026-07-05
Scope: Tracked artifacts violating File and Module Layout norms

Summary

This audit cataloged all tracked repository debris across the pdftract workspace. Found 44 files across 5 categories that violate the project's layout norms.

---

Category 1: Scratch Artifacts in Root Directory (13 files)

Python scripts in root (should be in scripts/ or removed):

• assess_doc_coverage.py
• audit_docs.py
• check_content.py
• check_docs.py
• check_examples.py
• fix_fixtures.py
• tmp_fixtures.py

Rust files in root (should be in examples/, tests/, or removed):

• generate_expected_json.rs
• gen_unmapped_comprehensive.rs
• test_js_logging.rs

Shell scripts in root (should be in scripts/ or removed):

• check_doc_coverage.sh
• measure_doc_coverage.sh

Action: All 13 files should be removed. These appear to be temporary development artifacts that have been superseded by tools in scripts/ or crates/.

---

Category 2: Tracked Compiled Binaries (6 files)

ELF binaries in root directory:

• mod — 6.9MB ELF binary
• conformance_test — ELF binary
• test_trailer_parse — ELF binary
• test_trailer_parse2 — ELF binary
• gen_fixtures — Symlink wrapper to ELF binary

ELF binaries in test fixtures:

• tests/sdk-conformance/fixtures/gen_fixtures — 4.4MB ELF binary
• tests/document_model/fixtures/gen_fixtures — 4.4MB ELF binary

Action: Remove all 6 compiled binaries. These are build artifacts that should not be tracked. The test fixture gen_fixtures should be regenerated as needed from source.

---

Category 3: Stray Output Files (6 files)

Temporary outputs in root:

• --1.ppm — 246MB PPM image file (massive disk space waste)
• out.pdf — 1.3KB PDF output
• memory-report.json — 4.3KB memory profiling output
• test_js.pdf — 668B test output
• pdftract-test-merged.cdx.json — 114KB Codecov output
• 0 — Mysteriously named file (likely stray output)

Action: Remove all 6 files. These are temporary outputs from development/testing that should not be committed.

---

Category 4: Tests/Fixtures/ Generator Scripts (18 files)

Generator scripts in tests/fixtures/ root:

• generate_book_chapter_fixtures.rs
• generate_cjk_fixtures_fixed.rs
• generate_cjk_fixtures.rs
• generate_encoding_fixtures.py
• generate_encrypted_fixtures.py
• generate_encrypted_fixtures.rs
• generate_large_remote_fixture.rs
• generate_legal_filing_fixtures.rs
• generate_lzw_fixtures_main.rs
• generate_lzw_fixtures.rs.disabled
• generate_ocr_fixtures.rs
• generate_page_class_fixtures.rs
• generate_scientific_paper_fixtures.rs
• generate_slide_deck_fixtures.rs
• generate_suspects_fixture.rs
• generate_suspects_fixtures.rs
• generate_suspects_fixtures_v5.rs
• PROVENANCE.md (documentation file for fixtures)

Action: FLAG FOR RELOCATION — These generators are legitimate tools for creating test fixtures. They should be moved to tools/ or integrated into xtask/ for proper organization. DO NOT DELETE without relocation plan.

---

Category 5: Non-Standard Root src/ Directory (7 files)

Files in src/ directory (non-standard for workspace layout):

• src/lib.rs
• src/graphics_state/mod.rs
• src/graphics_state/color.rs
• src/graphics_state/diagnostics.rs
• src/graphics_state/matrix.rs
• src/graphics_state/stack.rs
• src/graphics_state/state.rs

Action: Investigate and determine if these are legacy code or active development. If active, relocate to appropriate crate. If legacy, remove.

---

Files NOT Flagged (Intentional Fixtures)

LZW test binaries (14 files) — LEGITIMATE:

• tests/fixtures/lzw_incremental_early.bin through lzw_truncated.bin

These are small (<50 bytes each) intentional test fixtures for LZW decoder testing. They should remain.

Benchmark corpus PDFs (100+ files) — LEGITIMATE:

• benches/competitors/corpus/raster/*.pdf
• benches/competitors/corpus/vector/*.pdf

These are intentionally tracked test corpus for benchmarking. They should remain.

Build artifacts — LEGITIMATE:

• build/font-fingerprints.json
• build/frequency.json
• build/glyph-shapes.json
• crates/pdftract-core/build/*.json

These are generated build data that is intentionally tracked for reproducibility. They should remain.

---

Statistics

Category	File Count	Total Size
Scratch artifacts (root)	13	~500KB
Compiled binaries	6	~20MB
Stray outputs	6	~247MB (mostly --1.ppm)
Generator scripts	18	~200KB
Non-standard src/	7	~50KB
TOTAL	50	~267MB

Note: The 246MB --1.ppm file is the single largest disk space offender.

---

Recommendations

1. Immediate cleanup (safe to remove):

   • Remove all 13 scratch artifacts from root
   • Remove all 6 compiled binaries
   • Remove all 6 stray output files
   • Savings: ~267MB disk space

2. Relocation required:

   • Move 18 generator scripts from tests/fixtures/ to tools/ or xtask/
   • Investigate and handle 7 files in non-standard src/ directory

3. Update .gitignore:

   • Add patterns to prevent future tracking of these file types
   • Consider adding *.ppm, out.pdf, memory-report.json patterns

---

Next Steps

This audit is for bead bf-a8031 (audit only). The actual cleanup will be handled by a follow-up bead.