seofleet-cli 0.2.0__py3-none-any.whl

seofleet/__init__.py

@@ -0,0 +1,104 @@
+"""
+Programmatic / agent-native entry point.
+
+    from seofleet import load_site, run_checks, select_checks, ALL_CHECKS
+
+    ctx = load_site("https://example.com")
+    results = run_checks(ALL_CHECKS, ctx)
+    for r in results:
+        print(r.status, r.name, r.message)
+
+This is the Python port of the seofleet-cli npm package
+(https://www.npmjs.com/package/seofleet-cli). Both distributions run the
+same 12 technical-SEO/GEO checks; see
+https://github.com/RudrenduPaul/SeoFleet for the canonical documentation,
+comparison table, and the original TypeScript source.
+"""
+from .checks import (
+    ALL_CHECKS,
+    GEO_CHECKS,
+    TECHNICAL_CHECKS,
+    ai_crawler_directives_check,
+    canonical_check,
+    content_extraction_check,
+    faq_schema_check,
+    heading_structure_check,
+    image_alt_check,
+    llms_txt_check,
+    meta_description_check,
+    robots_txt_check,
+    sitemap_xml_check,
+    structured_data_check,
+    title_check,
+)
+from .config import CONFIG_FILENAME, SeoFleetConfig, default_config, load_config, select_checks
+from .errors import SeoFleetError
+from .fetch_utils import FetchedResource, assert_http_url, safe_fetch
+from .fleet import FleetManifest, FleetManifestEntry, FleetSiteResult, load_fleet_manifest, run_fleet
+from .format import (
+    format_check_results_json,
+    format_check_results_text,
+    format_fleet_results_json,
+    format_fleet_results_text,
+    format_init_result_json,
+    format_init_result_text,
+)
+from .init import InitResult, init_project
+from .runner import has_failure, run_checks
+from .site_resources import build_check_context, fetch_site_resources, load_site
+from .types import Check, CheckContext, CheckResult, SiteResources
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "__version__",
+    # Types
+    "Check",
+    "CheckContext",
+    "CheckResult",
+    "SiteResources",
+    "FetchedResource",
+    "SeoFleetError",
+    "SeoFleetConfig",
+    "InitResult",
+    "FleetManifest",
+    "FleetManifestEntry",
+    "FleetSiteResult",
+    # Checks
+    "ALL_CHECKS",
+    "TECHNICAL_CHECKS",
+    "GEO_CHECKS",
+    "title_check",
+    "meta_description_check",
+    "canonical_check",
+    "robots_txt_check",
+    "sitemap_xml_check",
+    "heading_structure_check",
+    "image_alt_check",
+    "structured_data_check",
+    "llms_txt_check",
+    "ai_crawler_directives_check",
+    "faq_schema_check",
+    "content_extraction_check",
+    # Core functions
+    "run_checks",
+    "has_failure",
+    "fetch_site_resources",
+    "build_check_context",
+    "load_site",
+    "safe_fetch",
+    "assert_http_url",
+    "load_config",
+    "default_config",
+    "select_checks",
+    "CONFIG_FILENAME",
+    "init_project",
+    "load_fleet_manifest",
+    "run_fleet",
+    "format_check_results_text",
+    "format_check_results_json",
+    "format_fleet_results_text",
+    "format_fleet_results_json",
+    "format_init_result_text",
+    "format_init_result_json",
+]

seofleet/checks/__init__.py

