sardine-cms-validation 0.1.0__tar.gz

sardine_cms_validation-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+
+# Node (admin panel UI, if applicable)
+node_modules/
+*.tsbuildinfo
+
+# Environment and secrets
+.env
+.env.*
+!.env.example
+
+# Local databases
+*.sqlite3
+*.db
+
+# Static build output
+_site/
+out/
+export/
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/
+!.vscode/settings.json

sardine_cms_validation-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: sardine-cms-validation
+Version: 0.1.0
+Summary: Configurable content validation rules for Sardine CMS
+License-Expression: Apache-2.0
+Requires-Python: >=3.12
+Requires-Dist: sardine-cms-core
+Description-Content-Type: text/markdown
+
+# cms-validation
+
+Configurable validation rules for Sardine CMS: language parity,
+structure, editorial rules. Runs before every publish. See the repository
+root README and docs for the full architecture.

sardine_cms_validation-0.1.0/README.md

@@ -0,0 +1,5 @@
+# cms-validation
+
+Configurable validation rules for Sardine CMS: language parity,
+structure, editorial rules. Runs before every publish. See the repository
+root README and docs for the full architecture.

sardine_cms_validation-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "sardine-cms-validation"
+version = "0.1.0"
+description = "Configurable content validation rules for Sardine CMS"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+dependencies = ["sardine-cms-core"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cms_validation"]

sardine_cms_validation-0.1.0/src/cms_validation/__init__.py

@@ -0,0 +1,37 @@
+"""Configurable content validation rules."""
+
+from cms_validation.engine import (
+    Issue,
+    Report,
+    Rule,
+    RuleSet,
+    Severity,
+    SiteContent,
+    ValidationContext,
+)
+from cms_validation.rules import (
+    KnownCategoriesRule,
+    MediaAltCoverageRule,
+    MediaReferencesRule,
+    RequiredTranslationsRule,
+    UniqueSlugsRule,
+    default_ruleset,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Issue",
+    "KnownCategoriesRule",
+    "MediaAltCoverageRule",
+    "MediaReferencesRule",
+    "Report",
+    "RequiredTranslationsRule",
+    "Rule",
+    "RuleSet",
+    "Severity",
+    "SiteContent",
+    "UniqueSlugsRule",
+    "ValidationContext",
+    "default_ruleset",
+]

sardine_cms_validation-0.1.0/src/cms_validation/engine.py

@@ -0,0 +1,89 @@
+"""Validation engine: composable, configurable rules over site content.
+
+A rule is any object satisfying the :class:`Rule` protocol; a
+:class:`RuleSet` runs the enabled rules and aggregates issues. Publishing is
+gated on the absence of ``ERROR`` issues.
+"""
+
+from collections.abc import Iterable, Iterator, Sequence
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Protocol, runtime_checkable
+
+from cms_core import Article, Language, MediaAsset, Page
+
+
+class Severity(StrEnum):
+    ERROR = "error"
+    WARNING = "warning"
+
+
+@dataclass(frozen=True, slots=True)
+class Issue:
+    code: str
+    severity: Severity
+    message: str
+    subject: str
+    language: Language | None = None
+
+    def __str__(self) -> str:
+        scope = f" [{self.language.value}]" if self.language else ""
+        return f"{self.severity.value}: {self.code}: {self.subject}{scope}: {self.message}"
+
+
+@dataclass(frozen=True, slots=True)
+class SiteContent:
+    """The full content set a validation or build run operates on."""
+
+    articles: Sequence[Article] = ()
+    pages: Sequence[Page] = ()
+    media: Sequence[MediaAsset] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class ValidationContext:
+    """Configuration a rule may consult; never read from globals."""
+
+    required_languages: tuple[Language, ...]
+    known_categories: tuple[str, ...] | None = None
+    """None disables the check; a tuple restricts article categories to it."""
+
+
+@runtime_checkable
+class Rule(Protocol):
+    name: str
+
+    def check(self, content: SiteContent, context: ValidationContext) -> Iterable[Issue]: ...
+
+
+@dataclass(frozen=True, slots=True)
+class Report:
+    issues: tuple[Issue, ...]
+
+    @property
+    def errors(self) -> tuple[Issue, ...]:
+        return tuple(issue for issue in self.issues if issue.severity is Severity.ERROR)
+
+    @property
+    def warnings(self) -> tuple[Issue, ...]:
+        return tuple(issue for issue in self.issues if issue.severity is Severity.WARNING)
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+
+@dataclass(slots=True)
+class RuleSet:
+    rules: list[Rule] = field(default_factory=list)
+    disabled: set[str] = field(default_factory=set)
+
+    def enabled_rules(self) -> Iterator[Rule]:
+        return (rule for rule in self.rules if rule.name not in self.disabled)
+
+    def run(self, content: SiteContent, context: ValidationContext) -> Report:
+        issues: list[Issue] = []
+        for rule in self.enabled_rules():
+            issues.extend(rule.check(content, context))
+        issues.sort(key=lambda issue: (issue.subject, issue.code, issue.language or ""))
+        return Report(issues=tuple(issues))

sardine_cms_validation-0.1.0/src/cms_validation/rules.py

@@ -0,0 +1,162 @@
+"""Core validation rules.
+
+Each rule is small, pure and independently testable. Rules never read global
+state — everything comes from the content set and the context.
+"""
+
+from collections.abc import Iterable, Iterator
+
+from cms_core import Article, ContentStatus, Language, Page, TranslationState
+
+from cms_validation.engine import Issue, Rule, Severity, SiteContent, ValidationContext
+
+
+def _publishable(status: ContentStatus) -> bool:
+    return status in (ContentStatus.REVIEW, ContentStatus.PUBLISHED)
+
+
+class RequiredTranslationsRule:
+    """Published/review content must be complete in every required language."""
+
+    name = "required-translations"
+
+    def check(self, content: SiteContent, context: ValidationContext) -> Iterator[Issue]:
+        entries: Iterable[tuple[str, Article | Page]] = [
+            *((f"article:{article.id}", article) for article in content.articles),
+            *((f"page:{page.id}", page) for page in content.pages),
+        ]
+        for subject, entry in entries:
+            if not _publishable(entry.status):
+                continue
+            severity = (
+                Severity.ERROR if entry.status is ContentStatus.PUBLISHED else Severity.WARNING
+            )
+            for language in context.required_languages:
+                state = entry.translation_state(language)
+                if state is not TranslationState.COMPLETE:
+                    yield Issue(
+                        code=self.name,
+                        severity=severity,
+                        message=f"translation is {state.value}",
+                        subject=subject,
+                        language=language,
+                    )
+
+
+class UniqueSlugsRule:
+    """Within each language, generated URLs must not collide."""
+
+    name = "unique-slugs"
+
+    def check(self, content: SiteContent, context: ValidationContext) -> Iterator[Issue]:
+        for language in (Language.EN, *context.required_languages):
+            seen: dict[str, str] = {}
+            for article in content.articles:
+                slug = _article_slug(article, language)
+                subject = f"article:{article.id}"
+                if slug in seen:
+                    yield self._collision(subject, seen[slug], slug, language)
+                else:
+                    seen[slug] = subject
+            for page in content.pages:
+                slug = _page_slug(page, language)
+                subject = f"page:{page.id}"
+                if slug in seen:
+                    yield self._collision(subject, seen[slug], slug, language)
+                else:
+                    seen[slug] = subject
+
+    def _collision(self, subject: str, other: str, slug: str, language: Language) -> Issue:
+        return Issue(
+            code=self.name,
+            severity=Severity.ERROR,
+            message=f"slug {slug!r} collides with {other}",
+            subject=subject,
+            language=language,
+        )
+
+
+class MediaReferencesRule:
+    """Sections may only reference media assets that exist."""
+
+    name = "media-references"
+
+    def check(self, content: SiteContent, context: ValidationContext) -> Iterator[Issue]:
+        known = {asset.id for asset in content.media}
+        for page in content.pages:
+            for section in page.sections:
+                for media_id in section.source.media:
+                    if media_id not in known:
+                        yield Issue(
+                            code=self.name,
+                            severity=Severity.ERROR,
+                            message=f"unknown media asset {media_id!r}",
+                            subject=f"page:{page.id}/section:{section.key}",
+                        )
+
+
+class MediaAltCoverageRule:
+    """Media used by publishable content must have alt text in required languages."""
+
+    name = "media-alt-coverage"
+
+    def check(self, content: SiteContent, context: ValidationContext) -> Iterator[Issue]:
+        for asset in content.media:
+            missing = [
+                language
+                for language in context.required_languages
+                if not asset.alt.get(language, "").strip()
+            ]
+            for language in missing:
+                yield Issue(
+                    code=self.name,
+                    severity=Severity.WARNING,
+                    message="missing alt text",
+                    subject=f"media:{asset.id}",
+                    language=language,
+                )
+
+
+def _article_slug(article: Article, language: Language) -> str:
+    if language is Language.EN:
+        return article.source.slug or article.id
+    translation = article.translations.get(language)
+    if translation is None or translation.content.slug is None:
+        return article.source.slug or article.id
+    return translation.content.slug
+
+
+def _page_slug(page: Page, language: Language) -> str:
+    if language is Language.EN:
+        return page.source.slug
+    translation = page.translations.get(language)
+    return translation.content.slug if translation else page.source.slug
+
+
+class KnownCategoriesRule:
+    """When the project declares categories, articles may only use those."""
+
+    name = "known-categories"
+
+    def check(self, content: SiteContent, context: ValidationContext) -> Iterator[Issue]:
+        if context.known_categories is None:
+            return
+        known = set(context.known_categories)
+        for article in content.articles:
+            if article.category is not None and article.category not in known:
+                yield Issue(
+                    code=self.name,
+                    severity=Severity.ERROR,
+                    message=f"unknown category {article.category!r}",
+                    subject=f"article:{article.id}",
+                )
+
+
+def default_ruleset() -> list[Rule]:
+    return [
+        RequiredTranslationsRule(),
+        UniqueSlugsRule(),
+        MediaReferencesRule(),
+        MediaAltCoverageRule(),
+        KnownCategoriesRule(),
+    ]