@fullstackdatasolutions/articles 0.11.0 → 1.0.0

package/src/__tests__/pagination.test.ts

@@ -0,0 +1,178 @@
+import type { Article } from '../articleTypes'
+import {
+  getTotalPages,
+  paginateArticles,
+  buildPageUrl,
+  buildPaginationLinks,
+  generateListingPageStaticParams,
+  parsePageParam,
+  isPageOutOfRange,
+} from '../pagination'
+
+function makeArticles(count: number): Article[] {
+  return Array.from({ length: count }, (_, i) => ({
+    slug: `article-${i + 1}`,
+    title: `Article ${i + 1}`,
+    excerpt: `Excerpt ${i + 1}`,
+    author: 'Author',
+    category: 'Test',
+    categories: ['Test'],
+    readTime: '3 min read',
+    featuredImage: `/articles/article-${i + 1}/image.jpg`,
+  }))
+}
+
+describe('getTotalPages', () => {
+  it('divides totalCount by pageSize, rounding up', () => {
+    expect(getTotalPages(10, 3)).toBe(4)
+    expect(getTotalPages(9, 3)).toBe(3)
+  })
+
+  it('returns 1 for a zero or negative totalCount', () => {
+    expect(getTotalPages(0, 6)).toBe(1)
+    expect(getTotalPages(-5, 6)).toBe(1)
+  })
+
+  it('returns 1 for a zero or negative pageSize', () => {
+    expect(getTotalPages(10, 0)).toBe(1)
+    expect(getTotalPages(10, -1)).toBe(1)
+  })
+
+  it('returns 1 when totalCount is less than pageSize', () => {
+    expect(getTotalPages(2, 6)).toBe(1)
+  })
+})
+
+describe('paginateArticles', () => {
+  it('slices the requested page', () => {
+    const result = paginateArticles(makeArticles(10), 2, 3)
+    expect(result.articles.map((a) => a.slug)).toEqual(['article-4', 'article-5', 'article-6'])
+    expect(result.page).toBe(2)
+    expect(result.totalPages).toBe(4)
+    expect(result.hasPrevious).toBe(true)
+    expect(result.hasNext).toBe(true)
+  })
+
+  it('returns the first page by default characteristics (no previous, has next)', () => {
+    const result = paginateArticles(makeArticles(10), 1, 3)
+    expect(result.hasPrevious).toBe(false)
+    expect(result.hasNext).toBe(true)
+    expect(result.articles.map((a) => a.slug)).toEqual(['article-1', 'article-2', 'article-3'])
+  })
+
+  it('returns a shorter final slice and no next page on the last page', () => {
+    const result = paginateArticles(makeArticles(10), 4, 3)
+    expect(result.articles.map((a) => a.slug)).toEqual(['article-10'])
+    expect(result.hasNext).toBe(false)
+    expect(result.hasPrevious).toBe(true)
+  })
+
+  it('clamps a page number above totalPages down to the last page', () => {
+    const result = paginateArticles(makeArticles(10), 99, 3)
+    expect(result.page).toBe(4)
+    expect(result.articles.map((a) => a.slug)).toEqual(['article-10'])
+  })
+
+  it('clamps a page number below 1 up to page 1', () => {
+    const result = paginateArticles(makeArticles(10), -3, 3)
+    expect(result.page).toBe(1)
+    expect(result.articles.map((a) => a.slug)).toEqual(['article-1', 'article-2', 'article-3'])
+  })
+
+  it('clamps a non-integer page number', () => {
+    const result = paginateArticles(makeArticles(10), 2.9, 3)
+    expect(result.page).toBe(2)
+  })
+
+  it('returns totalPages 1 and all articles for an empty list', () => {
+    const result = paginateArticles([], 1, 6)
+    expect(result.totalPages).toBe(1)
+    expect(result.articles).toEqual([])
+    expect(result.hasNext).toBe(false)
+    expect(result.hasPrevious).toBe(false)
+  })
+})
+
+describe('buildPageUrl', () => {
+  it('returns basePath unchanged for page 1', () => {
+    expect(buildPageUrl('/articles', 1)).toBe('/articles')
+  })
+
+  it('appends /page/N for page > 1', () => {
+    expect(buildPageUrl('/articles', 2)).toBe('/articles/page/2')
+    expect(buildPageUrl('/articles/category/campaigns', 3)).toBe(
+      '/articles/category/campaigns/page/3'
+    )
+  })
+
+  it('strips a trailing slash from basePath before appending', () => {
+    expect(buildPageUrl('/articles/', 2)).toBe('/articles/page/2')
+  })
+})
+
+describe('buildPaginationLinks', () => {
+  it('has no prevUrl on page 1', () => {
+    const links = buildPaginationLinks('/articles', 1, 4)
+    expect(links.prevUrl).toBeNull()
+    expect(links.nextUrl).toBe('/articles/page/2')
+    expect(links.canonicalUrl).toBe('/articles')
+  })
+
+  it('has no nextUrl on the last page', () => {
+    const links = buildPaginationLinks('/articles', 4, 4)
+    expect(links.nextUrl).toBeNull()
+    expect(links.prevUrl).toBe('/articles/page/3')
+    expect(links.canonicalUrl).toBe('/articles/page/4')
+  })
+
+  it('has both prevUrl and nextUrl on a middle page', () => {
+    const links = buildPaginationLinks('/articles', 2, 4)
+    expect(links.prevUrl).toBe('/articles')
+    expect(links.nextUrl).toBe('/articles/page/3')
+    expect(links.canonicalUrl).toBe('/articles/page/2')
+  })
+})
+
+describe('generateListingPageStaticParams', () => {
+  it('returns params for pages 2..totalPages, excluding page 1', () => {
+    expect(generateListingPageStaticParams(4)).toEqual([
+      { page: '2' },
+      { page: '3' },
+      { page: '4' },
+    ])
+  })
+
+  it('returns an empty array when there is only one page', () => {
+    expect(generateListingPageStaticParams(1)).toEqual([])
+  })
+})
+
+describe('parsePageParam', () => {
+  it('parses a valid numeric string', () => {
+    expect(parsePageParam('3')).toBe(3)
+  })
+
+  it('defaults to 1 for undefined, null, or empty input', () => {
+    expect(parsePageParam(undefined)).toBe(1)
+    expect(parsePageParam(null)).toBe(1)
+    expect(parsePageParam('')).toBe(1)
+  })
+
+  it('defaults to 1 for non-numeric or non-positive input', () => {
+    expect(parsePageParam('abc')).toBe(1)
+    expect(parsePageParam('0')).toBe(1)
+    expect(parsePageParam('-2')).toBe(1)
+  })
+})
+
+describe('isPageOutOfRange', () => {
+  it('returns false for pages within [1, totalPages]', () => {
+    expect(isPageOutOfRange(1, 4)).toBe(false)
+    expect(isPageOutOfRange(4, 4)).toBe(false)
+  })
+
+  it('returns true for pages below 1 or above totalPages', () => {
+    expect(isPageOutOfRange(0, 4)).toBe(true)
+    expect(isPageOutOfRange(5, 4)).toBe(true)
+  })
+})

