feat: R package that emits WordBuilderSwift scripts from R analysis results

[kiki830621]

Problem

Original text:
「我記得我有一個想要用 swift 腳本來做成 word 的想法，我在想是不是可以寫一個 R 的 package 可以直接從分析結果整理成 swift 的 docx 腳本？」
— Source: Claude Code session 2026-04-19

word-builder-swift 0.9.0 (#71) shipped a fluent Swift API for programmatically building .docx — a Swift-side equivalent of docx.js. R users doing statistical analysis still generate Word reports through older toolchains (officer, flextable, rmarkdown → pandoc) that have their own quirks and limited styling control.

Proposal: an R package that serialises R analysis artefacts (data frames, ggplot2 plots, model summaries, character vectors, lists) into a runnable .swift script that imports WordBuilderSwift and emits a .docx. The R function call shells out to swift run, captures the produced .docx, and returns its path to R.

Type

feature

Motivation

• Unifies the "analysis in R, formatted report in Swift" pipeline. R stays the analytical engine; Swift owns layout/styling.
• Keeps word-builder-swift as the single canonical .docx writer across the macdoc ecosystem — R integration becomes "just another caller," not a parallel DOCX generator.
• The produced .swift file is a first-class artefact — committable, re-runnable, reviewable, diffable against last week's report. Beats "black-box PDF" reproducibility by a wide margin.
• Forces a clean R ↔ Swift type mapping (data.frame → Table, ggplot → ImageRun when that lands in Phase 2, character heading → Paragraph(heading:), etc.) — exercising word-builder-swift's API surface and surfacing Phase 2/3 needs.

Expected

R user writes:

library(wordBuilder)  # or whatever the package ends up named

doc <- word_document()
doc <- add_heading(doc, "Q1 Report", level = 1)
doc <- add_paragraph(doc, paste("Revenue grew", scales::percent(0.15)))
doc <- add_table(doc, mtcars[1:5, ])
doc <- add_plot(doc, ggplot(mtcars, aes(mpg, hp)) + geom_point())

render(doc, output = "q1-report.docx")
# Internally:
#   1. Emits q1-report.swift (calls WordBuilderSwift)
#   2. Emits any plot as media/{png}
#   3. `swift run --package-path <tempdir> q1-report.swift`
#   4. Returns path to q1-report.docx

The intermediate q1-report.swift is retained (not deleted) so users can:

• Read / edit it for fine-grained control
• Check it into git alongside R analysis code
• Re-run Swift-side without re-running R

Actual

No such package exists. R users wanting .docx output today use:

• officer + flextable — most common, but styling API is idiosyncratic, Windows-biased, and has long-standing table-inside-body quirks
• rmarkdown → pandoc — converts markdown to docx, but loses fine control over run-level formatting
• Manual copy-paste from R → Word (still the most common "pipeline" in practice)

None of these produce a reviewable intermediate artefact like the Swift script approach would.

Impact

Positive:

• New R-side audience for word-builder-swift (feat: 新增 word-builder-swift — Swift fluent API 直接寫 .docx（類 docx.js） #71) — forces the API to be good enough for scientific/statistical reporting, which often exposes gaps early
• APA-style reporting becomes easier — R already has great citation/bibliography tooling (bibtex, citr); combined with bib-apa-*-swift the Swift-side emission can consume that
• Reports become rerunnable single-file artefacts (the .swift) — superior reproducibility story vs. black-box .docx
• Potentially drives Phase 2 priorities for word-builder-swift (headers/footers, numbering, images — all high-value for scientific reports)

Negative / risk:

• Platform: Swift toolchain is required on the R user's machine. macOS native; Linux requires swift.org toolchain; Windows is painful. Scope is macOS-first, explicitly.
• Dependency surface: R package pulls in nothing extra (pure R + shelling to Swift), but runtime needs swift binary on $PATH. Document prominently.
• Performance: each render() call compiles the generated Swift file (~5–20s for a fresh compile, cached after). Acceptable for "run once per report" workflow; bad for "iterate 50 times" — mitigation: provide a persistent compile cache or a long-lived SPM project under ~/.wordBuilder/.

Scope (Phase 1 MVP)

• R package (proposed name: wordBuilder, rswiftdocx, or docx.swift — open for bikeshed)
• API mirrors word-builder-swift idioms where sensible: word_document(), add_heading(), add_paragraph(), add_text_run(), add_table()
• Code generator: R state → .swift file using WordBuilderSwift
• Shell-out runner: swift run the generated file, return .docx path
• Type mapping Phase 1: character → heading/paragraph, data.frame → Table (no styling), list of character → mixed runs
• Test suite: R-side unit tests (generated .swift matches golden files) + integration test (runs Swift, reads-back .docx via officer to assert content)
• Vignette: "Your first report" translating an existing R markdown example

Scope (later phases, explicitly out)

• ggplot2 → image embedding (needs word-builder-swift Phase 2 ImageRun)
• Table styling / APA format (needs word-builder-swift Phase 2 Styles)
• Cross-references / citations (needs Phase 2 hyperlinks + bookmarks)
• Windows support (revisit when Swift/Windows matures)

Open design questions (for diagnosis)

1. Repo location: PsychQuant/r-word-builder? Separate org? CRAN vs GitHub-only?
2. Package name: any opinion? Short + searchable matters more than clever.
3. Runner abstraction: should render() call macdoc's convert subcommand, or swift run directly on the generated file? (Former keeps macdoc as the single binary surface; latter is more direct.)
4. Intermediate .swift retention: default retain vs default cleanup? Users likely want both modes.
5. ggplot → image: wait for word-builder-swift Phase 2 ImageRun, or inline image embedding as raw OOXML in Phase 1 R-side? Probably wait — scope creep.
6. Relationship to existing R → docx packages: compete with officer, or position as "officer for Swift users who want reviewable intermediates"?
7. Testing strategy: how to assert generated .swift correctness without running Swift in every R CI (Swift toolchain install is slow)? Golden-file comparison + periodic end-to-end runs?

Related

• feat: 新增 word-builder-swift — Swift fluent API 直接寫 .docx（類 docx.js） #71 — word-builder-swift 0.9.0 (the Swift-side API this R package would wrap)
• bib-apa-{html,md,json}-swift — companion citation/bibliography toolchain the R package could leverage
• feat: note-to-html — Notability 筆記轉互動式 HTML 播放器 #64 — note-to-html-swift (different "R → X" territory but same "R as caller" pattern)

Current Status

Phase: diagnosed
Last updated: 2026-04-22 by idd-diagnose (batch)

---

Current Status

Phase: diagnosed / MVP Spectra proposal ready
Last updated: 2026-05-02 by Codex

Key Decisions

• feat: R package that emits WordBuilderSwift scripts from R analysis results #88 should start as a separate PsychQuant R package MVP, not macdoc CLI work.
• Working package name: wordbuilder.
• MVP API covers word_document(), add_heading(), add_paragraph(), add_text_run(), add_table(), and render().
• render() generates Swift directly, runs Swift through a persistent package cache, and retains the generated .swift artifact by default.
• Routine tests should use generated-Swift golden files; Swift compile/readback tests are marked as local or periodic integration tests.

Spectra Proposal

• Change: r-word-builder-mvp
• PR: Propose R wordbuilder MVP #96
• Files: openspec/changes/r-word-builder-mvp/proposal.md, design.md, tasks.md, and specs/r-word-builder-mvp/spec.md
• Validation passed: spectra analyze r-word-builder-mvp --json, spectra validate r-word-builder-mvp, and git diff --check -- openspec/changes/r-word-builder-mvp

Blocking

• Waiting for PR Propose R wordbuilder MVP #96 review/merge.
• After the proposal is accepted, next action is creating/using the implementation repository and applying r-word-builder-mvp there or mirroring the accepted tasks into that repo.

Commits

• cd12010 docs: propose r word-builder mvp

[kiki830621]

Diagnosis

Type

feature (new package, R ecosystem)

Root Cause / Analysis

word-builder-swift (v0.9.0, shipped in #71) provides the fluent Swift API for .docx — a 1:1 Swift mirror of docx.js. The proposal extends reach: an R package that serialises R artefacts (data.frame, ggplot2, character, list) into a runnable .swift file importing WordBuilderSwift, then shells out to swift run and returns the produced .docx path.

Current R-side alternatives (officer, rmarkdown+pandoc) have known quirks (Windows-bias, opaque pipeline). The proposed design's distinctive value:

1. Reviewable intermediate — the generated .swift is a first-class, diffable, re-runnable artefact
2. Unified Writer — keeps word-builder-swift as the single DOCX authoring layer across macdoc + R
3. Reproducibility — beats black-box .docx output from rmarkdown

Impact

• New repo (proposed: PsychQuant/r-word-builder or similar)
• Dependency on word-builder-swift via GitHub release (not SPM — R has no Swift package manager; assume bundled source + local compile)
• No changes to existing macdoc/CLI/packages unless API gaps surface
• Likely to surface missing word-builder-swift Phase 2 features (images, numbering, table styles) faster than pure Swift consumers

Strategy

• /spectra:discuss to scope — the proposal body raises 7 open design questions (repo location, package name, render() calls convert vs swift run directly, intermediate retention, ggplot→image phasing, officer relationship, CI testing strategy)
• Phase 1 MVP per proposal's scope section: text/heading/paragraph/table (no styling), no images, macOS-first
• Golden-file test strategy: generated .swift is asserted against a checked-in golden; end-to-end (run Swift, read-back .docx via R officer) runs locally + periodically, not in every CI
• R package scaffolding: usethis standard layout; DESCRIPTION lists Swift toolchain as SystemRequirements
• Compile cache: ~/.cache/wordBuilder/ with persistent SPM project to avoid cold-compile per render()

Complexity

SDD-warranted — entirely new repo with cross-language surface (R + Swift), platform constraints (macOS-first, Linux secondary, Windows out), CI strategy, and downstream integration with word-builder-swift roadmap (Phase 2 features gate ggplot/styling). Needs /spectra:discuss to scope the MVP before /spectra:propose.

Risks

• Toolchain dependency: Swift binary must be on $PATH. Many R users on macOS do have Xcode CLT, but CRAN submission (if pursued) becomes tricky — probably GitHub-only distribution, at least in Phase 1.
• Cold compile latency: 5-20s per render() — unacceptable for iterative workflow. Persistent SPM project + warm cache is mandatory, not nice-to-have.
• API surface mismatch: R's interactive/mutation patterns (add_* mutating doc state) vs Swift's immutable builder pattern — design risk. Probably R side uses immutable-returning style (doc <- add_heading(doc, ...)) to mirror Swift, which is more idiomatic R anyway.
• Feature gap with officer: officer has 10+ years of iteration. Phase 1 MVP will look thin by comparison. Positioning ("reviewable intermediate") needs to be clear or users will bounce back to officer.
• word-builder-swift roadmap dependency: ggplot→image needs Phase 2 ImageRun; APA-style tables need Phase 2 Styles. Phase 1 MVP is text-only; users wanting full reports have to wait.
• Versioning: how the R package pins which word-builder-swift tag to generate for. Possible: hardcode in R package version's DESCRIPTION; auto-update on major Swift releases.

Related

• feat: 新增 word-builder-swift — Swift fluent API 直接寫 .docx（類 docx.js） #71 — word-builder-swift 0.9.0 (the Swift-side package this wraps)
• bib-apa-*-swift — could be leveraged for citation/bibliography via the generated .swift
• feat: note-to-html — Notability 筆記轉互動式 HTML 播放器 #64 — note-to-html-swift (same pattern: R as caller of a Swift-native converter)

[kiki830621]

🎯 Decision

Original (2026-04-22 diagnosis):
「Needs /spectra:discuss to scope the MVP before /spectra:propose.」

決定

#88 now has a scoped MVP Spectra proposal in PR #96. The MVP targets a future external PsychQuant R package named wordbuilder, not direct macdoc CLI changes.

Rationale

The proposal fixes the main open choices before implementation: generated Swift is the reviewable artifact, render() runs Swift directly through a persistent package cache, generated Swift is retained by default, and tests split fast golden-file code generation from optional integration render/readback tests. This keeps Phase 1 focused on headings, paragraphs, text runs, and plain data-frame tables while deferring ggplot images, APA table styling, citations, headers/footers, numbering, Windows support, and CRAN release decisions.

Related

• PR: Propose R wordbuilder MVP #96
• Spectra change: r-word-builder-mvp
• Validation: spectra analyze r-word-builder-mvp --json, spectra validate r-word-builder-mvp