Add pcf-debug: inspection and visualization tool for PCF files

[kduma]

Summary

This PR introduces pcf-debug, a comprehensive read-only inspection and visualization tool for Partitioned Container Format (PCF) files. The tool walks a file's physical structure defensively, renders layouts and partition tables as text or self-contained HTML, and decodes partition contents through a plugin system.

Key Changes

• New pcf-debug binary crate with minimal dependencies (no external argument parsing or rendering libraries)

  • Defensive file walking that tolerates corruption and surfaces anomalies as diagnostics rather than errors
  • Physical byte-layout modeling with gap and overlap detection
  • Plugin-based partition decoder system for format-specific interpretation

• Core modules:

  • model/walk.rs: Defensive, read-only traversal of the table-block chain with per-block validation
  • model/layout.rs: Physical region mapping (header, table blocks, entries, data, slack, gaps)
  • model/diag.rs: Diagnostic types for structural anomalies (overlaps, truncation, hash mismatches, cycles)
  • plugin/mod.rs: Object-safe decoder trait and registry system
  • plugin/pfs.rs: Decoders for PFS-MS records (PFS_NODE and PFS_SESSION partitions per spec v1.0)
  • plugin/raw.rs: Fallback decoder for any partition type

• Rendering backends:

  • render/text.rs: CLI/ASCII output with byte-map strip, layout, partition table, block chain tree
  • render/html.rs: Self-contained HTML report with inline CSS, collapsible sections, no JavaScript
  • render/hexdump.rs: Classic 16-column hexdump with file offsets
  • render/color.rs: Minimal ANSI coloring with NO_COLOR and TTY detection support

• CLI interface (cli/mod.rs):

  • Subcommands: inspect (default), layout, table, chain, hexdump, decode
  • Global flags: --html, --no-color, --verify/--no-verify
  • Hexdump filtering by region/range with byte limits
  • Decode filtering by UID/label/decoder name

• Comprehensive test suite:

  • tests/decode_pfs.rs: PFS-MS decoder validation (fields, ranges, warnings)
  • tests/diagnostics.rs: Structural anomaly detection (overlaps, truncation, cycles)
  • tests/cli_snapshot.rs: Text renderer output validation
  • tests/html_smoke.rs: HTML report structural integrity
  • tests/common/mod.rs: Shared test fixtures (canonical PCF, PFS records)

Notable Implementation Details

• Defensive design: The walk tolerates file corruption that pcf::Container would reject, capturing anomalies as diagnostics for debugging broken files
• No re-implementation: Reuses the reference crate's public byte parsers (FileHeader::from_bytes, etc.) to stay in sync with the spec
• Renderer independence: Decoders produce a format-agnostic field tree (FieldNode) consumed by both text and HTML renderers, ensuring consistency
• PFS-MS spec compliance: PFS_NODE and PFS_SESSION decoders mirror the spec's byte tables field-for-field, reporting violations as warnings rather than failing
• Workspace integration: Added root Cargo.toml workspace configuration linking the reference crate and new tool

Files Modified

• .gitignore: Expanded with Rust/Cargo, editor, and OS-specific patterns
• .github/workflows/ci.yml: Updated coverage command formatting
• Cargo.toml (new): Workspace root configuration
• tools/pcf-debug/Cargo.toml (new): Binary crate manifest

https://claude.ai/code/session_012g2y2iK7i18XEMYEdQugLK