paths.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/core/paths.py
 
"""
Purpose
-------
Provide a single canonical helper for rendering filesystem paths in
user-facing output. OCT commands (``oct lint``, ``oct health``, ``oct
git check``, ...) must present paths as project-relative POSIX strings
so findings are portable across machines, cross-platform, and safe to
paste into tickets, CI logs, and patch files.
 
Responsibilities
----------------
- Convert an absolute :class:`pathlib.Path` into a project-relative
  POSIX string when the path is inside *project_root*.
- Fall back to an absolute POSIX string when *path* is outside the
  project (e.g. a stdlib file surfaced by a traceback, a user-supplied
  lint target under ``C:\\`` or ``/tmp``).
 
Diagnostics
-----------
Domain: OCT-CORE
Levels:
    L2 - lifecycle
    L3 - semantic details
    L4 - each path relativisation, with its project root
 
Contracts
---------
- Never raises on valid ``Path`` input.
- Always returns forward slashes (POSIX), even on Windows.
- ``project_root`` must be an absolute, resolved path for the relative
  calculation to be correct; callers typically hand it straight from
  :class:`LinterContext.project_root` (already resolved at context
  construction).
 
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
"""
 
from __future__ import annotations
 
from pathlib import Path
from oct.core.diagnostics import _dbg
 
 
def to_project_relative(path: Path, project_root: Path) -> str:
    """Render *path* as a project-relative POSIX string.
 
    OI-533: standardises path output across linter, health, and git
    commands so findings never leak absolute machine paths into CI
    artifacts or pasted error reports.
 
    Parameters
    ----------
    path
        The file or directory to render. May be absolute or relative.
    project_root
        The project root; typically ``ctx.project_root``. Should be
        absolute and resolved so :meth:`~pathlib.Path.relative_to`
        computes the expected relative.
 
    Returns
    -------
    Project-relative POSIX string when *path* lives inside
    *project_root*; otherwise the absolute POSIX form of *path* (so
    out-of-tree paths remain unambiguous).
    """
    func = "to_project_relative"
    _dbg("OCT-CORE", func, f"relativising {path} against {project_root}", 4)
    try:
        return path.relative_to(project_root).as_posix()
    except ValueError:
        return path.as_posix()