deprecate legacy module facades

[jonathanMLDev]

Summary

• Mark all legacy module-level singleton facades @deprecated in JSDoc with ServerContext replacements and policy-relative removal wording (next minor; earliest removal two minors later).
• Document the migration path in docs/MIGRATION.md, docs/deprecation-policy.md, CHANGELOG.md, and README.md (Stability / deployment model).
• Migrate examples to instance-first (createServer → ctx.setClient → setup*Server({ context: ctx })); legacy facade path documented in MIGRATION only.
• Refresh docs/PACKAGE_SPLIT_EVAL.md to use legacy-facade wording instead of internal roadmap jargon.

Affected facades: getPineconeClient / setPineconeClient / clearPineconeClient, config getters, URL registry (incl. resetUrlGenerationRegistry), suggest-flow gate, namespaces cache, getDefaultServerContext.

Not in scope: runtime removal, warn-once logging, or npm package split.

Test plan

• npm run ci (277 tests)
• IDE shows strikethrough on deprecated facade imports
• Legacy setPineconeClient + setupAllianceServer(config) still works during deprecation window
• Examples match docs/MIGRATION.md#unreleased-legacy-module-facade-deprecations

Release note

Exact semver (0.N.0 / 0.(N+2).0) pinned when publishing the deprecating minor

Related issues

• Close Legacy Facade Deprecation: Add @deprecated JSDoc Tags with Migration Guidance #155
• Close Stability Policy README Section: Document Pre-1.0 Breaking Change Expectations #157
• Close Deprecate legacy getters #161

Summary by CodeRabbit

Release Notes

• Documentation

  • Added deprecation guidance for legacy module-level singleton APIs; users should migrate to ServerContext instance methods via createServer().
  • Updated all examples to demonstrate the recommended pattern.
  • Provided migration documentation with replacement patterns and deprecation timeline.

• Chores

  • Added deprecation notices to legacy APIs with references to migration guides.

[coderabbitai]

Warning

Review limit reached

@jonathanMLDev, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 6 minutes and 53 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f433e999-7ad7-4022-91ee-fef09c076059

📥 Commits

Reviewing files that changed from the base of the PR and between d6d80b4 and 8bd46e9.

📒 Files selected for processing (16)

• CHANGELOG.md
• README.md
• docs/MIGRATION.md
• docs/PACKAGE_SPLIT_EVAL.md
• docs/deprecation-policy.md
• examples/alliance/custom-url-generator.ts
• examples/alliance/guided-query-demo.ts
• examples/alliance/library-embedding-demo.ts
• examples/alliance/suggest-flow-demo.ts
• examples/quickstart/mcp-demo.ts
• src/core/server/client-context.ts
• src/core/server/config-context.ts
• src/core/server/namespaces-cache.ts
• src/core/server/server-context.ts
• src/core/server/suggestion-flow.ts
• src/core/server/url-registry.ts

📝 Walkthrough

Walkthrough

All module-level singleton facade exports (setPineconeClient, registerUrlGenerator, getNamespacesWithCache, markSuggested, etc.) are marked @deprecated in JSDoc with guidance to use ServerContext instance methods obtained from createServer. Policy and migration documentation is updated with an active-deprecations table and full before/after migration snippets. All example scripts are refactored to the createServer(config) → ctx.setClient() → setup*Server({ context: ctx }) pattern. No runtime behavior changes.

Changes

Legacy Facade Deprecation and Example Migration

