@pseolint/core 0.6.6 → 0.7.1

package/README.md

@@ -1,8 +1,8 @@
 # @pseolint/core
 
-> Programmatic SEO audit engine — 45 rules, surfaced per-template, on every monitored release.
+> Programmatic SEO audit engine — 44 rules, surfaced per-template, on every monitored release.
 
-The core engine behind [pseolint](https://www.npmjs.com/package/pseolint) v0.6.2. Use this package to embed pSEO auditing into your own tools, CI pipelines, or SaaS products.
+The core engine behind [pseolint](https://www.npmjs.com/package/pseolint) v0.7.0. Use this package to embed pSEO auditing into your own tools, CI pipelines, or SaaS products.
 
 ## Install
 
@@ -34,7 +34,7 @@ for (const t of result.templates) {
 
 ## What It Checks
 
-45 rules grouped into 4 scoring super-categories (v0.4): **Integrity** (spam + content + cannibal, weight 0.50), **Discoverability** (links + tech, 0.20), **Citation** (aeo + schema, 0.25), **Data** (0.05). Source-tree namespaces remain `spam/*`, `aeo/*`, etc. for stable rule IDs.
+44 rules grouped into 4 scoring super-categories (v0.4): **Integrity** (spam + content + cannibal, weight 0.50), **Discoverability** (links + tech, 0.20), **Citation** (aeo + schema, 0.25), **Data** (0.05). Source-tree namespaces remain `spam/*`, `aeo/*`, etc. for stable rule IDs.
 
 - **Spam / SpamBrain risk** (8) — near-duplicate (SimHash), entity-swap doorways, thin content, boilerplate ratio, template diversity, template coverage, publication velocity, doorway pattern (cluster-collapsed since v0.5.2)
 - **Technical SEO** (9) — canonical consistency, canonical/noindex and robots/noindex conflicts, sitemap completeness, robots compliance, redirect chains, soft 404s, hreflang reciprocity, robots-sitemap presence, **og-completeness** (v0.5.2)

package/dist/algorithms/authority/commoncrawl.d.ts

@@ -0,0 +1,13 @@
+import type { AuthorityProvider } from "./provider.js";
+/**
+ * Authority from a pre-processed Common Crawl host-webgraph table
+ * (registrable domain -> harmonic-centrality rank normalized to 0–100).
+ * Owned/permissive data (CC license; attribution courtesy). The table is built
+ * offline (gated); this provider is a pure lookup. Empty table -> null.
+ */
+export declare class CommonCrawlProvider implements AuthorityProvider {
+    private readonly table;
+    constructor(table: ReadonlyMap<string, number>);
+    authorityFor(domain: string): Promise<number | null>;
+}
+//# sourceMappingURL=commoncrawl.d.ts.map

package/dist/algorithms/authority/commoncrawl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commoncrawl.d.ts","sourceRoot":"","sources":["../../../src/algorithms/authority/commoncrawl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,iBAAiB;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC;IAEzD,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAI3D"}

package/dist/algorithms/authority/commoncrawl.js

@@ -0,0 +1,17 @@
+/**
+ * Authority from a pre-processed Common Crawl host-webgraph table
+ * (registrable domain -> harmonic-centrality rank normalized to 0–100).
+ * Owned/permissive data (CC license; attribution courtesy). The table is built
+ * offline (gated); this provider is a pure lookup. Empty table -> null.
+ */
+export class CommonCrawlProvider {
+    table;
+    constructor(table) {
+        this.table = table;
+    }
+    async authorityFor(domain) {
+        const v = this.table.get(domain);
+        return typeof v === "number" && Number.isFinite(v) ? v : null;
+    }
+}
+//# sourceMappingURL=commoncrawl.js.map

package/dist/algorithms/authority/commoncrawl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commoncrawl.js","sourceRoot":"","sources":["../../../src/algorithms/authority/commoncrawl.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,OAAO,mBAAmB;IACD;IAA7B,YAA6B,KAAkC;QAAlC,UAAK,GAAL,KAAK,CAA6B;IAAG,CAAC;IAEnE,KAAK,CAAC,YAAY,CAAC,MAAc;QAC/B,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACjC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAChE,CAAC;CACF"}

package/dist/algorithms/authority/openpagerank.d.ts

@@ -0,0 +1,19 @@
+import type { AuthorityProvider } from "./provider.js";
+type FetchFn = (url: string, init?: {
+    headers?: Record<string, string>;
+}) => Promise<Response>;
+/**
+ * Open PageRank authority source. Returns 0–100 (page_rank_decimal × 10).
+ * Requires a free API key; with no key it returns null (no calls). Any network
+ * or per-domain error → null. Attribution ("Open PageRank by DomCop") is the
+ * caller's responsibility when displaying.
+ */
+export declare class OpenPageRankProvider implements AuthorityProvider {
+    private readonly apiKey;
+    private readonly fetchFn;
+    private readonly timeoutMs;
+    constructor(apiKey: string, fetchFn?: FetchFn, timeoutMs?: number);
+    authorityFor(domain: string): Promise<number | null>;
+}
+export {};
+//# sourceMappingURL=openpagerank.d.ts.map

package/dist/algorithms/authority/openpagerank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openpagerank.d.ts","sourceRoot":"","sources":["../../../src/algorithms/authority/openpagerank.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD,KAAK,OAAO,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAQ/F;;;;;GAKG;AACH,qBAAa,oBAAqB,YAAW,iBAAiB;IAE1D,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAFT,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,OAAgD,EACzD,SAAS,SAAO;IAG7B,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAoB3D"}

package/dist/algorithms/authority/openpagerank.js

@@ -0,0 +1,42 @@
+/**
+ * Open PageRank authority source. Returns 0–100 (page_rank_decimal × 10).
+ * Requires a free API key; with no key it returns null (no calls). Any network
+ * or per-domain error → null. Attribution ("Open PageRank by DomCop") is the
+ * caller's responsibility when displaying.
+ */
+export class OpenPageRankProvider {
+    apiKey;
+    fetchFn;
+    timeoutMs;
+    constructor(apiKey, fetchFn = globalThis.fetch, timeoutMs = 8000) {
+        this.apiKey = apiKey;
+        this.fetchFn = fetchFn;
+        this.timeoutMs = timeoutMs;
+    }
+    async authorityFor(domain) {
+        if (!this.apiKey)
+            return null;
+        const url = `https://openpagerank.com/api/v1.0/getPageRank?domains[]=${encodeURIComponent(domain)}`;
+        let res;
+        try {
+            res = await this.fetchFn(url, { headers: { "API-OPR": this.apiKey } });
+        }
+        catch {
+            return null;
+        }
+        if (!res.ok)
+            return null;
+        let body;
+        try {
+            body = (await res.json());
+        }
+        catch {
+            return null;
+        }
+        const entry = body.response?.find((e) => e.domain === domain) ?? body.response?.[0];
+        if (!entry || entry.status_code !== 200 || typeof entry.page_rank_decimal !== "number")
+            return null;
+        return Math.round(entry.page_rank_decimal * 10);
+    }
+}
+//# sourceMappingURL=openpagerank.js.map

package/dist/algorithms/authority/openpagerank.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openpagerank.js","sourceRoot":"","sources":["../../../src/algorithms/authority/openpagerank.ts"],"names":[],"mappings":"AAUA;;;;;GAKG;AACH,MAAM,OAAO,oBAAoB;IAEZ;IACA;IACA;IAHnB,YACmB,MAAc,EACd,UAAmB,UAAU,CAAC,KAA2B,EACzD,YAAY,IAAI;QAFhB,WAAM,GAAN,MAAM,CAAQ;QACd,YAAO,GAAP,OAAO,CAAkD;QACzD,cAAS,GAAT,SAAS,CAAO;IAChC,CAAC;IAEJ,KAAK,CAAC,YAAY,CAAC,MAAc;QAC/B,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QAC9B,MAAM,GAAG,GAAG,2DAA2D,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;QACpG,IAAI,GAAa,CAAC;QAClB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACzE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QACzB,IAAI,IAA+B,CAAC;QACpC,IAAI,CAAC;YACH,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA8B,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC;QACpF,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,WAAW,KAAK,GAAG,IAAI,OAAO,KAAK,CAAC,iBAAiB,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACpG,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,iBAAiB,GAAG,EAAE,CAAC,CAAC;IAClD,CAAC;CACF"}

package/dist/algorithms/authority/provider.d.ts

@@ -0,0 +1,16 @@
+/** A source of domain authority on a 0–100 scale (higher = more authoritative). */
+export interface AuthorityProvider {
+    /** Authority for a registrable domain; null when unknown/unavailable. */
+    authorityFor(domain: string): Promise<number | null>;
+}
+/**
+ * Combines several providers. Returns the MAX non-null score (any source
+ * vouching for authority is sufficient evidence). All-null → null → callers
+ * apply no moderation (fail-safe). A source that throws is treated as null.
+ */
+export declare class CompositeAuthorityProvider implements AuthorityProvider {
+    private readonly sources;
+    constructor(sources: ReadonlyArray<AuthorityProvider>);
+    authorityFor(domain: string): Promise<number | null>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/algorithms/authority/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../src/algorithms/authority/provider.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACtD;AAED;;;;GAIG;AACH,qBAAa,0BAA2B,YAAW,iBAAiB;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC;IAEhE,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAa3D"}

package/dist/algorithms/authority/provider.js

@@ -0,0 +1,24 @@
+/**
+ * Combines several providers. Returns the MAX non-null score (any source
+ * vouching for authority is sufficient evidence). All-null → null → callers
+ * apply no moderation (fail-safe). A source that throws is treated as null.
+ */
+export class CompositeAuthorityProvider {
+    sources;
+    constructor(sources) {
+        this.sources = sources;
+    }
+    async authorityFor(domain) {
+        const results = await Promise.all(this.sources.map(async (s) => {
+            try {
+                return await s.authorityFor(domain);
+            }
+            catch {
+                return null;
+            }
+        }));
+        const vals = results.filter((v) => v !== null && Number.isFinite(v));
+        return vals.length ? Math.max(...vals) : null;
+    }
+}
+//# sourceMappingURL=provider.js.map

package/dist/algorithms/authority/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../../src/algorithms/authority/provider.ts"],"names":[],"mappings":"AAMA;;;;GAIG;AACH,MAAM,OAAO,0BAA0B;IACR;IAA7B,YAA6B,OAAyC;QAAzC,YAAO,GAAP,OAAO,CAAkC;IAAG,CAAC;IAE1E,KAAK,CAAC,YAAY,CAAC,MAAc;QAC/B,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;YAC3B,IAAI,CAAC;gBACH,OAAO,MAAM,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YACtC,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC,CAAC,CACH,CAAC;QACF,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAClF,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAChD,CAAC;CACF"}

package/dist/algorithms/auto-entity-mask.d.ts

@@ -0,0 +1,19 @@
+import type { EntityMaskPattern, ParsedPage } from "../types.js";
+export interface DeriveOptions {
+    /** Only derive from URL-template clusters with at least this many siblings. */
+    minClusterSize?: number;
+    /** Ignore tokens shorter than this. */
+    minTokenLength?: number;
+    /** Placeholder substituted for masked entities. */
+    placeholder?: string;
+    /** Enable URL-slug token derivation. */
+    urlSlug?: boolean;
+    /** Enable capitalized-content-token derivation. */
+    contentDiff?: boolean;
+    /** Hard cap on total derived tokens (over-masking guard). */
+    maxTokens?: number;
+}
+type MaskPage = Pick<ParsedPage, "url" | "contentText">;
+export declare function deriveEntityPatterns(pages: ReadonlyArray<MaskPage>, opts?: DeriveOptions): EntityMaskPattern[];
+export {};
+//# sourceMappingURL=auto-entity-mask.d.ts.map

package/dist/algorithms/auto-entity-mask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-entity-mask.d.ts","sourceRoot":"","sources":["../../src/algorithms/auto-entity-mask.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGjE,MAAM,WAAW,aAAa;IAC5B,+EAA+E;IAC/E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uCAAuC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mDAAmD;IACnD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,KAAK,QAAQ,GAAG,IAAI,CAAC,UAAU,EAAE,KAAK,GAAG,aAAa,CAAC,CAAC;AA4DxD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,iBAAiB,EAAE,CA0C9G"}

package/dist/algorithms/auto-entity-mask.js

@@ -0,0 +1,102 @@
+import { normalizePathToTemplate } from "../template-detection.js";
+/** Tiny stopword set so varying function-words never become entities. */
+const STOPWORDS = new Set([
+    "the", "and", "for", "with", "from", "this", "that", "your", "our", "are",
+    "you", "all", "new", "best", "top", "how", "what", "why", "who", "about",
+    "page", "home", "more", "get", "buy", "free", "online", "now",
+]);
+function pathOf(url) {
+    try {
+        return new URL(url).pathname;
+    }
+    catch {
+        return url.split("?")[0].split("#")[0];
+    }
+}
+function rawSegments(path) {
+    return path.replace(/^\/+|\/+$/g, "").split("/").filter(Boolean);
+}
+/** Tokens from `:slug` path segments only (numeric `:n` segments are not name-entities). */
+function urlSlugTokens(path) {
+    const tmplSegs = normalizePathToTemplate(path).replace(/^\//, "").split("/");
+    const raw = rawSegments(path);
+    const out = [];
+    tmplSegs.forEach((t, i) => {
+        if (t === ":slug" && raw[i]) {
+            for (const tok of raw[i].split(/[-_]/))
+                out.push(tok.toLowerCase());
+        }
+    });
+    return out;
+}
+const CONTENT_ENTITY_RE = /\b[A-Z][a-zA-Z]{2,}\b/g;
+function contentEntityTokens(text) {
+    return (text.match(CONTENT_ENTITY_RE) ?? []).map((t) => t.toLowerCase());
+}
+/**
+ * Tokens whose presence VARIES across cluster members: present in at least one
+ * member but not in all. Constant template vocabulary (in every member) is
+ * excluded; per-page entities (in a subset) are kept.
+ */
+function varyingTokens(perMember, minLen) {
+    const memberSets = perMember.map((toks) => new Set(toks.filter((t) => t.length >= minLen && !STOPWORDS.has(t))));
+    const presence = new Map();
+    for (const s of memberSets)
+        for (const t of s)
+            presence.set(t, (presence.get(t) ?? 0) + 1);
+    const n = memberSets.length;
+    const out = new Set();
+    for (const [t, c] of presence)
+        if (c >= 1 && c < n)
+            out.add(t);
+    return out;
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export function deriveEntityPatterns(pages, opts) {
+    const minCluster = opts?.minClusterSize ?? 3;
+    const minLen = opts?.minTokenLength ?? 3;
+    const placeholder = opts?.placeholder ?? "[ENTITY]";
+    const useUrl = opts?.urlSlug ?? true;
+    const useContent = opts?.contentDiff ?? true;
+    const maxTokens = opts?.maxTokens ?? 500;
+    // Cluster pages by normalized URL template.
+    const clusters = new Map();
+    for (const p of pages) {
+        const tmpl = normalizePathToTemplate(pathOf(p.url));
+        const bucket = clusters.get(tmpl);
+        if (bucket)
+            bucket.push(p);
+        else
+            clusters.set(tmpl, [p]);
+    }
+    const entities = new Set();
+    for (const members of clusters.values()) {
+        if (members.length < minCluster)
+            continue;
+        if (useUrl) {
+            for (const t of varyingTokens(members.map((m) => urlSlugTokens(pathOf(m.url))), minLen))
+                entities.add(t);
+        }
+        if (useContent) {
+            for (const t of varyingTokens(members.map((m) => contentEntityTokens(m.contentText ?? "")), minLen))
+                entities.add(t);
+        }
+    }
+    const tokens = [...entities].sort().slice(0, maxTokens);
+    if (tokens.length === 0)
+        return [];
+    const CHUNK = 200;
+    const patterns = [];
+    for (let i = 0; i < tokens.length; i += CHUNK) {
+        // Each token is metacharacter-escaped (escapeRegex) and joined into a bounded,
+        // backtracking-free alternation `\b(?:a|b|c)\b` — no nested quantifiers, so this
+        // dynamic RegExp is ReDoS-safe by construction.
+        const alt = tokens.slice(i, i + CHUNK).map(escapeRegex).join("|");
+        // nosemgrep: javascript.lang.security.audit.detect-non-literal-regexp.detect-non-literal-regexp
+        patterns.push({ placeholder, pattern: new RegExp(`\\b(?:${alt})\\b`, "gi") });
+    }
+    return patterns;
+}
+//# sourceMappingURL=auto-entity-mask.js.map

package/dist/algorithms/auto-entity-mask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-entity-mask.js","sourceRoot":"","sources":["../../src/algorithms/auto-entity-mask.ts"],"names":[],"mappings":"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"}

package/dist/algorithms/example-regions.d.ts

@@ -0,0 +1,22 @@
+import type { ParsedPage } from "../types.js";
+/**
+ * Selector for "quoted example / code / sample" regions — markup that documents
+ * a pattern rather than expressing the page's own editorial voice.
+ *
+ * Content-quality heuristics that judge the page's OWN prose (cliché density,
+ * regurgitated-content signals) exclude these regions so a docs / explainer
+ * page that *quotes* a bad pattern to teach it isn't penalised for describing
+ * it. A real spam page puts clichés in flowing prose, not inside `<code>` or a
+ * `<blockquote>` example box — so the exclusion narrows false positives without
+ * opening a meaningful evasion path for a low-confidence proxy.
+ */
+export declare const EXAMPLE_REGION_SELECTOR = "pre, code, blockquote, figure, samp, kbd, [data-example]";
+/**
+ * Page body text with site chrome AND quoted-example regions removed.
+ *
+ * Falls back to the pre-parsed `contentText` when no html is available (e.g.
+ * synthetic unit-test pages). The fallback keeps example text in place — it's a
+ * best-effort path; the html path is what production audits exercise.
+ */
+export declare function proseTextExcludingExamples(page: ParsedPage): string;
+//# sourceMappingURL=example-regions.d.ts.map

package/dist/algorithms/example-regions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-regions.d.ts","sourceRoot":"","sources":["../../src/algorithms/example-regions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,6DACwB,CAAC;AAI7D;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CASnE"}

package/dist/algorithms/example-regions.js

@@ -0,0 +1,32 @@
+import { load } from "cheerio";
+/**
+ * Selector for "quoted example / code / sample" regions — markup that documents
+ * a pattern rather than expressing the page's own editorial voice.
+ *
+ * Content-quality heuristics that judge the page's OWN prose (cliché density,
+ * regurgitated-content signals) exclude these regions so a docs / explainer
+ * page that *quotes* a bad pattern to teach it isn't penalised for describing
+ * it. A real spam page puts clichés in flowing prose, not inside `<code>` or a
+ * `<blockquote>` example box — so the exclusion narrows false positives without
+ * opening a meaningful evasion path for a low-confidence proxy.
+ */
+export const EXAMPLE_REGION_SELECTOR = "pre, code, blockquote, figure, samp, kbd, [data-example]";
+const CHROME_SELECTOR = "header, footer, nav, script, style, noscript";
+/**
+ * Page body text with site chrome AND quoted-example regions removed.
+ *
+ * Falls back to the pre-parsed `contentText` when no html is available (e.g.
+ * synthetic unit-test pages). The fallback keeps example text in place — it's a
+ * best-effort path; the html path is what production audits exercise.
+ */
+export function proseTextExcludingExamples(page) {
+    if (page.html && page.html.trim()) {
+        const $ = load(page.html);
+        $(`${CHROME_SELECTOR}, ${EXAMPLE_REGION_SELECTOR}`).remove();
+        const body = $("body");
+        const text = body.length ? body.text() : $.root().text();
+        return text.replace(/\s+/g, " ").trim();
+    }
+    return page.contentText ?? "";
+}
+//# sourceMappingURL=example-regions.js.map

package/dist/algorithms/example-regions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-regions.js","sourceRoot":"","sources":["../../src/algorithms/example-regions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAG/B;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAClC,0DAA0D,CAAC;AAE7D,MAAM,eAAe,GAAG,8CAA8C,CAAC;AAEvE;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CAAC,IAAgB;IACzD,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;QAClC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC,CAAC,GAAG,eAAe,KAAK,uBAAuB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;QAC7D,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;QACvB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;QACzD,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC;AAChC,CAAC"}

package/dist/algorithms/fact-extraction.d.ts

@@ -0,0 +1,46 @@
+import type { EntityMaskPattern, ParsedPage } from "../types.js";
+export type FactKind = "money" | "percent" | "timeframe" | "date" | "isoDate" | "form" | "ratio" | "measurement";
+export interface FactSpan {
+    value: string;
+    kind: FactKind;
+}
+export interface NamedEntity {
+    value: string;
+    source: "proper-noun" | "cue-word" | "json-ld";
+    type?: "organization" | "person" | "product" | "law" | "standard" | "place" | "other";
+}
+export interface Citation {
+    href: string;
+    domain: string;
+    authority: "authoritative" | "general";
+    reason?: "tld" | "allowlist";
+}
+export interface GroundedClaim {
+    sentence: string;
+    facts: string[];
+    citations: string[];
+}
+export interface PageFacts {
+    /** EXACTLY today's extractRawFacts() output (run on entity-masked text). Frozen. */
+    citableFacts: string[];
+    measurements: FactSpan[];
+    namedEntities: NamedEntity[];
+    citations: Citation[];
+    groundedClaims: GroundedClaim[];
+}
+export declare function extractCitableFacts(text: string): string[];
+export declare function extractMeasurements(maskedText: string): FactSpan[];
+export declare function extractNamedEntities(maskedText: string, jsonLd?: unknown[]): NamedEntity[];
+export declare const DEFAULT_CITATION_ALLOWLIST: readonly string[];
+export declare function registrableDomain(host: string): string;
+export declare function classifyCitations(resolvedHrefs: readonly string[], pageUrl: string, allowlist?: readonly string[]): Citation[];
+export declare function hasAuthoritativeCitation(resolvedHrefs: readonly string[], pageUrl: string, allowlist?: readonly string[]): boolean;
+/**
+ * Deterministic approximation of "a verifiable claim": a block (<p>/<li>) that
+ * contains a statistic AND an outbound citation. Approximated at block level,
+ * not exact sentence level — documented limitation. Detects co-occurrence, not
+ * semantic truth. Consume at `speculative` confidence.
+ */
+export declare function extractGroundedClaims(html: string, pageUrl: string, allowlist?: readonly string[]): GroundedClaim[];
+export declare function extractPageFacts(page: Pick<ParsedPage, "url" | "contentText" | "html" | "resolvedHrefs" | "jsonLd">, entityPatterns: EntityMaskPattern[], allowlist?: readonly string[]): PageFacts;
+//# sourceMappingURL=fact-extraction.d.ts.map

package/dist/algorithms/fact-extraction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact-extraction.d.ts","sourceRoot":"","sources":["../../src/algorithms/fact-extraction.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEjE,MAAM,MAAM,QAAQ,GAChB,OAAO,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAC/D,OAAO,GAAG,aAAa,CAAC;AAE5B,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,aAAa,GAAG,UAAU,GAAG,SAAS,CAAC;IAC/C,IAAI,CAAC,EAAE,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,KAAK,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC;CACvF;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,eAAe,GAAG,SAAS,CAAC;IACvC,MAAM,CAAC,EAAE,KAAK,GAAG,WAAW,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,SAAS;IACxB,oFAAoF;IACpF,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,QAAQ,EAAE,CAAC;IACzB,aAAa,EAAE,WAAW,EAAE,CAAC;IAC7B,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,cAAc,EAAE,aAAa,EAAE,CAAC;CACjC;AAqBD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ1D;AAWD,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,EAAE,CAclE;AA4BD,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,WAAW,EAAE,CAe9F;AAED,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAUvD,CAAC;AAWF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMtD;AAMD,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,SAAS,MAAM,EAA+B,GACxD,QAAQ,EAAE,CAqBZ;AAED,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,SAAS,MAAM,EAA+B,GACxD,OAAO,CAET;AAYD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,SAAS,MAAM,EAA+B,GACxD,aAAa,EAAE,CA0BjB;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,KAAK,GAAG,aAAa,GAAG,MAAM,GAAG,eAAe,GAAG,QAAQ,CAAC,EACnF,cAAc,EAAE,iBAAiB,EAAE,EACnC,SAAS,GAAE,SAAS,MAAM,EAA+B,GACxD,SAAS,CASX"}