@pseolint/core 0.2.2 → 0.3.1

package/dist/rules/aeo/citable-facts.js

@@ -0,0 +1,90 @@
+const FACT_PATTERNS = [
+    { name: "dollar", regex: /\$[\d,]+(\.\d{2})?/g },
+    { name: "percent", regex: /\b\d+(\.\d+)?\s*%/g },
+    {
+        name: "timeframe",
+        regex: /\b\d+(?:-\d+)?\s*(business\s+days?|days?|weeks?|months?|years?|hours?|minutes?)\b/gi,
+    },
+    {
+        name: "date",
+        regex: /\b(january|february|march|april|may|june|july|august|september|october|november|december)\s+\d{1,2}(?:,\s*\d{4})?\b/gi,
+    },
+    { name: "isoDate", regex: /\b\d{4}-\d{2}-\d{2}\b/g },
+    { name: "form", regex: /\bForm\s+[A-Z0-9][A-Z0-9-]*\b/g },
+];
+function extractRawFacts(text) {
+    const out = new Set();
+    for (const { regex } of FACT_PATTERNS) {
+        const matches = text.match(regex);
+        if (!matches)
+            continue;
+        for (const m of matches)
+            out.add(m.trim().toLowerCase());
+    }
+    return Array.from(out);
+}
+function applyEntityMask(text, patterns) {
+    let out = text;
+    for (const p of patterns)
+        out = out.replace(p.pattern, p.placeholder);
+    return out;
+}
+export function citableFactsRule(pages, entityPatterns, options) {
+    const minFacts = options?.minFactsPerPage ?? 3;
+    const targetFacts = options?.targetFactsPerPage ?? 8;
+    const findings = [];
+    // Build a global template-fact set: facts that appear verbatim on a majority of pages
+    // after entity masking — those are "template facts", not entity-specific data points.
+    //
+    // Scaling by page count:
+    //   n == 1      → no template detection possible, all facts count as entity-specific.
+    //   n in 2..=5  → fact is template when it appears on ALL pages (strict).
+    //   n > 5       → fact is template when it appears on >= 50% of pages.
+    //
+    // Earlier cut-off (`> 5 ? ceil(n*0.5) : n + 1`) made small-sample audits silently
+    // ignore template facts, so a 3-page audit with "$70" on every page looked clean.
+    const templateThreshold = pages.length <= 1 ? Infinity :
+        pages.length <= 5 ? pages.length :
+            Math.ceil(pages.length * 0.5);
+    const factFrequency = new Map();
+    const perPageFacts = new Map();
+    for (const page of pages) {
+        const masked = applyEntityMask(page.contentText, entityPatterns);
+        const rawFacts = extractRawFacts(masked);
+        perPageFacts.set(page.url, rawFacts);
+        for (const f of rawFacts) {
+            factFrequency.set(f, (factFrequency.get(f) ?? 0) + 1);
+        }
+    }
+    const templateFacts = new Set();
+    for (const [f, count] of factFrequency.entries()) {
+        if (count >= templateThreshold)
+            templateFacts.add(f);
+    }
+    for (const page of pages) {
+        const facts = perPageFacts.get(page.url) ?? [];
+        const unique = facts.filter((f) => !templateFacts.has(f));
+        if (unique.length >= targetFacts)
+            continue;
+        const severity = unique.length < minFacts ? "error" : "warning";
+        const templateDrag = facts.length - unique.length;
+        const templateNote = templateDrag > 0
+            ? ` (${templateDrag} additional fact${templateDrag === 1 ? "" : "s"} appear on most pages and don't count as entity-specific)`
+            : "";
+        findings.push({
+            ruleId: "aeo/citable-facts",
+            severity,
+            message: `${page.url} has ${unique.length} unique citable fact${unique.length === 1 ? "" : "s"}${templateNote}. ` +
+                `AI Overviews cite specific numbers and named references.`,
+            pageUrl: page.url,
+            fix: `Replace vague language ("varies", "several weeks", "affordable", "many options") with ` +
+                `specific values a reader or AI engine would cite: exact prices, percentages, dates, ` +
+                `timeframes, version numbers, named products, standards, or regulations that apply to this page. ` +
+                `For pSEO templates, bind these values from your data source so each page gets ` +
+                `entity-specific numbers instead of repeating the same template wording. ` +
+                `Target: ${targetFacts}+ unique facts per page.`,
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=citable-facts.js.map

package/dist/rules/aeo/citable-facts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"citable-facts.js","sourceRoot":"","sources":["../../../src/rules/aeo/citable-facts.ts"],"names":[],"mappings":"AASA,MAAM,aAAa,GAA2C;IAC5D,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,qBAAqB,EAAE;IAChD,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,oBAAoB,EAAE;IAChD;QACE,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,qFAAqF;KAC7F;IACD;QACE,IAAI,EAAE,MAAM;QACZ,KAAK,EACH,uHAAuH;KAC1H;IACD,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,wBAAwB,EAAE;IACpD,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,gCAAgC,EAAE;CAC1D,CAAC;AAEF,SAAS,eAAe,CAAC,IAAY;IACnC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,EAAE,KAAK,EAAE,IAAI,aAAa,EAAE,CAAC;QACtC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,CAAC,OAAO;YAAE,SAAS;QACvB,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,SAAS,eAAe,CAAC,IAAY,EAAE,QAA6B;IAClE,IAAI,GAAG,GAAG,IAAI,CAAC;IACf,KAAK,MAAM,CAAC,IAAI,QAAQ;QAAE,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;IACtE,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,KAAmB,EACnB,cAAmC,EACnC,OAA6B;IAE7B,MAAM,QAAQ,GAAG,OAAO,EAAE,eAAe,IAAI,CAAC,CAAC;IAC/C,MAAM,WAAW,GAAG,OAAO,EAAE,kBAAkB,IAAI,CAAC,CAAC;IACrD,MAAM,QAAQ,GAAiB,EAAE,CAAC;IAElC,sFAAsF;IACtF,sFAAsF;IACtF,EAAE;IACF,yBAAyB;IACzB,sFAAsF;IACtF,0EAA0E;IAC1E,uEAAuE;IACvE,EAAE;IACF,kFAAkF;IAClF,kFAAkF;IAClF,MAAM,iBAAiB,GACrB,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;QAC9B,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAClC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;IAEhC,MAAM,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;IAChD,MAAM,YAAY,GAAG,IAAI,GAAG,EAAoB,CAAC;IAEjD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;QACjE,MAAM,QAAQ,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QACzC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QACrC,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,aAAa,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAED,MAAM,aAAa,GAAG,IAAI,GAAG,EAAU,CAAC;IACxC,KAAK,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,aAAa,CAAC,OAAO,EAAE,EAAE,CAAC;QACjD,IAAI,KAAK,IAAI,iBAAiB;YAAE,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACvD,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QAC/C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAE1D,IAAI,MAAM,CAAC,MAAM,IAAI,WAAW;YAAE,SAAS;QAE3C,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;QAChE,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAClD,MAAM,YAAY,GAAG,YAAY,GAAG,CAAC;YACnC,CAAC,CAAC,KAAK,YAAY,mBAAmB,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,2DAA2D;YAC9H,CAAC,CAAC,EAAE,CAAC;QAEP,QAAQ,CAAC,IAAI,CAAC;YACZ,MAAM,EAAE,mBAAmB;YAC3B,QAAQ;YACR,OAAO,EACL,GAAG,IAAI,CAAC,GAAG,QAAQ,MAAM,CAAC,MAAM,uBAAuB,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,YAAY,IAAI;gBACxG,0DAA0D;YAC5D,OAAO,EAAE,IAAI,CAAC,GAAG;YACjB,GAAG,EACD,wFAAwF;gBACxF,sFAAsF;gBACtF,kGAAkG;gBAClG,gFAAgF;gBAChF,0EAA0E;gBAC1E,WAAW,WAAW,0BAA0B;SACnD,CAAC,CAAC;IACL,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/rules/aeo/content-modularity.d.ts

@@ -0,0 +1,11 @@
+import type { ParsedPage, RuleResult } from "../../types.js";
+export interface ContentModularityOptions {
+    /** Paragraphs longer than this many words are flagged. Default: 200. */
+    maxParagraphWords?: number;
+    /** Fraction of sections that must be self-contained to pass. Default: 0.7. */
+    minSelfContainedRatio?: number;
+    /** Extra cross-reference regexes (merged with defaults). */
+    crossRefPatterns?: RegExp[];
+}
+export declare function contentModularityRule(pages: ParsedPage[], options?: ContentModularityOptions): RuleResult[];
+//# sourceMappingURL=content-modularity.d.ts.map

package/dist/rules/aeo/content-modularity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-modularity.d.ts","sourceRoot":"","sources":["../../../src/rules/aeo/content-modularity.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE7D,MAAM,WAAW,wBAAwB;IACvC,wEAAwE;IACxE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AA+FD,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,UAAU,EAAE,EACnB,OAAO,CAAC,EAAE,wBAAwB,GACjC,UAAU,EAAE,CAyCd"}

package/dist/rules/aeo/content-modularity.js

@@ -0,0 +1,107 @@
+import { load } from "cheerio";
+const DEFAULT_CROSS_REF_RULES = [
+    { re: /\b(as\s+)?(mentioned|noted|discussed|shown)\s+(above|below|earlier|previously|later)\b/i, label: "'as mentioned above'" },
+    { re: /\bin\s+the\s+(previous|next|following|preceding)\s+section\b/i, label: "'in the previous/next section'" },
+    { re: /\bsee\s+(above|below|earlier|the\s+section)\b/i, label: "'see above/below'" },
+    { re: /\bas\s+(noted|stated)\s+above\b/i, label: "'as noted above'" },
+];
+// Intentionally conservative — only flag headings that are truly content-free.
+// "FAQ", "Summary", "Conclusion", "Getting Started" are common legitimate headings
+// and were removed from this list after feedback.
+const VAGUE_HEADING_PATTERNS = [
+    /^\s*(more\s+information|more\s+info|details|additional\s+details|other|notes?)\s*$/i,
+];
+function splitIntoSections(html) {
+    const $ = load(html);
+    const sections = [];
+    let current = null;
+    const scope = $("article").length > 0 ? $("article") : $("main").length > 0 ? $("main") : $("body");
+    // Chrome/nav elements inside <article>/<main> (related-posts asides, breadcrumb nav,
+    // footer CTAs) inflate paragraph counts and confuse cross-reference detection.
+    // Skip any h2/h3/p/li that sits inside them.
+    const excludeSel = "nav, aside, footer, header, [role=navigation], .breadcrumbs, .breadcrumb";
+    const isExcluded = (el) => $(el).closest(excludeSel).length > 0;
+    scope.find("h2, h3, p, li").each((_, el) => {
+        if (isExcluded(el))
+            return;
+        const tag = el.tagName?.toLowerCase?.() ?? "";
+        const text = $(el).text().trim();
+        if (!text)
+            return;
+        if (tag === "h2" || tag === "h3") {
+            current = { heading: text, text: "", paragraphs: [] };
+            sections.push(current);
+            return;
+        }
+        if (!current) {
+            current = { heading: "", text: "", paragraphs: [] };
+            sections.push(current);
+        }
+        current.paragraphs.push(text);
+        current.text = current.text ? `${current.text} ${text}` : text;
+    });
+    return sections;
+}
+function wordCount(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return 0;
+    return trimmed.split(/\s+/).length;
+}
+function analyzeSection(section, crossRefRules, maxParagraphWords) {
+    const reasons = [];
+    for (const { re, label } of crossRefRules) {
+        if (re.test(section.text)) {
+            reasons.push(`cross-references another section (${label})`);
+            break;
+        }
+    }
+    if (section.heading && VAGUE_HEADING_PATTERNS.some((re) => re.test(section.heading))) {
+        reasons.push(`heading "${section.heading}" is too vague`);
+    }
+    const longParagraphs = section.paragraphs.filter((p) => wordCount(p) > maxParagraphWords).length;
+    if (longParagraphs > 0) {
+        reasons.push(`${longParagraphs} paragraph${longParagraphs === 1 ? "" : "s"} exceed ${maxParagraphWords} words`);
+    }
+    if (reasons.length === 0)
+        return null;
+    return { heading: section.heading || "(pre-heading)", reasons };
+}
+export function contentModularityRule(pages, options) {
+    const maxParagraphWords = options?.maxParagraphWords ?? 200;
+    const minRatio = options?.minSelfContainedRatio ?? 0.7;
+    const extraCrossRef = (options?.crossRefPatterns ?? []).map((re) => ({ re, label: "custom pattern" }));
+    const crossRefRules = [...DEFAULT_CROSS_REF_RULES, ...extraCrossRef];
+    const findings = [];
+    for (const page of pages) {
+        const sections = splitIntoSections(page.html).filter((s) => s.text.length > 0);
+        if (sections.length < 2)
+            continue;
+        const issues = [];
+        for (const section of sections) {
+            const issue = analyzeSection(section, crossRefRules, maxParagraphWords);
+            if (issue)
+                issues.push(issue);
+        }
+        const selfContainedRatio = 1 - issues.length / sections.length;
+        if (selfContainedRatio >= minRatio)
+            continue;
+        const examples = issues
+            .slice(0, 3)
+            .map((i) => `"${i.heading}": ${i.reasons.join(", ")}`)
+            .join(" | ");
+        findings.push({
+            ruleId: "aeo/content-modularity",
+            severity: "warning",
+            message: `${page.url} has ${issues.length}/${sections.length} sections that are not independently extractable. ` +
+                `Examples — ${examples}.`,
+            pageUrl: page.url,
+            fix: `Each section should answer one question completely without referencing other parts of the page. ` +
+                `(1) Replace "see above" / "as mentioned" with the actual information the reader needs. ` +
+                `(2) Rename vague H2s ("More Info", "Details") to specific topics (e.g. "California LLC Annual Report Requirements"). ` +
+                `(3) Break paragraphs longer than ${maxParagraphWords} words into 2–3 focused paragraphs with their own sub-headings.`,
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=content-modularity.js.map

package/dist/rules/aeo/content-modularity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-modularity.js","sourceRoot":"","sources":["../../../src/rules/aeo/content-modularity.ts"],"names":[],"mappings":"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"}

package/dist/rules/aeo/crawler-access.d.ts

@@ -0,0 +1,25 @@
+import type { RuleResult } from "../../types.js";
+/**
+ * Default AI crawler user-agents to check. Ordered by prevalence.
+ */
+export declare const DEFAULT_AI_CRAWLERS: readonly ["GPTBot", "ChatGPT-User", "ClaudeBot", "PerplexityBot", "Bytespider", "Google-Extended", "CCBot", "Applebot-Extended"];
+/**
+ * Parse robots.txt into a map of user-agent -> list of Disallow patterns.
+ * User-agent keys are lowercased for case-insensitive lookup.
+ * A blank Disallow value is treated as "allow all" and produces an empty array
+ * (matches the robots spec: "Disallow: " with no value means no restrictions).
+ */
+export declare function parseRobotsByUserAgent(robotsTxt: string): Map<string, string[]>;
+/** True if the Disallow list includes a root block (`/`). */
+export declare function isFullyDisallowed(patterns: string[] | undefined): boolean;
+export interface CrawlerAccessOptions {
+    /** List of AI crawler user-agents to check. */
+    crawlers?: readonly string[];
+}
+/**
+ * Warn per blocked AI crawler; escalate to error when all configured crawlers are blocked.
+ * Wildcard blocks (`User-agent: *` + `Disallow: /`) also count as blocking each named crawler
+ * unless the crawler has its own more-permissive block.
+ */
+export declare function crawlerAccessRule(robotsTxtContent: string, options?: CrawlerAccessOptions): RuleResult[];
+//# sourceMappingURL=crawler-access.d.ts.map

package/dist/rules/aeo/crawler-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crawler-access.d.ts","sourceRoot":"","sources":["../../../src/rules/aeo/crawler-access.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,mBAAmB,kIAStB,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAsC/E;AAED,6DAA6D;AAC7D,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,OAAO,CAGzE;AAED,MAAM,WAAW,oBAAoB;IACnC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,gBAAgB,EAAE,MAAM,EACxB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,UAAU,EAAE,CAkDd"}

package/dist/rules/aeo/crawler-access.js

@@ -0,0 +1,116 @@
+/**
+ * Default AI crawler user-agents to check. Ordered by prevalence.
+ */
+export const DEFAULT_AI_CRAWLERS = [
+    "GPTBot",
+    "ChatGPT-User",
+    "ClaudeBot",
+    "PerplexityBot",
+    "Bytespider",
+    "Google-Extended",
+    "CCBot",
+    "Applebot-Extended",
+];
+/**
+ * Parse robots.txt into a map of user-agent -> list of Disallow patterns.
+ * User-agent keys are lowercased for case-insensitive lookup.
+ * A blank Disallow value is treated as "allow all" and produces an empty array
+ * (matches the robots spec: "Disallow: " with no value means no restrictions).
+ */
+export function parseRobotsByUserAgent(robotsTxt) {
+    const lines = robotsTxt.split(/\r?\n/);
+    const result = new Map();
+    let currentAgents = [];
+    let expectingRules = false;
+    for (const raw of lines) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        if (/^user-agent\s*:/i.test(line)) {
+            const ua = line.replace(/^user-agent\s*:\s*/i, "").trim().toLowerCase();
+            if (!expectingRules) {
+                // Stacking consecutive User-agent lines — they all share the next rule block.
+                currentAgents.push(ua);
+            }
+            else {
+                currentAgents = [ua];
+                expectingRules = false;
+            }
+            if (!result.has(ua))
+                result.set(ua, []);
+            continue;
+        }
+        if (/^(allow|disallow|crawl-delay|sitemap)\s*:/i.test(line)) {
+            expectingRules = true;
+        }
+        if (/^disallow\s*:/i.test(line)) {
+            const value = line.replace(/^disallow\s*:\s*/i, "").trim();
+            if (!value)
+                continue;
+            for (const agent of currentAgents) {
+                const bucket = result.get(agent);
+                if (bucket)
+                    bucket.push(value);
+            }
+        }
+    }
+    return result;
+}
+/** True if the Disallow list includes a root block (`/`). */
+export function isFullyDisallowed(patterns) {
+    if (!patterns)
+        return false;
+    return patterns.some((p) => p === "/" || p === "/*");
+}
+/**
+ * Warn per blocked AI crawler; escalate to error when all configured crawlers are blocked.
+ * Wildcard blocks (`User-agent: *` + `Disallow: /`) also count as blocking each named crawler
+ * unless the crawler has its own more-permissive block.
+ */
+export function crawlerAccessRule(robotsTxtContent, options) {
+    if (!robotsTxtContent)
+        return [];
+    const crawlers = options?.crawlers ?? DEFAULT_AI_CRAWLERS;
+    const byAgent = parseRobotsByUserAgent(robotsTxtContent);
+    const wildcardBlocked = isFullyDisallowed(byAgent.get("*"));
+    const blocked = [];
+    for (const crawler of crawlers) {
+        const key = crawler.toLowerCase();
+        const ownBlock = byAgent.get(key);
+        if (ownBlock === undefined) {
+            // No explicit block for this agent — it falls back to the wildcard block.
+            if (wildcardBlocked)
+                blocked.push(crawler);
+            continue;
+        }
+        if (isFullyDisallowed(ownBlock))
+            blocked.push(crawler);
+    }
+    if (blocked.length === 0)
+        return [];
+    const findings = [];
+    const allBlocked = blocked.length === crawlers.length;
+    if (allBlocked) {
+        findings.push({
+            ruleId: "aeo/crawler-access",
+            severity: "error",
+            message: `robots.txt blocks all ${crawlers.length} configured AI crawlers: ${blocked.join(", ")}.`,
+            fix: `Blocking every AI crawler makes your pages invisible to answer engines. ` +
+                `Sites uncited in AI Overviews lose ~68% of traffic vs ~12% for cited sites. ` +
+                `Remove the Disallow rules for these crawlers unless you have a specific legal or competitive reason to block them.`,
+        });
+        return findings;
+    }
+    for (const crawler of blocked) {
+        findings.push({
+            ruleId: "aeo/crawler-access",
+            severity: "warning",
+            message: `robots.txt blocks ${crawler}.`,
+            fix: `Remove the "Disallow: /" directive for User-agent: ${crawler} in your robots.txt. ` +
+                `Blocking ${crawler} removes your pages from its answer engine's citation pool. ` +
+                `If selective blocking is intentional (e.g. admin routes only), narrow the Disallow pattern instead of blocking the whole site.`,
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=crawler-access.js.map

package/dist/rules/aeo/crawler-access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crawler-access.js","sourceRoot":"","sources":["../../../src/rules/aeo/crawler-access.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,QAAQ;IACR,cAAc;IACd,WAAW;IACX,eAAe;IACf,YAAY;IACZ,iBAAiB;IACjB,OAAO;IACP,mBAAmB;CACX,CAAC;AAEX;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,SAAiB;IACtD,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC3C,IAAI,aAAa,GAAa,EAAE,CAAC;IACjC,IAAI,cAAc,GAAG,KAAK,CAAC;IAE3B,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;QACxB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QAE5C,IAAI,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAClC,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YACxE,IAAI,CAAC,cAAc,EAAE,CAAC;gBACpB,8EAA8E;gBAC9E,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACzB,CAAC;iBAAM,CAAC;gBACN,aAAa,GAAG,CAAC,EAAE,CAAC,CAAC;gBACrB,cAAc,GAAG,KAAK,CAAC;YACzB,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YACxC,SAAS;QACX,CAAC;QAED,IAAI,4CAA4C,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5D,cAAc,GAAG,IAAI,CAAC;QACxB,CAAC;QAED,IAAI,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAChC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YAC3D,IAAI,CAAC,KAAK;gBAAE,SAAS;YACrB,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;gBAClC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;gBACjC,IAAI,MAAM;oBAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACjC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,iBAAiB,CAAC,QAA8B;IAC9D,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5B,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;AACvD,CAAC;AAOD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,gBAAwB,EACxB,OAA8B;IAE9B,IAAI,CAAC,gBAAgB;QAAE,OAAO,EAAE,CAAC;IAEjC,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,mBAAmB,CAAC;IAC1D,MAAM,OAAO,GAAG,sBAAsB,CAAC,gBAAgB,CAAC,CAAC;IACzD,MAAM,eAAe,GAAG,iBAAiB,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAE5D,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,0EAA0E;YAC1E,IAAI,eAAe;gBAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC3C,SAAS;QACX,CAAC;QACD,IAAI,iBAAiB,CAAC,QAAQ,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACzD,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,MAAM,QAAQ,GAAiB,EAAE,CAAC;IAClC,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,CAAC;IAEtD,IAAI,UAAU,EAAE,CAAC;QACf,QAAQ,CAAC,IAAI,CAAC;YACZ,MAAM,EAAE,oBAAoB;YAC5B,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,yBAAyB,QAAQ,CAAC,MAAM,4BAA4B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAClG,GAAG,EACD,0EAA0E;gBAC1E,8EAA8E;gBAC9E,oHAAoH;SACvH,CAAC,CAAC;QACH,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,OAAO,EAAE,CAAC;QAC9B,QAAQ,CAAC,IAAI,CAAC;YACZ,MAAM,EAAE,oBAAoB;YAC5B,QAAQ,EAAE,SAAS;YACnB,OAAO,EAAE,qBAAqB,OAAO,GAAG;YACxC,GAAG,EACD,sDAAsD,OAAO,uBAAuB;gBACpF,YAAY,OAAO,8DAA8D;gBACjF,gIAAgI;SACnI,CAAC,CAAC;IACL,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/rules/aeo/faq-coverage.d.ts

@@ -0,0 +1,9 @@
+import type { ParsedPage, RuleResult } from "../../types.js";
+export interface FaqCoverageOptions {
+    /** URL substring/glob fragments that signal question intent. */
+    questionPatterns?: string[];
+    /** Minimum number of question-style headings to trigger the check (default: 2). */
+    minQuestionHeadings?: number;
+}
+export declare function faqCoverageRule(pages: ParsedPage[], options?: FaqCoverageOptions): RuleResult[];
+//# sourceMappingURL=faq-coverage.d.ts.map

package/dist/rules/aeo/faq-coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"faq-coverage.d.ts","sourceRoot":"","sources":["../../../src/rules/aeo/faq-coverage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE7D,MAAM,WAAW,kBAAkB;IACjC,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,mFAAmF;IACnF,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AA6CD,wBAAgB,eAAe,CAC7B,KAAK,EAAE,UAAU,EAAE,EACnB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,UAAU,EAAE,CA8Bd"}

package/dist/rules/aeo/faq-coverage.js

@@ -0,0 +1,71 @@
+const DEFAULT_URL_PATTERNS = ["/how-to-", "/what-is-", "/guide-", "-faq", "/faq", "/questions"];
+const QUESTION_STARTERS = /^\s*(how|what|why|when|where|who|can|does|do|is|are|should|which|will|could|would|may)\b/i;
+function isQuestionHeading(heading) {
+    const trimmed = heading.trim();
+    if (!trimmed)
+        return false;
+    return trimmed.endsWith("?") || QUESTION_STARTERS.test(trimmed);
+}
+function hasFaqLikeSchema(entries) {
+    const stack = [...entries];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (node === null || typeof node !== "object")
+            continue;
+        const obj = node;
+        const type = obj["@type"];
+        if (type === "FAQPage" || type === "HowTo" || type === "QAPage")
+            return true;
+        if (Array.isArray(type) && type.some((t) => t === "FAQPage" || t === "HowTo" || t === "QAPage")) {
+            return true;
+        }
+        for (const value of Object.values(obj)) {
+            if (Array.isArray(value)) {
+                for (const item of value)
+                    stack.push(item);
+            }
+            else if (value !== null && typeof value === "object") {
+                stack.push(value);
+            }
+        }
+    }
+    return false;
+}
+function urlLooksLikeFaq(url, patterns) {
+    try {
+        const path = new URL(url).pathname.toLowerCase();
+        return patterns.some((p) => path.includes(p));
+    }
+    catch {
+        const lower = url.toLowerCase();
+        return patterns.some((p) => lower.includes(p));
+    }
+}
+export function faqCoverageRule(pages, options) {
+    const patterns = options?.questionPatterns ?? DEFAULT_URL_PATTERNS;
+    const minQuestions = options?.minQuestionHeadings ?? 2;
+    const findings = [];
+    for (const page of pages) {
+        const questionHeadings = page.headings.h2.filter(isQuestionHeading);
+        const urlSignalsFaq = urlLooksLikeFaq(page.url, patterns);
+        if (!urlSignalsFaq && questionHeadings.length < minQuestions)
+            continue;
+        if (hasFaqLikeSchema(page.jsonLd))
+            continue;
+        const sampleList = questionHeadings.slice(0, 3).map((h) => `"${h.trim()}"`).join(", ");
+        const detail = questionHeadings.length > 0
+            ? `${questionHeadings.length} question-style heading${questionHeadings.length === 1 ? "" : "s"}${sampleList ? ` (e.g. ${sampleList})` : ""}`
+            : `URL path matches an FAQ pattern`;
+        findings.push({
+            ruleId: "aeo/faq-coverage",
+            severity: "info",
+            message: `${page.url} contains FAQ-style content (${detail}) but no FAQPage/HowTo JSON-LD.`,
+            pageUrl: page.url,
+            fix: `Add FAQPage JSON-LD that mirrors the existing Q&A content. For pSEO templates, generate the ` +
+                `schema programmatically from the same data source that renders the headings — don't ship identical ` +
+                `questions with only the entity name swapped.`,
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=faq-coverage.js.map

package/dist/rules/aeo/faq-coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"faq-coverage.js","sourceRoot":"","sources":["../../../src/rules/aeo/faq-coverage.ts"],"names":[],"mappings":"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"}

package/dist/rules/aeo/freshness-signals.d.ts

@@ -0,0 +1,9 @@
+import type { ParsedPage, RuleResult } from "../../types.js";
+export interface FreshnessOptions {
+    /** Flag pages with dateModified older than this many days. Default: 180. */
+    maxStaleDays?: number;
+    /** Clock override for deterministic testing. Default: Date.now(). */
+    now?: () => number;
+}
+export declare function freshnessSignalsRule(pages: ParsedPage[], options?: FreshnessOptions): RuleResult[];
+//# sourceMappingURL=freshness-signals.d.ts.map

package/dist/rules/aeo/freshness-signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness-signals.d.ts","sourceRoot":"","sources":["../../../src/rules/aeo/freshness-signals.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE7D,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAkED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,UAAU,EAAE,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,UAAU,EAAE,CAsDd"}

package/dist/rules/aeo/freshness-signals.js

@@ -0,0 +1,109 @@
+import { load } from "cheerio";
+const DAY_MS = 86_400_000;
+/**
+ * Find dateModified-specific signals in JSON-LD (recursive). Keeps `dateModified` and
+ * `datePublished` separate so callers can require a true modification signal rather than
+ * accept "published once in 2020" as evidence of freshness.
+ */
+function findDatesInJsonLd(entries) {
+    let modified = null;
+    let published = null;
+    const stack = [...entries];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (node === null || typeof node !== "object")
+            continue;
+        const obj = node;
+        const m = obj["dateModified"];
+        if (!modified && typeof m === "string" && m.length > 0)
+            modified = m;
+        const p = obj["datePublished"] ?? obj["dateCreated"];
+        if (!published && typeof p === "string" && p.length > 0)
+            published = p;
+        for (const value of Object.values(obj)) {
+            if (Array.isArray(value)) {
+                for (const item of value)
+                    stack.push(item);
+            }
+            else if (value !== null && typeof value === "object") {
+                stack.push(value);
+            }
+        }
+    }
+    return { modified, published };
+}
+/**
+ * Find modification-specific meta tags and <time> elements. Uses cheerio so attribute
+ * order does not matter (<meta content="..." property="...">` and `<meta property="..."
+ * content="...">` both work).
+ */
+function findDateModifiedInHtml(html) {
+    const $ = load(html);
+    const candidates = [
+        $('meta[property="article:modified_time"]').attr("content"),
+        $('meta[name="last-modified"]').attr("content"),
+        $('meta[name="dc.date.modified"]').attr("content"),
+        $("time[datetime]").attr("datetime"),
+    ];
+    for (const value of candidates) {
+        if (typeof value === "string" && value.length > 0)
+            return value;
+    }
+    return null;
+}
+function hasVisibleUpdateSignal(contentText) {
+    return /\b(last\s+updated|updated\s+on|revised|last\s+modified)\b/i.test(contentText);
+}
+function parseDateSafe(value) {
+    if (!value)
+        return null;
+    const t = Date.parse(value);
+    return Number.isFinite(t) ? new Date(t) : null;
+}
+export function freshnessSignalsRule(pages, options) {
+    const maxStaleDays = options?.maxStaleDays ?? 180;
+    const now = options?.now ? options.now() : Date.now();
+    const findings = [];
+    for (const page of pages) {
+        const { modified: jsonLdModified, published: jsonLdPublished } = findDatesInJsonLd(page.jsonLd);
+        const htmlModified = findDateModifiedInHtml(page.html);
+        const visibleSignal = hasVisibleUpdateSignal(page.contentText);
+        // A true modification signal is `dateModified`, a modification meta tag, or visible
+        // "Last updated" text. `datePublished` alone (a page born in 2019 and never touched)
+        // is NOT a modification signal — fall through to the no-signal warning.
+        const hasModificationSignal = Boolean(jsonLdModified || htmlModified || visibleSignal);
+        if (!hasModificationSignal) {
+            findings.push({
+                ruleId: "aeo/freshness-signals",
+                severity: "warning",
+                message: `${page.url} has no dateModified signal (no JSON-LD dateModified, no modification meta tag, no visible "Last updated").`,
+                pageUrl: page.url,
+                fix: `Add a freshness signal so AI engines know the page is current. Three recommended places: ` +
+                    `(1) dateModified in your JSON-LD schema, ` +
+                    `(2) a visible "Last updated: YYYY-MM-DD" line in the page content, ` +
+                    `(3) accurate <lastmod> in your sitemap. ` +
+                    `For pSEO templates, automate dateModified to update when your underlying data source changes.`,
+            });
+            continue;
+        }
+        const best = parseDateSafe(jsonLdModified) ??
+            parseDateSafe(htmlModified) ??
+            parseDateSafe(jsonLdPublished) ??
+            parseDateSafe(page.publishedDate);
+        if (best) {
+            const ageDays = Math.floor((now - best.getTime()) / DAY_MS);
+            if (ageDays > maxStaleDays) {
+                findings.push({
+                    ruleId: "aeo/freshness-signals",
+                    severity: "info",
+                    message: `${page.url} was last updated ${ageDays} days ago (threshold: ${maxStaleDays}).`,
+                    pageUrl: page.url,
+                    fix: `AI engines prioritize fresh content for citation. If the page is still accurate, ` +
+                        `refresh the visible date and bump dateModified. If information has changed, update the body accordingly.`,
+                });
+            }
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=freshness-signals.js.map

package/dist/rules/aeo/freshness-signals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness-signals.js","sourceRoot":"","sources":["../../../src/rules/aeo/freshness-signals.ts"],"names":[],"mappings":"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"}

package/dist/rules/aeo/llms-txt.d.ts

@@ -0,0 +1,24 @@
+import type { RuleResult } from "../../types.js";
+export interface LlmsTxtFetcher {
+    (url: string): Promise<string | null>;
+}
+/**
+ * Minimal shape check for the emerging llms.txt convention:
+ *   - First non-empty line is an `# H1` title
+ *   - At least one `## ` section heading
+ *   - At least one markdown link line under a section
+ * Deliberately lenient: the spec is still evolving, so only reject obvious garbage.
+ */
+export declare function validateLlmsTxt(content: string): {
+    valid: boolean;
+    reason?: string;
+};
+/**
+ * Check for /llms.txt at the origin. Site-level rule — runs once, not per page.
+ */
+export interface LlmsTxtRuleOptions {
+    /** Timeout in ms for the /llms.txt fetch. Default: 10 000. */
+    timeoutMs?: number;
+}
+export declare function llmsTxtRule(source: string, fetcherOrOptions?: LlmsTxtFetcher | LlmsTxtRuleOptions): Promise<RuleResult[]>;
+//# sourceMappingURL=llms-txt.d.ts.map

package/dist/rules/aeo/llms-txt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llms-txt.d.ts","sourceRoot":"","sources":["../../../src/rules/aeo/llms-txt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,MAAM,WAAW,cAAc;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACvC;AAkBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAgCpF;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,gBAAgB,GAAE,cAAc,GAAG,kBAAuB,GACzD,OAAO,CAAC,UAAU,EAAE,CAAC,CAqCvB"}