diff --git a/packages/gitbook/src/lib/openapi/fetch.ts b/packages/gitbook/src/lib/openapi/fetch.ts index 7ec7dc53c..246d03b8b 100644 --- a/packages/gitbook/src/lib/openapi/fetch.ts +++ b/packages/gitbook/src/lib/openapi/fetch.ts @@ -10,6 +10,7 @@ import { } from '@gitbook/openapi-parser'; import { enrichFilesystem } from './enrich'; +import { resolveOpenAPIDescriptionLinks } from './resolveDescriptionLinks'; import type { AnyOpenAPIOperationsBlock, OpenAPISchemasBlock, @@ -41,7 +42,9 @@ export async function fetchOpenAPIFilesystem( // If the reference is a new OpenAPI reference, we return it. if (ref.kind === 'openapi') { assert(resolved.openapi?.filesystem); - return resolved.openapi.filesystem; + return resolveOpenAPIDescriptionLinks(resolved.openapi.filesystem, (contentRef) => + resolveContentRef(contentRef, context) + ); } // For legacy blocks ("swagger"), we need to fetch the file system. return fetchFilesystem(resolved.href, context.space.id); diff --git a/packages/gitbook/src/lib/openapi/resolveDescriptionLinks.test.ts b/packages/gitbook/src/lib/openapi/resolveDescriptionLinks.test.ts new file mode 100644 index 000000000..36f0a22b4 --- /dev/null +++ b/packages/gitbook/src/lib/openapi/resolveDescriptionLinks.test.ts @@ -0,0 +1,44 @@ +import { describe, expect, it } from 'bun:test'; + +import { parseOpenAPI } from '@gitbook/openapi-parser'; + +import { resolveOpenAPIDescriptionLinks } from './resolveDescriptionLinks'; + +const APP_URL = 'https://app.gitbook.com/s/space-1/tables'; + +describe('resolveOpenAPIDescriptionLinks', () => { + it('points tagged links at their resolved URL without mutating the input', async () => { + const original = + `

Fields` + + ` Gone` + + ' Docs

'; + const { filesystem } = await parseOpenAPI({ + value: JSON.stringify({ + openapi: '3.0.0', + info: { title: 'Test', version: '1.0.0' }, + paths: {}, + components: { + schemas: { + Condition: { type: 'object', 'x-gitbook-description-html': original }, + }, + }, + }), + rootURL: null, + }); + + const resolved = await resolveOpenAPIDescriptionLinks(filesystem, async (ref) => + ref.kind === 'page' && ref.page === 'page-1' ? { href: '/docs/tables' } : null + ); + + expect(resolved[0]?.specification.components?.schemas?.Condition).toMatchObject({ + 'x-gitbook-description-html': + '

Fields' + + ` Gone` + + ' Docs

', + }); + // The spec content comes from the data cache, shared across sites. + expect(filesystem[0]?.specification.components?.schemas?.Condition).toMatchObject({ + 'x-gitbook-description-html': original, + }); + }); +}); diff --git a/packages/gitbook/src/lib/openapi/resolveDescriptionLinks.ts b/packages/gitbook/src/lib/openapi/resolveDescriptionLinks.ts new file mode 100644 index 000000000..9083ad8c9 --- /dev/null +++ b/packages/gitbook/src/lib/openapi/resolveDescriptionLinks.ts @@ -0,0 +1,165 @@ +import { type DefaultTreeAdapterMap, parseFragment } from 'parse5'; +import * as React from 'react'; + +import type { ContentRef } from '@gitbook/api'; +import type { Filesystem, OpenAPIV3xDocument } from '@gitbook/openapi-parser'; + +import { escapeHTML } from '@/lib/html'; +import { resolveStringContentRef } from '@/lib/references'; + +const DESCRIPTION_HTML_KEY = 'x-gitbook-description-html'; +// Set by spec processing on links to GitBook content, e.g. `/spaces/{space}/pages/{page}`. +const CONTENT_REF_ATTRIBUTE = 'data-gitbook-ref'; + +type OpenAPIFilesystem = Filesystem; +type HTMLElement = DefaultTreeAdapterMap['element']; +type HTMLNode = DefaultTreeAdapterMap['parentNode'] | DefaultTreeAdapterMap['childNode']; + +// Per request: resolved hrefs depend on the site being rendered. +const getResolvedFilesystems = React.cache( + () => new WeakMap>() +); + +/** + * Point description links that spec processing tagged with a content ref at their URL in the + * current site. Links whose ref doesn't resolve keep the href written in the spec. + * Returns a copy when something changed: the input may be shared through the data cache. + */ +export function resolveOpenAPIDescriptionLinks( + filesystem: OpenAPIFilesystem, + resolveContentRef: (ref: ContentRef) => Promise<{ href: string } | null> +): Promise { + const resolvedFilesystems = getResolvedFilesystems(); + let promise = resolvedFilesystems.get(filesystem); + if (!promise) { + promise = baseResolveOpenAPIDescriptionLinks(filesystem, resolveContentRef); + resolvedFilesystems.set(filesystem, promise); + } + return promise; +} + +async function baseResolveOpenAPIDescriptionLinks( + filesystem: OpenAPIFilesystem, + resolveContentRef: (ref: ContentRef) => Promise<{ href: string } | null> +): Promise { + const taggedHTML = new Set(); + mapDescriptionHTML(filesystem, (html) => { + if (html.includes(CONTENT_REF_ATTRIBUTE)) { + taggedHTML.add(html); + } + return html; + }); + + if (taggedHTML.size === 0) { + return filesystem; + } + + const hrefs = new Map>(); + const resolveHref = (source: string) => { + let href = hrefs.get(source); + if (!href) { + const ref = resolveStringContentRef(source); + href = ref + ? resolveContentRef(ref).then((resolved) => resolved?.href ?? null) + : Promise.resolve(null); + hrefs.set(source, href); + } + return href; + }; + + const rewritten = new Map(); + await Promise.all( + Array.from(taggedHTML, async (html) => { + rewritten.set(html, await rewriteLinks(html, resolveHref)); + }) + ); + + return mapDescriptionHTML(filesystem, (html) => rewritten.get(html) ?? html); +} + +/** + * Replace the href of each tagged link with its resolved URL. + */ +async function rewriteLinks( + html: string, + resolveHref: (source: string) => Promise +): Promise { + const fragment = parseFragment(html, { sourceCodeLocationInfo: true }); + const replacements: { start: number; end: number; value: string }[] = []; + + await Promise.all( + collectLinks(fragment).map(async (link) => { + const source = link.attrs.find((attr) => attr.name === CONTENT_REF_ATTRIBUTE)?.value; + const location = link.sourceCodeLocation?.attrs?.href; + if (!source || !location) { + return; + } + + const href = await resolveHref(source); + if (href) { + replacements.push({ + start: location.startOffset, + end: location.endOffset, + value: `href="${escapeHTML(href)}"`, + }); + } + }) + ); + + // Apply from the end so earlier offsets stay valid. + replacements.sort((a, b) => b.start - a.start); + let result = html; + for (const { start, end, value } of replacements) { + result = result.slice(0, start) + value + result.slice(end); + } + return result; +} + +function collectLinks(node: HTMLNode, links: HTMLElement[] = []): HTMLElement[] { + if ('tagName' in node && node.tagName === 'a') { + links.push(node); + } + if ('childNodes' in node) { + for (const child of node.childNodes) { + collectLinks(child, links); + } + } + return links; +} + +/** + * Map every description HTML in a JSON value, copying only the objects on a changed path. + */ +function mapDescriptionHTML(value: T, transform: (html: string) => string): T { + if (typeof value !== 'object' || value === null) { + return value; + } + + if (Array.isArray(value)) { + let result: unknown[] | null = null; + value.forEach((item, index) => { + const next = mapDescriptionHTML(item, transform); + if (next !== item) { + result ??= [...value]; + result[index] = next; + } + }); + return (result ?? value) as T; + } + + const record = value as Record; + let result: Record | null = null; + // `for...in` over plain JSON objects: several times faster than `Object.entries` on large specs. + for (const key in record) { + const child = record[key]; + const next = + key === DESCRIPTION_HTML_KEY && typeof child === 'string' + ? transform(child) + : mapDescriptionHTML(child, transform); + if (next !== child) { + result ??= { ...record }; + result[key] = next; + } + } + return (result ?? record) as T; +}