@nebulacomponents/citable 0.1.0

package/src/detectors/page.js

@@ -0,0 +1,202 @@
+import { defineDetector, indexTargets, pageSubject } from './framework.js';
+
+const D = [];
+
+D.push(defineDetector({
+  id: 'PAGE-001', name: 'Missing title element', namespace: 'PAGE',
+  description: 'Index-target page has no <title>.',
+  discipline: ['seo', 'aeo'], severity: 'high', deterministic: true, requires: ['site'],
+  impact: { ranking: 'high', representation: 'medium' },
+  applicable_requirement: 'SEO §2 unique and accurate title; §5 title element',
+  remediation: 'Add a concise title identifying the page subject and distinguishing it from other pages.',
+  verification: 'Confirm a non-empty <title> in rendered HTML.',
+  check(ctx) {
+    return indexTargets(ctx).filter((p) => p.status === 200 && !p.title).map((p) => ({
+      subject: pageSubject(p), summary: 'Page has no title element', evidence: ['<title> absent or empty'],
+    }));
+  },
+}));
+
+D.push(defineDetector({
+  id: 'PAGE-002', name: 'Duplicate title across pages', namespace: 'PAGE',
+  description: 'Two or more index-target pages share an identical title.',
+  discipline: ['seo'], severity: 'medium', deterministic: true, requires: ['site'],
+  impact: { ranking: 'medium' },
+  applicable_requirement: 'SEO §5 title should distinguish the page from other pages; avoid boilerplate duplication',
+  remediation: 'Differentiate titles to reflect each page’s distinct intent.',
+  verification: 'Confirm title uniqueness across index targets.',
+  check(ctx) {
+    const byTitle = new Map();
+    for (const p of indexTargets(ctx)) {
+      if (!p.title || p.status !== 200) continue;
+      if (!byTitle.has(p.title)) byTitle.set(p.title, []);
+      byTitle.get(p.title).push(p);
+    }
+    return [...byTitle.entries()].filter(([, ps]) => ps.length > 1).map(([title, ps]) => ({
+      subject: { type: 'site', identifier: `title:${title}` },
+      summary: `${ps.length} pages share the title "${title}"`,
+      evidence: ps.map((p) => p.url),
+    }));
+  },
+}));
+
+D.push(defineDetector({
+  id: 'PAGE-003', name: 'Missing meta description', namespace: 'PAGE',
+  description: 'Index-target page lacks a meta description (search-result copy).',
+  discipline: ['seo'], severity: 'low', deterministic: true, requires: ['site'],
+  impact: { conversion: 'low', ranking: 'none' },
+  applicable_requirement: 'SEO §5 meta description as search-result copy, not a ranking lever',
+  remediation: 'Add an accurate, page-specific description stating the expected value.',
+  verification: 'Confirm meta[name=description] present and non-empty.',
+  check(ctx) {
+    return indexTargets(ctx).filter((p) => p.status === 200 && !p.metaDescription).map((p) => ({
+      subject: pageSubject(p), summary: 'Page has no meta description', evidence: ['meta[name=description] absent'],
+    }));
+  },
+}));
+
+D.push(defineDetector({
+  id: 'PAGE-004', name: 'Duplicate meta description', namespace: 'PAGE',
+  description: 'Multiple pages share an identical meta description.',
+  discipline: ['seo'], severity: 'low', deterministic: true, requires: ['site'],
+  impact: { conversion: 'low' },
+  applicable_requirement: 'SEO §5 avoid duplicated descriptions',
+  remediation: 'Write distinct descriptions per page.',
+  verification: 'Confirm description uniqueness.',
+  check(ctx) {
+    const byDesc = new Map();
+    for (const p of indexTargets(ctx)) {
+      if (!p.metaDescription || p.status !== 200) continue;
+      if (!byDesc.has(p.metaDescription)) byDesc.set(p.metaDescription, []);
+      byDesc.get(p.metaDescription).push(p);
+    }
+    return [...byDesc.entries()].filter(([, ps]) => ps.length > 1).map(([desc, ps]) => ({
+      subject: { type: 'site', identifier: `description:${desc.slice(0, 40)}` },
+      summary: `${ps.length} pages share the same meta description`,
+      evidence: ps.map((p) => p.url),
+    }));
+  },
+}));
+
+D.push(defineDetector({
+  id: 'PAGE-005', name: 'Missing or multiple H1', namespace: 'PAGE',
+  description: 'Page does not have exactly one primary heading.',
+  discipline: ['seo', 'aeo'], severity: 'medium', deterministic: true, requires: ['site'],
+  impact: { ranking: 'low', citation: 'low' },
+  applicable_requirement: 'SEO §2 one clear primary heading; §5 primary heading',
+  remediation: 'Use exactly one H1 that identifies the page purpose.',
+  verification: 'Count H1 elements.',
+  check(ctx) {
+    return indexTargets(ctx).filter((p) => p.status === 200 && p.h1s.length !== 1).map((p) => ({
+      subject: pageSubject(p),
+      summary: p.h1s.length === 0 ? 'Page has no H1' : `Page has ${p.h1s.length} H1 elements`,
+      evidence: p.h1s.length ? p.h1s.map((h) => `H1: ${h.text}`) : ['no <h1> found'],
+      captured: p.h1s.length, expected: 1,
+    }));
+  },
+}));
+
+D.push(defineDetector({
+  id: 'PAGE-006', name: 'Heading hierarchy skip', namespace: 'PAGE',
+  description: 'Heading levels skip (e.g., H1 → H3), indicating headings used for visual size rather than document structure.',
+  discipline: ['seo', 'aeo'], severity: 'low', deterministic: true, requires: ['site'],
+  impact: { citation: 'low' },
+  applicable_requirement: 'SEO §5 headings represent real document hierarchy',
+  remediation: 'Restructure headings to descend one level at a time.',
+  verification: 'Walk heading sequence and confirm no level is skipped.',
+  check(ctx) {
+    const hits = [];
+    for (const p of indexTargets(ctx)) {
+      if (p.status !== 200) continue;
+      let prev = 0;
+      for (const h of p.headings) {
+        if (prev > 0 && h.level > prev + 1) {
+          hits.push({
+            subject: pageSubject(p),
+            summary: `Heading hierarchy skips from H${prev} to H${h.level} ("${h.text.slice(0, 60)}")`,
+            evidence: [`sequence: H${prev} → H${h.level}`],
+          });
+          break;
+        }
+        prev = h.level;
+      }
+    }
+    return hits;
+  },
+}));
+
+D.push(defineDetector({
+  id: 'PAGE-007', name: 'Image missing alt text', namespace: 'PAGE',
+  description: 'Content images lack alt attributes.',
+  discipline: ['seo'], severity: 'low', deterministic: true, requires: ['site'],
+  impact: { ranking: 'low', representation: 'low' },
+  applicable_requirement: 'SEO §5 images: appropriate alt text; accessibility preservation (premise 3.7)',
+  remediation: 'Add descriptive alt text (or empty alt for purely decorative images, reviewed case by case).',
+  verification: 'Confirm every <img> has an alt attribute.',
+  check(ctx) {
+    return indexTargets(ctx)
+      .map((p) => ({ p, missing: p.images.filter((i) => i.alt === undefined || i.alt === null) }))
+      .filter(({ p, missing }) => p.status === 200 && missing.length > 0)
+      .map(({ p, missing }) => ({
+        subject: pageSubject(p),
+        summary: `${missing.length} image(s) without alt attribute`,
+        evidence: missing.slice(0, 5).map((i) => `img src=${i.src}`),
+      }));
+  },
+}));
+
+D.push(defineDetector({
+  id: 'PAGE-008', name: 'Thin index-target content', namespace: 'PAGE',
+  description: 'An index-target page has very little primary text.',
+  discipline: ['seo', 'aeo'], severity: 'medium', deterministic: false, requires: ['site'],
+  impact: { ranking: 'medium', citation: 'medium' },
+  applicable_requirement: 'SEO §2 meaningful main content; §4 sufficient depth',
+  false_positive_conditions: ['intentionally short pages (contact, legal index) — classify them in the page registry'],
+  remediation: 'Either add substantive content for the intent or remove the page from the index target set.',
+  verification: 'Re-measure extracted word count after revision.',
+  check(ctx) {
+    const min = ctx.config?.audit?.thin_content_words ?? 120;
+    return indexTargets(ctx)
+      .filter((p) => p.status === 200 && p.wordCount > 0 && p.wordCount < min)
+      .map((p) => ({
+        subject: pageSubject(p),
+        summary: `Index-target page has only ~${p.wordCount} words (threshold ${min})`,
+        evidence: [`extracted word count: ${p.wordCount}`],
+        confidence: 'high',
+      }));
+  },
+}));
+
+D.push(defineDetector({
+  id: 'PAGE-009', name: 'Keyword stuffing', namespace: 'PAGE',
+  description: 'A single non-trivial term dominates the page text at a frequency inconsistent with natural prose.',
+  discipline: ['seo'], severity: 'medium', deterministic: false, requires: ['site'],
+  impact: { ranking: 'medium', reputational: 'low' },
+  applicable_requirement: 'SEO §5 semantic coverage, not term-frequency quotas; anti-pattern library: keyword stuffing',
+  false_positive_conditions: ['glossaries and reference pages legitimately repeating a defined term'],
+  remediation: 'Rewrite for human comprehension; vary phrasing naturally; do not chase term-frequency quotas.',
+  verification: 'Re-measure dominant-term density.',
+  check(ctx) {
+    const hits = [];
+    for (const p of indexTargets(ctx)) {
+      if (p.status !== 200 || p.wordCount < 80) continue;
+      const words = p.text.toLowerCase().match(/[a-z][a-z-]{3,}/g) || [];
+      const freq = new Map();
+      for (const w of words) freq.set(w, (freq.get(w) || 0) + 1);
+      const stop = new Set(['this', 'that', 'with', 'from', 'have', 'your', 'about', 'more', 'when', 'they', 'their', 'will', 'which', 'into', 'than', 'them', 'these', 'those', 'because', 'does', 'were', 'been', 'also', 'such', 'other']);
+      let top = null;
+      for (const [w, n] of freq) if (!stop.has(w) && (!top || n > top[1])) top = [w, n];
+      if (top && top[1] / words.length > 0.08 && top[1] >= 10) {
+        hits.push({
+          subject: pageSubject(p),
+          summary: `Term "${top[0]}" is ${(100 * top[1] / words.length).toFixed(1)}% of page words (${top[1]} occurrences)`,
+          evidence: [`density ${(100 * top[1] / words.length).toFixed(1)}% exceeds 8% threshold`],
+          confidence: 'medium',
+        });
+      }
+    }
+    return hits;
+  },
+}));
+
+export default D;

