@readme/cli 0.0.29 → 0.0.31

package/README.md

@@ -50,6 +50,33 @@ Starts a local dev server so you can preview your docs as you write them. Watche
 npx @readme/cli dev
 ```
 
+## GitHub Action
+
+This repo also publishes itself as a GitHub Action, so a workflow can run `lint`, `oas:validate`, or `oas:sync` directly, pinned to a version, without an `npx` install step on every run:
+
+```yaml
+- uses: readmeio/cli@v1
+  with:
+    readme: oas:sync
+```
+
+The `readme` input is the same command you'd run on the CLI, e.g. `lint`, `oas:validate --dereference`, or `oas:sync`. Each command exits non-zero on a real problem, same as running it locally, and publishes its results as step outputs — `has-errors`, `skipped-count`, `total-errors`, and more (see [`action.yml`](./action.yml) for the full list) — so a later step can check them directly instead of parsing log output:
+
+```yaml
+- name: Sync reference pages from OpenAPI specs
+  id: sync
+  uses: readmeio/cli@v1
+  with:
+    readme: oas:sync
+```
+
+```yaml
+- if: steps.sync.outputs.skipped-count != '0'
+  run: echo "::error::oas:sync skipped a page — see the sync step above."
+```
+
+Note: the first run of a workflow using this Action installs one extra dependency (`@readme/markdown`) behind the scenes before your command runs — this is expected, and only adds a few seconds.
+
 ## Feedback
 
 If something doesn't work right, or if you have suggestions, please [open an issue](https://github.com/readmeio/cli/issues). We're actively building this and want to hear from you.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@readme/cli",
-  "version": "0.0.29",
+  "version": "0.0.31",
   "description": "The ReadMe CLI",
   "type": "module",
   "bin": {
@@ -25,10 +25,11 @@
   ],
   "scripts": {
     "start": "node bin/readme.js",
-    "test": "node --test src/**/*.test.js test/*.test.js"
+    "test": "node --test src/**/*.test.js test/*.test.js",
+    "build:gha": "ncc build src/gha.js -o dist-gha --external @readme/markdown"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "keywords": [
     "readme",
@@ -43,7 +44,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.207",
     "@readme/markdown": "^13.3.0",
-    "@readmeio/git-format": "readmeio/git-format",
+    "@readmeio/git-format": "git+https://github.com/readmeio/git-format.git",
     "ajv": "^8.18.0",
     "chalk": "^5.4.1",
     "cli-spinners": "^3.4.0",
@@ -56,5 +57,8 @@
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "update-notifier": "^7.3.1"
+  },
+  "devDependencies": {
+    "@vercel/ncc": "^0.45.0"
   }
 }

package/src/cli.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { pathToFileURL, fileURLToPath } from 'node:url';
 import { Command } from 'commander';
 import { createRequire } from 'node:module';
 import updateNotifier from 'update-notifier';
@@ -56,7 +56,7 @@ export async function main() {
   }
 
   // Auto-discover and register every command in src/commands/
-  const commandsDir = path.join(path.dirname(new URL(import.meta.url).pathname), 'commands');
+  const commandsDir = path.join(path.dirname(fileURLToPath(import.meta.url)), 'commands');
   const files = fs.readdirSync(commandsDir).filter((f) => f.endsWith('.js') && !f.endsWith('.test.js'));
 
   // Load all modules, then sort by order (default 0)

package/src/commands/import-oas.test.js

@@ -0,0 +1,277 @@
+import { afterEach, test } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { __test__ } from './import.js'
+
+const {
+  sniffOasContent,
+  buildWellKnownOasProbeUrls,
+  probeWellKnownOasPaths,
+  extractOasUrlsFromHtml,
+  extractMintlifyOasCandidates,
+  sitemapUrlsToKnownUrls,
+  extractOasSpecUrlsFromParsed,
+  downloadOasSpecs,
+} = __test__
+
+const originalFetch = globalThis.fetch
+
+afterEach(() => {
+  globalThis.fetch = originalFetch
+})
+
+const JSON_SPEC = JSON.stringify({ openapi: '3.0.0', info: { title: 'T', version: '1' }, paths: {} })
+const YAML_SPEC = 'openapi: 3.0.0\ninfo:\n  title: T\n  version: "1"\npaths: {}\n'
+const HTML_SHELL = '<!DOCTYPE html><html><head><title>Docs</title></head><body>hi</body></html>'
+
+function toArrayBuffer(str) {
+  const buf = Buffer.from(str)
+  return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength)
+}
+
+function mockProbeFetch(routes) {
+  const seen = []
+  globalThis.fetch = async (url) => {
+    const href = String(url)
+    seen.push(href)
+    const entry = routes[href] || routes['*']
+    if (!entry) return { ok: false, status: 404, url: href, arrayBuffer: async () => new ArrayBuffer(0) }
+    return {
+      ok: true,
+      status: 200,
+      url: entry.finalUrl || href,
+      arrayBuffer: async () => toArrayBuffer(entry.body),
+    }
+  }
+  return seen
+}
+
+test('sniffOasContent accepts JSON and YAML specs, rejects HTML and random content', () => {
+  assert.equal(sniffOasContent(JSON_SPEC), true)
+  assert.equal(sniffOasContent(JSON.stringify({ swagger: '2.0', paths: {} })), true)
+  assert.equal(sniffOasContent(YAML_SPEC), true)
+  assert.equal(sniffOasContent('swagger: "2.0"\npaths: {}\n'), true)
+  assert.equal(sniffOasContent("'openapi': 3.1.0\n"), true)
+  assert.equal(sniffOasContent(HTML_SHELL), false)
+  assert.equal(sniffOasContent('  <svg></svg>'), false)
+  assert.equal(sniffOasContent(JSON.stringify({ name: 'pkg', version: '1.0.0' })), false)
+  assert.equal(sniffOasContent(''), false)
+  assert.equal(sniffOasContent('just some prose about openapi stuff'), false)
+})
+
+test('buildWellKnownOasProbeUrls covers both origins and path-kind docs bases without duplicates', () => {
+  const docsBase = { kind: 'path', url: new URL('https://foo.com/docs/') }
+  const urls = buildWellKnownOasProbeUrls(new URL('https://foo.com/docs/'), docsBase, 'https://foo.com')
+  assert(urls.includes('https://foo.com/openapi.json'))
+  assert(urls.includes('https://foo.com/v3/api-docs'))
+  assert(urls.includes('https://foo.com/docs/openapi.yaml'))
+  assert(!urls.includes('https://foo.com/docs/openapi.yml'))
+  assert.equal(new Set(urls).size, urls.length)
+
+  const subdomain = buildWellKnownOasProbeUrls(
+    new URL('https://docs.foo.com/'),
+    { kind: 'subdomain', url: new URL('https://docs.foo.com/') },
+    'https://foo.com',
+  )
+  assert(subdomain.includes('https://docs.foo.com/openapi.json'))
+  assert(subdomain.includes('https://foo.com/openapi.json'))
+})
+
+test('probeWellKnownOasPaths returns zero hits when every path 200s with HTML', async () => {
+  const seen = mockProbeFetch({ '*': { body: HTML_SHELL } })
+  const hits = await probeWellKnownOasPaths(new URL('https://foo.com/'), null, 'https://foo.com')
+  assert.equal(hits.length, 0)
+  assert(seen.length <= 27)
+})
+
+test('probeWellKnownOasPaths returns a hit with prefetched body for a real YAML spec', async () => {
+  mockProbeFetch({ 'https://foo.com/openapi.yaml': { body: YAML_SPEC } })
+  const hits = await probeWellKnownOasPaths(new URL('https://foo.com/'), null, 'https://foo.com')
+  assert.equal(hits.length, 1)
+  assert.equal(hits[0].url, 'https://foo.com/openapi.yaml')
+  assert.equal(hits[0].source, 'probe')
+  assert(Buffer.isBuffer(hits[0].body))
+  assert.equal(hits[0].body.toString('utf8'), YAML_SPEC)
+})
+
+test('probeWellKnownOasPaths skips hits that redirect off the probe origins', async () => {
+  mockProbeFetch({
+    'https://foo.com/openapi.json': { body: JSON_SPEC, finalUrl: 'https://other.example.com/openapi.json' },
+    'https://foo.com/swagger.json': { body: JSON_SPEC },
+  })
+  const hits = await probeWellKnownOasPaths(new URL('https://foo.com/'), null, 'https://foo.com')
+  assert.deepEqual(hits.map((h) => h.url), ['https://foo.com/swagger.json'])
+})
+
+test('extractMintlifyOasCandidates handles string, string[], {source}, and nested nav nodes', () => {
+  const config = {
+    openapi: '/specs/root.json',
+    navigation: {
+      tabs: [
+        {
+          tab: 'API',
+          openapi: ['https://cdn.foo.com/a.yaml', '/specs/b.json'],
+          groups: [{ group: 'Endpoints', openapi: { source: 'specs/c.json' }, pages: ['api/list'] }],
+        },
+      ],
+    },
+  }
+  const items = extractMintlifyOasCandidates(config, 'https://foo.com')
+  const urls = items.map((i) => i.url)
+  assert.deepEqual(urls, [
+    'https://foo.com/specs/root.json',
+    'https://cdn.foo.com/a.yaml',
+    'https://foo.com/specs/b.json',
+    'https://foo.com/specs/c.json',
+  ])
+  assert(items.every((i) => i.source === 'mintlify' && i.text === null))
+})
+
+test('extractMintlifyOasCandidates ignores non-url values and dedupes', () => {
+  const config = {
+    navigation: {
+      anchors: [{ openapi: '/spec.json' }, { openapi: '/spec.json' }, { openapi: { notSource: true } }],
+    },
+  }
+  const items = extractMintlifyOasCandidates(config, 'https://foo.com')
+  assert.deepEqual(items.map((i) => i.url), ['https://foo.com/spec.json'])
+})
+
+test('extractOasUrlsFromHtml finds Swagger UI single url and urls arrays', () => {
+  const single = `<script>SwaggerUIBundle({ dom_id: '#swagger', url: "/openapi.json" })</script>`
+  assert.deepEqual(extractOasUrlsFromHtml(single, 'https://foo.com/reference'), ['https://foo.com/openapi.json'])
+
+  const multi = `<script>SwaggerUI({ urls: [{ url: "https://foo.com/v1.json", name: "v1" }, { url: '/v2.yaml', name: "v2" }] })</script>`
+  assert.deepEqual(extractOasUrlsFromHtml(multi, 'https://foo.com/reference'), [
+    'https://foo.com/v1.json',
+    'https://foo.com/v2.yaml',
+  ])
+})
+
+test('extractOasUrlsFromHtml finds redoc in every quoting variant plus Redoc.init', () => {
+  for (const html of [
+    '<redoc spec-url="/spec.yaml"></redoc>',
+    "<redoc spec-url='/spec.yaml'></redoc>",
+    '<redoc lazy-rendering spec-url=/spec.yaml></redoc>',
+  ]) {
+    assert.deepEqual(extractOasUrlsFromHtml(html, 'https://foo.com/api'), ['https://foo.com/spec.yaml'])
+  }
+  const init = `<script>Redoc.init("https://foo.com/openapi.json", {}, document.getElementById('redoc'))</script>`
+  assert.deepEqual(extractOasUrlsFromHtml(init, 'https://foo.com/api'), ['https://foo.com/openapi.json'])
+})
+
+test('extractOasUrlsFromHtml finds Scalar script tags in both attribute orders', () => {
+  const a = '<script id="api-reference" data-url="/openapi.json"></script>'
+  const b = "<script data-url='/openapi.json' id='api-reference'></script>"
+  assert.deepEqual(extractOasUrlsFromHtml(a, 'https://foo.com/'), ['https://foo.com/openapi.json'])
+  assert.deepEqual(extractOasUrlsFromHtml(b, 'https://foo.com/'), ['https://foo.com/openapi.json'])
+  const noId = '<script data-url="/openapi.json"></script>'
+  assert.deepEqual(extractOasUrlsFromHtml(noId, 'https://foo.com/'), [])
+})
+
+test('extractOasUrlsFromHtml finds Stoplight apiDescriptionUrl and skips marketing pages', () => {
+  const stoplight = '<elements-api apiDescriptionUrl="https://foo.com/api.yaml" router="hash" />'
+  assert.deepEqual(extractOasUrlsFromHtml(stoplight, 'https://foo.com/'), ['https://foo.com/api.yaml'])
+  const marketing = '<html><body><a href="/pricing">Pricing</a><script>analytics.track("url: nope")</script></body></html>'
+  assert.deepEqual(extractOasUrlsFromHtml(marketing, 'https://foo.com/'), [])
+})
+
+test('sitemapUrlsToKnownUrls routes spec-shaped locs to the sink instead of known pages', () => {
+  const sink = []
+  const known = sitemapUrlsToKnownUrls(
+    [
+      'https://foo.com/docs/getting-started',
+      'https://foo.com/openapi.json',
+      'https://foo.com/specs/api.yaml',
+      'https://foo.com/specs/api.yml',
+    ],
+    sink,
+  )
+  assert.deepEqual(known.map((k) => k.url), ['https://foo.com/docs/getting-started'])
+  assert.deepEqual(
+    sink.map((s) => s.url),
+    ['https://foo.com/openapi.json', 'https://foo.com/specs/api.yaml', 'https://foo.com/specs/api.yml'],
+  )
+  assert(sink.every((s) => s.source === 'sitemap'))
+})
+
+test('extractOasSpecUrlsFromParsed captures .yaml links too and prunes emptied sections', () => {
+  const parsed = {
+    sections: [
+      { title: 'Specs', items: [{ text: 'OpenAPI', url: 'https://foo.com/openapi.yaml' }] },
+      {
+        title: 'Guides',
+        items: [
+          { text: 'Intro', url: 'https://foo.com/docs/intro' },
+          { text: 'Spec', url: 'https://foo.com/spec.json' },
+        ],
+      },
+    ],
+  }
+  const captured = extractOasSpecUrlsFromParsed(parsed)
+  assert.deepEqual(captured, [
+    { url: 'https://foo.com/openapi.yaml', text: 'OpenAPI', source: 'llms' },
+    { url: 'https://foo.com/spec.json', text: 'Spec', source: 'llms' },
+  ])
+  assert.equal(parsed.sections.length, 1)
+  assert.deepEqual(parsed.sections[0].items.map((i) => i.url), ['https://foo.com/docs/intro'])
+})
+
+test('downloadOasSpecs writes prefetched bodies without fetching and preserves extensions', async () => {
+  const seen = []
+  globalThis.fetch = async (url) => {
+    seen.push(String(url))
+    return { ok: true, status: 200, url: String(url), arrayBuffer: async () => toArrayBuffer(YAML_SPEC) }
+  }
+  const stagingDir = fs.mkdtempSync(path.join(os.tmpdir(), 'import-oas-test-'))
+  const written = await downloadOasSpecs(
+    [
+      { url: 'https://foo.com/openapi.json', text: null, source: 'probe', body: Buffer.from(JSON_SPEC) },
+      { url: 'https://foo.com/specs/api.yaml', text: null, source: 'llms' },
+    ],
+    stagingDir,
+  )
+  assert.equal(written, 2)
+  assert.deepEqual(seen, ['https://foo.com/specs/api.yaml'])
+  const files = fs.readdirSync(path.join(stagingDir, 'oas')).sort()
+  assert.deepEqual(files, ['api.yaml', 'openapi.json'])
+  assert.equal(fs.readFileSync(path.join(stagingDir, 'oas', 'openapi.json'), 'utf8'), JSON_SPEC)
+  assert.equal(fs.readFileSync(path.join(stagingDir, 'oas', 'api.yaml'), 'utf8'), YAML_SPEC)
+})
+
+test('downloadOasSpecs sniffs an extension for extensionless URLs', async () => {
+  const stagingDir = fs.mkdtempSync(path.join(os.tmpdir(), 'import-oas-test-'))
+  const written = await downloadOasSpecs(
+    [
+      { url: 'https://foo.com/v3/api-docs', text: null, source: 'probe', body: Buffer.from(JSON_SPEC) },
+      { url: 'https://foo.com/spec/latest', text: null, source: 'probe', body: Buffer.from(YAML_SPEC) },
+    ],
+    stagingDir,
+  )
+  assert.equal(written, 2)
+  const files = fs.readdirSync(path.join(stagingDir, 'oas')).sort()
+  assert.deepEqual(files, ['api-docs.json', 'latest.yaml'])
+})
+
+test('downloadOasSpecs skips HTML bodies and suffixes filename collisions', async () => {
+  globalThis.fetch = async (url) => ({
+    ok: true,
+    status: 200,
+    url: String(url),
+    arrayBuffer: async () => toArrayBuffer(HTML_SHELL),
+  })
+  const stagingDir = fs.mkdtempSync(path.join(os.tmpdir(), 'import-oas-test-'))
+  const written = await downloadOasSpecs(
+    [
+      { url: 'https://foo.com/a/openapi.json', text: null, source: 'probe', body: Buffer.from(JSON_SPEC) },
+      { url: 'https://foo.com/b/openapi.json', text: null, source: 'probe', body: Buffer.from(JSON_SPEC) },
+      { url: 'https://foo.com/shell.json', text: null, source: 'html' },
+    ],
+    stagingDir,
+  )
+  assert.equal(written, 2)
+  const files = fs.readdirSync(path.join(stagingDir, 'oas')).sort()
+  assert.deepEqual(files, ['openapi-2.json', 'openapi.json'])
+})

package/src/commands/import.classify.test.js

@@ -0,0 +1,172 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { __test__ } from './import.js'
+
+const {
+  isDiscoverableLink,
+  isAuthChromeUrl,
+  isDocsUnderApiPath,
+  filterUrlPagesTree,
+  urlIsApiReference,
+  urlIsChangelog,
+  reclassifyReferencePages,
+  extractChangelogFromSections,
+  decodeEntities,
+  stripTags,
+} = __test__
+
+test('isDocsUnderApiPath treats /api/docs guides as docs, not reference', () => {
+  assert.equal(isDocsUnderApiPath('https://example.com/api/docs/guides/intro'), true)
+  assert.equal(isDocsUnderApiPath('https://example.com/api/docs/pricing'), true)
+  assert.equal(isDocsUnderApiPath('https://example.com/api/docs'), true)
+  assert.equal(isDocsUnderApiPath('https://example.com/API/DOC/guides'), true)
+  assert.equal(isDocsUnderApiPath('https://example.com/api/docs/api'), false)
+  assert.equal(isDocsUnderApiPath('https://example.com/api/docs/reference'), false)
+  assert.equal(isDocsUnderApiPath('https://example.com/api/docs/api-reference'), false)
+  assert.equal(isDocsUnderApiPath('https://example.com/docs/guides'), false)
+  assert.equal(isDocsUnderApiPath('https://example.com/api/reference/pets'), false)
+  assert.equal(isDocsUnderApiPath('not a url'), false)
+})
+
+test('filterUrlPagesTree keeps matching URL pages and empty parents with survivors', () => {
+  const tree = [
+    { title: 'Guides', url: 'https://example.com/api/docs/guides' },
+    { title: 'Pets', url: 'https://example.com/api/reference/pets' },
+    {
+      title: 'Mixed',
+      pages: [
+        { title: 'Pricing', url: 'https://example.com/api/docs/pricing' },
+        { title: 'Endpoint', url: 'https://example.com/api/reference/create' },
+      ],
+    },
+    { title: 'Empty leftover', pages: [{ title: 'Gone', url: 'https://example.com/api/reference/gone' }] },
+  ]
+
+  const kept = filterUrlPagesTree(tree, isDocsUnderApiPath)
+  assert.deepEqual(
+    kept.map((p) => p.title),
+    ['Guides', 'Mixed'],
+  )
+  assert.deepEqual(
+    kept[1].pages.map((p) => p.title),
+    ['Pricing'],
+  )
+})
+
+test('urlIsApiReference matches api-reference / endpoints segments only', () => {
+  assert.equal(urlIsApiReference('https://example.com/api-reference/pets'), true)
+  assert.equal(urlIsApiReference('https://example.com/api_reference/pets'), true)
+  assert.equal(urlIsApiReference('https://example.com/endpoints/create'), true)
+  assert.equal(urlIsApiReference('https://example.com/endpoint/create'), true)
+  assert.equal(urlIsApiReference('https://example.com/api/docs/guides'), false)
+  assert.equal(urlIsApiReference('https://example.com/docs/api'), false)
+  assert.equal(urlIsApiReference('://bad'), false)
+})
+
+test('urlIsChangelog matches changelog-ish slugs without sweeping release-pipeline', () => {
+  assert.equal(urlIsChangelog('https://example.com/docs/changelog'), true)
+  assert.equal(urlIsChangelog('https://example.com/docs/changelog-javascript-agent'), true)
+  assert.equal(urlIsChangelog('https://example.com/docs/release-notes'), true)
+  assert.equal(urlIsChangelog('https://example.com/docs/whats-new'), true)
+  assert.equal(urlIsChangelog('https://example.com/docs/releases'), true)
+  assert.equal(urlIsChangelog('https://example.com/docs/release-2026-2'), true)
+  assert.equal(urlIsChangelog('https://example.com/docs/release-pipeline'), false)
+  assert.equal(urlIsChangelog('https://example.com/docs/getting-started'), false)
+  assert.equal(urlIsChangelog('://bad'), false)
+})
+
+test('extractChangelogFromSections pulls changelog rows out of llms sections in place', () => {
+  const sections = [
+    {
+      title: 'Guides',
+      items: [
+        { text: 'Intro', url: 'https://example.com/docs/intro' },
+        { text: 'Notes', url: 'https://example.com/docs/changelog', description: 'What shipped' },
+      ],
+    },
+    {
+      title: 'History',
+      items: [{ text: 'v1', url: 'https://example.com/docs/release-notes/v1' }],
+    },
+  ]
+
+  const extracted = extractChangelogFromSections(sections)
+  assert.deepEqual(extracted, [
+    { title: 'Notes', url: 'https://example.com/docs/changelog', description: 'What shipped' },
+    { title: 'v1', url: 'https://example.com/docs/release-notes/v1' },
+  ])
+  assert.deepEqual(sections[0].items.map((i) => i.url), ['https://example.com/docs/intro'])
+  assert.deepEqual(sections[1].items, [])
+})
+
+test('reclassifyReferencePages sweeps api-reference URLs into one category and drops emptied ones', () => {
+  const scraped = {
+    categories: [
+      {
+        title: 'Developers',
+        pages: [
+          { title: 'Guide', url: 'https://example.com/docs/guide' },
+          {
+            title: 'List pets',
+            url: 'https://example.com/api-reference/pets',
+            pages: [{ title: 'Create pet', url: 'https://example.com/endpoints/create' }],
+          },
+        ],
+      },
+      {
+        title: 'Only endpoints',
+        pages: [{ title: 'Delete pet', url: 'https://example.com/endpoints/delete' }],
+      },
+    ],
+  }
+
+  assert.equal(reclassifyReferencePages(scraped), 3)
+  assert.deepEqual(
+    scraped.categories.map((c) => c.title),
+    ['Developers', 'API Reference'],
+  )
+  assert.deepEqual(
+    scraped.categories[0].pages.map((p) => p.title),
+    ['Guide'],
+  )
+  assert.deepEqual(
+    scraped.categories[1].pages.map((p) => p.url),
+    [
+      'https://example.com/api-reference/pets',
+      'https://example.com/endpoints/create',
+      'https://example.com/endpoints/delete',
+    ],
+  )
+})
+
+test('isAuthChromeUrl matches leading login/account routes only', () => {
+  assert.equal(isAuthChromeUrl('https://example.com/auth'), true)
+  assert.equal(isAuthChromeUrl('https://example.com/login/callback'), true)
+  assert.equal(isAuthChromeUrl('https://example.com/sign-in'), true)
+  assert.equal(isAuthChromeUrl('https://example.com/signup'), true)
+  assert.equal(isAuthChromeUrl('https://example.com/oauth2/authorize'), true)
+  assert.equal(isAuthChromeUrl('https://example.com/sso'), true)
+  assert.equal(isAuthChromeUrl('https://example.com/docs/auth'), false)
+  assert.equal(isAuthChromeUrl('https://example.com/authenticate'), false)
+  assert.equal(isAuthChromeUrl('://bad'), false)
+})
+
+test('isDiscoverableLink keeps same-origin doc paths and drops assets, chrome, and off-origin', () => {
+  const base = new URL('https://example.com/docs')
+  assert.equal(isDiscoverableLink('https://example.com/docs/intro', base), true)
+  assert.equal(isDiscoverableLink('https://other.com/docs/intro', base), false)
+  assert.equal(isDiscoverableLink('https://example.com/', base), false)
+  assert.equal(isDiscoverableLink('https://example.com/logo.png', base), false)
+  assert.equal(isDiscoverableLink('https://example.com/_next/static/chunk.js', base), false)
+  assert.equal(isDiscoverableLink('https://example.com/assets/app.js', base), false)
+  assert.equal(isDiscoverableLink('not a url', base), false)
+})
+
+test('decodeEntities and stripTags clean sidebar titles that would otherwise miss category routing', () => {
+  assert.equal(decodeEntities('New Features & Upgrade Changes'), 'New Features & Upgrade Changes')
+  assert.equal(decodeEntities('A & B'), 'A & B')
+  assert.equal(decodeEntities('hex & amp'), 'hex & amp')
+  assert.equal(decodeEntities('plain'), 'plain')
+  assert.equal(stripTags('<span>API\u200B Reference</span>'), 'API Reference')
+  assert.equal(stripTags('Guides &amp; <b>Recipes</b>'), 'Guides & Recipes')
+})