@@ -0,0 +1,83 @@
+"""Ported from src/checks/index.ts."""
+from __future__ import annotations
+
+from typing import List
+
+from ..types import Check
+from .geo.ai_crawler_directives import ai_crawler_directives_check
+from .geo.content_extraction import content_extraction_check
+from .geo.faq_schema import faq_schema_check
+from .geo.link_header import link_header_check
+from .geo.llms_txt import llms_txt_check
+from .geo.markdown_negotiation import markdown_negotiation_check
+from .geo.organization_schema import organization_schema_check
+from .geo.speakable_schema import speakable_schema_check
+from .geo.structured_data import structured_data_check
+from .technical.canonical import canonical_check
+from .technical.heading_structure import heading_structure_check
+from .technical.image_alt import image_alt_check
+from .technical.image_weight import image_weight_check
+from .technical.meta_description import meta_description_check
+from .technical.open_graph import open_graph_check
+from .technical.robots_meta_directives import robots_meta_directives_check
+from .technical.redirect_chain import redirect_chain_check
+from .technical.robots_txt import robots_txt_check
+from .technical.sitemap_xml import sitemap_xml_check
+from .technical.title import title_check
+from .technical.twitter_card import twitter_card_check
+
+TECHNICAL_CHECKS: List[Check] = [
+    title_check,
+    meta_description_check,
+    canonical_check,
+    robots_txt_check,
+    sitemap_xml_check,
+    heading_structure_check,
+    image_alt_check,
+    open_graph_check,
+    twitter_card_check,
+    robots_meta_directives_check,
+    image_weight_check,
+    redirect_chain_check,
+]
+
+GEO_CHECKS: List[Check] = [
+    structured_data_check,
+    llms_txt_check,
+    ai_crawler_directives_check,
+    faq_schema_check,
+    content_extraction_check,
+    speakable_schema_check,
+    organization_schema_check,
+    markdown_negotiation_check,
+    link_header_check,
+]
+
+ALL_CHECKS: List[Check] = [*TECHNICAL_CHECKS, *GEO_CHECKS]
+
+__all__ = [
+    "TECHNICAL_CHECKS",
+    "GEO_CHECKS",
+    "ALL_CHECKS",
+    "title_check",
+    "meta_description_check",
+    "canonical_check",
+    "robots_txt_check",
+    "sitemap_xml_check",
+    "heading_structure_check",
+    "image_alt_check",
+    "open_graph_check",
+    "twitter_card_check",
+    "robots_meta_directives_check",
+    "image_weight_check",
+    "redirect_chain_check",
+    "structured_data_check",
+    "llms_txt_check",
+    "ai_crawler_directives_check",
+    "faq_schema_check",
+    "content_extraction_check",
+    "speakable_schema_check",
+    "organization_schema_check",
+    "markdown_negotiation_check",
+    "link_header_check",
+]

seofleet/checks/geo/ai_crawler_directives.py

@@ -0,0 +1,89 @@
+"""Ported from src/checks/geo/ai-crawler-directives.ts."""
+from __future__ import annotations
+
+from typing import Dict, List
+
+from ...types import Check, CheckContext, CheckResult
+
+_ID = "ai-crawler-directives"
+_NAME = "AI crawler directives"
+_CATEGORY = "geo"
+
+# The AI crawlers checked for are reported on, never prescribed -- whether
+# to allow or disallow any of them is a genuine site-owner choice this tool
+# does not take a position on. Training crawlers (GPTBot, ClaudeBot,
+# Google-Extended, Applebot-Extended) and search/retrieval crawlers
+# (OAI-SearchBot, Claude-SearchBot, PerplexityBot) are separate,
+# independently blockable user agents at OpenAI and Anthropic -- a real
+# robots.txt distinction, not a cosmetic one: blocking a training bot has
+# no effect on whether that same company's assistant can still retrieve
+# and cite the page live via its search bot, and vice versa.
+TRACKED_BOTS = [
+    "GPTBot",
+    "OAI-SearchBot",
+    "ClaudeBot",
+    "Claude-SearchBot",
+    "PerplexityBot",
+    "Google-Extended",
+    "Applebot-Extended",
+]
+
+
+def parse_ai_crawler_directives(robots_txt: str, bots: List[str] = TRACKED_BOTS) -> Dict[str, str]:
+    """
+    A deliberately simple robots.txt parser: it tracks the single most
+    recent User-agent line and attributes the next Allow/Disallow lines to
+    it. It does not handle grouped multi-agent blocks (several consecutive
+    User-agent lines sharing one set of rules) -- a documented limitation,
+    not a bug, for v0.1.
+    """
+    result: Dict[str, str] = {bot: "unspecified" for bot in bots}
+
+    current_agent = None
+    for raw_line in robots_txt.splitlines():
+        line = raw_line.split("#", 1)[0].strip()
+        if not line:
+            continue
+
+        sep_index = line.find(":")
+        if sep_index == -1:
+            continue
+
+        key = line[:sep_index].strip().lower()
+        value = line[sep_index + 1 :].strip()
+
+        if key == "user-agent":
+            current_agent = value
+            continue
+
+        if key in ("disallow", "allow") and current_agent:
+            matched_bot = next((bot for bot in bots if bot.lower() == current_agent.lower()), None)
+            if matched_bot is None:
+                continue
+            if key == "disallow" and value == "":
+                continue  # an empty Disallow means "allow everything"; leave unspecified rather than assert allow
+            result[matched_bot] = "disallow" if key == "disallow" else "allow"
+
+    return result
+
+
+def _run(ctx: CheckContext) -> CheckResult:
+    robots = ctx.resources.robots_txt
+
+    if not robots.ok or robots.body is None:
+        return CheckResult(
+            _ID, _NAME, _CATEGORY, "WARN",
+            "robots.txt is unreachable, so AI-crawler directives could not be determined.",
+            "Add a reachable robots.txt if you want to state an explicit policy for AI crawlers (GPTBot, OAI-SearchBot, ClaudeBot, Claude-SearchBot, PerplexityBot, Google-Extended, Applebot-Extended).",
+        )
+
+    directives = parse_ai_crawler_directives(robots.body)
+    summary = ", ".join(f"{bot}: {directives[bot]}" for bot in TRACKED_BOTS)
+
+    return CheckResult(
+        _ID, _NAME, _CATEGORY, "PASS",
+        f"AI crawler directives found in robots.txt -- {summary}. This is a report of what's configured, not a recommendation.",
+    )
+
+
+ai_crawler_directives_check = Check(id=_ID, name=_NAME, category=_CATEGORY, run=_run)

