@fullstackdatasolutions/articles 0.12.0 → 1.0.0

package/src/server-articles.ts

@@ -3,15 +3,24 @@ import matter from 'gray-matter'
 import fs from 'node:fs'
 import path from 'node:path'
 import readingTime from 'reading-time'
+import { getAuthorAvatar } from './authorUtils'
 import { markdownToHtml, extractToc } from './markdown'
-import type { Article, AuthorProfile, CategoryInfo, FaqItem, HowToStep } from './articleTypes'
+import type {
+  Article,
+  AuthorProfile,
+  CategoryInfo,
+  FaqItem,
+  HowToStep,
+  PathDefinition,
+} from './articleTypes'
 import type { ArticlesConfig } from './articlesConfig'
 import { reportArticlesError } from './errorReporting'
 
 const articlesDirectory = path.join(/* turbopackIgnore: true */ process.cwd(), 'public/articles')
 
-function getReadingTime(content: string): string {
-  return readingTime(content).text
+function getReadingStats(content: string): { readTime: string; wordCount: number } {
+  const stats = readingTime(content)
+  return { readTime: stats.text, wordCount: stats.words }
 }
 
 function findArticleImage(slug: string): string | null {
@@ -153,6 +162,35 @@ function parseHowToSteps(raw: unknown): HowToStep[] | undefined {
   return steps.length ? steps : undefined
 }
 
+// Trims and drops empty strings - the same "unset if blank" rule applied to
+// every other optional string frontmatter field in this file
+// (canonicalUrl/articleType/series). Used for all five discovery overrides
+// (Phase 27F) so a stray `searchTitle: ""` in frontmatter behaves exactly
+// like omitting the key, rather than becoming an empty <title> override.
+function parseOptionalString(raw: unknown): string | undefined {
+  return typeof raw === 'string' && raw.trim().length > 0 ? raw.trim() : undefined
+}
+
+function parseSeriesOrder(raw: unknown): number | undefined {
+  return typeof raw === 'number' && Number.isFinite(raw) ? raw : undefined
+}
+
+function parsePrimaryAction(raw: unknown): { actionId: string } | undefined {
+  if (typeof raw === 'string') {
+    const actionId = raw.trim()
+    return actionId ? { actionId } : undefined
+  }
+  if (
+    typeof raw === 'object' &&
+    raw !== null &&
+    typeof (raw as { actionId?: unknown }).actionId === 'string'
+  ) {
+    const actionId = (raw as { actionId: string }).actionId.trim()
+    return actionId ? { actionId } : undefined
+  }
+  return undefined
+}
+
 function parseAuthors(raw: unknown): string[] | undefined {
   if (!Array.isArray(raw)) return undefined
   const authors = raw.filter(
@@ -233,23 +271,38 @@ async function getArticleSummary(slug: string, config?: ArticlesConfig): Promise
     if (!found) return null
     const fileContent = fs.readFileSync(found.filePath, 'utf8')
     const { data, content: markdownContent } = matter(fileContent)
-    const readTime = getReadingTime(markdownContent)
+    const { readTime, wordCount } = getReadingStats(markdownContent)
     const allTags: string[] = Array.isArray(data.tags)
       ? data.tags.filter((t: unknown) => typeof t === 'string' && String(t).trim())
       : []
     const categories: string[] =
       allTags.length > 0 ? allTags.map((t: string) => t.replaceAll('-', ' ').trim()) : ['Campaigns']
+    const author = resolveArticleAuthorName(data.author, data.authors, config)
+    const authors = parseAuthors(data.authors)
+    // Resolve the primary author's profile (if configured) so cards can
+    // render an avatar/link without needing `config` client-side. Reuses
+    // getArticleAuthors' existing slug/name resolution chain instead of
+    // duplicating it - only the two fields it reads (author/authors) exist
+    // on this partial yet.
+    const primaryAuthorProfile = config
+      ? getArticleAuthors({ author, authors } as Article, config)[0]
+      : undefined
     return {
       slug,
       title: data.title || slug.replaceAll('-', ' '),
       excerpt: data.excerpt || '',
       date: parseDateField(data.date),
       lastmod: parseDateField(data.lastmod),
-      author: resolveArticleAuthorName(data.author, data.authors, config),
-      authors: parseAuthors(data.authors),
+      author,
+      authors,
+      authorSlug: primaryAuthorProfile?.slug,
+      authorAvatar: primaryAuthorProfile
+        ? getAuthorAvatar(primaryAuthorProfile, config)
+        : undefined,
       category: categories[0],
       categories,
       readTime,
+      wordCount,
       featuredImage: resolveFeaturedImage(data.featuredImage, slug),
       tags: data.tags || [],
       contentType: found.contentType,
@@ -259,7 +312,15 @@ async function getArticleSummary(slug: string, config?: ArticlesConfig): Promise
       canonicalUrl: typeof data.canonicalUrl === 'string' ? data.canonicalUrl : undefined,
       articleType: typeof data.articleType === 'string' ? data.articleType : undefined,
       series: typeof data.series === 'string' ? data.series : undefined,
+      seriesSlug: parseOptionalString(data.seriesSlug),
+      seriesOrder: parseSeriesOrder(data.seriesOrder),
       aiCrawl: data.aiCrawl === true,
+      searchTitle: parseOptionalString(data.searchTitle),
+      searchDescription: parseOptionalString(data.searchDescription),
+      socialTitle: parseOptionalString(data.socialTitle),
+      socialDescription: parseOptionalString(data.socialDescription),
+      socialImage: parseOptionalString(data.socialImage),
+      primaryAction: parsePrimaryAction(data.primaryAction),
     }
   } catch (error) {
     reportArticlesError({
@@ -468,6 +529,20 @@ export async function getArticlesByCategory(
   )
 }
 
+// Built on getArticlesByCategory (same slug-matching filter, no duplicated
+// logic) rather than getAdjacentArticles' global date-order walk, so an
+// article detail page can link to other articles in the same category
+// instead of just the two chronologically-nearest articles overall.
+export async function getRelatedArticlesByCategory(
+  currentSlug: string,
+  category: string,
+  limit = 3,
+  config?: ArticlesConfig
+): Promise<Article[]> {
+  const articles = await getArticlesByCategory(categoryToSlug(category), config)
+  return articles.filter((article) => article.slug !== currentSlug).slice(0, limit)
+}
+
 export async function getArticlesByAuthor(
   authorSlug: string,
   config: ArticlesConfig
@@ -478,4 +553,122 @@ export async function getArticlesByAuthor(
   )
 }
 
+// Sorted by `seriesOrder` ascending (undefined pushed to the end); ties fall
+// back to the date-descending order `getAllArticles` already applies, since
+// `Array.prototype.sort` is stable - matching `getArticlesByCategory`'s
+// "build on the existing filter, don't duplicate `getAllArticles`" pattern.
+// The label-only `series` string field is untouched by this function.
+export async function getArticlesBySeries(
+  seriesSlug: string,
+  config?: ArticlesConfig
+): Promise<Article[]> {
+  const articles = await getAllArticles(config)
+  return articles
+    .filter((article) => article.seriesSlug === seriesSlug)
+    .sort((a, b) => {
+      const orderA = a.seriesOrder ?? Number.POSITIVE_INFINITY
+      const orderB = b.seriesOrder ?? Number.POSITIVE_INFINITY
+      return orderA - orderB
+    })
+}
+
+/**
+ * Series-aware sibling of `getAdjacentArticles`: walks `seriesOrder` within
+ * one series instead of global date order. `previous`/`next` follow series
+ * order (ascending), not chronology.
+ */
+export async function getAdjacentArticlesInSeries(
+  currentSlug: string,
+  seriesSlug: string,
+  config?: ArticlesConfig
+): Promise<{ previous: Article | null; next: Article | null }> {
+  const seriesArticles = await getArticlesBySeries(seriesSlug, config)
+  const currentIndex = seriesArticles.findIndex((article) => article.slug === currentSlug)
+  if (currentIndex === -1) return { previous: null, next: null }
+  return {
+    previous: currentIndex > 0 ? seriesArticles[currentIndex - 1] : null,
+    next: currentIndex < seriesArticles.length - 1 ? seriesArticles[currentIndex + 1] : null,
+  }
+}
+
+/** Looks up one configured `PathDefinition` by its app-chosen key. */
+export function getPath(pathKey: string, config: ArticlesConfig): PathDefinition | null {
+  return config.paths?.[pathKey] ?? null
+}
+
+/** Resolves a path's ordered slugs against the real article set, dropping any that don't resolve (e.g. a draft filtered out of `getAllArticles` in production) rather than throwing - use `validateArticles` to catch broken references before publishing. */
+export async function getPathArticles(pathKey: string, config: ArticlesConfig): Promise<Article[]> {
+  const path = getPath(pathKey, config)
+  if (!path) return []
+  const articles = await getAllArticles(config)
+  const bySlug = new Map(articles.map((article) => [article.slug, article]))
+  return path.articles
+    .map((slug) => bySlug.get(slug))
+    .filter((article): article is Article => Boolean(article))
+}
+
+function findPathForArticle(
+  slug: string,
+  config: ArticlesConfig
+): { key: string; path: PathDefinition } | null {
+  for (const [key, path] of Object.entries(config.paths ?? {})) {
+    if (path.articles.includes(slug)) return { key, path }
+  }
+  return null
+}
+
+export type RelatedContentSource = 'path' | 'series' | 'category'
+
+export interface RelatedContentResult {
+  source: RelatedContentSource
+  /** Heading for a related-content UI - the path's `name`, the article's `series` label, or "More in {category}". */
+  heading: string
+  articles: Article[]
+  /** Set only when `source === 'path'`. */
+  pathKey?: string
+  /** Set only when `source === 'path'` - the path's one configured next action. */
+  nextAction?: { label: string; href: string }
+}
+
+/**
+ * Reusable related-content selection (Phase 27F): prefers a configured
+ * `Path` containing this article first, then the article's `seriesSlug`,
+ * falling back to 27B's `getRelatedArticlesByCategory` (imported, not
+ * reimplemented) when neither a path nor a series applies - the plain
+ * chronological-within-category behavior stays the fallback, not a full
+ * replacement.
+ */
+export async function getRelatedContent(
+  article: Article,
+  config: ArticlesConfig,
+  limit = 3
+): Promise<RelatedContentResult> {
+  const matchedPath = findPathForArticle(article.slug, config)
+  if (matchedPath) {
+    const pathArticles = await getPathArticles(matchedPath.key, config)
+    return {
+      source: 'path',
+      heading: matchedPath.path.name,
+      articles: pathArticles.filter((a) => a.slug !== article.slug),
+      pathKey: matchedPath.key,
+      nextAction: matchedPath.path.nextAction,
+    }
+  }
+  if (article.seriesSlug) {
+    const seriesArticles = await getArticlesBySeries(article.seriesSlug, config)
+    return {
+      source: 'series',
+      heading: article.series ?? 'This series',
+      articles: seriesArticles.filter((a) => a.slug !== article.slug),
+    }
+  }
+  const categoryArticles = await getRelatedArticlesByCategory(
+    article.slug,
+    article.category,
+    limit,
+    config
+  )
+  return { source: 'category', heading: `More in ${article.category}`, articles: categoryArticles }
+}
+
 export { sanitizeImagePath }

package/src/server.ts

@@ -10,6 +10,12 @@ export {
   getArticleAuthors,
   getAvailableArticleSlugs,
   getAdjacentArticles,
+  getAdjacentArticlesInSeries,
+  getArticlesBySeries,
+  getRelatedArticlesByCategory,
+  getRelatedContent,
+  getPath,
+  getPathArticles,
   getAllAuthors,
   searchArticles,
   getAuthorBySlug,
@@ -24,23 +30,42 @@ export {
   generateRssFeed,
   generateArticleStaticParams,
   generateCategoryStaticParams,
+  generateSeriesStaticParams,
   generateAuthorStaticParams,
   generateArticlesIndexMetadata,
+  generateArticlesIndexPageMetadata,
   generateArticleMetadata,
   generateCategoryMetadata,
+  generateCategoryPageMetadata,
+  generateSeriesMetadata,
   generateAuthorMetadata,
+  generateAuthorPageMetadata,
   buildArticleBreadcrumbs,
   buildCategoryBreadcrumbs,
   buildAuthorBreadcrumbs,
   resolveAuthorAvatar,
+  resolveSearchMetadata,
+  resolveSocialMetadata,
   getArticleSitemapEntries,
 } from './seoUtils'
 
-export { markdownToHtml, extractToc } from './markdown'
+export {
+  getTotalPages,
+  paginateArticles,
+  buildPageUrl,
+  buildPaginationLinks,
+  generateListingPageStaticParams,
+  parsePageParam,
+  isPageOutOfRange,
+} from './pagination'
+
+export { markdownToHtml, extractToc, getContentSlotBoundaries } from './markdown'
 export { setArticlesErrorHandler } from './errorReporting'
 export { getBreadcrumbsConfig } from './articlesConfig'
 export { ArticleContent } from './ArticleContent'
 export { ArticleTOC } from './ArticleTOC'
+export { validateArticles, validateAllArticles } from './validateArticles'
+export { emitArticleEvent } from './events'
 
 export type {
   Article,
@@ -48,9 +73,28 @@ export type {
   AuthorSocial,
   BreadcrumbItem,
   CategoryInfo,
+  PathDefinition,
   TocItem,
 } from './articleTypes'
-export type { ArticlesConfig, LinkTargetStrategy } from './articlesConfig'
+export type { ArticlesConfig, LinkTargetStrategy, ListingPagination } from './articlesConfig'
+export type { PaginatedArticles, PaginationLinks, ListingPaginationContext } from './pagination'
+export type { ContentSlotBoundaries } from './markdown'
+export type { ArticleSlotContext, ArticleSlotContent } from './ArticleContent'
+export type { RelatedContentResult, RelatedContentSource } from './server-articles'
+export type { ValidationIssue, ValidationResult, ValidationSeverity } from './validateArticles'
+export type {
+  ArticleEvent,
+  ArticleEventHandler,
+  ArticleEventName,
+  ArticleViewedEvent,
+  MeaningfulReadEvent,
+  AuthorClickedEvent,
+  CtaViewedEvent,
+  CtaClickedEvent,
+  SharedEvent,
+  RelatedArticleClickedEvent,
+  PathStepAdvancedEvent,
+} from './events'
 export type {
   ArticlesErrorCode,
   ArticlesErrorContext,

package/src/validateArticles.ts

@@ -0,0 +1,260 @@
+// Package validator (Phase 27F). A pure function operating on an already
+// loaded `Article[]`/`ArticlesConfig` - no `fs` access here, so it's
+// directly unit-testable with fixture data. `validateAllArticles` below is
+// the thin, fs-dependent convenience wrapper (`server`-only, like the rest
+// of this file) for a consuming app's own validation script.
+import {
+  getAllArticles,
+  getArticleAuthors,
+  getAuthorBySlug,
+  categoryToSlug,
+} from './server-articles'
+import type { Article } from './articleTypes'
+import type { ArticlesConfig } from './articlesConfig'
+
+export type ValidationSeverity = 'error' | 'warning'
+
+export interface ValidationIssue {
+  severity: ValidationSeverity
+  /** Stable machine-readable code, e.g. `'duplicate-canonical-url'`. */
+  code: string
+  message: string
+  articleSlug?: string
+  pathKey?: string
+}
+
+export interface ValidationResult {
+  ok: boolean
+  errors: ValidationIssue[]
+  warnings: ValidationIssue[]
+}
+
+const UNSAFE_URL_SCHEME = /^\s*(javascript|data|vbscript):/i
+
+const SEARCH_TITLE_MAX = 60
+const SEARCH_DESCRIPTION_MAX = 160
+const SOCIAL_TITLE_MAX = 95
+const SOCIAL_DESCRIPTION_MAX = 200
+
+function isUnsafeUrl(href: string): boolean {
+  return UNSAFE_URL_SCHEME.test(href)
+}
+
+function checkDuplicateCanonicalUrls(articles: Article[]): ValidationIssue[] {
+  const seen = new Map<string, string>()
+  const issues: ValidationIssue[] = []
+  for (const article of articles) {
+    if (!article.canonicalUrl) continue
+    const owner = seen.get(article.canonicalUrl)
+    if (owner) {
+      issues.push({
+        severity: 'error',
+        code: 'duplicate-canonical-url',
+        message: `canonicalUrl "${article.canonicalUrl}" is also used by "${owner}".`,
+        articleSlug: article.slug,
+      })
+    } else {
+      seen.set(article.canonicalUrl, article.slug)
+    }
+  }
+  return issues
+}
+
+function checkAuthorReferences(articles: Article[], config: ArticlesConfig): ValidationIssue[] {
+  if (!config.authors || Object.keys(config.authors).length === 0) return []
+  const issues: ValidationIssue[] = []
+  for (const article of articles) {
+    for (const resolved of getArticleAuthors(article, config)) {
+      if (!getAuthorBySlug(resolved.slug, config)) {
+        issues.push({
+          severity: 'error',
+          code: 'unknown-author-reference',
+          message: `Author "${resolved.name}" does not match any entry in config.authors.`,
+          articleSlug: article.slug,
+        })
+      }
+    }
+  }
+  return issues
+}
+
+function checkSeriesCollisions(articles: Article[]): ValidationIssue[] {
+  const issues: ValidationIssue[] = []
+  const seenSlugOrder = new Map<string, string>()
+  for (const article of articles) {
+    if (!article.seriesSlug || article.seriesOrder === undefined) continue
+    const key = `${article.seriesSlug}::${article.seriesOrder}`
+    const owner = seenSlugOrder.get(key)
+    if (owner) {
+      issues.push({
+        severity: 'error',
+        code: 'duplicate-series-order',
+        message: `seriesOrder ${article.seriesOrder} in series "${article.seriesSlug}" collides with "${owner}".`,
+        articleSlug: article.slug,
+      })
+    } else {
+      seenSlugOrder.set(key, article.slug)
+    }
+  }
+  return issues
+}
+
+function checkPaths(articles: Article[], config: ArticlesConfig): ValidationIssue[] {
+  const issues: ValidationIssue[] = []
+  const bySlug = new Map(articles.map((article) => [article.slug, article]))
+  for (const [pathKey, path] of Object.entries(config.paths ?? {})) {
+    if (path.articles.length === 0) {
+      issues.push({
+        severity: 'error',
+        code: 'empty-path',
+        message: `Path "${pathKey}" has no articles.`,
+        pathKey,
+      })
+    }
+    for (const slug of path.articles) {
+      const referenced = bySlug.get(slug)
+      if (!referenced) {
+        issues.push({
+          severity: 'error',
+          code: 'path-missing-article',
+          message: `Path "${pathKey}" references missing article "${slug}".`,
+          pathKey,
+          articleSlug: slug,
+        })
+      } else if (referenced.draft) {
+        issues.push({
+          severity: 'error',
+          code: 'path-references-draft',
+          message: `Path "${pathKey}" references unpublished (draft) article "${slug}".`,
+          pathKey,
+          articleSlug: slug,
+        })
+      }
+    }
+    if (isUnsafeUrl(path.nextAction.href)) {
+      issues.push({
+        severity: 'error',
+        code: 'unsafe-url',
+        message: `Path "${pathKey}" nextAction.href uses an unsafe URL scheme.`,
+        pathKey,
+      })
+    }
+  }
+  return issues
+}
+
+function checkAuthorCtaUrls(config: ArticlesConfig): ValidationIssue[] {
+  const issues: ValidationIssue[] = []
+  for (const author of Object.values(config.authors ?? {})) {
+    if (author.primaryCta && isUnsafeUrl(author.primaryCta.href)) {
+      issues.push({
+        severity: 'error',
+        code: 'unsafe-url',
+        message: `Author "${author.slug}" primaryCta.href uses an unsafe URL scheme.`,
+      })
+    }
+  }
+  return issues
+}
+
+function checkRequiredFrontmatter(articles: Article[]): ValidationIssue[] {
+  const issues: ValidationIssue[] = []
+  for (const article of articles) {
+    if (!article.excerpt) {
+      issues.push({
+        severity: 'warning',
+        code: 'missing-excerpt',
+        message: 'Article has no excerpt.',
+        articleSlug: article.slug,
+      })
+    }
+    if (!article.date) {
+      issues.push({
+        severity: 'warning',
+        code: 'missing-date',
+        message: 'Article has no date.',
+        articleSlug: article.slug,
+      })
+    }
+  }
+  return issues
+}
+
+function checkDiscoveryFieldLengths(articles: Article[]): ValidationIssue[] {
+  const issues: ValidationIssue[] = []
+  for (const article of articles) {
+    const checks: [string | undefined, string, number][] = [
+      [article.searchTitle, 'search-title-too-long', SEARCH_TITLE_MAX],
+      [article.searchDescription, 'search-description-too-long', SEARCH_DESCRIPTION_MAX],
+      [article.socialTitle, 'social-title-too-long', SOCIAL_TITLE_MAX],
+      [article.socialDescription, 'social-description-too-long', SOCIAL_DESCRIPTION_MAX],
+    ]
+    for (const [value, code, max] of checks) {
+      if (value && value.length > max) {
+        issues.push({
+          severity: 'warning',
+          code,
+          message: `${code.replaceAll('-', ' ')} (${value.length} > ${max} recommended chars).`,
+          articleSlug: article.slug,
+        })
+      }
+    }
+  }
+  return issues
+}
+
+function checkCategorySlugs(articles: Article[]): ValidationIssue[] {
+  // Two differently-cased/spaced category labels that collapse to the same
+  // slug silently merge on `/articles/category/[slug]` - surfaced as a
+  // warning (not an error) since it may be intentional (e.g. "Game
+  // Masters" and "game-masters" tags both meaning the same category).
+  const issues: ValidationIssue[] = []
+  const slugToNames = new Map<string, Set<string>>()
+  for (const article of articles) {
+    for (const category of article.categories) {
+      const slug = categoryToSlug(category)
+      const names = slugToNames.get(slug) ?? new Set<string>()
+      names.add(category)
+      slugToNames.set(slug, names)
+    }
+  }
+  for (const [slug, names] of slugToNames) {
+    if (names.size > 1) {
+      issues.push({
+        severity: 'warning',
+        code: 'category-slug-collision',
+        message: `Categories [${[...names].join(', ')}] all collapse to slug "${slug}".`,
+      })
+    }
+  }
+  return issues
+}
+
+/**
+ * Validates a loaded article set + config. Warnings cover optional
+ * discovery-field issues (missing excerpt/date, over-length search/social
+ * fields, category slug collisions); errors cover broken reader journeys
+ * (duplicate canonical URLs, unknown author references, series order
+ * collisions, missing/draft path references, unsafe URL schemes).
+ */
+export function validateArticles(articles: Article[], config: ArticlesConfig): ValidationResult {
+  const errors = [
+    ...checkDuplicateCanonicalUrls(articles),
+    ...checkAuthorReferences(articles, config),
+    ...checkSeriesCollisions(articles),
+    ...checkPaths(articles, config),
+    ...checkAuthorCtaUrls(config),
+  ]
+  const warnings = [
+    ...checkRequiredFrontmatter(articles),
+    ...checkDiscoveryFieldLengths(articles),
+    ...checkCategorySlugs(articles),
+  ]
+  return { ok: errors.length === 0, errors, warnings }
+}
+
+/** Convenience wrapper: loads every article via `getAllArticles(config)` (fs-dependent) then validates. Suitable for a consuming app's own `scripts/validate-articles.ts` invoked in CI before publish. */
+export async function validateAllArticles(config: ArticlesConfig): Promise<ValidationResult> {
+  const articles = await getAllArticles(config)
+  return validateArticles(articles, config)
+}