bookwright-cli 0.2.0__py3-none-any.whl

bookwright/core/_build.py

@@ -0,0 +1,154 @@
+"""Builder for fresh manifests from minimal inputs (FR-015..FR-017).
+
+Internal helper for `bookwright.core.manifest`. `Manifest.build()` is the
+public entry point and delegates here. Kept separate so the public model
+module stays under the Principle IV 500-line ceiling.
+See specs/002-manifest-model/contracts/manifest_api.md §`Manifest.build`.
+"""
+
+from __future__ import annotations
+
+from functools import cache
+from importlib.resources import files as _resource_files
+from typing import TYPE_CHECKING, Any
+
+import tomlkit
+from packaging.version import InvalidVersion, Version
+from pydantic import ValidationError
+from tomlkit.toml_document import TOMLDocument
+
+from bookwright.core._translate import _translate_validation_error
+
+if TYPE_CHECKING:
+    from bookwright.core.manifest import Manifest
+
+
+_BUILD_OVERRIDE_ALLOWLIST_TABLE: dict[str, tuple[str, str]] = {
+    "language": ("book", "language"),
+    "type": ("book", "type"),
+    "subtitle": ("book", "subtitle"),
+    "genre": ("book", "genre"),
+    "target_length_words": ("book", "target_length_words"),
+    "status": ("book", "status"),
+    "book_metadata": ("book", "metadata"),
+    "vocabularies_active": ("vocabularies", "active"),
+    "validators_enabled": ("validators", "enabled"),
+    "validators_disabled": ("validators", "disabled"),
+    "validators_custom": ("validators", "custom"),
+    "paths_manuscript": ("paths", "manuscript"),
+    "paths_bible": ("paths", "bible"),
+    "paths_outline": ("paths", "outline"),
+    "paths_graph": ("paths", "graph"),
+    "paths_constitution": ("paths", "constitution"),
+    "integration_options": ("integration", "options"),
+    "integration_skills_dir": ("integration", "skills_dir"),
+    "manifest_version": ("bookwright", "manifest_version"),
+    "schema_version": ("bookwright", "schema_version"),
+    "cli_version_min": ("bookwright", "cli_version_min"),
+    "uri_base": ("bookwright", "uri_base"),
+    "indexer": ("bookwright", "indexer"),
+}
+
+
+@cache
+def _template_text() -> str:
+    """Cached read of the bundled manifest template (text only)."""
+
+    resource = _resource_files("bookwright.resources.templates").joinpath("manifest.template.toml")
+    return resource.read_text(encoding="utf-8")
+
+
+def _load_template_document() -> TOMLDocument:
+    """Return a fresh tomlkit document parsed from the cached template text.
+
+    The on-disk read is amortised via `_template_text()`; each call still
+    parses a new document so callers get independent mutable trees.
+    """
+
+    return tomlkit.parse(_template_text())
+
+
+def _build_manifest(  # noqa: PLR0913 — model_cls + 3 user inputs + 2 injected deps; injection breaks an import cycle with manifest.py.
+    model_cls: type[Manifest],
+    *,
+    title: str,
+    authors: list[str],
+    integration_key: str,
+    installed_version: str,
+    default_skills_dir: dict[str, str],
+    **overrides: Any,
+) -> Manifest:
+    """Construct a fresh manifest from minimal inputs.
+
+    `installed_version` and `default_skills_dir` are injected by the caller
+    so this helper does not need to import `bookwright.core.manifest`,
+    which would close an import cycle.
+
+    Override semantics: passing an override as `None` is treated as
+    "not supplied" (the template default stands). This keeps conditional
+    propagation patterns (`build(..., subtitle=user_subtitle)` where
+    `user_subtitle` may be None) from leaking tomlkit's
+    `ConvertError` on `NoneType`.
+    """
+
+    unknown = set(overrides) - _BUILD_OVERRIDE_ALLOWLIST_TABLE.keys()
+    if unknown:
+        names = ", ".join(repr(n) for n in sorted(unknown))
+        raise TypeError(f"build() got unexpected keyword argument(s): {names}")
+
+    # Drop explicit-None overrides up-front (treated as "not supplied").
+    effective_overrides: dict[str, Any] = {k: v for k, v in overrides.items() if v is not None}
+
+    document = _load_template_document()
+
+    # Apply the three required positional inputs.
+    document["book"]["title"] = title
+    document["book"]["authors"] = list(authors)
+    document["integration"]["key"] = integration_key
+
+    # cli_version_min default = installed CLI version. When the caller did
+    # NOT override cli_version_min and the installed version isn't valid
+    # PEP 440, fail with a clear message that blames the *environment*,
+    # not a field the user never supplied.
+    if "cli_version_min" not in effective_overrides:
+        try:
+            Version(installed_version)
+        except InvalidVersion as exc:
+            raise RuntimeError(
+                f"installed CLI version {installed_version!r} is not a valid "
+                f"PEP 440 string; cannot derive a cli_version_min default. "
+                f"Pass cli_version_min= explicitly."
+            ) from exc
+        document["bookwright"]["cli_version_min"] = installed_version
+
+    # uri_base has no default at build time (data-model.md). If the caller
+    # did not override it, surface the missing-field failure.
+    if "uri_base" not in effective_overrides:
+        del document["bookwright"]["uri_base"]
+
+    # skills_dir default depends on integration_key (FR-017).
+    if "integration_skills_dir" in effective_overrides:
+        document["integration"]["skills_dir"] = effective_overrides["integration_skills_dir"]
+    else:
+        try:
+            document["integration"]["skills_dir"] = default_skills_dir[integration_key]
+        except KeyError as exc:
+            raise TypeError(
+                f"build() requires explicit integration_skills_dir for unknown "
+                f"integration_key={integration_key!r}"
+            ) from exc
+
+    # Overlay caller-provided overrides.
+    for kwarg, value in effective_overrides.items():
+        if kwarg == "integration_skills_dir":
+            continue  # already applied above
+        target_block, target_key = _BUILD_OVERRIDE_ALLOWLIST_TABLE[kwarg]
+        document[target_block][target_key] = value
+
+    # Re-parse through Pydantic for end-to-end validation (FR-016).
+    try:
+        instance = model_cls.model_validate(document.unwrap())
+    except ValidationError as exc:
+        raise _translate_validation_error(exc) from exc
+    instance._document = document
+    return instance