package/src/__tests__/seoUtils-authors.test.ts

@@ -3,6 +3,7 @@ import {
   buildAuthorBreadcrumbs,
   buildCategoryBreadcrumbs,
   generateAuthorMetadata,
+  generateAuthorPageMetadata,
   generateAuthorStaticParams,
 } from '../seoUtils'
 
@@ -158,3 +159,39 @@ describe('author metadata utilities', () => {
     })
   })
 })
+
+describe('generateAuthorPageMetadata', () => {
+  it('matches generateAuthorMetadata unchanged on page 1', async () => {
+    const base = await generateAuthorMetadata('andrew-blase', config)
+    const paged = await generateAuthorPageMetadata('andrew-blase', 1, 3, config)
+    expect(paged.title).toBe(base.title)
+    expect(paged.alternates?.canonical).toBe('https://example.com/articles/authors/andrew-blase')
+  })
+
+  it('appends a page suffix to the title and points canonical at the paginated URL', async () => {
+    const meta = await generateAuthorPageMetadata('andrew-blase', 2, 3, config)
+    expect(meta.title).toBe('Andrew Blase Articles | Example - Page 2')
+    expect(meta.alternates?.canonical).toBe(
+      'https://example.com/articles/authors/andrew-blase/page/2'
+    )
+  })
+
+  it('uses a configured absolute author.url as the pagination basePath when set', async () => {
+    const cfg = {
+      ...config,
+      authors: {
+        'andrew-blase': {
+          ...config.authors['andrew-blase'],
+          url: 'https://elsewhere.com/team/andrew',
+        },
+      },
+    }
+    const meta = await generateAuthorPageMetadata('andrew-blase', 2, 3, cfg)
+    expect(meta.alternates?.canonical).toBe('https://elsewhere.com/team/andrew/page/2')
+  })
+
+  it('returns Author Not Found metadata unchanged for an unknown author slug', async () => {
+    const meta = await generateAuthorPageMetadata('nobody', 2, 3, config)
+    expect(meta.title).toBe('Author Not Found')
+  })
+})

