@fullstackdatasolutions/articles 1.2.2 → 1.3.0

package/src/__tests__/linkClassification.test.ts

@@ -0,0 +1,55 @@
+import { isExternalHttpLink, isNonBrowserNavigationLink } from '../linkClassification'
+
+describe('isNonBrowserNavigationLink', () => {
+  it('returns true for mailto: links', () => {
+    expect(isNonBrowserNavigationLink('mailto:hello@example.com')).toBe(true)
+  })
+
+  it('returns true for tel: links', () => {
+    expect(isNonBrowserNavigationLink('tel:+15551234567')).toBe(true)
+  })
+
+  it('returns false for http:// links', () => {
+    expect(isNonBrowserNavigationLink('http://example.com')).toBe(false)
+  })
+
+  it('returns false for https:// links', () => {
+    expect(isNonBrowserNavigationLink('https://example.com')).toBe(false)
+  })
+
+  it('returns false for root-relative links', () => {
+    expect(isNonBrowserNavigationLink('/articles/some-article')).toBe(false)
+  })
+
+  it('returns false for in-page hash anchors', () => {
+    expect(isNonBrowserNavigationLink('#section')).toBe(false)
+  })
+})
+
+describe('isExternalHttpLink', () => {
+  it('returns false for a root-relative link regardless of siteUrl', () => {
+    expect(isExternalHttpLink('/articles/some-article', 'https://example.com')).toBe(false)
+  })
+
+  it('returns false for an in-page hash anchor', () => {
+    expect(isExternalHttpLink('#section')).toBe(false)
+  })
+
+  it('returns true for an http(s) link when no siteUrl is configured', () => {
+    expect(isExternalHttpLink('https://other-site.com')).toBe(true)
+  })
+
+  it('returns false for a same-origin absolute link when siteUrl is configured', () => {
+    expect(isExternalHttpLink('https://example.com/articles/other', 'https://example.com')).toBe(
+      false
+    )
+  })
+
+  it('returns true for a different-origin absolute link when siteUrl is configured', () => {
+    expect(isExternalHttpLink('https://other-site.com/page', 'https://example.com')).toBe(true)
+  })
+
+  it('returns true when siteUrl is malformed and cannot be parsed', () => {
+    expect(isExternalHttpLink('https://example.com', 'not-a-valid-url')).toBe(true)
+  })
+})

package/src/__tests__/markdown.test.ts

@@ -64,7 +64,13 @@ jest.mock('unist-util-visit', () => ({
   },
 }))
 
-import { customRenderer, markdownToHtml, extractToc, getContentSlotBoundaries } from '../markdown'
+import {
+  customRenderer,
+  deriveFaqFromHeadings,
+  markdownToHtml,
+  extractToc,
+  getContentSlotBoundaries,
+} from '../markdown'
 
 // ---------------------------------------------------------------------------
 // customRenderer
@@ -429,3 +435,73 @@ describe('getContentSlotBoundaries', () => {
     expect(boundaries?.paragraphCount).toBe(1)
   })
 })
