@nebulacomponents/citable 1.16.0 → 1.18.0

package/src/analysis/schemaRecommendations.js

@@ -0,0 +1,173 @@
+import { parse as parseHtml } from 'node-html-parser';
+
+const QUESTION_RX = /^(?:how|what|why|when|where|who|can|is|does|which|should)\b|\?$/i;
+const HOWTO_TITLE_RX = /^(?:how\s+to|how\s+do\s+i|step-by-step|guide\s+to)\b/i;
+
+/**
+ * Scan audited site pages for FAQPage, Speakable, and HowTo markup opportunities.
+ */
+export function recommendSchemaForPages(pages = []) {
+  const recommendations = {
+    faq: [],
+    speakable: [],
+    howto: [],
+  };
+
+  for (const page of pages) {
+    if (!page || page.status !== 200) continue;
+    const html = page.html || '';
+    const root = parseHtml(html);
+    const existingTypes = new Set(
+      (page.jsonLd || []).flatMap((j) => j.blocks || []).flatMap((b) => [].concat(b['@type'] || []))
+    );
+
+    // -------------------------------------------------------------
+    // 1. FAQPage Recommendation
+    // -------------------------------------------------------------
+    if (!existingTypes.has('FAQPage')) {
+      const qas = [];
+
+      // Pattern A: <details><summary>Q</summary><p>A</p></details>
+      for (const details of root.querySelectorAll('details')) {
+        const summary = details.querySelector('summary');
+        if (summary) {
+          const questionText = summary.text.trim();
+          const clone = parseHtml(details.innerHTML);
+          const s = clone.querySelector('summary');
+          if (s) s.remove();
+          const answerText = clone.text.replace(/\s+/g, ' ').trim();
+          if (questionText && answerText) {
+            qas.push({ question: questionText, answer: answerText });
+          }
+        }
+      }
+
+      // Pattern B: Question headings followed by paragraphs
+      if (qas.length < 2) {
+        const headings = root.querySelectorAll('h2, h3');
+        for (const h of headings) {
+          const hText = h.text.trim();
+          if (QUESTION_RX.test(hText)) {
+            // Find next sibling paragraph
+            let next = h.nextElementSibling;
+            let answerText = '';
+            while (next && !['H1', 'H2', 'H3', 'H4'].includes(next.tagName)) {
+              if (['P', 'UL', 'OL', 'DIV'].includes(next.tagName)) {
+                answerText += (answerText ? ' ' : '') + next.text.replace(/\s+/g, ' ').trim();
+                if (answerText.length > 60) break;
+              }
+              next = next.nextElementSibling;
+            }
+            if (hText && answerText) {
+              qas.push({ question: hText, answer: answerText });
+            }
+          }
+        }
+      }
+
+      if (qas.length >= 2) {
+        recommendations.faq.push({
+          target_url: page.url,
+          source_file: page.sourceFile || null,
+          schema_type: 'FAQPage',
+          rationale: `Detected ${qas.length} visible question-and-answer pairs without FAQPage schema.`,
+          jsonld: {
+            '@context': 'https://schema.org',
+            '@type': 'FAQPage',
+            mainEntity: qas.slice(0, 10).map((qa) => ({
+              '@type': 'Question',
+              name: qa.question,
+              acceptedAnswer: {
+                '@type': 'Answer',
+                text: qa.answer,
+              },
+            })),
+          },
+        });
+      }
+    }
+
+    // -------------------------------------------------------------
+    // 2. Speakable Recommendation (SpeakableSpecification)
+    // -------------------------------------------------------------
+    const hasExistingSpeakable = (page.jsonLd || []).some((j) =>
+      (j.blocks || []).some((b) => b.speakable)
+    );
+
+    if (!hasExistingSpeakable) {
+      const speakableSelectors = [];
+      if (root.querySelector('h1')) speakableSelectors.push('h1');
+      if (root.querySelector('#summary, .executive-summary, .summary, .key-takeaways')) {
+        speakableSelectors.push(root.querySelector('#summary') ? '#summary' : '.executive-summary');
+      } else if (root.querySelector('article > p:first-of-type, main > p:first-of-type, p:first-of-type')) {
+        speakableSelectors.push('article > p:first-of-type');
+      }
+
+      if (speakableSelectors.length >= 2) {
+        recommendations.speakable.push({
+          target_url: page.url,
+          source_file: page.sourceFile || null,
+          schema_type: 'SpeakableSpecification',
+          rationale: 'Page has clear title and executive lead passage suitable for smart speaker / assistant audio playback.',
+          jsonld: {
+            '@context': 'https://schema.org',
+            '@type': 'WebPage',
+            '@id': `${page.url}#webpage`,
+            url: page.url,
+            name: page.title || 'Page',
+            speakable: {
+              '@type': 'SpeakableSpecification',
+              cssSelector: speakableSelectors,
+            },
+          },
+        });
+      }
+    }
+
+    // -------------------------------------------------------------
+    // 3. HowTo Recommendation
+    // -------------------------------------------------------------
+    if (!existingTypes.has('HowTo')) {
+      const pageTitle = page.title || '';
+      const h1s = (page.headings || []).filter((h) => h.level === 1).map((h) => h.text);
+      const isHowToPage = HOWTO_TITLE_RX.test(pageTitle) || h1s.some((h) => HOWTO_TITLE_RX.test(h));
+
+      if (isHowToPage) {
+        const steps = [];
+        // Look for ordered list items or step subheadings
+        const olItems = root.querySelectorAll('ol > li');
+        if (olItems.length >= 2) {
+          olItems.forEach((li, idx) => {
+            const stepText = li.text.replace(/\s+/g, ' ').trim();
+            if (stepText) {
+              steps.push({
+                '@type': 'HowToStep',
+                position: idx + 1,
+                name: `Step ${idx + 1}`,
+                text: stepText,
+              });
+            }
+          });
+        }
+
+        if (steps.length >= 2) {
+          recommendations.howto.push({
+            target_url: page.url,
+            source_file: page.sourceFile || null,
+            schema_type: 'HowTo',
+            rationale: `Procedural instructional guide detected with ${steps.length} ordered steps.`,
+            jsonld: {
+              '@context': 'https://schema.org',
+              '@type': 'HowTo',
+              name: h1s[0] || pageTitle,
+              description: page.paragraphs?.[0] || 'Procedural guide and instructions.',
+              step: steps,
+            },
+          });
+        }
+      }
+    }
+  }
+
+  return recommendations;
+}