package/src/detectors/schemaData.js

@@ -0,0 +1,249 @@
+import { defineDetector, indexTargets, pageSubject, safePath } from './framework.js';
+import { isPastDate } from '../shared/io.js';
+
+const D = [];
+
+D.push(defineDetector({
+  id: 'SCHEMA-001', name: 'JSON-LD parse failure', namespace: 'SCHEMA',
+  description: 'A JSON-LD script block does not parse as JSON.',
+  discipline: ['seo', 'aeo', 'geo'], severity: 'high', deterministic: true, requires: ['site'],
+  impact: { ranking: 'medium', representation: 'medium' },
+  applicable_requirement: 'SEO §7 schema validation in CI/CD; detector spec: JSON-LD parse failure',
+  remediation: 'Fix the JSON syntax; generate JSON-LD from data structures rather than hand-edited strings.',
+  verification: 'All ld+json blocks parse.',
+  check(ctx) {
+    const hits = [];
+    for (const p of ctx.site.pages) {
+      for (const j of p.jsonLd) {
+        if (j.parseError) {
+          hits.push({
+            subject: { type: 'schema_block', identifier: `${p.url}#ld+json`, url: p.url, ...(p.sourceFile ? { source_file: p.sourceFile } : {}) },
+            summary: `JSON-LD block fails to parse: ${j.parseError}`,
+            evidence: [`parse error: ${j.parseError}`, `block head: ${j.raw.slice(0, 120)}`],
+          });
+        }
+      }
+    }
+    return hits;
+  },
+}));
+
+D.push(defineDetector({
+  id: 'SCHEMA-002', name: 'Schema headline/name mismatch with visible content', namespace: 'SCHEMA',
+  description: 'Article/WebPage headline in JSON-LD does not match the visible title or H1.',
+  discipline: ['seo', 'aeo'], severity: 'medium', deterministic: true, requires: ['site'],
+  impact: { representation: 'medium' },
+  applicable_requirement: 'Premise 3.4: structured data must match visible content; SEO §7 no invisible marked-up claims',
+  remediation: 'Generate the headline from the same authoritative field that renders the visible title.',
+  verification: 'Schema headline equals visible title or H1.',
+  check(ctx) {
+    const hits = [];
+    for (const p of indexTargets(ctx)) {
+      for (const j of p.jsonLd) {
+        for (const b of j.blocks) {
+          const type = [].concat(b['@type'] || []).join(',');
+          if (!/Article|BlogPosting|TechArticle|WebPage/i.test(type)) continue;
+          const headline = b.headline || b.name;
+          if (!headline) continue;
+          const visible = [p.title, ...(p.h1s.map((h) => h.text))].filter(Boolean).map((s) => s.toLowerCase().trim());
+          if (!visible.some((v) => v.includes(String(headline).toLowerCase().trim()) || String(headline).toLowerCase().trim().includes(v))) {
+            hits.push({
+              subject: { type: 'schema_block', identifier: `${p.url}#${type}`, url: p.url },
+              summary: `Schema headline "${headline}" does not match visible title or H1`,
+              evidence: [`schema headline: ${headline}`, `visible title: ${p.title}`, `H1: ${p.h1s.map((h) => h.text).join(' | ') || 'none'}`],
+            });
+          }
+        }
+      }
+    }
+    return hits;
+  },
+}));
+
+D.push(defineDetector({
+  id: 'SCHEMA-003', name: 'Schema URL conflicts with canonical', namespace: 'SCHEMA',
+  description: 'JSON-LD url/mainEntityOfPage disagrees with the page canonical.',
+  discipline: ['seo'], severity: 'medium', deterministic: true, requires: ['site'],
+  impact: { ranking: 'medium' },
+  applicable_requirement: 'SEO §2 canonical signals should agree across structured data URLs',
+  remediation: 'Emit the canonical URL in structured data.',
+  verification: 'Schema url matches rel=canonical.',
+  check(ctx) {
+    const hits = [];
+    for (const p of indexTargets(ctx)) {
+      if (p.canonicals.length !== 1) continue;
+      const canon = safePath(p.canonicals[0], p.url);
+      for (const j of p.jsonLd) {
+        for (const b of j.blocks) {
+          const u = typeof b.url === 'string' ? b.url : typeof b.mainEntityOfPage === 'string' ? b.mainEntityOfPage : b.mainEntityOfPage?.['@id'];
+          if (u && /WebPage|Article|BlogPosting|TechArticle/i.test([].concat(b['@type'] || []).join(',')) && safePath(u, p.url) !== canon) {
+            hits.push({
+              subject: { type: 'schema_block', identifier: `${p.url}#url`, url: p.url },
+              summary: `Schema URL ${u} conflicts with canonical ${p.canonicals[0]}`,
+              evidence: [`schema url: ${u}`, `canonical: ${p.canonicals[0]}`],
+            });
+          }
+        }
+      }
+    }
+    return hits;
+  },
+}));
+
+D.push(defineDetector({
+  id: 'SCHEMA-004', name: 'Inaccurate schema dates', namespace: 'SCHEMA',
+  description: 'datePublished is in the future, or dateModified precedes datePublished.',
+  discipline: ['seo', 'aeo'], severity: 'medium', deterministic: true, requires: ['site'],
+  impact: { representation: 'medium' },
+  applicable_requirement: 'SEO §7 accurate dates; AEO §8 do not update dates without material updates',
+  remediation: 'Derive dates from the content system of record.',
+  verification: 'datePublished ≤ dateModified ≤ now.',
+  check(ctx) {
+    const now = ctx.refDate ?? new Date();
+    const hits = [];
+    for (const p of ctx.site.pages) {
+      for (const j of p.jsonLd) {
+        for (const b of j.blocks) {
+          const pub = b.datePublished ? new Date(b.datePublished) : null;
+          const mod = b.dateModified ? new Date(b.dateModified) : null;
+          if (pub && !Number.isNaN(pub.getTime()) && pub > now) {
+            hits.push({
+              subject: { type: 'schema_block', identifier: `${p.url}#datePublished`, url: p.url },
+              summary: `datePublished ${b.datePublished} is in the future`,
+              evidence: [`datePublished: ${b.datePublished}; audit reference date: ${now.toISOString().slice(0, 10)}`],
+            });
+          }
+          if (pub && mod && !Number.isNaN(pub.getTime()) && !Number.isNaN(mod.getTime()) && mod < pub) {
+            hits.push({
+              subject: { type: 'schema_block', identifier: `${p.url}#dateModified`, url: p.url },
+              summary: `dateModified ${b.dateModified} precedes datePublished ${b.datePublished}`,
+              evidence: [`dateModified: ${b.dateModified}; datePublished: ${b.datePublished}`],
+            });
+          }
+        }
+      }
+    }
+    return hits;
+  },
+}));
+
+D.push(defineDetector({
+  id: 'SCHEMA-005', name: 'Rating/review markup without visible reviews', namespace: 'SCHEMA',
+  description: 'aggregateRating or review markup exists but the visible page contains no review content.',
+  discipline: ['seo'], severity: 'critical', deterministic: true, requires: ['site'],
+  impact: { legal: 'high', reputational: 'high', ranking: 'medium' },
+  applicable_requirement: 'Premise 3.4: no fabricated ratings or reviews; SEO §7 required controls',
+  remediation: 'Remove the rating markup unless genuine, visible, attributable reviews exist.',
+  unsafe_shortcuts: ['keeping the markup and adding boilerplate "reviews" text'],
+  verification: 'Rating markup exists only alongside visible review content.',
+  check(ctx) {
+    const reviewRx = /\b(review(s|ed)?|rating|testimonial)\b/i;
+    const hits = [];
+    for (const p of ctx.site.pages) {
+      for (const j of p.jsonLd) {
+        for (const b of j.blocks) {
+          if ((b.aggregateRating || b.review) && !reviewRx.test(p.text)) {
+            hits.push({
+              subject: { type: 'schema_block', identifier: `${p.url}#aggregateRating`, url: p.url },
+              summary: 'Rating/review markup present but no visible review content on the page',
+              evidence: [`schema contains ${b.aggregateRating ? 'aggregateRating' : 'review'}`, 'page text contains no review/rating/testimonial content'],
+            });
+          }
+        }
+      }
+    }
+    return hits;
+  },
+}));
+
+D.push(defineDetector({
+  id: 'SCHEMA-006', name: 'Stale offer price validity', namespace: 'SCHEMA',
+  description: 'Offer markup carries a priceValidUntil in the past.',
+  discipline: ['seo', 'geo'], severity: 'medium', deterministic: true, requires: ['site'],
+  impact: { representation: 'high', conversion: 'medium' },
+  applicable_requirement: 'Premise 3.4: avoid stale prices or availability; GEO §11 pricing: immediate on change',
+  remediation: 'Regenerate offers from live commercial data; remove expired offers.',
+  verification: 'No offer has priceValidUntil in the past.',
+  check(ctx) {
+    const hits = [];
+    for (const p of ctx.site.pages) {
+      for (const j of p.jsonLd) {
+        for (const b of j.blocks) {
+          const offers = [].concat(b.offers || []);
+          for (const o of offers) {
+            if (o && o.priceValidUntil && isPastDate(o.priceValidUntil, ctx.refDate)) {
+              hits.push({
+                subject: { type: 'schema_block', identifier: `${p.url}#offers`, url: p.url },
+                summary: `Offer priceValidUntil ${o.priceValidUntil} is in the past`,
+                evidence: [`priceValidUntil: ${o.priceValidUntil}; price: ${o.price ?? '?'}`],
+              });
+            }
+          }
+        }
+      }
+    }
+    return hits;
+  },
+}));
+
+D.push(defineDetector({
+  id: 'SCHEMA-007', name: 'FAQPage markup without matching visible questions', namespace: 'SCHEMA',
+  description: 'FAQPage JSON-LD questions do not appear in the visible page text.',
+  discipline: ['seo', 'aeo'], severity: 'high', deterministic: true, requires: ['site'],
+  impact: { legal: 'medium', ranking: 'medium' },
+  applicable_requirement: 'AEO §6 do not deploy mass-generated FAQ schema; anti-pattern: FAQ schema without substantive FAQ content',
+  remediation: 'Only mark up FAQs that are visible, substantive page content.',
+  verification: 'Every FAQPage question string appears in visible text.',
+  check(ctx) {
+    const hits = [];
+    for (const p of ctx.site.pages) {
+      for (const j of p.jsonLd) {
+        for (const b of j.blocks) {
+          if (![].concat(b['@type'] || []).includes('FAQPage')) continue;
+          const questions = [].concat(b.mainEntity || []).map((q) => q?.name).filter(Boolean);
+          const missing = questions.filter((q) => !p.text.toLowerCase().includes(String(q).toLowerCase().slice(0, 40)));
+          if (questions.length > 0 && missing.length > 0) {
+            hits.push({
+              subject: { type: 'schema_block', identifier: `${p.url}#FAQPage`, url: p.url },
+              summary: `${missing.length}/${questions.length} FAQ schema questions not found in visible content`,
+              evidence: missing.slice(0, 3).map((q) => `not visible: "${q}"`),
+            });
+          }
+        }
+      }
+    }
+    return hits;
+  },
+}));
+
+D.push(defineDetector({
+  id: 'SCHEMA-008', name: 'Contradictory Organization graphs', namespace: 'SCHEMA',
+  description: 'Multiple Organization blocks exist with the same @id but different names, or different @id values with the same name (split identity).',
+  discipline: ['geo', 'seo'], severity: 'high', deterministic: true, requires: ['site'],
+  impact: { representation: 'high' },
+  applicable_requirement: 'Detector spec: multiple contradictory entity graphs; GEO §9 graph consistency',
+  remediation: 'Emit one shared Organization node from a single data source; reference it by @id everywhere else.',
+  verification: 'One @id ↔ one name for the organization across all pages.',
+  check(ctx) {
+    const byId = new Map();
+    for (const p of ctx.site.pages) {
+      for (const j of p.jsonLd) {
+        for (const b of j.blocks) {
+          if (!/Organization|Corporation/i.test([].concat(b['@type'] || []).join(','))) continue;
+          if (!b['@id'] || !b.name) continue;
+          if (!byId.has(b['@id'])) byId.set(b['@id'], new Set());
+          byId.get(b['@id']).add(String(b.name));
+        }
+      }
+    }
+    return [...byId.entries()]
+      .filter(([, names]) => names.size > 1)
+      .map(([id, names]) => ({
+        subject: { type: 'schema_block', identifier: id },
+        summary: `Organization @id ${id} carries ${names.size} different names: ${[...names].join(' / ')}`,
+        evidence: [...names].map((n) => `name: ${n}`),
+      }));
+  },
+}));
+
+export default D;