pyrepowiki-cli 0.1.0__py3-none-any.whl

repowiki/shared/output.py

@@ -0,0 +1,204 @@
+"""Output formatting for CLI results."""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from contextlib import contextmanager
+from typing import Iterator
+
+from rich.console import Console
+from rich.markdown import Markdown
+
+from repowiki.shared.model import Answer, Reference, SourceFile
+
+_PAGE_DELIMITER = re.compile(r"^# Page: (.*)$", re.MULTILINE)
+_DETAILS_TAG = re.compile(r"</?details[^>]*>", re.IGNORECASE)
+_SUMMARY_TAG = re.compile(r"<summary[^>]*>(.*?)</summary>", re.IGNORECASE | re.DOTALL)
+
+
+def format_header(service: str, repo: str, command: str) -> str:
+    """Return the Markdown header line identifying a result."""
+    return f"## {service}: {repo} ({command})"
+
+
+def format_result(service: str, repo: str, command: str, text: str) -> str:
+    """Wrap result text in a Markdown header, trimming surrounding whitespace."""
+    return f"{format_header(service, repo, command)}\n\n{text.strip()}"
+
+
+def format_json(repo: str, command: str, **fields: object) -> str:
+    """Return a machine-readable JSON envelope for a result."""
+    return json.dumps(
+        {"repo": repo, "command": command, **fields},
+        indent=2,
+        ensure_ascii=False,
+    )
+
+
+def format_error_json(kind: str, message: str) -> str:
+    """Return a single-line JSON error object."""
+    return json.dumps({"error": message, "kind": kind}, ensure_ascii=False)
+
+
+def format_command_json(command: str, **fields: object) -> str:
+    """Return a JSON envelope without a repo field (for management commands)."""
+    return json.dumps({"command": command, **fields}, indent=2, ensure_ascii=False)
+
+
+def list_page_titles(text: str) -> list[str]:
+    """Return page titles found after each '# Page:' delimiter."""
+    return [m.group(1).strip() for m in _PAGE_DELIMITER.finditer(text)]
+
+
+def split_pages(text: str) -> list[tuple[str, str]]:
+    """Split markdown on each ``# Page:`` delimiter into ``(title, content)``.
+
+    Content with no delimiter is returned as a single ``("Overview", text)`` page.
+    """
+    matches = list(_PAGE_DELIMITER.finditer(text))
+    if not matches:
+        return [("Overview", text.strip())]
+    pages: list[tuple[str, str]] = []
+    for i, m in enumerate(matches):
+        title = m.group(1).strip()
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
+        pages.append((title, text[m.end():end].strip()))
+    return pages
+
+
+def filter_page(text: str, title: str) -> str:
+    """Return the content of the page whose title matches (case-insensitive exact).
+
+    Raises ValueError if no page matches.
+    """
+    matches = list(_PAGE_DELIMITER.finditer(text))
+    target = title.strip().lower()
+    available = []
+    for i, m in enumerate(matches):
+        page_title = m.group(1).strip()
+        available.append(page_title)
+        if page_title.lower() == target:
+            end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
+            return text[m.end() : end].strip()
+    listing = "\n".join(f"  - {t}" for t in available) or "  - (none)"
+    raise ValueError(f"Page '{title}' not found. Available pages:\n{listing}")
+
+
+def _prepare_markdown(text: str) -> str:
+    """Convert HTML that rich's Markdown renderer would silently drop."""
+    text = _DETAILS_TAG.sub("", text)
+    text = _SUMMARY_TAG.sub(lambda m: f"**{m.group(1).strip()}**", text)
+    return text
+
+
+def render_markdown(text: str) -> None:
+    """Render Markdown text to the terminal via rich."""
+    Console().print(Markdown(_prepare_markdown(text)))
+
+
+@contextmanager
+def status(message: str) -> Iterator[None]:
+    """Show a spinner on stderr while a slow call runs.
+
+    No-op when stderr is not a terminal, so piped output and tests stay clean.
+    """
+    if not sys.stderr.isatty():
+        yield
+        return
+    with Console(stderr=True).status(message):
+        yield
+
+
+def _clean_path(file_path: str) -> str:
+    """Strip a leading 'Repo owner/repo: ' prefix from a reference path."""
+    if ": " in file_path:
+        return file_path.split(": ", 1)[1]
+    return file_path
+
+
+def _range_label(path: str, start: int | None, end: int | None) -> str:
+    """Format a path with its line range, omitting the range when absent.
+
+    The reverse API uses ``None`` or ``0`` to mean "no specific lines", so
+    either renders as just the path.
+    """
+    if not start and not end:
+        return path
+    return f"{path}:{start}-{end}"
+
+
+def _render_slice(ref: Reference, sources: list[SourceFile]) -> str | None:
+    path = _clean_path(ref.file_path)
+    src = next((s for s in sources if s.path == path), None)
+    if src is None:
+        return None
+    lines = src.content.split("\n")
+    start = ref.range_start if ref.range_start else 1
+    end = ref.range_end if ref.range_end else len(lines)
+    lo = max(0, start - 1)
+    hi = min(len(lines), end)
+    numbered = "\n".join(f"{n:4d} {lines[n - 1]}" for n in range(lo + 1, hi + 1))
+    return f"```\n{_range_label(path, ref.range_start, ref.range_end)}\n{numbered}\n```"
+
+
+def _format_sources(references: list[Reference], sources: list[SourceFile], show_sources: bool) -> str:
+    lines = ["## Sources", ""]
+    for i, ref in enumerate(references, 1):
+        path = _clean_path(ref.file_path)
+        lines.append(f"{i}. {_range_label(path, ref.range_start, ref.range_end)}")
+        if show_sources:
+            slice_text = _render_slice(ref, sources)
+            if slice_text:
+                lines.extend(["", slice_text])
+    return "\n".join(lines)
+
+
+def format_answer(answer: Answer, *, show_sources: bool = False) -> str:
+    """Render an Answer as Markdown (no outer header)."""
+    body = answer.body
+    parts = [body.strip()]
+    if answer.summary:
+        parts.append(f"## Summary\n\n{answer.summary.strip()}")
+    if answer.references:
+        parts.append(_format_sources(answer.references, answer.sources, show_sources))
+    return "\n\n".join(parts)
+
+
+def format_answer_tail(answer: Answer, *, show_sources: bool = False) -> str:
+    """Render an Answer's summary and sources (no body) for streamed output."""
+    parts = []
+    if answer.summary:
+        parts.append(f"## Summary\n\n{answer.summary.strip()}")
+    if answer.references:
+        parts.append(_format_sources(answer.references, answer.sources, show_sources))
+    return "\n\n".join(parts)
+
+
+def format_list(result: dict) -> str:
+    """Render a list_public_indexes result as one line per indexed repo."""
+    indices = result.get("indices") or []
+    if not indices:
+        return "No matching indexed repos."
+    lines = []
+    for entry in indices:
+        repo = entry.get("repo_name", "")
+        bits = []
+        if entry.get("last_modified"):
+            bits.append(entry["last_modified"])
+        if entry.get("language"):
+            bits.append(entry["language"])
+        if entry.get("stargazers_count") is not None:
+            bits.append(f"{entry['stargazers_count']} stars")
+        suffix = f" ({', '.join(bits)})" if bits else ""
+        lines.append(f"- {repo}{suffix}")
+    return "\n".join(lines)
+
+
+def format_status(repo: str, result: dict) -> str:
+    return f"{repo}: {result.get('status', 'unknown')}"
+
+
+def format_warm(repo: str, result: dict) -> str:
+    return f"warmed {repo} ({result.get('status', 'OK')})"

