parsing.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/core/parsing.py
 
"""
Purpose
-------
Provide shared Python-source parsing helpers:
 
- :func:`safe_parse` parses source text into an AST while capturing any
  ``SyntaxWarning`` diagnostics (so callers can surface them without
  letting them leak to stderr).
- :func:`header_boundary` (OI-509 / FS-505) returns the line index where
  file content begins, scanning at most the first 5 lines in the strict
  order shebang → encoding → file-identity comment → blank line. This
  replaces two drift-prone inline copies that previously existed in the
  linter and the formatter.
 
Responsibilities
----------------
- Parse Python source text into an AST tree.
- Capture ``SyntaxWarning`` (e.g. invalid escape sequences) as structured data.
- Locate the header/content boundary of an Option-C-formatted Python file
  using only the file's basename and (optionally) its expected identity
  comment, so both the linter (with full ``LinterContext``) and the
  formatter (with a lighter ``FormatterContext``) can share one code path.
 
Diagnostics
-----------
Domain: OCT-CORE
Levels:
    L2 - lifecycle
    L3 - semantic details
    L4 - deep tracing
 
Contracts
---------
- :func:`safe_parse` must not emit warnings to stderr; all warnings are
  returned as strings.
- :func:`safe_parse` must return ``None`` for the tree on ``SyntaxError``.
- :func:`header_boundary` must never raise; it returns an integer in
  ``[0, min(len(lines), 5)]``.
- :func:`header_boundary` must consume the trailing blank only if at
  least one header element was matched first.
 
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
"""
 
from __future__ import annotations
 
import ast
import re
import warnings
from pathlib import Path
from oct.core.diagnostics import _dbg
 
 
_ENCODING_RE = re.compile(r"#.*coding[:=]")
 
 
def safe_parse(text: str) -> tuple[ast.Module | None, list[str]]:
    """Parse Python source, capturing SyntaxWarnings instead of emitting to stderr.
 
    Returns (tree, warnings_list). tree is None on SyntaxError.
    """
    func = "safe_parse"
    _dbg("OCT-CORE", func, f"parsing {len(text)} chars", 4)
    with warnings.catch_warnings(record=True) as w:
        warnings.simplefilter("always", SyntaxWarning)
        try:
            tree = ast.parse(text)
        except SyntaxError:
            return None, []
 
    caught = [str(warning.message) for warning in w
              if issubclass(warning.category, SyntaxWarning)]
    return tree, caught
 
 
def header_boundary(
    lines: list[str],
    path: Path,
    expected_identity: str | None = None,
) -> int:
    """Return the line index where file content begins.
 
    Scans at most the first 5 lines of *lines*, in strict order:
    shebang → encoding → file-identity comment → blank line.
 
    Parameters
    ----------
    lines : list[str]
        Source file split by newlines (as returned by ``str.splitlines()``).
    path : Path
        The file's path; its basename is used as the fallback identity
        match when *expected_identity* is not provided.
    expected_identity : str | None, optional
        The exact expected file-identity comment (e.g.
        ``"# oct/core/parsing.py"``). When supplied the match is strict
        against this string; otherwise any ``"# ...<path.name>"`` line
        qualifies.
    """
    func = "header_boundary"
    _dbg("OCT-CORE", func, f"locating header boundary in {path}", 4)
    limit = min(len(lines), 5)
    i = 0
 
    # 1. Shebang (any flavour: python, python3, etc.)
    if i < limit and lines[i].strip().startswith("#!"):
        i += 1
 
    # 2. Encoding declaration (PEP 263)
    if i < limit and _ENCODING_RE.match(lines[i].strip()):
        i += 1
 
    # 3. File-identity comment - only if it references THIS file's name
    if i < limit:
        stripped = lines[i].strip()
        if expected_identity is not None:
            is_identity = (
                stripped == expected_identity
                or (stripped.startswith("# ") and stripped.endswith(path.name))
            )
        else:
            is_identity = (
                stripped.startswith("# ") and stripped.endswith(path.name)
            )
        if is_identity:
            i += 1
 
    # 4. Trailing blank line (only if at least one header element was found)
    if i > 0 and i < limit and lines[i].strip() == "":
        i += 1
 
    return i