@stainless-api/docs-ui 0.1.0-beta.29 → 0.1.0-beta.30

package/src/search/mcp.ts

@@ -1,156 +0,0 @@
-import { BM25Retriever } from '@langchain/community/retrievers/bm25';
-import { renderMarkdown } from '../markdown';
-import { DocsLanguage, parseStainlessPath } from '../routing';
-import { getResourceFromSpec } from '../utils';
-import { buildIndex, search as fuseSearch } from './providers/fuse';
-import { generateIndex } from './indexer';
-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 filtered = Array.from(methods).filter((path) => !resources.has(path.split(' >').at(0)!));
-  return [...resources, ...filtered];
-}
-
-export function render(
-  spec: SDKJSON.Spec,
-  language: DocsLanguage,
-  items: Item[],
-  includeModelProperties: boolean,
-) {
-  const env = {
-    spec,
-    language,
-    options: {
-      renderNestedResources: false,
-      includeModelProperties,
-    },
-  };
-
-  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 content = renderMarkdown(env, target);
-    return [entry, content];
-  });
-
-  return Object.fromEntries(output);
-}
-
-export async function searchAndRender(
-  spec: SDKJSON.Spec,
-  language: DocsLanguage,
-  query: string,
-  limit?: number,
-  includeModelProperties: boolean = false,
-) {
-  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);
-}
-
-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(' ');
-}
-
-export { generateIndex };

package/src/search/printer.tsx

@@ -1,86 +0,0 @@
-import * as React from 'react';
-import { renderToStaticMarkup } from 'react-dom/server';
-import type * as SDKJSON from '@stainless/sdk-json';
-import type { DocsLanguage } from '../routing';
-
-import { DocsProvider, useLanguageComponents } from '../contexts';
-
-import style from '../style';
-import { ComponentProvider } from '../contexts/component';
-
-type ProvidersProps = {
-  language: DocsLanguage;
-  children: React.ReactNode;
-};
-
-function Providers({ language, children }: ProvidersProps) {
-  return (
-    <DocsProvider spec={null} language={language}>
-      <ComponentProvider
-        components={{
-          SDKReference({ stainlessPath, children }) {
-            if (!stainlessPath) return children;
-            return <span className={style.TypeReference}>{children}</span>;
-          },
-        }}
-      >
-        {children}
-      </ComponentProvider>
-    </DocsProvider>
-  );
-}
-
-function RenderType({ type, full }: { type: SDKJSON.Type; full?: boolean }) {
-  const { Type, TypeName } = useLanguageComponents();
-  return full ? <Type type={type} /> : <TypeName type={type} />;
-}
-
-export function typeName(language: DocsLanguage, type: SDKJSON.Type) {
-  const component = (
-    <Providers language={language}>
-      <RenderType type={type} />
-    </Providers>
-  );
-
-  return renderToStaticMarkup(component);
-}
-
-export function type(language: DocsLanguage, type: SDKJSON.Type) {
-  const component = (
-    <Providers language={language}>
-      <RenderType type={type} full={true} />
-    </Providers>
-  );
-
-  return renderToStaticMarkup(component);
-}
-
-function RenderDeclaration({ decl }: { decl: SDKJSON.DeclarationNode }) {
-  const { Declaration } = useLanguageComponents();
-  return <Declaration decl={decl} />;
-}
-
-export function declaration(language: DocsLanguage, decl: SDKJSON.DeclarationNode) {
-  const component = (
-    <Providers language={language}>
-      <RenderDeclaration decl={decl} />
-    </Providers>
-  );
-
-  return renderToStaticMarkup(component);
-}
-
-function RenderMethod({ method }: { method: SDKJSON.DeclarationNode }) {
-  const { MethodSignature } = useLanguageComponents();
-  return <MethodSignature decl={method} />;
-}
-
-export function methodSignature(language: DocsLanguage, decl: SDKJSON.DeclarationNode) {
-  const component = (
-    <Providers language={language}>
-      <RenderMethod method={decl} />
-    </Providers>
-  );
-
-  return renderToStaticMarkup(component);
-}

package/src/search/providers/algolia.ts

