From c94b03f17b2d540b5a146946910fb6b522e1c221 Mon Sep 17 00:00:00 2001 From: Dan Draper Date: Tue, 2 Jun 2026 10:56:09 +1000 Subject: [PATCH 1/4] fix(reference): resolve TypeDoc link warnings in the stack API reference Configure the stack TypeDoc build so the operation-class and helper cross-references resolve instead of warning: - map @byteslice/result's Result to its npm page (externalSymbolLinkMappings) - add errors/index.ts as an entry point so EncryptionError is documented - list deliberately-internal referenced types (brands, zod schemas, *WithLockContext operation variants) under intentionallyNotExported Pairs with cipherstash/stack#502, which exports the operation classes those links target. Together they take the stack reference build from 54 warnings to 0. --- scripts/generate-docs.ts | 1 + scripts/lib/docs-generator.ts | 43 +++++++++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+) diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts index afc02ad..e254677 100644 --- a/scripts/generate-docs.ts +++ b/scripts/generate-docs.ts @@ -27,6 +27,7 @@ const stackConfig: DocsConfig = { "./packages/stack/src/identity/index.ts", "./packages/stack/src/types-public.ts", "./packages/stack/src/client.ts", + "./packages/stack/src/errors/index.ts", ], tsconfigInclude: ["packages/stack/src/**/*"], tagFilter: (tag: string) => diff --git a/scripts/lib/docs-generator.ts b/scripts/lib/docs-generator.ts index 1c2469e..97ee1b2 100644 --- a/scripts/lib/docs-generator.ts +++ b/scripts/lib/docs-generator.ts @@ -244,6 +244,49 @@ export async function generateDocsForTag( excludePrivate: true, excludeProtected: true, excludeInternal: true, + // Map external-package symbols referenced in {@link} tags to their upstream + // docs so the links resolve instead of warning. `Result` comes from + // @byteslice/result, which is not part of the generated reference. + externalSymbolLinkMappings: { + "@byteslice/result": { + Result: "https://www.npmjs.com/package/@byteslice/result", + }, + }, + // Types that are deliberately not exported from the public entry points but + // are referenced by exported declarations (return types, params, mapped + // types). Listing them here documents the intent and silences the + // "referenced by ... but not included" warnings. The *WithLockContext + // variants are the lock-context-aware operation classes returned by + // `.withLockContext()`; the rest are internal helper/brand/zod-schema types. + intentionallyNotExported: [ + "Brand", + "AtLeastOneCsTable", + "QueryTermBase", + "DecryptionSuccess", + "DecryptionError", + "tokenFilterSchema", + "matchIndexOptsSchema", + "steVecIndexOptsSchema", + "uniqueIndexOptsSchema", + "oreIndexOptsSchema", + "columnSchema", + "TableDefinition", + "AuditConfig", + "AuditData", + "DynamoDBOperationOptions", + "FilterOp", + "DrizzleEncryptedSchema", + "EncryptOperationWithLockContext", + "EncryptQueryOperationWithLockContext", + "BatchEncryptQueryOperationWithLockContext", + "DecryptOperationWithLockContext", + "EncryptModelOperationWithLockContext", + "DecryptModelOperationWithLockContext", + "BulkEncryptOperationWithLockContext", + "BulkDecryptOperationWithLockContext", + "BulkEncryptModelsOperationWithLockContext", + "BulkDecryptModelsOperationWithLockContext", + ], useCodeBlocks: true, expandObjects: true, hideBreadcrumbs: true, From d5bab07f184e574c0b2bcdbf3042b79bb92bfa37 Mon Sep 17 00:00:00 2001 From: Dan Draper Date: Tue, 2 Jun 2026 12:02:32 +1000 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Dan Draper --- content/stack/cipherstash/kms/access-keys.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/stack/cipherstash/kms/access-keys.mdx b/content/stack/cipherstash/kms/access-keys.mdx index 4fdad4b..61c95be 100644 --- a/content/stack/cipherstash/kms/access-keys.mdx +++ b/content/stack/cipherstash/kms/access-keys.mdx @@ -1,6 +1,6 @@ --- title: Access keys -description: Create and manage CipherStash access keys for programmatic access to CTS and ZeroKMS, with member, control, and admin roles and their available scopes. +description: Create and manage CipherStash access keys for programmatic access to CipherStash Services like ZeroKMS, with member, control, and admin roles and their available scopes. --- Access keys are used to authenticate programmatic access to CipherStash [CTS](/stack/cipherstash/kms/cts) and [ZeroKMS](/stack/cipherstash/kms). From fa0f23756ebd5f64eff1720cb4eb19c07b3c3b69 Mon Sep 17 00:00:00 2001 From: Dan Draper Date: Tue, 2 Jun 2026 12:02:51 +1000 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Dan Draper --- content/stack/reference/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/stack/reference/index.mdx b/content/stack/reference/index.mdx index 3ff2267..5acc9a0 100644 --- a/content/stack/reference/index.mdx +++ b/content/stack/reference/index.mdx @@ -1,6 +1,6 @@ --- title: API Reference -description: Browse the CipherStash API reference, including the @cipherstash/stack SDK with Encryption and Secrets, plus the EQL types, operators, and functions. +description: Browse the CipherStash API reference, including the @cipherstash/stack SDK with Encryption, plus types, operators, and functions. --- Auto-generated TypeDoc reference for CipherStash packages. For hand-written guides and examples, see the [Encryption docs](/stack/cipherstash/encryption). From 39884e94e491f8d70eae066ccf5103dbbc5fa3d3 Mon Sep 17 00:00:00 2001 From: Dan Draper Date: Tue, 2 Jun 2026 14:35:03 +1000 Subject: [PATCH 4/4] docs(reference): clarify intentionallyNotExported intent, split internal vs pending-export The list only silences "referenced but not included" warnings; it does not document the types. Rewrite the comment to say so, and split the array into two groups: - genuinely internal helpers/brands/zod-schema values (keep suppressed) - public API surface that is useful to document but not yet reachable from a documented entry point (*WithLockContext operation classes, AuditConfig/AuditData, DynamoDBOperationOptions, FilterOp) suppressed only as a stopgap until a stack follow-up re-exports them the way #502 did for the base operation classes, after which they should be removed. Addresses review feedback on the list. No entries removed, so the build stays at 0 warnings. --- scripts/lib/docs-generator.ts | 32 ++++++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/scripts/lib/docs-generator.ts b/scripts/lib/docs-generator.ts index 97ee1b2..d787979 100644 --- a/scripts/lib/docs-generator.ts +++ b/scripts/lib/docs-generator.ts @@ -252,16 +252,24 @@ export async function generateDocsForTag( Result: "https://www.npmjs.com/package/@byteslice/result", }, }, - // Types that are deliberately not exported from the public entry points but - // are referenced by exported declarations (return types, params, mapped - // types). Listing them here documents the intent and silences the - // "referenced by ... but not included" warnings. The *WithLockContext - // variants are the lock-context-aware operation classes returned by - // `.withLockContext()`; the rest are internal helper/brand/zod-schema types. + // NOTE: `intentionallyNotExported` only *silences* the "referenced by ... + // but not included" warning — it does NOT add the type to the reference. + // So it is the right tool only for genuinely-internal types. Anything a + // consumer would want to know about should instead be re-exported from a + // documented entry point (the way the base operation classes are surfaced + // via the `export { ... }` block in stack's encryption/index.ts, per + // cipherstash/stack#502) so it renders as a real reference page — and then + // removed from this list. The array is split accordingly. intentionallyNotExported: [ + // --- Genuinely internal: keep suppressed indefinitely. --- + // Helper/brand types, zod schema *values* (the runtime validators, not the + // inferred option types), and decrypt-result union members. QueryTermBase + // and TableDefinition are marked "excluded"/"used internally" in the stack + // source itself, so they belong here too. "Brand", "AtLeastOneCsTable", "QueryTermBase", + "TableDefinition", "DecryptionSuccess", "DecryptionError", "tokenFilterSchema", @@ -270,12 +278,20 @@ export async function generateDocsForTag( "uniqueIndexOptsSchema", "oreIndexOptsSchema", "columnSchema", - "TableDefinition", + "DrizzleEncryptedSchema", + + // --- Public API surface, suppressed only as a STOPGAP. --- + // These are useful to document but are not yet reachable from a documented + // entry point. The fix is stack-side: re-export them (the *WithLockContext + // operation classes + AuditConfig/AuditData from encryption/index.ts, + // DynamoDBOperationOptions from dynamodb/index.ts, FilterOp from + // supabase/index.ts) the same way cipherstash/stack#502 surfaced the base + // operation classes. Once a stack release exports them, REMOVE them here so + // they become real reference pages. (#502 covered the base classes only.) "AuditConfig", "AuditData", "DynamoDBOperationOptions", "FilterOp", - "DrizzleEncryptedSchema", "EncryptOperationWithLockContext", "EncryptQueryOperationWithLockContext", "BatchEncryptQueryOperationWithLockContext",