Skip to content

💫 Toolkit to help you get started with SDD or any other process!

5.7 KB
Raw Blame
"""Strict project configuration bootstrap and explicit FileHelper handoff."""

from __future__ import annotations

import json
import stat
from pathlib import Path
from typing import Any, NoReturn

from ._init_options import INIT_OPTIONS_FILE
from .file_helper import FileHelper, FileHelperError


class ProjectPolicyError(ValueError):
    """The project configuration cannot safely supply a filesystem policy."""


def _validate_options(options: Any) -> dict[str, Any]:
    if not isinstance(options, dict):
        raise ProjectPolicyError(f"{INIT_OPTIONS_FILE} must contain a JSON object")
    if "allow_symlinks" in options and type(options["allow_symlinks"]) is not bool:
        raise ProjectPolicyError(
            f"{INIT_OPTIONS_FILE}: allow_symlinks must be a JSON boolean (true or false)"
        )
    return options


def _reject_json_constant(value: str) -> NoReturn:
    raise ValueError(f"Non-JSON numeric constant: {value}")


def read_project_options(project_root: Path) -> dict[str, Any]:
    """Read without following configuration links; only absence defaults."""
    try:
        files = FileHelper(project_root)
    except (OSError, RuntimeError) as exc:
        raise ProjectPolicyError(
            f"Cannot establish project root for {INIT_OPTIONS_FILE}: {exc}"
        ) from exc
    try:
        text = files.read_text(INIT_OPTIONS_FILE)
    except FileNotFoundError:
        return {}
    except (OSError, UnicodeError, FileHelperError) as exc:
        raise ProjectPolicyError(
            f"Cannot read {INIT_OPTIONS_FILE}: {exc}. "
            "Ensure the configuration hierarchy is non-symlinked and readable."
        ) from exc
    try:
        options = json.loads(text, parse_constant=_reject_json_constant)
    except (ValueError, RecursionError) as exc:
        raise ProjectPolicyError(
            f"Invalid JSON in {INIT_OPTIONS_FILE}: {exc}. Repair the configuration."
        ) from exc
    return _validate_options(options)


def project_files(project_root: Path) -> FileHelper:
    """Resolve current policy afresh and return an immutable operation owner."""
    options = read_project_options(project_root)
    try:
        return FileHelper(project_root, allow_symlinks=options.get("allow_symlinks", False))
    except (OSError, RuntimeError) as exc:
        raise ProjectPolicyError(f"Cannot establish project filesystem boundary: {exc}") from exc


def save_project_options(project_root: Path, options: dict[str, Any]) -> None:
    """Persist with deny-mode bootstrap and legacy metadata/text I/O behavior."""
    _validate_options(options)
    try:
        content = json.dumps(
            options, indent=2, sort_keys=True, ensure_ascii=False, allow_nan=False
        ) + "\n"
    except (TypeError, ValueError, RecursionError) as exc:
        raise ProjectPolicyError(f"Cannot encode {INIT_OPTIONS_FILE} as JSON: {exc}") from exc
    try:
        files = FileHelper(project_root)
        # Validate the entire destination before creating even .specify.
        try:
            files.read_text(INIT_OPTIONS_FILE)
        except FileNotFoundError:
            pass
        from .integrations._file_changes import after_file_change, before_file_change

        destination = project_root / INIT_OPTIONS_FILE
        before_file_change(destination)
        files.mkdir(".specify", exist_ok=True)
        files.overwrite_text(INIT_OPTIONS_FILE, content)
        after_file_change(destination)
    except (OSError, UnicodeError, FileHelperError, RuntimeError) as exc:
        raise ProjectPolicyError(
            f"Cannot write {INIT_OPTIONS_FILE}: {exc}. "
            "Ensure the configuration hierarchy is non-symlinked and writable."
        ) from exc


def _existing_init_parent(target: Path) -> Path:
    ancestor = target.parent
    while not ancestor.exists() and not ancestor.is_symlink():
        ancestor = ancestor.parent
    return ancestor


def _validate_init_traversal(target: Path) -> None:
    # Windows presence probes can fold missing/../existing before filesystem access.
    for index, part in enumerate(target.parts):
        if part != "..":
            continue
        prefix = Path(*target.parts[:index])
        try:
            is_directory = stat.S_ISDIR(prefix.stat().st_mode)
        except FileNotFoundError as exc:
            raise FileHelperError(
                f"Parent traversal requires an existing directory before '..': {prefix}"
            ) from exc
        if not is_directory:
            raise FileHelperError(
                f"Parent traversal requires an existing directory before '..': {prefix}"
            )


def preflight_init_root(target: Path) -> Path:
    """Validate original init spelling and policy before project preparation."""
    target = target.absolute()
    try:
        _validate_init_traversal(target)
        if target.exists() or target.is_symlink():
            read_project_options(target)
        else:
            files = FileHelper(_existing_init_parent(target))
            try:
                files.read_bytes(target)
            except FileNotFoundError:
                pass
        return target.resolve()
    except (OSError, FileHelperError, RuntimeError) as exc:
        raise ProjectPolicyError(
            f"Cannot establish init project root {target}: {exc}"
        ) from exc


def prepare_init_root(target: Path) -> Path:
    """Create a missing init root beneath its nearest existing trusted parent.

    Existing explicit root aliases are trusted just like FileHelper roots.
    For new roots, deny traversal below the nearest existing directory.
    """
    target = target.absolute()
    _validate_init_traversal(target)
    if target.exists() or target.is_symlink():
        FileHelper(target)
        return target
    FileHelper(_existing_init_parent(target)).mkdir(target, parents=True, exist_ok=True)
    return target