@@ -1,88 +0,0 @@
-import { searchClient } from '@algolia/client-search';
-import { generateChatIndex, generateIndex } from '../indexer';
-import { SearchableAttributes, SearchableAttributesChat } from '../types';
-import type * as SDKJSON from '@stainless/sdk-json';
-import type { ResultRecordType, SearchSettings, SearchParams, ResultType } from '../types';
-
-export async function buildIndex(
-  appId: string,
-  indexName: string,
-  writeKey: string,
-  spec: SDKJSON.Spec,
-  renderMarkdown: (_: string) => string | null,
-): Promise<void> {
-  if (!appId || !indexName || !writeKey) return;
-  const objects = Array.from(generateIndex(spec, renderMarkdown));
-  const client = searchClient(appId, writeKey);
-
-  await client.setSettings({
-    indexName,
-    indexSettings: {
-      highlightPreTag: '<mark>',
-      highlightPostTag: '</mark>',
-      customRanking: ['asc(priority)'],
-      attributesForFaceting: ['language', 'kind'],
-      searchableAttributes: [...SearchableAttributes],
-    },
-  });
-
-  await client.replaceAllObjects({ indexName, objects });
-}
-
-export async function buildChatIndex(
-  appId: string,
-  indexName: string,
-  writeKey: string,
-  spec: SDKJSON.Spec,
-): Promise<void> {
-  if (!appId || !indexName || !writeKey) return;
-  const objects = Array.from(generateChatIndex(spec));
-  const client = searchClient(appId, writeKey);
-
-  await client.setSettings({
-    indexName,
-    indexSettings: {
-      attributesForFaceting: ['language'],
-      attributeForDistinct: 'stainlessPath',
-      searchableAttributes: SearchableAttributesChat,
-    },
-  });
-
-  await client.replaceAllObjects({ indexName, objects });
-}
-
-export async function search({
-  settings: { appId, indexName, searchKey },
-  params: { query, language, kind },
-}: {
-  params: SearchParams;
-  settings: SearchSettings;
-}): Promise<ResultType | undefined> {
-  const client = searchClient(appId, searchKey);
-  const filters = language ? `language:${language}` : undefined;
-  const facetFilters = kind ? [`kind:${kind}`] : undefined;
-  const { results } = await client.search<ResultRecordType>({
-    requests: [
-      {
-        query,
-        indexName,
-        filters,
-        hitsPerPage: 5,
-        facets: ['kind'],
-      },
-      {
-        query,
-        indexName,
-        filters,
-        facetFilters,
-        facets: ['kind'],
-        hitsPerPage: 50,
-      },
-    ],
-  });
-
-  if ('hits' in results[0]! && 'hits' in results[1]!) {
-    const [{ nbHits, facets }, { hits }] = results;
-    return { hits, nbHits: nbHits ?? 0, facets };
-  }
-}

package/src/search/providers/fuse.ts

@@ -1,19 +0,0 @@
-import Fuse, { FuseIndex } from 'fuse.js';
-import { DocsLanguage } from '../../routing';
-import { generateIndex } from '../indexer';
-import { IndexEntry, SearchableAttributes } from '../types';
-import type * as SDKJSON from '@stainless/sdk-json';
-
-export type FuseIndexData = { content: IndexEntry[]; index: FuseIndex<IndexEntry> };
-
-export function buildIndex(spec: SDKJSON.Spec, language?: DocsLanguage): FuseIndexData {
-  const idx = Array.from(generateIndex(spec, undefined, false));
-  const content = language ? idx.filter((entry) => entry.language === language) : idx;
-  const index = Fuse.createIndex([...SearchableAttributes], content);
-  return { content, index };
-}
-
-export function search({ content, index }: FuseIndexData, query: string, limit: number = 100) {
-  const fuse = new Fuse(content, { keys: [...SearchableAttributes] }, index);
-  return fuse.search(query).slice(0, limit);
-}

package/src/search/providers/pagefind.ts

@@ -1,17 +0,0 @@
-import type { GuideResultType } from '../types';
-
-async function loadPagefind(path: string) {
-  const url = new URL(path, import.meta.url).href;
-  return await import(/* @vite-ignore */ url);
-}
-
-export async function guideSearch(
-  loadPath: string,
-  query: string,
-  limit?: number,
-): Promise<GuideResultType[]> {
-  const index = await loadPagefind(loadPath);
-  const response = await index.search(query);
-  const items = limit ? response.results.slice(0, limit) : response.results;
-  return Promise.all(items.map((result: any) => result.data().then((data: any) => ({ ...result, data }))));
-}

package/src/search/providers/walker.ts

