bookwright-cli 0.2.0__py3-none-any.whl

bookwright/validation/registry.py

@@ -0,0 +1,185 @@
+"""Validator discovery and configuration resolution (contracts/validator-protocol.md).
+
+Built-ins are auto-discovered by iterating the ``bookwright.validation.validators``
+package (``pkgutil``); customs are loaded from sorted ``*.py`` under
+``<root>/.bookwright/validators/`` (``importlib``). No hand-registration, no
+``entry_points`` (research D2). Discovery is deterministic: modules sorted by name,
+objects within a module sorted by validator name (D8).
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import pkgutil
+from pathlib import Path
+from types import ModuleType
+from typing import TYPE_CHECKING
+
+from bookwright.validation import validators as _validators_pkg
+from bookwright.validation.base import UnknownValidatorError, Validator, ValidatorError
+
+if TYPE_CHECKING:
+    from bookwright.core.manifest import ValidatorsBlock
+
+__all__ = ["discover_validators", "resolve_active"]
+
+
+def _looks_like_validator_class(value: object) -> bool:
+    """Whether ``value`` is a concrete class shaped like a validator (not a Protocol)."""
+    if not isinstance(value, type) or getattr(value, "_is_protocol", False):
+        return False
+    return all(hasattr(value, attr) for attr in ("name", "severity_default", "validate"))
+
+
+def _as_validator(value: object) -> Validator | None:
+    """Normalize a module-level object to a validator instance, or ``None``.
+
+    A conforming class is instantiated once (data-model); an already-built
+    conforming instance is used as-is. A class that raises on construction is
+    treated as not-a-validator (its file then yields the "no conforming" error).
+    """
+    if _looks_like_validator_class(value):
+        try:
+            instance = value()  # type: ignore[operator]
+        except Exception:  # a broken ctor is "no conforming validator", not a crash
+            return None
+        return instance if isinstance(instance, Validator) else None
+    if isinstance(value, Validator) and not isinstance(value, type):
+        return value
+    return None
+
+
+def _collect_from_module(module: ModuleType) -> list[Validator]:
+    """Every conforming validator declared at module level, sorted by ``name``."""
+    found: list[Validator] = []
+    for attr, value in vars(module).items():
+        if attr.startswith("_"):
+            continue
+        instance = _as_validator(value)
+        if instance is not None:
+            found.append(instance)
+    return sorted(found, key=lambda v: v.name)
+
+
+def _discover_builtins() -> tuple[dict[str, Validator], list[ValidatorError]]:
+    builtins: dict[str, Validator] = {}
+    errors: list[ValidatorError] = []
+    modules = sorted(pkgutil.iter_modules(_validators_pkg.__path__), key=lambda m: m.name)
+    for info in modules:
+        module = importlib.import_module(f"{_validators_pkg.__name__}.{info.name}")
+        for validator in _collect_from_module(module):
+            if validator.name in builtins:
+                errors.append(
+                    ValidatorError(
+                        validator.name,
+                        f"duplicate built-in validator name '{validator.name}'",
+                        "load",
+                    )
+                )
+                continue
+            builtins[validator.name] = validator
+    return builtins, errors
+
+
+def _load_custom_module(path: Path, mod_name: str) -> ModuleType:
+    spec = importlib.util.spec_from_file_location(mod_name, path)
+    if spec is None or spec.loader is None:  # pragma: no cover — defensive
+        raise ImportError(f"cannot load module spec for {path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def _discover_customs(
+    custom_dir: Path, builtins: dict[str, Validator]
+) -> tuple[dict[str, Validator], list[ValidatorError]]:
+    customs: dict[str, Validator] = {}
+    errors: list[ValidatorError] = []
+    if not custom_dir.is_dir():
+        return customs, errors
+    root = custom_dir.parent.parent  # <root>/.bookwright/validators
+    for index, path in enumerate(sorted(custom_dir.glob("*.py"))):
+        try:
+            relpath = path.relative_to(root).as_posix()
+        except ValueError:  # pragma: no cover — custom_dir always under root
+            relpath = path.as_posix()
+        try:
+            module = _load_custom_module(path, f"_bookwright_custom_{index}_{path.stem}")
+        except Exception as exc:  # any import failure is a skip (FR-005), never a crash
+            errors.append(ValidatorError(relpath, f"{type(exc).__name__}: {exc}", "load"))
+            continue
+        found = _collect_from_module(module)
+        if not found:
+            errors.append(ValidatorError(relpath, "no conforming validator found", "load"))
+            continue
+        for validator in found:
+            name = validator.name
+            if name in builtins:
+                errors.append(
+                    ValidatorError(
+                        relpath,
+                        f"custom validator name '{name}' collides with a built-in; rename it",
+                        "load",
+                    )
+                )
+                continue
+            if name in customs:
+                errors.append(
+                    ValidatorError(relpath, f"duplicate custom validator name '{name}'", "load")
+                )
+                continue
+            customs[name] = validator
+    return customs, errors
+
+
+def discover_validators(
+    custom_dir: Path,
+) -> tuple[dict[str, Validator], dict[str, Validator], list[ValidatorError]]:
+    """Discover built-in and custom validators (FR-004/005).
+
+    Returns ``(builtins, customs, load_errors)``. The built-in and custom dicts are
+    **disjoint by name**: a custom colliding with a built-in is dropped with an
+    attributed ``ValidatorError(phase="load")`` so a built-in coherence check is
+    never silently shadowed by project code (FR-019, D2). A malformed custom file --
+    import failure, no conforming object, or a duplicate name -- is skipped the same
+    way; the run continues.
+    """
+    builtins, builtin_errors = _discover_builtins()
+    customs, custom_errors = _discover_customs(custom_dir, builtins)
+    return builtins, customs, builtin_errors + custom_errors
+
+
+def resolve_active(
+    builtins: dict[str, Validator],
+    customs: dict[str, Validator],
+    cfg: ValidatorsBlock,
+) -> list[Validator]:
+    """Apply the ``[validators]`` config to the discovered set (research D7).
+
+    1. A non-empty ``custom`` allow-lists the discovered customs to those names.
+    2. ``candidates = builtins + customs`` minus ``disabled``.
+    3. A non-empty ``enabled`` intersects ``candidates`` with those names.
+    4. Any ``enabled`` / ``disabled`` / ``custom`` name absent from the discovered
+       ``builtins + customs`` -> :class:`UnknownValidatorError` (FR-007).
+
+    Returns the active validators sorted by ``name`` (FR-019, D8).
+    """
+    discovered = {**builtins, **customs}
+
+    unknown = tuple(
+        sorted(
+            name for name in (*cfg.enabled, *cfg.disabled, *cfg.custom) if name not in discovered
+        )
+    )
+    if unknown:
+        raise UnknownValidatorError(unknown)
+
+    selected_customs = {name: customs[name] for name in cfg.custom} if cfg.custom else dict(customs)
+    candidates = {**builtins, **selected_customs}
+    disabled = set(cfg.disabled)
+    active = {name: v for name, v in candidates.items() if name not in disabled}
+    if cfg.enabled:
+        enabled = set(cfg.enabled)
+        active = {name: v for name, v in active.items() if name in enabled}
+    return [active[name] for name in sorted(active)]

bookwright/validation/report.py

@@ -0,0 +1,106 @@
+"""``ValidationReport`` — aggregation, the CI gate, filtering, and rendering.
+
+The gate (:attr:`failed`) is computed from **all** violations before any filter, so a
+display ``--scope`` / ``--severity`` can never hide an error from CI (FR-013). The
+emitted order is fixed by the runner's total-order sort; ``reported`` only removes
+entries, never reorders — so the human report and the JSON ``violations[]`` are
+byte-identical across runs (SC-003).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from bookwright.validation.base import Severity, ValidatorError, Violation, split_source
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+__all__ = ["ScopeFilter", "ValidationReport"]
+
+
+@dataclass(frozen=True)
+class ScopeFilter:
+    """Limits reported findings to a file or directory under the project root."""
+
+    rel: str  # project-relative posix path of the scope
+    is_dir: bool
+
+    def matches(self, source: str | None) -> bool:
+        """Whether ``source`` falls within the scope. ``None`` never matches (FR-009)."""
+        if source is None:
+            return False
+        path = split_source(source)[0] or source
+        if self.is_dir:
+            return path == self.rel or path.startswith(f"{self.rel}/")
+        return path == self.rel
+
+
+@dataclass
+class ValidationReport:
+    """A full run: all (deduped, pre-filter) violations, run/load errors, run names."""
+
+    violations: tuple[Violation, ...]
+    errors: tuple[ValidatorError, ...]
+    ran: tuple[str, ...]
+
+    @property
+    def failed(self) -> bool:
+        """The gate: any violation at ``error`` severity, ignoring filters (FR-013)."""
+        return any(v.severity == Severity.error for v in self.violations)
+
+    def reported(self, *, scope: ScopeFilter | None, severity: Severity | None) -> list[Violation]:
+        """Apply ``scope`` then the ``severity`` threshold, preserving order (D8)."""
+        result: list[Violation] = []
+        for violation in self.violations:
+            if scope is not None and not scope.matches(violation.source):
+                continue
+            if severity is not None and not violation.severity.at_least(severity):
+                continue
+            result.append(violation)
+        return result
+
+    def to_json(self, *, scope: ScopeFilter | None, severity: Severity | None) -> dict[str, Any]:
+        """The Principle-IX envelope (data-model / contracts/cli-validate.md)."""
+        reported = self.reported(scope=scope, severity=severity)
+        return {
+            "status": "violations" if reported else "ok",
+            "failed": self.failed,
+            "violations": [v.to_json() for v in reported],
+            "errors": [e.to_json() for e in self.errors],
+            "summary": {
+                "ran": list(self.ran),
+                "total": len(self.violations),
+                "reported": len(reported),
+                "by_severity": self._by_severity(),
+            },
+        }
+
+    def _by_severity(self) -> dict[str, int]:
+        """Counts over the unfiltered set; always all three keys, ``0`` when absent."""
+        counts = {level.value: 0 for level in Severity}
+        for violation in self.violations:
+            counts[violation.severity.value] += 1
+        return counts
+
+    def render(
+        self, console: Console, *, scope: ScopeFilter | None, severity: Severity | None
+    ) -> None:
+        """Render the human report (grouped by validator) to ``console`` (FR-012)."""
+        reported = self.reported(scope=scope, severity=severity)
+        if not reported and not self.errors:
+            console.print("no violations found", markup=False)
+            return
+        for validator in sorted({v.validator for v in reported}):
+            console.print(f"{validator}:", markup=False)
+            for violation in [v for v in reported if v.validator == validator]:
+                location = violation.source or "(no specific location)"
+                console.print(
+                    f"  {violation.severity.value}: {violation.message} — {location}",
+                    markup=False,
+                )
+        if self.errors:
+            console.print("validator errors:", markup=False)
+            for error in self.errors:
+                console.print(f"  {error.phase}: {error.validator}: {error.message}", markup=False)

