fix: fence code block regex handles ansi, edge cases, shiki highlighting fixed, tests updated

Author: devdumpling

app/pages/docs/[...path].vue

@@ -318,10 +318,31 @@ const showEmptyState = computed(() => docsData.value?.status !== 'ok')
   @apply text-sm text-fg-muted leading-relaxed mb-5;
 }
 
+/* Inline code in descriptions */
 .docs-content .docs-description code {
   @apply bg-bg-muted px-1.5 py-0.5 rounded text-xs font-mono;
 }
 
+/*
+ * Fenced code blocks in descriptions use a subtle left-border style.
+ *
+ * Design rationale: We use two visual styles for code examples:
+ * 1. Boxed style (bg + border + padding) - for formal @example JSDoc tags
+ *    and function signatures. These are intentional, structured sections.
+ * 2. Left-border style (blockquote-like) - for inline code in descriptions.
+ *    These are illustrative/casual and shouldn't compete with the signature.
+ */
+.docs-content .docs-description .shiki {
+  @apply text-sm pl-4 py-3 my-4 border-l-2 border-border;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.docs-content .docs-description .shiki code {
+  @apply text-sm bg-transparent p-0;
+  white-space: pre-wrap;
+}
+
 /* Deprecation warning */
 .docs-content .docs-deprecated {
   @apply bg-amber-500/10 border border-amber-500/20 rounded-lg p-4 mb-5;
@@ -370,7 +391,7 @@ const showEmptyState = computed(() => docsData.value?.status !== 'ok')
   @apply text-sm text-fg-muted m-0;
 }
 
-/* Example code blocks - now uses Shiki */
+/* Example code blocks from @example JSDoc tags - boxed style (see design rationale above) */
 .docs-content .docs-examples .shiki {
   @apply text-sm bg-bg-muted border border-border/50 p-4 rounded-lg overflow-x-auto mb-3;
 }

server/api/registry/docs/[...pkg].get.ts

@@ -1,6 +1,7 @@
 import type { DocsResponse } from '#shared/types'
 import { fetchNpmPackage } from '#server/utils/npm'
-import { assertValidPackageName, parsePackageParam } from '#shared/utils/npm'
+import { assertValidPackageName } from '#shared/utils/npm'
+import { parsePackageParam } from '#shared/utils/parse-package-param'
 import { generateDocsWithDeno } from '#server/utils/docs'
 
 export default defineCachedEventHandler(

server/utils/docs/format.ts

@@ -7,7 +7,7 @@
  */
 
 import type { DenoDocNode, FunctionParam, TsType } from '#shared/types/deno-doc'
-import { cleanSymbolName } from './text'
+import { cleanSymbolName, stripAnsi } from './text'
 
 /**
  * Generate a TypeScript signature string for a node.
@@ -72,7 +72,8 @@ export function formatParam(param: FunctionParam): string {
 export function formatType(type?: TsType): string {
   if (!type) return ''
 
-  if (type.repr) return type.repr
+  // Strip ANSI codes from repr (deno doc may include terminal colors since it's built for that)
+  if (type.repr) return stripAnsi(type.repr)
 
   if (type.kind === 'keyword' && type.keyword) {
     return type.keyword
@@ -91,5 +92,5 @@ export function formatType(type?: TsType): string {
     return type.union.map(t => formatType(t)).join(' | ')
   }
 
-  return type.repr || 'unknown'
+  return type.repr ? stripAnsi(type.repr) : 'unknown'
 }

server/utils/docs/render.ts

@@ -143,7 +143,7 @@ async function renderMergedSymbol(
   // Description
   if (symbol.jsDoc?.doc) {
     const description = symbol.jsDoc.doc.trim()
-    lines.push(`<div class="docs-description">${renderMarkdown(description, symbolLookup)}</div>`)
+    lines.push(`<div class="docs-description">${await renderMarkdown(description, symbolLookup)}</div>`)
   }
 
   // JSDoc tags

server/utils/docs/text.ts

@@ -6,8 +6,20 @@
  * @module server/utils/docs/text
  */
 
+import { highlightCodeBlock } from '../shiki'
 import type { SymbolLookup } from './types'
 
+/**
+ * Strip ANSI escape codes from text.
+ * Deno doc output may contain terminal color codes that need to be removed.
+ */
+const ESC = String.fromCharCode(27)
+const ANSI_PATTERN = new RegExp(`${ESC}\\[[0-9;]*m`, 'g')
+
+export function stripAnsi(text: string): string {
+  return text.replace(ANSI_PATTERN, '')
+}
+
 /**
  * Escape HTML special characters.
  *
@@ -82,17 +94,38 @@ export function parseJsDocLinks(text: string, symbolLookup: SymbolLookup): strin
 /**
  * Render simple markdown-like formatting.
  * Uses <br> for line breaks to avoid nesting issues with inline elements.
+ * Fenced code blocks (```) are syntax-highlighted with Shiki.
  *
  * @internal Exported for testing
  */
-export function renderMarkdown(text: string, symbolLookup: SymbolLookup): string {
-  let result = parseJsDocLinks(text, symbolLookup)
+export async function renderMarkdown(text: string, symbolLookup: SymbolLookup): Promise<string> {
+  // Extract fenced code blocks FIRST (before any HTML escaping)
+  // Pattern handles:
+  // - Optional whitespace before/after language identifier
+  // - \r\n, \n, or \r line endings
+  const codeBlockData: Array<{ lang: string, code: string }> = []
+  let result = text.replace(/```[ \t]*(\w*)[ \t]*(?:\r\n|\r|\n)([\s\S]*?)(?:\r\n|\r|\n)?```/g, (_, lang, code) => {
+    const index = codeBlockData.length
+    codeBlockData.push({ lang: lang || 'text', code: code.trim() })
+    return `__CODE_BLOCK_${index}__`
+  })
+
+  // Now process the rest (JSDoc links, HTML escaping, etc.)
+  result = parseJsDocLinks(result, symbolLookup)
 
+  // Handle inline code (single backticks) - won't interfere with fenced blocks
   result = result
     .replace(/`([^`]+)`/g, '<code class="docs-inline-code">$1</code>')
     .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
     .replace(/\n\n+/g, '<br><br>')
     .replace(/\n/g, '<br>')
 
+  // Highlight and restore code blocks
+  for (let i = 0; i < codeBlockData.length; i++) {
+    const { lang, code } = codeBlockData[i]!
+    const highlighted = await highlightCodeBlock(code, lang)
+    result = result.replace(`__CODE_BLOCK_${i}__`, highlighted)
+  }
+
   return result
 }

server/utils/shiki.ts

@@ -55,10 +55,12 @@ export async function highlightCodeBlock(code: string, language: string): Promis
 
   if (loadedLangs.includes(language as never)) {
     try {
-      const html = shiki.codeToHtml(code, {
+      let html = shiki.codeToHtml(code, {
         lang: language,
         theme: 'github-dark',
       })
+      // Remove inline style from <pre> tag so CSS can control appearance
+      html = html.replace(/<pre([^>]*)\s+style="[^"]*"/, '<pre$1')
       // Shiki doesn't encode > in text content (e.g., arrow functions =>)
       // We need to encode them for HTML validation
       return escapeRawGt(html)

shared/utils/npm.ts

@@ -1,10 +1,6 @@
 import { createError } from 'h3'
 import validatePackageName from 'validate-npm-package-name'
 
-// Re-export from separate file (avoids h3 dependency for unit tests)
-export { parsePackageParam } from './parse-package-param'
-export type { ParsedPackageParams } from './parse-package-param'
-
 /**
  * Validate an npm package name and throw an HTTP error if invalid.
  * Uses validate-npm-package-name to check against npm naming rules.

test/unit/docs-text.spec.ts

@@ -1,7 +1,42 @@
 import { describe, expect, it } from 'vitest'
-import { escapeHtml, parseJsDocLinks, renderMarkdown } from '../../server/utils/docs/text'
+import { escapeHtml, parseJsDocLinks, renderMarkdown, stripAnsi } from '../../server/utils/docs/text'
 import type { SymbolLookup } from '../../server/utils/docs/types'
 
+describe('stripAnsi', () => {
+  it('should strip basic color codes', () => {
+    const ESC = String.fromCharCode(27)
+    const input = `${ESC}[0m${ESC}[38;5;12mhello${ESC}[0m`
+    expect(stripAnsi(input)).toBe('hello')
+  })
+
+  it('should strip multiple ANSI codes', () => {
+    const ESC = String.fromCharCode(27)
+    const input = `${ESC}[31mred${ESC}[0m and ${ESC}[32mgreen${ESC}[0m`
+    expect(stripAnsi(input)).toBe('red and green')
+  })
+
+  it('should handle text without ANSI codes', () => {
+    expect(stripAnsi('plain text')).toBe('plain text')
+  })
+
+  it('should handle empty string', () => {
+    expect(stripAnsi('')).toBe('')
+  })
+
+  it('should strip 256-color codes', () => {
+    const ESC = String.fromCharCode(27)
+    const input = `${ESC}[38;5;196mtext${ESC}[0m`
+    expect(stripAnsi(input)).toBe('text')
+  })
+
+  it('should handle type predicates from deno_doc', () => {
+    // Real example: "object is ReactElement<P>" with ANSI codes
+    const ESC = String.fromCharCode(27)
+    const input = `object is ReactElement${ESC}[0m${ESC}[38;5;12m<${ESC}[0mP${ESC}[38;5;12m>${ESC}[0m`
+    expect(stripAnsi(input)).toBe('object is ReactElement<P>')
+  })
+})
+
 describe('escapeHtml', () => {
   it('should escape < and >', () => {
     expect(escapeHtml('<script>')).toBe('&lt;script&gt;')
@@ -89,55 +124,127 @@ describe('parseJsDocLinks', () => {
 describe('renderMarkdown', () => {
   const emptyLookup: SymbolLookup = new Map()
 
-  it('should convert inline code', () => {
-    const result = renderMarkdown('Use `foo()` here', emptyLookup)
+  it('should convert inline code', async () => {
+    const result = await renderMarkdown('Use `foo()` here', emptyLookup)
     expect(result).toContain('<code class="docs-inline-code">foo()</code>')
   })
 
-  it('should escape HTML inside inline code', () => {
-    const result = renderMarkdown('Use `Array<T>` here', emptyLookup)
+  it('should escape HTML inside inline code', async () => {
+    const result = await renderMarkdown('Use `Array<T>` here', emptyLookup)
     expect(result).toContain('&lt;T&gt;')
     expect(result).not.toContain('<T>')
   })
 
-  it('should convert bold text', () => {
-    const result = renderMarkdown('This is **important**', emptyLookup)
+  it('should convert bold text', async () => {
+    const result = await renderMarkdown('This is **important**', emptyLookup)
     expect(result).toContain('<strong>important</strong>')
   })
 
-  it('should convert single newlines to <br>', () => {
-    const result = renderMarkdown('line 1\nline 2', emptyLookup)
+  it('should convert single newlines to <br>', async () => {
+    const result = await renderMarkdown('line 1\nline 2', emptyLookup)
     expect(result).toBe('line 1<br>line 2')
   })
 
-  it('should convert double newlines to <br><br>', () => {
-    const result = renderMarkdown('paragraph 1\n\nparagraph 2', emptyLookup)
+  it('should convert double newlines to <br><br>', async () => {
+    const result = await renderMarkdown('paragraph 1\n\nparagraph 2', emptyLookup)
     expect(result).toBe('paragraph 1<br><br>paragraph 2')
   })
 
-  it('should handle multiple formatting in same text', () => {
-    const result = renderMarkdown('Use `foo()` for **important** tasks', emptyLookup)
+  it('should handle multiple formatting in same text', async () => {
+    const result = await renderMarkdown('Use `foo()` for **important** tasks', emptyLookup)
     expect(result).toContain('<code class="docs-inline-code">foo()</code>')
     expect(result).toContain('<strong>important</strong>')
   })
 
-  it('should process {@link} tags', () => {
+  it('should process {@link} tags', async () => {
     const lookup: SymbolLookup = new Map([['MyFunc', 'function-MyFunc']])
-    const result = renderMarkdown('See {@link MyFunc} for details', lookup)
+    const result = await renderMarkdown('See {@link MyFunc} for details', lookup)
     expect(result).toContain('href="#function-MyFunc"')
   })
 
-  it('should escape HTML in regular text', () => {
-    const result = renderMarkdown('Returns <T> or null', emptyLookup)
+  it('should escape HTML in regular text', async () => {
+    const result = await renderMarkdown('Returns <T> or null', emptyLookup)
     expect(result).toContain('&lt;T&gt;')
   })
 
-  it('should handle empty string', () => {
-    expect(renderMarkdown('', emptyLookup)).toBe('')
+  it('should handle empty string', async () => {
+    expect(await renderMarkdown('', emptyLookup)).toBe('')
   })
 
-  it('should handle text with only whitespace', () => {
-    const result = renderMarkdown('  \n  ', emptyLookup)
+  it('should handle text with only whitespace', async () => {
+    const result = await renderMarkdown('  \n  ', emptyLookup)
     expect(result).toBe('  <br>  ')
   })
+
+  it('should syntax highlight fenced code blocks with Shiki', async () => {
+    const input = '```ts\nconst x = 1;\n```'
+    const result = await renderMarkdown(input, emptyLookup)
+    // Shiki outputs use class="shiki" and have syntax highlighting spans
+    expect(result).toContain('shiki')
+    expect(result).toContain('const')
+    expect(result).not.toContain('```')
+  })
+
+  it('should handle fenced code blocks with CRLF line endings', async () => {
+    const input = '```ts\r\nconst x = 1;\r\n```'
+    const result = await renderMarkdown(input, emptyLookup)
+    expect(result).toContain('shiki')
+    expect(result).toContain('const')
+    expect(result).not.toContain('```')
+  })
+
+  it('should handle fenced code blocks with CR line endings', async () => {
+    const input = '```ts\rconst x = 1;\r```'
+    const result = await renderMarkdown(input, emptyLookup)
+    expect(result).toContain('shiki')
+    expect(result).toContain('const')
+    expect(result).not.toContain('```')
+  })
+
+  it('should handle fenced code blocks without language', async () => {
+    const input = '```\nconst x = 1;\n```'
+    const result = await renderMarkdown(input, emptyLookup)
+    // Falls back to plain code block for unknown language
+    expect(result).toContain('<pre>')
+    expect(result).toContain('const x = 1;')
+  })
+
+  it('should handle fenced code blocks with trailing whitespace after language', async () => {
+    const input = '```ts  \nconst x = 1;\n```'
+    const result = await renderMarkdown(input, emptyLookup)
+    expect(result).toContain('shiki')
+    expect(result).toContain('const')
+  })
+
+  it('should handle fenced code blocks with space before language', async () => {
+    const input = '``` js\nconst x = 1;\n```'
+    const result = await renderMarkdown(input, emptyLookup)
+    expect(result).toContain('shiki')
+    expect(result).toContain('const')
+    expect(result).not.toContain('```')
+  })
+
+  it('should escape HTML inside fenced code blocks', async () => {
+    const input = '```ts\nconst arr: Array<string> = [];\n```'
+    const result = await renderMarkdown(input, emptyLookup)
+    // Shiki escapes < as &#x3C; (hex entity)
+    expect(result).toContain('&#x3C;')
+    // The raw < character shouldn't appear outside of HTML tags
+    expect(result).not.toMatch(/<string>/)
+  })
+
+  it('should handle multiple fenced code blocks', async () => {
+    const input = '```ts\nconst a = 1\n```\n\nSome text\n\n```js\nconst b = 2\n```'
+    const result = await renderMarkdown(input, emptyLookup)
+    expect(result).toContain('Some text')
+    // Both code blocks should be highlighted
+    expect((result.match(/shiki/g) || []).length).toBe(2)
+  })
+
+  it('should not confuse inline code with fenced code blocks', async () => {
+    const input = 'Use `code` inline and:\n```ts\nblock code\n```'
+    const result = await renderMarkdown(input, emptyLookup)
+    expect(result).toContain('<code class="docs-inline-code">code</code>')
+    expect(result).toContain('shiki')
+  })
 })