seofleet/checks/geo/content_extraction.py

@@ -0,0 +1,72 @@
+"""Ported from src/checks/geo/content-extraction.ts."""
+from __future__ import annotations
+
+from ...types import Check, CheckContext, CheckResult
+
+_ID = "content-extraction"
+_NAME = "Content extraction friendliness"
+_CATEGORY = "geo"
+_UNSTRUCTURED_BLOCK_THRESHOLD = 800
+_PARAGRAPH_MIN_LENGTH = 30
+_STRUCTURE_TAGS = ("h1", "h2", "h3", "h4", "h5", "h6", "p", "li")
+_HEADING_TAGS = ("h1", "h2", "h3", "h4", "h5", "h6")
+
+
+def _run(ctx: CheckContext) -> CheckResult:
+    """
+    A heuristic, not a precise measurement: it checks whether the page has
+    heading/paragraph structure a generative engine can chunk, versus a
+    large amount of text crammed into a single element with no internal
+    structure. It cannot judge semantic quality, and it cannot see content
+    that only appears after client-side JavaScript runs -- this tool does
+    not execute JS or use a headless browser by design, so a page that is
+    empty until hydrated will read as unstructured here even if it renders
+    well structured in a real browser. Treat WARN as "worth a manual look",
+    not as a definitive verdict.
+    """
+    if ctx.root is None:
+        return CheckResult(
+            _ID, _NAME, _CATEGORY, "FAIL",
+            "Homepage could not be fetched, so content extraction friendliness could not be checked.",
+            "Confirm siteUrl in seofleet.json is correct and reachable.",
+        )
+
+    root = ctx.root
+    main = root.find_first(("main",))
+    scope = main if main is not None else (root.find_first(("body",)) or root)
+
+    heading_count = len(scope.find_all(_HEADING_TAGS))
+    paragraph_count = sum(
+        1 for el in scope.find_all(("p", "li")) if len(el.text().strip()) > _PARAGRAPH_MIN_LENGTH
+    )
+
+    max_unstructured_length = 0
+    for div in scope.find_all(("div",)):
+        has_structure = len(div.find_all(_STRUCTURE_TAGS)) > 0
+        if not has_structure:
+            length = len(div.text().strip())
+            if length > max_unstructured_length:
+                max_unstructured_length = length
+
+    if heading_count == 0 and paragraph_count == 0:
+        return CheckResult(
+            _ID, _NAME, _CATEGORY, "WARN",
+            "No headings or paragraph-level structure detected; a generative engine may struggle to extract distinct sections from this page.",
+            "Break content into headings (<h2>, <h3>, ...) and paragraphs (<p>) rather than unstructured text.",
+        )
+
+    if max_unstructured_length > _UNSTRUCTURED_BLOCK_THRESHOLD:
+        return CheckResult(
+            _ID, _NAME, _CATEGORY, "WARN",
+            f"Found a {max_unstructured_length}-character block of text with no internal heading or paragraph structure.",
+            "Break large unstructured blocks into headed sections and paragraphs.",
+        )
+
+    return CheckResult(
+        _ID, _NAME, _CATEGORY, "PASS",
+        f"Found {heading_count} heading(s) and {paragraph_count} structured text block(s); "
+        "content appears reasonably extractable. (Heuristic: cannot assess semantic quality or JS-rendered content.)",
+    )
+
+
+content_extraction_check = Check(id=_ID, name=_NAME, category=_CATEGORY, run=_run)

