feat(cli): add --require-meta flag to hard-fail on missing meta description (1.11.0) (#37) (#38)

Promotes a missing <meta name="description"> from an info-level
technical-seo finding to a hard exit-1 when --require-meta is passed,
so CI can gate on it even when the page otherwise scores >= 70.
Works in both single-URL and sitemap modes; sitemap mode lists the
offending URLs on stderr. Default behavior is unchanged.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: arberx

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.11.0 (2026-05-28)
+
+### Added
+- **`--require-meta` flag (#37).** New CI gate: when passed, the CLI exits `1` if any audited page lacks `<meta name="description">`, regardless of the overall (or aggregate) score-based exit rule. Previously a missing meta description surfaced as a `missing` finding under `technical-seo` but did not fail the run on otherwise-healthy sites, so the issue could silently pass CI. Works in both single-URL and sitemap modes; in sitemap mode the failure lists the offending URLs (truncated to the first three) on stderr.
+
 ## 1.10.0 (2026-05-23)
 
 ### Added

README.md

@@ -92,6 +92,10 @@ npx @ainyc/aeo-audit https://example.com --lighthouse
 
 # Provide a PageSpeed Insights API key to lift anonymous rate limits
 PAGESPEED_API_KEY=xxx npx @ainyc/aeo-audit https://example.com --lighthouse --format json
+
+# Force exit 1 when meta description is missing (CI gate)
+npx @ainyc/aeo-audit https://example.com --require-meta
+npx @ainyc/aeo-audit https://example.com --sitemap --require-meta
 ```
 
 ### Platform Detection Mode
@@ -183,9 +187,10 @@ When fetching `/llms.txt`, `/llms-full.txt`, `/robots.txt`, and `/sitemap.xml` t
 | `--urls <src>` | In `--detect-platform` mode, run on multiple URLs. `<src>` is a file path (one URL per line), a comma-separated list, or `-` for stdin |
 | `--concurrency <n>` | In `--detect-platform` batch mode, max in-flight fetches (default 5) |
 | `--min-confidence <lvl>` | In platform-detect mode, only report matches at or above this level: `low` (default), `medium`, `high` |
+| `--require-meta` | Exit `1` if any audited page is missing `<meta name="description">`, regardless of the overall score. Works in both single-URL and sitemap modes. |
 | `-h`, `--help` | Show the help message |
 
-Exit code `0` for score >= 70, `1` for < 70 (CI-friendly). In sitemap mode the exit code is based on the aggregate score.
+Exit code `0` for score >= 70, `1` for < 70 (CI-friendly). In sitemap mode the exit code is based on the aggregate score. When `--require-meta` is passed, exit is forced to `1` if any audited page lacks `<meta name="description">`, regardless of the score-based rule.
 
 ## Programmatic Usage
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainyc/aeo-audit",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "The most comprehensive open-source Answer Engine Optimization (AEO) audit tool. Scores websites across 16 ranking factors that determine AI citation.",
   "type": "module",
   "main": "./dist/index.js",

skills/aeo/SKILL.md

@@ -53,6 +53,8 @@ If no mode is provided, default to `audit`.
 - `audit https://example.com --sitemap --limit 10`
 - `audit https://example.com --sitemap --top-issues`
 - `audit https://example.com --lighthouse`
+- `audit https://example.com --require-meta`
+- `audit https://example.com --sitemap --require-meta`
 - `fix https://example.com`
 - `schema https://example.com`
 - `llms https://example.com`
@@ -83,6 +85,10 @@ Use for broad requests such as "audit this site" or "why am I not being cited?"
    - Top fixes
    - Metadata such as fetch time and auxiliary file availability
 
+#### `--require-meta` (CI gate)
+
+Pass `--require-meta` (single or sitemap mode) to force exit `1` whenever any audited page is missing `<meta name="description">`, regardless of the otherwise score-based exit rule. Useful in CI pipelines that need to block deploys on a missing meta description even on otherwise-healthy sites.
+
 ### Sitemap Mode
 
 Use `--sitemap` to audit all pages discovered from the site's sitemap:
@@ -98,6 +104,7 @@ Flags:
 - `--sitemap [url]` — auto-discover the sitemap (tries `/sitemap.xml`, then `/sitemap-index.xml`, then `Sitemap:` directives in `/robots.txt`) or provide an explicit URL
 - `--limit <n>` — cap pages audited (default 200, sorted by sitemap priority)
 - `--top-issues` — skip per-page output, show only cross-cutting patterns
+- `--require-meta` — force exit `1` if any audited page is missing `<meta name="description">`, regardless of overall score (useful as a CI gate)
 
 Pages are audited with bounded concurrency (5 in flight) to avoid hammering the target origin.
 

src/cli.ts

@@ -25,6 +25,7 @@ import type {
   BatchPlatformDetectionReport,
   PlatformConfidence,
   PlatformDetectionReport,
+  ScoredFactor,
   SitemapAuditOptions,
   SitemapAuditReport,
 } from './types.js'
@@ -71,6 +72,7 @@ interface ParsedArgs {
   minConfidence: PlatformConfidence | null
   urls: string | null
   concurrency: number | null
+  requireMeta: boolean
 }
 
 function isFormatterName(value: string): value is FormatterName {
@@ -95,6 +97,7 @@ function parseArgs(argv: string[]): ParsedArgs {
     minConfidence: null,
     urls: null,
     concurrency: null,
+    requireMeta: false,
   }
 
   for (let i = 0; i < args.length; i += 1) {
@@ -142,6 +145,8 @@ function parseArgs(argv: string[]): ParsedArgs {
         result.concurrency = num
       }
       i += 1
+    } else if (args[i] === '--require-meta') {
+      result.requireMeta = true
     } else if (args[i] === '--help' || args[i] === '-h') {
       result.help = true
     } else if (!args[i].startsWith('-')) {
@@ -152,6 +157,15 @@ function parseArgs(argv: string[]): ParsedArgs {
   return result
 }
 
+export function hasMissingMetaDescription(factors: ScoredFactor[] | undefined): boolean {
+  if (!factors) return false
+  const tech = factors.find((f) => f.id === 'technical-seo')
+  if (!tech) return false
+  return tech.findings.some(
+    (f) => f.type === 'missing' && f.message.startsWith('No meta description found'),
+  )
+}
+
 export function parseUrlList(text: string): string[] {
   const urls: string[] = []
   for (const rawLine of text.split(/\r?\n/)) {
@@ -212,6 +226,8 @@ Options:
   --concurrency <n>       In --detect-platform batch mode, max in-flight fetches (default 5).
   --min-confidence <lvl>  In platform-detect mode, only report platforms at or above this
                           confidence level: low (default), medium, high.
+  --require-meta          Exit 1 if any audited page is missing <meta name="description">,
+                          regardless of overall score. Works in both single-URL and sitemap modes.
   -h, --help              Show this help message
 
 Examples:
@@ -227,6 +243,8 @@ Examples:
   aeo-audit https://example.com --sitemap https://example.com/sitemap.xml
   aeo-audit https://example.com --sitemap --limit 10
   aeo-audit https://example.com --sitemap --top-issues
+  aeo-audit https://example.com --require-meta
+  aeo-audit https://example.com --sitemap --require-meta
   aeo-audit https://example.com --detect-platform
   aeo-audit https://example.com --detect-platform --format json
   aeo-audit https://example.com --detect-platform --min-confidence medium
@@ -237,6 +255,8 @@ Examples:
 Exit code: 0 when score >= 70, 1 otherwise. In sitemap mode, the aggregate score is used.
 In --detect-platform mode, exit code is 0 if any platform is detected, 1 otherwise.
 In --detect-platform batch mode, exit code is 0 if at least one URL succeeded, 1 otherwise.
+With --require-meta, exit is 1 if any audited page is missing <meta name="description">,
+regardless of the score-based rule above.
 `)
 }
 
@@ -329,6 +349,22 @@ export async function main(argv: string[] = process.argv): Promise<number> {
       const report = await runSitemapAudit(args.url, options)
       const sitemapFormatter = SITEMAP_FORMATTERS[args.format]
       console.log(sitemapFormatter(report, args.topIssues))
+
+      if (args.requireMeta) {
+        const missingPages = report.pages.filter(
+          (p) => p.status === 'success' && hasMissingMetaDescription(p.factors),
+        )
+        if (missingPages.length > 0) {
+          console.error(
+            `Error: --require-meta failed. ${missingPages.length} page(s) missing <meta name="description">: ${missingPages
+              .slice(0, 3)
+              .map((p) => p.url)
+              .join(', ')}${missingPages.length > 3 ? ` (+${missingPages.length - 3} more)` : ''}`,
+          )
+          return 1
+        }
+      }
+
       return report.aggregateScore >= 70 ? 0 : 1
     }
 
@@ -341,6 +377,12 @@ export async function main(argv: string[] = process.argv): Promise<number> {
     })
 
     console.log(formatter(report))
+
+    if (args.requireMeta && hasMissingMetaDescription(report.factors)) {
+      console.error(`Error: --require-meta failed. Page is missing <meta name="description">: ${report.finalUrl}`)
+      return 1
+    }
+
     return report.overallScore >= 70 ? 0 : 1
   } catch (error) {
     if (isAeoAuditError(error)) {

test/cli-require-meta.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest'
+
+import { hasMissingMetaDescription } from '../src/cli.js'
+import type { ScoredFactor } from '../src/types.js'
+
+function technicalSeoFactor(
+  findings: ScoredFactor['findings'],
+): ScoredFactor {
+  return {
+    id: 'technical-seo',
+    name: 'Technical SEO',
+    weight: 5,
+    score: 50,
+    grade: 'D',
+    status: 'partial',
+    findings,
+    recommendations: [],
+  }
+}
+
+describe('hasMissingMetaDescription', () => {
+  it('returns false when factors are undefined', () => {
+    expect(hasMissingMetaDescription(undefined)).toBe(false)
+  })
+
+  it('returns false when technical-seo factor is absent', () => {
+    expect(
+      hasMissingMetaDescription([
+        {
+          id: 'structured-data',
+          name: 'Structured Data',
+          weight: 10,
+          score: 80,
+          grade: 'B',
+          status: 'pass',
+          findings: [],
+          recommendations: [],
+        },
+      ]),
+    ).toBe(false)
+  })
+
+  it('returns true when technical-seo has a missing-meta-description finding', () => {
+    expect(
+      hasMissingMetaDescription([
+        technicalSeoFactor([{ type: 'missing', message: 'No meta description found.' }]),
+      ]),
+    ).toBe(true)
+  })
+
+  it('returns false when meta description is present (any length)', () => {
+    expect(
+      hasMissingMetaDescription([
+        technicalSeoFactor([
+          { type: 'found', message: 'Meta description present (152 chars).' },
+        ]),
+      ]),
+    ).toBe(false)
+  })
+
+  it('returns false when meta description is merely short (info-level finding)', () => {
+    expect(
+      hasMissingMetaDescription([
+        technicalSeoFactor([
+          {
+            type: 'info',
+            message: 'Meta description is too short (90 chars; target 150–160): "..."',
+          },
+        ]),
+      ]),
+    ).toBe(false)
+  })
+
+  it('returns false when finding type is missing but unrelated message', () => {
+    expect(
+      hasMissingMetaDescription([
+        technicalSeoFactor([
+          { type: 'missing', message: 'No canonical tag found.' },
+        ]),
+      ]),
+    ).toBe(false)
+  })
+})

test/e2e/cli.test.ts

@@ -125,6 +125,35 @@ function captureConsole(t: TestContext): { stdout: string[]; stderr: string[] }
   return { stdout, stderr }
 }
 
+test('--require-meta forces exit 1 when the fixture has no <meta name="description">', async (t) => {
+  installMockClock(t)
+  installMockFetch(t)
+  const { stdout, stderr } = captureConsole(t)
+  const { main } = await import(new URL('../../dist/cli.js', import.meta.url).href)
+
+  const exitCode = await main([
+    'node',
+    'aeo-audit',
+    FIXTURE_URL,
+    '--format',
+    'json',
+    '--require-meta',
+  ])
+
+  assert.equal(exitCode, 1, 'expected exit 1 because fixture HTML has no meta description')
+  assert.equal(stdout.length, 1, 'report still printed before failure')
+  assert.ok(
+    stderr.some((line) => line.includes('--require-meta failed')),
+    'stderr should mention --require-meta failure',
+  )
+
+  const report = JSON.parse(stdout[0]) as AuditReport
+  assert.ok(
+    report.overallScore >= 70,
+    'sanity check: fixture would otherwise pass the score-based exit rule',
+  )
+})
+
 test('compiled CLI returns the expected JSON report for the fixture site', async (t) => {
   installMockClock(t)
   installMockFetch(t)