@fullstackdatasolutions/articles 0.12.0 → 1.0.0

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

@@ -16,9 +16,16 @@ import {
   getArticlesByAuthor,
   getAuthorBySlug,
   getAvailableArticleSlugs,
+  getRelatedArticlesByCategory,
+  getArticlesBySeries,
+  getAdjacentArticlesInSeries,
+  getPath,
+  getPathArticles,
+  getRelatedContent,
   sanitizeImagePath,
   searchArticles,
 } from '../server-articles'
+import type { ArticlesConfig } from '../articlesConfig'
 import { setArticlesErrorHandler } from '../errorReporting'
 import { markdownToHtml } from '../markdown'
 
@@ -28,7 +35,7 @@ jest.mock('../markdown', () => ({
   markdownToHtml: jest.fn(async () => '<p>content</p>'),
   extractToc: jest.fn(async () => []),
 }))
-jest.mock('reading-time', () => () => ({ text: '2 min read' }))
+jest.mock('reading-time', () => () => ({ text: '2 min read', words: 42 }))
 
 const mockedFs = fs as jest.Mocked<typeof fs>
 const mockedMarkdownToHtml = markdownToHtml as jest.MockedFunction<typeof markdownToHtml>
@@ -181,6 +188,14 @@ describe('getArticleMetadata - frontmatter parsing', () => {
     expect(article!.lastmod).toBe('2025-06-15')
   })
 
