Skip to content

DOCX: expose actionable Typst diagnostics for conversion failures #107

@developer0hye

Description

@developer0hye

Summary

DOCX conversion failures from Typst compilation are currently hard to debug because the surfaced error is too generic.

Problem

When Typst compilation fails, the current error path does not provide enough context (exact line/column, local source snippet, and stable stage attribution). This increases turnaround time for parser/codegen fixes.

Proposal

  1. Extend PDF rendering error propagation to include:
  • stage (typst_codegen vs typst_compile)
  • line/column (when available)
  • primary diagnostic message
  • short source snippet around the failing location
  1. Add opt-in debug artifact dumping:
  • library option: ConversionOptions::dump_typst_on_error: Option<PathBuf>
  • CLI option: --dump-typst-on-error <dir>
  • default behavior remains safe (no persistent dump unless explicitly enabled)
  1. Make diagnostics machine-readable for tests:
  • add structured error fields rather than only a flattened string

Code Areas

  • crates/office2pdf/src/render/pdf.rs
  • crates/office2pdf/src/error.rs
  • crates/office2pdf-cli/src/main.rs

Acceptance Criteria

  • A forced Typst compile failure reports line/column and stage.
  • Error output includes a compact snippet with pointer to failing token.
  • With --dump-typst-on-error, generated Typst source is written to disk and path is printed.
  • New tests cover both default and debug-dump modes.

Non-Goals

  • No change to document layout behavior in this issue.
  • No fixture content from private/internal corpora is embedded in tests or logs.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions