From 91b986f5b65086791b91105491843ddcee4545ac Mon Sep 17 00:00:00 2001 From: Sachin Sharma Date: Thu, 3 Sep 2026 22:52:40 +0530 Subject: [PATCH] fix(types): stop shipping declarations that reference stripped types MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `stripInternal: true` deletes `@internal` declarations from the emitted .d.ts but does not rewrite the imports that name them. Seven knowledge types and `GitToolRuntimeSettings` were tagged while public declarations still used them in their signatures, so the published package shipped .d.ts files that cannot compile: dist/knowledge/context.d.ts(11,15): TS2305: Module '"../types/index.js"' has no exported member 'KnowledgeAssembledContext'. Six errors across four files. Consumers with `skipLibCheck: true` — the common default — never see it; everyone else gets errors from inside node_modules with nothing actionable in them. The tags were wrong, not the code. Every one of these types is named by the emitted signature of a public runtime export (assembleKnowledgeContext, retrieve, resolveEntry, manifestToSources, normalizeAndValidate, configureGitTools), which makes them public by construction. Three knowledge types that never reach an emitted signature keep their tag. `check:dts` typechecks all 1027 shipped declaration files with skipLibCheck off and fails on any unresolved reference. It is not decoration: it caught the first version of this fix, where the explanatory comment on GitToolRuntimeSettings named the tag literally and re-triggered the strip — the tag is matched as plain text anywhere in the doc comment. Verified: check:dts green over 1027 files, and a consumer project typechecking against the built package with skipLibCheck:false goes from 6 errors to 0. --- docs/api/README.md | 7 + .../api/functions/assembleKnowledgeContext.md | 6 +- docs/api/functions/normalizeAndValidate.md | 6 +- docs/api/functions/retrieve.md | 6 +- .../type-aliases/GitToolRuntimeSettings.md | 60 ++++++++ .../type-aliases/KnowledgeAssembledContext.md | 45 ++++++ .../api/type-aliases/KnowledgeEngineStatus.md | 12 +- .../type-aliases/KnowledgeGroundingInput.md | 8 +- .../type-aliases/KnowledgeGroundingOutcome.md | 8 +- .../type-aliases/KnowledgeNormalizeOptions.md | 21 +++ .../type-aliases/KnowledgeNormalizeResult.md | 29 ++++ .../KnowledgeResolvedRetrieval.md | 61 ++++++++ .../type-aliases/KnowledgeScoredCandidate.md | 69 +++++++++ docs/api/type-aliases/KnowledgeSelection.md | 53 +++++++ package.json | 1 + scripts/check-shipped-types.ts | 131 ++++++++++++++++++ src/lib/types/gitTools.ts | 7 +- src/lib/types/knowledge.ts | 23 +-- tsconfig.ci-scripts.json | 1 + 19 files changed, 522 insertions(+), 32 deletions(-) create mode 100644 docs/api/type-aliases/GitToolRuntimeSettings.md create mode 100644 docs/api/type-aliases/KnowledgeAssembledContext.md create mode 100644 docs/api/type-aliases/KnowledgeNormalizeOptions.md create mode 100644 docs/api/type-aliases/KnowledgeNormalizeResult.md create mode 100644 docs/api/type-aliases/KnowledgeResolvedRetrieval.md create mode 100644 docs/api/type-aliases/KnowledgeScoredCandidate.md create mode 100644 docs/api/type-aliases/KnowledgeSelection.md create mode 100644 scripts/check-shipped-types.ts diff --git a/docs/api/README.md b/docs/api/README.md index 592790303..72256de36 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -1211,6 +1211,7 @@ console.log(result.content); - [GitToolsetOptions](type-aliases/GitToolsetOptions.md) - [GitToolResult](type-aliases/GitToolResult.md) - [GitToolRefusal](type-aliases/GitToolRefusal.md) +- [GitToolRuntimeSettings](type-aliases/GitToolRuntimeSettings.md) - [EnhancedGroundingSource](type-aliases/EnhancedGroundingSource.md) - [SegmentSupport](type-aliases/SegmentSupport.md) - [SegmentAttribution](type-aliases/SegmentAttribution.md) @@ -1311,6 +1312,12 @@ console.log(result.content); - [KnowledgeGroundingMetadata](type-aliases/KnowledgeGroundingMetadata.md) - [KnowledgeValidationIssue](type-aliases/KnowledgeValidationIssue.md) - [KnowledgeValidationResult](type-aliases/KnowledgeValidationResult.md) +- [KnowledgeNormalizeOptions](type-aliases/KnowledgeNormalizeOptions.md) +- [KnowledgeNormalizeResult](type-aliases/KnowledgeNormalizeResult.md) +- [KnowledgeResolvedRetrieval](type-aliases/KnowledgeResolvedRetrieval.md) +- [KnowledgeScoredCandidate](type-aliases/KnowledgeScoredCandidate.md) +- [KnowledgeSelection](type-aliases/KnowledgeSelection.md) +- [KnowledgeAssembledContext](type-aliases/KnowledgeAssembledContext.md) - [KnowledgeGroundingInput](type-aliases/KnowledgeGroundingInput.md) - [KnowledgeGroundingOutcome](type-aliases/KnowledgeGroundingOutcome.md) - [KnowledgeEngineStatus](type-aliases/KnowledgeEngineStatus.md) diff --git a/docs/api/functions/assembleKnowledgeContext.md b/docs/api/functions/assembleKnowledgeContext.md index cec834235..78bb7b645 100644 --- a/docs/api/functions/assembleKnowledgeContext.md +++ b/docs/api/functions/assembleKnowledgeContext.md @@ -6,7 +6,7 @@ # Function: assembleKnowledgeContext() -> **assembleKnowledgeContext**(`selection`, `config`): `KnowledgeAssembledContext` +> **assembleKnowledgeContext**(`selection`, `config`): [`KnowledgeAssembledContext`](../type-aliases/KnowledgeAssembledContext.md) Defined in: [knowledge/context.ts:77](https://github.com/juspay/neurolink/blob/release/src/lib/knowledge/context.ts#L77) @@ -19,7 +19,7 @@ entry was degraded or dropped for budget. ### selection -`KnowledgeSelection` +[`KnowledgeSelection`](../type-aliases/KnowledgeSelection.md) ### config @@ -27,4 +27,4 @@ entry was degraded or dropped for budget. ## Returns -`KnowledgeAssembledContext` +[`KnowledgeAssembledContext`](../type-aliases/KnowledgeAssembledContext.md) diff --git a/docs/api/functions/normalizeAndValidate.md b/docs/api/functions/normalizeAndValidate.md index 8d3865295..feeb1aca3 100644 --- a/docs/api/functions/normalizeAndValidate.md +++ b/docs/api/functions/normalizeAndValidate.md @@ -6,7 +6,7 @@ # Function: normalizeAndValidate() -> **normalizeAndValidate**(`sources`, `options`): `Promise`\<`KnowledgeNormalizeResult`\> +> **normalizeAndValidate**(`sources`, `options`): `Promise`\<[`KnowledgeNormalizeResult`](../type-aliases/KnowledgeNormalizeResult.md)\> Defined in: [knowledge/resolve.ts:105](https://github.com/juspay/neurolink/blob/release/src/lib/knowledge/resolve.ts#L105) @@ -23,8 +23,8 @@ contract is stable if a future source kind needs asynchronous loading. ### options -`KnowledgeNormalizeOptions` +[`KnowledgeNormalizeOptions`](../type-aliases/KnowledgeNormalizeOptions.md) ## Returns -`Promise`\<`KnowledgeNormalizeResult`\> +`Promise`\<[`KnowledgeNormalizeResult`](../type-aliases/KnowledgeNormalizeResult.md)\> diff --git a/docs/api/functions/retrieve.md b/docs/api/functions/retrieve.md index 3131d87b1..9d22e9233 100644 --- a/docs/api/functions/retrieve.md +++ b/docs/api/functions/retrieve.md @@ -6,7 +6,7 @@ # Function: retrieve() -> **retrieve**(`snapshot`, `request`, `config`, `blockedDomains?`): `KnowledgeSelection` +> **retrieve**(`snapshot`, `request`, `config`, `blockedDomains?`): [`KnowledgeSelection`](../type-aliases/KnowledgeSelection.md) Defined in: [knowledge/retrieval.ts:160](https://github.com/juspay/neurolink/blob/release/src/lib/knowledge/retrieval.ts#L160) @@ -26,7 +26,7 @@ a confidence class. Context assembly is a separate, later step. ### config -`KnowledgeResolvedRetrieval` +[`KnowledgeResolvedRetrieval`](../type-aliases/KnowledgeResolvedRetrieval.md) ### blockedDomains? @@ -34,4 +34,4 @@ a confidence class. Context assembly is a separate, later step. ## Returns -`KnowledgeSelection` +[`KnowledgeSelection`](../type-aliases/KnowledgeSelection.md) diff --git a/docs/api/type-aliases/GitToolRuntimeSettings.md b/docs/api/type-aliases/GitToolRuntimeSettings.md new file mode 100644 index 000000000..895c5ce7e --- /dev/null +++ b/docs/api/type-aliases/GitToolRuntimeSettings.md @@ -0,0 +1,60 @@ +[**NeuroLink API Reference**](../README.md) + +--- + +[NeuroLink API Reference](../README.md) / GitToolRuntimeSettings + +# Type Alias: GitToolRuntimeSettings + +> **GitToolRuntimeSettings** = `object` + +Defined in: [types/gitTools.ts:83](https://github.com/juspay/neurolink/blob/release/src/lib/types/gitTools.ts#L83) + +Resolved git toolset settings for one host. + +Deliberately not marked internal: it is the return type of +`configureGitTools`, so it is named by an emitted declaration. Marking it +would make `stripInternal` delete the type without touching the import that +references it, leaving a .d.ts that fails to compile for any consumer using +`skipLibCheck: false`. (Note that the tag is matched as plain text anywhere +in the doc comment, so it cannot even be named here to explain itself.) + +## Properties + +### repoRoot + +> **repoRoot**: `string` + +Defined in: [types/gitTools.ts:84](https://github.com/juspay/neurolink/blob/release/src/lib/types/gitTools.ts#L84) + +--- + +### timeoutMs + +> **timeoutMs**: `number` + +Defined in: [types/gitTools.ts:85](https://github.com/juspay/neurolink/blob/release/src/lib/types/gitTools.ts#L85) + +--- + +### maxOutputBytes + +> **maxOutputBytes**: `number` + +Defined in: [types/gitTools.ts:86](https://github.com/juspay/neurolink/blob/release/src/lib/types/gitTools.ts#L86) + +--- + +### previewChars + +> **previewChars**: `number` + +Defined in: [types/gitTools.ts:87](https://github.com/juspay/neurolink/blob/release/src/lib/types/gitTools.ts#L87) + +--- + +### gitExecutable + +> **gitExecutable**: `string` + +Defined in: [types/gitTools.ts:88](https://github.com/juspay/neurolink/blob/release/src/lib/types/gitTools.ts#L88) diff --git a/docs/api/type-aliases/KnowledgeAssembledContext.md b/docs/api/type-aliases/KnowledgeAssembledContext.md new file mode 100644 index 000000000..e0e80de24 --- /dev/null +++ b/docs/api/type-aliases/KnowledgeAssembledContext.md @@ -0,0 +1,45 @@ +[**NeuroLink API Reference**](../README.md) + +--- + +[NeuroLink API Reference](../README.md) / KnowledgeAssembledContext + +# Type Alias: KnowledgeAssembledContext + +> **KnowledgeAssembledContext** = `object` + +Defined in: [types/knowledge.ts:473](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L473) + +The assembled ephemeral-context string plus its diagnostics. + +## Properties + +### assembledContext + +> **assembledContext**: `string` + +Defined in: [types/knowledge.ts:474](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L474) + +--- + +### citations + +> **citations**: [`KnowledgeCitation`](KnowledgeCitation.md)[] + +Defined in: [types/knowledge.ts:475](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L475) + +--- + +### contextTokens + +> **contextTokens**: `number` + +Defined in: [types/knowledge.ts:476](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L476) + +--- + +### truncated + +> **truncated**: `boolean` + +Defined in: [types/knowledge.ts:477](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L477) diff --git a/docs/api/type-aliases/KnowledgeEngineStatus.md b/docs/api/type-aliases/KnowledgeEngineStatus.md index d2849a8b7..c70067246 100644 --- a/docs/api/type-aliases/KnowledgeEngineStatus.md +++ b/docs/api/type-aliases/KnowledgeEngineStatus.md @@ -8,7 +8,7 @@ > **KnowledgeEngineStatus** = `object` -Defined in: [types/knowledge.ts:492](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L492) +Defined in: [types/knowledge.ts:499](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L499) Snapshot of engine health for telemetry and host introspection. @@ -18,7 +18,7 @@ Snapshot of engine health for telemetry and host introspection. > **enabled**: `boolean` -Defined in: [types/knowledge.ts:493](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L493) +Defined in: [types/knowledge.ts:500](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L500) --- @@ -26,7 +26,7 @@ Defined in: [types/knowledge.ts:493](https://github.com/juspay/neurolink/blob/re > **ready**: `boolean` -Defined in: [types/knowledge.ts:494](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L494) +Defined in: [types/knowledge.ts:501](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L501) --- @@ -34,7 +34,7 @@ Defined in: [types/knowledge.ts:494](https://github.com/juspay/neurolink/blob/re > **entryCount**: `number` -Defined in: [types/knowledge.ts:495](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L495) +Defined in: [types/knowledge.ts:502](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L502) --- @@ -42,7 +42,7 @@ Defined in: [types/knowledge.ts:495](https://github.com/juspay/neurolink/blob/re > **lastError**: `string` \| `null` -Defined in: [types/knowledge.ts:496](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L496) +Defined in: [types/knowledge.ts:503](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L503) --- @@ -50,4 +50,4 @@ Defined in: [types/knowledge.ts:496](https://github.com/juspay/neurolink/blob/re > **validationIssues**: [`KnowledgeValidationIssue`](KnowledgeValidationIssue.md)[] -Defined in: [types/knowledge.ts:497](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L497) +Defined in: [types/knowledge.ts:504](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L504) diff --git a/docs/api/type-aliases/KnowledgeGroundingInput.md b/docs/api/type-aliases/KnowledgeGroundingInput.md index 99ae9199e..5ea2effb6 100644 --- a/docs/api/type-aliases/KnowledgeGroundingInput.md +++ b/docs/api/type-aliases/KnowledgeGroundingInput.md @@ -8,7 +8,7 @@ > **KnowledgeGroundingInput** = `object` -Defined in: [types/knowledge.ts:474](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L474) +Defined in: [types/knowledge.ts:481](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L481) Per-turn input to `KnowledgeGroundingEngine.ground()`. @@ -18,7 +18,7 @@ Per-turn input to `KnowledgeGroundingEngine.ground()`. > **query**: `string` -Defined in: [types/knowledge.ts:475](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L475) +Defined in: [types/knowledge.ts:482](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L482) --- @@ -26,7 +26,7 @@ Defined in: [types/knowledge.ts:475](https://github.com/juspay/neurolink/blob/re > `optional` **recentTurns?**: [`KnowledgeConversationTurn`](KnowledgeConversationTurn.md)[] -Defined in: [types/knowledge.ts:476](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L476) +Defined in: [types/knowledge.ts:483](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L483) --- @@ -34,4 +34,4 @@ Defined in: [types/knowledge.ts:476](https://github.com/juspay/neurolink/blob/re > `optional` **scope?**: [`KnowledgeRequestScope`](KnowledgeRequestScope.md) -Defined in: [types/knowledge.ts:477](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L477) +Defined in: [types/knowledge.ts:484](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L484) diff --git a/docs/api/type-aliases/KnowledgeGroundingOutcome.md b/docs/api/type-aliases/KnowledgeGroundingOutcome.md index 8e6997794..d571b45fd 100644 --- a/docs/api/type-aliases/KnowledgeGroundingOutcome.md +++ b/docs/api/type-aliases/KnowledgeGroundingOutcome.md @@ -8,7 +8,7 @@ > **KnowledgeGroundingOutcome** = `object` -Defined in: [types/knowledge.ts:485](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L485) +Defined in: [types/knowledge.ts:492](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L492) The engine's per-turn output: the ephemeral context to inject (null on no-match, when disabled, or on fail-open), the aggregate metadata for the @@ -20,7 +20,7 @@ result, and the full retrieval for host diagnostics. > **ephemeralContext**: [`EphemeralContext`](EphemeralContext.md) \| `null` -Defined in: [types/knowledge.ts:486](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L486) +Defined in: [types/knowledge.ts:493](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L493) --- @@ -28,7 +28,7 @@ Defined in: [types/knowledge.ts:486](https://github.com/juspay/neurolink/blob/re > **metadata**: [`KnowledgeGroundingMetadata`](KnowledgeGroundingMetadata.md) -Defined in: [types/knowledge.ts:487](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L487) +Defined in: [types/knowledge.ts:494](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L494) --- @@ -36,4 +36,4 @@ Defined in: [types/knowledge.ts:487](https://github.com/juspay/neurolink/blob/re > **retrieval**: [`KnowledgeRetrievalResult`](KnowledgeRetrievalResult.md) \| `null` -Defined in: [types/knowledge.ts:488](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L488) +Defined in: [types/knowledge.ts:495](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L495) diff --git a/docs/api/type-aliases/KnowledgeNormalizeOptions.md b/docs/api/type-aliases/KnowledgeNormalizeOptions.md new file mode 100644 index 000000000..fdb047d6f --- /dev/null +++ b/docs/api/type-aliases/KnowledgeNormalizeOptions.md @@ -0,0 +1,21 @@ +[**NeuroLink API Reference**](../README.md) + +--- + +[NeuroLink API Reference](../README.md) / KnowledgeNormalizeOptions + +# Type Alias: KnowledgeNormalizeOptions + +> **KnowledgeNormalizeOptions** = `object` + +Defined in: [types/knowledge.ts:432](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L432) + +Options for normalizing + validating a set of sources before indexing. + +## Properties + +### manifestVersion + +> **manifestVersion**: `string` + +Defined in: [types/knowledge.ts:433](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L433) diff --git a/docs/api/type-aliases/KnowledgeNormalizeResult.md b/docs/api/type-aliases/KnowledgeNormalizeResult.md new file mode 100644 index 000000000..347595735 --- /dev/null +++ b/docs/api/type-aliases/KnowledgeNormalizeResult.md @@ -0,0 +1,29 @@ +[**NeuroLink API Reference**](../README.md) + +--- + +[NeuroLink API Reference](../README.md) / KnowledgeNormalizeResult + +# Type Alias: KnowledgeNormalizeResult + +> **KnowledgeNormalizeResult** = `object` + +Defined in: [types/knowledge.ts:437](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L437) + +Normalized entries paired with the validation outcome. + +## Properties + +### entries + +> **entries**: [`NormalizedKnowledgeEntry`](NormalizedKnowledgeEntry.md)[] + +Defined in: [types/knowledge.ts:438](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L438) + +--- + +### validation + +> **validation**: [`KnowledgeValidationResult`](KnowledgeValidationResult.md) + +Defined in: [types/knowledge.ts:439](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L439) diff --git a/docs/api/type-aliases/KnowledgeResolvedRetrieval.md b/docs/api/type-aliases/KnowledgeResolvedRetrieval.md new file mode 100644 index 000000000..bc4897d7e --- /dev/null +++ b/docs/api/type-aliases/KnowledgeResolvedRetrieval.md @@ -0,0 +1,61 @@ +[**NeuroLink API Reference**](../README.md) + +--- + +[NeuroLink API Reference](../README.md) / KnowledgeResolvedRetrieval + +# Type Alias: KnowledgeResolvedRetrieval + +> **KnowledgeResolvedRetrieval** = `object` + +Defined in: [types/knowledge.ts:443](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L443) + +Retrieval tuning after config + SDK defaults are merged. + +## Properties + +### candidateLimit + +> **candidateLimit**: `number` + +Defined in: [types/knowledge.ts:444](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L444) + +--- + +### resultLimit + +> **resultLimit**: `number` + +Defined in: [types/knowledge.ts:445](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L445) + +--- + +### relationLimit + +> **relationLimit**: `number` + +Defined in: [types/knowledge.ts:446](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L446) + +--- + +### fieldWeights + +> **fieldWeights**: [`KnowledgeFieldWeights`](KnowledgeFieldWeights.md) + +Defined in: [types/knowledge.ts:447](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L447) + +--- + +### exactBoost + +> **exactBoost**: `number` + +Defined in: [types/knowledge.ts:448](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L448) + +--- + +### aliasBoost + +> **aliasBoost**: `number` + +Defined in: [types/knowledge.ts:449](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L449) diff --git a/docs/api/type-aliases/KnowledgeScoredCandidate.md b/docs/api/type-aliases/KnowledgeScoredCandidate.md new file mode 100644 index 000000000..91a2b3561 --- /dev/null +++ b/docs/api/type-aliases/KnowledgeScoredCandidate.md @@ -0,0 +1,69 @@ +[**NeuroLink API Reference**](../README.md) + +--- + +[NeuroLink API Reference](../README.md) / KnowledgeScoredCandidate + +# Type Alias: KnowledgeScoredCandidate + +> **KnowledgeScoredCandidate** = `object` + +Defined in: [types/knowledge.ts:453](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L453) + +One scored retrieval candidate with its signal breakdown, for traces. + +## Properties + +### id + +> **id**: `string` + +Defined in: [types/knowledge.ts:454](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L454) + +--- + +### score + +> **score**: `number` + +Defined in: [types/knowledge.ts:455](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L455) + +--- + +### exact + +> **exact**: `boolean` + +Defined in: [types/knowledge.ts:456](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L456) + +--- + +### alias + +> **alias**: `boolean` + +Defined in: [types/knowledge.ts:457](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L457) + +--- + +### lexical + +> **lexical**: `number` + +Defined in: [types/knowledge.ts:458](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L458) + +--- + +### fieldScores + +> **fieldScores**: `Partial`\<`Record`\<[`KnowledgeFieldName`](KnowledgeFieldName.md), `number`\>\> + +Defined in: [types/knowledge.ts:459](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L459) + +--- + +### matchedPhrases + +> **matchedPhrases**: `string`[] + +Defined in: [types/knowledge.ts:460](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L460) diff --git a/docs/api/type-aliases/KnowledgeSelection.md b/docs/api/type-aliases/KnowledgeSelection.md new file mode 100644 index 000000000..d24f5eadf --- /dev/null +++ b/docs/api/type-aliases/KnowledgeSelection.md @@ -0,0 +1,53 @@ +[**NeuroLink API Reference**](../README.md) + +--- + +[NeuroLink API Reference](../README.md) / KnowledgeSelection + +# Type Alias: KnowledgeSelection + +> **KnowledgeSelection** = `object` + +Defined in: [types/knowledge.ts:464](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L464) + +The selected primary + relationship-expanded entries for one turn. + +## Properties + +### primary + +> **primary**: [`NormalizedKnowledgeEntry`](NormalizedKnowledgeEntry.md)[] + +Defined in: [types/knowledge.ts:465](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L465) + +--- + +### expanded + +> **expanded**: [`NormalizedKnowledgeEntry`](NormalizedKnowledgeEntry.md)[] + +Defined in: [types/knowledge.ts:466](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L466) + +--- + +### candidates + +> **candidates**: [`KnowledgeScoredCandidate`](KnowledgeScoredCandidate.md)[] + +Defined in: [types/knowledge.ts:467](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L467) + +--- + +### confidence + +> **confidence**: [`KnowledgeRetrievalConfidence`](KnowledgeRetrievalConfidence.md) + +Defined in: [types/knowledge.ts:468](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L468) + +--- + +### candidateCount + +> **candidateCount**: `number` + +Defined in: [types/knowledge.ts:469](https://github.com/juspay/neurolink/blob/release/src/lib/types/knowledge.ts#L469) diff --git a/package.json b/package.json index b79f9d2f9..64485e3ea 100644 --- a/package.json +++ b/package.json @@ -34,6 +34,7 @@ "build:action": "ncc build src/action/index.ts -o action-dist --source-map", "build:cli:link": "pnpm run build:cli && pnpm link --global", "check:deps": "tsx scripts/check-banned-deps.ts", + "check:dts": "tsx scripts/check-shipped-types.ts", "codegen:catalog": "tsx tools/codegen-catalog.ts", "cli": "node dist/cli/index.js", "preview": "vite preview", diff --git a/scripts/check-shipped-types.ts b/scripts/check-shipped-types.ts new file mode 100644 index 000000000..843a2cdd5 --- /dev/null +++ b/scripts/check-shipped-types.ts @@ -0,0 +1,131 @@ +#!/usr/bin/env tsx +/** + * check-shipped-types.ts + * + * Typecheck every declaration file in `dist/` the way a consumer does, with + * `skipLibCheck` off, and fail on any reference that does not resolve. + * + * Why this exists + * --------------- + * `tsconfig.json` sets `stripInternal: true`. TypeScript honours that by + * deleting `@internal` declarations from the emitted `.d.ts` — but it does not + * check whether anything still refers to them, and it does not rewrite the + * imports that name them. Tag a type `@internal` while a non-internal + * declaration keeps it in its signature and the published package ships a + * `.d.ts` that cannot compile: + * + * import type { KnowledgeSelection } from "../types/index.js"; + * // ^ stripped from types/index.d.ts, still imported here + * + * Consumers with `skipLibCheck: true` (the common default) never notice. + * Everyone else gets TS2305/TS2724 from inside `node_modules` and no + * actionable message. This shipped twice before the check existed — + * `KnowledgeSelection` and friends in `knowledge/`, and + * `GitToolRuntimeSettings` in `agent/gitTools.d.ts`. + * + * The fix is always one of two things, decided by whether the *referencing* + * declaration is public: drop `@internal` from the type, or add it to the + * declaration that names it. Never leave the pair inconsistent. + * + * Scope note: this deliberately roots the program at every `.d.ts` in `dist/`, + * not just the ones reachable from the package entry point. A file that no + * public path imports today still ships, and a deep import of it is a + * supported-enough thing to keep compiling. + * + * Exit codes + * ---------- + * 0 Every shipped declaration file typechecks. + * 1 At least one unresolved reference, or `dist/` has not been built. + */ + +import { readdirSync, statSync } from "node:fs"; +import { join, relative } from "node:path"; +import ts from "typescript"; + +const ROOT = process.cwd(); +const DIST = join(ROOT, "dist"); + +/** Errors that mean "this declaration names something that isn't there". */ +const UNRESOLVED_REFERENCE_CODES = new Set([ + 2305, // Module '"X"' has no exported member 'Y'. + 2307, // Cannot find module 'X' or its corresponding type declarations. + 2724, // 'X' has no exported member named 'Y'. Did you mean 'Z'? +]); + +/** + * A build must exist and be substantial before the result means anything. + * An empty or missing `dist/` would otherwise report a clean pass. + */ +const MINIMUM_DECLARATION_FILES = 100; + +const collectDeclarationFiles = (dir: string, found: string[] = []): string[] => { + for (const entry of readdirSync(dir)) { + const full = join(dir, entry); + if (statSync(full).isDirectory()) { + collectDeclarationFiles(full, found); + } else if (entry.endsWith(".d.ts")) { + found.push(full); + } + } + return found; +}; + +const main = (): number => { + let files: string[]; + try { + files = collectDeclarationFiles(DIST); + } catch { + console.error("✗ dist/ not found — run `pnpm run build` first."); + return 1; + } + + if (files.length < MINIMUM_DECLARATION_FILES) { + console.error( + `✗ only ${files.length} declaration file(s) under dist/ — expected at ` + + `least ${MINIMUM_DECLARATION_FILES}. The build is missing or partial, ` + + `so a pass here would prove nothing.`, + ); + return 1; + } + + const program = ts.createProgram(files, { + strict: true, + skipLibCheck: false, + noEmit: true, + module: ts.ModuleKind.NodeNext, + moduleResolution: ts.ModuleResolutionKind.NodeNext, + target: ts.ScriptTarget.ES2022, + }); + + const unresolved = ts + .getPreEmitDiagnostics(program) + .filter((diagnostic) => UNRESOLVED_REFERENCE_CODES.has(diagnostic.code)) + .filter((diagnostic) => diagnostic.file?.fileName.startsWith(DIST)); + + console.log(`Checked ${files.length} declaration file(s) under dist/.`); + + if (unresolved.length === 0) { + console.log("✓ every shipped declaration resolves."); + return 0; + } + + console.error(`\n✗ ${unresolved.length} unresolved reference(s) in shipped types:\n`); + for (const diagnostic of unresolved) { + const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, " "); + const file = diagnostic.file; + if (file && diagnostic.start !== undefined) { + const { line, character } = file.getLineAndCharacterOfPosition(diagnostic.start); + console.error(` ${relative(ROOT, file.fileName)}:${line + 1}:${character + 1}`); + console.error(` TS${diagnostic.code}: ${message}`); + } else { + console.error(` TS${diagnostic.code}: ${message}`); + } + } + console.error( + "\nUsually a `@internal` tag on a type that a non-internal declaration " + + "still names. Drop the tag, or tag the declaration that names it.", + ); + return 1; +}; + +process.exit(main()); diff --git a/src/lib/types/gitTools.ts b/src/lib/types/gitTools.ts index 34d2e6eb8..3726320e7 100644 --- a/src/lib/types/gitTools.ts +++ b/src/lib/types/gitTools.ts @@ -73,7 +73,12 @@ export type GitToolRefusal = { isError: true; error: string }; /** * Resolved git toolset settings for one host. * - * @internal + * Deliberately not marked internal: it is the return type of + * `configureGitTools`, so it is named by an emitted declaration. Marking it + * would make `stripInternal` delete the type without touching the import that + * references it, leaving a .d.ts that fails to compile for any consumer using + * `skipLibCheck: false`. (Note that the tag is matched as plain text anywhere + * in the doc comment, so it cannot even be named here to explain itself.) */ export type GitToolRuntimeSettings = { repoRoot: string; diff --git a/src/lib/types/knowledge.ts b/src/lib/types/knowledge.ts index a2e1fec37..3b95d4a88 100644 --- a/src/lib/types/knowledge.ts +++ b/src/lib/types/knowledge.ts @@ -410,8 +410,15 @@ export type KnowledgeValidationResult = { }; // --------------------------------------------------------------------------- -// Engine-internal working types (kept here per the repo rule that every type -// alias lives in src/lib/types/, including @internal ones). +// Engine working types (kept here per the repo rule that every type alias lives +// in src/lib/types/, including @internal ones). +// +// Only types that never reach an emitted signature carry @internal. The rest +// are public by construction: they appear in the .d.ts of public runtime +// exports (assembleKnowledgeContext, retrieve, resolveEntry, manifestToSources, +// normalizeAndValidate), and `stripInternal` does not rewrite the imports that +// reference them — tagging those produced .d.ts files that failed to compile +// for any consumer using skipLibCheck: false. // --------------------------------------------------------------------------- /** A source after loading: raw entries plus the version to apply. @internal */ @@ -421,18 +428,18 @@ export type KnowledgeLoadedSource = { entries: KnowledgeEntryInput[]; }; -/** Options for normalizing + validating a set of sources before indexing. @internal */ +/** Options for normalizing + validating a set of sources before indexing. */ export type KnowledgeNormalizeOptions = { manifestVersion: string; }; -/** Normalized entries paired with the validation outcome. @internal */ +/** Normalized entries paired with the validation outcome. */ export type KnowledgeNormalizeResult = { entries: NormalizedKnowledgeEntry[]; validation: KnowledgeValidationResult; }; -/** Retrieval tuning after config + SDK defaults are merged. @internal */ +/** Retrieval tuning after config + SDK defaults are merged. */ export type KnowledgeResolvedRetrieval = { candidateLimit: number; resultLimit: number; @@ -442,7 +449,7 @@ export type KnowledgeResolvedRetrieval = { aliasBoost: number; }; -/** One scored retrieval candidate with its signal breakdown, for traces. @internal */ +/** One scored retrieval candidate with its signal breakdown, for traces. */ export type KnowledgeScoredCandidate = { id: string; score: number; @@ -453,7 +460,7 @@ export type KnowledgeScoredCandidate = { matchedPhrases: string[]; }; -/** The selected primary + relationship-expanded entries for one turn. @internal */ +/** The selected primary + relationship-expanded entries for one turn. */ export type KnowledgeSelection = { primary: NormalizedKnowledgeEntry[]; expanded: NormalizedKnowledgeEntry[]; @@ -462,7 +469,7 @@ export type KnowledgeSelection = { candidateCount: number; }; -/** The assembled ephemeral-context string plus its diagnostics. @internal */ +/** The assembled ephemeral-context string plus its diagnostics. */ export type KnowledgeAssembledContext = { assembledContext: string; citations: KnowledgeCitation[]; diff --git a/tsconfig.ci-scripts.json b/tsconfig.ci-scripts.json index 264ce81df..e488f078d 100644 --- a/tsconfig.ci-scripts.json +++ b/tsconfig.ci-scripts.json @@ -29,6 +29,7 @@ "include": [ "scripts/build-validations.ts", "scripts/check-banned-deps.ts", + "scripts/check-shipped-types.ts", "scripts/env-validation.ts", "scripts/security-check.ts", "tools/verify-provider-onboarding.ts",