Skip to content

refactor(do): drop the unconsumed shard-engine re-exports - #362

Merged
prisis merged 2 commits into
alphafrom
refactor/286-do-barrel-deletion
Aug 8, 2026
Merged

prisis merged 2 commits into
alphafrom
refactor/286-do-barrel-deletion

Conversation

@prisis

@prisis prisis commented Aug 8, 2026 •

Copy link
Copy Markdown
Member

@lunora/do's barrel froze 275 @lunora/shard-engine names into this package's
public surface. Only 55 have a consumer — repo import sites plus the codegen
emitter's import builders. This deletes the other 234. Every one of them is
still exported by @lunora/shard-engine, which is where to import it from.

do.api.md goes 311 → 77 entries; lunora.api.md loses the same set, since
lunorash/do is an export * mirror.

Why now, instead of after the deprecation cycle

The earlier phase deprecated these for one alpha cycle. That cycle can't deliver
its signal: packem's dts bundler merges same-specifier re-exports and drops their
leading comments, so 57 @deprecated markers in source became 1 in dist (and
that 1 is a pre-existing, unrelated alias). Consumers resolve through dist, in
repo and from npm — nobody was ever going to see a strikethrough.

Waiting another cycle buys calendar time and no warning. On a pre-release branch
the convention is to cut the old path rather than keep a shim alive, so the
removal lands as one deliberate breaking change with release notes.

Fixing the bundler instead is a real option, just not this PR: the dts step is
@visulima/rollup-plugin-dts, and the drop reproduces under both its oxc and
tsc generators, so it is the bundling step rather than isolated declarations.
Every same-specifier re-export is merged into one combined export { … } from
and the leading comments go with the merge; JSDoc on a declaration survives. That
is worth fixing upstream on its own merits, but it does not change what to do
with 234 re-exports that no consumer wants.

The kept set was three names short

Worth a look from a reviewer — deleting the block as it stood would have broken
generated code:

  • The derivation script scanned only @lunora/do import sites, so it missed
    lunorash/do. apps/playground/lunora/_generated/shard.ts:4 imports
    WhereInput from there.
  • It read buildDoTypeImports but not the two conditional pushes below it:
    emit.ts:4204 adds WhereInput when a project declares shapes, and :4300
    emits ExternalSourceLike + SourceClientLike for .source() tables.

All three sat in the deprecated block. They're kept now, annotated with the
emitter lines that demand them. The final 55-name demand set is asserted present
in the regenerated snapshot rather than eyeballed.

The enforcement comment atop the block stays: a re-export here needs a named
consumer, and drive-by additions are how 230 unused names got frozen in the
first place.

Verification

Gate Result
build:packages 54/54
lint:types (repo) 73/73
api-snapshot check 47/47
@lunora/do tests 522
@lunora/runtime tests 846
@lunora/codegen tests 1068, golden fixtures byte-identical
lunorash tests 121
@lunora/do eslint clean

No _generated output changed, and nothing outside packages/do/src/index.ts,
the two snapshots, and the plan index was touched.

Breaking change

@lunora/do (and lunorash/do) no longer re-export the 234 shard-engine symbols
that had no consumer. Import them from @lunora/shard-engine; names and
signatures are unchanged.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KBeSX2o4sTCPjVDRDWkVQG

Summary by CodeRabbit

  • Refactor

    • Simplified the public API by removing deprecated exports that are no longer supported.
    • Retained essential source and query types to preserve compatibility with generated integrations.
    • Reactive engine functionality is now accessed through its dedicated package.
  • Documentation

    • Updated ingestion documentation and code references to use the dedicated reactive engine package.

The barrel froze 275 shard-engine names into this package's public surface;
only 55 have a consumer (repo import sites plus the codegen emitter's import
builders). Delete the other 234 — every one of them is still exported by
@lunora/shard-engine, which is where to import it from.

Plan 286's phase A deprecated them for one alpha cycle, but packem's dts
bundler merges same-specifier re-exports and drops their JSDoc, so the
@deprecated markers never reached dist and no consumer was ever warned. On a
pre-release branch the convention is to cut the old path, so the cycle is
skipped and the removal lands as one breaking change.

Phase A's kept set was three names short: its derivation scanned only
@lunora/do import sites (missing lunorash/do, which apps/playground's
generated shard uses for WhereInput) and read buildDoTypeImports without the
conditional pushes below it — WhereInput for projects with shapes,
ExternalSourceLike and SourceClientLike for .source() tables. All three are
kept and annotated with their emitter line.

BREAKING CHANGE: @lunora/do no longer re-exports the 234 @lunora/shard-engine
symbols that had no consumer (lunorash/do mirrors the same removal). Import
them from @lunora/shard-engine instead; the names and signatures are unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KBeSX2o4sTCPjVDRDWkVQG
@netlify

netlify Bot commented Aug 8, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for lunorash ready!

Name Link
🔨 Latest commit 7302fc0
🔍 Latest deploy log https://app.netlify.com/projects/lunorash/deploys/6a76f3c9bd7c930008b6731a
😎 Deploy Preview https://deploy-preview-362--lunorash.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@github-actions

github-actions Bot commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

Thank you for following the naming conventions! 🙏

@github-actions

github-actions Bot commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

Thank you for confirming the Contributor License Agreement! 🙏

@coderabbitai

coderabbitai Bot commented Aug 8, 2026 •

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 6bd4caab-bbc4-44ab-b8b0-4b61ac45c745

