project_root.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/core/project_root.py
 
"""
Purpose
-------
Provide shared logic for detecting the root of an Option C project.
 
Responsibilities
----------------
- Walk upward from the current directory.
- Identify the project root by required directories.
"""
 
import json
import sys
from pathlib import Path
import click
 
 
# Maximum size of an .octrc.json file that will be read during root discovery.
# Larger files are skipped to prevent memory exhaustion from malicious or
# accidentally oversized config files in parent directories (OI-414).
MAX_OCTRC_SIZE = 64 * 1024  # 64 KB
 
 
def find_project_root(start: Path) -> Path:
    current = start.resolve()
    workspace_root: Path | None = None
    for parent in [current] + list(current.parents):
        # FS-539: .option_c/ is the canonical root marker on migrated
        # projects — its presence alone is sufficient evidence that this
        # directory is an Option C project root. Checked first so the
        # detector is fastest on post-v0.19.0 projects.
        if (parent / ".option_c").is_dir():
            return parent
 
        # Check for explicit root marker next
        octrc = parent / ".octrc.json"
        if octrc.is_file():
            try:
                size = octrc.stat().st_size
                if size > MAX_OCTRC_SIZE:
                    print(
                        f"Warning: skipping {octrc} ({size} bytes > "
                        f"{MAX_OCTRC_SIZE} limit)",
                        file=sys.stderr,
                    )
                else:
                    cfg = json.loads(octrc.read_text(encoding="utf-8"))
                    if cfg.get("root_marker", False):
                        return parent
            except (json.JSONDecodeError, OSError):
                pass
 
        has_oc_diag = (parent / "oc_diagnostics").exists()
        has_legacy = (parent / "diagnostics").exists()
        has_diag = has_oc_diag or has_legacy
        if (parent / "docs").exists() and (parent / "tests").exists() and has_diag:
            if has_legacy and not has_oc_diag:
                click.echo(
                    "Warning: 'diagnostics/' is deprecated and will be removed in v1.0.0. "
                    "Rename to 'oc_diagnostics/'.",
                    err=True,
                )
            return parent
 
        # F1 / L1: workspace manifest acts as a fallback root for
        # commands that need a working directory but no per-project
        # markers (e.g. ``oct git status`` from the workspace root in
        # a monorepo). Recorded but not returned yet — a project root
        # closer to ``start`` always wins.
        if workspace_root is None and (
            parent / ".option_c_workspace.json"
        ).is_file():
            workspace_root = parent
 
    if workspace_root is not None:
        return workspace_root
    raise click.ClickException("Could not locate project root.")
 
 
def get_project_root(ctx: click.Context) -> Path:
    """Return project root from --root-dir override or auto-detection.
 
    When ``--root-dir`` is supplied, OI-405 requires the target directory to
    look like an Option C project (contain ``pyproject.toml`` or
    ``.octrc.json``). If the user intentionally wants to point at an
    unrelated directory, they must also pass ``--allow-outside-project``,
    which is recorded in ``ctx.obj``.
    """
    root_dir = ctx.obj.get("root_dir") if ctx.obj else None
    if root_dir:
        resolved = Path(root_dir).resolve()
        if not resolved.is_dir():
            raise click.ClickException(f"--root-dir path does not exist: {resolved}")
        allow_outside = bool(ctx.obj.get("allow_outside_project")) if ctx.obj else False
        if not allow_outside:
            has_marker = (
                (resolved / "pyproject.toml").is_file()
                or (resolved / ".octrc.json").is_file()
                or (resolved / ".option_c").is_dir()  # FS-539
                or (resolved / ".option_c_workspace.json").is_file()  # F1
            )
            if not has_marker:
                raise click.ClickException(
                    f"--root-dir {resolved} does not appear to be an Option C project "
                    f"(no pyproject.toml, .octrc.json, or .option_c/). Pass "
                    f"--allow-outside-project to override."
                )
        return resolved
    return find_project_root(Path.cwd())
 
 
def is_within_project_root(path: Path, project_root: Path) -> bool:
    """Pure predicate: True if ``path`` resolves inside ``project_root``.
 
    Symlink-safe: both sides are resolved before comparison so symlink
    targets cannot escape the project root. Never raises — any ``OSError``
    during resolution is treated as "not inside". Intended for library
    callers (e.g. ``oct.core.git``) that must not depend on Click.
    """
    try:
        resolved = Path(path).resolve()
        root_resolved = Path(project_root).resolve()
    except OSError:
        return False
    try:
        resolved.relative_to(root_resolved)
        return True
    except ValueError:
        return False
 
 
def validate_path_containment(
    path: Path, project_root: Path, allow_outside: bool = False
) -> Path:
    """Resolve ``path`` and verify it is within ``project_root``.
 
    If ``allow_outside`` is True, the resolved path is returned without
    containment enforcement. Otherwise, a ``click.ClickException`` is raised
    when the path falls outside ``project_root``. Used by export and clean
    commands to prevent accidental operations on files outside the project
    via symlink tricks or bare ``..`` paths (OI-405).
    """
    resolved = Path(path).resolve()
    if allow_outside:
        return resolved
    root_resolved = Path(project_root).resolve()
    if not is_within_project_root(resolved, root_resolved):
        raise click.ClickException(
            f"Path {resolved} is outside project root {root_resolved}. "
            f"Use --allow-outside-project to override."
        )
    return resolved