+
+describe('deriveFaqFromHeadings', () => {
+  it('pairs a question-shaped h2 with the paragraph that follows it', () => {
+    const markdown = [
+      '## What is initiative?',
+      '',
+      'It is the turn order for combat.',
+      'Everyone rolls once.',
+      '',
+      '## How do I roll it?',
+      '',
+      'Roll a d20 and add your modifier.',
+    ].join('\n')
+
+    expect(deriveFaqFromHeadings(markdown)).toEqual([
+      {
+        question: 'What is initiative?',
+        answer: 'It is the turn order for combat. Everyone rolls once.',
+      },
+      { question: 'How do I roll it?', answer: 'Roll a d20 and add your modifier.' },
+    ])
+  })
+
+  it('ignores headings that are not questions, rhetorical questions, and other heading levels', () => {
+    const markdown = [
+      '## Setting the scene',
+      '',
+      'Some prose.',
+      '',
+      '## Sound familiar?',
+      '',
+      'More prose.',
+      '',
+      '### How do I nest?',
+      '',
+      'Nested prose.',
+    ].join('\n')
+
+    expect(deriveFaqFromHeadings(markdown)).toEqual([])
+  })
+
+  it('skips a question heading with no prose under it', () => {
+    const markdown = ['## What is this?', '', '## Why does it matter?', '', 'Because.'].join('\n')
+    expect(deriveFaqFromHeadings(markdown)).toEqual([
+      { question: 'Why does it matter?', answer: 'Because.' },
+    ])
+  })
+
+  it('ignores question headings inside fenced code blocks', () => {
+    const markdown = ['```md', '## What is this?', '', 'Not real prose.', '```'].join('\n')
+    expect(deriveFaqFromHeadings(markdown)).toEqual([])
+  })
+
+  it('requires whitespace after ## and rejects deeper heading levels', () => {
+    expect(deriveFaqFromHeadings(['##What is this?', '', 'Prose.'].join('\n'))).toEqual([])
+    expect(deriveFaqFromHeadings(['### What is this?', '', 'Prose.'].join('\n'))).toEqual([])
+    expect(deriveFaqFromHeadings(['##\tWhat is this?', '', 'Prose.'].join('\n'))).toEqual([
+      { question: 'What is this?', answer: 'Prose.' },
+    ])
+  })
+
+  it('stops collecting at the next heading and strips closing hashes', () => {
+    const markdown = ['## Can I do this? ##', '', 'Yes.', '# New section', '', 'Ignored.'].join(
+      '\n'
+    )
+    expect(deriveFaqFromHeadings(markdown)).toEqual([
+      { question: 'Can I do this?', answer: 'Yes.' },
+    ])
+  })
+})

package/src/__tests__/nextjs.test.ts

@@ -3,10 +3,10 @@
  * Mocks server-articles to isolate the handler logic.
  */
 
-const mockGetArticleMarkdownResponse = jest.fn()
+const mockGetMarkdownTwinResponse = jest.fn()
 
 jest.mock('../server-articles', () => ({
-  getArticleMarkdownResponse: (...args: unknown[]) => mockGetArticleMarkdownResponse(...args),
+  getMarkdownTwinResponse: (...args: unknown[]) => mockGetMarkdownTwinResponse(...args),
 }))
 
 import { createArticleMarkdownHandler } from '../nextjs'
@@ -47,14 +47,16 @@ function makeContext(slugValue: string | string[]): {
   }
 }
 