bookwright/validation/runner.py

@@ -0,0 +1,65 @@
+"""Run the active validators with per-validator isolation (FR-014, D8/D9).
+
+A validator that raises is caught and recorded as a ``ValidatorError(phase="run")``
+without aborting the others (FR-014). Identical findings are deduped and the
+combined set is sorted by an explicit total-order key so the emitted list is
+byte-identical across runs and platforms (SC-003), not merely "stably sorted".
+"""
+
+from __future__ import annotations
+
+from bookwright.indexers import Indexer
+from bookwright.validation.base import (
+    _RANK,
+    ValidationContext,
+    Validator,
+    ValidatorError,
+    Violation,
+)
+
+__all__ = ["RunResult", "run_validators", "sort_key"]
+
+RunResult = tuple[list[Violation], list[ValidatorError], list[str]]
+"""``(violations, errors, ran)`` — deduped/sorted findings, run errors, run names."""
+
+
+def sort_key(violation: Violation) -> tuple[str, int, str, str, tuple[tuple[str, str, str], ...]]:
+    """The explicit total order (D8): validator, severity desc, source, message, triples."""
+    return (
+        violation.validator,
+        -_RANK[violation.severity],
+        violation.source or "",
+        violation.message,
+        violation.triples,
+    )
+
+
+def run_validators(
+    active: list[Validator], project: ValidationContext, indexer: Indexer
+) -> RunResult:
+    """Run every validator in ``active``, isolating failures (FR-014).
+
+    Collects each validator's ``Violation`` list, deduplicates identical findings
+    across the whole run (D8), and returns them sorted by :func:`sort_key`. A
+    validator that raises contributes a ``ValidatorError(phase="run")`` and no
+    findings; the rest still run. ``ran`` lists every invoked validator name, sorted.
+    """
+    seen: set[Violation] = set()
+    violations: list[Violation] = []
+    errors: list[ValidatorError] = []
+    ran: list[str] = []
+
+    for validator in active:
+        ran.append(validator.name)
+        try:
+            found = validator.validate(project, indexer)
+        except Exception as exc:  # per-validator isolation (FR-014) — never abort the run
+            errors.append(ValidatorError(validator.name, f"{type(exc).__name__}: {exc}", "run"))
+            continue
+        for violation in found:
+            if violation not in seen:
+                seen.add(violation)
+                violations.append(violation)
+
+    violations.sort(key=sort_key)
+    return violations, errors, sorted(ran)

