@fullstackdatasolutions/articles 1.2.3 → 1.3.1

package/src/validateArticles.ts

@@ -10,7 +10,7 @@ import {
   categoryToSlug,
 } from './server-articles'
 import type { Article } from './articleTypes'
-import type { ArticlesConfig } from './articlesConfig'
+import { formatPageTitle, type ArticlesConfig } from './articlesConfig'
 
 export type ValidationSeverity = 'error' | 'warning'
 
@@ -31,6 +31,9 @@ export interface ValidationResult {
 
 const UNSAFE_URL_SCHEME = /^\s*(javascript|data|vbscript):/i
 
+const THIN_CONTENT_WORDS = 300
+const STALE_CONTENT_MONTHS = 18
+
 const SEARCH_TITLE_MAX = 60
 const SEARCH_DESCRIPTION_MAX = 160
 const SOCIAL_TITLE_MAX = 95
@@ -180,12 +183,28 @@ function checkRequiredFrontmatter(articles: Article[]): ValidationIssue[] {
   return issues
 }
 
-function checkDiscoveryFieldLengths(articles: Article[]): ValidationIssue[] {
+/**
+ * Length checks against what a search result actually renders, not just the
+ * optional overrides.
+ *
+ * Before 1.3.0 this only measured `searchTitle`/`searchDescription`, so a site
+ * that never set them (the common case) got no warnings at all while every
+ * one of its titles rendered over-length. The effective title is
+ * `titleTemplate` applied to `searchTitle ?? title`, and the effective
+ * description is `searchDescription ?? excerpt` - those are the strings a
+ * person sees, so those are what get measured.
+ */
+function checkDiscoveryFieldLengths(
+  articles: Article[],
+  config: ArticlesConfig
+): ValidationIssue[] {
   const issues: ValidationIssue[] = []
   for (const article of articles) {
+    const effectiveTitle = formatPageTitle(article.searchTitle ?? article.title, config)
+    const effectiveDescription = article.searchDescription ?? article.excerpt
     const checks: [string | undefined, string, number][] = [
-      [article.searchTitle, 'search-title-too-long', SEARCH_TITLE_MAX],
-      [article.searchDescription, 'search-description-too-long', SEARCH_DESCRIPTION_MAX],
+      [effectiveTitle, 'effective-title-too-long', SEARCH_TITLE_MAX],
+      [effectiveDescription, 'effective-description-too-long', SEARCH_DESCRIPTION_MAX],
       [article.socialTitle, 'social-title-too-long', SOCIAL_TITLE_MAX],
       [article.socialDescription, 'social-description-too-long', SOCIAL_DESCRIPTION_MAX],
     ]
@@ -203,6 +222,117 @@ function checkDiscoveryFieldLengths(articles: Article[]): ValidationIssue[] {
   return issues
 }
 
+// AEO checks. All warnings, never errors: each one flags content that will
+// still build and render correctly but is unlikely to be quotable, resolvable,
+// or trusted by an answer engine.
+function checkAnswerability(articles: Article[]): ValidationIssue[] {
+  const issues: ValidationIssue[] = []
+  for (const article of articles) {
+    const hasQuestionHeading = (article.toc ?? []).some(
+      (item) => item.depth === 2 && item.text.trim().endsWith('?')
+    )
+    if (!article.answer && !article.faq?.length && !hasQuestionHeading) {
+      issues.push({
+        severity: 'warning',
+        code: 'no-answer',
+        message:
+          'Article has no `answer`, no `faq`, and no question-shaped heading - nothing for an answer engine to lift.',
+        articleSlug: article.slug,
+      })
+    }
+    if (article.wordCount !== undefined && article.wordCount < THIN_CONTENT_WORDS) {
+      issues.push({
+        severity: 'warning',
+        code: 'thin-content',
+        message: `Article is ${article.wordCount} words (under ${THIN_CONTENT_WORDS}).`,
+        articleSlug: article.slug,
+      })
+    }
+    if (!article.about?.length) {
+      issues.push({
+        severity: 'warning',
+        code: 'missing-about',
+        message: 'Article has no `about` entity references.',
+        articleSlug: article.slug,
+      })
+    }
+  }
+  return issues
+}
+
+// `now` is injected rather than read from the clock so the check is
+// deterministic in tests and reproducible in CI.
+// `about` strings that hit no `config.entities` key still render as plain
+// names - the warning exists because that is how a corpus ends up with
+// "Pathfinder", "pathfinder", and "PF2e" as three separate entities.
+function checkEntityReferences(articles: Article[], config: ArticlesConfig): ValidationIssue[] {
+  const registry = config.entities
+  if (!registry) return []
+  const known = new Set(Object.values(registry).map((entity) => entity.name))
+  const issues: ValidationIssue[] = []
+  for (const article of articles) {
+    for (const entity of article.about ?? []) {
+      if (!known.has(entity.name) && !entity.sameAs) {
+        issues.push({
+          severity: 'warning',
+          code: 'unknown-entity',
+          message: `about entry "${entity.name}" is not in config.entities and has no sameAs.`,
+          articleSlug: article.slug,
+        })
+      }
+    }
+  }
+  return issues
+}
+
+function checkStaleContent(articles: Article[], now: Date): ValidationIssue[] {
+  const cutoff = new Date(now)
+  cutoff.setMonth(cutoff.getMonth() - STALE_CONTENT_MONTHS)
+  const issues: ValidationIssue[] = []
+  for (const article of articles) {
+    const stamp = article.lastmod ?? article.date
+    if (!stamp) continue
+    const parsed = new Date(stamp)
+    if (Number.isNaN(parsed.getTime())) continue
+    if (parsed < cutoff) {
+      issues.push({
+        severity: 'warning',
+        code: 'stale-content',
+        message: `Last updated ${stamp}, over ${STALE_CONTENT_MONTHS} months ago.`,
+        articleSlug: article.slug,
+      })
+    }
+  }
+  return issues
+}
+
+// An article no other article links to is reachable only from listing pages,
+// which is the weakest possible internal signal. Matches on the article's own
+// `/articles/<slug>` path appearing in any other article's raw body, so it
+// only runs for articles loaded with their `content` (i.e. via
+// `getArticleMetadata`, not `getAllArticles`' summaries).
+function checkOrphanArticles(articles: Article[]): ValidationIssue[] {
+  const bodies = articles.filter((article) => typeof article.content === 'string')
+  if (bodies.length === 0) return []
+
+  const issues: ValidationIssue[] = []
+  for (const article of articles) {
+    const needle = `/articles/${article.slug}`
+    const linked = bodies.some(
+      (other) => other.slug !== article.slug && other.content!.includes(needle)
+    )
+    if (!linked) {
+      issues.push({
+        severity: 'warning',
+        code: 'orphan-article',
+        message: 'No other article links to this one.',
+        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
@@ -232,12 +362,20 @@ function checkCategorySlugs(articles: Article[]): ValidationIssue[] {
 
 /**
  * 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).
+ * discovery-field issues (missing excerpt/date, over-length rendered title
+ * and meta description, over-length social fields, category slug collisions) and answer-engine readiness
+ * (`no-answer`, `thin-content`, `missing-about`, `unknown-entity`,
+ * `stale-content`, `orphan-article`); errors cover broken reader journeys (duplicate canonical
+ * URLs, unknown author references, series order collisions, missing/draft
+ * path references, unsafe URL schemes).
+ *
+ * `options.now` overrides the clock used by the `stale-content` check.
  */
-export function validateArticles(articles: Article[], config: ArticlesConfig): ValidationResult {
+export function validateArticles(
+  articles: Article[],
+  config: ArticlesConfig,
+  options?: Readonly<{ now?: Date }>
+): ValidationResult {
   const errors = [
     ...checkDuplicateCanonicalUrls(articles),
     ...checkAuthorReferences(articles, config),
@@ -247,14 +385,21 @@ export function validateArticles(articles: Article[], config: ArticlesConfig): V
   ]
   const warnings = [
     ...checkRequiredFrontmatter(articles),
-    ...checkDiscoveryFieldLengths(articles),
+    ...checkDiscoveryFieldLengths(articles, config),
+    ...checkAnswerability(articles),
+    ...checkEntityReferences(articles, config),
+    ...checkStaleContent(articles, options?.now ?? new Date()),
+    ...checkOrphanArticles(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> {
+export async function validateAllArticles(
+  config: ArticlesConfig,
+  options?: Readonly<{ now?: Date }>
+): Promise<ValidationResult> {
   const articles = await getAllArticles(config)
-  return validateArticles(articles, config)
+  return validateArticles(articles, config, options)
 }