+const requestHeaders = { get: () => null }
+
 function makeRequest(): NextRequest {
-  return {} as NextRequest
+  return { headers: requestHeaders } as unknown as NextRequest
 }
 
 describe('createArticleMarkdownHandler', () => {
   beforeEach(() => {
     jest.clearAllMocks()
-    mockGetArticleMarkdownResponse.mockResolvedValue(new Response('# Article', { status: 200 }))
+    mockGetMarkdownTwinResponse.mockResolvedValue(new Response('# Article', { status: 200 }))
   })
 
   it('returns an object with a GET handler', () => {
@@ -62,12 +64,14 @@ describe('createArticleMarkdownHandler', () => {
     expect(typeof GET).toBe('function')
   })
 
-  it('calls getArticleMarkdownResponse with joined slug array and config', async () => {
+  it('calls getMarkdownTwinResponse with joined slug array and config', async () => {
     const { GET } = createArticleMarkdownHandler(siteConfig)
     const ctx = makeContext(['category', 'my-article.md'])
     await GET(makeRequest(), ctx)
 
-    expect(mockGetArticleMarkdownResponse).toHaveBeenCalledWith('category/my-article', siteConfig)
+    expect(mockGetMarkdownTwinResponse).toHaveBeenCalledWith('category/my-article', siteConfig, {
+      headers: requestHeaders,
+    })
   })
 
   it('strips trailing .md from a slug array', async () => {
@@ -75,7 +79,9 @@ describe('createArticleMarkdownHandler', () => {
     const ctx = makeContext(['some-article.md'])
     await GET(makeRequest(), ctx)
 
-    expect(mockGetArticleMarkdownResponse).toHaveBeenCalledWith('some-article', siteConfig)
+    expect(mockGetMarkdownTwinResponse).toHaveBeenCalledWith('some-article', siteConfig, {
+      headers: requestHeaders,
+    })
   })
 
   it('handles a plain string slug without .md extension', async () => {
@@ -83,7 +89,9 @@ describe('createArticleMarkdownHandler', () => {
     const ctx = makeContext('plain-slug')
     await GET(makeRequest(), ctx)
 
-    expect(mockGetArticleMarkdownResponse).toHaveBeenCalledWith('plain-slug', siteConfig)
+    expect(mockGetMarkdownTwinResponse).toHaveBeenCalledWith('plain-slug', siteConfig, {
+      headers: requestHeaders,
+    })
   })
 
   it('handles a plain string slug with .md extension - strips it', async () => {
@@ -91,7 +99,9 @@ describe('createArticleMarkdownHandler', () => {
     const ctx = makeContext('plain-slug.md')
     await GET(makeRequest(), ctx)
 
-    expect(mockGetArticleMarkdownResponse).toHaveBeenCalledWith('plain-slug', siteConfig)
+    expect(mockGetMarkdownTwinResponse).toHaveBeenCalledWith('plain-slug', siteConfig, {
+      headers: requestHeaders,
+    })
   })
 
   it('handles undefined slug (missing param) as empty string', async () => {
@@ -101,12 +111,14 @@ describe('createArticleMarkdownHandler', () => {
     }
     await GET(makeRequest(), ctx)
 
-    expect(mockGetArticleMarkdownResponse).toHaveBeenCalledWith('', siteConfig)
+    expect(mockGetMarkdownTwinResponse).toHaveBeenCalledWith('', siteConfig, {
+      headers: requestHeaders,
+    })
   })
 
-  it('returns the response from getArticleMarkdownResponse', async () => {
+  it('returns the response from getMarkdownTwinResponse', async () => {
     const mockResponse = new Response('markdown content', { status: 200 })
-    mockGetArticleMarkdownResponse.mockResolvedValue(mockResponse)
+    mockGetMarkdownTwinResponse.mockResolvedValue(mockResponse)
 
     const { GET } = createArticleMarkdownHandler(siteConfig)
     const ctx = makeContext(['article.md'])
@@ -115,7 +127,7 @@ describe('createArticleMarkdownHandler', () => {
     expect(result).toBe(mockResponse)
   })
 
-  it('passes the config object through to getArticleMarkdownResponse', async () => {
+  it('passes the config object through to getMarkdownTwinResponse', async () => {
     const customConfig: ArticlesConfig = {
       siteUrl: 'https://custom.example.com',
       siteName: 'Custom Site',
@@ -124,7 +136,9 @@ describe('createArticleMarkdownHandler', () => {
     const ctx = makeContext(['test.md'])
     await GET(makeRequest(), ctx)
 
-    expect(mockGetArticleMarkdownResponse).toHaveBeenCalledWith('test', customConfig)
+    expect(mockGetMarkdownTwinResponse).toHaveBeenCalledWith('test', customConfig, {
+      headers: requestHeaders,
+    })
   })
 
   it('handles deeply nested slug array', async () => {
@@ -132,6 +146,8 @@ describe('createArticleMarkdownHandler', () => {
     const ctx = makeContext(['a', 'b', 'c', 'deep-article.md'])
     await GET(makeRequest(), ctx)
 
-    expect(mockGetArticleMarkdownResponse).toHaveBeenCalledWith('a/b/c/deep-article', siteConfig)
+    expect(mockGetMarkdownTwinResponse).toHaveBeenCalledWith('a/b/c/deep-article', siteConfig, {
+      headers: requestHeaders,
+    })
   })
 })

package/src/__tests__/renderMdx.test.tsx

@@ -14,7 +14,18 @@ jest.mock('rehype-slug', () => () => () => {})
 jest.mock('rehype-prism-plus', () => () => () => {})
 jest.mock('remark-gfm', () => () => () => {})
 jest.mock('remark-github-blockquote-alert', () => () => () => {})
+// customRenderer runs the real rehype/hast pipeline, not needed for these
+// unit tests. linkClassification.ts is not mocked - it's dependency-free,
+// and the internal-link-routing tests below rely on its real logic.
 jest.mock('../markdown', () => ({ customRenderer: () => () => {} }))
+jest.mock('next/link', () => ({
+  __esModule: true,
+  default: ({ href, children }: { href: string; children: React.ReactNode }) => (
+    <a href={href} data-testid="next-link">
+      {children}
+    </a>
+  ),
+}))
 
 const originalNodeEnv = process.env.NODE_ENV
 
@@ -203,6 +214,152 @@ describe('renderMdxSource', () => {
     })
   })
 
+  describe('internal link routing', () => {
+    it('routes a root-relative internal link through next/link, not a plain page-reload anchor', async () => {
+      mockEvaluate.mockResolvedValue({
+        default: ({
+          components,
+        }: {
+          components?: Record<string, React.ComponentType<unknown>>
+        }) => {
+          const A = components?.a as React.ComponentType<
+            React.AnchorHTMLAttributes<HTMLAnchorElement>
+          >
+          return A
+            ? React.createElement(A, { href: '/articles/other-article' }, 'Other article')
+            : React.createElement('a', { href: '/articles/other-article' }, 'Other article')
+        },
+      })
+      Object.defineProperty(process.env, 'NODE_ENV', { value: 'production', writable: true })
+
+      const { renderMdxSource } = await import('../renderMdx')
+      const el = await renderMdxSource('[Other article](/articles/other-article)')
+      const { container } = render(el as React.ReactElement)
+
+      const link = container.querySelector('a[href="/articles/other-article"]')
+      expect(link).not.toBeNull()
+      expect(link?.textContent).toBe('Other article')
+      // Confirms next/link (mocked above) actually handled this render,
+      // not a bare intrinsic <a> - this is the assertion that would have
+      // caught the original bug (every in-article link forcing a full
+      // page reload instead of client-side navigation).
+      expect(link?.getAttribute('data-testid')).toBe('next-link')
+    })
+
+    it('leaves an external link as a plain anchor, not routed through next/link', async () => {
+      mockEvaluate.mockResolvedValue({
+        default: ({
+          components,
+        }: {
+          components?: Record<string, React.ComponentType<unknown>>
+        }) => {
+          const A = components?.a as React.ComponentType<
+            React.AnchorHTMLAttributes<HTMLAnchorElement>
+          >
+          return A
+            ? React.createElement(
+                A,
+                {
+                  href: 'https://external.example.com',
+                  target: '_blank',
+                  rel: 'noopener noreferrer',
+                },
+                'External'
+              )
+            : null
+        },
+      })
+      Object.defineProperty(process.env, 'NODE_ENV', { value: 'production', writable: true })
+
+      const { renderMdxSource } = await import('../renderMdx')
+      const el = await renderMdxSource('[External](https://external.example.com)')
+      const { container } = render(el as React.ReactElement)
+
+      const link = container.querySelector('a[href="https://external.example.com"]')
+      expect(link).not.toBeNull()
+      expect(link?.getAttribute('data-testid')).toBeNull()
+      expect(link?.getAttribute('target')).toBe('_blank')
+    })
+
+    it('routes a same-origin absolute link through next/link when siteUrl is configured', async () => {
+      mockEvaluate.mockResolvedValue({
+        default: ({
+          components,
+        }: {
+          components?: Record<string, React.ComponentType<unknown>>
+        }) => {
+          const A = components?.a as React.ComponentType<
+            React.AnchorHTMLAttributes<HTMLAnchorElement>
+          >
+          return A
+            ? React.createElement(A, { href: 'https://example.com/articles/other' }, 'Same origin')
+            : null
+        },
+      })
+      Object.defineProperty(process.env, 'NODE_ENV', { value: 'production', writable: true })
+
+      const { renderMdxSource } = await import('../renderMdx')
+      const el = await renderMdxSource(
+        '[Same origin](https://example.com/articles/other)',
+        undefined,
+        { siteUrl: 'https://example.com', siteName: 'Example' }
+      )
+      const { container } = render(el as React.ReactElement)
+
+      const link = container.querySelector('a[href="https://example.com/articles/other"]')
+      expect(link).not.toBeNull()
+      expect(link?.getAttribute('data-testid')).toBe('next-link')
+    })
+
+    it('leaves an in-page hash anchor as a plain anchor, not routed through next/link', async () => {
+      mockEvaluate.mockResolvedValue({
+        default: ({
+          components,
+        }: {
+          components?: Record<string, React.ComponentType<unknown>>
+        }) => {
+          const A = components?.a as React.ComponentType<
+            React.AnchorHTMLAttributes<HTMLAnchorElement>
+          >
+          return A ? React.createElement(A, { href: '#section' }, 'Jump') : null
+        },
+      })
+      Object.defineProperty(process.env, 'NODE_ENV', { value: 'production', writable: true })
+
+      const { renderMdxSource } = await import('../renderMdx')
+      const el = await renderMdxSource('[Jump](#section)')
+      const { container } = render(el as React.ReactElement)
+
+      const link = container.querySelector('a[href="#section"]')
+      expect(link).not.toBeNull()
+      expect(link?.getAttribute('data-testid')).toBeNull()
+    })
+
+    it('leaves a mailto: link as a plain anchor, not routed through next/link', async () => {
+      mockEvaluate.mockResolvedValue({
+        default: ({
+          components,
+        }: {
+          components?: Record<string, React.ComponentType<unknown>>
+        }) => {
+          const A = components?.a as React.ComponentType<
+            React.AnchorHTMLAttributes<HTMLAnchorElement>
+          >
+          return A ? React.createElement(A, { href: 'mailto:hello@example.com' }, 'Email us') : null
+        },
+      })
+      Object.defineProperty(process.env, 'NODE_ENV', { value: 'production', writable: true })
+
+      const { renderMdxSource } = await import('../renderMdx')
+      const el = await renderMdxSource('[Email us](mailto:hello@example.com)')
+      const { container } = render(el as React.ReactElement)
+
+      const link = container.querySelector('a[href="mailto:hello@example.com"]')
+      expect(link).not.toBeNull()
+      expect(link?.getAttribute('data-testid')).toBeNull()
+    })
+  })
+
   describe('basePath image resolution', () => {
     it('resolves relative img src to absolute path when basePath is provided', async () => {
       mockEvaluate.mockResolvedValue({
@@ -318,7 +475,7 @@ describe('renderMdxSource', () => {
       expect(capturedSrc).not.toBe('/articles/my-article/[object Blob]')
     })
 
-    it('does not inject img component when basePath is not provided', async () => {
+    it('does not inject img component when basePath is not provided, but always injects the link override', async () => {
       let capturedComponents: Record<string, unknown> | undefined
       mockEvaluate.mockResolvedValue({
         default: ({ components }: { components?: Record<string, unknown> }) => {
@@ -329,9 +486,11 @@ describe('renderMdxSource', () => {
       Object.defineProperty(process.env, 'NODE_ENV', { value: 'production', writable: true })
 
       const { renderMdxSource } = await import('../renderMdx')
-      await renderMdxSource('# Test')
+      const el = await renderMdxSource('# Test')
+      render(el as React.ReactElement)
 
-      expect(capturedComponents).toBeUndefined()
+      expect(capturedComponents?.img).toBeUndefined()
+      expect(capturedComponents?.a).toBeInstanceOf(Function)
     })
   })