package/src/analysis/strategicRoadmap.js

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJson, writeJson, nowIso } from '../shared/io.js';
+import { scoreFinding, scoreInitiative } from './iceMatrix.js';
+
+/**
+ * Generate a 30 / 90 / 180-day Strategic Roadmap from audit findings and initiatives.
+ */
+export function buildStrategicRoadmap({ findings = [], initiatives = [], targetDomain = 'example.com' } = {}) {
+  // Score all findings and initiatives with ICE
+  const scoredFindings = findings.map(scoreFinding);
+  const scoredInitiatives = initiatives.map(scoreInitiative);
+
+  // Group into horizons
+  const horizon30 = {
+    horizon: '30_days',
+    label: 'Days 1 - 30: Foundation & Unblock',
+    objective: 'Eliminate catastrophic crawl, index, and Core Web Vitals blockers; establish foundational crawler access and entity identity.',
+    focus_areas: [
+      'Technical SEO: Resolve HTTP non-200 responses, accidental noindex, and canonical contradictions',
+      'Core Web Vitals: Eliminate render-blocking scripts, specify image dimensions (CLS <= 0.1), preload LCP hero images',
+      'Answer Engine Access: Open robots.txt permissions for PerplexityBot, Bingbot, and OAI-SearchBot',
+      'Entity Identity: Deploy baseline Organization and primary Person JSON-LD schemas',
+    ],
+    exit_criteria: [
+      'Zero critical-severity technical findings in citable audit technical',
+      'Static CLS readiness: 100% of body images have explicit dimensions',
+      'All major answer engine bots verified allowed in robots directives',
+      'Baseline Organization schema live with verified @id',
+    ],
+    actions: [],
+  };
+
+  const horizon90 = {
+    horizon: '90_days',
+    label: 'Days 31 - 90: Governance, E-E-A-T & Extractability',
+    objective: 'Elevate on-page E-E-A-T, deploy rich structured data (FAQPage, Speakable, HowTo), audit backlinks, and automate fast indexing.',
+    focus_areas: [
+      'On-Page E-E-A-T: Attribute all content to verified authors, add credentials, visible update dates, and editorial transparency links',
+      'Schema Enrichment: Deploy FAQPage Q&A markup, SpeakableSpecification for audio extraction, and HowTo step schemas',
+      'Fast Indexing: Configure and verify IndexNow protocol connector for instant Bing / search engine notification',
+      'Off-Page Governance: Audit inbound backlink profile, flag toxic PBN/spam TLDs, and compile GSC disavow candidate file',
+      'Claim Substantiation: Map material business claims to evidence registry records',
+    ],
+    exit_criteria: [
+      'Composite E-E-A-T score >= 4.0 / 5.0 across money and content pages',
+      'FAQPage and Speakable schema deployed on all eligible guide/product pages',
+      'IndexNow connection tested and submitting on content updates',
+      'Google Disavow file reviewed and archived in evidence package',
+      'Zero unverified material claims in citable substantiate',
+    ],
+    actions: [],
+  };
+
+  const horizon180 = {
+    horizon: '180_days',
+    label: 'Days 91 - 180: GEO Dominance, Corroboration & Scale',
+    objective: 'Dominate generative search citations across Perplexity, Copilot, and ChatGPT; build digital PR authority; govern conversion experiments.',
+    focus_areas: [
+      'Generative Engine Optimization (GEO): Optimize RAG chunk boundaries (150-350 words) and direct copular definitions ("X is Y")',
+      'Competitive Share-of-Voice: Benchmark brand citation share and sentiment stance across AI engines vs key competitors',
+      'Authority & Corroboration: Earn high-authority primary citations (.edu, .gov, standards bodies, industry reports)',
+      'Conversion Rate Optimization (CRO): Implement accessible Nebula UI components and govern A/B experiment guardrails (SRM, stopping)',
+      'Continuous Governance: Schedule automated version-pinned audit runs with regression alerts',
+    ],
+    exit_criteria: [
+      'Answer-Engine readiness score >= 85/100 across Perplexity, Bing Copilot, and ChatGPT',
+      'Weekly automated continuous audit pipeline with regression monitoring active',
+      'Dominant citation share on primary category prompts in AI search engine probes',
+      'Zero statistically invalid experiment decisions (SRM < 0.001)',
+    ],
+    actions: [],
+  };
+
+  // Map findings into horizons based on urgency and discipline
+  for (const f of scoredFindings) {
+    const ns = (f.id || '').split('-')[0];
+    if (f.severity === 'critical' || ['TECH', 'CRAWL', 'STATUS'].includes(ns)) {
+      horizon30.actions.push(f);
+    } else if (f.severity === 'high' || ['CWV', 'SCHEMA', 'PAGE', 'LINK'].includes(ns)) {
+      if (['CWV-001', 'CWV-004'].includes(f.id)) horizon30.actions.push(f);
+      else horizon90.actions.push(f);
+    } else if (['ANS', 'ENTITY', 'CLAIM', 'EVD'].includes(ns)) {
+      horizon90.actions.push(f);
+    } else {
+      horizon180.actions.push(f);
+    }
+  }
+
+  // Map initiatives into horizons
+  for (const i of scoredInitiatives) {
+    if (i.impact >= 8 && i.effort <= 4) {
+      horizon30.actions.push(i);
+    } else if (i.impact >= 6) {
+      horizon90.actions.push(i);
+    } else {
+      horizon180.actions.push(i);
+    }
+  }
+
+  return {
+    fact_status: 'strategic_roadmap_projection',
+    target_domain: targetDomain,
+    generated_at: nowIso(),
+    methodology: 'Horizon Phasing: 30-Day (Critical Unblock & Core CWV) -> 90-Day (E-E-A-T, Schema & Off-Page) -> 180-Day (GEO Dominance & PR)',
+    horizons: [horizon30, horizon90, horizon180],
+  };
+}
+
+/**
+ * Format Strategic Roadmap as GitHub-flavored Markdown
+ */
+export function formatRoadmapMarkdown(roadmap) {
+  const lines = [
+    `# 30 / 90 / 180-Day Strategic Roadmap`,
+    ``,
+    `- Target Property: \`${roadmap.target_domain}\``,
+    `- Generated: ${roadmap.generated_at}`,
+    `- Governance Methodology: ${roadmap.methodology}`,
+    ``,
+    `> **Operating Premise Reminder**: This roadmap sequences verified remediation priorities and strategic enhancements. It establishes technical eligibility and extractability, but never guarantees ranking, traffic, or citation outcomes.`,
+    ``,
+  ];
+
+  for (const h of roadmap.horizons) {
+    lines.push(`## ${h.label}`);
+    lines.push(``);
+    lines.push(`**Objective**: ${h.objective}`);
+    lines.push(``);
+    lines.push(`### Strategic Focus Areas:`);
+    for (const f of h.focus_areas) lines.push(`- ${f}`);
+    lines.push(``);
+    lines.push(`### Exit Criteria & Success Milestones:`);
+    for (const c of h.exit_criteria) lines.push(`- [ ] ${c}`);
+    lines.push(``);
+    if (h.actions.length) {
+      lines.push(`### Prioritized Actions (${h.actions.length}):`);
+      lines.push(`| Action / Initiative | Impact | Effort | Conf | ICE Score | Quadrant |`);
+      lines.push(`| :--- | :--- | :--- | :--- | :--- | :--- |`);
+      for (const a of h.actions.slice(0, 10)) {
+        lines.push(`| **${a.id}**: ${a.title.slice(0, 45)} | ${a.impact}/10 | ${a.effort}/10 | ${a.confidence}/10 | **${a.ice_score}** | ${a.quadrant} |`);
+      }
+      lines.push(``);
+    }
+  }
+
+  return lines.join('\n');
+}