@@ -1,32 +0,0 @@
-import { DocsLanguage } from '../../routing';
-import { generateIndex } from '../indexer';
-import { IndexEntry, SearchableAttributes } from '../types';
-import type * as SDKJSON from '@stainless/sdk-json';
-
-export function buildIndex(spec: SDKJSON.Spec) {
-  return generateIndex(spec, undefined, false);
-}
-
-function* findEntryInIndex(index: Generator<IndexEntry>, language: string, query: string) {
-  for (const entry of index) {
-    if (entry.language !== language) continue;
-    for (const attr of SearchableAttributes) {
-      const attr_ = attr in entry ? (attr as keyof typeof entry) : null;
-      if (attr_ && entry[attr_] && typeof entry[attr_] === 'string' && entry[attr_].includes(query))
-        yield entry;
-    }
-  }
-}
-
-export function search(
-  index: Generator<IndexEntry>,
-  language: DocsLanguage,
-  query: string,
-  limit: number = 100,
-) {
-  const results = findEntryInIndex(index, language, query);
-  const sorted = Array.from(results)
-    .sort((a, b) => a.priority - b.priority)
-    .slice(0, limit);
-  return sorted;
-}

package/src/search/results.tsx

@@ -1,183 +0,0 @@
-import { Folder, Box, Code, Wrench, BookOpenText, Search } from 'lucide-react';
-import { useLanguage } from '../contexts';
-import { useComponents } from '../contexts/use-components';
-import { GuideResultType, QueryKindsType, ResultRecordType, SearchAttributeNames } from './types';
-
-import style from '../style';
-
-export const QueryKindDisplay: Record<QueryKindsType, { name: string; icon: typeof Folder }> = {
-  all: { name: 'Results', icon: Search },
-  resource: { name: 'Resources', icon: Folder },
-  http_method: { name: 'Methods', icon: Box },
-  model: { name: 'Types', icon: Code },
-  property: { name: 'Properties', icon: Wrench },
-  guide: { name: 'Guide', icon: BookOpenText },
-};
-
-export type HighlightProps = {
-  result: ResultRecordType;
-  name: SearchAttributeNames;
-};
-
-export function Highlight({ result, name }: HighlightProps) {
-  const value = result._highlightResult[name]?.value;
-  if (value) return <span dangerouslySetInnerHTML={{ __html: value }} />;
-}
-
-export type SearchResultProps = {
-  result: ResultRecordType;
-};
-
-export function SearchResultBreadcrumb({ result }: SearchResultProps) {
-  const Docs = useComponents();
-  const Icon = QueryKindDisplay[result.kind].icon;
-  const items = result.crumbs?.map((crumb) => (
-    <span key={crumb} className={style.SearchBreadcrumbItem}>
-      {crumb}
-    </span>
-  ));
-
-  return (
-    <div className={style.SearchBreadcrumb}>
-      <Icon className={style.Icon} size={14} />
-      {Array.isArray(result.crumbs) && (
-        <Docs.Join items={items}>
-          <span className={style.SearchBreadcrumbDivider}>{'›'}</span>
-        </Docs.Join>
-      )}
-    </div>
-  );
-}
-
-export function SearchResult({ result }: SearchResultProps) {
-  return (
-    <div className={style.SearchResult} data-stldocs-search-result={result.kind}>
-      <SearchResultBreadcrumb result={result} />
-      <SearchResultContent result={result} />
-    </div>
-  );
-}
-
-export type GuideResultProps = {
-  result: GuideResultType;
-};
-
-export function GuideResult({ result }: GuideResultProps) {
-  const Docs = useComponents();
-  const Icon = QueryKindDisplay['guide'].icon;
-  const path = result.data.url
-    .slice(1, -1)
-    .split('/')
-    .map((crumb) => (
-      <span className={style.SearchBreadcrumbItem} key={crumb}>
-        {crumb}
-      </span>
-    ));
-
-  const crumbs =
-    path.length > 1
-      ? path
-      : [
-          <span className={style.SearchBreadcrumbItem} key="overview">
-            Overview
-          </span>,
-        ];
-
-  return (
-    <div className={style.SearchResult} data-stldocs-search-result="guide">
-      <div className={style.SearchBreadcrumb}>
-        <Icon className={style.Icon} size={14} />
-        <Docs.Join items={crumbs}>
-          <span className={style.SearchBreadcrumbDivider}>{'›'}</span>
-        </Docs.Join>
-      </div>
-      <h3 className={style.SearchResultGuideTitle}>{result.data.meta.title}</h3>
-      <div
-        className={style.SearchResultGuideExcerpt}
-        dangerouslySetInnerHTML={{ __html: result.data.excerpt }}
-      />
-    </div>
-  );
-}
-
-export function SearchResultContent({ result }: SearchResultProps) {
-  const Docs = useComponents();
-  const language = useLanguage();
-
-  switch (result.kind) {
-    case 'http_method':
-      return (
-        <>
-          <Docs.MethodHeader
-            level="h5"
-            title={<Highlight result={result} name={result.summary ? 'summary' : 'title'} />}
-            signature={result['qualified'] && <Highlight result={result} name={'qualified'} />}
-          >
-            <Docs.MethodRoute
-              httpMethod={result.httpMethod}
-              endpoint={<Highlight result={result} name="endpoint" />}
-            />
-          </Docs.MethodHeader>
-          <div className={`${style.MethodDescription} ${style.Content}`}>
-            <Highlight result={result} name="description" />
-          </div>
-        </>
-      );
-
-    case 'model': {
-      const properties =
-        result.children?.map((child, index) => (
-          <span key={index} className={style.TextIdentifier}>
-            {child}
-          </span>
-        )) ?? [];
-
-      return (
-        <div className={style.Property} data-stldocs-language={language}>
-          <div className={style.PropertyHeader}>
-            <span className={style.PropertyName}>
-              <Highlight result={result} name={result.title ? 'title' : 'name'} />
-            </span>
-          </div>
-          <span className={style.PropertyDeclaration}>
-            <Highlight result={result} name="ident" />:{' '}
-            <Docs.Join items={properties} limit={3}>
-              <span className={style.TextPunctuation}>, </span>
-            </Docs.Join>
-          </span>
-        </div>
-      );
-    }
-
-    case 'resource':
-      return (
-        <div className={style.SearchResultResourceInfo}>
-          <span className={style.SearchResultResourceTitle}>
-            <Highlight result={result} name="title" />
-          </span>
-          <span className={style.SearchResultResourcePath}>
-            <Highlight result={result} name="QualifiedName" />
-          </span>
-        </div>
-      );
-
-    case 'property':
-      return (
-        <div className={style.Property} data-stldocs-language={language}>
-          <div className={style.PropertyHeader}>
-            <span className={style.PropertyName}>
-              <Highlight result={result} name="name" />
-            </span>
-            <span className={style.PropertyTypeName}>
-              <span dangerouslySetInnerHTML={{ __html: result.type ?? '' }} />
-            </span>
-          </div>
-          {result.docstring && (
-            <span className={style.PropertyDescription}>
-              <Highlight result={result} name="docstring" />
-            </span>
-          )}
-        </div>
-      );
-  }
-}