seofleet/checks/geo/faq_schema.py

@@ -0,0 +1,58 @@
+"""Ported from src/checks/geo/faq-schema.ts."""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ...html_util import get_scripts_by_type
+from ...types import Check, CheckContext, CheckResult
+
+_ID = "faq-schema"
+_NAME = "FAQ schema"
+_CATEGORY = "geo"
+
+
+def _contains_faq_type(value: Any) -> bool:
+    if isinstance(value, list):
+        return any(_contains_faq_type(item) for item in value)
+    if isinstance(value, dict):
+        type_value = value.get("@type")
+        if type_value == "FAQPage" or (isinstance(type_value, list) and "FAQPage" in type_value):
+            return True
+        if "@graph" in value:
+            return _contains_faq_type(value["@graph"])
+    return False
+
+
+def _run(ctx: CheckContext) -> CheckResult:
+    if ctx.root is None:
+        return CheckResult(
+            _ID, _NAME, _CATEGORY, "FAIL",
+            "Homepage could not be fetched, so FAQ schema could not be checked.",
+            "Confirm siteUrl in seofleet.json is correct and reachable.",
+        )
+
+    found = False
+    for script in get_scripts_by_type(ctx.root, "application/ld+json"):
+        if found:
+            break
+        try:
+            parsed = json.loads(script.text())
+            if _contains_faq_type(parsed):
+                found = True
+        except (json.JSONDecodeError, ValueError):
+            pass  # invalid JSON-LD is reported by the structured-data check; ignore here
+
+    # FAQ schema only applies to pages that actually have FAQ content, so
+    # its absence is informational, never a failure.
+    if not found:
+        return CheckResult(
+            _ID, _NAME, _CATEGORY, "WARN",
+            "No FAQPage structured data found.",
+            "If this page has an FAQ section, mark it up with FAQPage JSON-LD so generative engines can surface individual answers.",
+        )
+
+    return CheckResult(_ID, _NAME, _CATEGORY, "PASS", "FAQPage structured data found.")
+
+
+faq_schema_check = Check(id=_ID, name=_NAME, category=_CATEGORY, run=_run)

seofleet/checks/geo/link_header.py

