fix(sdk): give CommonJS consumers their own type declarations by EricAndrechek · Pull Request #792 · Wave-RF/WaveHouse

EricAndrechek · 2026-10-09T15:14:58Z

Summary

A TypeScript project compiled as CommonJS ("type": "commonjs", moduleResolution node16/nodenext) got TS1479 importing @wavehouse/sdk, though require() worked at runtime. The package is "type": "module" and exports["."] gave import and require one shared types entry, dist/index.d.ts, which TypeScript reads as ESM.

exports["."] now has per-condition typings: import carries index.d.ts and index.js, require carries index.d.cts (already emitted by the build, previously unreferenced) and index.cjs. Top-level main, module and types are unchanged. The codegen bin and the IIFE bundle ship no declarations, so they need nothing.
make smoke-ts-dist (run by make build-ts) compiles a CommonJS and an ESM consumer against the built package with tsc --module node16, offline, from a scratch project that resolves the package by name. It also checks the exports typings and defaults against the top-level fields and the files on disk.
Docs: the SDK guide's Node CJS section names the .d.cts declarations, and the development guide, make help and the SDK README describe the new type check.
README release badge: its filter=!client excluded only a tag named exactly client, so the newest SDK release won and the badge read release: clients/ts/v0.1.1. It now selects the server tags with filter=v* and reads release: v0.1.0 (both rendered against shields.io).

Test plan

Before: the new check against the old package.json fails with TS1479 for the CommonJS consumer only; the ESM consumer compiles.
After: both consumers type-check; require() and import still resolve through the exports map and expose the same 12 names.
make build-ts green (build, then the smoke at the oldest supported Node, v22.0.0).
Commit-time make verify green.

Related Issues

Closes #751. Part of #740.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Wjv2nu841pxTMdUWSAPmDH

The package is "type": "module" and exports["."] shared one types entry (dist/index.d.ts) between import and require, which TypeScript reads as ESM. A CommonJS project under node16/nodenext resolution got TS1479 on import even though require() works. Give import and require their own types and default, pointing require at the dist/index.d.cts the build already emits. smoke-ts-dist now compiles a CommonJS and an ESM consumer against the built package with tsc --module node16, offline, and the exports fields are checked against the files. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Wjv2nu841pxTMdUWSAPmDH

The development guide, the Makefile comments and help text still described build-ts as only smoke-loading the entry points. The SDK page's CommonJS section now notes the matching .d.cts declarations. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Wjv2nu841pxTMdUWSAPmDH

The badge filtered out only a tag named exactly "client", so the SDK release clients/ts/v0.1.1 won and the badge read that instead of v0.1.0. Select the server tags (v*) instead of excluding one name. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Wjv2nu841pxTMdUWSAPmDH

coderabbitai · 2026-10-09T15:15:08Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Advanced
Run ID: e03e684c-e402-460d-8ed3-bfe24539978f

📥 Commits

Reviewing files that changed from the base of the PR and between b9069da and fa8705a.

📒 Files selected for processing (8)

CHANGELOG.md
Makefile
README.md
clients/ts/README.md
clients/ts/package.json
clients/ts/scripts/smoke-dist.mjs
docs/src/content/docs/development.md
docs/src/content/docs/sdk/index.mdx

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📜 Recent review details

⏰ Context from checks skipped due to timeout. (1)

GitHub Check: Coverage

🧰 Additional context used

📚 Code guidelines (4)

README.md — auto-discovered
AGENTS.md — auto-discovered
CONTRIBUTING.md — auto-discovered
docs/src/content/docs/development.md — auto-discovered

📓 Path-based instructions (5)

Source excerpt: Pick between the in-repo Docker Compose, pulling a container image, or `go install`.

📄 CodeRabbit inference engine (README.md)

Files:

README.md

Source excerpt: **Editors see WH001 in `.md` only.**

📄 CodeRabbit inference engine (AGENTS.md)

Files:

docs/src/content/docs/sdk/index.mdx

