@nebulacomponents/citable 1.15.1 → 1.17.0

package/src/detectors/index.js

@@ -13,8 +13,9 @@ import lifeMeas from './lifeMeas.js';
 import { hreflangDetectors } from './hreflang.js';
 import { cwvDetectors } from './cwv.js';
 import { AGENT_DETECTORS } from './agent.js';
+import cro from './cro.js';
 
-export const ALL_DETECTORS = [...tech, ...crawl, ...arch, ...page, ...ans, ...entity, ...claim, ...evd, ...schemaData, ...link, ...geoReco, ...lifeMeas, ...hreflangDetectors, ...cwvDetectors, ...AGENT_DETECTORS];
+export const ALL_DETECTORS = [...tech, ...crawl, ...arch, ...page, ...ans, ...entity, ...claim, ...evd, ...schemaData, ...link, ...geoReco, ...lifeMeas, ...hreflangDetectors, ...cwvDetectors, ...AGENT_DETECTORS, ...cro];
 
 const ids = new Set();
 for (const d of ALL_DETECTORS) {
@@ -45,9 +46,10 @@ export function selectDetectors({ scope, namespaces, discipline } = {}) {
       schema: ['SCHEMA'],
       lifecycle: ['LIFE'],
       corroboration: ['EXT'],
+      cro: ['CRO'],
     };
     if (scopeMap[scope]) ds = ds.filter((d) => scopeMap[scope].includes(d.namespace));
-    else if (['seo', 'aeo', 'geo'].includes(scope)) ds = ds.filter((d) => d.discipline.includes(scope));
+    else if (['seo', 'aeo', 'geo', 'cro'].includes(scope)) ds = ds.filter((d) => d.discipline.includes(scope));
   }
   return ds;
 }

package/src/detectors/link.js

@@ -1,4 +1,4 @@
-import { defineDetector, pageSubject } from './framework.js';
+import { defineDetector, indexTargets, pageSubject } from './framework.js';
 
 const D = [];
 
@@ -118,4 +118,115 @@ D.push(defineDetector({
   },
 }));
 
