goatseo-core 0.1.0__tar.gz

goatseo_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Louis Midson LAJEANTY <midsonlajeanty@proton.me>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

goatseo_core-0.1.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: goatseo-core
+Version: 0.1.0
+Summary: Framework-independent SEO metadata, validation and HTML rendering for GoatSEO.
+Keywords: seo,schema.org,json-ld,opengraph,twitter-cards,metadata
+Author: Louis Midson LAJEANTY
+Author-email: Louis Midson LAJEANTY <midsonlajeanty@proton.me>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.12
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/goatlabshq/goatseo
+Project-URL: Documentation, https://goatlabshq.github.io/goatseo/
+Project-URL: Issues, https://github.com/goatlabshq/goatseo/issues
+Description-Content-Type: text/markdown
+
+# goatseo-core
+
+Framework-independent primitives of GoatSEO: typed page metadata, deterministic precedence between metadata layers, URL safety, escaped HTML rendering of head elements and an SEO audit.
+
+```bash
+pip install goatseo-core
+```
+
+```python
+from goatseo.core import Metadata, metadata_elements, render_elements
+
+html = render_elements(metadata_elements(Metadata(title="Hello")))
+```
+
+Part of [GoatSEO](https://github.com/goatlabshq/goatseo). See the [documentation](https://goatlabshq.github.io/goatseo/).

goatseo_core-0.1.0/README.md

@@ -0,0 +1,15 @@
+# goatseo-core
+
+Framework-independent primitives of GoatSEO: typed page metadata, deterministic precedence between metadata layers, URL safety, escaped HTML rendering of head elements and an SEO audit.
+
+```bash
+pip install goatseo-core
+```
+
+```python
+from goatseo.core import Metadata, metadata_elements, render_elements
+
+html = render_elements(metadata_elements(Metadata(title="Hello")))
+```
+
+Part of [GoatSEO](https://github.com/goatlabshq/goatseo). See the [documentation](https://goatlabshq.github.io/goatseo/).

goatseo_core-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "goatseo-core"
+version = "0.1.0"
+description = "Framework-independent SEO metadata, validation and HTML rendering for GoatSEO."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+keywords = [
+    "seo",
+    "schema.org",
+    "json-ld",
+    "opengraph",
+    "twitter-cards",
+    "metadata",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Typing :: Typed",
+]
+dependencies = ["pydantic>=2.12"]
+
+[[project.authors]]
+name = "Louis Midson LAJEANTY"
+email = "midsonlajeanty@proton.me"
+
+[project.urls]
+Homepage = "https://github.com/goatlabshq/goatseo"
+Documentation = "https://goatlabshq.github.io/goatseo/"
+Issues = "https://github.com/goatlabshq/goatseo/issues"
+
+[build-system]
+requires = ["uv_build>=0.12,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "goatseo.core"

goatseo_core-0.1.0/pyproject.toml.orig

@@ -0,0 +1,34 @@
+[project]
+name = "goatseo-core"
+version = "0.1.0" # x-release-please-version
+description = "Framework-independent SEO metadata, validation and HTML rendering for GoatSEO."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Louis Midson LAJEANTY", email = "midsonlajeanty@proton.me" }]
+requires-python = ">=3.14"
+keywords = ["seo", "schema.org", "json-ld", "opengraph", "twitter-cards", "metadata"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/goatlabshq/goatseo"
+Documentation = "https://goatlabshq.github.io/goatseo/"
+Issues = "https://github.com/goatlabshq/goatseo/issues"
+
+[build-system]
+requires = ["uv_build>=0.12,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "goatseo.core"

goatseo_core-0.1.0/src/goatseo/core/__init__.py

@@ -0,0 +1,52 @@
+"""Framework-independent SEO primitives."""
+
+from goatseo.core.context import RequestContext, StaticRequestContext
+from goatseo.core.html import HeadElement, JsonLd, Link, Meta, SafeHtml, Title, render_elements
+from goatseo.core.metadata import (
+    AlternateLink,
+    HrefLang,
+    Metadata,
+    MetadataFields,
+    Robots,
+    RobotsDirectives,
+    merge_metadata,
+)
+from goatseo.core.precedence import MetadataStack, Precedence, SupportsMetadata
+from goatseo.core.renderer import ElementRenderer, metadata_elements
+from goatseo.core.serialization import JsonObject, JsonValue, dumps_for_script
+from goatseo.core.urls import AbsoluteUrl, UnsafeUrlError, Url, resolve_url
+from goatseo.core.validation import Issue, Severity, audit
+
+__all__ = [
+    "AbsoluteUrl",
+    "AlternateLink",
+    "ElementRenderer",
+    "HeadElement",
+    "HrefLang",
+    "Issue",
+    "JsonLd",
+    "JsonObject",
+    "JsonValue",
+    "Link",
+    "Meta",
+    "Metadata",
+    "MetadataFields",
+    "MetadataStack",
+    "Precedence",
+    "RequestContext",
+    "Robots",
+    "RobotsDirectives",
+    "SafeHtml",
+    "Severity",
+    "StaticRequestContext",
+    "SupportsMetadata",
+    "Title",
+    "UnsafeUrlError",
+    "Url",
+    "audit",
+    "dumps_for_script",
+    "merge_metadata",
+    "metadata_elements",
+    "render_elements",
+    "resolve_url",
+]

goatseo_core-0.1.0/src/goatseo/core/context.py

@@ -0,0 +1,14 @@
+"""The only thing GoatSEO needs from a web framework: the URL of the current request."""
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+class RequestContext(Protocol):
+    @property
+    def url(self) -> str: ...
+
+
+@dataclass(frozen=True, slots=True)
+class StaticRequestContext:
+    url: str

goatseo_core-0.1.0/src/goatseo/core/html.py

@@ -0,0 +1,85 @@
+"""Head elements and their escaped HTML serialization."""
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from html import escape
+from typing import Literal, Self, final
+
+from goatseo.core.serialization import JsonValue, dumps_for_script
+
+
+@final
+class SafeHtml(str):
+    """Trusted HTML: ``__html__`` tells Django, Jinja and MarkupSafe not to escape it again."""
+
+    __slots__ = ()
+
+    # nosemgrep: python.django.security.audit.xss.html-magic-method.html-magic-method
+    def __html__(self) -> Self:
+        return self
+
+
+type MetaAttribute = Literal["name", "property", "http-equiv", "itemprop"]
+
+
+@dataclass(frozen=True, slots=True)
+class Title:
+    text: str
+
+
+@dataclass(frozen=True, slots=True)
+class Meta:
+    attribute: MetaAttribute
+    key: str
+    content: str
+
+
+@dataclass(frozen=True, slots=True)
+class Link:
+    rel: str
+    href: str
+    hreflang: str | None = None
+    type: str | None = None
+    title: str | None = None
+    media: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class JsonLd:
+    data: JsonValue
+
+
+type HeadElement = Title | Meta | Link | JsonLd
+
+
+def _attributes(pairs: Iterable[tuple[str, str | None]]) -> str:
+    return "".join(
+        f' {name}="{escape(value, quote=True)}"' for name, value in pairs if value is not None
+    )
+
+
+def render_element(element: HeadElement, *, json_indent: int | None = None) -> str:
+    match element:
+        case Title(text):
+            return f"<title>{escape(text, quote=True)}</title>"
+        case Meta(attribute, key, content):
+            return f"<meta{_attributes([(attribute, key), ('content', content)])}>"
+        case Link(rel, href, hreflang, type_, title, media):
+            pairs = [
+                ("rel", rel),
+                ("hreflang", hreflang),
+                ("type", type_),
+                ("title", title),
+                ("media", media),
+                ("href", href),
+            ]
+            return f"<link{_attributes(pairs)}>"
+        case JsonLd(data):
+            payload = dumps_for_script(data, indent=json_indent)
+            return f'<script type="application/ld+json">{payload}</script>'
+
+
+def render_elements(
+    elements: Iterable[HeadElement], *, separator: str = "\n", json_indent: int | None = None
+) -> SafeHtml:
+    return SafeHtml(separator.join(render_element(e, json_indent=json_indent) for e in elements))

goatseo_core-0.1.0/src/goatseo/core/metadata.py

@@ -0,0 +1,184 @@
+"""Strongly typed page metadata and its deterministic merge rules."""
+
+import datetime as _dt
+import re
+from collections.abc import Sequence
+from typing import Annotated, Final, Literal, Self, TypedDict
+
+from pydantic import AfterValidator, BaseModel, ConfigDict, Field
+
+from goatseo.core.urls import Url
+
+TITLE_PLACEHOLDER: Final = "{title}"
+X_DEFAULT: Final = "x-default"
+
+_LANGUAGE_TAG: Final = re.compile(r"^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*$")
+_LOCALE: Final = re.compile(r"^[a-z]{2,3}(?:_[A-Z]{2})?$")
+
+
+def validate_language_tag(value: str) -> str:
+    if not _LANGUAGE_TAG.match(value):
+        raise ValueError(f"{value!r} is not a BCP 47 language tag such as 'en' or 'fr-CA'")
+    return value
+
+
+def validate_hreflang(value: str) -> str:
+    return value if value == X_DEFAULT else validate_language_tag(value)
+
+
+def validate_locale(value: str) -> str:
+    if not _LOCALE.match(value):
+        raise ValueError(f"{value!r} is not a locale such as 'en_US'")
+    return value
+
+
+def validate_title_template(value: str) -> str:
+    if TITLE_PLACEHOLDER not in value:
+        raise ValueError(f"title template {value!r} must contain {TITLE_PLACEHOLDER}")
+    return value
+
+
+type LanguageTag = Annotated[str, AfterValidator(validate_language_tag)]
+type Locale = Annotated[str, AfterValidator(validate_locale)]
+type NonEmptyText = Annotated[str, Field(min_length=1)]
+type ImagePreview = Literal["none", "standard", "large"]
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid", str_strip_whitespace=True)
+
+
+class RobotsDirectives(TypedDict, total=False):
+    index: bool | None
+    follow: bool | None
+    archive: bool | None
+    snippet: bool | None
+    image_index: bool | None
+    translate: bool | None
+    max_snippet: int | None
+    max_image_preview: ImagePreview | None
+    max_video_preview: int | None
+    unavailable_after: _dt.datetime | None
+
+
+class Robots(_Model):
+    """Robots directives; ``None`` means "not specified" and lets a lower layer decide."""
+
+    index: bool | None = None
+    follow: bool | None = None
+    archive: bool | None = None
+    snippet: bool | None = None
+    image_index: bool | None = None
+    translate: bool | None = None
+    max_snippet: Annotated[int, Field(ge=-1)] | None = None
+    max_image_preview: ImagePreview | None = None
+    max_video_preview: Annotated[int, Field(ge=-1)] | None = None
+    unavailable_after: _dt.datetime | None = None
+
+    def merged(self, override: Robots) -> Robots:
+        return self.model_copy(update=override.model_dump(exclude_none=True))
+
+    def directives(self) -> tuple[str, ...]:
+        flags = (
+            (self.index, "index", "noindex"),
+            (self.follow, "follow", "nofollow"),
+            (self.archive, None, "noarchive"),
+            (self.snippet, None, "nosnippet"),
+            (self.image_index, None, "noimageindex"),
+            (self.translate, None, "notranslate"),
+        )
+        directives = [
+            positive if value else negative
+            for value, positive, negative in flags
+            if value is not None and (positive if value else negative)
+        ]
+        if self.max_snippet is not None:
+            directives.append(f"max-snippet:{self.max_snippet}")
+        if self.max_image_preview is not None:
+            directives.append(f"max-image-preview:{self.max_image_preview}")
+        if self.max_video_preview is not None:
+            directives.append(f"max-video-preview:{self.max_video_preview}")
+        if self.unavailable_after is not None:
+            directives.append(f"unavailable_after:{self.unavailable_after.isoformat()}")
+        return tuple(d for d in directives if d)
+
+    @property
+    def indexable(self) -> bool:
+        return self.index is not False
+
+
+class HrefLang(_Model):
+    hreflang: Annotated[str, AfterValidator(validate_hreflang)]
+    href: Url
+
+
+class AlternateLink(_Model):
+    """A ``<link rel="alternate">`` such as an RSS feed or a print version."""
+
+    href: Url
+    type: NonEmptyText | None = None
+    title: NonEmptyText | None = None
+    media: NonEmptyText | None = None
+
+
+class Metadata(_Model):
+    """Page metadata. Every field defaults to ``None``, meaning "inherit from a lower layer"."""
+
+    title: NonEmptyText | None = None
+    title_template: Annotated[str, AfterValidator(validate_title_template)] | None = None
+    description: NonEmptyText | None = None
+    canonical: Url | None = None
+    robots: Robots | None = None
+    language: LanguageTag | None = None
+    locale: Locale | None = None
+    site_name: NonEmptyText | None = None
+    author: NonEmptyText | None = None
+    publisher: NonEmptyText | None = None
+    keywords: Sequence[NonEmptyText] | None = None
+    theme_color: Annotated[str, Field(pattern=r"^[#(),.%\w\s-]{1,64}$")] | None = None
+    alternates: Sequence[AlternateLink] | None = None
+    hreflang: Sequence[HrefLang] | None = None
+
+    def merged(self, override: Metadata) -> Self:
+        """Returns a copy where every field set on ``override`` wins; robots merge per directive."""
+        update = {
+            name: getattr(override, name)
+            for name in type(override).model_fields
+            if getattr(override, name) is not None
+        }
+        if self.robots is not None and override.robots is not None:
+            update["robots"] = self.robots.merged(override.robots)
+        return self.model_copy(update=update)
+
+    @property
+    def full_title(self) -> str | None:
+        if self.title is None or self.title_template is None:
+            return self.title
+        return self.title_template.replace(TITLE_PLACEHOLDER, self.title)
+
+
+class MetadataFields(TypedDict, total=False):
+    """Keyword arguments accepted wherever a :class:`Metadata` can be built inline."""
+
+    title: str | None
+    title_template: str | None
+    description: str | None
+    canonical: str | None
+    robots: Robots | None
+    language: str | None
+    locale: str | None
+    site_name: str | None
+    author: str | None
+    publisher: str | None
+    keywords: Sequence[str] | None
+    theme_color: str | None
+    alternates: Sequence[AlternateLink] | None
+    hreflang: Sequence[HrefLang] | None
+
+
+def merge_metadata(*layers: Metadata) -> Metadata:
+    """Merges layers from least to most specific: the last layer that sets a field wins."""
+    result = Metadata()
+    for layer in layers:
+        result = result.merged(layer)
+    return result

goatseo_core-0.1.0/src/goatseo/core/precedence.py

@@ -0,0 +1,54 @@
+"""Metadata layers resolved from the least to the most specific."""
+
+from collections.abc import Mapping
+from enum import IntEnum
+from typing import Protocol, Self, runtime_checkable
+
+from goatseo.core.metadata import Metadata, merge_metadata
+
+
+class Precedence(IntEnum):
+    GLOBAL = 0
+    SITE = 10
+    APPLICATION = 20
+    MODEL = 30
+    VIEW = 40
+    REQUEST = 50
+
+
+@runtime_checkable
+class SupportsMetadata(Protocol):
+    """Implemented by domain objects (a Django model, a dataclass...) that describe their page."""
+
+    def seo_metadata(self) -> Metadata: ...
+
+
+class MetadataStack:
+    """Holds one metadata layer per precedence level; higher levels override lower ones."""
+
+    __slots__ = ("_layers", "_resolved")
+
+    def __init__(self, layers: Mapping[Precedence, Metadata] | None = None) -> None:
+        self._layers: dict[Precedence, Metadata] = dict(layers or {})
+        self._resolved: Metadata | None = None
+
+    def set(self, precedence: Precedence, metadata: Metadata) -> Self:
+        self._layers[precedence] = metadata
+        self._resolved = None
+        return self
+
+    def update(self, precedence: Precedence, metadata: Metadata) -> Self:
+        """Merges ``metadata`` into the layer at ``precedence`` instead of replacing it."""
+        current = self._layers.get(precedence)
+        return self.set(precedence, metadata if current is None else current.merged(metadata))
+
+    def layer(self, precedence: Precedence) -> Metadata | None:
+        return self._layers.get(precedence)
+
+    def resolve(self) -> Metadata:
+        if self._resolved is None:
+            self._resolved = merge_metadata(*(self._layers[p] for p in sorted(self._layers)))
+        return self._resolved
+
+    def copy(self) -> MetadataStack:
+        return MetadataStack(self._layers)

goatseo_core-0.1.0/src/goatseo/core/renderer.py

@@ -0,0 +1,42 @@
+"""Turns metadata into head elements; framework adapters only choose where to print them."""
+
+from collections.abc import Iterable, Iterator
+from typing import Protocol
+
+from goatseo.core.html import HeadElement, Link, Meta, Title
+from goatseo.core.metadata import Metadata
+from goatseo.core.urls import resolve_url
+
+
+class ElementRenderer[T](Protocol):
+    def __call__(self, value: T, /) -> Iterable[HeadElement]: ...
+
+
+def metadata_elements(metadata: Metadata, *, base_url: str | None = None) -> Iterator[HeadElement]:
+    title = metadata.full_title
+    if title is not None:
+        yield Title(title)
+    if metadata.description is not None:
+        yield Meta("name", "description", metadata.description)
+    if metadata.robots is not None and (directives := metadata.robots.directives()):
+        yield Meta("name", "robots", ", ".join(directives))
+    if metadata.author is not None:
+        yield Meta("name", "author", metadata.author)
+    if metadata.publisher is not None:
+        yield Meta("name", "publisher", metadata.publisher)
+    if metadata.keywords:
+        yield Meta("name", "keywords", ", ".join(metadata.keywords))
+    if metadata.theme_color is not None:
+        yield Meta("name", "theme-color", metadata.theme_color)
+    if metadata.canonical is not None:
+        yield Link("canonical", resolve_url(metadata.canonical, base_url))
+    for alternate in metadata.hreflang or ():
+        yield Link("alternate", resolve_url(alternate.href, base_url), hreflang=alternate.hreflang)
+    for link in metadata.alternates or ():
+        yield Link(
+            "alternate",
+            resolve_url(link.href, base_url),
+            type=link.type,
+            title=link.title,
+            media=link.media,
+        )

goatseo_core-0.1.0/src/goatseo/core/serialization.py

@@ -0,0 +1,21 @@
+"""JSON values and serialization that is safe to embed inside an HTML ``<script>`` element."""
+
+import json
+from typing import Final
+
+type JsonValue = str | int | float | bool | list[JsonValue] | dict[str, JsonValue] | None
+type JsonObject = dict[str, JsonValue]
+
+# Escaping these keeps "</script>", "<!--" and line separators from ending or corrupting
+# the script element, while the JSON document itself stays byte-for-byte equivalent.
+_SCRIPT_ESCAPES: Final = str.maketrans(
+    {"<": "\\u003c", ">": "\\u003e", "&": "\\u0026", "\u2028": "\\u2028", "\u2029": "\\u2029"}
+)
+
+
+def dumps_for_script(value: JsonValue, *, indent: int | None = None) -> str:
+    separators = (",", ": ") if indent is not None else (",", ":")
+    text = json.dumps(
+        value, ensure_ascii=False, allow_nan=False, indent=indent, separators=separators
+    )
+    return text.translate(_SCRIPT_ESCAPES)

goatseo_core-0.1.0/src/goatseo/core/urls.py

@@ -0,0 +1,51 @@
+"""URL validation and resolution shared by every GoatSEO package."""
+
+import unicodedata
+from typing import Annotated, Final
+from urllib.parse import urljoin, urlsplit
+
+from pydantic import AfterValidator
+
+ALLOWED_SCHEMES: Final = frozenset({"http", "https"})
+
+
+class UnsafeUrlError(ValueError):
+    pass
+
+
+def _reject_invisible_characters(value: str) -> None:
+    if any(char.isspace() or unicodedata.category(char).startswith("C") for char in value):
+        raise UnsafeUrlError(f"URL {value!r} contains whitespace or control characters")
+
+
+def is_absolute(url: str) -> bool:
+    parts = urlsplit(url)
+    return bool(parts.scheme and parts.netloc)
+
+
+def validate_absolute_url(value: str) -> str:
+    value = value.strip()
+    _reject_invisible_characters(value)
+    parts = urlsplit(value)
+    if parts.scheme.lower() not in ALLOWED_SCHEMES or not parts.netloc:
+        raise UnsafeUrlError(f"URL {value!r} must be an absolute http(s) URL")
+    return value
+
+
+def validate_url(value: str) -> str:
+    """Accepts absolute http(s) URLs and root-relative paths such as ``/articles/1``."""
+    value = value.strip()
+    _reject_invisible_characters(value)
+    if value.startswith("/") and not value.startswith("//"):
+        return value
+    return validate_absolute_url(value)
+
+
+def resolve_url(url: str, base_url: str | None) -> str:
+    if base_url is None or is_absolute(url):
+        return url
+    return validate_absolute_url(urljoin(base_url, url))
+
+
+type AbsoluteUrl = Annotated[str, AfterValidator(validate_absolute_url)]
+type Url = Annotated[str, AfterValidator(validate_url)]

goatseo_core-0.1.0/src/goatseo/core/validation.py

@@ -0,0 +1,97 @@
+"""SEO audit: checks that are valid HTML-wise but hurt search visibility."""
+
+from collections import Counter
+from collections.abc import Iterator
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Final
+
+from goatseo.core.metadata import X_DEFAULT, Metadata
+from goatseo.core.urls import is_absolute
+
+TITLE_MAX_LENGTH: Final = 60
+DESCRIPTION_MIN_LENGTH: Final = 50
+DESCRIPTION_MAX_LENGTH: Final = 160
+
+
+class Severity(StrEnum):
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+
+@dataclass(frozen=True, slots=True)
+class Issue:
+    code: str
+    severity: Severity
+    field: str
+    message: str
+
+
+def _title_issues(metadata: Metadata) -> Iterator[Issue]:
+    title = metadata.full_title
+    if title is None:
+        yield Issue("missing-title", Severity.ERROR, "title", "The page has no title.")
+    elif len(title) > TITLE_MAX_LENGTH:
+        yield Issue(
+            "title-too-long",
+            Severity.WARNING,
+            "title",
+            f"The title has {len(title)} characters; search engines show about {TITLE_MAX_LENGTH}.",
+        )
+
+
+def _description_issues(metadata: Metadata) -> Iterator[Issue]:
+    description = metadata.description
+    if description is None:
+        yield Issue(
+            "missing-description", Severity.WARNING, "description", "The page has no description."
+        )
+    elif not DESCRIPTION_MIN_LENGTH <= len(description) <= DESCRIPTION_MAX_LENGTH:
+        yield Issue(
+            "description-length",
+            Severity.INFO,
+            "description",
+            f"The description has {len(description)} characters; aim for "
+            f"{DESCRIPTION_MIN_LENGTH} to {DESCRIPTION_MAX_LENGTH}.",
+        )
+
+
+def _canonical_issues(metadata: Metadata) -> Iterator[Issue]:
+    if metadata.canonical is None:
+        yield Issue("missing-canonical", Severity.INFO, "canonical", "No canonical URL is set.")
+    elif not is_absolute(metadata.canonical):
+        yield Issue(
+            "relative-canonical",
+            Severity.INFO,
+            "canonical",
+            "The canonical URL is relative; it is resolved against the request URL.",
+        )
+
+
+def _hreflang_issues(metadata: Metadata) -> Iterator[Issue]:
+    languages = Counter(link.hreflang.lower() for link in metadata.hreflang or ())
+    for language, count in sorted(languages.items()):
+        if count > 1:
+            yield Issue(
+                "duplicate-hreflang",
+                Severity.ERROR,
+                "hreflang",
+                f"hreflang {language!r} is declared {count} times.",
+            )
+    if languages and X_DEFAULT not in languages:
+        yield Issue(
+            "missing-x-default",
+            Severity.INFO,
+            "hreflang",
+            "hreflang alternates have no x-default entry.",
+        )
+
+
+def audit(metadata: Metadata) -> tuple[Issue, ...]:
+    return (
+        *_title_issues(metadata),
+        *_description_issues(metadata),
+        *_canonical_issues(metadata),
+        *_hreflang_issues(metadata),
+    )