md4c-sync

name	md4c-sync
description	Check the current md4c upstream release on GitHub and integrate it into this package if newer than the vendored copy. Updates `src/md4c.c`, `inst/include/md4c.h`, and the spec files under `inst/specs/md4c/`, then surfaces any new MD4C enums/flags that may need wrapper updates and runs the test suite.

Sync the vendored md4c sources to the latest upstream release at https://github.com/mity/md4c.

Step 1: Detect currently vendored version

Read the most recent "Based on md4c version X.Y.Z" line from NEWS.md. That is the authoritative record. Note the version as CURRENT.

Step 2: Find the latest upstream release tag

md4c does not publish GitHub Releases — it uses tags of the form release-X.Y.Z. Query:

gh api repos/mity/md4c/tags --jq '.[].name' | grep '^release-' | sed 's/^release-//' | sort -V | tail -5

Pick the highest version as LATEST. If LATEST <= CURRENT, report that the package is up to date and stop.

Step 3: Confirm with the user

Use AskUserQuestion to confirm before fetching:

• Show CURRENT and LATEST.
• Ask whether to proceed with the sync.

If the user wants to pin to a specific tag (not necessarily the highest), let them override via the question's "Other" option.

Step 4: Fetch files from the chosen tag

Use curl against https://raw.githubusercontent.com/mity/md4c/release-<TAG>/<PATH>. Fetch to a scratch directory first, then move into place after Step 5's review. The mapping from upstream paths to package paths is:

Upstream	Package
src/md4c.c	src/md4c.c
src/md4c.h	inst/include/md4c.h
test/LICENSE.md	inst/specs/md4c/LICENSE.md
test/coverage.txt	inst/specs/md4c/coverage.txt
test/regressions.txt	inst/specs/md4c/regressions.txt
test/spec.txt	inst/specs/md4c/spec.txt
test/spec-*.txt	inst/specs/md4c/spec-*.txt

Only overwrite spec files that already exist in inst/specs/md4c/. If upstream introduces new spec-*.txt files (e.g. spec-spoilers.txt, spec-subscripts.txt, spec-superscripts.txt), list them but do NOT add them automatically — they correspond to flags the R wrapper does not yet support, which needs separate wiring. Surface these as a follow-up item for the user.

Use gh api repos/mity/md4c/contents/test?ref=release-<TAG> --jq '.[].name' to enumerate upstream test/ so you can compare against the local set.

Step 5: Review what changed

Before overwriting, run a quick scan of upstream src/md4c.h against the current inst/include/md4c.h to flag wrapper-relevant API changes. Specifically grep for new entries in any of these enums:

• MD_BLOCKTYPE (block kinds; handled in src/markdownparser.cpp::onEnterBlock)
• MD_SPANTYPE (span kinds; handled in src/markdownparser.cpp::onEnterSpan)
• MD_TEXTTYPE (text kinds; handled in src/markdownparser.cpp::onText)
• MD_FLAG_* macros (flags; mirrored in R/flags.R::flags_describe)
• Any new MD_*_DETAIL struct fields (attributes are propagated in src/markdownparser.cpp callbacks)

Also note any signature change to MD_PARSER or the callback prototypes — those would break MarkdownParser::MarkdownParser() in src/markdownparser.cpp.

Report the list of new enum values / flags / struct fields to the user before applying. These are potential wrapper updates the user may want to handle in a follow-up.

Step 6: Apply the file updates

Move the fetched files into place. Run a clean rebuild and the full test suite:

Rscript -e 'devtools::clean_dll(); devtools::test()'

Report pass/fail counts. If tests fail, do NOT proceed to Step 7 — report the failures and ask the user how to handle them. Common reasons:

• A regenerated md4c spec file produces test diffs because spec wording or example numbering changed (spec-driven tests under tests/testthat/test-to_*-md4c.R are auto-regenerated by tests/testthat/helper-tests.R from the new spec files; the diff is expected, but inspect a sample to confirm it is benign).
• A new MD4C behavior changes existing parser output — review the diff.

Step 7: Update bookkeeping

After tests pass:

1. NEWS.md: add a bullet to the development version entry: * Updated vendored md4c to version X.Y.Z. (or create a new entry if the user wants to bump the package version too).
2. DESCRIPTION: if upstream copyright year changed, update the copyright headers/comments. Do NOT modify the package Version field unless the user explicitly asks (they track md4c versions intentionally, with an extra component for in-version package iterations — confirm the version policy with them before changing).
3. Spec files note: if Step 4 surfaced new upstream spec files that were not synced, leave a TODO bullet in NEWS or report it separately so the user can decide whether to wire up the corresponding flag(s) in R/flags.R and the inst/specs/md4c/ directory.

Step 8: Final report

Summarize:

• Version delta (CURRENT → LATEST)
• File counts changed
• Any new enums/flags/struct fields surfaced in Step 5
• Test results
• Any new upstream spec files that were skipped
• Suggested follow-up work, if any

Do not commit. Leave the user to review the diff and commit themselves.

Notes

• The package's MIT license depends on md4c remaining MIT — the upstream LICENSE.md we vendor is the source of truth. If the upstream license file changed, flag that prominently.
• src/httpuv_url_tools.cpp is unrelated (vendored from httpuv) — do not touch.
• Pre-built artifacts (*.o, *.so) under src/ are build outputs; do not touch.
• The package user has stated they intentionally track md4c versions in the package version (0.5.2.X follows md4c 0.5.2). Respect that policy: never bump the major/minor/patch components without explicit confirmation, even after a successful md4c sync.