repowiki/shared/repo.py

@@ -0,0 +1,45 @@
+"""Repository name normalization and validation."""
+
+from __future__ import annotations
+
+
+def normalize_repo(raw: str) -> str:
+    """Normalize a repo reference to ``owner/repo`` form.
+
+    Accepts ``owner/repo``, ``github.com/owner/repo``, and full GitHub URLs
+    (optionally with a trailing path such as ``/tree/main`` or a ``.git``
+    suffix). Raises ``ValueError`` for anything that is not a well-formed
+    repo reference.
+    """
+    value = raw.strip()
+    if not value:
+        raise ValueError("repository reference is empty")
+
+    for scheme in ("https://", "http://"):
+        if value.lower().startswith(scheme):
+            value = value[len(scheme):]
+            break
+
+    lower = value.lower()
+    if lower.startswith("www.github.com/"):
+        value = value[len("www.github.com/"):]
+    elif lower.startswith("github.com/"):
+        value = value[len("github.com/"):]
+
+    segments = [seg for seg in value.split("/") if seg]
+    if len(segments) < 2:
+        raise ValueError(
+            f"invalid repository reference: '{raw}'. "
+            "Expected owner/repo, github.com/owner/repo, or a GitHub URL."
+        )
+
+    owner, repo = segments[0], segments[1]
+    if repo.endswith(".git"):
+        repo = repo[:-4]
+
+    if not owner or not repo:
+        raise ValueError(f"invalid repository reference: '{raw}'")
+    if any(" " in part or "\t" in part for part in (owner, repo)):
+        raise ValueError(f"invalid repository reference: '{raw}'")
+
+    return f"{owner}/{repo}"

repowiki/shared/save.py

@@ -0,0 +1,27 @@
+"""Persist ask Q&A records to Markdown files."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+
+def default_save_path(repo: str) -> str:
+    """Return an auto-generated Markdown filename for a repo's Q&A session."""
+    slug = repo.replace("/", "-")
+    stamp = datetime.now().strftime("%Y%m%d%H%M%S")
+    return f"repowiki-{slug}_{stamp}.md"
+
+
+def append_entry(path: str, repo: str, question: str, answer: str) -> None:
+    """Append a single Q&A record to *path*, creating parent directories."""
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M")
+    entry = (
+        f"# {repo} · {timestamp}\n\n"
+        f"> **Q:** {question}\n\n"
+        f"{answer.strip()}\n\n"
+        f"---\n\n"
+    )
+    Path(path).parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "a", encoding="utf-8") as fh:
+        fh.write(entry)