paths Namespace Reference

Functions
str	to_project_relative (Path path, Path project_root)

Detailed Description

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

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).

Function Documentation

to_project_relative()

str paths.to_project_relative	(	Path	path,
		Path	project_root )

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).

Definition at line 44 of file paths.py.