feat: phase 1 export trim — remove experimental block builders from public API

[jonathanMLDev]

Summary

Remove internal experimental-block assembly helpers from the public package surface.

• Removed from @will-cppa/pinecone-read-only-mcp and /alliance re-exports: buildQueryExperimental, buildGuidedQueryExperimental
• Unchanged internally: tool handlers still import builders via ../response-schemas.js (no runtime behavior change)
• Added: src/core/__tests__/public-exports.test.ts regression guard, CHANGELOG.md [Unreleased] entries, docs/MIGRATION.md#unreleased-trimmed-library-exports

Test plan

• npm run release:check (typecheck, lint, format, build, coverage, pack dry-run)
• npm test — 264 tests passed, including public-exports.test.ts
• npm pack --dry-run — builders absent from published index.d.ts

Related Issue

• Close Export Trimming: Remove Internal Types from Public API #154

Summary by CodeRabbit

• Breaking Changes

  • Removed buildQueryExperimental and buildGuidedQueryExperimental from the public library exports (including the /alliance surface).

• Documentation

  • Updated CHANGELOG.md with Unreleased breaking notes.
  • Added an Unreleased migration guide explaining how to obtain experimental fields via the appropriate MCP tool handlers and response parsing.

• Tests

  • Added a public export check to verify these experimental helpers are no longer exposed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d18c768e-a321-434c-95c2-4d7865c6bcfc

📥 Commits

Reviewing files that changed from the base of the PR and between cc08c09 and 716184b.

📒 Files selected for processing (3)

• CHANGELOG.md
• docs/MIGRATION.md
• src/core/index.ts

✅ Files skipped from review due to trivial changes (2)

• docs/MIGRATION.md
• CHANGELOG.md

🚧 Files skipped from review as they are similar to previous changes (1)

• src/core/index.ts

---

📝 Walkthrough

Walkthrough

Removes buildQueryExperimental and buildGuidedQueryExperimental from the named re-exports in src/core/index.ts. Adds a Vitest test asserting these names are absent from the public module surface. Documents the breaking removal in CHANGELOG.md and adds a migration section in docs/MIGRATION.md.

Changes

Experimental Builder Export Removal

Layer / File(s)	Summary
Remove exports from core index and add regression test src/core/index.ts, src/core/__tests__/public-exports.test.ts	buildGuidedQueryExperimental and buildQueryExperimental are dropped from the named re-export list in src/core/index.ts. A new Vitest suite asserts both names are absent from the public core export surface using the in operator.
CHANGELOG and MIGRATION documentation CHANGELOG.md, docs/MIGRATION.md	Adds Breaking (library) bullets to the Unreleased Changed and Removed sections of CHANGELOG.md. Adds a new docs/MIGRATION.md section instructing embedders to call MCP tool handlers and parse responses with queryResponseSchema or guidedQueryResponseSchema instead of the removed helpers.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Suggested reviewers

• wpak-ai

Poem

🐇 Snip snip, two exports fall away,
No more builders for the public to stray.
The index is cleaner, the surface is lean,
A test stands guard where the symbols had been.
Less is more, says the rabbit with glee! 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR addresses issue #154 but only implements phase 1, removing only 2 of 6 required symbols; 4 types (HybridLegFailed, HybridQueryResult, MergedHit, KeywordIndexNamespacesResult) remain exported.	Complete the remaining phases to remove all 6 symbols as specified in issue #154 acceptance criteria.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and specifically describes the main change: removing experimental builder functions from the public API surface.
Out of Scope Changes check	✅ Passed	All changes directly support the phase 1 objective of removing the two builder functions; no out-of-scope changes detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[codecov]

Codecov Report

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

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #166   +/-   ##
=======================================
  Coverage        ?   87.56%           
=======================================
  Files           ?       40           
  Lines           ?     1664           
  Branches        ?      554           
=======================================
  Hits            ?     1457           
  Misses          ?      207           
  Partials        ?        0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 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.

[jonathanMLDev]

@coderabbitai full review again

[coderabbitai]

@jonathanMLDev: Sure! I'll kick off a full review of the PR now.

✅ Action performed

Full review finished.