Source excerpt: **Docs prose**: never hard-wrap Markdown — one paragraph is one line.

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Files:

docs/src/content/docs/sdk/index.mdx

Source excerpt: Run `make fix` to apply them.

📄 CodeRabbit inference engine (docs/src/content/docs/development.md)

Files:

docs/src/content/docs/sdk/index.mdx
README.md
docs/src/content/docs/development.md
CHANGELOG.md
clients/ts/README.md

Source excerpt: **WH001 applies to every tracked Markdown file, with no carve-out** — `AGENTS.md`, `CHANGELOG.md`, `.github/` CI docs and `.claude/` agent prompts included.

📄 CodeRabbit inference engine (AGENTS.md)

Files:

README.md
docs/src/content/docs/development.md
CHANGELOG.md
clients/ts/README.md

🔇 Additional comments (1)

README.md (1)

22-22: LGTM!

📝 Summary

Summary by CodeRabbit

New Features
- TypeScript projects using Node16 or NodeNext resolution now receive declarations matched to their CommonJS or ESM usage.
Documentation
- Updated SDK guidance to explain TypeScript support for CommonJS consumers.
- Clarified that the build check validates both CommonJS and ESM TypeScript consumers.

Walkthrough

The SDK package now provides separate runtime and declaration targets for ESM and CommonJS consumers. Its smoke check validates export targets and type-checks both consumer formats with Node16 module resolution. The README release badge now filters tags matching v*.

Changes

SDK TypeScript declarations

Layer / File(s)	Summary
Conditional package exports `clients/ts/package.json`, `docs/src/content/docs/sdk/index.mdx`, `CHANGELOG.md`	The root export maps ESM consumers to `index.js` and `index.d.ts`, and CommonJS consumers to `index.cjs` and `index.d.cts`. The SDK documentation and changelog describe the conditional targets.
Consumer type-check smoke test `clients/ts/scripts/smoke-dist.mjs`, `Makefile`, `clients/ts/README.md`, `docs/src/content/docs/development.md`	The smoke check validates conditional export targets and compiles temporary CommonJS and ESM consumers using `tsc` with Node16 resolution. The Makefile and documentation describe these checks.

Release badge filter

Layer / File(s)	Summary
Tag filter `README.md`	The GitHub Release badge now filters tags matching `v*`.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: taitelee

Merge Risk: ⚪ Minimal · up to fa870

No actionable issue is established; the change is mergeable after normal checks.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check		The `README.md` release badge change from `filter=!client` to `filter=v*` does not support issue `#751`. It does not change SDK exports, declarations, CommonJS behavior, or related tests. The package ch…	Revert the unrelated `README.md` release badge change, or move it to a separate pull request.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check		Issue `#751` requires TypeScript CommonJS consumers using Node16 or NodeNext resolution to avoid TS1479 while preserving runtime require(). `clients/ts/package.json` maps `exports["."].require.types` to…
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…
Title check		The title clearly and concisely describes the main change: providing separate type declarations for CommonJS consumers of the SDK.
Description check		The description directly explains the CommonJS TypeScript issue, the conditional export changes, validation steps, documentation updates, and related issue.

Full details: Out of Scope Changes check

Explanation

The README.md release badge change from filter=!client to filter=v* does not support issue #751. It does not change SDK exports, declarations, CommonJS behavior, or related tests. The package changes, smoke checks, documentation, Makefile text, and changelog entry remain connected to the SDK typing fix.

Fix all pre-merge checks with AI

✨ Finishing Touches

📝 Generate docstrings

Commit to this branch
Create a new PR

🧪 Generate unit tests (beta)

Commit to this branch
Create a new PR

✨ Simplify code

Commit to this branch
Create a new PR

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

github-actions · 2026-10-09T15:17:50Z

📚 Docs preview is live → https://ada68284-wavehouse-docs.wave-rf.workers.dev

Commit — fa8705a: Merge origin/main into fix/sdk-cjs-types
Author — @EricAndrechek, Claude Opus 5.5
Committed — 2026-10-09 14:12 (UTC-04:00)
Deployed — 2026-10-09 14:38 EDT

github-code-quality · 2026-10-09T15:19:09Z

Code Coverage Overview

Languages: Go

Go

The overall line coverage in commit fa8705a in the fix/sdk-cjs-types branch remains at 93%, unchanged from commit b9069da in the main branch.

Show a line coverage summary of the most impacted files.

File	`main` b9069da	`fix/sdk-cjs-types` fa8705a	+/-
`internal/mq/nats_topology.go`	92%	91%	-1%
`internal/mq/external.go`	85%	85%	0%

_{Updated October 09, 2026 18:32 UTC}

EricAndrechek · 2026-10-09T17:34:17Z

@coderabbitai review

coderabbitai · 2026-10-09T17:34:25Z

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Brings in #786 and the PRs merged since. CHANGELOG.md conflicted only because two new Fixed entries landed at the same spot; both are kept. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Wjv2nu841pxTMdUWSAPmDH

EricAndrechek · 2026-10-09T18:32:32Z

@coderabbitai review

coderabbitai · 2026-10-09T18:32:40Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Both PRs added their Fixed entries at the top of the section after merging main, so whichever merged second would conflict. These now sit below the TestClaims entry from main. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Wjv2nu841pxTMdUWSAPmDH

EricAndrechek and others added 3 commits October 9, 2026 10:47

github-project-automation Bot added this to WaveHouse Task Board Oct 9, 2026

github-actions Bot added documentation Improvements or additions to documentation dependencies Pull requests that update a dependency file area/sdk TypeScript SDK (clients/ts/) area/docs Documentation, site/, README area/infra CI, build, deploy, Docker, release labels Oct 9, 2026

coderabbitai Bot approved these changes Oct 9, 2026

View reviewed changes

EricAndrechek marked this pull request as ready for review October 9, 2026 18:35

EricAndrechek requested review from a team and taitelee October 9, 2026 18:35

EricAndrechek merged commit 3582039 into main Oct 9, 2026

EricAndrechek deleted the fix/sdk-cjs-types branch October 9, 2026 18:39

github-project-automation Bot moved this from Backlog to Done in WaveHouse Task Board Oct 9, 2026

github-actions Bot mentioned this pull request Oct 9, 2026

ci: add make ci-remote and make the repo's hooks fail closed #798

Merged

11 of 15 tasks

Navigation Menu

Repository navigation

fix(sdk): give CommonJS consumers their own type declarations - #792

fix(sdk): give CommonJS consumers their own type declarations#792
EricAndrechek merged 4 commits into
mainfrom
fix/sdk-cjs-types

EricAndrechek commented Oct 9, 2026

Uh oh!

coderabbitai Bot commented Oct 9, 2026 •

edited

Loading

Summary by CodeRabbit

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot commented Oct 9, 2026 •

edited

Loading

Uh oh!

github-code-quality Bot commented Oct 9, 2026 •

edited

Loading

Uh oh!

EricAndrechek commented Oct 9, 2026

Uh oh!

coderabbitai Bot commented Oct 9, 2026 •

edited

Loading

Uh oh!

EricAndrechek commented Oct 9, 2026

Uh oh!

coderabbitai Bot commented Oct 9, 2026 •

edited

Loading

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

EricAndrechek commented Oct 9, 2026

Summary

Test plan

Related Issues

Uh oh!

coderabbitai Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-code-quality Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage Overview

Go

Uh oh!

EricAndrechek commented Oct 9, 2026

Uh oh!

coderabbitai Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

EricAndrechek commented Oct 9, 2026

Uh oh!

coderabbitai Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

coderabbitai Bot commented Oct 9, 2026 •

edited

Loading

github-actions Bot commented Oct 9, 2026 •

edited

Loading

github-code-quality Bot commented Oct 9, 2026 •

edited

Loading

coderabbitai Bot commented Oct 9, 2026 •

edited

Loading

coderabbitai Bot commented Oct 9, 2026 •

edited

Loading