@mintlify/scraping 4.0.1161 → 4.0.1163

package/bin/sdk/converters/go.js

@@ -0,0 +1,828 @@
+import fse from 'fs-extra';
+import path from 'node:path';
+import { visit } from 'unist-util-visit';
+import { z } from 'zod';
+import { isHtmlParagraph, isProseParagraph, parseMarkdown, plainText, rewriteMdastLinks, stringifyMdast, } from '../convert.js';
+import { encodeHref, indent, inlineCode, linkedCode, responseField, safeHref, truncate, } from '../mdx.js';
+const SUPPORTED_SCHEMA_VERSION = 1;
+const PACKAGE_PAGE = 'package-overview';
+const MEMBER_HEADING_DEPTH = 3;
+const MIN_COMMENT_HEADING_DEPTH = 4;
+const MAX_TYPE_ATTR = 80;
+const MIN_README_HEADING_DEPTH = 2;
+const GITHUB_MODULE = /^github\.com\/([^/]+)\/([^/]+)((?:\/[^/]+)*?)(?:\/v(?:[2-9]|[1-9]\d+))?$/;
+const MAX_TEXT = 1 << 20;
+const MAX_CODE = 1 << 18;
+const identifierSchema = z
+    .string()
+    .max(512)
+    .regex(/^[\p{L}_][\p{L}\p{N}_]*$/u, 'expected a Go identifier');
+const importPathSchema = z
+    .string()
+    .max(512)
+    .regex(/^[\p{L}\p{N}._~-]+(?:\/[\p{L}\p{N}._~-]+)*$/u, 'expected a Go import path');
+const DIR_SEGMENT = /^[\p{L}\p{N}._~-]+$/u;
+const dirSchema = z
+    .string()
+    .max(512)
+    .refine((dir) => dir === '.' ||
+    dir.split('/').every((segment) => DIR_SEGMENT.test(segment) && !/^\.+$/.test(segment)), 'expected "." or a relative directory of import-path segments, none made only of dots');
+const textSchema = z.string().max(MAX_TEXT);
+const codeTextSchema = z.string().max(MAX_CODE);
+const refSchema = z.object({
+    pkg: importPathSchema.optional(),
+    name: identifierSchema,
+    private: z.boolean().optional(),
+});
+const codeSchema = z.array(z.object({ t: codeTextSchema, ref: refSchema.optional() }));
+const exampleSchema = z.object({
+    suffix: identifierSchema.optional(),
+    doc: textSchema.optional(),
+    code: codeTextSchema,
+    output: codeTextSchema.optional(),
+});
+const typeParamSchema = z.object({ name: identifierSchema, constraint: codeSchema });
+const paramSchema = z.object({ name: identifierSchema.optional(), type: codeSchema });
+const funcSchema = z.object({
+    name: identifierSchema,
+    recv: codeTextSchema.optional(),
+    decl: codeSchema,
+    doc: textSchema.optional(),
+    deprecated: textSchema.optional(),
+    typeParams: z.array(typeParamSchema).optional(),
+    params: z.array(paramSchema).optional(),
+    results: z.array(paramSchema).optional(),
+    examples: z.array(exampleSchema).optional(),
+});
+const valueSchema = z.object({
+    names: z.array(identifierSchema),
+    decl: codeSchema,
+    doc: textSchema.optional(),
+    deprecated: textSchema.optional(),
+});
+const fieldSchema = z.object({
+    name: identifierSchema,
+    type: codeSchema,
+    doc: textSchema.optional(),
+    deprecated: textSchema.optional(),
+    embedded: z.boolean().optional(),
+    tag: codeTextSchema.optional(),
+});
+const typeSchema = z.object({
+    name: identifierSchema,
+    kind: z.enum(['struct', 'interface', 'defined', 'alias']),
+    decl: codeSchema,
+    doc: textSchema.optional(),
+    deprecated: textSchema.optional(),
+    typeParams: z.array(typeParamSchema).optional(),
+    fields: z.array(fieldSchema).optional(),
+    methods: z.array(funcSchema).optional(),
+    funcs: z.array(funcSchema).optional(),
+    consts: z.array(valueSchema).optional(),
+    vars: z.array(valueSchema).optional(),
+    examples: z.array(exampleSchema).optional(),
+});
+const packageSchema = z.object({
+    importPath: importPathSchema,
+    name: identifierSchema,
+    dir: dirSchema,
+    synopsis: textSchema.optional(),
+    doc: textSchema.optional(),
+    readme: textSchema.optional(),
+    deprecated: textSchema.optional(),
+    consts: z.array(valueSchema).optional(),
+    vars: z.array(valueSchema).optional(),
+    funcs: z.array(funcSchema).optional(),
+    types: z.array(typeSchema).optional(),
+    examples: z.array(exampleSchema).optional(),
+});
+const goArtifactSchema = z.object({
+    schemaVersion: z.literal(SUPPORTED_SCHEMA_VERSION),
+    generator: z.object({
+        name: z.string().max(512),
+        version: z.string().max(512),
+        go: z.string().max(512),
+    }),
+    module: importPathSchema,
+    goos: z.string(),
+    goarch: z.string(),
+    commentSyntax: z.enum(['markdown', 'godoc']),
+    packages: z.array(packageSchema).superRefine((packages, ctx) => {
+        const importPaths = new Set();
+        const dirs = new Set();
+        const namespaces = new Map();
+        const root = packages.find((pkg) => pkg.dir === '.');
+        packages.forEach((pkg, index) => {
+            if (importPaths.has(pkg.importPath)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [index, 'importPath'],
+                    message: `duplicate package ${pkg.importPath}`,
+                });
+            }
+            importPaths.add(pkg.importPath);
+            if (dirs.has(pkg.dir)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [index, 'dir'],
+                    message: `duplicate package directory ${pkg.dir}`,
+                });
+            }
+            dirs.add(pkg.dir);
+            const namespace = packageNamespace(pkg, root);
+            const other = namespaces.get(namespace);
+            if (other !== undefined) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [index, 'dir'],
+                    message: `packages ${other} and ${pkg.dir} would both be addressed as ${namespace}`,
+                });
+            }
+            namespaces.set(namespace, pkg.dir);
+        });
+    }),
+});
+const TYPE_TAGS = {
+    struct: 'STRUCT',
+    interface: 'INTERFACE',
+    defined: 'TYPE',
+    alias: 'TYPE',
+};
+export async function convertGo(sourcePath) {
+    const artifact = parseArtifact(await fse.readJson(sourcePath), sourcePath);
+    const index = new GoIndex(artifact);
+    const renderers = artifact.packages.map((pkg) => new GoRenderer(index, pkg));
+    const pages = [];
+    const groups = [];
+    for (const renderer of renderers) {
+        const packagePages = renderer.packagePages();
+        pages.push(...packagePages, ...renderer.memberPages());
+        groups.push({ group: renderer.group, pages: packagePages.map((page) => page.slug) });
+    }
+    return { pages, groups };
+}
+function parseArtifact(raw, sourcePath) {
+    const version = typeof raw === 'object' && raw !== null && 'schemaVersion' in raw
+        ? raw.schemaVersion
+        : undefined;
+    if (typeof version === 'number' && version !== SUPPORTED_SCHEMA_VERSION) {
+        throw new Error(`Go SDK artifact ${sourcePath} uses schema version ${version}, but Mintlify reads schema version ${SUPPORTED_SCHEMA_VERSION}. Regenerate it with a compatible mintlify-go-extractor release.`);
+    }
+    const result = goArtifactSchema.safeParse(raw);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const detail = issue ? `${issue.path.join('.') || 'artifact'}: ${issue.message}` : 'invalid';
+        throw new Error(`Invalid Go SDK artifact ${sourcePath}: ${detail}`);
+    }
+    return result.data;
+}
+function slugify(name) {
+    return name.replace(/[^\p{L}\p{N}\-_.]+/gu, '-').replace(/^-+|-+$/g, '') || 'item';
+}
+function packageBase(pkg) {
+    return pkg.dir === '.' ? '' : pkg.dir.split('/').map(slugify).join('/');
+}
+// Packages are addressed as a tree headed by the root package's name and
+// continued by directory path, dotted: the root of openai-go is `package
+// openai` and its symbols `type openai.Client`; audio/client is `package
+// openai.audio.client` (or any trailing part, `package client`) and its
+// symbols `type openai.audio.client.Foo`. api/v1 (package api) is `package
+// api.v1`, not `package api`. The root prefix keeps a root package and a
+// top-level directory of the same name apart; a module without a root package
+// has nothing to keep apart and uses the directory path alone.
+function packageNamespace(pkg, root) {
+    if (pkg.dir === '.')
+        return pkg.name;
+    const dotted = pkg.dir.replaceAll('/', '.');
+    return root ? `${root.name}.${dotted}` : dotted;
+}
+function packageTargetName(pkg) {
+    return pkg.dir === '.' ? pkg.name : path.posix.basename(pkg.dir);
+}
+function packageParent(pkg, root) {
+    if (pkg.dir === '.')
+        return undefined;
+    const parent = path.posix.dirname(pkg.dir);
+    const dotted = parent === '.' ? undefined : parent.replaceAll('/', '.');
+    if (!root)
+        return dotted;
+    return dotted ? `${root.name}.${dotted}` : root.name;
+}
+function memberHeading(name) {
+    return `${name}()`;
+}
+// Method headings carry an explicit id, pkg.go.dev style, so links to them
+// do not depend on how many same-named headings precede them on the page.
+function methodAnchor(type, method) {
+    return `${type.name}.${method.name}`;
+}
+function packageFuncs(pkg) {
+    return [...(pkg.funcs ?? []), ...(pkg.types ?? []).flatMap((type) => type.funcs ?? [])].sort((left, right) => left.name.localeCompare(right.name));
+}
+class GoIndex {
+    constructor(artifact) {
+        this.packages = new Map();
+        this.symbols = new Map();
+        this.routes = new Map();
+        this.module = artifact.module;
+        this.root = artifact.packages.find((pkg) => pkg.dir === '.');
+        for (const pkg of artifact.packages) {
+            const base = packageBase(pkg);
+            const overview = { slug: this.route(base, PACKAGE_PAGE) };
+            this.packages.set(pkg.importPath, overview.slug);
+            for (const value of [...(pkg.consts ?? []), ...(pkg.vars ?? [])]) {
+                for (const name of value.names)
+                    this.add(pkg, name, overview);
+            }
+            for (const fn of packageFuncs(pkg)) {
+                this.add(pkg, fn.name, { slug: this.route(base, fn.name) });
+            }
+            for (const type of pkg.types ?? []) {
+                const slug = this.route(base, type.name);
+                this.add(pkg, type.name, { slug });
+                for (const value of [...(type.consts ?? []), ...(type.vars ?? [])]) {
+                    for (const name of value.names)
+                        this.add(pkg, name, { slug });
+                }
+            }
+        }
+        for (const pkg of artifact.packages) {
+            for (const type of pkg.types ?? []) {
+                const slug = this.slugOf(pkg, type.name);
+                for (const method of type.methods ?? []) {
+                    this.add(pkg, `${type.name}.${method.name}`, {
+                        slug,
+                        anchor: methodAnchor(type, method),
+                        page: this.route(slug, method.name),
+                    });
+                }
+                for (const field of type.fields ?? []) {
+                    this.add(pkg, `${type.name}.${field.name}`, {
+                        slug,
+                        anchor: field.name,
+                        page: this.route(slug, field.name),
+                    });
+                }
+            }
+        }
+    }
+    add(pkg, name, location) {
+        this.symbols.set(`${pkg.importPath}#${name}`, location);
+    }
+    slugOf(pkg, name) {
+        return this.symbols.get(`${pkg.importPath}#${name}`)?.slug ?? packageBase(pkg);
+    }
+    route(base, name) {
+        const slug = path.posix.join(base, slugify(name));
+        // Same key prebuild uses for route collisions (getGeneratedRouteKey).
+        const key = slug.normalize('NFC').toLowerCase();
+        const taken = this.routes.get(key);
+        if (taken === undefined) {
+            this.routes.set(key, 1);
+            return slug;
+        }
+        // A Go identifier cannot contain "-", so `${key}-${attempt}` is only ever a
+        // route this function reserved itself and the next number is free.
+        const attempt = taken + 1;
+        this.routes.set(key, attempt);
+        this.routes.set(`${key}-${attempt}`, 1);
+        return `${slug}-${attempt}`;
+    }
+    packageSlug(importPath) {
+        return this.packages.get(importPath);
+    }
+    symbolSlug(importPath, name) {
+        return this.symbols.get(`${importPath}#${name}`)?.slug;
+    }
+    memberPageSlug(importPath, name) {
+        return this.symbols.get(`${importPath}#${name}`)?.page;
+    }
+    href(importPath, name, isPrivate) {
+        if (name) {
+            const dot = name.indexOf('.');
+            const location = this.symbols.get(`${importPath}#${name}`) ??
+                (dot > 0 ? this.symbols.get(`${importPath}#${name.slice(0, dot)}`) : undefined);
+            if (location)
+                return `/${location.slug}${location.anchor ? `#${location.anchor}` : ''}`;
+        }
+        const packageSlug = this.packages.get(importPath);
+        if (packageSlug)
+            return `/${packageSlug}`;
+        if (isPrivate)
+            return undefined;
+        return `https://pkg.go.dev/${encodeHref(importPath)}${name ? `#${encodeHref(name)}` : ''}`;
+    }
+}
+class GoRenderer {
+    constructor(index, pkg) {
+        this.index = index;
+        this.pkg = pkg;
+        this.rendered = new Map();
+        this.group = pkg.dir === '.' ? pkg.name : pkg.dir;
+        this.base = packageBase(pkg);
+        this.funcs = packageFuncs(pkg);
+    }
+    packagePages() {
+        return [
+            this.packagePage(),
+            ...(this.pkg.types ?? []).map((type) => this.typePage(type)),
+            ...this.funcs.map((fn) => this.funcPage(fn)),
+        ];
+    }
+    memberPages() {
+        return (this.pkg.types ?? []).flatMap((type) => this.typeMemberPages(type));
+    }
+    packagePage() {
+        const slug = this.index.packageSlug(this.pkg.importPath) ?? path.posix.join(this.base, PACKAGE_PAGE);
+        const lines = [this.prose(this.pkg.doc), this.deprecated(this.pkg.deprecated)];
+        const types = this.pkg.types ?? [];
+        if (types.length)
+            lines.push('## Types', this.indexList(types.map((type) => type.name)));
+        if (this.funcs.length) {
+            lines.push('## Functions', this.indexList(this.funcs.map((fn) => fn.name)));
+        }
+        lines.push(...this.valueSection('Constants', this.pkg.consts, 2));
+        lines.push(...this.valueSection('Variables', this.pkg.vars, 2));
+        lines.push(...this.exampleSection(this.pkg.examples, 2));
+        const parent = packageParent(this.pkg, this.index.root);
+        // The synopsis is the package doc's first sentence, so it is read from the
+        // doc's parse, which rendering the page needs anyway.
+        const synopsis = this.description(this.pkg.doc);
+        const readme = this.pkg.readme ? this.readme(this.pkg.readme, synopsis) : undefined;
+        const description = synopsis ?? readme?.description;
+        return {
+            slug,
+            title: `package ${this.pkg.name}`,
+            ...(description ? { description } : {}),
+            tag: 'PACKAGE',
+            ...(readme?.intro ? { intro: readme.intro } : {}),
+            content: join(lines),
+            target: {
+                kind: 'package',
+                name: packageTargetName(this.pkg),
+                ...(parent ? { namespace: parent } : {}),
+            },
+        };
+    }
+    // Renders a README the way pkg.go.dev shows it, minus the sentence the page
+    // shows as its description (see takeLeadingSentence).
+    readme(markdown, synopsis) {
+        if (unparseable(markdown))
+            return { intro: codeBlock(markdown, 'text') };
+        const tree = parseMarkdown(markdown);
+        const first = tree.children[0];
+        if (first?.type === 'heading' && first.depth === 1)
+            tree.children.shift();
+        visit(tree, 'heading', (node) => {
+            node.depth = Math.max(node.depth, MIN_README_HEADING_DEPTH);
+        });
+        const imageDefinitions = new Set();
+        const linkDefinitions = new Set();
+        visit(tree, 'imageReference', (node) => {
+            imageDefinitions.add(node.identifier);
+        });
+        visit(tree, 'linkReference', (node) => {
+            linkDefinitions.add(node.identifier);
+        });
+        rewriteMdastLinks(tree, (node) => this.repoUrl(node.url, node.type === 'image' ||
+            (node.type === 'definition' &&
+                imageDefinitions.has(node.identifier) &&
+                !linkDefinitions.has(node.identifier))));
+        const description = takeLeadingSentence(tree, synopsis);
+        return { intro: stringifyMdast(tree), ...(description ? { description } : {}) };
+    }
+    // The first sentence of a doc's opening paragraph, read from the parsed tree
+    // rather than from the Markdown source, so link syntax and escapes are
+    // already gone and the cost is linear in the doc's length.
+    describe(markdown) {
+        const description = this.description(markdown);
+        return description ? { description } : {};
+    }
+    description(markdown) {
+        if (!markdown)
+            return undefined;
+        const paragraph = this.doc(markdown).tree.children.find((node) => node.type === 'paragraph');
+        if (!paragraph)
+            return undefined;
+        return firstSentence(plainText(paragraph).replace(/\s+/g, ' ').trim());
+    }
+    // Relative README links resolve against the package directory in the
+    // repository; a leading slash means the repository root, as on GitHub.
+    repoUrl(url, raw) {
+        const href = safeHref(url);
+        if (href === undefined || !/^[^#]/.test(href) || /^[a-z][a-z0-9+.-]*:/i.test(href)) {
+            return href;
+        }
+        const match = GITHUB_MODULE.exec(this.index.module);
+        if (!match)
+            return href;
+        const [, owner, repo, moduleDir = ''] = match;
+        const [file = '', hash] = href.split('#');
+        const resolved = file.startsWith('/')
+            ? path.posix.normalize(file.slice(1))
+            : path.posix.normalize(path.posix.join(moduleDir.slice(1), this.pkg.dir === '.' ? '' : this.pkg.dir, file));
+        if (resolved.startsWith('..'))
+            return href;
+        const view = raw ? 'raw' : 'blob';
+        return `https://github.com/${owner}/${repo}/${view}/HEAD/${resolved}${hash ? `#${hash}` : ''}`;
+    }
+    typePage(type) {
+        const lines = [
+            this.prose(type.doc),
+            this.deprecated(type.deprecated),
+            codeBlock(declarationHeader(type)),
+        ];
+        if (type.typeParams?.length) {
+            lines.push('## Type Parameters', ...type.typeParams.map((param) => this.field(param.name, param.constraint)));
+        }
+        if (type.fields?.length) {
+            lines.push('## Fields', ...type.fields.map((field) => this.fieldEntry(field)));
+        }
+        lines.push(...this.memberSection('Constructors', type.funcs));
+        lines.push(...this.memberSection('Methods', type.methods, type));
+        lines.push(...this.valueSection('Constants', type.consts, 2));
+        lines.push(...this.valueSection('Variables', type.vars, 2));
+        lines.push(...this.exampleSection(type.examples, 2));
+        return {
+            slug: this.slug(type.name),
+            title: type.name,
+            ...this.describe(type.doc),
+            tag: TYPE_TAGS[type.kind],
+            content: join(lines),
+            target: this.target(type.kind === 'interface' ? 'interface' : 'type', type.name),
+        };
+    }
+    funcPage(fn) {
+        const lines = [
+            this.prose(fn.doc),
+            this.deprecated(fn.deprecated),
+            codeBlock(codeText(fn.decl)),
+            ...this.signatureDetails(fn, 2),
+        ];
+        return {
+            slug: this.slug(fn.name),
+            title: fn.name,
+            ...this.describe(fn.doc),
+            tag: 'FUNCTION',
+            content: join(lines),
+            target: this.target('function', fn.name),
+        };
+    }
+    typeMemberPages(type) {
+        const methods = (type.methods ?? []).map((method) => ({
+            slug: this.memberSlug(type, method.name),
+            title: `${type.name}.${method.name}`,
+            ...this.describe(method.doc),
+            tag: 'METHOD',
+            content: join(this.funcBody(method, 2)),
+            target: this.target('method', method.name, type.name),
+        }));
+        const fields = (type.fields ?? []).map((field) => ({
+            slug: this.memberSlug(type, field.name),
+            title: `${type.name}.${field.name}`,
+            ...this.describe(field.doc),
+            tag: 'FIELD',
+            content: this.fieldEntry(field),
+            target: this.target('property', field.name, type.name),
+        }));
+        return [...methods, ...fields];
+    }
+    target(kind, name, parent) {
+        return {
+            kind,
+            name,
+            ...(parent ? { parent } : {}),
+            namespace: packageNamespace(this.pkg, this.index.root),
+        };
+    }
+    slug(name) {
+        return (this.index.symbolSlug(this.pkg.importPath, name) ?? path.posix.join(this.base, slugify(name)));
+    }
+    memberSlug(type, name) {
+        return (this.index.memberPageSlug(this.pkg.importPath, `${type.name}.${name}`) ??
+            path.posix.join(this.slug(type.name), slugify(name)));
+    }
+    indexList(names) {
+        return names.map((name) => `- [${name}](/${this.slug(name)})`).join('\n');
+    }
+    memberSection(heading, fns, owner) {
+        if (!fns?.length)
+            return [];
+        const marker = '#'.repeat(MEMBER_HEADING_DEPTH);
+        return [
+            `## ${heading}`,
+            ...fns.flatMap((fn) => [
+                `${marker} ${memberHeading(fn.name)}${owner ? ` {#${methodAnchor(owner, fn)}}` : ''}`,
+                ...this.funcBody(fn, 4),
+            ]),
+        ];
+    }
+    funcBody(fn, depth) {
+        return [
+            codeBlock(codeText(fn.decl)),
+            this.prose(fn.doc),
+            this.deprecated(fn.deprecated),
+            ...this.signatureDetails(fn, depth),
+        ];
+    }
+    signatureDetails(fn, depth) {
+        const heading = '#'.repeat(depth);
+        const lines = [];
+        if (fn.typeParams?.length) {
+            lines.push(`${heading} Type Parameters`, ...fn.typeParams.map((param) => this.field(param.name, param.constraint)));
+        }
+        const params = fn.params ?? [];
+        if (params.length) {
+            lines.push(`${heading} Parameters`, ...(params.every((param) => Boolean(param.name))
+                ? params.map((param) => this.field(param.name, param.type))
+                : [this.returns(params)]));
+        }
+        if (fn.results?.length)
+            lines.push(`${heading} Returns`, this.returns(fn.results));
+        lines.push(...this.exampleSection(fn.examples, depth));
+        return lines;
+    }
+    returns(results) {
+        const tokens = [];
+        results.forEach((result, position) => {
+            if (position > 0)
+                tokens.push({ text: ', ' });
+            tokens.push(...this.tokens(result.type));
+        });
+        if (results.length > 1) {
+            tokens.unshift({ text: '(' });
+            tokens.push({ text: ')' });
+        }
+        return linkedCode(tokens) ?? inlineCode(tokens.map((token) => token.text).join(''));
+    }
+    fieldEntry(field) {
+        const body = join([
+            field.embedded ? 'Embedded field.' : undefined,
+            field.tag ? `**Tag:** ${inlineCode(field.tag)}` : undefined,
+            this.prose(field.doc),
+            this.deprecated(field.deprecated),
+        ]);
+        return this.field(field.name, field.type, body, field.name);
+    }
+    // The type attribute is cut at 80 characters, so a longer type is also
+    // written out in full in the body: linked when it has refs, plain otherwise.
+    field(name, code, body, id) {
+        const typeHref = this.singleRefHref(code);
+        const text = codeText(code);
+        const full = typeHref
+            ? undefined
+            : (linkedCode(this.tokens(code)) ??
+                (text.length > MAX_TYPE_ATTR ? inlineCode(text) : undefined));
+        const content = join([full && `**Type:** ${full}`, body]);
+        return responseField(name, text, true, content, typeHref, id);
+    }
+    singleRefHref(code) {
+        const position = code.findIndex((token) => token.ref);
+        if (position === -1 || position !== code.length - 1)
+            return undefined;
+        const prefix = codeText(code.slice(0, position));
+        if (!/^(?:\*|\[\]|\.\.\.)*(?:[\p{L}_][\p{L}\p{N}_]*\.)?$/u.test(prefix))
+            return undefined;
+        const ref = code[position]?.ref;
+        const href = ref ? this.refHref(ref) : undefined;
+        return href?.startsWith('/') ? href : undefined;
+    }
+    tokens(code) {
+        return code.map((token) => {
+            const href = token.ref ? this.refHref(token.ref) : undefined;
+            return href ? { text: token.t, href } : { text: token.t };
+        });
+    }
+    refHref(ref) {
+        return this.index.href(ref.pkg ?? this.pkg.importPath, ref.name, ref.private ?? false);
+    }
+    valueSection(heading, values, depth) {
+        if (!values?.length)
+            return [];
+        return [
+            `${'#'.repeat(depth)} ${heading}`,
+            ...values.flatMap((value) => [
+                codeBlock(codeText(value.decl)),
+                this.prose(value.doc),
+                this.deprecated(value.deprecated),
+            ]),
+        ];
+    }
+    exampleSection(examples, depth) {
+        if (!examples?.length)
+            return [];
+        const heading = '#'.repeat(depth);
+        return [
+            `${heading} Examples`,
+            ...examples.flatMap((example) => [
+                `${heading}# ${example.suffix ? `Example (${example.suffix})` : 'Example'}`,
+                this.prose(example.doc),
+                codeBlock(example.code),
+                example.output ? `Output:\n\n${codeBlock(example.output.replace(/\n+$/, ''), 'text')}` : '',
+            ]),
+        ];
+    }
+    deprecated(text) {
+        if (!text)
+            return '';
+        return `<Warning>\n${indent(`Deprecated: ${this.prose(text)}`)}\n</Warning>`;
+    }
+    prose(markdown) {
+        return markdown ? stringifyMdast(this.doc(markdown).tree) : '';
+    }
+    doc(markdown) {
+        let doc = this.rendered.get(markdown);
+        if (!doc) {
+            doc = this.parseDoc(markdown);
+            this.rendered.set(markdown, doc);
+        }
+        return doc;
+    }
+    parseDoc(markdown) {
+        if (unparseable(markdown)) {
+            return {
+                tree: { type: 'root', children: [{ type: 'code', lang: 'text', value: markdown }] },
+            };
+        }
+        const tree = parseMarkdown(markdown, MIN_COMMENT_HEADING_DEPTH);
+        rewriteMdastLinks(tree, (node) => {
+            if (!node.url.startsWith('go:'))
+                return safeHref(node.url);
+            return this.resolveDocLink(node.url.slice('go:'.length));
+        });
+        return { tree };
+    }
+    resolveDocLink(target) {
+        const hash = target.indexOf('#');
+        const importPath = hash === -1 ? target : target.slice(0, hash);
+        const name = hash === -1 ? undefined : target.slice(hash + 1);
+        return this.index.href(importPath, name, false);
+    }
+}
+function codeText(code) {
+    return code.map((token) => token.t).join('');
+}
+function declarationHeader(type) {
+    const text = codeText(type.decl);
+    if (type.kind !== 'struct' && type.kind !== 'interface')
+        return text;
+    const open = bodyStart(text, type.kind);
+    if (open === -1)
+        return text;
+    if (type.kind === 'interface') {
+        const body = text.slice(open + type.kind.length + 3, text.lastIndexOf('}'));
+        const entries = body
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line && !line.startsWith('//'));
+        const shown = (type.methods?.length ?? 0) + (type.fields?.length ?? 0);
+        if (entries.length > shown)
+            return text;
+    }
+    return text.slice(0, open + type.kind.length + 1);
+}
+// The declaration's own body opens outside any type-parameter brackets; a
+// constraint written as `interface{ ... }` inside `[...]` comes first in the
+// text but is not it.
+function bodyStart(text, kind) {
+    const marker = ` ${kind} {`;
+    let depth = 0;
+    for (let i = 0; i < text.length; i += 1) {
+        const char = text[i];
+        if (char === '[')
+            depth += 1;
+        else if (char === ']')
+            depth -= 1;
+        else if (depth === 0 && text.startsWith(marker, i))
+            return i;
+    }
+    return -1;
+}
+function codeBlock(code, lang = 'go') {
+    const longestRun = Math.max(0, ...(code.match(/`+/g) ?? []).map((run) => run.length));
+    const fence = '`'.repeat(Math.max(3, longestRun + 1));
+    return `${fence}${lang}\n${code}\n${fence}`;
+}
+function join(chunks) {
+    return chunks.filter(Boolean).join('\n\n');
+}
+// The README's first prose paragraph (badges, images, and HTML blocks such as a
+// centred <h1> are skipped) supplies the description when the page has none,
+// provided it is a single sentence, and is then removed from the intro since
+// the page already shows it. When the package doc supplied the description and
+// the README opens with the same sentence, that sentence is removed instead.
+function takeLeadingSentence(tree, synopsis) {
+    const index = tree.children.findIndex((node) => node.type === 'paragraph' && !isHtmlParagraph(node) && isProseParagraph(node));
+    const paragraph = tree.children[index];
+    if (!paragraph)
+        return synopsis;
+    const text = plainText(paragraph).replace(/\s+/g, ' ').trim();
+    const sentence = leadingSentence(text);
+    if (!sentence || (synopsis !== undefined && truncate(sentence, MAX_DESCRIPTION) !== synopsis)) {
+        return synopsis;
+    }
+    if (sentence === text) {
+        tree.children.splice(index, 1);
+        return synopsis ?? truncate(sentence, MAX_DESCRIPTION);
+    }
+    if (synopsis !== undefined)
+        dropLeadingSentence(paragraph);
+    return synopsis;
+}
+// Removes a paragraph's first sentence, whatever inline markup it contains,
+// by dropping the children that lie wholly inside it and trimming the text
+// node it ends in. When the sentence ends inside a link or emphasis, nothing
+// is removed rather than splitting that node.
+function dropLeadingSentence(paragraph) {
+    const pieces = paragraph.children.map(plainText);
+    const end = /\.(?:\s|$)/.exec(pieces.join(''));
+    if (!end)
+        return;
+    const stop = end.index + 1;
+    let offset = 0;
+    for (let i = 0; i < paragraph.children.length; i += 1) {
+        const child = paragraph.children[i];
+        const length = pieces[i]?.length ?? 0;
+        if (offset + length <= stop) {
+            offset += length;
+            continue;
+        }
+        if (offset === stop) {
+            // The sentence ended with the previous node; drop it and any hard
+            // break that separated it from the rest.
+            paragraph.children.splice(0, i);
+            while (paragraph.children[0]?.type === 'break')
+                paragraph.children.shift();
+            const next = paragraph.children[0];
+            if (next?.type === 'text') {
+                next.value = next.value.trimStart();
+                if (next.value === '')
+                    paragraph.children.shift();
+            }
+            return;
+        }
+        if (child?.type !== 'text')
+            return;
+        child.value = child.value.slice(stop - offset).trimStart();
+        paragraph.children.splice(0, i);
+        if (child.value === '')
+            paragraph.children.shift();
+        return;
+    }
+    paragraph.children = [];
+}
+// Text past either limit is rendered as a text block instead of Markdown.
+// micromark is quadratic in unclosed brackets (80k `[a](` takes about 45 s)
+// and in balanced link and emphasis markup (40k nested brackets, `[]` pairs,
+// `[a]` references, or `*a` runs take 5 to 36 s), and remark-stringify is
+// quadratic in the characters it escapes (40k `<` or `{` take 0.7 s, minutes
+// at the 1 MiB cap). At 10k either costs well under 2 s. The largest real doc
+// seen (openai-go's README, 60 KB) has about 1,500 such characters and no more
+// than 3 unclosed brackets.
+const MAX_UNCLOSED = 1000;
+const MAX_MARKUP = 10000;
+const MARKUP = new Set(['[', ']', '*', '_', '<', '>', '{', '}', '`', '&']);
+function unparseable(markdown) {
+    let square = 0;
+    let round = 0;
+    let unclosed = 0;
+    let markup = 0;
+    for (let i = 0; i < markdown.length; i += 1) {
+        const char = markdown[i];
+        if (char !== undefined && MARKUP.has(char))
+            markup += 1;
+        if (char === '\\')
+            i += 1;
+        else if (char === '[')
+            square += 1;
+        else if (char === '(')
+            round += 1;
+        else if (char === ']') {
+            if (square > 0)
+                square -= 1;
+            else
+                unclosed += 1;
+        }
+        else if (char === ')') {
+            if (round > 0)
+                round -= 1;
+            else
+                unclosed += 1;
+        }
+    }
+    return square + round + unclosed > MAX_UNCLOSED || markup > MAX_MARKUP;
+}
+const MAX_DESCRIPTION = 160;
+// The text up to and including the first full stop that ends a sentence, or
+// all of it; untruncated, so it can be compared with the paragraph it came from.
+function leadingSentence(text) {
+    if (!text)
+        return undefined;
+    const end = /\.\s/.exec(text);
+    return end ? text.slice(0, end.index + 1) : text;
+}
+function firstSentence(text) {
+    const sentence = leadingSentence(text);
+    return sentence && truncate(sentence, MAX_DESCRIPTION);
+}
+//# sourceMappingURL=go.js.map