@mintlify/scraping 4.0.1161 → 4.0.1162

package/__test__/sdk-go.test.ts

@@ -0,0 +1,1671 @@
+import { preprocessCustomHeadingIds } from '@mintlify/common';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import remarkMdx from 'remark-mdx';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import { visit } from 'unist-util-visit';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { convertGo } from '../src/sdk/converters/go.js';
+import { findSdkPage, renderSdkTarget } from '../src/sdk/findSdkPage.js';
+import { safeHref } from '../src/sdk/mdx.js';
+import type { SdkPage, SdkReference } from '../src/sdk/types.js';
+
+const goldenDir = fileURLToPath(
+  new URL('../../mintlify-go-extractor/internal/extract/testdata/golden/', import.meta.url)
+);
+const golden = (name: string) => path.join(goldenDir, `${name}.json`);
+
+function page(reference: SdkReference, slug: string): SdkPage {
+  const found = reference.pages.find((entry) => entry.slug === slug);
+  if (!found) throw new Error(`missing page ${slug}`);
+  return found;
+}
+
+// Components the converter emits, plus the h1-h6 that heading ids become.
+const ALLOWED_JSX = [
+  'ResponseField',
+  'Warning',
+  'code',
+  'Steps',
+  'Step',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+];
+
+// The converter writes literal text inside <code> as {"..."}; an expression
+// that is exactly one JSON string evaluates to that text and nothing else.
+function isStringLiteral(source: string): boolean {
+  try {
+    return typeof JSON.parse(source) === 'string';
+  } catch {
+    return false;
+  }
+}
+
+// Everything in a rendered page that MDX would execute or a browser would
+// follow as script: ESM, expressions, unknown JSX, and javascript:/data: URLs.
+function liveMdx(mdx: string): string[] {
+  const tree = unified().use(remarkParse).use(remarkMdx).parse(preprocessCustomHeadingIds(mdx));
+  const found: string[] = [];
+  visit(tree, (node) => {
+    if (node.type === 'mdxjsEsm') found.push(node.type);
+    if (node.type === 'mdxFlowExpression' || node.type === 'mdxTextExpression') {
+      const value = (node as { value: string }).value;
+      if (!isStringLiteral(value)) found.push(`${node.type}:${value}`);
+    }
+    if (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') {
+      const name = (node as { name?: string | null }).name ?? '';
+      if (!ALLOWED_JSX.includes(name)) found.push(`jsx:${name}`);
+    }
+    const url = (node as { url?: string }).url;
+    if (url !== undefined && /^\s*(?:javascript|data|vbscript):/i.test(url)) {
+      found.push(`${node.type}:${url}`);
+    }
+  });
+  return found;
+}
+
+function expectNoLiveMdx(reference: SdkReference) {
+  for (const entry of reference.pages) {
+    expect(liveMdx(entry.content), entry.slug).toEqual([]);
+    if (entry.intro) expect(liveMdx(entry.intro), `${entry.slug} intro`).toEqual([]);
+  }
+}
+
+function within(ms: number, run: () => unknown) {
+  const start = performance.now();
+  run();
+  expect(performance.now() - start).toBeLessThan(ms);
+}
+
+describe('convertGo', () => {
+  let basic: SdkReference;
+
+  beforeAll(async () => {
+    basic = await convertGo(golden('basic'));
+  });
+
+  it('groups pages by package with the overview first', () => {
+    expect(basic.groups).toEqual([
+      {
+        group: 'acme',
+        pages: [
+          'package-overview',
+          'Alias',
+          'Client',
+          'Color',
+          'Handler',
+          'Settings',
+          'Store',
+          'Widget',
+          'WidgetService',
+          'NewClient',
+          'Parse',
+        ],
+      },
+      { group: 'legacy', pages: ['legacy/package-overview', 'legacy/Client'] },
+      {
+        group: 'option',
+        pages: [
+          'option/package-overview',
+          'option/Config',
+          'option/RequestOption',
+          'option/WithAPIKey',
+        ],
+      },
+    ]);
+  });
+
+  it('renders package overview pages', () => {
+    const overview = page(basic, 'package-overview');
+    expect(overview.title).toBe('package acme');
+    expect(overview.tag).toBe('PACKAGE');
+    expect(overview.target).toEqual({ kind: 'package', name: 'acme' });
+    expect(overview.intro).toBe(
+      [
+        'The Acme Go library provides access to the Acme API.',
+        '',
+        '## Installation',
+        '',
+        '```sh',
+        'go get example.com/acme',
+        '```',
+        '',
+        'See [the option package](option/README.md) and ![logo](assets/logo.png).',
+      ].join('\n')
+    );
+    expect(overview.content).not.toContain('Acme Go library');
+    const option = page(basic, 'option/package-overview');
+    expect(option).toMatchObject({
+      description: 'Request options for the Acme client.',
+      target: { kind: 'package', name: 'option' },
+    });
+    expect(option.intro).toBeUndefined();
+    expect(page(basic, 'legacy/package-overview').intro).toBeUndefined();
+    expect(renderSdkTarget(basic, { kind: 'package', name: 'option' }).slug).toBe(
+      'option/package-overview'
+    );
+    expect(overview.description).toBe('Package acme is the Go client for the Acme API.');
+    expect(overview.content).toContain('- [Client](/Client)');
+    expect(overview.content).toContain(
+      '## Functions\n\n- [NewClient](/NewClient)\n- [Parse](/Parse)'
+    );
+    expect(overview.content).toContain('## Constants\n\n```go\nconst DefaultTimeout = 30\n```');
+    expect(page(basic, 'legacy/package-overview').content).toContain(
+      '<Warning>\n  Deprecated: Use [example.com/acme.Client](/Client) instead.\n</Warning>'
+    );
+  });
+
+  it('renders type pages with fields, constructors, and methods', () => {
+    const client = page(basic, 'Client');
+    expect(client).toMatchObject({
+      title: 'Client',
+      tag: 'STRUCT',
+      description: 'Client calls the Acme API.',
+      target: { kind: 'type', name: 'Client' },
+    });
+    expect(client.content).toContain('```go\ntype Client struct\n```');
+    expect(client.content).not.toContain('BaseURL string `json:"base_url"`');
+    expect(page(basic, 'Color').content).toContain('```go\ntype Color int\n```');
+    expect(client.content).toContain(
+      '<ResponseField name={"Widgets"} id={"Widgets"} type={"*WidgetService"} typeHref={"/WidgetService"}>'
+    );
+    expect(client.content).toContain(
+      '<ResponseField name={"Options"} id={"Options"} type={"[]option.RequestOption"} typeHref={"/option/RequestOption"}>'
+    );
+    expect(client.content).toContain(
+      '<ResponseField name={"Reader"} id={"Reader"} type={"io.Reader"}>\n  **Type:** <code>{"io."}[Reader](https://pkg.go.dev/io#Reader)</code>\n\n  Embedded field.'
+    );
+    expect(client.content).toContain(
+      '<ResponseField name={"BaseURL"} id={"BaseURL"} type={"string"}>\n  **Tag:** `json:"base_url"`'
+    );
+    expect(client.content).toContain(
+      '<Warning>\n    Deprecated: Use [Client.Do](/Client#Client.Do) instead.\n  </Warning>'
+    );
+    expect(client.content).toContain('## Constructors\n\n### NewClient()');
+    expect(client.content).toContain('#### Returns\n\n<code>{"*"}[Client](/Client)</code>');
+    expect(client.content).toContain(
+      '#### Returns\n\n<code>{"(*"}[Widget](/Widget){", error)"}</code>'
+    );
+    expect(client.content).toContain(
+      '##### Example\n\n```go\nclient := acme.NewClient()\nfmt.Println(client.BaseURL == "")\n```\n\nOutput:\n\n```text\ntrue\n```'
+    );
+  });
+
+  it('resolves doc links to pages, member anchors, and pkg.go.dev', () => {
+    const client = page(basic, 'Client');
+    expect(client.content).toContain(
+      'Create one with [NewClient](/NewClient) and see [Client.Do](/Client#Client.Do).'
+    );
+    expect(client.content).toContain('[io.Reader](https://pkg.go.dev/io#Reader)');
+    expect(client.content).toContain('\\[Missing]');
+    expect(client.content).toContain('`[Widget]`');
+  });
+
+  it('gives method headings explicit ids that survive author content and section headings', () => {
+    const widget = page(basic, 'Widget');
+    expect(widget.content).toContain('## Fields\n\n');
+    expect(widget.content).toContain('## Methods\n\n### Fields() {#Widget.Fields}');
+    expect(widget.content).toContain('Call [Widget.Fields](/Widget#Widget.Fields) to list');
+  });
+
+  it('demotes comment headings below page sections', () => {
+    expect(page(basic, 'Widget').content).toContain(
+      'Parse parses a widget.\n\n#### Format\n\nThe input looks like:'
+    );
+  });
+
+  it('marks deprecated types and interfaces', () => {
+    expect(page(basic, 'WidgetService').content).toContain(
+      '<Warning>\n  Deprecated: Use [Client](/Client) directly.\n</Warning>'
+    );
+    expect(page(basic, 'Store')).toMatchObject({
+      tag: 'INTERFACE',
+      target: { kind: 'interface', name: 'Store' },
+    });
+    expect(page(basic, 'Store').content).toContain('```go\ntype Store interface\n```');
+  });
+
+  it('adds member pages that resolve frontmatter targets', () => {
+    expect(() => renderSdkTarget(basic, { kind: 'type', name: 'Client' })).toThrow(
+      'SDK symbol is ambiguous: type Client matches acme.Client, acme.legacy.Client'
+    );
+    expect(renderSdkTarget(basic, { kind: 'type', name: 'Widget' }).slug).toBe('Widget');
+    expect(renderSdkTarget(basic, { kind: 'function', name: 'NewClient' })).toMatchObject({
+      slug: 'NewClient',
+      tag: 'FUNCTION',
+    });
+    expect(renderSdkTarget(basic, { kind: 'type', name: 'acme.Client' }).slug).toBe('Client');
+    expect(renderSdkTarget(basic, { kind: 'type', name: 'legacy.Client' }).slug).toBe(
+      'legacy/Client'
+    );
+    expect(
+      renderSdkTarget(basic, { kind: 'method', name: 'Do', parent: 'acme.Client' })
+    ).toMatchObject({
+      slug: 'Client/Do',
+      title: 'Client.Do',
+      tag: 'METHOD',
+    });
+    expect(() =>
+      renderSdkTarget(basic, { kind: 'method', name: 'Do', parent: 'legacy.Client' })
+    ).toThrow('SDK symbol not found: method legacy.Client.Do');
+    expect(
+      renderSdkTarget(basic, { kind: 'property', name: 'BaseURL', parent: 'acme.Client' })
+    ).toMatchObject({ slug: 'Client/BaseURL', tag: 'FIELD' });
+    expect(
+      basic.groups
+        .flatMap((group) => group.pages)
+        .filter((entry) => typeof entry === 'string' && entry.startsWith('Client/'))
+    ).toEqual([]);
+  });
+
+  it('renders Go doc comment syntax literally in godoc mode', async () => {
+    const reference = await convertGo(golden('basic-godoc'));
+    expect(page(reference, 'Client').content).toContain(
+      'It is safe for \\*\\*concurrent\\*\\* use.'
+    );
+  });
+
+  it('renders generics and package-level functions', async () => {
+    const reference = await convertGo(golden('generics'));
+    const sum = page(reference, 'Sum');
+    expect(sum).toMatchObject({ tag: 'FUNCTION', target: { kind: 'function', name: 'Sum' } });
+    expect(sum.content).toContain(
+      '## Type Parameters\n\n<ResponseField name={"Item"} type={"Number"} typeHref={"/Number"}>'
+    );
+    expect(sum.content).toContain('## Returns\n\n`Item`');
+    expect(page(reference, 'Number').content).toContain(
+      '```go\ntype Number interface {\n\t~int | ~int64 | ~float64\n}\n```'
+    );
+    expect(page(reference, 'Opt').content).toContain(
+      '#### Returns\n\n<code>[Opt](/Opt){"[T]"}</code>'
+    );
+  });
+
+  it('links in-module packages and leaves private references unlinked', async () => {
+    const record = page(await convertGo(golden('privacy')), 'Record');
+    expect(record.content).toContain(
+      '<ResponseField name={"Sub"} id={"Sub"} type={"subpkg.Thing"} typeHref={"/sub/Thing"}>'
+    );
+    expect(record.content).toContain(
+      '<ResponseField name={"Private"} id={"Private"} type={"priv.Model"}>\n\n</ResponseField>'
+    );
+    expect(record.content).toContain(
+      '[Widget](https://pkg.go.dev/github.com/public/widgets/v2#Widget)'
+    );
+    expect(record.content).toContain('Its \\[corp.example/sdk/models.Model] stays private.');
+  });
+
+  it('produces valid MDX for every page', async () => {
+    const processor = unified().use(remarkParse).use(remarkMdx);
+    for (const name of ['basic', 'basic-godoc', 'generics', 'privacy', 'hostile']) {
+      const reference = await convertGo(golden(name));
+      for (const entry of reference.pages) {
+        expect(
+          () => processor.parse(preprocessCustomHeadingIds(entry.content)),
+          `${name}: ${entry.slug}`
+        ).not.toThrow();
+      }
+    }
+  });
+
+  describe('synthetic artifacts', () => {
+    let dir: string;
+
+    beforeAll(async () => {
+      dir = await mkdtemp(path.join(os.tmpdir(), 'go-artifact-'));
+    });
+
+    afterAll(async () => {
+      await rm(dir, { recursive: true, force: true });
+    });
+
+    async function artifact(
+      name: string,
+      packages: unknown[],
+      module = 'example.com/acme'
+    ): Promise<string> {
+      const file = path.join(dir, `${name}.json`);
+      await writeFile(
+        file,
+        JSON.stringify({
+          schemaVersion: 1,
+          generator: { name: 'mintlify-go-extractor', version: 'test', go: 'go1.22' },
+          module,
+          goos: 'linux',
+          goarch: 'amd64',
+          commentSyntax: 'markdown',
+          packages,
+        })
+      );
+      return file;
+    }
+
+    it('keeps Unicode names distinct in slugs', async () => {
+      const reference = await convertGo(
+        await artifact('unicode', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            types: [
+              { name: 'Éclair', kind: 'struct', decl: [{ t: 'type Éclair struct{}' }] },
+              { name: 'Üclair', kind: 'struct', decl: [{ t: 'type Üclair struct{}' }] },
+            ],
+          },
+        ])
+      );
+      expect(reference.groups[0]?.pages).toEqual(['package-overview', 'Éclair', 'Üclair']);
+    });
+
+    it('links same-named constructors and methods to their own pages and headings', async () => {
+      const reference = await convertGo(
+        await artifact('anchors', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            types: [
+              {
+                name: 'Client',
+                kind: 'struct',
+                decl: [{ t: 'type Client struct{}' }],
+                doc: 'Use [Close](go:example.com/acme#Close) or [Client.Close](go:example.com/acme#Client.Close).',
+                funcs: [{ name: 'Close', decl: [{ t: 'func Close() *Client' }] }],
+                methods: [
+                  { name: 'Close', recv: '*Client', decl: [{ t: 'func (c *Client) Close()' }] },
+                ],
+              },
+            ],
+          },
+        ])
+      );
+      expect(page(reference, 'Client').content).toContain(
+        'Use [Close](/Close) or [Client.Close](/Client#Client.Close).'
+      );
+    });
+
+    it('links field references to the rendered field', async () => {
+      const reference = await convertGo(
+        await artifact('fields', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            types: [
+              {
+                name: 'Client',
+                kind: 'struct',
+                decl: [{ t: 'type Client struct{ BaseURL string }' }],
+                doc: 'Set [Client.BaseURL](go:example.com/acme#Client.BaseURL) first.',
+                fields: [{ name: 'BaseURL', type: [{ t: 'string' }] }],
+              },
+            ],
+          },
+        ])
+      );
+      expect(page(reference, 'Client').content).toContain(
+        'Set [Client.BaseURL](/Client#BaseURL) first.'
+      );
+    });
+
+    it('keeps routes distinct when names differ only by case', async () => {
+      const reference = await convertGo(
+        await artifact('case', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            funcs: [{ name: 'Parse', decl: [{ t: 'func Parse()' }] }],
+            types: [
+              {
+                name: 'URL',
+                kind: 'struct',
+                decl: [{ t: 'type URL struct{}' }],
+                fields: [
+                  { name: 'Host', type: [{ t: 'string' }] },
+                  { name: 'HOST', type: [{ t: 'string' }] },
+                ],
+                doc: 'See [Url](go:example.com/acme#Url) and [URL.HOST](go:example.com/acme#URL.HOST).',
+              },
+              { name: 'Url', kind: 'alias', decl: [{ t: 'type Url = URL' }] },
+              { name: 'PARSE', kind: 'defined', decl: [{ t: 'type PARSE int' }] },
+            ],
+          },
+        ])
+      );
+      expect(reference.groups[0]?.pages).toEqual([
+        'package-overview',
+        'URL',
+        'Url-2',
+        'PARSE-2',
+        'Parse',
+      ]);
+      expect(page(reference, 'URL').content).toContain(
+        'See [Url](/Url-2) and [URL.HOST](/URL#HOST).'
+      );
+      expect(
+        renderSdkTarget(reference, { kind: 'property', name: 'HOST', parent: 'URL' }).slug
+      ).toBe('URL/HOST-2');
+    });
+
+    it('reserves package routes before member routes', async () => {
+      const reference = await convertGo(
+        await artifact('member-routes', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            types: [
+              {
+                name: 'Client',
+                kind: 'struct',
+                decl: [{ t: 'type Client struct{}' }],
+                methods: [{ name: 'Do', recv: '*Client', decl: [{ t: 'func (c *Client) Do()' }] }],
+              },
+            ],
+          },
+          {
+            importPath: 'example.com/acme/client',
+            name: 'client',
+            dir: 'client',
+            funcs: [{ name: 'Do', decl: [{ t: 'func Do()' }] }],
+          },
+        ])
+      );
+      expect(reference.groups[1]?.pages).toEqual(['client/package-overview', 'client/Do']);
+      expect(
+        renderSdkTarget(reference, { kind: 'method', name: 'Do', parent: 'Client' }).slug
+      ).toBe('Client/Do-2');
+    });
+
+    it('resolves many colliding names without quadratic probing', async () => {
+      const count = 20_000;
+      const file = await artifact('collisions', [
+        {
+          importPath: 'example.com/acme',
+          name: 'acme',
+          dir: '.',
+          funcs: Array.from({ length: count }, () => ({
+            name: 'Dup',
+            decl: [{ t: 'func Dup()' }],
+          })),
+        },
+      ]);
+      const started = performance.now();
+      const reference = await convertGo(file);
+      expect(performance.now() - started).toBeLessThan(5_000);
+      expect(reference.groups[0]?.pages).toHaveLength(count + 1);
+      expect(reference.groups[0]?.pages.at(-1)).toBe(`Dup-${count}`);
+    });
+
+    it('renders unnamed parameters as a linked chip', async () => {
+      const reference = await convertGo(
+        await artifact('unnamed', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            types: [
+              { name: 'Widget', kind: 'struct', decl: [{ t: 'type Widget struct{}' }] },
+              {
+                name: 'Store',
+                kind: 'interface',
+                decl: [{ t: 'type Store interface{ Save(*Widget, []byte) error }' }],
+                methods: [
+                  {
+                    name: 'Save',
+                    decl: [{ t: 'Save(*Widget, []byte) error' }],
+                    params: [
+                      { type: [{ t: '*' }, { t: 'Widget', ref: { name: 'Widget' } }] },
+                      { type: [{ t: '[]byte' }] },
+                    ],
+                    results: [{ type: [{ t: 'error' }] }],
+                  },
+                ],
+              },
+            ],
+          },
+        ])
+      );
+      expect(page(reference, 'Store').content).toContain(
+        '#### Parameters\n\n<code>{"(*"}[Widget](/Widget){", []byte)"}</code>'
+      );
+    });
+
+    it('rejects names that are not Go identifiers', async () => {
+      const file = await artifact('injection', [
+        {
+          importPath: 'example.com/acme',
+          name: 'acme',
+          dir: '.',
+          funcs: [{ name: 'alert(3)', decl: [{ t: 'func alert(3)()' }] }],
+        },
+      ]);
+      await expect(convertGo(file)).rejects.toThrow(
+        'packages.0.funcs.0.name: expected a Go identifier'
+      );
+    });
+
+    it('rewrites README links to the GitHub repository and demotes its headings', async () => {
+      const reference = await convertGo(
+        await artifact(
+          'readme',
+          [
+            {
+              importPath: 'github.com/acme/acme-go/v2',
+              name: 'acme',
+              dir: '.',
+              doc: 'Package acme is the client.',
+              readme:
+                '# Acme\n\nSee [guide](docs/guide.md#start), ![logo](./assets/logo.png), [site](https://acme.dev), [top](#install), [ref][g] and ![badge][b].\n\n# Install\n\n### Deep\n\n[g]: docs/guide.md\n[b]: assets/badge.svg',
+            },
+            {
+              importPath: 'github.com/acme/acme-go/v2/option',
+              name: 'option',
+              dir: 'option',
+              readme: 'Options. See [parent](../README.md) and [local](README.md).',
+            },
+            {
+              importPath: 'github.com/acme/acme-go/v2/param',
+              name: 'param',
+              dir: 'param',
+              readme: '# Param\n\nHelpers for `param` **values**.\n\nMore detail follows.',
+            },
+          ],
+          'github.com/acme/acme-go/v2'
+        )
+      );
+      expect(page(reference, 'package-overview').intro).toBe(
+        'See [guide](https://github.com/acme/acme-go/blob/HEAD/docs/guide.md#start), ![logo](https://github.com/acme/acme-go/raw/HEAD/assets/logo.png), [site](https://acme.dev), [top](#install), [ref][g] and ![badge][b].\n\n## Install\n\n### Deep\n\n[g]: https://github.com/acme/acme-go/blob/HEAD/docs/guide.md\n\n[b]: https://github.com/acme/acme-go/raw/HEAD/assets/badge.svg'
+      );
+      const option = page(reference, 'option/package-overview');
+      expect(option).toMatchObject({
+        intro:
+          'Options. See [parent](https://github.com/acme/acme-go/blob/HEAD/README.md) and [local](https://github.com/acme/acme-go/blob/HEAD/option/README.md).',
+        target: { kind: 'package', name: 'option' },
+      });
+      expect(option.description).toBeUndefined();
+      expect(page(reference, 'param/package-overview').description).toBe(
+        'Helpers for param values.'
+      );
+    });
+
+    it('takes the description from the first prose paragraph after README badges', async () => {
+      const reference = await convertGo(
+        await artifact('badges', [
+          {
+            importPath: 'example.com/b',
+            name: 'b',
+            dir: '.',
+            readme:
+              '# B\n\n[![ci](https://x/y.svg)](https://x) ![cov](https://x/c.svg)\n\nPackage *b* does [things](https://x/docs).\n\nMore detail.',
+          },
+          {
+            importPath: 'example.com/b/long',
+            name: 'long',
+            dir: 'long',
+            readme: '[![ci](https://x/y.svg)](https://x)\n\nFirst sentence. Second sentence.',
+          },
+        ])
+      );
+      const overview = page(reference, 'package-overview');
+      expect(overview.description).toBe('Package b does things.');
+      expect(overview.intro).toBe(
+        '[![ci](https://x/y.svg)](https://x) ![cov](https://x/c.svg)\n\nMore detail.'
+      );
+      const long = page(reference, 'long/package-overview');
+      expect(long.description).toBeUndefined();
+      expect(long.intro).toBe(
+        '[![ci](https://x/y.svg)](https://x)\n\nFirst sentence. Second sentence.'
+      );
+    });
+
+    it('reads descriptions from the parsed doc, not the Markdown source', async () => {
+      const reference = await convertGo(
+        await artifact('descriptions', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            doc: 'Package acme talks to the [Acme API](https://acme.dev) via `HTTP`\\*. It retries.\n\nMore.',
+            types: [
+              {
+                name: 'Client',
+                kind: 'struct',
+                decl: [{ t: 'type Client struct{}' }],
+                doc: `Client is <b>the</b> **client** for ${'[a]('.repeat(20)}. Second sentence.`,
+              },
+            ],
+          },
+        ])
+      );
+      expect(page(reference, 'package-overview').description).toBe(
+        'Package acme talks to the Acme API via HTTP*.'
+      );
+      expect(page(reference, 'Client').description).toBe(
+        `Client is the client for ${'[a]('.repeat(20)}.`
+      );
+    });
+
+    it('cuts struct and interface headers after their own body opens', async () => {
+      const reference = await convertGo(
+        await artifact('generic-constraints', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            types: [
+              {
+                name: 'Set',
+                kind: 'struct',
+                decl: [
+                  { t: 'type Set[T interface {\n\tcomparable\n\tString() string\n}] struct {\n' },
+                  { t: '\titems map[T]struct{}\n}' },
+                ],
+              },
+              {
+                name: 'Store',
+                kind: 'interface',
+                decl: [
+                  { t: 'type Store[K interface { comparable }, V any] interface {\n' },
+                  { t: '\tGet(key K) (V, bool)\n}' },
+                ],
+              },
+            ],
+          },
+        ])
+      );
+      expect(page(reference, 'Set').content).toContain(
+        '```go\ntype Set[T interface {\n\tcomparable\n\tString() string\n}] struct\n```'
+      );
+      expect(page(reference, 'Store').content).toContain(
+        '```go\ntype Store[K interface { comparable }, V any] interface {\n\tGet(key K) (V, bool)\n}\n```'
+      );
+    });
+
+    it('resolves README links for modules in a repository subdirectory', async () => {
+      const reference = await convertGo(
+        await artifact(
+          'subdir-module',
+          [
+            {
+              importPath: 'github.com/acme/monorepo/sdk/go/v12',
+              name: 'acme',
+              dir: '.',
+              doc: 'Package acme is the client.',
+              readme: '![logo](./assets/logo.svg) and [sub](option/README.md)',
+            },
+          ],
+          'github.com/acme/monorepo/sdk/go/v12'
+        )
+      );
+      expect(page(reference, 'package-overview').intro).toBe(
+        '![logo](https://github.com/acme/monorepo/raw/HEAD/sdk/go/assets/logo.svg) and [sub](https://github.com/acme/monorepo/blob/HEAD/sdk/go/option/README.md)'
+      );
+    });
+
+    it('addresses nested packages by their parent directory', async () => {
+      const reference = await convertGo(
+        await artifact('nested-packages', [
+          { importPath: 'example.com/acme/audio/client', name: 'client', dir: 'audio/client' },
+          { importPath: 'example.com/acme/batches/client', name: 'client', dir: 'batches/client' },
+        ])
+      );
+      expect(renderSdkTarget(reference, { kind: 'package', name: 'batches.client' }).slug).toBe(
+        'batches/client/package-overview'
+      );
+      expect(() => renderSdkTarget(reference, { kind: 'package', name: 'client' })).toThrow(
+        'matches audio.client, batches.client'
+      );
+    });
+
+    it('addresses packages by their directory when it differs from the package name', async () => {
+      const reference = await convertGo(
+        await artifact('versioned-packages', [
+          {
+            importPath: 'example.com/acme/api/v1',
+            name: 'api',
+            dir: 'api/v1',
+            types: [{ name: 'Request', kind: 'struct', decl: [{ t: 'type Request struct{}' }] }],
+          },
+          {
+            importPath: 'example.com/acme/api/v2',
+            name: 'api',
+            dir: 'api/v2',
+            types: [{ name: 'Request', kind: 'struct', decl: [{ t: 'type Request struct{}' }] }],
+          },
+        ])
+      );
+      expect(page(reference, 'api/v2/package-overview').target).toEqual({
+        kind: 'package',
+        name: 'v2',
+        namespace: 'api',
+      });
+      expect(renderSdkTarget(reference, { kind: 'package', name: 'api.v1' }).slug).toBe(
+        'api/v1/package-overview'
+      );
+      expect(renderSdkTarget(reference, { kind: 'type', name: 'api.v2.Request' }).slug).toBe(
+        'api/v2/Request'
+      );
+      expect(() => renderSdkTarget(reference, { kind: 'type', name: 'Request' })).toThrow(
+        'matches api.v1.Request, api.v2.Request'
+      );
+    });
+
+    it('keeps a root package apart from a top-level directory of the same name', async () => {
+      const type = { name: 'C', kind: 'struct', decl: [{ t: 'type C struct{}' }] };
+      const reference = await convertGo(
+        await artifact('root-collision', [
+          { importPath: 'example.com/client', name: 'client', dir: '.', types: [type] },
+          { importPath: 'example.com/client/client', name: 'client', dir: 'client', types: [type] },
+        ])
+      );
+      expect(page(reference, 'package-overview').target).toEqual({
+        kind: 'package',
+        name: 'client',
+      });
+      expect(page(reference, 'client/package-overview').target).toEqual({
+        kind: 'package',
+        name: 'client',
+        namespace: 'client',
+      });
+      expect(renderSdkTarget(reference, { kind: 'package', name: 'client' }).slug).toBe(
+        'package-overview'
+      );
+      expect(renderSdkTarget(reference, { kind: 'package', name: 'client.client' }).slug).toBe(
+        'client/package-overview'
+      );
+      expect(renderSdkTarget(reference, { kind: 'type', name: 'client.C' }).slug).toBe('C');
+      expect(renderSdkTarget(reference, { kind: 'type', name: 'client.client.C' }).slug).toBe(
+        'client/C'
+      );
+      expect(() => renderSdkTarget(reference, { kind: 'type', name: 'C' })).toThrow(
+        'matches client.C, client.client.C'
+      );
+    });
+
+    it('rejects packages whose dotted directories would share an address', async () => {
+      const file = await artifact('dotted-dirs', [
+        { importPath: 'example.com/m/a.b/c', name: 'c', dir: 'a.b/c' },
+        { importPath: 'example.com/m/a/b.c', name: 'c', dir: 'a/b.c' },
+      ]);
+      await expect(convertGo(file)).rejects.toThrow(
+        'packages.1.dir: packages a.b/c and a/b.c would both be addressed as a.b.c'
+      );
+      const duplicateDir = await artifact('duplicate-dir', [
+        { importPath: 'example.com/m/x', name: 'x', dir: 'x' },
+        { importPath: 'example.com/m/y', name: 'x', dir: 'x' },
+      ]);
+      await expect(convertGo(duplicateDir)).rejects.toThrow(
+        'packages.1.dir: duplicate package directory x'
+      );
+      const dots = await artifact('dots-dir', [
+        { importPath: 'example.com/m/x', name: 'x', dir: 'a/...' },
+      ]);
+      await expect(convertGo(dots)).rejects.toThrow('packages.0.dir: expected "."');
+      const oddDir = await artifact('odd-dir', [
+        { importPath: 'example.com/m/x', name: 'x', dir: 'a b/{x}' },
+      ]);
+      await expect(convertGo(oddDir)).rejects.toThrow('packages.0.dir: expected "."');
+    });
+
+    it('selects symbols in same-named packages by their directory path', async () => {
+      const type = (dir: string) => ({
+        name: 'Foo',
+        kind: 'struct',
+        decl: [{ t: `type Foo struct{} // ${dir}` }],
+      });
+      const reference = await convertGo(
+        await artifact('same-named-packages', [
+          {
+            importPath: 'example.com/acme/audio/client',
+            name: 'client',
+            dir: 'audio/client',
+            types: [type('audio')],
+          },
+          {
+            importPath: 'example.com/acme/batches/client',
+            name: 'client',
+            dir: 'batches/client',
+            types: [type('batches')],
+          },
+        ])
+      );
+      expect(renderSdkTarget(reference, { kind: 'type', name: 'batches.client.Foo' }).slug).toBe(
+        'batches/client/Foo'
+      );
+      expect(renderSdkTarget(reference, { kind: 'type', name: 'audio.client.Foo' }).slug).toBe(
+        'audio/client/Foo'
+      );
+      expect(() => renderSdkTarget(reference, { kind: 'type', name: 'client.Foo' })).toThrow(
+        'SDK symbol is ambiguous: type client.Foo matches audio.client.Foo, batches.client.Foo'
+      );
+    });
+
+    it('renders the hostile golden without live MDX', async () => {
+      const reference = await convertGo(golden('hostile'));
+      const processor = unified().use(remarkParse).use(remarkMdx);
+      const live = (mdx: string) => {
+        const tree = processor.parse(preprocessCustomHeadingIds(mdx));
+        const types: string[] = [];
+        visit(tree, (node) => {
+          if (/^mdx(?:jsEsm|FlowExpression|TextExpression)$/.test(node.type)) types.push(node.type);
+          const url = (node as { url?: string }).url;
+          if (url !== undefined && /^\s*(?:javascript|data|vbscript):/i.test(url)) {
+            types.push(`${node.type}:${url}`);
+          }
+          if (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') {
+            const name = (node as { name?: string | null }).name ?? '';
+            if (!['ResponseField', 'Warning', 'code', 'Steps', 'Step'].includes(name))
+              types.push(`jsx:${name}`);
+          }
+        });
+        return types;
+      };
+      for (const entry of reference.pages) {
+        expect(live(entry.content), entry.slug).toEqual([]);
+        if (entry.intro) expect(live(entry.intro), `${entry.slug} intro`).toEqual([]);
+      }
+      const overview = page(reference, 'package-overview');
+      expect(overview.content).toContain('&#105;mport x from "y"');
+      expect(overview.content).toContain('&#101;xport GOPRIVATE=example.com/\\*');
+      const record = page(reference, 'Record');
+      expect(record.content).toContain('**Tag:** `json:"raw" extra:"{alert(1)}"`');
+      expect(record.content).not.toMatch(/\n\n\{alert/);
+      const intro = overview.intro ?? '';
+      expect(intro).toContain('&#105;mport fs from "node:fs"');
+      expect(intro).toContain('&#101;xport default function X()\\{}');
+      expect(intro).toContain('Env\n\n&#101;xport FOO=bar');
+      expect(intro).toContain('first\n\n&#105;mport os from "node:os"');
+      expect(intro).toContain('&#105;mport starts this paragraph after an inline tag.');
+      expect(page(reference, 'Do').content).toContain('&#101;xport is the first word after a tag.');
+      expect(intro).toContain('&#105;mport x from "y"');
+      expect(intro).toContain('&#101;xport const a = 1');
+      expect(intro).toContain('See one, two, three, and four.');
+      expect(page(reference, 'Do').content).toContain('&#105;mport x from "y"');
+    });
+
+    it('escapes ESM in HTML blocks with CRLF or bare CR line endings', async () => {
+      const block = (eol: string, open: string, close: string) =>
+        [open, 'import a from "a"', '', 'export const b = 1', close].join(eol);
+      const reference = await convertGo(
+        await artifact('cr-html', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            doc: 'Package acme is the client.',
+            readme: [
+              block('\r\n', '<pre>', '</pre>'),
+              block('\r', '<!--', '-->'),
+              block('\r\n', '<details>', '</details>'),
+            ].join('\r\n\r\n'),
+          },
+        ])
+      );
+      const intro = page(reference, 'package-overview').intro ?? '';
+      expect(intro).not.toMatch(/\r/);
+      // The comment's text is dropped with it; <pre> and <details> keep theirs.
+      expect(intro.match(/&#105;mport a from "a"/g)).toHaveLength(2);
+      expect(intro.match(/&#101;xport const b = 1/g)).toHaveLength(2);
+      const tree = unified().use(remarkParse).use(remarkMdx).parse(intro);
+      const esm: string[] = [];
+      visit(tree, 'mdxjsEsm', (node: { value: string }) => {
+        esm.push(node.value);
+      });
+      expect(esm).toEqual([]);
+    });
+
+    it('keeps a bare carriage return from ending a code span', async () => {
+      const reference = await convertGo(
+        await artifact('carriage-return', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            types: [
+              { name: 'Widget', kind: 'struct', decl: [{ t: 'type Widget struct{}' }] },
+              {
+                name: 'Record',
+                kind: 'struct',
+                decl: [{ t: 'type Record struct{}' }],
+                fields: [
+                  { name: 'Raw', type: [{ t: 'string' }], tag: 'a\r\r<Danger>{alert(1)}</Danger>' },
+                ],
+                methods: [
+                  {
+                    name: 'Do',
+                    decl: [{ t: 'func (r Record) Do() *Widget' }],
+                    results: [
+                      { type: [{ t: 'Opt\r\r' }, { t: 'Widget', ref: { name: 'Widget' } }] },
+                    ],
+                  },
+                ],
+              },
+            ],
+          },
+        ])
+      );
+      const record = page(reference, 'Record').content;
+      expect(record).toContain('**Tag:** `a <Danger>{alert(1)}</Danger>`');
+      expect(record).toContain('<code>{"Opt "}[Widget](/Widget)</code>');
+      expect(record).not.toMatch(/\r/);
+    });
+
+    it('collapses newlines inside code spans and linked code', async () => {
+      const reference = await convertGo(
+        await artifact('newlines', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            types: [
+              { name: 'Widget', kind: 'struct', decl: [{ t: 'type Widget struct{}' }] },
+              {
+                name: 'Record',
+                kind: 'struct',
+                decl: [{ t: 'type Record struct{}' }],
+                fields: [
+                  { name: 'Raw', type: [{ t: 'string' }], tag: 'json:"x"\n\n{alert(5)}\n\nhi' },
+                ],
+                methods: [
+                  {
+                    name: 'Do',
+                    decl: [{ t: 'func (r Record) Do() (*Widget, error)' }],
+                    results: [
+                      {
+                        type: [
+                          { t: '*\n\n{alert(3)}\n\n' },
+                          { t: 'Widget', ref: { name: 'Widget' } },
+                        ],
+                      },
+                      { type: [{ t: 'error\n\n{alert(4)}' }] },
+                    ],
+                  },
+                  {
+                    name: 'Mode',
+                    decl: [{ t: 'func (r Record) Mode() string' }],
+                    results: [{ type: [{ t: '"a  b" |\t"c"' }] }],
+                  },
+                ],
+              },
+            ],
+          },
+        ])
+      );
+      const record = page(reference, 'Record').content;
+      expect(record).toContain('**Tag:** `json:"x" {alert(5)} hi`');
+      expect(record).toContain(
+        '<code>{"(* {alert(3)} "}[Widget](/Widget){", error {alert(4)})"}</code>'
+      );
+      expect(record).toContain('`"a  b" |\t"c"`');
+      expect(record).not.toMatch(/\n\{alert/);
+    });
+
+    it('drops unsafe URL schemes from READMEs and doc comments', async () => {
+      const reference = await convertGo(
+        await artifact(
+          'schemes',
+          [
+            {
+              importPath: 'github.com/acme/acme-go',
+              name: 'acme',
+              dir: '.',
+              doc: 'Package acme is the client.',
+              readme:
+                '[a](javascript:alert(2)) ![i](data:text/html,x) [ok](https://acme.dev) [mail](mailto:x@y.z) [rel](docs/a.md)',
+              types: [
+                {
+                  name: 'Client',
+                  kind: 'struct',
+                  decl: [{ t: 'type Client struct{}' }],
+                  doc: 'See [bad](javascript:alert(1)) and [good](https://acme.dev) and [Client](go:github.com/acme/acme-go#Client).',
+                },
+              ],
+            },
+          ],
+          'github.com/acme/acme-go'
+        )
+      );
+      expect(page(reference, 'package-overview').intro).toBe(
+        'a i [ok](https://acme.dev) [mail](mailto:x@y.z) [rel](https://github.com/acme/acme-go/blob/HEAD/docs/a.md)'
+      );
+      expect(page(reference, 'Client').content).toContain(
+        'See bad and [good](https://acme.dev) and [Client](/Client).'
+      );
+    });
+
+    it('writes out long unlinked field types in full', async () => {
+      const long = `struct { ${Array.from({ length: 12 }, (_, i) => `F${i} string`).join('; ')} }`;
+      const reference = await convertGo(
+        await artifact('long-types', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            types: [
+              {
+                name: 'Record',
+                kind: 'struct',
+                decl: [{ t: 'type Record struct{}' }],
+                fields: [
+                  { name: 'Short', type: [{ t: 'map[string]int' }] },
+                  { name: 'Long', type: [{ t: long }] },
+                ],
+              },
+            ],
+          },
+        ])
+      );
+      const record = page(reference, 'Record').content;
+      expect(record).toContain(`**Type:** \`${long}\``);
+      expect(record).not.toContain('**Type:** `map[string]int`');
+    });
+
+    it('drops reference definitions that spell a scheme with character references', async () => {
+      const readme = [
+        'See [one][r1], [two][r2], [three][r3], [four][r4], and [ok][r5].',
+        '',
+        '[r1]: javascript&amp;colon;alert(1)',
+        '[r2]: javascript&#58;alert(2)',
+        '[r3]: javascript&#x3a;alert(3)',
+        '[r4]: <javascript&colon;alert(4)>',
+        '[r5]: docs/a&amp;b.md',
+      ].join('\n');
+      const reference = await convertGo(
+        await artifact(
+          'entity-schemes',
+          [
+            {
+              importPath: 'gitlab.com/acme/acme-go',
+              name: 'acme',
+              dir: '.',
+              doc: 'Package acme is the client.',
+              readme,
+              types: [
+                {
+                  name: 'Client',
+                  kind: 'struct',
+                  decl: [{ t: 'type Client struct{}' }],
+                  doc: 'See [bad][r].\n\n[r]: javascript&colon;alert(1)',
+                },
+              ],
+            },
+          ],
+          'gitlab.com/acme/acme-go'
+        )
+      );
+      const urls = (mdx: string) => {
+        const found: string[] = [];
+        visit(unified().use(remarkParse).use(remarkMdx).parse(mdx), (node) => {
+          const url = (node as { url?: string }).url;
+          if (url !== undefined) found.push(url);
+        });
+        return found;
+      };
+      const intro = page(reference, 'package-overview').intro ?? '';
+      expect(intro).toContain('See one, two, three, four, and [ok][r5].');
+      expect(urls(intro)).toEqual(['docs/a&b.md']);
+      const client = page(reference, 'Client').content;
+      expect(client).toContain('See bad.');
+      expect(urls(client).filter((url) => /javascript/i.test(url))).toEqual([]);
+    });
+
+    it('skips HTML titles for the description and drops a README sentence the synopsis repeats', async () => {
+      const reference = await convertGo(
+        await artifact('readme-descriptions', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            readme: '<h1 align="center">Acme</h1>\n\nPackage acme  talks to\nthe API.',
+          },
+          {
+            importPath: 'example.com/acme/client',
+            name: 'client',
+            dir: 'client',
+            doc: 'Package client calls the API. It retries.',
+            readme: 'Package client calls the API. Use [New] to start.\n\nMore.',
+          },
+          {
+            importPath: 'example.com/acme/breaks',
+            name: 'breaks',
+            dir: 'breaks',
+            doc: 'Package breaks has a hard  \nline break.',
+          },
+        ])
+      );
+      const root = page(reference, 'package-overview');
+      expect(root.description).toBe('Package acme talks to the API.');
+      expect(root.intro).toBe('Acme');
+      const client = page(reference, 'client/package-overview');
+      expect(client.description).toBe('Package client calls the API.');
+      expect(client.intro).toBe('Use \\[New] to start.\n\nMore.');
+      expect(page(reference, 'breaks/package-overview').description).toBe(
+        'Package breaks has a hard line break.'
+      );
+    });
+
+    it('uses a long single-sentence README paragraph and drops a marked-up repeated synopsis', async () => {
+      const long = `Package acme ${'talks to the API '.repeat(15).trim()}.`;
+      const reference = await convertGo(
+        await artifact('sentence-edges', [
+          { importPath: 'example.com/acme', name: 'acme', dir: '.', readme: `${long}\n\nMore.` },
+          {
+            importPath: 'example.com/acme/client',
+            name: 'client',
+            dir: 'client',
+            doc: 'Package client calls the Acme API. It retries.',
+            readme:
+              'Package *client* calls the [Acme](https://acme.dev) API. Use [New] to start.\n\nMore.',
+          },
+          {
+            importPath: 'example.com/acme/breaks',
+            name: 'breaks',
+            dir: 'breaks',
+            doc: 'Package breaks calls the API. It retries.',
+            readme: 'Package breaks calls the **API.**\\\nUse [New] to start.',
+          },
+          {
+            importPath: 'example.com/acme/kept',
+            name: 'kept',
+            dir: 'kept',
+            doc: 'Package kept calls the API. It retries.',
+            readme: 'Package kept calls the *API. Really* well. Use it.',
+          },
+        ])
+      );
+      const root = page(reference, 'package-overview');
+      expect(root.description).toBe(`${long.slice(0, 159)}…`);
+      expect(root.intro).toBe('More.');
+      const client = page(reference, 'client/package-overview');
+      expect(client.description).toBe('Package client calls the Acme API.');
+      expect(client.intro).toBe('Use \\[New] to start.\n\nMore.');
+      expect(page(reference, 'breaks/package-overview').intro).toBe('Use \\[New] to start.');
+      expect(page(reference, 'kept/package-overview').intro).toBe(
+        'Package kept calls the *API. Really* well. Use it.'
+      );
+    });
+
+    it('renders pathological Markdown as text instead of parsing it', async () => {
+      const hostile = '[a]('.repeat(80000);
+      const start = Date.now();
+      const reference = await convertGo(
+        await artifact('pathological', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            doc: hostile,
+            readme: hostile,
+            types: [
+              {
+                name: 'Client',
+                kind: 'struct',
+                decl: [{ t: 'type Client struct{}' }],
+                doc: hostile,
+              },
+            ],
+          },
+        ])
+      );
+      expect(Date.now() - start).toBeLessThan(5000);
+      const overview = page(reference, 'package-overview');
+      expect(overview.intro).toMatch(/^```text\n\[a\]\(/);
+      expect(page(reference, 'Client').content).toContain('```text\n[a](');
+    });
+
+    it('widens code fences past any backtick run in tags, types, and code', async () => {
+      const fenced = 'x\n```\n{alert(1)}\nimport x from "y"\n````\n{alert(2)}';
+      const reference = await convertGo(
+        await artifact('fences', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            doc: 'Package acme is the client.',
+            examples: [{ code: fenced, output: fenced }],
+            types: [
+              {
+                name: 'Record',
+                kind: 'struct',
+                decl: [{ t: `type Record struct{} // ${fenced}` }],
+                fields: [
+                  { name: 'A', type: [{ t: 'string' }], tag: 'a`{alert(1)}`b' },
+                  { name: 'B', type: [{ t: 'string' }], tag: '`lead' },
+                  { name: 'C', type: [{ t: 'string' }], tag: 'trail`' },
+                ],
+                methods: [
+                  {
+                    name: 'Do',
+                    decl: [{ t: 'func (r Record) Do() string' }],
+                    results: [{ type: [{ t: 'a``{alert(3)}``b' }] }],
+                  },
+                ],
+              },
+            ],
+          },
+        ])
+      );
+      expectNoLiveMdx(reference);
+      const record = page(reference, 'Record').content;
+      expect(record).toContain('**Tag:** ``a`{alert(1)}`b``');
+      expect(record).toContain('**Tag:** `` `lead ``');
+      expect(record).toContain('**Tag:** `` trail` ``');
+      expect(record).toContain('```a``{alert(3)}``b```');
+      expect(record).toContain('`````go\ntype Record struct{}');
+      expect(page(reference, 'package-overview').content).toContain('`````go\nx\n```');
+    });
+
+    it('escapes braces, angle brackets, and brackets in linked type text', async () => {
+      const reference = await convertGo(
+        await artifact('linked-text', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            doc: 'Package acme is the client.',
+            types: [
+              { name: 'Widget', kind: 'struct', decl: [{ t: 'type Widget struct{}' }] },
+              {
+                name: 'Record',
+                kind: 'struct',
+                decl: [{ t: 'type Record struct{}' }],
+                fields: [
+                  {
+                    name: 'W',
+                    type: [
+                      { t: 'map[string]' },
+                      { t: '{alert(1)}<b>[x]', ref: { name: 'Widget' } },
+                    ],
+                  },
+                ],
+              },
+            ],
+          },
+        ])
+      );
+      expectNoLiveMdx(reference);
+      expect(page(reference, 'Record').content).toContain(
+        '[\\{alert(1)\\}\\<b\\>\\[x\\]](/Widget)'
+      );
+    });
+
+    it('escapes ESM in HTML blocks with bare CR line endings', async () => {
+      const readme = [
+        '<pre>',
+        'import a from "a"',
+        '',
+        'export const b = 1',
+        '</pre>',
+        '',
+        '<details>',
+        'export FOO=bar',
+        '</details>',
+      ].join('\r');
+      const reference = await convertGo(
+        await artifact('bare-cr', [
+          { importPath: 'example.com/acme', name: 'acme', dir: '.', doc: 'Package acme.', readme },
+        ])
+      );
+      expectNoLiveMdx(reference);
+      const intro = page(reference, 'package-overview').intro ?? '';
+      expect(intro).toContain('&#105;mport a from "a"');
+      expect(intro).toContain('&#101;xport const b = 1');
+      expect(intro).toContain('&#101;xport FOO=bar');
+    });
+
+    it('keeps hostile inputs at the size caps fast', async () => {
+      within(1000, () => {
+        expect(safeHref(`a${' '.repeat(1 << 20)}b`)).toBe(`a${' '.repeat(1 << 20)}b`);
+      });
+      const start = performance.now();
+      const reference = await convertGo(
+        await artifact('size-caps', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            doc: `<div>\n${'<'.repeat((1 << 20) - 6)}`,
+            readme: ')'.repeat(2000),
+          },
+        ])
+      );
+      expect(performance.now() - start).toBeLessThan(5000);
+      expect(page(reference, 'package-overview').intro).toBe(
+        `\`\`\`text\n${')'.repeat(2000)}\n\`\`\``
+      );
+      const tooBig = await artifact('too-big', [
+        { importPath: 'example.com/acme', name: 'acme', dir: '.', doc: 'x'.repeat((1 << 20) + 1) },
+      ]);
+      await expect(convertGo(tooBig)).rejects.toThrow('packages.0.doc');
+    });
+
+    it('renders balanced but heavy markup as text instead of parsing it', async () => {
+      const start = performance.now();
+      const reference = await convertGo(
+        await artifact('heavy-markup', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            doc: 'Package acme.',
+            readme: `${'['.repeat(20000)}${']'.repeat(20000)}`,
+            types: [
+              {
+                name: 'A',
+                kind: 'struct',
+                decl: [{ t: 'type A struct{}' }],
+                doc: '*a'.repeat(20000),
+              },
+            ],
+          },
+        ])
+      );
+      expect(performance.now() - start).toBeLessThan(5000);
+      expect(page(reference, 'package-overview').intro).toMatch(/^```text\n\[\[/);
+      expect(page(reference, 'A').content).toContain('```text\n*a*a');
+    });
+
+    it('resolves package-only and unknown-member doc links and encodes pkg.go.dev paths', async () => {
+      const reference = await convertGo(
+        await artifact(
+          'doc-links',
+          [
+            {
+              importPath: 'github.com/acme/acme-go',
+              name: 'acme',
+              dir: '.',
+              doc: '**Package acme** is _the_ client.',
+              readme: 'Up [two](../../x.md) and [one](../y.md).',
+              types: [
+                {
+                  name: 'Client',
+                  kind: 'struct',
+                  decl: [{ t: 'type Client struct{}' }],
+                  doc: 'See [acme](go:github.com/acme/acme-go), [Client.Missing](go:github.com/acme/acme-go#Client.Missing), and [T](go:example.org/a(b)#T).',
+                },
+              ],
+            },
+          ],
+          'github.com/acme/acme-go'
+        )
+      );
+      const overview = page(reference, 'package-overview');
+      expect(overview.description).toBe('Package acme is the client.');
+      expect(overview.intro).toBe('Up [two](../../x.md) and [one](../y.md).');
+      expect(page(reference, 'Client').content).toContain(
+        'See [acme](/package-overview), [Client.Missing](/Client), and [T](https://pkg.go.dev/example.org/a%28b%29#T).'
+      );
+    });
+
+    it('reports every candidate for an ambiguous method and lets an exact one win', async () => {
+      const client = {
+        name: 'Client',
+        kind: 'struct',
+        decl: [{ t: 'type Client struct{}' }],
+        methods: [{ name: 'Do', decl: [{ t: 'func (c *Client) Do()' }] }],
+      };
+      const reference = await convertGo(
+        await artifact('ambiguous-methods', [
+          { importPath: 'example.com/acme', name: 'acme', dir: '.', types: [client] },
+          { importPath: 'example.com/acme/v2', name: 'acme', dir: 'v2', types: [client] },
+        ])
+      );
+      expect(() =>
+        findSdkPage(reference, { kind: 'method', name: 'Do', parent: 'Client' })
+      ).toThrow('method Client.Do matches acme.Client.Do, acme.v2.Client.Do');
+      expect(
+        findSdkPage(reference, { kind: 'method', name: 'Do', parent: 'acme.Client' })?.slug
+      ).toBe('Client/Do');
+      expect(
+        findSdkPage(reference, {
+          kind: 'method',
+          name: 'Do',
+          parent: 'Client',
+          namespace: 'acme.v2',
+        })?.slug
+      ).toBe('v2/Client/Do');
+    });
+
+    it('drops protocol-relative URLs spelled with character references after a slash', async () => {
+      expect(safeHref('/&sol;evil.com')).toBeUndefined();
+      expect(safeHref('\\&#47;evil.com')).toBeUndefined();
+      expect(safeHref('/docs/a&amp;b.md')).toBe('/docs/a&amp;b.md');
+    });
+
+    it('keeps spaces inside relative README links', async () => {
+      const reference = await convertGo(
+        await artifact(
+          'spaced-links',
+          [
+            {
+              importPath: 'github.com/acme/acme-go',
+              name: 'acme',
+              dir: '.',
+              doc: 'Package acme is the client.',
+              readme: '[guide](<docs/Getting Started.md>) and ![shot](<img/a b.png>)',
+            },
+          ],
+          'github.com/acme/acme-go'
+        )
+      );
+      expect(page(reference, 'package-overview').intro).toBe(
+        '[guide](<https://github.com/acme/acme-go/blob/HEAD/docs/Getting Started.md>) and ![shot](<https://github.com/acme/acme-go/raw/HEAD/img/a b.png>)'
+      );
+    });
+
+    it('keeps names apart that differ only in Unicode normalisation', async () => {
+      const composed = 'A\uAC00';
+      const decomposed = 'A\u1100\u1161';
+      const reference = await convertGo(
+        await artifact('unicode-forms', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            types: [composed, decomposed].map((name) => ({
+              name,
+              kind: 'struct',
+              decl: [{ t: `type ${name} struct{}` }],
+            })),
+          },
+        ])
+      );
+      const slugs = reference.pages
+        .filter((entry) => entry.tag === 'STRUCT')
+        .map((entry) => entry.slug.normalize('NFC').toLowerCase());
+      expect(new Set(slugs).size).toBe(2);
+    });
+
+    it('drops URLs that only look relative until a browser normalises them', async () => {
+      const readme = [
+        '[tab](<java\tscript:alert(1)>)',
+        '[ctl](<\u0001javascript:alert(1)>)',
+        '[spaced](<  javascript:alert(1)>)',
+        '[bs](\\\\evil.com)',
+        '[sbs](/\\evil.com)',
+        '[rel](docs/a.md)',
+      ].join(' ');
+      const reference = await convertGo(
+        await artifact(
+          'normalised-schemes',
+          [
+            {
+              importPath: 'gitlab.com/acme/acme-go',
+              name: 'acme',
+              dir: '.',
+              doc: 'Package acme is the client.',
+              readme,
+            },
+          ],
+          'gitlab.com/acme/acme-go'
+        )
+      );
+      expect(page(reference, 'package-overview').intro).toBe(
+        'tab ctl spaced bs sbs [rel](docs/a.md)'
+      );
+    });
+
+    it('resolves root-relative README links against the repository root', async () => {
+      const reference = await convertGo(
+        await artifact(
+          'root-links',
+          [
+            {
+              importPath: 'github.com/acme/acme-go/option',
+              name: 'option',
+              dir: 'option',
+              readme: '[abs](/docs/a.md) [rel](b.md) [both][d] ![both][d]\n\n[d]: img.png',
+            },
+          ],
+          'github.com/acme/acme-go'
+        )
+      );
+      expect(page(reference, 'option/package-overview').intro).toBe(
+        '[abs](https://github.com/acme/acme-go/blob/HEAD/docs/a.md) [rel](https://github.com/acme/acme-go/blob/HEAD/option/b.md) [both][d] ![both][d]\n\n[d]: https://github.com/acme/acme-go/blob/HEAD/option/img.png'
+      );
+    });
+
+    it('rejects traversal in package directories and duplicate import paths', async () => {
+      await expect(
+        convertGo(
+          await artifact('bad-dir', [
+            { importPath: 'example.com/acme/x', name: 'x', dir: '../../etc' },
+          ])
+        )
+      ).rejects.toThrow('packages.0.dir: expected "." or a relative directory');
+      await expect(
+        convertGo(
+          await artifact('dup', [
+            { importPath: 'example.com/acme', name: 'acme', dir: '.' },
+            { importPath: 'example.com/acme', name: 'acme', dir: 'other' },
+          ])
+        )
+      ).rejects.toThrow('packages.1.importPath: duplicate package example.com/acme');
+    });
+
+    it('leaves doc links inside code spans untouched', async () => {
+      const doc =
+        'Call `[y](go:q`) then ` alert(document.domain)} />` done. See [Client](go:example.com/acme#Client).';
+      const reference = await convertGo(
+        await artifact('code-span-links', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            types: [{ name: 'Client', kind: 'struct', decl: [{ t: 'type Client struct{}' }], doc }],
+          },
+        ])
+      );
+      const content = page(reference, 'Client').content;
+      expect(content).toContain(
+        'Call `[y](go:q`) then ` alert(document.domain)} />` done. See [Client](/Client).'
+      );
+      expect(content).not.toContain('pkg.go.dev');
+    });
+
+    it('escapes linked code text and external hrefs', async () => {
+      const reference = await convertGo(
+        await artifact('escape', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            types: [
+              {
+                name: 'Client',
+                kind: 'struct',
+                decl: [{ t: 'type Client struct{}' }],
+                fields: [
+                  {
+                    name: 'Ext',
+                    type: [
+                      { t: 'map[' },
+                      { t: 'x]*', ref: { pkg: 'gopkg.in/yaml.v3', name: 'T' } },
+                      { t: ']' },
+                    ],
+                  },
+                ],
+              },
+            ],
+          },
+        ])
+      );
+      expect(page(reference, 'Client').content).toContain(
+        '<code>{"map["}[x\\]\\*](https://pkg.go.dev/gopkg.in/yaml.v3#T){"]"}</code>'
+      );
+    });
+
+    it('demotes underlined comment headings', async () => {
+      const reference = await convertGo(
+        await artifact('setext', [
+          {
+            importPath: 'example.com/acme',
+            name: 'acme',
+            dir: '.',
+            types: [
+              {
+                name: 'Client',
+                kind: 'struct',
+                decl: [{ t: 'type Client struct{}' }],
+                doc: 'Client is a client.\n\nFormat\n------\n\nDetails.',
+              },
+            ],
+          },
+        ])
+      );
+      expect(page(reference, 'Client').content).toContain(
+        'Client is a client.\n\n#### Format\n\nDetails.'
+      );
+    });
+  });
+
+  describe('artifact validation', () => {
+    let dir: string;
+
+    beforeAll(async () => {
+      dir = await mkdtemp(path.join(os.tmpdir(), 'go-artifact-'));
+    });
+
+    afterAll(async () => {
+      await rm(dir, { recursive: true, force: true });
+    });
+
+    it('rejects unsupported schema versions', async () => {
+      const file = path.join(dir, 'future.json');
+      await writeFile(file, JSON.stringify({ schemaVersion: 2, packages: [] }));
+      await expect(convertGo(file)).rejects.toThrow(
+        'uses schema version 2, but Mintlify reads schema version 1'
+      );
+    });
+
+    it('rejects malformed artifacts', async () => {
+      const file = path.join(dir, 'invalid.json');
+      await writeFile(
+        file,
+        JSON.stringify({
+          schemaVersion: 1,
+          generator: { name: 'mintlify-go-extractor', version: 'test', go: 'go1.22' },
+          module: 'example.com/acme',
+          goos: 'linux',
+          goarch: 'amd64',
+          commentSyntax: 'markdown',
+          packages: [{ importPath: 'example.com/acme', name: 'acme' }],
+        })
+      );
+      await expect(convertGo(file)).rejects.toThrow(
+        'Invalid Go SDK artifact ' + file + ': packages.0.dir'
+      );
+    });
+  });
+});