+D.push(defineDetector({
+  id: 'LINK-005', name: 'Internal redirect hop chain or circular redirect loop', namespace: 'LINK',
+  description: 'An internal link targets a URL that initiates a multi-hop redirect chain (>=2 hops) or a circular redirect loop, dissipating link equity and wasting crawler budget.',
+  discipline: ['seo', 'tech'], severity: 'medium', deterministic: true, requires: ['site'],
+  impact: { retrieval: 'medium', ranking: 'low' },
+  applicable_requirement: 'SEO §3 eliminate multi-hop internal redirects; prevent crawler trap redirect loops',
+  remediation: 'Update internal links to point directly to the terminal 200 destination URL, bypassing redirect hops.',
+  verification: 'Verify all internal links resolve to terminal 200 destinations in 0 redirect hops.',
+  check(ctx) {
+    const hits = [];
+    for (const p of ctx.site.pages) {
+      const seenLinks = new Set();
+      for (const e of ctx.site.outbound.get(ctx.site.normalize(p.url)) || []) {
+        if (!e.to || seenLinks.has(e.to)) continue;
+        seenLinks.add(e.to);
+
+        let curr = ctx.site.byUrl.get(e.to);
+        if (!curr || curr.status < 300 || curr.status >= 400) continue;
+
+        let hops = 0;
+        const visited = [e.to];
+        const visitedSet = new Set([e.to]);
+        let loopDetected = false;
+
+        while (curr && curr.status >= 300 && curr.status < 400 && hops < 10) {
+          hops++;
+          const loc = curr.headers?.location || curr.headers?.Location || curr.redirectLocation;
+          if (!loc) break;
+          const nextUrl = ctx.site.normalize ? ctx.site.normalize(loc) : loc;
+          if (visitedSet.has(nextUrl)) {
+            loopDetected = true;
+            visited.push(nextUrl);
+            break;
+          }
+          visitedSet.add(nextUrl);
+          visited.push(nextUrl);
+          curr = ctx.site.byUrl.get(nextUrl);
+        }
+
+        if (loopDetected) {
+          hits.push({
+            subject: pageSubject(p),
+            summary: `Internal link "${e.text || e.href}" targets circular redirect loop (${visited.join(' → ')})`,
+            evidence: [
+              `link: "${e.text || e.href}"`,
+              `redirect loop: ${visited.join(' → ')}`,
+            ],
+          });
+        } else if (hops >= 2) {
+          hits.push({
+            subject: pageSubject(p),
+            summary: `Internal link "${e.text || e.href}" targets multi-hop redirect chain (${hops} hops: ${visited.join(' → ')})`,
+            evidence: [
+              `link: "${e.text || e.href}"`,
+              `redirect chain: ${visited.join(' → ')}`,
+              `hops: ${hops}`,
+            ],
+            captured: hops,
+            expected: 0,
+          });
+        }
+      }
+    }
+    return hits;
+  },
+}));
+
+D.push(defineDetector({
+  id: 'LINK-006', name: 'Excessive naked URL or uninformative internal anchor text ratio', namespace: 'LINK',
+  description: 'Over 25% of internal links on a page use naked URLs or uninformative anchors, diluting semantic topic graph signals for search engines and generative models.',
+  discipline: ['seo', 'aeo'], severity: 'low', deterministic: true, requires: ['site'],
+  impact: { ranking: 'medium', representation: 'low' },
+  applicable_requirement: 'SEO §3 descriptive anchor text; AEO §2 semantic entity linking; premise 3.3 topic graph integrity',
+  remediation: 'Replace naked URLs and symbol-only anchors with descriptive, keyword-aligned topic text.',
+  verification: 'Confirm less than 25% of internal anchors on any page are naked URLs or non-descriptive tokens.',
+  check(ctx) {
+    const hits = [];
+    const UNINFORMATIVE_RX = /^(\s*|https?:\/\/.*|\/.*|[0-9]+|[•→>»*#\-_|~]+|click\s+here|read\s+more|learn\s+more|view\s+more|here|link|more|details|page)$/i;
+
+    for (const p of indexTargets(ctx)) {
+      const outbound = ctx.site.outbound.get(ctx.site.normalize(p.url)) || [];
+      if (outbound.length < 4) continue;
+
+      let uninformativeCount = 0;
+      for (const e of outbound) {
+        const text = (e.text || '').trim();
+        if (!text || UNINFORMATIVE_RX.test(text) || text === e.href || text === e.to) {
+          uninformativeCount++;
+        }
+      }
+
+      const ratio = uninformativeCount / outbound.length;
+      if (ratio > 0.25) {
+        hits.push({
+          subject: pageSubject(p),
+          summary: `Page has ${Math.round(ratio * 100)}% uninformative internal anchors (${uninformativeCount}/${outbound.length})`,
+          evidence: [
+            `uninformative anchors: ${uninformativeCount}`,
+            `total internal links: ${outbound.length}`,
+            `ratio: ${(ratio * 100).toFixed(1)}%`,
+          ],
+          captured: `${Math.round(ratio * 100)}%`,
+          expected: '<= 25%',
+        });
+      }
+    }
+    return hits;
+  },
+}));
+
 export default D;
+

package/src/detectors/page.js

@@ -1,4 +1,5 @@
 import { defineDetector, htmlIndexTargets, pageSubject } from './framework.js';
+import { parse } from 'node-html-parser';
 
 const D = [];
 
@@ -199,4 +200,104 @@ D.push(defineDetector({
   },
 }));
 
+D.push(defineDetector({
+  id: 'PAGE-010', name: 'High boilerplate-to-content ratio in extracted answer passages', namespace: 'PAGE',
+  description: 'An index-target page has a high ratio of boilerplate (navigation, header, footer, chrome) relative to substantive primary content, diluting extracted answer passages.',
+  discipline: ['aeo', 'seo'], severity: 'medium', deterministic: true, requires: ['site'],
+  impact: { ranking: 'low', citation: 'medium' },
+  applicable_requirement: 'SEO §5 main content extraction; AEO §4 concise and focused answer passages',
+  false_positive_conditions: ['minimal navigation shells intentionally designed as search gateways'],
+  remediation: 'Reduce header/footer/chrome weight or enrich main body content so substantive answer passages dominate the document.',
+  verification: 'Confirm boilerplate-to-content ratio is below the defined threshold.',
+  check(ctx) {
+    const threshold = ctx.config?.audit?.max_boilerplate_ratio ?? 0.70;
+    const hits = [];
+    for (const p of htmlIndexTargets(ctx)) {
+      if (p.status !== 200) continue;
+      const boilerplateWords = (p.structuralRegions || []).reduce((sum, r) => sum + (r.token_count || 0), 0);
+      const mainWords = p.wordCount || 0;
+      const total = boilerplateWords + mainWords;
+      if (boilerplateWords > 0 && mainWords > 0 && total >= 50) {
+        const ratio = boilerplateWords / total;
+        if (ratio >= threshold) {
+          hits.push({
+            subject: pageSubject(p),
+            summary: `High boilerplate-to-content ratio: ${(100 * ratio).toFixed(1)}% of visible text is chrome/navigation/footer (threshold ${(100 * threshold).toFixed(0)}%)`,
+            evidence: [`boilerplate tokens: ${boilerplateWords}`, `main content tokens: ${mainWords}`, `ratio: ${(100 * ratio).toFixed(1)}%`],
+            captured: Number(ratio.toFixed(4)),
+            threshold,
+          });
+        }
+      }
+    }
+    return hits;
+  },
+}));
+
+D.push(defineDetector({
+  id: 'PAGE-011', name: 'Critical entity claims rendered inside transient/collapsible UI containers without fallback', namespace: 'PAGE',
+  description: 'Registered claim or critical entity statement is rendered exclusively inside a collapsible or transient UI container (<details>, accordion, hidden tab) without an uncollapsed fallback or crawlable representation.',
+  discipline: ['aeo', 'geo'], severity: 'medium', deterministic: true, requires: ['site', 'registries'],
+  impact: { citation: 'medium', representation: 'medium' },
+  applicable_requirement: 'AEO §2 crawlable and indexable answer surfaces; premise 3.5: claims must be verified and crawlable',
+  false_positive_conditions: ['supplemental FAQs where claims are also summarized in main prose'],
+  remediation: 'Expose key entity statements and primary claim assertions directly in main crawlable prose or provide server-rendered uncollapsed fallbacks.',
+  verification: 'Confirm registered claims are accessible outside closed collapsible containers.',
+  check(ctx) {
+    const claims = (ctx.registries?.claims?.entries || []).filter((c) => !['retired', 'expired', 'prohibited'].includes(c.status));
+    if (claims.length === 0) return [];
+    const hits = [];
+
+    for (const p of htmlIndexTargets(ctx)) {
+      if (p.status !== 200 || !p.rawHtml) continue;
+      const doc = parse(p.rawHtml);
+
+      // Identify transient/collapsible containers
+      const collapsibleContainers = doc.querySelectorAll('details:not([open]), [aria-expanded="false"], .collapse:not(.show), [data-state="closed"]');
+      if (collapsibleContainers.length === 0) continue;
+
+      const containerTexts = collapsibleContainers.map((el) => ({
+        tag: el.tagName ? el.tagName.toLowerCase() : 'container',
+        text: el.text.toLowerCase().replace(/\s+/g, ' ').trim(),
+      })).filter((c) => c.text.length > 0);
+
+      if (containerTexts.length === 0) continue;
+
+      // Compute document text outside collapsible containers
+      const docClone = parse(p.rawHtml);
+      for (const el of docClone.querySelectorAll('details:not([open]), [aria-expanded="false"], .collapse:not(.show), [data-state="closed"]')) {
+        el.remove();
+      }
+      const exteriorText = docClone.text.toLowerCase().replace(/\s+/g, ' ').trim();
+
+      for (const c of claims) {
+        const keywords = (c.claim.toLowerCase().match(/[a-z0-9][a-z0-9-]{3,}/g) || []).slice(0, 8);
+        if (keywords.length < 2) continue;
+
+        for (const container of containerTexts) {
+          const matchedInContainer = keywords.filter((k) => container.text.includes(k)).length;
+          if (matchedInContainer / keywords.length >= 0.7) {
+            const matchedInExterior = keywords.filter((k) => exteriorText.includes(k)).length;
+            if (matchedInExterior / keywords.length < 0.4) {
+              hits.push({
+                subject: pageSubject(p),
+                summary: `Claim "${c.claim_id}" rendered inside collapsible <${container.tag}> container without uncollapsed fallback`,
+                evidence: [
+                  `claim_id: ${c.claim_id}`,
+                  `claim: "${c.claim}"`,
+                  `container: <${container.tag}>`,
+                  `keywords matched in container: ${matchedInContainer}/${keywords.length}`,
+                  `keywords outside container: ${matchedInExterior}/${keywords.length}`,
+                ],
+              });
+              break;
+            }
+          }
+        }
+      }
+    }
+    return hits;
+  },
+}));
+
 export default D;