Tianyi Cui
7c400e9c02
Collapse docs/adr/ and docs/rfc/ into a single docs/rfc/ with proposed/, implemented/, and rejected/ subfolders. Every file is renamed to yyyy-mm-dd-topic-title.md, where the date is when the topic was first proposed (from git history). ADRs and RFCs that covered exactly the same topic are merged (property-based testing, session persistence); the umbrella RFC 005 stays split across its three implemented decisions, and RFC 006's deferred part-3 (API extractor reports) splits into its own proposed RFC. All cross-references become machine-checkable relative links instead of bare "ADR NNNN" / "RFC NNN" prose. Add a verify-md-links doc-sync gate (scripts/verify-md-links.ts) that checks every relative Markdown cross-link resolves, wired into doc-sync alongside verify-md-wrap. This makes the reorganization self-verifying: the same change that rewrote ~forty inter-doc links adds the check that proves none dangle. Document the cross-link convention in a new docs/AGENTS.md and record the gate as an implemented RFC. doc-sync, typecheck, lint, and the full test suite (667) all pass.
2.7 KiB
RFC: tsdown for JS bundling instead of dumble
Status: implemented (accepted 2026-06-11)
Context
The initial build used dumble, the cordiverse zero-config esbuild wrapper that upstream Cordis itself builds with — maximum alignment with the vendored packages' conventions (it reads each package.json and infers entries/formats from the exports field). But dumble is a liability as a load-bearing tool in this repo: v0.2.x, ~530 npm downloads/week, effectively one maintainer, and we were invoking it through a custom orchestration script (scripts/build.ts) because it has no workspace mode.
Build output currently matters only for pnpm run build + publint (nothing publishes yet; dev/test/demo run unbuilt via tsx), so the switching cost is at its lowest now and only grows once packages publish.
Decision
Replace dumble with tsdown (rolldown-based, ~2.5M downloads/week, VoidZero-backed, actively released):
- Root
tsdown.config.tswithworkspace: ['vendor/*', 'packages/*'](explicit globs, notworkspace: true, which would also pick upexamples/*— they have package.json files but are not pnpm workspaces). - Shared shape: entry
src/index.ts,outDir: 'lib', ESM,platform: node,target: es2024,fixedExtension: false(keeps.jsfor"type": "module"packages),dts: false(tsc -b owns declarations),clean: false(lib/ holds tsc's .d.ts output). - Two per-package overrides in vendor/ (ours, like the regenerated tsconfigs; logged in vendor/README.md): schemastery (dual
.mjs/.cjsviaoutExtensions), logger-console (two single-entry passes so the shared base class is inlined into each entry instead of a hash-named chunk, matching upstream's published shape). scripts/build.tsdeleted;pnpm run build=tsc -b && tsdown.
Alternatives considered: direct esbuild script (most established engine, zero wrapper risk, but hand-maintains the per-package spec table tsdown's workspace mode gives us); pkgroll (closest drop-in philosophically, but 78k dl/wk and Rollup-based — strictly weaker maintenance story than tsdown); keep dumble (perfect upstream alignment, unacceptable bus factor).
Consequences
Output file lists are byte-for-byte-list identical to dumble's (verified by snapshot diff at migration time); externals still come from each package's dependencies/peerDependencies. We give up dumble's exports-field inference — new packages with non-default shapes need a per-package tsdown.config.ts instead of just package.json fields. Future option: tsdown could also absorb declaration bundling (isolatedDeclarations) if tsc -b ever becomes the bottleneck; that would be a new RFC.