@@ -0,0 +1,116 @@
+"""Ported from src/checks/geo/link-header.ts."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from ...types import Check, CheckContext, CheckResult
+
+_ID = "link-header"
+_NAME = "Link header (RFC 8288)"
+_CATEGORY = "geo"
+
+
+@dataclass
+class ParsedLink:
+    url: str
+    rel: Optional[str] = None
+    params: Dict[str, str] = field(default_factory=dict)
+
+
+def _split_top_level(header: str) -> List[str]:
+    """Splits a raw header value on top-level commas -- i.e. commas that
+    are neither inside a `<...>` URI-reference nor inside a `"..."` quoted
+    param value. RFC 8288 link-values themselves can contain commas in a
+    quoted title param (`title="a, b"`), so a naive `split(",")` would
+    misparse a multi-link header in that case."""
+    parts: List[str] = []
+    depth = 0
+    in_quotes = False
+    current = ""
+    for ch in header:
+        if ch == '"':
+            in_quotes = not in_quotes
+        if not in_quotes:
+            if ch == "<":
+                depth += 1
+            if ch == ">":
+                depth = max(0, depth - 1)
+        if ch == "," and depth == 0 and not in_quotes:
+            parts.append(current)
+            current = ""
+        else:
+            current += ch
+    if current.strip():
+        parts.append(current)
+    return parts
+
+
+def parse_link_header(header: str) -> List[ParsedLink]:
+    """Parses a raw RFC 8288 Link header value into one entry per
+    link-value, e.g. `<https://example.com/feed>; rel="alternate"` becomes
+    `ParsedLink(url="https://example.com/feed", rel="alternate", params={"rel": "alternate"})`.
+    Entries that don't match the `<url>; params` shape are dropped rather
+    than raising -- a malformed header is data for the check to report on,
+    not a reason to crash the run."""
+    links: List[ParsedLink] = []
+    for raw_part in _split_top_level(header):
+        part = raw_part.strip()
+        if not part:
+            continue
+        if not (part.startswith("<") and ">" in part):
+            continue
+        end = part.index(">")
+        url = part[1:end]
+        params_raw = part[end + 1 :]
+
+        params: Dict[str, str] = {}
+        for raw_param in params_raw.split(";"):
+            param_part = raw_param.strip()
+            if not param_part:
+                continue
+            eq = param_part.find("=")
+            if eq == -1:
+                continue
+            key = param_part[:eq].strip().lower()
+            value = param_part[eq + 1 :].strip()
+            if value.startswith('"') and value.endswith('"'):
+                value = value[1:-1]
+            params[key] = value
+
+        links.append(ParsedLink(url=url, rel=params.get("rel"), params=params))
+    return links
+
+
+def _run(ctx: CheckContext) -> CheckResult:
+    header = ctx.resources.homepage.link_header
+
+    # An RFC 8288 Link header is machine-readable service discovery
+    # (alternate feeds, API entry points, rel="describedby" schemas, etc.)
+    # that almost no site sends today -- its absence is informational only
+    # and never fails the run, same spirit as llms_txt.py.
+    if not header or not header.strip():
+        return CheckResult(
+            _ID, _NAME, _CATEGORY, "WARN",
+            "The homepage does not send a Link response header.",
+            'Optional: add an RFC 8288 Link response header (e.g. <https://example.com/feed>; rel="alternate") '
+            "to advertise machine-readable service-discovery endpoints to crawlers and AI agents.",
+        )
+
+    links = parse_link_header(header)
+    if not links:
+        return CheckResult(
+            _ID, _NAME, _CATEGORY, "WARN",
+            f'The homepage sends a Link header that could not be parsed as RFC 8288: "{header}".',
+            'Optional: format the Link header per RFC 8288, e.g. <https://example.com/feed>; rel="alternate".',
+        )
+
+    summary = ", ".join(f'{link.url} (rel="{link.rel}")' if link.rel else link.url for link in links)
+    plural = "y" if len(links) == 1 else "ies"
+    return CheckResult(
+        _ID, _NAME, _CATEGORY, "PASS",
+        f"The homepage sends {len(links)} Link header entr{plural}: {summary}.",
+    )
+
+
+link_header_check = Check(id=_ID, name=_NAME, category=_CATEGORY, run=_run)

seofleet/checks/geo/llms_txt.py

@@ -0,0 +1,29 @@
+"""Ported from src/checks/geo/llms-txt.ts."""
+from __future__ import annotations
+
+from ...types import Check, CheckContext, CheckResult
+
+_ID = "llms-txt"
+_NAME = "llms.txt"
+_CATEGORY = "geo"
+
+
+def _run(ctx: CheckContext) -> CheckResult:
+    llms_txt = ctx.resources.llms_txt
+
+    # llms.txt is an emerging, not-yet-universal convention -- its absence
+    # is informational only and never fails the run.
+    if not llms_txt.ok or not (llms_txt.body or "").strip():
+        return CheckResult(
+            _ID, _NAME, _CATEGORY, "WARN",
+            f"No llms.txt found at {llms_txt.url}.",
+            "Optional: add an llms.txt at your site root summarizing the site for LLM-based agents (see llmstxt.org).",
+        )
+
+    return CheckResult(
+        _ID, _NAME, _CATEGORY, "PASS",
+        f"llms.txt is present at {llms_txt.url}.",
+    )
+
+
+llms_txt_check = Check(id=_ID, name=_NAME, category=_CATEGORY, run=_run)

seofleet/checks/geo/markdown_negotiation.py

@@ -0,0 +1,40 @@
+"""Ported from src/checks/geo/markdown-negotiation.ts."""
+from __future__ import annotations
+
+from ...types import Check, CheckContext, CheckResult
+
+_ID = "markdown-negotiation"
+_NAME = "Markdown content negotiation"
+_CATEGORY = "geo"
+
+
+def _run(ctx: CheckContext) -> CheckResult:
+    url = ctx.resources.site_url
+    res = ctx.fetch_fn(url, headers={"Accept": "text/markdown"})
+    content_type = (res.content_type or "").lower()
+
+    # Markdown content negotiation (responding to "Accept: text/markdown"
+    # with an actual text/markdown body) is an emerging, forward-looking
+    # convention that almost no site supports yet -- its absence is
+    # informational only and never fails the run, same spirit as
+    # llms_txt.py.
+    if not res.ok or "text/markdown" not in content_type:
+        message = (
+            f'Requesting {url} with "Accept: text/markdown" returned Content-Type '
+            f'"{res.content_type or "unknown"}" instead of text/markdown.'
+            if res.ok
+            else f'Could not verify Markdown content negotiation at {url} (the request failed).'
+        )
+        return CheckResult(
+            _ID, _NAME, _CATEGORY, "WARN", message,
+            'Optional: serve a text/markdown representation of pages when the client sends '
+            '"Accept: text/markdown" so LLM-based agents can fetch clean Markdown directly instead of parsing HTML.',
+        )
+
+    return CheckResult(
+        _ID, _NAME, _CATEGORY, "PASS",
+        f'{url} returns Content-Type "{res.content_type}" when requested with "Accept: text/markdown".',
+    )
+
+
+markdown_negotiation_check = Check(id=_ID, name=_NAME, category=_CATEGORY, run=_run)

seofleet/checks/geo/organization_schema.py

@@ -0,0 +1,89 @@
+"""Ported from src/checks/geo/organization-schema.ts."""
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional
+
+from ...html_util import get_scripts_by_type
+from ...types import Check, CheckContext, CheckResult
+
+_ID = "organization-schema"
+_NAME = "Organization schema"
+_CATEGORY = "geo"
+
+ENTITY_TYPES = ["Organization", "Corporation", "LocalBusiness", "Person"]
+
+
+def _has_entity_type(type_value: Any) -> bool:
+    if isinstance(type_value, str):
+        return type_value in ENTITY_TYPES
+    if isinstance(type_value, list):
+        return any(isinstance(t, str) and t in ENTITY_TYPES for t in type_value)
+    return False
+
+
+def _find_entity_node(value: Any) -> Optional[Dict[str, Any]]:
+    if isinstance(value, list):
+        for item in value:
+            found = _find_entity_node(item)
+            if found is not None:
+                return found
+        return None
+    if isinstance(value, dict):
+        if _has_entity_type(value.get("@type")):
+            return value
+        if "@graph" in value:
+            return _find_entity_node(value["@graph"])
+    return None
+
+
+def _has_non_empty_same_as(node: Dict[str, Any]) -> bool:
+    same_as = node.get("sameAs")
+    if isinstance(same_as, list):
+        return len(same_as) > 0
+    return isinstance(same_as, str) and same_as.strip() != ""
+
+
+def _run(ctx: CheckContext) -> CheckResult:
+    if ctx.root is None:
+        return CheckResult(
+            _ID, _NAME, _CATEGORY, "FAIL",
+            "Homepage could not be fetched, so Organization schema could not be checked.",
+            "Confirm siteUrl in seofleet.json is correct and reachable.",
+        )
+
+    entity_node: Optional[Dict[str, Any]] = None
+    for script in get_scripts_by_type(ctx.root, "application/ld+json"):
+        if entity_node is not None:
+            break
+        try:
+            parsed = json.loads(script.text())
+            entity_node = _find_entity_node(parsed)
+        except (json.JSONDecodeError, ValueError):
+            pass  # invalid JSON-LD is reported by the structured-data check; ignore here
+
+    # Organization/Person schema only applies to entities that actually
+    # want a Knowledge Panel presence, so its absence is informational,
+    # never a failure.
+    if entity_node is None:
+        return CheckResult(
+            _ID, _NAME, _CATEGORY, "WARN",
+            f"No {'/'.join(ENTITY_TYPES)} structured data found.",
+            "Add Organization (or Person) JSON-LD with a sameAs array of your official social/profile URLs "
+            "to strengthen Knowledge Panel signals.",
+        )
+
+    if not _has_non_empty_same_as(entity_node):
+        return CheckResult(
+            _ID, _NAME, _CATEGORY, "WARN",
+            "Organization/Person schema found, but it has no sameAs property.",
+            "Add a sameAs array listing this entity's official social profiles and other authoritative URLs.",
+        )
+
+    return CheckResult(
+        _ID, _NAME, _CATEGORY, "PASS",
+        "Organization/Person schema found with a sameAs property linking authoritative profiles.",
+    )
+
+
+organization_schema_check = Check(id=_ID, name=_NAME, category=_CATEGORY, run=_run)