@fullstackdatasolutions/articles 1.2.3 → 1.3.1

package/src/__tests__/server-articles.test.ts

@@ -1,7 +1,13 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import {
+  buildMarkdownTwinHeader,
   categoryToSlug,
+  getAuthorMarkdown,
+  getCategoryMarkdown,
+  getMarkdownTwinResponse,
+  getSeriesMarkdown,
+  matchAiCrawler,
   getAdjacentArticles,
   getAiRobotsTxtRules,
   getAllArticles,
@@ -26,6 +32,7 @@ import {
   searchArticles,
 } from '../server-articles'
 import type { ArticlesConfig } from '../articlesConfig'
+import type { Article } from '../articleTypes'
 import { setArticlesErrorHandler } from '../errorReporting'
 import { markdownToHtml } from '../markdown'
 
@@ -34,6 +41,13 @@ jest.mock('node:fs')
 jest.mock('../markdown', () => ({
   markdownToHtml: jest.fn(async () => '<p>content</p>'),
   extractToc: jest.fn(async () => []),
+  // Real derivation logic is covered in markdown.test.ts; markdown.ts's
+  // unified deps are ESM-only, so this suite only asserts the wiring.
+  deriveFaqFromHeadings: jest.fn((markdown: string) =>
+    markdown.includes('## What is initiative?')
+      ? [{ question: 'What is initiative?', answer: 'Turn order for combat.' }]
+      : []
+  ),
 }))
 jest.mock('reading-time', () => () => ({ text: '2 min read', words: 42 }))
 
@@ -171,6 +185,63 @@ describe('getArticleMetadata - frontmatter parsing', () => {
     expect(article!.faq![0]).toEqual({ question: 'What is this?', answer: 'A test.' })
   })
 
+  it('parses answer, about, and citation from frontmatter', async () => {
+    setupArticleMock(
+      [
+        'answer: Roll a d20 and add your modifier.\n',
+        'about:\n  - name: Pathfinder\n    sameAs: https://www.wikidata.org/wiki/Q1194077\n  - Combat\n',
+        'citation:\n  - name: Core Rulebook\n    url: https://example.com/crb\n  - Errata\n',
+      ].join('')
+    )
+    const article = await getArticleMetadata('test-slug')
+    expect(article!.answer).toBe('Roll a d20 and add your modifier.')
+    expect(article!.about).toEqual([
+      { name: 'Pathfinder', sameAs: 'https://www.wikidata.org/wiki/Q1194077' },
+      { name: 'Combat' },
+    ])
+    expect(article!.citation).toEqual([
+      { name: 'Core Rulebook', url: 'https://example.com/crb' },
+      { name: 'Errata' },
+    ])
+  })
+
+  it('drops malformed and blank about/citation entries', async () => {
+    setupArticleMock('about:\n  - ""\n  - 42\n  - name: ""\ncitation: not-a-list\n')
+    const article = await getArticleMetadata('test-slug')
+    expect(article!.about).toBeUndefined()
+    expect(article!.citation).toBeUndefined()
+  })
+
+  it('derives faq from question headings only when deriveFaqFromHeadings is enabled', async () => {
+    const body = ['## What is initiative?', '', 'Turn order for combat.'].join('\n')
+    const config: ArticlesConfig = {
+      siteUrl: 'https://example.com',
+      siteName: 'Example',
+      deriveFaqFromHeadings: true,
+    }
+
+    setupArticleMock('', body)
+    expect((await getArticleMetadata('test-slug'))!.faq).toBeUndefined()
+
+    setupArticleMock('', body)
+    expect((await getArticleMetadata('test-slug', config))!.faq).toEqual([
+      { question: 'What is initiative?', answer: 'Turn order for combat.' },
+    ])
+  })
+
+  it('prefers explicit faq frontmatter over derived headings', async () => {
+    setupArticleMock(
+      'faq:\n  - question: "Declared?"\n    answer: "Yes."\n',
+      ['## What is initiative?', '', 'Turn order for combat.'].join('\n')
+    )
+    const article = await getArticleMetadata('test-slug', {
+      siteUrl: 'https://example.com',
+      siteName: 'Example',
+      deriveFaqFromHeadings: true,
+    })
+    expect(article!.faq).toEqual([{ question: 'Declared?', answer: 'Yes.' }])
+  })
+
   it('parses howTo from frontmatter', async () => {
     setupArticleMock(
       'howTo:\n  - name: "Step 1"\n    text: "Do this."\n  - name: "Step 2"\n    text: "Then that."\n'
@@ -924,7 +995,20 @@ describe('AI markdown helpers', () => {
     })
     expect(allowed.status).toBe(200)
     expect(allowed.headers.get('Content-Type')).toBe('text/markdown; charset=utf-8')
-    await expect(allowed.text()).resolves.toBe('\n# Allowed')
+    await expect(allowed.text()).resolves.toBe(
+      [
+        '> Excerpt for allowed',
+        '',
+        'Source: https://example.com/articles/allowed',
+        'Published: 2025-01-01',
+        'Author: Test Author',
+        'Site: Example',
+        '',
+        '---',
+        '',
+        '# Allowed',
+      ].join('\n')
+    )
 
     const blocked = await getArticleMarkdownResponse('blocked', {
       siteUrl: 'https://example.com',
@@ -933,6 +1017,27 @@ describe('AI markdown helpers', () => {
     expect(blocked.status).toBe(404)
   })
 
+  it('links the markdown twin back to its HTML article, not to itself', async () => {
+    setupArticleTreeMock([
+      {
+        slug: 'allowed',
+        frontmatter: 'date: 2025-01-01\naiCrawl: true\n',
+        body: '# Allowed',
+      },
+    ])
+
+    const response = await getArticleMarkdownResponse('allowed', {
+      siteUrl: 'https://example.com/',
+      siteName: 'Example',
+    })
+
+    expect(response.headers.get('Link')).toBe(
+      '<https://example.com/articles/allowed>; rel="canonical"'
+    )
+    expect(response.headers.get('Link')).not.toContain('.md')
+    expect(response.headers.get('Link')).not.toContain('alternate')
+  })
+
   it('generates robots rules for AI crawlers and blocked articles only', async () => {
     setupArticleTreeMock([
       { slug: 'allowed', frontmatter: 'date: 2025-01-01\naiCrawl: true\n' },
@@ -944,6 +1049,82 @@ describe('AI markdown helpers', () => {
     expect(rules).toContain('Disallow: /articles/blocked')
     expect(rules).not.toContain('Disallow: /articles/allowed')
   })
+
+  it('opts every article in when aiCrawlDefault is true, without overriding explicit false', async () => {
+    setupArticleTreeMock([
+      { slug: 'inherits', frontmatter: 'date: 2025-01-01\n' },
+      { slug: 'opted-out', frontmatter: 'date: 2025-01-01\naiCrawl: false\n' },
+    ])
+    const config: ArticlesConfig = {
+      siteUrl: 'https://example.com',
+      siteName: 'Example',
+      aiCrawlDefault: true,
+    }
+
+    expect((await getArticleMetadata('inherits', config))!.aiCrawl).toBe(true)
+    expect((await getArticleMetadata('opted-out', config))!.aiCrawl).toBe(false)
+    await expect(getArticleMarkdown('inherits', config)).resolves.toContain('Article body content.')
+    await expect(getArticleMarkdown('opted-out', config)).resolves.toBeNull()
+
+    const rules = await getAiRobotsTxtRules(config)
+    expect(rules).toContain('Disallow: /articles/opted-out')
+    expect(rules).not.toContain('Disallow: /articles/inherits')
+  })
+
+  it('keeps a distinct title as its own H1 and includes lastmod when present', () => {
+    const header = buildMarkdownTwinHeader(
+      {
+        slug: 'guides/first-session',
+        title: 'Running Your First Session',
+        excerpt: 'A short summary.',
+        date: '2025-01-01',
+        lastmod: '2025-06-01',
+        author: 'Test Author',
+      } as Article,
+      { siteUrl: 'https://example.com/', siteName: 'Example' },
+      'Body text that does not repeat the title.'
+    )
+
+    expect(header).toBe(
+      [
+        '# Running Your First Session',
+        '',
+        '> A short summary.',
+        '',
+        'Source: https://example.com/articles/guides/first-session',
+        'Published: 2025-01-01',
+        'Updated: 2025-06-01',
+        'Author: Test Author',
+        'Site: Example',
+        '',
+        '---',
+        '',
+        '',
+      ].join('\n')
+    )
+  })
+
+  it('omits the author line when showAuthor is false', () => {
+    const header = buildMarkdownTwinHeader(
+      { slug: 'a', title: 'A', excerpt: '', author: 'Test Author' } as Article,
+      { siteUrl: 'https://example.com', siteName: 'Example', showAuthor: false },
+      'Body.'
+    )
+    expect(header).not.toContain('Author:')
+  })
+
+  it('serves the bare body when markdownTwinHeader is false', async () => {
+    setupArticleTreeMock([
+      { slug: 'allowed', frontmatter: 'date: 2025-01-01\naiCrawl: true\n', body: '# Allowed' },
+    ])
+
+    const response = await getArticleMarkdownResponse('allowed', {
+      siteUrl: 'https://example.com',
+      siteName: 'Example',
+      markdownTwinHeader: false,
+    })
+    await expect(response.text()).resolves.toBe('\n# Allowed')
+  })
 })
 
 describe('article path helpers', () => {
@@ -1161,3 +1342,255 @@ describe('getRelatedContent', () => {
     expect(result.articles.map((a) => a.slug)).toEqual(['two'])
   })
 })
+
+describe('markdown twins for listing surfaces', () => {
+  const config: ArticlesConfig = {
+    siteUrl: 'https://example.com/',
+    siteName: 'Example',
+    aiCrawlDefault: true,
+    categoryDescriptions: { campaigns: { short: 'Short.', long: 'The long description.' } },
+    authors: {
+      'jane-doe': {
+        name: 'Jane Doe',
+        slug: 'jane-doe',
+        bio: 'Writes about campaigns.',
+        promise: 'Helping organizers run better campaigns.',
+        servesWho: ['Organizers'],
+        knowsAbout: ['Campaigns'],
+        credentials: ['10 years in the field'],
+        proof: [{ claim: '500 doors knocked', url: 'https://example.com/proof' }],
+        originStory: [{ heading: 'How I started', paragraphs: ['A paragraph.'] }],
+      },
+    },
+  }
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('builds a category twin with description, source lines, and .md links', async () => {
+    setupArticleTreeMock([{ slug: 'one', frontmatter: 'date: 2025-01-01\ntags: [campaigns]\n' }])
+    const markdown = await getCategoryMarkdown('campaigns', config)
+    expect(markdown).toContain('# campaigns')
+    expect(markdown).toContain('The long description.')
+    expect(markdown).toContain('Source: https://example.com')
+    expect(markdown).toContain('Site: Example')
+    expect(markdown).toContain('- [one](https://example.com/articles/one.md): Excerpt for one')
+  })
+
+  it('returns null for a category with no articles', async () => {
+    setupArticleTreeMock([{ slug: 'one', frontmatter: 'date: 2025-01-01\ntags: [other]\n' }])
+    await expect(getCategoryMarkdown('campaigns', config)).resolves.toBeNull()
+  })
+
+  it('omits articles that are not aiCrawl-eligible', async () => {
+    setupArticleTreeMock([
+      { slug: 'shown', frontmatter: 'date: 2025-01-01\ntags: [campaigns]\n' },
+      { slug: 'hidden', frontmatter: 'date: 2025-01-01\ntags: [campaigns]\naiCrawl: false\n' },
+    ])
+    const markdown = await getCategoryMarkdown('campaigns', config)
+    expect(markdown).toContain('shown')
+    expect(markdown).not.toContain('hidden')
+  })
+
+  it('builds an author twin carrying bio, promise, credentials, proof, and background', async () => {
+    setupArticleTreeMock([
+      { slug: 'one', frontmatter: 'date: 2025-01-01\nauthors:\n  - jane-doe\n' },
+    ])
+    const markdown = await getAuthorMarkdown('jane-doe', config)
+    expect(markdown).toContain('# Jane Doe')
+    expect(markdown).toContain('Helping organizers run better campaigns.')
+    expect(markdown).toContain('Writes about campaigns.')
+    expect(markdown).toContain('Writes for: Organizers')
+    expect(markdown).toContain('Writes about: Campaigns')
+    expect(markdown).toContain('## Stated experience')
+    expect(markdown).toContain('- 10 years in the field')
+    expect(markdown).toContain('- [500 doors knocked](https://example.com/proof)')
+    expect(markdown).toContain('### How I started')
+  })
+
+  it('returns null for an unknown author', async () => {
+    setupArticleTreeMock([{ slug: 'one', frontmatter: 'date: 2025-01-01\n' }])
+    await expect(getAuthorMarkdown('nobody', config)).resolves.toBeNull()
+  })
+
+  it('builds a series twin and returns null for an empty series', async () => {
+    setupArticleTreeMock([
+      {
+        slug: 'one',
+        frontmatter: 'date: 2025-01-01\nseries: New GM Path\nseriesSlug: new-gm\nseriesOrder: 1\n',
+      },
+    ])
+    const markdown = await getSeriesMarkdown('new-gm', config)
+    expect(markdown).toContain('# New GM Path')
+    expect(markdown).toContain('- [one](https://example.com/articles/one.md)')
+    await expect(getSeriesMarkdown('missing', config)).resolves.toBeNull()
+  })
+
+  it('renders a placeholder when every article in a listing is blocked', async () => {
+    setupArticleTreeMock([
+      { slug: 'one', frontmatter: 'date: 2025-01-01\ntags: [campaigns]\naiCrawl: false\n' },
+    ])
+    expect(await getCategoryMarkdown('campaigns', config)).toContain('_No articles available._')
+  })
+})
+
+describe('getMarkdownTwinResponse', () => {
+  const config: ArticlesConfig = {
+    siteUrl: 'https://example.com',
+    siteName: 'Example',
+    aiCrawlDefault: true,
+  }
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('dispatches category, author, and series prefixes to the listing twins', async () => {
+    setupArticleTreeMock([{ slug: 'one', frontmatter: 'date: 2025-01-01\ntags: [campaigns]\n' }])
+    const response = await getMarkdownTwinResponse('category/campaigns', config)
+    expect(response.status).toBe(200)
+    expect(response.headers.get('Content-Type')).toBe('text/markdown; charset=utf-8')
+    await expect(response.text()).resolves.toContain('# campaigns')
+  })
+
+  it('404s a listing path that resolves to nothing', async () => {
+    setupArticleTreeMock([{ slug: 'one', frontmatter: 'date: 2025-01-01\n' }])
+    const response = await getMarkdownTwinResponse('category/missing', config)
+    expect(response.status).toBe(404)
+  })
+
+  it('falls through to the article handler for a non-listing slug', async () => {
+    setupArticleTreeMock([{ slug: 'category', frontmatter: 'date: 2025-01-01\n', body: '# Body' }])
+    const response = await getMarkdownTwinResponse('category', config)
+    expect(response.status).toBe(200)
+    await expect(response.text()).resolves.toContain('# Body')
+  })
+})
+
+describe('AI crawl telemetry', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('matches known crawlers case-insensitively and returns null otherwise', () => {
+    expect(matchAiCrawler('Mozilla/5.0 (compatible; GPTBot/1.0)')).toBe('GPTBot')
+    expect(matchAiCrawler('claudebot/1.0')).toBe('ClaudeBot')
+    expect(matchAiCrawler('Mozilla/5.0 Chrome/120')).toBeNull()
+    expect(matchAiCrawler('')).toBeNull()
+  })
+
+  it('reports the crawler, slug, and raw user agent on a twin fetch', async () => {
+    const onAiCrawl = jest.fn()
+    setupArticleTreeMock([{ slug: 'one', frontmatter: 'date: 2025-01-01\naiCrawl: true\n' }])
+
+    await getMarkdownTwinResponse(
+      'one',
+      { siteUrl: 'https://example.com', siteName: 'Example', onAiCrawl },
+      { headers: { get: () => 'Mozilla/5.0 (compatible; PerplexityBot/1.0)' } }
+    )
+
+    expect(onAiCrawl).toHaveBeenCalledWith({
+      slug: 'one',
+      crawler: 'PerplexityBot',
+      userAgent: 'Mozilla/5.0 (compatible; PerplexityBot/1.0)',
+    })
+  })
+
+  it('reports unknown for an unrecognized agent and an absent header', async () => {
+    const onAiCrawl = jest.fn()
+    setupArticleTreeMock([{ slug: 'one', frontmatter: 'date: 2025-01-01\naiCrawl: true\n' }])
+    await getMarkdownTwinResponse('one', {
+      siteUrl: 'https://example.com',
+      siteName: 'Example',
+      onAiCrawl,
+    })
+    expect(onAiCrawl).toHaveBeenCalledWith({ slug: 'one', crawler: 'unknown', userAgent: '' })
+  })
+
+  it('does not let a throwing handler break the response', async () => {
+    const reported: string[] = []
+    setArticlesErrorHandler((report) => reported.push(report.code))
+    setupArticleTreeMock([{ slug: 'one', frontmatter: 'date: 2025-01-01\naiCrawl: true\n' }])
+
+    const response = await getMarkdownTwinResponse('one', {
+      siteUrl: 'https://example.com',
+      siteName: 'Example',
+      onAiCrawl: () => {
+        throw new Error('telemetry down')
+      },
+    })
+
+    expect(response.status).toBe(200)
+    expect(reported).toContain('ai-crawl-handler-failed')
+    setArticlesErrorHandler(() => undefined)
+  })
+
+  it('fires for listing twins too', async () => {
+    const onAiCrawl = jest.fn()
+    setupArticleTreeMock([
+      { slug: 'one', frontmatter: 'date: 2025-01-01\ntags: [campaigns]\naiCrawl: true\n' },
+    ])
+    await getMarkdownTwinResponse(
+      'category/campaigns',
+      { siteUrl: 'https://example.com', siteName: 'Example', onAiCrawl },
+      { headers: { get: () => 'CCBot/2.0' } }
+    )
+    expect(onAiCrawl).toHaveBeenCalledWith(
+      expect.objectContaining({ slug: 'category/campaigns', crawler: 'CCBot' })
+    )
+  })
+})
+
+describe('lastmod fallback and entity registry', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('leaves lastmod unset by default and honors explicit frontmatter', async () => {
+    setupArticleMock('date: 2025-01-01\n')
+    expect((await getArticleMetadata('test-slug'))!.lastmod).toBeUndefined()
+
+    setupArticleMock('date: 2025-01-01\nlastmod: 2025-06-01\n')
+    expect((await getArticleMetadata('test-slug'))!.lastmod).toBe('2025-06-01')
+  })
+
+  it('reads file mtime when lastmodFallback is fileMtime', async () => {
+    setupArticleMock('date: 2025-01-01\n')
+    mockedFs.statSync.mockReturnValue({ mtime: new Date('2026-03-04T00:00:00Z') } as fs.Stats)
+    const article = await getArticleMetadata('test-slug', {
+      siteUrl: 'https://example.com',
+      siteName: 'Example',
+      lastmodFallback: 'fileMtime',
+    })
+    expect(article!.lastmod).toBe('2026-03-04')
+  })
+
+  it('falls back to the publish date when statSync throws', async () => {
+    setupArticleMock('date: 2025-01-01\n')
+    mockedFs.statSync.mockImplementation(() => {
+      throw new Error('no such file')
+    })
+    const article = await getArticleMetadata('test-slug', {
+      siteUrl: 'https://example.com',
+      siteName: 'Example',
+      lastmodFallback: 'fileMtime',
+    })
+    expect(article!.lastmod).toBe('2025-01-01')
+  })
+
+  it('resolves about strings through config.entities', async () => {
+    setupArticleMock('about:\n  - pathfinder\n  - unregistered\n')
+    const article = await getArticleMetadata('test-slug', {
+      siteUrl: 'https://example.com',
+      siteName: 'Example',
+      entities: {
+        pathfinder: { name: 'Pathfinder', sameAs: 'https://www.wikidata.org/wiki/Q1194077' },
+      },
+    })
+    expect(article!.about).toEqual([
+      { name: 'Pathfinder', sameAs: 'https://www.wikidata.org/wiki/Q1194077' },
+      { name: 'unregistered' },
+    ])
+  })
+})

package/src/__tests__/validateArticles.test.ts

@@ -279,16 +279,177 @@ describe('validateArticles', () => {
       )
     })
 
-    it('warns when searchTitle exceeds the recommended length', () => {
-      const result = validateArticles([makeArticle({ searchTitle: 'x'.repeat(61) })], baseConfig)
-      expect(result.warnings).toEqual(
-        expect.arrayContaining([expect.objectContaining({ code: 'search-title-too-long' })])
+    it('warns on the rendered title length, including the siteName suffix', () => {
+      // 45-char title is fine alone but not once ' | Example' is appended
+      // under the default template - the rendered string is what is measured.
+      const codes = validateArticles(
+        [makeArticle({ title: 'x'.repeat(55) })],
+        baseConfig
+      ).warnings.map((i) => i.code)
+      expect(codes).toContain('effective-title-too-long')
+    })
+
+    it('warns even when searchTitle is unset - the common case', () => {
+      const codes = validateArticles(
+        [makeArticle({ title: 'y'.repeat(80), searchTitle: undefined })],
+        baseConfig
+      ).warnings.map((i) => i.code)
+      expect(codes).toContain('effective-title-too-long')
+    })
+
+    it('measures searchTitle when it overrides the title', () => {
+      const long = validateArticles(
+        [makeArticle({ title: 'Short', searchTitle: 'z'.repeat(70) })],
+        baseConfig
+      ).warnings.map((i) => i.code)
+      expect(long).toContain('effective-title-too-long')
+
+      const short = validateArticles(
+        [makeArticle({ title: 'x'.repeat(80), searchTitle: 'Short title' })],
+        baseConfig
+      ).warnings.map((i) => i.code)
+      expect(short).not.toContain('effective-title-too-long')
+    })
+
+    it('stops warning once titleTemplate drops the siteName suffix', () => {
+      const article = makeArticle({ title: 'x'.repeat(55) })
+      expect(validateArticles([article], baseConfig).warnings.map((i) => i.code)).toContain(
+        'effective-title-too-long'
       )
+      expect(
+        validateArticles([article], { ...baseConfig, titleTemplate: '{title}' }).warnings.map(
+          (i) => i.code
+        )
+      ).not.toContain('effective-title-too-long')
+    })
+
+    it('warns on the rendered meta description, falling back to excerpt', () => {
+      const fromExcerpt = validateArticles(
+        [makeArticle({ excerpt: 'e'.repeat(200) })],
+        baseConfig
+      ).warnings.map((i) => i.code)
+      expect(fromExcerpt).toContain('effective-description-too-long')
+
+      const overridden = validateArticles(
+        [makeArticle({ excerpt: 'e'.repeat(200), searchDescription: 'Short description.' })],
+        baseConfig
+      ).warnings.map((i) => i.code)
+      expect(overridden).not.toContain('effective-description-too-long')
     })
 
-    it('does not warn when searchTitle is within the recommended length', () => {
+    it('does not warn when the rendered title is within the limit', () => {
       const result = validateArticles([makeArticle({ searchTitle: 'Short title' })], baseConfig)
-      expect(result.warnings).toEqual([])
+      expect(result.warnings.map((issue) => issue.code)).not.toContain('effective-title-too-long')
+    })
+
+    it('warns when an article offers nothing quotable', () => {
+      const codes = validateArticles([makeArticle({})], baseConfig).warnings.map((i) => i.code)
+      expect(codes).toContain('no-answer')
+      expect(codes).toContain('missing-about')
+    })
+
+    it('accepts an answer, an faq, or a question-shaped h2 as answerable', () => {
+      const withAnswer = validateArticles([makeArticle({ answer: 'Yes.' })], baseConfig)
+      const withFaq = validateArticles(
+        [makeArticle({ faq: [{ question: 'Why?', answer: 'Because.' }] })],
+        baseConfig
+      )
+      const withHeading = validateArticles(
+        [makeArticle({ toc: [{ id: 'q', depth: 2, text: 'What is this?' }] })],
+        baseConfig
+      )
+      for (const result of [withAnswer, withFaq, withHeading]) {
+        expect(result.warnings.map((i) => i.code)).not.toContain('no-answer')
+      }
+    })
+
+    it('warns on thin content and stays quiet above the threshold', () => {
+      expect(
+        validateArticles([makeArticle({ wordCount: 120 })], baseConfig).warnings.map((i) => i.code)
+      ).toContain('thin-content')
+      expect(
+        validateArticles([makeArticle({ wordCount: 1200 })], baseConfig).warnings.map((i) => i.code)
+      ).not.toContain('thin-content')
+      expect(
+        validateArticles([makeArticle({})], baseConfig).warnings.map((i) => i.code)
+      ).not.toContain('thin-content')
+    })
+
+    it('warns on stale content using the injected clock and prefers lastmod', () => {
+      const now = new Date('2026-08-22T00:00:00.000Z')
+      const stale = validateArticles([makeArticle({ date: '2024-01-01' })], baseConfig, { now })
+      expect(stale.warnings.map((i) => i.code)).toContain('stale-content')
+
+      const refreshed = validateArticles(
+        [makeArticle({ date: '2024-01-01', lastmod: '2026-06-01' })],
+        baseConfig,
+        { now }
+      )
+      expect(refreshed.warnings.map((i) => i.code)).not.toContain('stale-content')
+    })
+
+    it('ignores undated and unparseable timestamps in the stale check', () => {
+      const now = new Date('2026-08-22T00:00:00.000Z')
+      const codes = validateArticles(
+        [
+          makeArticle({ slug: 'a', date: undefined }),
+          makeArticle({ slug: 'b', date: 'not-a-date' }),
+        ],
+        baseConfig,
+        { now }
+      ).warnings.map((i) => i.code)
+      expect(codes).not.toContain('stale-content')
+    })
+
+    it('warns on orphan articles only when bodies are loaded', () => {
+      const linked = validateArticles(
+        [
+          makeArticle({ slug: 'hub', content: 'See [the guide](/articles/spoke).' }),
+          makeArticle({ slug: 'spoke', content: 'Standalone body.' }),
+        ],
+        baseConfig
+      ).warnings.filter((i) => i.code === 'orphan-article')
+      expect(linked.map((i) => i.articleSlug)).toEqual(['hub'])
+
+      const noBodies = validateArticles(
+        [makeArticle({ slug: 'hub' }), makeArticle({ slug: 'spoke' })],
+        baseConfig
+      ).warnings.map((i) => i.code)
+      expect(noBodies).not.toContain('orphan-article')
+    })
+
+    it('warns on about entries missing from config.entities', () => {
+      const config: ArticlesConfig = {
+        ...baseConfig,
+        entities: { pathfinder: { name: 'Pathfinder' } },
+      }
+      const codes = validateArticles(
+        [makeArticle({ about: [{ name: 'PF2e' }] })],
+        config
+      ).warnings.map((i) => i.code)
+      expect(codes).toContain('unknown-entity')
+
+      const known = validateArticles(
+        [makeArticle({ about: [{ name: 'Pathfinder' }] })],
+        config
+      ).warnings.map((i) => i.code)
+      expect(known).not.toContain('unknown-entity')
+    })
+
+    it('accepts an unregistered entity that carries its own sameAs', () => {
+      const codes = validateArticles(
+        [makeArticle({ about: [{ name: 'PF2e', sameAs: 'https://example.com/pf2e' }] })],
+        { ...baseConfig, entities: { pathfinder: { name: 'Pathfinder' } } }
+      ).warnings.map((i) => i.code)
+      expect(codes).not.toContain('unknown-entity')
+    })
+
+    it('skips the entity check when no registry is configured', () => {
+      const codes = validateArticles(
+        [makeArticle({ about: [{ name: 'Anything' }] })],
+        baseConfig
+      ).warnings.map((i) => i.code)
+      expect(codes).not.toContain('unknown-entity')
     })
 
     it('warns on category slug collisions', () => {