package/src/search/state.ts

@@ -1,64 +0,0 @@
-import { useReducer } from 'react';
-import { QueryKindsType, ResultRecordType } from './types';
-
-export type SearchReducerState = {
-  results: ResultRecordType[];
-  resultsCount: number;
-  filterKind?: QueryKindsType;
-  filterKindCount?: Record<QueryKindsType, number>;
-  keyboardSelection?: number;
-  selectedIndex: number;
-  searchQuery: string;
-};
-
-export type SearchReducerAction =
-  | { action: 'DecrementSelection' }
-  | { action: 'IncrementSelection' }
-  | { action: 'SetSelectedIndex'; selectedIndex: number }
-  | { action: 'SetFilterKind'; filterKind: QueryKindsType }
-  | { action: 'UpdateQuery'; searchQuery: string }
-  | ({ action: 'UpdateResults' } & Pick<SearchReducerState, 'results' | 'resultsCount' | 'filterKindCount'>);
-
-export const SearchReducerDefaults: SearchReducerState = {
-  results: [],
-  resultsCount: 0,
-  selectedIndex: 0,
-  searchQuery: '',
-};
-
-export function searchReducer(state: SearchReducerState, op: SearchReducerAction): SearchReducerState {
-  switch (op.action) {
-    case 'IncrementSelection': {
-      const value = Math.min(state.resultsCount, state.selectedIndex + 1);
-      return { ...state, selectedIndex: value, keyboardSelection: value };
-    }
-
-    case 'DecrementSelection': {
-      const value = Math.max(0, state.selectedIndex - 1);
-      return { ...state, selectedIndex: value, keyboardSelection: value };
-    }
-
-    case 'SetSelectedIndex':
-      return { ...state, selectedIndex: op.selectedIndex };
-
-    case 'SetFilterKind':
-      return { ...state, filterKind: op.filterKind };
-
-    case 'UpdateQuery':
-      return { ...state, searchQuery: op.searchQuery };
-
-    case 'UpdateResults':
-      return {
-        ...state,
-        results: op.results,
-        resultsCount: op.resultsCount,
-        filterKindCount: op.filterKindCount,
-        keyboardSelection: undefined,
-        selectedIndex: 0,
-      };
-  }
-}
-
-export function useSearchReducer() {
-  return useReducer(searchReducer, SearchReducerDefaults);
-}