package/src/__tests__/seoUtils.test.ts

@@ -2,11 +2,17 @@ import { ArticlesConfig } from '../articlesConfig'
 import {
   generateArticleStaticParams,
   generateArticlesIndexMetadata,
+  generateArticlesIndexPageMetadata,
   generateCategoryStaticParams,
+  generateSeriesStaticParams,
   generateArticleMetadata,
   generateCategoryMetadata,
+  generateCategoryPageMetadata,
+  generateSeriesMetadata,
   getArticleSitemapEntries,
   generateRssFeed,
+  resolveSearchMetadata,
+  resolveSocialMetadata,
 } from '../seoUtils'
 
 jest.mock('../server-articles', () => ({
@@ -96,6 +102,27 @@ jest.mock('../server-articles', () => ({
       return `${cfg.siteUrl.replace(/\/$/, '')}/articles/${article.slug}.md`
     }
   ),
+  getArticlesBySeries: jest.fn(async (seriesSlug: string) => {
+    if (seriesSlug === 'new-gm-path') {
+      return [
+        {
+          slug: 'article-one',
+          title: 'Article One',
+          excerpt: 'Excerpt.',
+          date: '2025-01-15',
+          author: 'Jane Doe',
+          category: 'Campaigns',
+          categories: ['Campaigns'],
+          readTime: '3 min read',
+          featuredImage: '/articles/article-one/image.jpg',
+          series: 'New GM Path',
+          seriesSlug: 'new-gm-path',
+          seriesOrder: 1,
+        },
+      ]
+    }
+    return []
+  }),
 }))
 
 const config: ArticlesConfig = {
@@ -404,6 +431,41 @@ describe('generateArticleMetadata', () => {
   })
 })
 