bookwright/validation/validators/__init__.py

@@ -0,0 +1,9 @@
+"""Built-in validator modules.
+
+This package is the auto-discovery root: :func:`bookwright.validation.registry.
+discover_validators` iterates its modules with ``pkgutil.iter_modules`` and
+collects every module-level object satisfying the ``Validator`` protocol. Adding
+a built-in is dropping a new module here — no hand-registration (FR-004).
+"""
+
+from __future__ import annotations

bookwright/validation/validators/character_presence.py

@@ -0,0 +1,202 @@
+"""``character_presence`` — bible roster vs. manuscript mentions (FR-016, research D3).
+
+Two directions, split by severity so a heuristic false positive can never fail CI:
+
+* a bible character **never** mentioned in the manuscript → orphan finding at
+  **error** (deterministic — the name and the prose are both authored),
+* a proper-noun candidate in the prose with **no** bible entry → unknown-mention at
+  **warning** (a pinned, conservative heuristic — no NER).
+
+Unknown mentions are collapsed per distinct name (one finding citing the first
+occurrence), never multiplied per mention (edge case).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import ClassVar
+
+from bookwright.golem.slug import make_slug
+from bookwright.indexers import Indexer
+from bookwright.validation.base import Severity, ValidationContext, Violation
+
+# Pinned proper-noun candidate: a capitalized word of ≥3 letters (D3). Accent-aware
+# for Spanish prose; matches single tokens (multi-word names are caught token-wise).
+_CANDIDATE = re.compile(r"[A-ZÁÉÍÓÚÑÜ][a-záéíóúñü]{2,}")
+# Sentence-ending punctuation: a capital right after one of these (or at line start)
+# is grammatical, not necessarily a proper noun — excluded (conservative, D3).
+_SENTENCE_END = frozenset(".!?¿¡")
+_MIN_TOKEN_LEN = 3  # shortest name token worth matching as a standalone word.
+# Common capitalized non-names we never treat as a character mention (pinned stop-set).
+_STOP_WORDS = frozenset(
+    {
+        # Spanish weekdays / months / frequent sentence openers.
+        "lunes",
+        "martes",
+        "miercoles",
+        "jueves",
+        "viernes",
+        "sabado",
+        "domingo",
+        "enero",
+        "febrero",
+        "marzo",
+        "abril",
+        "mayo",
+        "junio",
+        "julio",
+        "agosto",
+        "septiembre",
+        "octubre",
+        "noviembre",
+        "diciembre",
+        "entonces",
+        "cuando",
+        "aunque",
+        "pero",
+        "porque",
+        "tambien",
+        "despues",
+        "antes",
+        "ahora",
+        "nunca",
+        "siempre",
+        "quiza",
+        "quizas",
+        "acaso",
+        # English weekdays / months / openers.
+        "monday",
+        "tuesday",
+        "wednesday",
+        "thursday",
+        "friday",
+        "saturday",
+        "sunday",
+        "january",
+        "february",
+        "march",
+        "april",
+        "may",
+        "june",
+        "july",
+        "august",
+        "september",
+        "october",
+        "november",
+        "december",
+        "then",
+        "when",
+        "although",
+        "because",
+        "after",
+        "before",
+        "however",
+        "perhaps",
+    }
+)
+
+
+class CharacterPresence:
+    """Cross-checks the bible character roster against manuscript proper nouns."""
+
+    name: ClassVar[str] = "character_presence"
+    severity_default: ClassVar[Severity] = Severity.error
+
+    def validate(self, project: ValidationContext, indexer: Indexer) -> list[Violation]:
+        roster = project.character_names()
+        files = project.manuscript_files()
+        roster_slugs = _roster_slugs(roster)
+
+        out: list[Violation] = []
+        out.extend(self._orphans(roster, files))
+        out.extend(self._unknown_mentions(files, roster_slugs))
+        return out
+
+    def _orphans(
+        self,
+        roster: tuple[tuple[str, str], ...],
+        files: tuple[tuple[str, str], ...],
+    ) -> list[Violation]:
+        out: list[Violation] = []
+        for name, relpath in roster:
+            if not _is_mentioned(name, files):
+                out.append(
+                    Violation(
+                        validator=self.name,
+                        severity=Severity.error,
+                        message=(
+                            f"character '{name}' is defined in the bible but never "
+                            "mentioned in the manuscript"
+                        ),
+                        source=relpath,
+                        triples=(),
+                    )
+                )
+        return out
+
+    def _unknown_mentions(
+        self,
+        files: tuple[tuple[str, str], ...],
+        roster_slugs: frozenset[str],
+    ) -> list[Violation]:
+        # slug → (display name, first "relpath:line"); first occurrence wins.
+        first_seen: dict[str, tuple[str, str]] = {}
+        for relpath, text in files:
+            for lineno, line in enumerate(text.splitlines(), start=1):
+                for match in _CANDIDATE.finditer(line):
+                    token = match.group(0)
+                    slug = make_slug(token)
+                    if (
+                        slug in roster_slugs
+                        or slug in first_seen
+                        or slug in _STOP_WORDS
+                        or _is_sentence_initial(line, match.start())
+                    ):
+                        continue
+                    first_seen[slug] = (token, f"{relpath}:{lineno}")
+        out: list[Violation] = []
+        for _, (token, source) in sorted(first_seen.items()):
+            out.append(
+                Violation(
+                    validator=self.name,
+                    severity=Severity.warning,
+                    message=(
+                        f"proper noun '{token}' appears in the manuscript but has no "
+                        "bible entry (heuristic — may be a place or organization)"
+                    ),
+                    source=source,
+                    triples=(),
+                )
+            )
+        return out
+
+
+def _roster_slugs(roster: tuple[tuple[str, str], ...]) -> frozenset[str]:
+    """Slugs for every roster name and each of its tokens (so a surname matches)."""
+    slugs: set[str] = set()
+    for name, _ in roster:
+        slugs.add(make_slug(name))
+        for token in name.split():
+            candidate = make_slug(token)
+            if candidate:
+                slugs.add(candidate)
+    return frozenset(slugs)
+
+
+def _is_mentioned(name: str, files: tuple[tuple[str, str], ...]) -> bool:
+    """Whether ``name`` (full phrase or any ≥3-letter token) appears as a word."""
+    patterns = [re.compile(rf"\b{re.escape(name)}\b", re.IGNORECASE)]
+    patterns += [
+        re.compile(rf"\b{re.escape(token)}\b", re.IGNORECASE)
+        for token in name.split()
+        if len(token) >= _MIN_TOKEN_LEN
+    ]
+    return any(pattern.search(text) for pattern in patterns for _, text in files)
+
+
+def _is_sentence_initial(line: str, start: int) -> bool:
+    """Whether the match at ``start`` opens a sentence (capitalization is grammatical)."""
+    prefix = line[:start].rstrip()
+    if not prefix:
+        return True
+    return prefix[-1] in _SENTENCE_END