rightkit-docs

Product-neutral read and write for DOCX, XLSX and PDF, behind one typed API, for apps and agents that must not trust the files they open. Pure Rust: no Word, no Excel, no LibreOffice, no network.

Use it to read a document into typed content with caps, to create a DOCX or XLSX from typed blocks and cells, or to edit an existing file with typed ops and get a receipt that says what the edit could not keep.

Do not use it to render pages, to recalculate formulas, to open password-protected or macro-enabled files, or for PDF page graphs and font work (that is rightkit-pdf, which this crate wraps for PDF).

Capability: document-io; rightkit owns docx|xlsx|document|spreadsheet resolve to this crate and rightkit owns pdf resolves to rightkit-pdf. Choice of engine and evidence: BAKEOFF.md.

API

use rightkit_docs::{read, write, Block, Op, ReadOptions, Source, WriteOptions};

let path = std::path::Path::new("report.docx");
write(path, &[Op::CreateDocx { blocks: vec![Block::Heading { level: 1, text: "Q3".into() }] }],
      &WriteOptions::default())?;
let doc = read(Source::Path(path), &ReadOptions::default())?;          // format from content
write(path, &[Op::ReplaceText { find: "Q3".into(), replace: "Q4".into() }],
      &WriteOptions { expect_sha256: Some(doc.sha256), ..Default::default() })?;

read(source, &ReadOptions) -> DocumentRead and write(target, &[Op], &WriteOptions) -> WriteReceipt. Every type is serde (camelCase, kind/type discriminators) and every error is a DocsError with a stable snake_case code() and a { code, message } serialisation, like rightkit-pdf's PdfEditError.

Reading

Selection and caps: pages (PDF, 1-based), sheets and an A1 range (XLSX), max_chars and max_cells; any cap that cuts the result sets truncated. sha256 is the hash of the exact bytes read.

omitted names everything the file holds that content does not: comments, tracked changes (inserted text is included, deleted text is not), footnotes and endnotes, images, charts, pivot tables, external links (never followed), drawings, list numbers, scanned PDF pages. Nothing is dropped without being named.

Writing

A call applies its ops in order to one in-memory document and publishes once, through rightkit_fs::AtomicWriter.

PDF create-from-nothing is not in v1.

WriteOptions: expect_sha256 (an edit refuses with source_changed unless the target's current hash matches), overwrite (a create over an existing file), limits.

Publishing. The result is re-detected as the same format before anything is written. The write goes to a temp sibling, is flushed, and a last source-hash recheck runs immediately before the rename; a file changed meanwhile is never overwritten (source_changed), and a create never clobbers a file that appears first (target_exists). Permission bits of the replaced file are kept; a symlink target is replaced where it points and the link survives. A failure before the rename leaves the original and no temp file. The recheck narrows, it does not exclude, another program replacing the file between the recheck and the rename.

Honest losses

An OOXML edit does not rebuild the document from a model. It patches exact byte ranges of the parts it touches and copies every other part raw (same bytes, same compression), so comments, tracked changes, footnotes, charts, notes, data validation, merged ranges, defined names, custom XML, extension parts and anything else this crate does not model survive unchanged. WriteReceipt.touched_parts lists the parts rewritten; everything else is byte-identical. What an edit does change is reported:

A formula cell that is the master of a shared formula, or an array formula, is refused (invalid_op) rather than overwritten.

Safety

All of it is inside this crate, per call, before a parser sees a byte. Defaults are Limits::default(); raise them per call, never process-wide.

Control characters XML cannot carry are dropped from written text.

Limits and gaps

• PDF decompression is bounded while the document loads (rightkit-pdf's loader bound, per stream). Page content streams are decoded later by pdf-extract (its own lopdf 0.42), which this crate cannot bound further than the 64 MiB input cap.
• XLSX read goes through calamine, which reads the whole sheet into memory; the per-part cap bounds that.
• The recheck-before-rename narrows but does not exclude a concurrent writer from another program.
• XLSX dates are numbers plus ISO 8601; no date-typed writes in v1. 1900 serials below 61 have no ISO form.
• Tracked-change, comment and chart authoring are out of scope; they are preserved, not created.
• Hidden-state and 1904-date-system information is reported on read; edits keep it.

Platform support

Pure Rust, macOS and Windows. The only platform-specific behaviour is rightkit-fs's atomic write (and rightkit-pdf's commit code, which this crate does not use). Proofs: see CHANGELOG.

Runtime budget

Class continuous = false: bounded per call, no thread, timer, listener or watcher. The one process-wide object is rightkit-pdf's font catalog, built once on the first PDF text replace or add.