tsc build does not emit dist/generated/conventions.json — `prepare` script leaves dist incomplete

[jstet]

The prepare script in package.json is husky || true; npm run build, where npm run build is just tsc. After tsc, dist/generated/ contains Appearances.js, DdiMappings.js, TypeMappings.js — but not conventions.json, which exists in src/generated/conventions.json and is imported by src/xlsform/validate.ts via import conventions from '"'"'../generated/conventions.json' with { type: '"'"'json' }'.

tsconfig.json already has resolveJsonModule: true and include: src/**/*, so the expectation that the JSON ships to dist/ is reasonable — but it does not.

Reproduction

In any consumer that installs @correlaid/formtransform from GitHub (e.g. CorrelAid/formtransform-app):

rm -rf node_modules/@correlaid/formtransform/dist
npm install   # or bun install + bun pm trust
ls node_modules/@correlaid/formtransform/dist/generated
# Appearances.js   DdiMappings.js   TypeMappings.js
# (no conventions.json)

# building the consumer:
npm run build
# → Could not resolve "../generated/conventions.json"
#   from "node_modules/@correlaid/formtransform/dist/xlsform/validate.js"

Why this matters here

This blocks CorrelAid/formtransform-app issue #4 (adding the library as a dependency). The app-side bun install works, the tsc build of the lib runs without error, but the produced dist/ is not a working browser bundle because validate.js cannot resolve the JSON it imports at runtime. From the app's perspective, a clean install with a working dist/ is the acceptance criterion — and the handover doc explicitly forbids shimming this from the consumer side.

Suggested fixes (upstream, your call)

• Add a JSON-copy step to the build script (e.g. tsc && cp -r src/generated/*.json dist/generated/, or a small node ./scripts/copy-json.mjs); or
• Switch the import ... with { type: '"'"'json' }' to inline the JSON via import attributes + a build step that inlines the content; or
• Commit dist/ (as @correlaid/cdl-design does, in the same monorepo), which makes this build-script bug moot for consumers but requires keeping dist/ in sync with src/.

Whichever path, the deliverable from a consumer's point of view is the same: node_modules/@correlaid/formtransform/dist/generated/conventions.json must exist after a fresh install.

Environment

• @correlaid/formtransform HEAD (542badc as installed by the app)
• TypeScript 5.6.x (per devDependencies)
• bun 1.3.10 / npm 10.x — same result on both

[jstet]

Fixed in 5c6184f (on branch chore/green-quality-gates, not yet on main — the commit closes this issue when it merges).

Root cause, slightly different from the diagnosis. Every module needing the generated conventions imported generated/conventions.json with an import attribute (with { type: 'json' }). tsc does copy that JSON into dist/ here — but only as a side effect of a .ts file importing it, and the resulting dist/xlsform/validate.js still carries a runtime JSON import that the consumer's bundler has to resolve and understand. So the package depended on two things outside its control instead of one.

Fix. codegen now emits src/generated/conventions.ts next to the JSON — same payload, same inferred types — and the six importers (utils/helpers.ts, xlsform/validate.ts, xlsform/sanitize.ts, pipelines/lstsv2ddi/toVariables.ts, pipelines/xlsform2ddi/variables.ts, pipelines/xlsform2lstsv/constants.ts) import that instead. No import attributes remain anywhere in dist/, so there is nothing left for a bundler to disagree about.

The JSON stays as the artifact for non-TypeScript consumers, and npm run build is now tsc && node scripts/copy-generated-json.mjs, so dist/generated/conventions.json is present in an installed package regardless of what imports it — your stated acceptance criterion holds either way.

Verified

• pristine clone, npm run build → dist/generated/ contains Appearances.js, conventions.js, conventions.json, DdiMappings.js, TypeMappings.js
• grep -rn "with { type:" dist/ → no hits
• bun build dist/index.js --target=browser → bundles 55 modules, no error (this is the check that would have caught the original report)
• npm pack --dry-run lists both dist/generated/conventions.js and dist/generated/conventions.json
• npm run validate (7 gates), 707 vitest, 33 pytest, codegen drift guard — all green

One note for CorrelAid/formtransform-app#4: I could not reproduce your install end-to-end here because npm install of this package fetches xlsx from https://cdn.sheetjs.com/..., which is blocked in my environment. Worth re-checking the fresh-install path on your side before closing app-side #4 — if dist/ still comes out incomplete after this fix, the cause is in how the git dependency's prepare runs, not in what tsc emits, and that is a different (and interesting) bug.

[jstet]

You are right, and my earlier comment was wrong in a way worth spelling out: 5c6184f existed only in a local clone. "on branch chore/green-quality-gates, not yet on main" reads as pushed but unmerged; it was neither. Sorry for the 404 hunt.

The branch is pushed now:

• branch: https://github.com/CorrelAid/formtransform/tree/chore/green-quality-gates
• the fix: 5c6184f

main is still 542badc, so a clean reinstall of the default branch will keep producing the old dist/ until this merges. To test before then, point the dependency at the branch:

"@correlaid/formtransform": "github:CorrelAid/formtransform#chore/green-quality-gates"

Two caveats on that branch, so you know what you are pulling in: it also carries the quality-gate fixes and three handover documents, and the doc links pointing at blob/main/... will 404 until it merges. Neither affects the library's behaviour.

Everything in my previous comment about the fix itself stands — the substance was verified, only its location was not. One thing I still cannot check here: the end-to-end fresh install, because npm install of this package fetches xlsx from https://cdn.sheetjs.com/... and remote tarballs are blocked in my environment. So please do confirm on your side that dist/generated/conventions.json is present after installing from the branch. If it is still missing there, the cause is in how the git dependency's prepare runs rather than in what tsc emits, and I would want that reopened as a separate bug.

[jstet]

Merged to main in #2 — main is now f26b07f, and 5c6184f is reachable there (merge commit, not a squash, so that SHA is unchanged).

Important if you already switched your dependency to the branch: chore/green-quality-gates was deleted on merge, so the ref I gave you earlier no longer resolves. Point it back at the default branch:

- "@correlaid/formtransform": "github:CorrelAid/formtransform#chore/green-quality-gates"
+ "@correlaid/formtransform": "github:CorrelAid/formtransform"

A clean reinstall from main should now give you dist/generated/conventions.json plus dist/generated/conventions.js, with no import attributes anywhere in dist/. Please confirm on your side — the one thing I could not test is the fresh-install path end to end, since npm install of this package fetches xlsx from cdn.sheetjs.com and remote tarballs are blocked in my environment. If the JSON is still missing after installing from main, that is a prepare-execution problem rather than a tsc emit problem; open a new issue and I will look at it as a separate bug.

Also note the docs referenced from the handover documents now resolve, since they landed on main in the same PR.