bookwright/core/_research_block.py

@@ -0,0 +1,56 @@
+"""The ``[research]`` manifest block model (FR-011..FR-016).
+
+Extracted from ``manifest.py`` so that module stays under the Principle IV
+500-line ceiling (it is already 535 lines). ``Manifest`` imports
+:class:`ResearchBlock` and exposes it as ``Manifest.research``; the public surface
+re-exports it from ``bookwright.core``.
+
+The three reliability values are duplicated from
+``golem.namespaces.RELIABILITY_IRI`` **on purpose**: ``core`` must not import
+``golem`` (layer direction, and the registry already late-imports to avoid a
+cycle). A unit test asserts the ``Literal`` stays in sync with that vocabulary
+(RB-8, research §R5) — the same anti-drift discipline as the SC-009 gate.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic_core import PydanticCustomError
+
+from bookwright.core.iso639_1 import ISO_639_1_CODES
+
+
+class ResearchBlock(BaseModel):
+    """``[research]`` block — optional research-system configuration.
+
+    All three fields carry documented defaults, so a manifest **without** a
+    ``[research]`` block loads with the same values an explicit default block
+    would produce (FR-012). ``extra="forbid", strict=True`` matches every sibling
+    block — an unknown key inside ``[research]`` is a validation error.
+    """
+
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    enabled: bool = True
+    source_languages: list[str] = Field(default_factory=list)
+    min_reliability_for_anchor: Literal["alta", "media", "baja"] = "media"
+
+    @field_validator("source_languages", mode="after")
+    @classmethod
+    def _check_source_languages(cls, value: list[str]) -> list[str]:
+        """Reject any non-ISO-639-1 entry, naming ``source_languages[i]`` (FR-016).
+
+        Mirrors ``BookBlock._check_language``; the ``index``/``value`` context is
+        spliced into the public ``field_path`` by ``_translate_validation_error``.
+        """
+
+        for index, entry in enumerate(value):
+            if entry not in ISO_639_1_CODES:
+                raise PydanticCustomError(
+                    "not_iso_639_1",
+                    "source_languages[{index}] '{value}' is not a valid ISO 639-1 code",
+                    {"index": index, "value": entry},
+                )
+        return value

bookwright/core/_translate.py

@@ -0,0 +1,90 @@
+"""Pydantic `ValidationError` → public `ManifestValidationError` translation.
+
+Internal helper for `bookwright.core.manifest`. Kept separate so the
+public model module stays under the Principle IV 500-line ceiling.
+See specs/002-manifest-model/contracts/manifest_api.md.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import ValidationError
+
+from bookwright.core.errors import ManifestValidationError, _FieldFailure
+
+_PYDANTIC_TYPE_TO_KIND: dict[str, str] = {
+    "missing": "missing",
+    "string_type": "not_a_string",
+    "int_type": "not_an_integer",
+    "list_type": "not_a_list",
+    "dict_type": "not_a_dict",
+    "bool_type": "not_a_bool",
+    "literal_error": "not_in_enum",
+    "extra_forbidden": "unknown_key",
+}
+
+# Model-level errors (raised from `@model_validator`) carry no field location.
+# Remap them to the field they conceptually belong to.
+_ROOT_ERROR_REMAP: dict[str, str] = {
+    "installed_too_old": "bookwright.cli_version_min",
+    "installed_not_pep440": "bookwright.cli_version_min",
+}
+
+
+def _format_loc(loc: tuple[Any, ...]) -> str:
+    """Render a Pydantic location tuple as a dotted path with `[N]` indices."""
+
+    parts: list[str] = []
+    for piece in loc:
+        if isinstance(piece, int):
+            assert parts, "Pydantic loc never starts with an int"
+            parts[-1] = f"{parts[-1]}[{piece}]"
+        else:
+            parts.append(str(piece))
+    return ".".join(parts)
+
+
+def _translate_validation_error(exc: ValidationError) -> ManifestValidationError:
+    """Convert a `pydantic.ValidationError` to the public `ManifestValidationError` shape."""
+
+    failures: list[_FieldFailure] = []
+    for err in exc.errors():
+        loc = err.get("loc", ())
+        field_path = _format_loc(loc)
+        rejected = err.get("input")
+        message = err.get("msg", "")
+        err_type = err.get("type", "")
+        ctx = err.get("ctx") or {}
+
+        if not field_path and err_type in _ROOT_ERROR_REMAP:
+            field_path = _ROOT_ERROR_REMAP[err_type]
+
+        # Pydantic built-in error types map to short kinds; custom errors
+        # (PydanticCustomError) carry their `error_type` here verbatim.
+        kind = _PYDANTIC_TYPE_TO_KIND.get(err_type, err_type or "validation")
+
+        # Prefer the offending value the validator named in `ctx["value"]`
+        # (e.g. authors[N] entry) over the validator's whole input.
+        if "value" in ctx:
+            rejected = ctx["value"]
+
+        rule_id = f"{field_path}.{kind}" if field_path else kind
+
+        # A field-level validator (e.g. `_check_authors`) that walks a list
+        # cannot embed the offending index in Pydantic's loc. When it surfaces
+        # `ctx["index"]` we splice the `[N]` suffix here so the public
+        # `field_path` matches the published contract (book.authors[N]) while
+        # `rule_id` stays index-free.
+        if "index" in ctx and isinstance(ctx["index"], int):
+            field_path = f"{field_path}[{ctx['index']}]"
+
+        failures.append(
+            _FieldFailure(
+                field_path=field_path,
+                rejected_value=rejected,
+                rule_id=rule_id,
+                message=message,
+            )
+        )
+    return ManifestValidationError(tuple(failures))