+  it('computes wordCount from the same reading-time pass as readTime', async () => {
+    setupArticleMock('')
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.readTime).toBe('2 min read')
+    expect(article!.wordCount).toBe(42)
+  })
+
   it('parses canonicalUrl from frontmatter', async () => {
     setupArticleMock('canonicalUrl: "https://canonical.example.com/article"\n')
     const article = await getArticleMetadata('test-slug')
@@ -202,6 +217,75 @@ describe('getArticleMetadata - frontmatter parsing', () => {
     expect(article!.series).toBe('My Series')
   })
 
+  it('parses seriesSlug and seriesOrder from frontmatter', async () => {
+    setupArticleMock('seriesSlug: "new-gm-path"\nseriesOrder: 2\n')
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.seriesSlug).toBe('new-gm-path')
+    expect(article!.seriesOrder).toBe(2)
+  })
+
+  it('leaves seriesSlug/seriesOrder undefined when omitted (legacy series field still works)', async () => {
+    setupArticleMock('series: "My Series"\n')
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.series).toBe('My Series')
+    expect(article!.seriesSlug).toBeUndefined()
+    expect(article!.seriesOrder).toBeUndefined()
+  })
+
+  it('parses searchTitle/searchDescription/socialTitle/socialDescription/socialImage from frontmatter', async () => {
+    setupArticleMock(
+      'searchTitle: "SEO Title"\nsearchDescription: "SEO description."\nsocialTitle: "Social Title"\nsocialDescription: "Social description."\nsocialImage: "social.jpg"\n'
+    )
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.searchTitle).toBe('SEO Title')
+    expect(article!.searchDescription).toBe('SEO description.')
+    expect(article!.socialTitle).toBe('Social Title')
+    expect(article!.socialDescription).toBe('Social description.')
+    expect(article!.socialImage).toBe('social.jpg')
+  })
+
+  it('leaves discovery override fields undefined when omitted', async () => {
+    setupArticleMock('')
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.searchTitle).toBeUndefined()
+    expect(article!.searchDescription).toBeUndefined()
+    expect(article!.socialTitle).toBeUndefined()
+    expect(article!.socialDescription).toBeUndefined()
+    expect(article!.socialImage).toBeUndefined()
+  })
+
+  it('treats a blank searchTitle as unset', async () => {
+    setupArticleMock('searchTitle: ""\n')
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.searchTitle).toBeUndefined()
+  })
+
+  it('parses primaryAction from a shorthand string', async () => {
+    setupArticleMock('primaryAction: "download-starter-kit"\n')
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.primaryAction).toEqual({ actionId: 'download-starter-kit' })
+  })
+
+  it('parses primaryAction from an object with actionId', async () => {
+    setupArticleMock('primaryAction:\n  actionId: "download-starter-kit"\n')
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.primaryAction).toEqual({ actionId: 'download-starter-kit' })
+  })
+
+  it('leaves primaryAction undefined when omitted', async () => {
+    setupArticleMock('')
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.primaryAction).toBeUndefined()
+  })
+
   it('filters out malformed faq items', async () => {
     setupArticleMock(
       'faq:\n  - question: "What is this?"\n    answer: "A test."\n  - question: "Missing answer"\n'
@@ -258,6 +342,49 @@ describe('getArticleMetadata - frontmatter parsing', () => {
     expect(article!.author).toBe('Andrew Blase')
   })
 
+  it('resolves authorSlug and authorAvatar from a configured author with an avatar', async () => {
+    setupArticleMock('author: andrew-blase\n')
+    const article = await getArticleMetadata('test-slug', {
+      siteUrl: 'https://example.com',
+      siteName: 'Example',
+      authors: {
+        'andrew-blase': {
+          name: 'Andrew Blase',
+          slug: 'andrew-blase',
+          bio: 'Writer.',
+          avatar: 'avatar.jpg',
+        },
+      },
+    })
+    expect(article).not.toBeNull()
+    expect(article!.authorSlug).toBe('andrew-blase')
+    expect(article!.authorAvatar).toBe(
+      'https://example.com/articles/authors/andrew-blase/avatar.jpg'
+    )
+  })
+
+  it('leaves authorSlug and authorAvatar unset when no config is passed', async () => {
+    setupArticleMock('author: andrew-blase\n')
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.authorSlug).toBeUndefined()
+    expect(article!.authorAvatar).toBeUndefined()
+  })
+
+  it('leaves authorAvatar unset when the configured author has no avatar', async () => {
+    setupArticleMock('author: andrew-blase\n')
+    const article = await getArticleMetadata('test-slug', {
+      siteUrl: 'https://example.com',
+      siteName: 'Example',
+      authors: {
+        'andrew-blase': { name: 'Andrew Blase', slug: 'andrew-blase', bio: 'Writer.' },
+      },
+    })
+    expect(article).not.toBeNull()
+    expect(article!.authorSlug).toBe('andrew-blase')
+    expect(article!.authorAvatar).toBeUndefined()
+  })
+
   it('parses multi-author frontmatter', async () => {
     setupArticleMock('authors:\n  - andrew-blase\n  - jane-doe\n')
     const article = await getArticleMetadata('test-slug')
@@ -555,6 +682,37 @@ describe('article collection utilities', () => {
     await expect(getAdjacentArticles('missing')).resolves.toEqual({ previous: null, next: null })
   })
 
+  it('returns other articles in the same category, excluding the current article', async () => {
+    setupArticleTreeMock([
+      { slug: 'one', frontmatter: 'date: 2025-01-01\ntags:\n  - Civic Tech\n' },
+      { slug: 'two', frontmatter: 'date: 2025-01-02\ntags:\n  - Civic Tech\n' },
+      { slug: 'three', frontmatter: 'date: 2025-01-03\ntags:\n  - Civic Tech\n' },
+      { slug: 'unrelated', frontmatter: 'date: 2025-01-04\ntags:\n  - Field Ops\n' },
+    ])
+
+    const related = await getRelatedArticlesByCategory('two', 'Civic Tech')
+    expect(related.map((article) => article.slug)).toEqual(['three', 'one'])
+  })
+
+  it('respects the limit parameter', async () => {
+    setupArticleTreeMock([
+      { slug: 'one', frontmatter: 'date: 2025-01-01\ntags:\n  - Civic Tech\n' },
+      { slug: 'two', frontmatter: 'date: 2025-01-02\ntags:\n  - Civic Tech\n' },
+      { slug: 'three', frontmatter: 'date: 2025-01-03\ntags:\n  - Civic Tech\n' },
+    ])
+
+    const related = await getRelatedArticlesByCategory('one', 'Civic Tech', 1)
+    expect(related).toHaveLength(1)
+  })
+
+  it('returns an empty array when no other articles share the category', async () => {
+    setupArticleTreeMock([
+      { slug: 'only', frontmatter: 'date: 2025-01-01\ntags:\n  - Civic Tech\n' },
+    ])
+
+    await expect(getRelatedArticlesByCategory('only', 'Civic Tech')).resolves.toEqual([])
+  })
+
   it('searches articles by title, excerpt, author, category, and tag', async () => {
     setupArticleTreeMock([
       {
@@ -805,3 +963,200 @@ describe('article path helpers', () => {
     expect(categoryToSlug('Civic Tech & Field Ops')).toBe('civic-tech--field-ops')
   })
 })
+
+describe('getArticlesBySeries', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('returns only articles matching seriesSlug, sorted by seriesOrder ascending', async () => {
+    setupArticleTreeMock([
+      { slug: 'step-2', frontmatter: 'date: 2025-01-01\nseriesSlug: "new-gm"\nseriesOrder: 2\n' },
+      { slug: 'step-1', frontmatter: 'date: 2025-01-02\nseriesSlug: "new-gm"\nseriesOrder: 1\n' },
+      { slug: 'unrelated', frontmatter: 'date: 2025-01-03\n' },
+    ])
+
+    const result = await getArticlesBySeries('new-gm')
+    expect(result.map((a) => a.slug)).toEqual(['step-1', 'step-2'])
+  })
+
+  it('falls back to date order (stable sort) for articles with no seriesOrder', async () => {
+    setupArticleTreeMock([
+      { slug: 'newer', frontmatter: 'date: 2025-01-02\nseriesSlug: "new-gm"\n' },
+      { slug: 'older', frontmatter: 'date: 2025-01-01\nseriesSlug: "new-gm"\n' },
+    ])
+
+    const result = await getArticlesBySeries('new-gm')
+    // getAllArticles already sorts newest-first; stable sort preserves that
+    // relative order when seriesOrder is absent on both.
+    expect(result.map((a) => a.slug)).toEqual(['newer', 'older'])
+  })
+
+  it('returns an empty array when no articles match the series', async () => {
+    setupArticleTreeMock([{ slug: 'unrelated', frontmatter: 'date: 2025-01-01\n' }])
+    await expect(getArticlesBySeries('nonexistent')).resolves.toEqual([])
+  })
+})
+
+describe('getAdjacentArticlesInSeries', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('walks seriesOrder, not global date order', async () => {
+    setupArticleTreeMock([
+      { slug: 'step-1', frontmatter: 'date: 2025-01-03\nseriesSlug: "new-gm"\nseriesOrder: 1\n' },
+      { slug: 'step-2', frontmatter: 'date: 2025-01-02\nseriesSlug: "new-gm"\nseriesOrder: 2\n' },
+      { slug: 'step-3', frontmatter: 'date: 2025-01-01\nseriesSlug: "new-gm"\nseriesOrder: 3\n' },
+    ])
+
+    const result = await getAdjacentArticlesInSeries('step-2', 'new-gm')
+    expect(result.previous?.slug).toBe('step-1')
+    expect(result.next?.slug).toBe('step-3')
+  })
+
+  it('returns null previous/next at the series boundaries', async () => {
+    setupArticleTreeMock([
+      { slug: 'step-1', frontmatter: 'date: 2025-01-02\nseriesSlug: "new-gm"\nseriesOrder: 1\n' },
+      { slug: 'step-2', frontmatter: 'date: 2025-01-01\nseriesSlug: "new-gm"\nseriesOrder: 2\n' },
+    ])
+
+    const first = await getAdjacentArticlesInSeries('step-1', 'new-gm')
+    expect(first.previous).toBeNull()
+    expect(first.next?.slug).toBe('step-2')
+
+    const last = await getAdjacentArticlesInSeries('step-2', 'new-gm')
+    expect(last.previous?.slug).toBe('step-1')
+    expect(last.next).toBeNull()
+  })
+
+  it('returns null/null when the current slug is not in the series', async () => {
+    setupArticleTreeMock([
+      { slug: 'step-1', frontmatter: 'date: 2025-01-01\nseriesSlug: "new-gm"\nseriesOrder: 1\n' },
+    ])
+    const result = await getAdjacentArticlesInSeries('not-in-series', 'new-gm')
+    expect(result).toEqual({ previous: null, next: null })
+  })
+})
+
+describe('getPath / getPathArticles', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  const baseConfig: ArticlesConfig = {
+    siteUrl: 'https://example.com',
+    siteName: 'Example',
+    paths: {
+      'new-gm': {
+        name: 'New GM Starter Path',
+        promise: 'Run your first session with confidence.',
+        articles: ['step-1', 'step-2'],
+        nextAction: { label: 'Get the checklist', href: '/lead-magnets/gm-checklist' },
+      },
+    },
+  }
+
+  it('getPath returns the configured PathDefinition by key', () => {
+    expect(getPath('new-gm', baseConfig)?.name).toBe('New GM Starter Path')
+  })
+
+  it('getPath returns null for an unconfigured key', () => {
+    expect(getPath('nonexistent', baseConfig)).toBeNull()
+  })
+
+  it('getPathArticles resolves slugs to real articles in path order', async () => {
+    setupArticleTreeMock([
+      { slug: 'step-2', frontmatter: 'date: 2025-01-01\n' },
+      { slug: 'step-1', frontmatter: 'date: 2025-01-02\n' },
+    ])
+
+    const result = await getPathArticles('new-gm', baseConfig)
+    expect(result.map((a) => a.slug)).toEqual(['step-1', 'step-2'])
+  })
+
+  it('getPathArticles drops references that do not resolve to a real article', async () => {
+    setupArticleTreeMock([{ slug: 'step-1', frontmatter: 'date: 2025-01-01\n' }])
+    const result = await getPathArticles('new-gm', baseConfig)
+    expect(result.map((a) => a.slug)).toEqual(['step-1'])
+  })
+
+  it('getPathArticles returns an empty array for an unconfigured path key', async () => {
+    setupArticleTreeMock([{ slug: 'step-1', frontmatter: 'date: 2025-01-01\n' }])
+    await expect(getPathArticles('nonexistent', baseConfig)).resolves.toEqual([])
+  })
+})
+
+describe('getRelatedContent', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('prefers a configured Path over series/category when the article is in one', async () => {
+    setupArticleTreeMock([
+      { slug: 'step-1', frontmatter: 'date: 2025-01-01\ntags:\n  - Campaigns\n' },
+      { slug: 'step-2', frontmatter: 'date: 2025-01-02\ntags:\n  - Campaigns\n' },
+    ])
+    const config: ArticlesConfig = {
+      siteUrl: 'https://example.com',
+      siteName: 'Example',
+      paths: {
+        'new-gm': {
+          name: 'New GM Starter Path',
+          promise: 'Run your first session with confidence.',
+          articles: ['step-1', 'step-2'],
+          nextAction: { label: 'Get the checklist', href: '/lead-magnets/gm-checklist' },
+        },
+      },
+    }
+    const article = (await getPathArticles('new-gm', config))[0]
+
+    const result = await getRelatedContent(article, config)
+    expect(result.source).toBe('path')
+    expect(result.pathKey).toBe('new-gm')
+    expect(result.heading).toBe('New GM Starter Path')
+    expect(result.articles.map((a) => a.slug)).toEqual(['step-2'])
+    expect(result.nextAction).toEqual({
+      label: 'Get the checklist',
+      href: '/lead-magnets/gm-checklist',
+    })
+  })
+
+  it('falls back to series when no path matches', async () => {
+    setupArticleTreeMock([
+      {
+        slug: 'part-1',
+        frontmatter:
+          'date: 2025-01-01\nseries: "Combat Basics"\nseriesSlug: "combat-basics"\nseriesOrder: 1\n',
+      },
+      {
+        slug: 'part-2',
+        frontmatter:
+          'date: 2025-01-02\nseries: "Combat Basics"\nseriesSlug: "combat-basics"\nseriesOrder: 2\n',
+      },
+    ])
+    const config: ArticlesConfig = { siteUrl: 'https://example.com', siteName: 'Example' }
+    const articles = await getArticlesBySeries('combat-basics', config)
+    const part1 = articles.find((a) => a.slug === 'part-1')!
+
+    const result = await getRelatedContent(part1, config)
+    expect(result.source).toBe('series')
+    expect(result.heading).toBe('Combat Basics')
+    expect(result.articles.map((a) => a.slug)).toEqual(['part-2'])
+  })
+
+  it('falls back to category (via getRelatedArticlesByCategory) when no path or series applies', async () => {
+    setupArticleTreeMock([
+      { slug: 'one', frontmatter: 'date: 2025-01-01\ntags:\n  - Civic Tech\n' },
+      { slug: 'two', frontmatter: 'date: 2025-01-02\ntags:\n  - Civic Tech\n' },
+    ])
+    const config: ArticlesConfig = { siteUrl: 'https://example.com', siteName: 'Example' }
+    const articles = await getAllArticles(config)
+    const one = articles.find((a) => a.slug === 'one')!
+
+    const result = await getRelatedContent(one, config)
+    expect(result.source).toBe('category')
+    expect(result.heading).toBe('More in Civic Tech')
+    expect(result.articles.map((a) => a.slug)).toEqual(['two'])
+  })
+})