📥 Commits

Reviewing files that changed from the base of the PR and between b8a8e8e and 7302fc0.

📒 Files selected for processing (2)
  • packages/hyperdrive/docs/index.mdx
  • packages/hyperdrive/src/source.ts

Walkthrough

packages/do removes deprecated @lunora/shard-engine re-exports and retains codegen-required types. Hyperdrive documentation now references @lunora/shard-engine for external-row materialization and source ID lifting APIs.

Changes

Export boundary

Layer / File(s) Summary
Retain codegen exports
packages/do/src/index.ts
The deprecated shard-engine API re-exports were removed. ExternalSourceLike, SourceClientLike, and WhereInput remain exported. Comments identify @lunora/shard-engine as the reactive engine home.
Update shard-engine references
packages/hyperdrive/docs/index.mdx, packages/hyperdrive/src/source.ts
Documentation references for materializeExternalRows, its write-side implementation, and liftSourceId now use @lunora/shard-engine.

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

Possibly related PRs

Suggested labels: package: shard-engine

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely describes the removal of unused shard-engine re-exports from the do package.
Description check ✅ Passed The description explains the change, rationale, breaking impact, retained exports, documentation updates, and extensive verification results.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch refactor/286-do-barrel-deletion

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.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
packages/do/src/index.ts (1)

42-47: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Align the removal counts in the comments and the PR description.

Line 46 states 237 removed names. Line 44 states 230 unused names. The PR description states 234 removed re-exports. These three numbers conflict. Use one verified count, or drop the exact number and describe the rule only.

📝 Proposed comment fix
-// Every re-export below must have a named consumer (the codegen emitter's
-// import builders, or an import site in this repo). Additions require one;
-// drive-by re-exports are how 230 unused names got frozen here (plan 286).
-//
-// The 237 that had no consumer were removed; everything they named is still
-// exported by `@lunora/shard-engine`, which is where to import it from.
+// Every re-export below must have a named consumer (the codegen emitter's
+// import builders, or an import site in this repo). Additions require one;
+// drive-by re-exports are how unused names got frozen here (plan 286).
+//
+// Re-exports without a consumer were removed; everything they named is still
+// exported by `@lunora/shard-engine`, which is where to import it from.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/do/src/index.ts` around lines 42 - 47, Update the explanatory
comments around the re-export list to use one verified removal count
consistently with the PR description, or remove the exact counts and retain only
the named-consumer rule. Do not change the re-export behavior.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@packages/do/src/index.ts`:
- Around line 42-47: Update the explanatory comments around the re-export list
to use one verified removal count consistently with the PR description, or
remove the exact counts and retain only the named-consumer rule. Do not change
the re-export behavior.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: e04d126b-cd18-411c-b61b-bd13d494bb09

📥 Commits

Reviewing files that changed from the base of the PR and between b179c06 and b8a8e8e.

⛔ Files ignored due to path filters (4)
  • api-snapshots/do.api.md is excluded by none and included by none
  • api-snapshots/lunora.api.md is excluded by none and included by none
  • plans/286-do-reexport-barrel.md is excluded by none and included by none
  • plans/README.md is excluded by none and included by none
📒 Files selected for processing (1)
  • packages/do/src/index.ts

@codspeed

codspeed Bot commented Aug 8, 2026 •

Copy link
Copy Markdown

Merging this PR will regress 1 benchmark

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 2 improved benchmarks
❌ 1 regressed benchmark
✅ 250 untouched benchmarks
⏩ 10 skipped benchmarks1

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

Benchmark BASE HEAD Efficiency
❌ findMany — plain table (no scope) 77.8 ms 87.9 ms -11.43%
⚡ 1 after-insert no-op trigger 473.8 µs 415.9 µs +13.94%
⚡ baseline (Object.keys + toInternal + path spread per field) 71.7 µs 65.1 µs +10.11%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.


Comparing refactor/286-do-barrel-deletion (7302fc0) with alpha (b179c06)

Open in CodSpeed

Footnotes

  1. 10 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

@codecov-commenter

codecov-commenter commented Aug 8, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (alpha@b179c06). Learn more about missing BASE report.

Additional details and impacted files
@@           Coverage Diff            @@
##             alpha     #362   +/-   ##
========================================
  Coverage         ?   87.08%           
========================================
  Files            ?     1170           
  Lines            ?    63259           
  Branches         ?    15621           
========================================
  Hits             ?    55087           
  Misses           ?     7651           
  Partials         ?      521           
Files with missing lines Coverage Δ
packages/hyperdrive/src/source.ts 100.00% <ø> (ø)
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

The ingest-bridge snippet imported it from `@lunora/do`, which no longer
re-exports it; the docs build's import check fails on it. The symbol lives in
`@lunora/shard-engine` — point the snippet and the module JSDoc there.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KBeSX2o4sTCPjVDRDWkVQG
@prisis
prisis merged commit 4b9f711 into alpha Aug 8, 2026
38 checks passed
@prisis
prisis deleted the refactor/286-do-barrel-deletion branch August 8, 2026 09:19
@github-actions

github-actions Bot commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using our GitHub Discussions tab for questions.

@github-actions github-actions Bot locked as resolved and limited conversation to collaborators Sep 8, 2026

This branch was previously deployed

1 inactive deployment
benchmarks — 7302fc04 Deployed Aug 8, 2026 by prisis via Benchmarks #1528
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants