From 5c24af1fde75edcded80f1afb5838f28c3aa64d1 Mon Sep 17 00:00:00 2001 From: timon0305 Date: Thu, 9 Jul 2026 04:50:52 +0200 Subject: [PATCH] refactor: trim internal-only exports from the public barrels (#203) Remove four internal-only re-exports from the package root and /alliance entry to shrink the public surface and blast radius: trimOptional, createUnconfiguredAllianceContext (core), and the concrete URL generators generatorMailing, generatorSlackCpplang (alliance). The symbols stay in their modules; only the barrel re-exports are dropped, and no in-repo importer used them via the barrel. Deprecated-in-window legacy facades are kept. Add a snapshot guard test that pins the runtime value-export allow-list for both barrels, so a future internal symbol leaking into a barrel fails CI. Document the removal in CHANGELOG (Breaking, library) and MIGRATION. --- CHANGELOG.md | 4 ++ docs/MIGRATION.md | 10 ++++ src/alliance/index.ts | 6 +- src/core/__tests__/public-exports.test.ts | 68 +++++++++++++++++++++++ src/core/index.ts | 3 +- 5 files changed, 84 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bb03d4d..1161c46 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,10 @@ Tagged releases are published to npm from GitHub Actions when a **GitHub Release - **Instructions:** Trimmed operator/install/deploy content (env-var setup, misconfiguration note, Alliance CLI index/rerank defaults, stderr logging config) from `CORE_SERVER_INSTRUCTIONS` and `ALLIANCE_INSTRUCTIONS_APPENDIX` — reduces per-session token cost; no behavior change. Replaced colliding Alliance appendix steps 4–5 with unnumbered "Manual Alliance flow" bullets (includes `PINECONE_DISABLE_SUGGEST_FLOW=true` escape clause). Full detail remains in [docs/CONFIGURATION.md](docs/CONFIGURATION.md). +### Removed + +- **Breaking (library):** Trimmed internal-only re-exports from the package root and `/alliance` entry to shrink the public surface and blast radius: `trimOptional`, `createUnconfiguredAllianceContext` (core), and the concrete URL generators `generatorMailing`, `generatorSlackCpplang` (alliance). These were internal helpers, not part of the documented API; register built-ins via `registerBuiltinUrlGenerators` and build contexts via `createServer` / `createIsolatedContext`. A snapshot test now guards the runtime export surface so internal symbols cannot leak back in. See [MIGRATION.md](docs/MIGRATION.md#internal-only-re-exports-removed-203). (#203) + ## [0.4.0] - 2026-06-24 ### Added diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index 4799680..fcde4f4 100644 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -202,6 +202,16 @@ import { buildQueryExperimental } from '@will-cppa/pinecone-read-only-mcp'; `PineconeClient.query()` return types (`HybridQueryResult`, etc.) and all Zod response schemas remain on the public surface. +### Internal-only re-exports removed (#203) + +**Who is affected:** Library embedders that imported any of these internal helpers from the package root or `/alliance`: + +- `trimOptional` (a string-trim helper) +- `createUnconfiguredAllianceContext` (an internal context factory used by setup guards) +- `generatorMailing`, `generatorSlackCpplang` (the concrete Alliance URL generators) + +**After:** none of these are part of the supported surface. Trim whitespace yourself, build contexts with `createServer` / `createIsolatedContext`, and register the built-in URL generators with `registerBuiltinUrlGenerators` (the documented entry point) instead of importing the individual generators. The public runtime export surface is now guarded by a snapshot test so internal symbols cannot leak back in. + ## Unreleased: `ServerContext` instance APIs (initial) **Rationale:** Process-global singletons (Pinecone client slot, config, URL registry, suggest-flow gate, namespaces cache) complicate testing and multi-tenant embedding. The initial milestone introduces an opt-in **`ServerContext`**; legacy module facades are deprecated since **0.3.0** (see [Legacy module-facade deprecations](#030-legacy-module-facade-deprecations)). diff --git a/src/alliance/index.ts b/src/alliance/index.ts index dcc2624..6e17a41 100644 --- a/src/alliance/index.ts +++ b/src/alliance/index.ts @@ -13,9 +13,5 @@ export { export type { AllianceServerConfig } from './config.js'; export type { AllianceServerContext } from '../core/server/server-context.js'; export { setupAllianceServer, type SetupAllianceServerOptions } from './setup.js'; -export { - registerBuiltinUrlGenerators, - generatorMailing, - generatorSlackCpplang, -} from './url-builtins.js'; +export { registerBuiltinUrlGenerators } from './url-builtins.js'; export type { RegisterBuiltinUrlGeneratorsOptions } from './url-builtins.js'; diff --git a/src/core/__tests__/public-exports.test.ts b/src/core/__tests__/public-exports.test.ts index cf02b92..3aa5bad 100644 --- a/src/core/__tests__/public-exports.test.ts +++ b/src/core/__tests__/public-exports.test.ts @@ -1,9 +1,77 @@ import { describe, expect, it } from 'vitest'; import * as core from '../index.js'; +import * as alliance from '../../alliance/index.js'; + +/** + * Guards the public runtime export surface of both barrels (#203). Types are + * erased at runtime, so only value exports appear here; this catches an internal + * symbol accidentally leaking into a barrel and growing the blast radius. When a + * genuinely public symbol is added, add it to the allow-list in the same change. + */ +const CORE_PUBLIC_EXPORTS = [ + 'PineconeClient', + 'ServerContext', + 'SourceRegistry', + 'buildSourceRegistry', + 'countResponseSchema', + 'createIsolatedContext', + 'createServer', + 'generateUrlForNamespace', + 'generateUrlsResponseSchema', + 'getDefaultServerContext', + 'guidedQueryResponseSchema', + 'hasUrlGenerator', + 'keywordSearchResponseSchema', + 'keywordSearchSuccessResponseSchema', + 'listNamespacesResponseSchema', + 'namespaceRouterResponseSchema', + 'queryDocumentsResponseSchema', + 'queryResponseSchema', + 'queryResultRowSchema', + 'querySuccessResponseSchema', + 'registerUrlGenerator', + 'resolveConfig', + 'setPineconeClient', + 'setupCoreServer', + 'suggestQueryParams', + 'suggestQueryParamsResponseSchema', + 'teardownServer', + 'toolErrorSchema', + 'unregisterUrlGenerator', + 'validateMetadataFilter', + 'validateMetadataFilterDetailed', +]; + +const ALLIANCE_PUBLIC_EXPORTS = [ + ...CORE_PUBLIC_EXPORTS, + 'ALLIANCE_DEFAULT_INDEX_NAME', + 'ALLIANCE_DEFAULT_RERANK_MODEL', + 'DEFAULT_ALLIANCE_RERANK_MODEL', + 'registerBuiltinUrlGenerators', + 'resolveAllianceConfig', + 'setupAllianceServer', +].sort(); describe('public export surface', () => { it('does not export internal experimental block builders', () => { expect('buildQueryExperimental' in core).toBe(false); expect('buildGuidedQueryExperimental' in core).toBe(false); }); + + it('does not export the internal-only symbols trimmed in #203', () => { + for (const name of ['trimOptional', 'createUnconfiguredAllianceContext']) { + expect(name in core).toBe(false); + } + for (const name of ['generatorMailing', 'generatorSlackCpplang']) { + expect(name in alliance).toBe(false); + } + }); + + it('core barrel value exports match the allow-list', () => { + expect(Object.keys(core).sort()).toEqual([...CORE_PUBLIC_EXPORTS].sort()); + }); + + it('alliance barrel value exports match the allow-list', () => { + expect(Object.keys(alliance).sort()).toEqual(ALLIANCE_PUBLIC_EXPORTS); + }); }); diff --git a/src/core/index.ts b/src/core/index.ts index f603331..6ec7873 100644 --- a/src/core/index.ts +++ b/src/core/index.ts @@ -11,7 +11,6 @@ export { ServerContext, createServer, createIsolatedContext, - createUnconfiguredAllianceContext, getDefaultServerContext, } from './server/server-context.js'; export type { @@ -65,7 +64,7 @@ export { hasUrlGenerator, } from './server/url-registry.js'; export type { UrlGenerationResult, UrlGenerator, UrlGeneratorFn } from './server/url-registry.js'; -export { resolveConfig, trimOptional } from './config.js'; +export { resolveConfig } from './config.js'; export type { SourceDefinition } from './server/source-config.js'; export { SourceRegistry, buildSourceRegistry } from './server/source-registry.js'; export type { AggregatedCacheResult, PerSourceCacheResult } from './server/source-registry.js';