+describe('generateArticlesIndexPageMetadata', () => {
+  it('matches generateArticlesIndexMetadata unchanged on page 1', () => {
+    const base = generateArticlesIndexMetadata(config)
+    const paged = generateArticlesIndexPageMetadata(1, 3, config)
+    expect(paged.title).toBe(base.title)
+    expect(paged.alternates?.canonical).toBe('https://example.com/articles')
+  })
+
+  it('appends a page suffix to the title on page > 1', () => {
+    const meta = generateArticlesIndexPageMetadata(2, 3, config)
+    expect(meta.title).toBe('Articles | Example Site - Page 2')
+  })
+
+  it('points canonical at the paginated URL on page > 1', () => {
+    const meta = generateArticlesIndexPageMetadata(2, 3, config)
+    expect(meta.alternates?.canonical).toBe('https://example.com/articles/page/2')
+  })
+
+  it('appends the page suffix to openGraph and twitter titles', () => {
+    const meta = generateArticlesIndexPageMetadata(3, 3, config)
+    expect(meta.openGraph?.title).toBe('Articles | Example Site - Page 3')
+    expect(meta.twitter?.title).toBe('Articles | Example Site - Page 3')
+  })
+
+  it('sets the openGraph url to the paginated canonical URL', () => {
+    const meta = generateArticlesIndexPageMetadata(2, 3, config)
+    expect(meta.openGraph?.url).toBe('https://example.com/articles/page/2')
+  })
+
+  it('remains index/follow on paginated pages', () => {
+    const meta = generateArticlesIndexPageMetadata(2, 3, config)
+    expect(meta.robots).toEqual(expect.objectContaining({ index: true, follow: true }))
+  })
+})
+
 describe('generateCategoryMetadata', () => {
   it('returns correct title using category name and siteName', async () => {
     const meta = await generateCategoryMetadata('campaigns', config)
@@ -449,6 +511,29 @@ describe('generateCategoryMetadata', () => {
   })
 })
 
+describe('generateCategoryPageMetadata', () => {
+  it('matches generateCategoryMetadata unchanged on page 1', async () => {
+    const base = await generateCategoryMetadata('campaigns', config)
+    const paged = await generateCategoryPageMetadata('campaigns', 1, 2, config)
+    expect(paged.title).toBe(base.title)
+    expect(paged.alternates?.canonical).toBe('https://example.com/articles/category/campaigns')
+  })
+
+  it('appends a page suffix to the title and points canonical at the paginated URL', async () => {
+    const meta = await generateCategoryPageMetadata('campaigns', 2, 2, config)
+    expect(meta.title).toBe('Campaigns Articles | Example Site - Page 2')
+    expect(meta.alternates?.canonical).toBe(
+      'https://example.com/articles/category/campaigns/page/2'
+    )
+  })
+
+  it('returns Category Not Found metadata unchanged for an unknown category (no page suffix/canonical added)', async () => {
+    const meta = await generateCategoryPageMetadata('nonexistent', 2, 2, config)
+    expect(meta.title).toBe('Category Not Found')
+    expect(meta.alternates).toBeUndefined()
+  })
+})
+
 describe('getArticleSitemapEntries', () => {
   it('returns article and category entries prefixed with baseUrl', async () => {
     const entries = await getArticleSitemapEntries('https://example.com')
@@ -685,3 +770,164 @@ describe('generateRssFeed', () => {
     expect(xml).toContain('<![CDATA[Second Article]]>')
   })
 })
+
+// ---------------------------------------------------------------------------
+// Phase 27F: discovery metadata channel separation
+// ---------------------------------------------------------------------------
+
+describe('resolveSearchMetadata', () => {
+  it('falls back to title/excerpt when searchTitle/searchDescription are unset', () => {
+    const result = resolveSearchMetadata(
+      { title: 'The Title', excerpt: 'The excerpt.' },
+      { siteName: 'Example' }
+    )
+    expect(result).toEqual({ title: 'The Title', description: 'The excerpt.' })
+  })
+
+  it('prefers searchTitle/searchDescription when set', () => {
+    const result = resolveSearchMetadata(
+      {
+        title: 'The Title',
+        excerpt: 'The excerpt.',
+        searchTitle: 'SEO Title',
+        searchDescription: 'SEO description.',
+      },
+      { siteName: 'Example' }
+    )
+    expect(result).toEqual({ title: 'SEO Title', description: 'SEO description.' })
+  })
+})
+
+describe('resolveSocialMetadata', () => {
+  it('falls back to title/excerpt/featuredImage when social overrides are unset', () => {
+    const result = resolveSocialMetadata(
+      { title: 'The Title', excerpt: 'The excerpt.', featuredImage: '/img.jpg' },
+      'https://example.com'
+    )
+    expect(result).toEqual({
+      title: 'The Title',
+      description: 'The excerpt.',
+      imageUrl: 'https://example.com/img.jpg',
+    })
+  })
+
+  it('prefers socialTitle/socialDescription/socialImage when set', () => {
+    const result = resolveSocialMetadata(
+      {
+        title: 'The Title',
+        excerpt: 'The excerpt.',
+        featuredImage: '/img.jpg',
+        socialTitle: 'Social Title',
+        socialDescription: 'Social description.',
+        socialImage: '/social.jpg',
+      },
+      'https://example.com'
+    )
+    expect(result).toEqual({
+      title: 'Social Title',
+      description: 'Social description.',
+      imageUrl: 'https://example.com/social.jpg',
+    })
+  })
+
+  it('passes through an absolute socialImage URL unchanged', () => {
+    const result = resolveSocialMetadata(
+      {
+        title: 'T',
+        excerpt: 'E',
+        featuredImage: '/img.jpg',
+        socialImage: 'https://cdn.example.com/social.jpg',
+      },
+      'https://example.com'
+    )
+    expect(result.imageUrl).toBe('https://cdn.example.com/social.jpg')
+  })
+})
+
+describe('generateArticleMetadata - discovery channel separation', () => {
+  it('uses title/excerpt (not overrides) for <title>/description when only canonical fields are set', async () => {
+    const meta = await generateArticleMetadata('article-one', config)
+    expect(meta.title).toBe('Article One | Example Site')
+    expect(meta.description).toBe('Excerpt for article one.')
+  })
+
+  it('prefers searchTitle/searchDescription for <title>/description, leaving openGraph on title/excerpt', async () => {
+    const { getArticleMetadata: mockGetArticleMetadata } = jest.requireMock('../server-articles')
+    mockGetArticleMetadata.mockImplementationOnce(async () => ({
+      slug: 'article-one',
+      title: 'Article One',
+      excerpt: 'Excerpt.',
+      date: '2025-01-15',
+      author: 'Jane Doe',
+      category: 'Campaigns',
+      categories: ['Campaigns'],
+      readTime: '3 min read',
+      featuredImage: '/articles/article-one/image.jpg',
+      searchTitle: 'SEO-Optimized Title',
+      searchDescription: 'SEO-optimized description.',
+    }))
+    const meta = await generateArticleMetadata('article-one', config)
+    expect(meta.title).toBe('SEO-Optimized Title | Example Site')
+    expect(meta.description).toBe('SEO-optimized description.')
+    expect((meta.openGraph as { title?: string }).title).toBe('Article One')
+  })
+
+  it('prefers socialTitle/socialDescription/socialImage for openGraph/twitter only', async () => {
+    const { getArticleMetadata: mockGetArticleMetadata } = jest.requireMock('../server-articles')
+    mockGetArticleMetadata.mockImplementationOnce(async () => ({
+      slug: 'article-one',
+      title: 'Article One',
+      excerpt: 'Excerpt.',
+      date: '2025-01-15',
+      author: 'Jane Doe',
+      category: 'Campaigns',
+      categories: ['Campaigns'],
+      readTime: '3 min read',
+      featuredImage: '/articles/article-one/image.jpg',
+      socialTitle: 'Social-Optimized Title',
+      socialDescription: 'Social-optimized description.',
+      socialImage: '/articles/article-one/social.jpg',
+    }))
+    const meta = await generateArticleMetadata('article-one', config)
+    expect(meta.title).toBe('Article One | Example Site')
+    expect((meta.openGraph as { title?: string }).title).toBe('Social-Optimized Title')
+    expect((meta.twitter as { title?: string }).title).toBe('Social-Optimized Title')
+    expect((meta.openGraph as { images?: Array<{ url: string }> }).images?.[0].url).toBe(
+      'https://example.com/articles/article-one/social.jpg'
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Phase 27F: series static params + metadata
+// ---------------------------------------------------------------------------
+
+describe('generateSeriesStaticParams', () => {
+  it('returns one entry per distinct seriesSlug across all articles', async () => {
+    const { getAllArticles: mockGetAllArticles } = jest.requireMock('../server-articles')
+    mockGetAllArticles.mockResolvedValueOnce([
+      { slug: 'a', seriesSlug: 'new-gm-path' },
+      { slug: 'b', seriesSlug: 'new-gm-path' },
+      { slug: 'c', seriesSlug: 'combat-basics' },
+      { slug: 'd' },
+    ])
+    const result = await generateSeriesStaticParams()
+    expect(result).toEqual(
+      expect.arrayContaining([{ series: 'new-gm-path' }, { series: 'combat-basics' }])
+    )
+    expect(result).toHaveLength(2)
+  })
+})
+
+describe('generateSeriesMetadata', () => {
+  it('returns "Series Not Found" for an unknown seriesSlug', async () => {
+    const meta = await generateSeriesMetadata('nonexistent', config)
+    expect(meta.title).toBe('Series Not Found')
+  })
+
+  it('builds title/description/canonical from the series articles', async () => {
+    const meta = await generateSeriesMetadata('new-gm-path', config)
+    expect(meta.title).toBe('New GM Path Series | Example Site')
+    expect(meta.alternates?.canonical).toBe('https://example.com/articles/series/new-gm-path')
+  })
+})