@stainless-api/docs-ui 0.1.0-beta.13 → 0.1.0-beta.15

package/src/languages/typescript.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type * as TSAST from '~/lib/json-spec-v2/TSAST';
+import { TSAST } from '@stainless/sdk-json';
 import { useDeclaration, useLanguage, useLanguageComponents, useSpec } from '../contexts';
 import { useComponents } from '../contexts/use-components';
 import style from '../style';
@@ -13,7 +13,7 @@ const ComplexTypes: Record<string, string> = {
   TSTypeArray: 'array',
 };
 
-const constStyle = {
+const constStyle: Record<string, string> = {
   string: style.LiteralString,
   number: style.LiteralNumeric,
   boolean: style.LiteralBoolean,
@@ -66,17 +66,23 @@ function TypeParams({ params }: { params?: TSAST.TSTypeParameter[] }) {
 function TypePreview({ path }: { path: string }) {
   const spec = useSpec();
   const language = useLanguage();
-  const decl = useDeclaration(path);
+  const decl = useDeclaration(path, false);
   const { Join } = useComponents();
 
-  if (!(decl && 'children' in decl && decl.children.length > 0) || decl['type']?.['kind'] === 'TSTypeUnion')
+  if (
+    !(decl && 'children' in decl && decl.children && decl.children.length > 0) ||
+    (decl && 'type' in decl && 'kind' in decl['type'] && decl['type']['kind'] === 'TSTypeUnion')
+  )
     return;
 
-  const items = decl.children.map((prop, key) => (
-    <span key={key} className={style.TypePropertyName}>
-      <span className={style.TextIdentifier}>{spec?.decls?.[language]?.[prop]?.['key']}</span>
-    </span>
-  ));
+  const items = decl.children.map((prop, key) => {
+    const p = spec?.decls?.[language]?.[prop];
+    return (
+      <span key={key} className={style.TypePropertyName}>
+        <span className={style.TextIdentifier}>{p && 'key' in p ? p['key'] : null}</span>
+      </span>
+    );
+  });
 
   return (
     <span className={style.TypePreview} data-stldocs-type-preview="properties">
@@ -146,7 +152,7 @@ export function Type({ type }: TypeProps) {
 
       return (
         <span className={style.Type}>
-          <SDKReference stainlessPath={type.$ref}>{name}</SDKReference>
+          <SDKReference stainlessPath={type.$ref!}>{name}</SDKReference>
           {params && params.length > 0 && (
             <>
               <span className={style.TypeBracket}>{'<'}</span>
@@ -156,7 +162,7 @@ export function Type({ type }: TypeProps) {
               <span className={style.TypeBracket}>{'>'}</span>
             </>
           )}
-          <TypePreview path={type.$ref} />
+          <TypePreview path={type.$ref!} />
         </span>
       );
     }
@@ -274,7 +280,7 @@ export function MethodSignature({ decl }: MethodSignatureProps) {
 
 export type PropertyProps = {
   decl: TSAST.TSDeclaration;
-  children?: PropertyFn;
+  children: PropertyFn;
 };
 
 export function Property({ decl, children }: PropertyProps) {

package/src/markdown/index.ts

@@ -2,7 +2,7 @@ import Markdoc from '@markdoc/markdoc';
 import * as md from './md';
 import { EnvironmentType, getDecl, getSnippet, stripMarkup } from './utils';
 import * as printer from '../search/printer';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import type * as SDKJSON from '@stainless/sdk-json';
 import type { Node } from '@markdoc/markdoc';
 
 export function declaration(env: EnvironmentType, decl: SDKJSON.DeclarationNode) {
@@ -15,20 +15,20 @@ function renderChildren(env: EnvironmentType, children: SDKJSON.ID[], nesting: s
 }
 
 function renderDecl(env: EnvironmentType, path: string, nesting: string[] = []) {
-  const decl = getDecl(env, path);
+  const decl = getDecl(env, path)!;
   const item = md.item(declaration(env, decl));
 
-  const hasChildren = 'children' in decl && decl.children.length > 0;
-  const showModelProps = !decl['modelPath'] || env.options.includeModelProperties;
+  const hasChildren = 'children' in decl && decl.children && decl.children.length > 0;
+  const showModelProps = !('modelPath' in decl && decl['modelPath']) || env.options.includeModelProperties;
 
   if ('docstring' in decl && decl.docstring) item.children.push(...md.parse(decl.docstring));
   if (hasChildren && showModelProps && !nesting.includes(path))
-    item.push(renderChildren(env, decl.children, [...nesting, path]));
+    item.push(renderChildren(env, decl.children ?? [], [...nesting, path]));
 
   return item;
 }
 
-function renderMethod(env: EnvironmentType, method: SDKJSON.Method) {
+function renderMethod(env: EnvironmentType, method: SDKJSON.Method): Node[] {
   const decl = getDecl(env, method.stainlessPath);
 
   if (!decl)
@@ -41,11 +41,11 @@ function renderMethod(env: EnvironmentType, method: SDKJSON.Method) {
     ];
 
   const signature = printer.methodSignature(env.language, decl);
-  const [httpMethod, endpoint] = method.endpoint.split(' ');
+  const [httpMethod, endpoint] = method.endpoint.split(' ') as [string, string];
 
   const output = [
     md.heading(2, method.title),
-    env.language === 'http' ? null : md.paragraph(md.code(stripMarkup(signature))),
+    ...(env.language === 'http' ? [] : [md.paragraph(md.code(stripMarkup(signature)))]),
     md.paragraph(md.strong(md.text(httpMethod)), md.text(' '), md.code(endpoint)),
   ];
 
@@ -54,7 +54,7 @@ function renderMethod(env: EnvironmentType, method: SDKJSON.Method) {
   if ('paramsChildren' in decl && Array.isArray(decl.paramsChildren) && decl.paramsChildren.length > 0)
     output.push(md.heading(3, 'Parameters'), renderChildren(env, decl.paramsChildren));
 
-  if ('responseChildren' in decl && decl.responseChildren.length > 0)
+  if ('responseChildren' in decl && decl.responseChildren && decl.responseChildren.length > 0)
     output.push(md.heading(3, 'Returns'), renderChildren(env, decl.responseChildren));
 
   const snippet = getSnippet(env, method.stainlessPath);
@@ -67,7 +67,7 @@ function renderModel(env: EnvironmentType, model: SDKJSON.Model) {
   return [md.heading(3, model.title), md.list(renderDecl(env, `${model.stainlessPath} > (schema)`))];
 }
 
-function renderResource(env: EnvironmentType, resource: SDKJSON.Resource) {
+function renderResource(env: EnvironmentType, resource: SDKJSON.Resource): Node[] {
   const methods = Object.values(resource.methods)
     .filter((method) => getDecl(env, method.stainlessPath))
     .flatMap((method) => renderMethod(env, method));
@@ -82,11 +82,16 @@ function renderResource(env: EnvironmentType, resource: SDKJSON.Resource) {
 
   if (!env.options.renderNestedResources) return doc;
 
-  const children = Object.values(resource.subresources).map((resource) => renderResource(env, resource));
+  const children = Object.values(resource.subresources ?? {}).flatMap((resource) =>
+    renderResource(env, resource),
+  );
   return [...doc, ...children];
 }
 
-export function render(env: EnvironmentType, node: SDKJSON.Resource | SDKJSON.Method | SDKJSON.Model) {
+export function render(
+  env: EnvironmentType,
+  node: SDKJSON.Resource | SDKJSON.Method | SDKJSON.Model,
+): Node[] {
   switch (node.kind) {
     case 'resource':
       return renderResource(env, node);

package/src/markdown/utils.ts

@@ -1,6 +1,6 @@
 import { Parser } from 'htmlparser2';
 import type { DocsLanguage } from '../routing';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import type * as SDKJSON from '@stainless/sdk-json';
 import type { TransformRequestSnippetFn } from '../components/sdk';
 
 export type EnvironmentType = {
@@ -19,7 +19,10 @@ export function getDecl(env: EnvironmentType, path: string) {
   const decl = env.spec?.decls?.[env.language]?.[path];
 
   if (decl?.kind?.endsWith('Reference')) {
-    const refId = decl['type']['$ref'];
+    const refId =
+      'type' in decl && typeof decl['type'] === 'object' && '$ref' in decl['type']
+        ? decl['type']['$ref']
+        : null;
     if (refId === path) return decl;
     if (refId) return getDecl(env, refId);
   }
@@ -28,7 +31,7 @@ export function getDecl(env: EnvironmentType, path: string) {
 }
 
 export function getSnippet(env: EnvironmentType, path: string) {
-  let snippet = env.spec?.snippets?.[`${env.language}.default`]?.[path];
+  let snippet = env.spec?.snippets?.[`${env.language}.default` as SDKJSON.SnippetLanguage]?.[path];
   if (typeof snippet === 'string' && env.transforms?.transformRequestSnippet) {
     snippet = env.transforms.transformRequestSnippet({ snippet, language: env.language });
   }

package/src/routing.ts

@@ -1,4 +1,4 @@
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import type * as SDKJSON from '@stainless/sdk-json';
 
 export const Languages = [
   'http',
@@ -56,10 +56,10 @@ export type ParsedStainlessPath = ReturnType<typeof parseStainlessPath>;
 export function parseStainlessPath(stainlessPath: string) {
   const match = stainlessPath.match(StainlessPathPattern);
 
-  if (!match) return null;
+  if (!match?.groups) return null;
 
   return {
-    resource: match.groups.resource.split('.'),
+    resource: match.groups.resource?.split('.') ?? null,
     method: match.groups.method ?? null,
     model: match.groups.model ?? null,
     routable: match.groups.model ? match[1] : match[0],
@@ -72,7 +72,7 @@ export function trimStainlessPath(stainlessPath: string) {
 
 export function getResource(stainlessPath: string) {
   const parsed = parseStainlessPath(stainlessPath);
-  return parsed?.resource[0];
+  return parsed?.resource?.[0];
 }
 
 export function parseRoute(
@@ -119,7 +119,7 @@ export function generateRoute(basePath: string, language: string, stainlessPath:
   const path = [basePath.endsWith('/') ? basePath.slice(0, -1) : basePath];
   if (language && language !== DefaultLanguage) path.push(language);
 
-  const resources = parsedPath.resource.flatMap((name, index) => [
+  const resources = parsedPath.resource!.flatMap((name, index) => [
     index > 0 ? 'subresources' : 'resources',
     name,
   ]);
@@ -130,7 +130,7 @@ export function generateRoute(basePath: string, language: string, stainlessPath:
 
   if (parsedPath.method) path.push('methods', parsedPath.method);
 
-  return stainlessPath.length > parsedPath.routable.length
+  return stainlessPath.length > parsedPath.routable!.length
     ? `${path.join('/')}#${encodeURIComponent(stainlessPath)}`
     : path.join('/');
 }
@@ -203,7 +203,7 @@ export function generateRouteList({
 
 type ResourceOrMethod = SDKJSON.Resource | SDKJSON.Method;
 
-export function findNavigationPath(items: ResourceOrMethod[], target: string) {
+export function findNavigationPath(items: ResourceOrMethod[], target: string): string[] | undefined {
   for (const item of Object.values(items)) {
     if (item.stainlessPath === target) return [item.stainlessPath];
     if (item.kind === 'http_method') continue;
@@ -217,9 +217,9 @@ export function findNavigationPath(items: ResourceOrMethod[], target: string) {
   }
 }
 
-export function expandToElement(el: HTMLElement) {
+export function expandToElement(el: HTMLElement | null) {
   while (el) {
-    if (el.tagName === 'DETAILS') el['open'] = true;
+    if (el instanceof HTMLDetailsElement) el.open = true;
     el = el.parentElement;
   }
 }

package/src/search/form.tsx

@@ -14,36 +14,36 @@ export function SearchForm() {
   const language = useLanguage();
   const { onSelect, pageFind } = useSearchContext();
 
-  const [results, setResults] = React.useState<ResultData>(null);
+  const [results, setResults] = React.useState<ResultData>(null!);
   const [filterKind, setFilterKind] = React.useState<QueryKindsType>('all');
   const [searchQuery, setSearchQuery] = React.useState<string>('');
   const inputRef = React.useRef<HTMLInputElement>(null);
 
-  async function performSearch() {
-    const guideLimit = filterKind === 'guide' ? 25 : 5;
-    const kind = ['all', 'guide'].includes(filterKind) ? undefined : filterKind;
-
-    const [guideResults, apiResults] = await Promise.all([
-      pageFind ? guideSearch(pageFind, searchQuery, guideLimit) : [],
-      search({ query: searchQuery, kind, language }),
-    ]);
-
-    setResults({
-      items: filterKind === 'guide' ? guideResults : [...guideResults, ...apiResults.hits],
-      counts: {
-        ...apiResults.facets?.['kind'],
-        guide: guideResults.length,
-        all: apiResults.nbHits,
-      },
-    });
-  }
-
   function clearInput() {
     setSearchQuery('');
     inputRef?.current?.focus();
   }
 
-  React.useEffect(() => void performSearch(), [searchQuery, filterKind, language]);
+  React.useEffect(() => {
+    (async function performSearch() {
+      const guideLimit = filterKind === 'guide' ? 25 : 5;
+      const kind = ['all', 'guide'].includes(filterKind) ? undefined : filterKind;
+
+      const [guideResults, apiResults] = await Promise.all([
+        pageFind ? guideSearch(pageFind, searchQuery, guideLimit) : [],
+        search({ query: searchQuery, kind, language }),
+      ]);
+
+      setResults({
+        items: filterKind === 'guide' ? guideResults : [...guideResults, ...(apiResults?.hits ?? [])],
+        counts: {
+          ...apiResults?.facets?.['kind'],
+          guide: guideResults.length,
+          all: apiResults?.nbHits,
+        },
+      });
+    })();
+  }, [searchQuery, filterKind, language, pageFind, search]);
 
   return (
     <div className={style.SearchForm}>
@@ -72,7 +72,9 @@ export function SearchForm() {
         itemDelegate={(item) =>
           'kind' in item ? <SearchResult result={item} /> : <GuideResult result={item} />
         }
-        onSelectListItem={(item) => onSelect?.(item['data']?.['url'] ?? item['stainlessPath'])}
+        onSelectListItem={(item) =>
+          onSelect?.((item as any)['data']?.['url'] ?? (item as any)['stainlessPath'])
+        }
       />
     </div>
   );
@@ -81,7 +83,7 @@ export function SearchForm() {
 export type SearchFilterProps = {
   results: ResultData;
   filterKind: QueryKindsType;
-  onChange: (filterKind?: QueryKindsType) => void;
+  onChange: (filterKind: QueryKindsType) => void;
 };
 
 export function SearchFilter({ results, filterKind, onChange }: SearchFilterProps) {
@@ -111,7 +113,7 @@ export type SearchModalProps = {
 };
 
 export function SearchModal({ id, open: isOpen }: SearchModalProps) {
-  const [open, setOpen] = React.useState<boolean>(isOpen);
+  const [open, setOpen] = React.useState<boolean>(isOpen ?? false);
 
   return (
     <div

package/src/search/indexer.ts

@@ -1,6 +1,6 @@
 import { generateRoute, Languages, parseStainlessPath, walkTree } from '../routing';
 import * as printer from './printer';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import type * as SDKJSON from '@stainless/sdk-json';
 import type { IndexEntry } from './types';
 import { renderMarkdown } from '../markdown';
 
@@ -93,8 +93,8 @@ export function* generateChatIndex(spec: SDKJSON.Spec) {
           summary,
           description,
           stainlessPath,
-          qualified: decl['qualified'],
-          ident: decl['ident'],
+          qualified: 'qualified' in decl ? decl['qualified'] : undefined,
+          ident: 'ident' in decl ? decl['ident'] : undefined,
           content: chunk,
           url: generateRoute('docs://BASE_PATH', language, stainlessPath),
         };
@@ -105,7 +105,7 @@ export function* generateChatIndex(spec: SDKJSON.Spec) {
 
 export function* generateIndex(
   spec: SDKJSON.Spec,
-  renderMarkdownFn?: (string?) => string | null,
+  renderMarkdownFn?: (_: string) => string | null,
   includeTypes?: boolean,
 ): Generator<IndexEntry> {
   const parentCrumbs: Record<string, string[]> = {};
@@ -113,8 +113,8 @@ export function* generateIndex(
     const { kind, name, title, stainlessPath } = data;
     const common = { name, title, stainlessPath };
 
-    const parsedPath = parseStainlessPath(stainlessPath);
-    const crumbs = getResourceNames(parsedPath.resource, spec.resources);
+    const parsedPath = parseStainlessPath(stainlessPath)!;
+    const crumbs = getResourceNames(parsedPath.resource!, spec.resources);
 
     switch (kind) {
       case 'resource':
@@ -144,7 +144,7 @@ export function* generateIndex(
           if (!found) continue;
 
           parentCrumbs[stainlessPath] = [...crumbs, title];
-          const qualified = found['qualified'];
+          const qualified = 'qualified' in found ? found['qualified'] : undefined;
           const ident = qualified?.split('.')?.at(-1);
 
           yield {
@@ -153,7 +153,9 @@ export function* generateIndex(
             ident,
             qualified,
             language,
-            description: renderMarkdownFn?.(data.description) ?? data.description,
+            description: data.description
+              ? (renderMarkdownFn?.(data.description) ?? data.description)
+              : undefined,
             endpoint: endpoint.slice(httpMethod.length).trim(),
             httpMethod,
             summary,
@@ -172,9 +174,9 @@ export function* generateIndex(
           parentCrumbs[stainlessPath] = [...crumbs, title];
           const schema = spec.decls[language]?.[`${stainlessPath} > (schema)`];
           const children =
-            schema?.['children']
+            (schema && 'children' in schema ? schema?.['children'] : undefined)
               ?.map((childPath) => {
-                const child = spec.decls?.[language]?.[childPath];
+                const child = spec.decls?.[language]?.[childPath] as any;
                 return (
                   child?.['ident'] ??
                   child?.['name'] ??
@@ -192,7 +194,7 @@ export function* generateIndex(
             children,
             language,
             priority: 2,
-            ident: schema?.['ident'],
+            ident: schema && 'ident' in schema ? schema?.['ident'] : undefined,
             ...common,
           };
         }
@@ -213,11 +215,11 @@ export function* generateIndex(
         case 'HttpDeclProperty':
         case 'TSDeclProperty':
           {
-            const parsedPath = parseStainlessPath(decl.stainlessPath);
+            const parsedPath = parseStainlessPath(decl.stainlessPath)!;
             const type = includeTypes === false ? undefined : printer.typeName(language, decl.type);
-            const name = decl['ident'] ?? decl['name'] ?? decl['key'];
+            const name: string = (decl as any)['ident'] ?? (decl as any)['name'] ?? (decl as any)['key'];
 
-            const parent = parentCrumbs[parsedPath.routable];
+            const parent = parentCrumbs[parsedPath.routable!];
             // Filter out properties of non-routable response types
             if (parent === undefined) continue;
 
@@ -232,7 +234,7 @@ export function* generateIndex(
               name,
               stainlessPath: decl.stainlessPath,
               crumbs: [...parent, ...props],
-              docstring: renderMarkdownFn?.(decl.docstring) ?? decl.docstring,
+              docstring: decl.docstring ? (renderMarkdownFn?.(decl.docstring) ?? decl.docstring) : undefined,
               type,
               language,
               priority: 3,

package/src/search/mcp.ts

@@ -1,28 +1,38 @@
+import { BM25Retriever } from '@langchain/community/retrievers/bm25';
 import { renderMarkdown } from '../markdown';
 import { DocsLanguage, parseStainlessPath } from '../routing';
 import { getResourceFromSpec } from '../utils';
-import { buildIndex, search } from './providers/fuse';
-import type { IndexEntry } from './types';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import { buildIndex, search as fuseSearch } from './providers/fuse';
+import type { IndexEntry, IndexMethod } from './types';
+import natural from 'natural';
+import type * as SDKJSON from '@stainless/sdk-json';
+
+type Item = IndexEntry & IndexMethod;
+
+export interface SearchResult {
+  item: Item;
+  score?: number;
+  refIndex: number;
+}
 
 export function consolidate(results: IndexEntry[]) {
   const resources = new Set<string>();
   const methods = new Set<string>();
 
   for (const entry of results) {
-    const parsed = parseStainlessPath(entry.stainlessPath);
-    if (parsed.method) methods.add(parsed.routable);
-    else resources.add(parsed.routable);
+    const parsed = parseStainlessPath(entry.stainlessPath)!;
+    if (parsed.method) methods.add(parsed.routable!);
+    else resources.add(parsed.routable!);
   }
 
-  const filtered = Array.from(methods).filter((path) => !resources.has(path.split(' >').at(0)));
+  const filtered = Array.from(methods).filter((path) => !resources.has(path.split(' >').at(0)!));
   return [...resources, ...filtered];
 }
 
 export function render(
   spec: SDKJSON.Spec,
   language: DocsLanguage,
-  items: IndexEntry[],
+  items: Item[],
   includeModelProperties: boolean,
 ) {
   const env = {
@@ -36,9 +46,9 @@ export function render(
 
   const paths = consolidate(items);
   const output = paths.map((entry) => {
-    const parsed = parseStainlessPath(entry);
-    const resource = getResourceFromSpec(parsed.resource, spec);
-    const target = parsed.method ? resource.methods[parsed.method] : resource;
+    const parsed = parseStainlessPath(entry)!;
+    const resource = getResourceFromSpec(parsed.resource!, spec)!;
+    const target = parsed.method ? resource.methods[parsed.method]! : resource;
     const content = renderMarkdown(env, target);
     return [entry, content];
   });
@@ -46,16 +56,98 @@ export function render(
   return Object.fromEntries(output);
 }
 
-export function searchAndRender(
+export async function searchAndRender(
   spec: SDKJSON.Spec,
   language: DocsLanguage,
   query: string,
   limit?: number,
   includeModelProperties: boolean = false,
 ) {
-  const idx = buildIndex(spec, language);
-  const results = search(idx, query, limit).map(({ item }) => item);
-  return render(spec, language, results, includeModelProperties);
+  const results = await search(spec, language, query, limit);
+  const items = results.map(({ item }) => item);
+  return render(spec, language, items, includeModelProperties);
+}
+
+export async function search(
+  spec: SDKJSON.Spec,
+  language: DocsLanguage,
+  query: string,
+  limit: number = 100,
+): Promise<SearchResult[]> {
+  const fuseIndex = buildIndex(spec, language);
+
+  // only HTTP methods are useful for MCP
+  const httpMethodEntries = fuseIndex.content.filter((entry) => entry.kind === 'http_method') as Item[];
+
+  // build BM25 retriever if we have HTTP methods
+  let bm25Retriever: BM25Retriever | null = null;
+  if (httpMethodEntries.length > 0) {
+    const documents = httpMethodEntries.map((entry) => {
+      // empirically, endpoint + summary seems to be a reasonable semantic encapsulation of what the endpoint does
+      const content = `${entry.endpoint} ${entry.summary}`;
+      return {
+        // stem the content - we will be stemming the query as well
+        pageContent: stemText(content),
+        metadata: {
+          stainlessPath: entry.stainlessPath,
+        },
+      };
+    });
+
+    bm25Retriever = BM25Retriever.fromDocuments(documents, { k: 100 });
+  }
+
+  // get initial results from Fuse
+  const rawResults = fuseSearch(fuseIndex, query, 100).filter(
+    (r) => r.item.kind === 'http_method',
+  ) as SearchResult[];
+
+  // only keep HTTP methods
+  const filtered = rawResults.filter((r) => r.item.kind === 'http_method');
+
+  // stem the query and apply BM25 reranking
+  if (filtered.length > 0 && bm25Retriever) {
+    const stemmedQuery = stemText(query);
+
+    // get BM25-ranked result
+    const results = await bm25Retriever.invoke(stemmedQuery);
+    const reranked = results.map((doc) => doc.metadata);
+
+    // build a map of Fuse results by path for fast lookup
+    const sortStart = Date.now();
+    const fuseResultsByPath = new Map(filtered.map((r) => [r.item.stainlessPath, r]));
+
+    // use BM25 ordering to reorder Fuse results
+    const reorderedResults: SearchResult[] = [];
+    for (const doc of reranked) {
+      const fuseResult = fuseResultsByPath.get(doc.stainlessPath);
+      if (fuseResult) {
+        reorderedResults.push(fuseResult);
+      }
+    }
+
+    // replace filtered with reordered results
+    filtered.length = 0;
+    filtered.push(...reorderedResults);
+    console.debug(`  [SORT] Reranked in ${Date.now() - sortStart}ms`);
+  }
+
+  return filtered.slice(0, limit);
 }
 
-export { buildIndex };
+function stemText(text: string): string {
+  if (!text) return '';
+
+  // tokenize manually and stem each word
+  const words = text.toLowerCase().split(/\s+/);
+  const stemmedWords = words
+    .map((word) => {
+      // remove punctuation and stem
+      const cleaned = word.replace(/[^\w]/g, '');
+      if (!cleaned) return '';
+      return natural.LancasterStemmer.stem(cleaned);
+    })
+    .filter((w) => w);
+
+  return stemmedWords.join(' ');
+}

package/src/search/printer.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { renderToStaticMarkup } from 'react-dom/server';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import type * as SDKJSON from '@stainless/sdk-json';
 import type { DocsLanguage } from '../routing';
 
 import { DocsProvider, useLanguageComponents } from '../contexts';

package/src/search/providers/algolia.ts

@@ -1,7 +1,7 @@
 import { searchClient } from '@algolia/client-search';
 import { generateChatIndex, generateIndex } from '../indexer';
 import { SearchableAttributes, SearchableAttributesChat } from '../types';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import type * as SDKJSON from '@stainless/sdk-json';
 import type { ResultRecordType, SearchSettings, SearchParams, ResultType } from '../types';
 
 export async function buildIndex(
@@ -9,7 +9,7 @@ export async function buildIndex(
   indexName: string,
   writeKey: string,
   spec: SDKJSON.Spec,
-  renderMarkdown: (string?) => string | null,
+  renderMarkdown: (_: string) => string | null,
 ): Promise<void> {
   if (!appId || !indexName || !writeKey) return;
   const objects = Array.from(generateIndex(spec, renderMarkdown));
@@ -22,7 +22,7 @@ export async function buildIndex(
       highlightPostTag: '</mark>',
       customRanking: ['asc(priority)'],
       attributesForFaceting: ['language', 'kind'],
-      searchableAttributes: SearchableAttributes,
+      searchableAttributes: [...SearchableAttributes],
     },
   });
 
@@ -81,8 +81,8 @@ export async function search({
     ],
   });
 
-  if ('hits' in results[0] && 'hits' in results[1]) {
+  if ('hits' in results[0]! && 'hits' in results[1]!) {
     const [{ nbHits, facets }, { hits }] = results;
-    return { hits, nbHits, facets };
+    return { hits, nbHits: nbHits ?? 0, facets };
   }
 }