Layer / File(s)	Summary
Deprecation policy, MIGRATION, and CHANGELOG docs docs/deprecation-policy.md, docs/MIGRATION.md, CHANGELOG.md	deprecation-policy.md gains an active-deprecations table mapping each facade group to its ServerContext replacement with timing. MIGRATION.md adds a comprehensive before/after guide for every deprecated facade group. CHANGELOG.md records the Unreleased Deprecated entries.
README stability section and facade callouts README.md	Adds a "Stability" section for pre-1.0 semver behavior, a single-line deprecation note for module-level facades, updated Library embedding examples using await using and the ctx pattern, and Custom URL generators updated to ctx.registerUrlGenerator(...).
PACKAGE_SPLIT_EVAL milestone alignment docs/PACKAGE_SPLIT_EVAL.md	Replaces all "phase 5" terminology with "legacy facade deprecation" milestone language across the decision statement, API blockers description, version policy bullet, Cons/rationale, and prerequisites checklist.
@deprecated JSDoc on legacy facade source modules src/core/server/client-context.ts, src/core/server/config-context.ts, src/core/server/namespaces-cache.ts, src/core/server/suggestion-flow.ts, src/core/server/url-registry.ts, src/core/server/server-context.ts	All legacy facade functions receive expanded @deprecated JSDoc blocks with @see references to ServerContext replacements and removal-policy links. server-context.ts updates the getClientIfSet error message and adds a deprecation notice for the process-default context section.
Examples migrated to createServer+ctx pattern examples/quickstart/mcp-demo.ts, examples/alliance/custom-url-generator.ts, examples/alliance/guided-query-demo.ts, examples/alliance/suggest-flow-demo.ts, examples/alliance/library-embedding-demo.ts	All example scripts drop setPineconeClient/teardownServer imports and adopt createServer(config) → ctx.setClient() → setup*Server({ context: ctx }) → ctx.teardown() lifecycle.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• cppalliance/pinecone-read-only-mcp-typescript#130: Introduced the delegation pattern where legacy facades call through to ServerContext/createServer — the exact functions now being marked @deprecated in this PR.
• cppalliance/pinecone-read-only-mcp-typescript#132: Migrated remaining tools to optional ServerContext usage, directly preceding the deprecation of the legacy facades that this PR annotates.
• cppalliance/pinecone-read-only-mcp-typescript#152: Added the initial PACKAGE_SPLIT_EVAL.md with phase-5 milestone wording that this PR realigns to the legacy facade deprecation milestone.

Suggested reviewers

• leostar0412
• AuraMindNest
• wpak-ai

Poem

🐇 Hop, hop — the old facades must go,
With @deprecated tags all in a row.
createServer now leads the way,
ctx.setClient() saves the day!
The singleton singleton hops away — hooray! 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'deprecate legacy module facades' clearly and concisely summarizes the main change: marking legacy module-level singleton facades as deprecated with JSDoc annotations and documentation updates.
Linked Issues check	✅ Passed	The PR addresses all requirements from linked issues #155, #157, and #161: JSDoc @deprecated tags added to facades with @since and @see references, README updated with Stability section and instance-first examples, CHANGELOG and MIGRATION.md updated with deprecation details, and all examples migrated to ServerContext patterns.
Out of Scope Changes check	✅ Passed	All changes are directly related to legacy facade deprecation objectives: documentation updates, JSDoc annotations, example migrations, and no runtime behavior changes or unrelated modifications introduced.
Docstring Coverage	✅ Passed	Docstring coverage is 90.00% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ 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@e36184b). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #168   +/-   ##
=======================================
  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.

[coderabbitai]

Actionable comments posted: 1

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

Inline comments:
In `@docs/deprecation-policy.md`:
- Line 35: The heading "### Active deprecations — legacy module facades" on line
35 contains an em-dash ("—") which causes markdown processors to generate an
anchor slug that doesn't match the internal link reference on line 111 which
expects `#active-deprecations-legacy-module-facades`. Replace the em-dash in the
heading with a standard hyphen or colon to ensure the generated anchor slug is
predictable and matches the existing link reference.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 74de05e8-1fc9-440b-a151-1774b7a7d82e

📥 Commits

Reviewing files that changed from the base of the PR and between d6d80b4 and 810f8b0.

📒 Files selected for processing (16)

• CHANGELOG.md
• README.md
• docs/MIGRATION.md
• docs/PACKAGE_SPLIT_EVAL.md
• docs/deprecation-policy.md
• examples/alliance/custom-url-generator.ts
• examples/alliance/guided-query-demo.ts
• examples/alliance/library-embedding-demo.ts
• examples/alliance/suggest-flow-demo.ts
• examples/quickstart/mcp-demo.ts
• src/core/server/client-context.ts
• src/core/server/config-context.ts
• src/core/server/namespaces-cache.ts
• src/core/server/server-context.ts
• src/core/server/suggestion-flow.ts
• src/core/server/url-registry.ts

[jonathanMLDev]

@coderabbitai full review again

[coderabbitai]

@jonathanMLDev Sure! I'll kick off a full review of this PR right away.

✅ Action performed

Full review finished.