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.
 
Diagnostics
-----------
Domain: OCT-CORE
Levels:
    L2 - (none) a failed search raises through click rather than logging
    L3 - root search entry, and each containment check with its verdict
    L4 - (none)
 
Contracts
---------
- Root discovery never adopts a root at or above the OS temp boundary.
- ``.octrc.json`` files larger than :data:`MAX_OCTRC_SIZE` are skipped
  rather than read, so an oversized parent config cannot exhaust memory.
- ``is_within_project_root`` is the containment predicate; every caller
  that needs to refuse an escaping path goes through it or
  ``validate_path_containment``.
 
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
- click (ClickException for a failed root search, a rejected --root-dir or an escaping path; echo for the diagnostics/ deprecation warning; the Context carrying --root-dir)
"""
 
import json
import sys
import tempfile
from pathlib import Path
import click
from oct.core.diagnostics import _dbg
 
 
# 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 _at_or_above_temp_boundary(candidate: Path, temp_boundary: Path | None) -> bool:
    """Return True if *candidate* is the OS temp dir or an ancestor of it.
 
    FS-560 / Plan 151 T6: root discovery must never adopt a project root at
    or above ``tempfile.gettempdir()``. A stray ``.option_c/`` (or other)
    root marker at the temp root would otherwise let the walk-up ESCAPE a
    per-test tmp sandbox and run git-mutating operations at the temp root -
    the reproducible environment-poisoning loop diagnosed in Plan 151 T3
    (a marker at ``%TEMP%\\.option_c`` fabricated 14 oc_chat + 17 oct false
    failures by git-initialising ``%TEMP%``). Markers STRICTLY BELOW the
    temp boundary - legitimate pytest ``tmp_path`` projects, which always
    live under a ``pytest-*`` subdir of the temp root - are unaffected.
 
    Never raises: an unresolvable path is treated as "not above the
    boundary" so discovery degrades to its pre-fix behaviour rather than
    failing closed on an IO error.
    """
    if temp_boundary is None:
        return False
    try:
        candidate_r = candidate.resolve()
        boundary_r = temp_boundary.resolve()
    except OSError:
        return False
    if candidate_r == boundary_r:
        return True
    try:
        boundary_r.relative_to(candidate_r)
    except ValueError:
        return False
    return True
 
 
def find_project_root(start: Path) -> Path:
    # No _dbg here on purpose: OctGroup.invoke calls this to build the
    # timing sample BEFORE the group callback runs oc_diagnostics.init(),
    # so a call at this seam warns "called before init()" on every single
    # oct command. The module reports at its containment seam instead,
    # which runs after the CLI is initialised.
    current = start.resolve()
    workspace_root: Path | None = None
    # FS-560: resolve the temp boundary once per walk so a stray marker at
    # or above ``%TEMP%`` cannot be adopted as a project root (Plan 151 T6).
    try:
        temp_boundary: Path | None = Path(tempfile.gettempdir())
    except Exception:  # pragma: no cover - gettempdir is effectively total
        temp_boundary = None
    # The sandbox-escape hazard exists ONLY when the walk ORIGINATES inside
    # the OS temp dir (a per-test tmp sandbox that could escape upward to a
    # stray marker at/above ``%TEMP%``). When ``start`` is outside the temp
    # dir the bound must NOT apply - otherwise a project whose ``TMPDIR`` is a
    # SUBDIRECTORY of itself (e.g. ``TMPDIR=<root>/logs``, as oct's own tool
    # runner sets) would have its own root rejected as an "ancestor of the
    # temp dir". (Plan 151 T6 self-fix: the first form over-rejected.)
    start_in_temp = (
        temp_boundary is not None
        and is_within_project_root(current, temp_boundary)
    )
    for parent in [current] + list(current.parents):
        # FS-560: never adopt (or record as a fallback) a candidate at or
        # above the OS temp boundary - the Plan 151 T3 poisoning cure - but
        # only when the walk started inside the temp sandbox.
        if start_in_temp and _at_or_above_temp_boundary(parent, temp_boundary):
            continue
 
        # 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).
    """
    func = "validate_path_containment"
    _dbg("OCT-CORE", func, f"containment check for {path} (allow_outside={allow_outside})", 3)
    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