bookwright/core/errors.py

@@ -0,0 +1,127 @@
+"""Public exception hierarchy and warning model for the manifest module.
+
+The error JSON shape is the canonical envelope owned by ``BookwrightError``
+(this iteration normalized the former flat ``{"error": …}`` bodies onto it).
+See specs/018-unified-error-envelope/contracts/error-envelope.md.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+from bookwright.errors import BookwrightError
+
+
+@dataclass(frozen=True)
+class _FieldFailure:
+    """One field-level validation failure.
+
+    Internal type. The public JSON form is emitted under
+    ``ManifestValidationError``'s ``details["failures"]``.
+    """
+
+    field_path: str
+    rejected_value: Any
+    rule_id: str
+    message: str
+
+
+class ManifestError(BookwrightError):
+    """Base for every failure mode the manifest module owns.
+
+    Abstract: declares no ``code`` and is never serialized directly.
+    """
+
+
+class ManifestNotFoundError(ManifestError):
+    """The manifest file does not exist."""
+
+    code = "manifest_not_found"
+
+    def __init__(self, path: Path | str) -> None:
+        self.path = Path(path).resolve()
+        super().__init__(f"no manifest at {self.path}", {"path": str(self.path)})
+
+
+class ManifestSyntaxError(ManifestError):
+    """The manifest file exists but is not valid TOML."""
+
+    code = "manifest_syntax"
+
+    def __init__(
+        self,
+        path: Path | str,
+        line: int | None,
+        column: int | None,
+        message: str,
+    ) -> None:
+        self.path = Path(path).resolve()
+        self.line = line
+        self.column = column
+        super().__init__(
+            message,
+            {"field": f"bookwright.{self.path.name}", "line": line, "column": column},
+        )
+
+
+class ManifestValidationError(ManifestError):
+    """One or more field-level validation failures (FR-004..FR-013)."""
+
+    code = "manifest_validation"
+
+    def __init__(self, failures: tuple[_FieldFailure, ...]) -> None:
+        if not failures:
+            raise ValueError("ManifestValidationError requires at least one failure")
+        self.failures = failures
+        first = failures[0]
+        summary = (
+            f"{len(failures)} validation failure(s); first: {first.field_path}: {first.message}"
+        )
+        super().__init__(
+            summary,
+            {
+                "failures": [
+                    {
+                        "field": f.field_path,
+                        "value": f.rejected_value,
+                        "rule": f.rule_id,
+                        "message": f.message,
+                    }
+                    for f in failures
+                ]
+            },
+        )
+
+
+class ManifestOverwriteError(ManifestError):
+    """Refuse to overwrite an existing manifest (FR-019)."""
+
+    code = "manifest_overwrite_refused"
+
+    def __init__(self, path: Path | str) -> None:
+        self.path = Path(path).resolve()
+        super().__init__(
+            f"refuse to overwrite existing manifest at {self.path} (pass overwrite=True to force)",
+            {"path": str(self.path)},
+        )
+
+
+class ManifestWarning(BaseModel):
+    """A non-fatal note attached to `Manifest.warnings` during `load()`."""
+
+    rule_id: str
+    field_path: str
+    offending_value: Any
+    message: str
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "rule": self.rule_id,
+            "field": self.field_path,
+            "value": self.offending_value,
+            "message": self.message,
+        }

bookwright/core/iso639_1.py

@@ -0,0 +1,200 @@
+"""ISO 639-1 alpha-2 language codes.
+
+Source: ISO 639-1 (Alpha-2 Codes for Representation of Names of Languages).
+The full registry is bundled in-package as a frozenset literal. No network
+access, no curation, no editorial filtering — constructed languages with
+official codes (eo, la, cu, ...) are included because they are part of the
+standard. See research §R3 for the rationale.
+"""
+
+from __future__ import annotations
+
+ISO_639_1_CODES: frozenset[str] = frozenset(
+    {
+        "aa",
+        "ab",
+        "ae",
+        "af",
+        "ak",
+        "am",
+        "an",
+        "ar",
+        "as",
+        "av",
+        "ay",
+        "az",
+        "ba",
+        "be",
+        "bg",
+        "bh",
+        "bi",
+        "bm",
+        "bn",
+        "bo",
+        "br",
+        "bs",
+        "ca",
+        "ce",
+        "ch",
+        "co",
+        "cr",
+        "cs",
+        "cu",
+        "cv",
+        "cy",
+        "da",
+        "de",
+        "dv",
+        "dz",
+        "ee",
+        "el",
+        "en",
+        "eo",
+        "es",
+        "et",
+        "eu",
+        "fa",
+        "ff",
+        "fi",
+        "fj",
+        "fo",
+        "fr",
+        "fy",
+        "ga",
+        "gd",
+        "gl",
+        "gn",
+        "gu",
+        "gv",
+        "ha",
+        "he",
+        "hi",
+        "ho",
+        "hr",
+        "ht",
+        "hu",
+        "hy",
+        "hz",
+        "ia",
+        "id",
+        "ie",
+        "ig",
+        "ii",
+        "ik",
+        "io",
+        "is",
+        "it",
+        "iu",
+        "ja",
+        "jv",
+        "ka",
+        "kg",
+        "ki",
+        "kj",
+        "kk",
+        "kl",
+        "km",
+        "kn",
+        "ko",
+        "kr",
+        "ks",
+        "ku",
+        "kv",
+        "kw",
+        "ky",
+        "la",
+        "lb",
+        "lg",
+        "li",
+        "ln",
+        "lo",
+        "lt",
+        "lu",
+        "lv",
+        "mg",
+        "mh",
+        "mi",
+        "mk",
+        "ml",
+        "mn",
+        "mr",
+        "ms",
+        "mt",
+        "my",
+        "na",
+        "nb",
+        "nd",
+        "ne",
+        "ng",
+        "nl",
+        "nn",
+        "no",
+        "nr",
+        "nv",
+        "ny",
+        "oc",
+        "oj",
+        "om",
+        "or",
+        "os",
+        "pa",
+        "pi",
+        "pl",
+        "ps",
+        "pt",
+        "qu",
+        "rm",
+        "rn",
+        "ro",
+        "ru",
+        "rw",
+        "sa",
+        "sc",
+        "sd",
+        "se",
+        "sg",
+        "si",
+        "sk",
+        "sl",
+        "sm",
+        "sn",
+        "so",
+        "sq",
+        "sr",
+        "ss",
+        "st",
+        "su",
+        "sv",
+        "sw",
+        "ta",
+        "te",
+        "tg",
+        "th",
+        "ti",
+        "tk",
+        "tl",
+        "tn",
+        "to",
+        "tr",
+        "ts",
+        "tt",
+        "tw",
+        "ty",
+        "ug",
+        "uk",
+        "ur",
+        "uz",
+        "ve",
+        "vi",
+        "vo",
+        "wa",
+        "wo",
+        "xh",
+        "yi",
+        "yo",
+        "za",
+        "zh",
+        "zu",
+    }
+)
+"""All 184 ISO 639-1 alpha-2 codes (lowercase)."""