surf-cli 0.7.0__py3-none-any.whl

surf/logic.py

@@ -0,0 +1,557 @@
+# logic.py
+"""Pure heading parse and extract. No Path, no exists, no print."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from urllib.parse import unquote
+
+from surf.models import (
+    ByteCount,
+    CharOffset,
+    CliTarget,
+    ClosedSpan,
+    Delimiter,
+    ExtractedOutline,
+    ExtractedSection,
+    FileRef,
+    FrontmatterSplit,
+    HeadingLevel,
+    HeadingLineCount,
+    HeadingPath,
+    HeadingPathRemainder,
+    HeadingRecord,
+    HeadingText,
+    LineCount,
+    LineIndex,
+    OutlineLevel,
+    OutlinePageSpan,
+    OutlineRecord,
+    PageCount,
+    PageIndex,
+    ParsedLink,
+    PdfDocument,
+    RenderedBody,
+    ScanBuffer,
+    TexCommand,
+    TexEnvironment,
+    TexIncludeCommand,
+    TexIncludeRelPath,
+)
+
+_HEADING_RE = re.compile(r"^(#{1,6})\s+(.+)$")
+_TEX_LEVEL: Mapping[TexCommand, HeadingLevel] = {
+    TexCommand.PART: HeadingLevel(1),
+    TexCommand.CHAPTER: HeadingLevel(2),
+    TexCommand.SECTION: HeadingLevel(3),
+    TexCommand.SUBSECTION: HeadingLevel(4),
+    TexCommand.SUBSUBSECTION: HeadingLevel(5),
+    TexCommand.PARAGRAPH: HeadingLevel(6),
+    TexCommand.SUBPARAGRAPH: HeadingLevel(7),
+}
+_TEX_COMMAND_BY_WORD: Mapping[str, TexCommand] = {command.value: command for command in TexCommand}
+_TEX_INCLUDE_BY_WORD: Mapping[str, TexIncludeCommand] = {
+    command.value: command for command in TexIncludeCommand
+}
+_TEX_CONTROL_WORD_RE = re.compile(r"^\s*\\([A-Za-z]+)")
+_TEX_UNBRACED_INCLUDE_STOP = frozenset(" \t%")
+
+
+def parse_heading_path(remainder: HeadingPathRemainder) -> HeadingPath | None:
+    segments = tuple(HeadingText(part.strip()) for part in remainder.split("#") if part.strip())
+    if not segments:
+        return None
+    return HeadingPath(segments=segments)
+
+
+def parse_link(target: CliTarget) -> ParsedLink:
+    """Parse a wikilink, markdown link, or plain path#heading into a ParsedLink.
+
+    The first `#` splits file ref from heading-path remainder.
+    """
+    m = re.match(r"^\[\[([^|\]]+?)(?:\|[^\]]+)?\]\]$", target)
+    if m:
+        inner = m.group(1)
+        if "#" in inner:
+            raw_path, remainder = inner.split("#", 1)
+            file_ref = FileRef(raw_path.strip()) if raw_path.strip() else None
+            return ParsedLink(
+                file_ref=file_ref,
+                heading_path=parse_heading_path(HeadingPathRemainder(remainder)),
+            )
+        stripped = inner.strip()
+        return ParsedLink(file_ref=FileRef(stripped) if stripped else None, heading_path=None)
+
+    m = re.match(r"^\[([^\]]*)\]\((.+?)\)$", target)
+    if m:
+        raw = unquote(m.group(2))
+        if "#" in raw:
+            raw_path, remainder = raw.split("#", 1)
+            file_ref = FileRef(raw_path.strip()) if raw_path.strip() else None
+            return ParsedLink(
+                file_ref=file_ref,
+                heading_path=parse_heading_path(HeadingPathRemainder(remainder)),
+            )
+        stripped = raw.strip()
+        return ParsedLink(file_ref=FileRef(stripped) if stripped else None, heading_path=None)
+
+    if "#" in target:
+        raw_path, remainder = target.split("#", 1)
+        file_ref = FileRef(raw_path.strip()) if raw_path.strip() else None
+        return ParsedLink(
+            file_ref=file_ref,
+            heading_path=parse_heading_path(HeadingPathRemainder(remainder)),
+        )
+
+    stripped = target.strip()
+    return ParsedLink(file_ref=FileRef(stripped) if stripped else None, heading_path=None)
+
+
+def parse_headings(lines: Sequence[str]) -> tuple[HeadingRecord, ...]:
+    records: list[HeadingRecord] = []
+    for i, line in enumerate(lines):
+        m = _HEADING_RE.match(line)
+        if m:
+            records.append(
+                HeadingRecord(
+                    level=HeadingLevel(len(m.group(1))),
+                    line_index=LineIndex(i),
+                    title_end_line=LineIndex(i),
+                    text=HeadingText(m.group(2).strip()),
+                )
+            )
+    return tuple(records)
+
+
+def _delimited_span_end(
+    buffer: ScanBuffer,
+    start: CharOffset,
+    opener: Delimiter,
+    closer: Delimiter,
+) -> CharOffset | None:
+    if start >= len(buffer) or buffer[start] != opener:
+        return None
+    depth = 0
+    for i in range(start, len(buffer)):
+        char = buffer[i]
+        if char == opener:
+            depth += 1
+        elif char == closer:
+            depth -= 1
+            if depth == 0:
+                return CharOffset(i + 1)
+    return None
+
+
+def _skip_horizontal(buffer: ScanBuffer, pos: CharOffset) -> CharOffset:
+    i = int(pos)
+    while i < len(buffer) and buffer[i] in " \t":
+        i += 1
+    return CharOffset(i)
+
+
+def _extend_until_closed(
+    lines: Sequence[str],
+    start_line: LineIndex,
+    rest: ScanBuffer,
+    pos: CharOffset,
+    opener: Delimiter,
+    closer: Delimiter,
+) -> ClosedSpan | None:
+    end = _delimited_span_end(rest, pos, opener, closer)
+    if end is not None:
+        return ClosedSpan(buffer=rest, end=end, last_line=start_line)
+    for j in range(start_line + 1, len(lines)):
+        rest = ScanBuffer(rest + "\n" + lines[j])
+        end = _delimited_span_end(rest, pos, opener, closer)
+        if end is not None:
+            return ClosedSpan(buffer=rest, end=end, last_line=LineIndex(j))
+    return None
+
+
+def _parse_tex_heading_at(
+    lines: Sequence[str], line_index: LineIndex
+) -> tuple[HeadingRecord, LineIndex] | None:
+    line = lines[line_index]
+    if line_index == 0:
+        line = line.lstrip("\ufeff")
+    m = _TEX_CONTROL_WORD_RE.match(line)
+    if m is None:
+        return None
+    command = _TEX_COMMAND_BY_WORD.get(m.group(1))
+    if command is None:
+        return _parse_tex_abstract_at(line_index, line, m)
+    rest = ScanBuffer(line[m.end() :])
+    pos = CharOffset(0)
+    if pos < len(rest) and rest[pos] == "*":
+        pos = CharOffset(pos + 1)
+    pos = _skip_horizontal(rest, pos)
+    if pos < len(rest) and rest[pos] == "[":
+        extended = _extend_until_closed(
+            lines, line_index, rest, pos, Delimiter("["), Delimiter("]")
+        )
+        if extended is None:
+            return None
+        rest = extended.buffer
+        pos = _skip_horizontal(extended.buffer, extended.end)
+    if pos >= len(rest) or rest[pos] != "{":
+        return None
+    extended = _extend_until_closed(lines, line_index, rest, pos, Delimiter("{"), Delimiter("}"))
+    if extended is None:
+        return None
+    rest = extended.buffer
+    brace_end = extended.end
+    title = re.sub(r"\s+", " ", rest[pos + 1 : brace_end - 1]).strip()
+    if not title:
+        return None
+    return (
+        HeadingRecord(
+            level=_TEX_LEVEL[command],
+            line_index=line_index,
+            title_end_line=extended.last_line,
+            text=HeadingText(title),
+        ),
+        extended.last_line,
+    )
+
+
+def _parse_tex_abstract_at(
+    line_index: LineIndex,
+    line: str,
+    matched: re.Match[str],
+) -> tuple[HeadingRecord, LineIndex] | None:
+    if matched.group(1) != "begin":
+        return None
+    rest = ScanBuffer(line[matched.end() :])
+    pos = _skip_horizontal(rest, CharOffset(0))
+    if pos >= len(rest) or rest[pos] != "{":
+        return None
+    end = _delimited_span_end(rest, pos, Delimiter("{"), Delimiter("}"))
+    if end is None:
+        return None
+    if rest[pos + 1 : end - 1].strip() != TexEnvironment.ABSTRACT:
+        return None
+    return (
+        HeadingRecord(
+            level=_TEX_LEVEL[TexCommand.SECTION],
+            line_index=line_index,
+            title_end_line=line_index,
+            text=HeadingText(TexEnvironment.ABSTRACT),
+        ),
+        line_index,
+    )
+
+
+def _normalized_tex_include(raw: str) -> TexIncludeRelPath | None:
+    path = raw.strip()
+    if not path or path.startswith(("/", "~", "|")):
+        return None
+    if any(char in path for char in "\\{}|#"):
+        return None
+    segments = path.split("/")
+    if any(segment in ("", "..") for segment in segments):
+        return None
+    name = segments[-1]
+    if "." in name:
+        suffix = name.rsplit(".", 1)[1]
+        if suffix.lower() != "tex":
+            return None
+    else:
+        path = f"{path}.tex"
+    return TexIncludeRelPath(path)
+
+
+def tex_include_path(line: str) -> TexIncludeRelPath | None:
+    """Return a static \\input/\\include relative path, or None.
+
+    Comments, graphics, shell pipes, macros, absolute paths, and non-.tex
+    suffixes are not includes. A missing suffix becomes .tex.
+    """
+    if line.lstrip(" \t").startswith("%"):
+        return None
+    matched = _TEX_CONTROL_WORD_RE.match(line)
+    if matched is None:
+        return None
+    command = _TEX_INCLUDE_BY_WORD.get(matched.group(1))
+    if command is None:
+        return None
+    rest = ScanBuffer(line[matched.end() :])
+    pos = _skip_horizontal(rest, CharOffset(0))
+    if pos < len(rest) and rest[pos] == "{":
+        end = _delimited_span_end(rest, pos, Delimiter("{"), Delimiter("}"))
+        if end is None:
+            return None
+        return _normalized_tex_include(rest[pos + 1 : end - 1])
+    if command is TexIncludeCommand.INCLUDE:
+        return None
+    if pos >= len(rest):
+        return None
+    stop = int(pos)
+    while stop < len(rest) and rest[stop] not in _TEX_UNBRACED_INCLUDE_STOP:
+        stop += 1
+    return _normalized_tex_include(rest[pos:stop])
+
+
+def relative_heading_levels(
+    headings: tuple[HeadingRecord, ...],
+) -> tuple[HeadingRecord, ...]:
+    """Shift ranks so the shallowest heading in the file is level 1.
+
+    LaTeX command ranks stay on the 1-7 map (part=1 ... subparagraph=7).
+    An article whose top command is \\section then lists at --level 1, matching
+    markdown's top-of-tree numbering. Gaps are preserved.
+    """
+    if not headings:
+        return headings
+    origin = min(int(record.level) for record in headings)
+    if origin <= 1:
+        return headings
+    delta = origin - 1
+    return tuple(
+        HeadingRecord(
+            level=HeadingLevel(int(record.level) - delta),
+            line_index=record.line_index,
+            title_end_line=record.title_end_line,
+            text=record.text,
+        )
+        for record in headings
+    )
+
+
+def parse_tex_headings(lines: Sequence[str]) -> tuple[HeadingRecord, ...]:
+    records: list[HeadingRecord] = []
+    i = LineIndex(0)
+    while i < len(lines):
+        parsed = _parse_tex_heading_at(lines, i)
+        if parsed is None:
+            i = LineIndex(i + 1)
+            continue
+        record, consumed_through = parsed
+        records.append(record)
+        i = LineIndex(consumed_through + 1)
+    return relative_heading_levels(tuple(records))
+
+
+def split_frontmatter(lines: Sequence[str]) -> FrontmatterSplit:
+    body = tuple(lines)
+    if not body or body[0].rstrip() != "---":
+        return FrontmatterSplit(frontmatter=None, body=body)
+    for i in range(1, len(body)):
+        if body[i].rstrip() == "---":
+            return FrontmatterSplit(frontmatter=body[: i + 1], body=body[i + 1 :])
+    return FrontmatterSplit(frontmatter=None, body=body)
+
+
+def extract_section(
+    lines: Sequence[str],
+    heading_path: HeadingPath,
+    *,
+    level_filter: HeadingLevel | None = None,
+    headings: tuple[HeadingRecord, ...] | None = None,
+) -> ExtractedSection | None:
+    """Extract by heading path. Same containment walk as the pre-split module.
+
+    level_filter is an exact rank, so same-named headings at different
+    levels stay distinguishable.
+    """
+    if headings is None:
+        headings = parse_headings(lines)
+    segments = heading_path.segments
+    if not segments:
+        return None
+
+    def section_end(start_idx: LineIndex, start_level: HeadingLevel) -> int:
+        for record in headings:
+            if record.line_index > start_idx and record.level <= start_level:
+                return int(record.line_index)
+        return len(lines)
+
+    bound_start = -1
+    bound_end = len(lines)
+    prev_level = HeadingLevel(0)
+    match_idx: LineIndex | None = None
+    match_level: HeadingLevel | None = None
+    match_title_end: LineIndex | None = None
+
+    for i, segment in enumerate(segments):
+        needle = str(segment).lower()
+        is_last = i == len(segments) - 1
+        found: HeadingRecord | None = None
+        for record in headings:
+            if record.line_index <= bound_start or record.line_index >= bound_end:
+                continue
+            if i > 0 and record.level <= prev_level:
+                continue
+            if str(record.text).lower().strip() != needle:
+                continue
+            if is_last and level_filter is not None and record.level != level_filter:
+                continue
+            found = record
+            break
+        if found is None:
+            return None
+        match_level = found.level
+        match_idx = found.line_index
+        match_title_end = found.title_end_line
+        bound_start = int(match_idx)
+        prev_level = match_level
+        bound_end = section_end(match_idx, match_level)
+
+    if match_idx is None or match_level is None or match_title_end is None:
+        return None
+    return ExtractedSection(
+        level=match_level,
+        lines=tuple(lines[int(match_idx) : bound_end]),
+        heading_line_count=HeadingLineCount(int(match_title_end) - int(match_idx) + 1),
+    )
+
+
+def match_outline_span(
+    outline: Sequence[OutlineRecord],
+    heading_path: HeadingPath,
+    *,
+    level_filter: OutlineLevel | None = None,
+) -> OutlinePageSpan | None:
+    """Dest-to-next-dest page bounds. Does not read page text."""
+    segments = heading_path.segments
+    if not segments:
+        return None
+
+    def containment_end(start_idx: int, start_level: OutlineLevel) -> int:
+        for j in range(start_idx + 1, len(outline)):
+            if outline[j].level <= start_level:
+                return j
+        return len(outline)
+
+    def next_dest_page(after_idx: int) -> PageIndex | None:
+        for j in range(after_idx + 1, len(outline)):
+            page = outline[j].page_index
+            if page is not None:
+                return page
+        return None
+
+    bound_start = -1
+    bound_end = len(outline)
+    prev_level = OutlineLevel(0)
+    match_idx: int | None = None
+    match_level: OutlineLevel | None = None
+
+    for i, segment in enumerate(segments):
+        target = str(segment).lower()
+        is_last = i == len(segments) - 1
+        found: OutlineRecord | None = None
+        found_idx: int | None = None
+        for j, record in enumerate(outline):
+            if j <= bound_start or j >= bound_end:
+                continue
+            if i > 0 and record.level <= prev_level:
+                continue
+            if str(record.title).lower().strip() != target:
+                continue
+            if is_last and level_filter is not None and record.level != level_filter:
+                continue
+            found = record
+            found_idx = j
+            break
+        if found is None or found_idx is None:
+            return None
+        match_level = found.level
+        match_idx = found_idx
+        bound_start = match_idx
+        prev_level = match_level
+        bound_end = containment_end(match_idx, match_level)
+
+    if match_idx is None or match_level is None:
+        return None
+    return OutlinePageSpan(
+        level=match_level,
+        start_page=outline[match_idx].page_index,
+        end_page=next_dest_page(match_idx),
+    )
+
+
+def exclusive_page_end(span: OutlinePageSpan) -> PageIndex | None:
+    """Half-open end page. Same-page next dest includes the dest page."""
+    if span.start_page is None:
+        return None
+    if span.end_page is None:
+        return None
+    if int(span.end_page) <= int(span.start_page):
+        return PageIndex(int(span.start_page) + 1)
+    return span.end_page
+
+
+def extract_outline_section(
+    document: PdfDocument,
+    heading_path: HeadingPath,
+    *,
+    level_filter: OutlineLevel | None = None,
+) -> ExtractedOutline | None:
+    """Slice in-memory page text for a dest-to-next-dest span."""
+    span = match_outline_span(document.outline, heading_path, level_filter=level_filter)
+    if span is None:
+        return None
+    if span.start_page is None:
+        return ExtractedOutline(level=span.level, pages=())
+    start = int(span.start_page)
+    end = exclusive_page_end(span)
+    if end is None:
+        page_slice = document.pages[start:]
+    else:
+        page_slice = document.pages[start : int(end)]
+    return ExtractedOutline(level=span.level, pages=tuple(page_slice))
+
+
+def format_empty_index(*, line_count: LineCount, byte_count: ByteCount) -> RenderedBody:
+    return RenderedBody(f"no structural index\nlines: {int(line_count)}\nbytes: {int(byte_count)}")
+
+
+def format_empty_pdf_index(*, page_count: PageCount, byte_count: ByteCount) -> RenderedBody:
+    return RenderedBody(f"no structural index\npages: {int(page_count)}\nbytes: {int(byte_count)}")
+
+
+def format_heading_list(
+    lines: Sequence[str],
+    *,
+    headings: tuple[HeadingRecord, ...] | None = None,
+    level_filter: HeadingLevel | None = None,
+) -> RenderedBody:
+    """List headings. level_filter is a maximum rank (1 through N)."""
+    records = parse_headings(lines) if headings is None else headings
+    if level_filter is not None:
+        records = tuple(record for record in records if record.level <= level_filter)
+    out: list[str] = []
+    for record in records:
+        indent = "  " * (int(record.level) - 1)
+        out.append(f"{indent}- {record.text}")
+    return RenderedBody("\n".join(out))
+
+
+def format_outline_list(
+    outline: Sequence[OutlineRecord],
+    *,
+    level_filter: OutlineLevel | None = None,
+) -> RenderedBody:
+    """List outline items. level_filter is a maximum rank (1 through N)."""
+    records = outline
+    if level_filter is not None:
+        records = tuple(record for record in records if record.level <= level_filter)
+    out: list[str] = []
+    for record in records:
+        indent = "  " * (int(record.level) - 1)
+        out.append(f"{indent}- {record.title}")
+    return RenderedBody("\n".join(out))
+
+
+def format_file_index(
+    split: FrontmatterSplit,
+    *,
+    headings: tuple[HeadingRecord, ...] | None = None,
+    level_filter: HeadingLevel | None = None,
+) -> RenderedBody:
+    frontmatter = "\n".join(split.frontmatter) if split.frontmatter is not None else ""
+    heading_list = format_heading_list(split.body, headings=headings, level_filter=level_filter)
+    if frontmatter and heading_list:
+        return RenderedBody(f"{frontmatter}\n\n{heading_list}")
+    return RenderedBody(frontmatter or heading_list)

surf/models.py

@@ -0,0 +1,148 @@
+# models.py
+"""Immutable domain values for surf. No I/O."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import NewType
+
+HeadingText = NewType("HeadingText", str)
+FileRef = NewType("FileRef", str)
+HeadingLevel = NewType("HeadingLevel", int)
+OutlineLevel = NewType("OutlineLevel", int)
+LineIndex = NewType("LineIndex", int)
+PageIndex = NewType("PageIndex", int)
+ScanBuffer = NewType("ScanBuffer", str)
+CharOffset = NewType("CharOffset", int)
+Delimiter = NewType("Delimiter", str)
+HeadingLineCount = NewType("HeadingLineCount", int)
+CliTarget = NewType("CliTarget", str)
+HeadingPathRemainder = NewType("HeadingPathRemainder", str)
+RenderedBody = NewType("RenderedBody", str)
+ErrorMessage = NewType("ErrorMessage", str)
+ExitCode = NewType("ExitCode", int)
+TexIncludeRelPath = NewType("TexIncludeRelPath", str)
+LineCount = NewType("LineCount", int)
+ByteCount = NewType("ByteCount", int)
+PageCount = NewType("PageCount", int)
+
+type DocumentLines = tuple[str, ...]
+type PageText = str
+
+
+class TexCommand(StrEnum):
+    PART = "part"
+    CHAPTER = "chapter"
+    SECTION = "section"
+    SUBSECTION = "subsection"
+    SUBSUBSECTION = "subsubsection"
+    PARAGRAPH = "paragraph"
+    SUBPARAGRAPH = "subparagraph"
+
+
+class TexIncludeCommand(StrEnum):
+    INPUT = "input"
+    INCLUDE = "include"
+
+
+class TexEnvironment(StrEnum):
+    ABSTRACT = "abstract"
+
+
+@dataclass(frozen=True, slots=True)
+class HeadingPath:
+    segments: tuple[HeadingText, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class HeadingRecord:
+    level: HeadingLevel
+    line_index: LineIndex
+    title_end_line: LineIndex
+    text: HeadingText
+
+
+@dataclass(frozen=True, slots=True)
+class ClosedSpan:
+    buffer: ScanBuffer
+    end: CharOffset
+    last_line: LineIndex
+
+
+@dataclass(frozen=True, slots=True)
+class OutlineRecord:
+    level: OutlineLevel
+    title: HeadingText
+    page_index: PageIndex | None
+    top: float | None
+
+
+@dataclass(frozen=True, slots=True)
+class PdfDocument:
+    outline: tuple[OutlineRecord, ...]
+    pages: tuple[PageText, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class PdfCatalog:
+    outline: tuple[OutlineRecord, ...]
+    page_count: PageCount
+    byte_count: ByteCount
+
+
+@dataclass(frozen=True, slots=True)
+class OutlinePageSpan:
+    """Dest-to-next-dest page range. start_page None means found but no dest."""
+
+    level: OutlineLevel
+    start_page: PageIndex | None
+    end_page: PageIndex | None
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedLink:
+    file_ref: FileRef | None
+    heading_path: HeadingPath | None
+
+
+@dataclass(frozen=True, slots=True)
+class FrontmatterSplit:
+    frontmatter: DocumentLines | None
+    body: DocumentLines
+
+
+@dataclass(frozen=True, slots=True)
+class ExtractedSection:
+    level: HeadingLevel
+    lines: DocumentLines
+    heading_line_count: HeadingLineCount
+
+
+@dataclass(frozen=True, slots=True)
+class ExtractedOutline:
+    level: OutlineLevel
+    pages: tuple[PageText, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class CliOptions:
+    file_ref: FileRef | None
+    heading_path: HeadingPath | None
+    list_headings: bool
+    frontmatter_only: bool
+    full: bool
+    no_heading: bool
+    level_filter: int | None
+    output_ref: FileRef | None
+
+
+@dataclass(frozen=True, slots=True)
+class CliSuccess:
+    body: RenderedBody
+
+
+@dataclass(frozen=True, slots=True)
+class CliFailure:
+    message: ErrorMessage
+    exit_code: ExitCode