docfriction 0.1.0__py3-none-any.whl

docfriction/__init__.py

@@ -0,0 +1,29 @@
+"""docfriction: automated friction logs for online documentation, scored with TypeSafe Jev."""
+
+from ._version import __version__
+from .evaluate import EvaluateOptions, Thresholds, evaluate_document
+from .fetch import FetchError, load_document
+from .jev import JevClient, JevError, MissingApiKeyError
+from .models import Document, Finding, FrictionLog, Segment, StepLog
+from .report import render_json, render_markdown
+from .segment import segment_markdown
+
+__all__ = [
+    "Document",
+    "EvaluateOptions",
+    "FetchError",
+    "Finding",
+    "FrictionLog",
+    "JevClient",
+    "JevError",
+    "MissingApiKeyError",
+    "Segment",
+    "StepLog",
+    "Thresholds",
+    "__version__",
+    "evaluate_document",
+    "load_document",
+    "render_json",
+    "render_markdown",
+    "segment_markdown",
+]

docfriction/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

docfriction/checks.py

@@ -0,0 +1,152 @@
+"""Deterministic checks that need no model. Jev is weak at counting and pattern
+matching, so anything a regex or an HTTP request can answer is done here."""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+import socket
+from collections.abc import Callable
+
+import httpx
+
+from ._version import __version__
+from .models import STATIC_SOURCE, Finding, Segment
+
+PLACEHOLDER_RE = re.compile(
+    r"YOUR_[A-Z0-9_]+"
+    r"|\{\{[^}]+\}\}"
+    r"|\bREPLACE[_ -]?ME\b"
+    r"|\bCHANGE[_ -]?ME\b"
+    r"|\bxxx+\b"
+    r"|\bTODO\b"
+)
+ANGLE_PLACEHOLDER_RE = re.compile(r"<[A-Za-z][\w-]*(?:[_-][\w-]+)*>")
+MARKUP_LANGUAGES = frozenset({"html", "xml", "jsx", "tsx", "vue", "svelte", "xhtml", "svg"})
+MIN_PROSE_CHARS = 40
+DEAD_LINK_RETRY_STATUSES = frozenset({400, 403, 405})
+DEFAULT_LINK_TIMEOUT_SECONDS = 10.0
+ALLOWED_LINK_SCHEMES = frozenset({"http", "https"})
+USER_AGENT = f"docfriction/{__version__} (+https://github.com/Cyvid7-Darus10/docfriction)"
+
+Resolver = Callable[[str], tuple[str, ...]]
+
+
+class BlockedHostError(httpx.RequestError):
+    """Raised by the link client when a URL points at a private or internal address."""
+
+
+def find_placeholders(segment: Segment) -> tuple[str, ...]:
+    found: list[str] = []
+    for block in segment.code_blocks:
+        found.extend(PLACEHOLDER_RE.findall(block.content))
+        if block.language not in MARKUP_LANGUAGES:
+            found.extend(ANGLE_PLACEHOLDER_RE.findall(block.content))
+    return tuple(sorted(set(found)))
+
+
+def static_findings(segment: Segment) -> tuple[Finding, ...]:
+    findings: list[Finding] = []
+    untagged = sum(1 for block in segment.code_blocks if not block.language)
+    if untagged:
+        findings.append(
+            Finding(
+                check="untagged_code_block",
+                source=STATIC_SOURCE,
+                detail=f"{untagged} code block(s) have no language tag, so readers cannot "
+                "tell shell from config or output",
+            )
+        )
+    if not segment.has_code and len(segment.prose) < MIN_PROSE_CHARS:
+        findings.append(
+            Finding(
+                check="stub_section",
+                source=STATIC_SOURCE,
+                detail="The heading has almost no content under it",
+            )
+        )
+    return tuple(findings)
+
+
+def ip_literal(host: str) -> tuple[str, ...]:
+    """The host itself if it is an IP address (IPv6 brackets stripped), else empty."""
+    try:
+        ipaddress.ip_address(host.strip("[]"))
+    except ValueError:
+        return ()
+    return (host.strip("[]"),)
+
+
+def resolve_host(host: str) -> tuple[str, ...]:
+    """All addresses a hostname resolves to via DNS."""
+    try:
+        infos = socket.getaddrinfo(host, None)
+    except socket.gaierror as exc:
+        raise BlockedHostError(f"{host} does not resolve") from exc
+    return tuple(dict.fromkeys(str(info[4][0]) for info in infos))
+
+
+def is_public_address(address: str) -> bool:
+    parsed = ipaddress.ip_address(address)
+    return not (
+        parsed.is_private
+        or parsed.is_loopback
+        or parsed.is_link_local
+        or parsed.is_multicast
+        or parsed.is_reserved
+        or parsed.is_unspecified
+    )
+
+
+def link_client(
+    *,
+    transport: httpx.BaseTransport | None = None,
+    timeout: float = DEFAULT_LINK_TIMEOUT_SECONDS,
+    allow_private_hosts: bool = False,
+    resolver: Resolver = resolve_host,
+) -> httpx.Client:
+    """One shared client for link checks. The request hook runs on every redirect hop,
+    so a public URL cannot bounce the checker into a private network."""
+
+    def guard(request: httpx.Request) -> None:
+        if request.url.scheme not in ALLOWED_LINK_SCHEMES:
+            raise BlockedHostError(f"{request.url} uses an unsupported scheme")
+        if allow_private_hosts:
+            return
+        host = request.url.host
+        addresses = ip_literal(host) or resolver(host)
+        if not all(is_public_address(address) for address in addresses):
+            raise BlockedHostError(f"{request.url} points at a private or internal address")
+
+    return httpx.Client(
+        follow_redirects=True,
+        headers={"User-Agent": USER_AGENT},
+        timeout=timeout,
+        transport=transport,
+        event_hooks={"request": [guard]},
+    )
+
+
+def check_links(urls: tuple[str, ...], client: httpx.Client) -> tuple[Finding, ...]:
+    results = (_check_link(client, url) for url in urls)
+    return tuple(finding for finding in results if finding is not None)
+
+
+def _check_link(client: httpx.Client, url: str) -> Finding | None:
+    try:
+        response = client.head(url)
+        if response.status_code in DEAD_LINK_RETRY_STATUSES:
+            # Some hosts reject HEAD; fetch headers only, never the body.
+            with client.stream("GET", url) as streamed:
+                response = streamed
+    except BlockedHostError as exc:
+        return Finding(check="blocked_link", source=STATIC_SOURCE, detail=str(exc))
+    except httpx.HTTPError as exc:
+        return _dead_link(f"{url} could not be reached ({type(exc).__name__})")
+    if response.status_code >= 400:
+        return _dead_link(f"{url} returned HTTP {response.status_code}")
+    return None
+
+
+def _dead_link(detail: str) -> Finding:
+    return Finding(check="dead_link", source=STATIC_SOURCE, detail=detail)

docfriction/cli.py

@@ -0,0 +1,106 @@
+"""Command-line entry point: docfriction <url-or-file> [options]."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from ._version import __version__
+from .evaluate import EvaluateOptions, evaluate_document
+from .fetch import FetchError, load_document
+from .jev import DEFAULT_MODEL, JevClient, JevError
+from .report import render_json, render_markdown
+from .segment import segment_markdown
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_THRESHOLD = 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="docfriction",
+        description="Write a friction log for a documentation page, scored step by step with Jev.",
+    )
+    parser.add_argument("source", help="URL of a docs page, or a local .md/.html file")
+    parser.add_argument("-o", "--out", type=Path, help="write the report here instead of stdout")
+    parser.add_argument("-f", "--format", choices=("md", "json"), default="md")
+    parser.add_argument("--model", default=DEFAULT_MODEL, help="Jev model id (default: jev-latest)")
+    parser.add_argument("--check-links", action="store_true", help="also HEAD every external link")
+    parser.add_argument(
+        "--allow-private-links",
+        action="store_true",
+        help="let --check-links request private, loopback, and link-local addresses",
+    )
+    parser.add_argument("--max-sections", type=int, help="only evaluate the first N sections")
+    parser.add_argument("--concurrency", type=int, default=4, help="parallel Jev calls")
+    parser.add_argument(
+        "--fail-on-severity",
+        type=float,
+        metavar="N",
+        help="exit 2 if any step's severity is at least N on the 0-3 scale",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="print the detected steps and exit without calling Jev (no API key needed)",
+    )
+    parser.add_argument("--version", action="version", version=f"docfriction {__version__}")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        document = load_document(args.source)
+    except FetchError as exc:
+        return _fail(str(exc))
+    if args.dry_run:
+        return _dry_run(document.markdown, document.title, args.max_sections)
+    options = EvaluateOptions(
+        check_links=args.check_links,
+        allow_private_links=args.allow_private_links,
+        max_sections=args.max_sections,
+        concurrency=args.concurrency,
+    )
+    try:
+        with JevClient(model=args.model) as client:
+            log = evaluate_document(document, client, options)
+    except JevError as exc:
+        return _fail(str(exc))
+    report = render_json(log) if args.format == "json" else render_markdown(log)
+    _emit(report, args.out)
+    if args.fail_on_severity is not None and log.max_severity >= args.fail_on_severity:
+        print(
+            f"docfriction: max severity {log.max_severity:.2f} >= {args.fail_on_severity}",
+            file=sys.stderr,
+        )
+        return EXIT_THRESHOLD
+    return EXIT_OK
+
+
+def _dry_run(markdown: str, title: str, max_sections: int | None) -> int:
+    segments = segment_markdown(markdown)[:max_sections]
+    print(f"{title}: {len(segments)} step(s)")
+    for segment in segments:
+        code = f", {len(segment.code_blocks)} code block(s)" if segment.has_code else ""
+        print(f"  {segment.index + 1}. {segment.title} ({len(segment.prose)} chars{code})")
+    return EXIT_OK
+
+
+def _emit(report: str, out: Path | None) -> None:
+    if out is None:
+        sys.stdout.write(report)
+        return
+    out.write_text(report, encoding="utf-8")
+    print(f"docfriction: wrote {out}", file=sys.stderr)
+
+
+def _fail(message: str) -> int:
+    print(f"docfriction: {message}", file=sys.stderr)
+    return EXIT_ERROR
+
+
+if __name__ == "__main__":
+    sys.exit(main())

docfriction/evaluate.py

@@ -0,0 +1,177 @@
+"""Walk a document step by step, ask Jev about each step, and assemble a friction log."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+import httpx
+
+from .checks import check_links, link_client, static_findings
+from .jev import JevClient
+from .models import JEV_SOURCE, Answer, Document, Finding, FrictionLog, Segment, StepLog
+from .rubric import (
+    ACTIONABLE_ONLY,
+    FRICTION_TYPES,
+    IS_ACTIONABLE,
+    NO_FRICTION,
+    NOUL_FAILURE_DETAIL,
+    build_questions,
+    build_state,
+)
+from .segment import segment_markdown
+
+SENTIMENT_BANDS: tuple[tuple[str, float], ...] = (
+    ("smooth", 0.75),
+    ("pause", 1.5),
+    ("frustrated", 2.25),
+)
+BLOCKED = "blocked"
+UNKNOWN_SENTIMENT = "unknown"
+
+
+@dataclass(frozen=True)
+class Thresholds:
+    """Where probabilities turn into findings. Tune per docs set; these are starting points."""
+
+    friction_min_probability: float = 0.5
+    noul_fail_below: float = 0.4
+    noul_review_below: float = 0.6
+    actionable_min: float = 0.5
+    low_confidence: float = 0.4
+
+
+@dataclass(frozen=True)
+class EvaluateOptions:
+    thresholds: Thresholds = field(default_factory=Thresholds)
+    check_links: bool = False
+    allow_private_links: bool = False
+    max_sections: int | None = None
+    concurrency: int = 4
+
+
+def evaluate_document(
+    document: Document,
+    client: JevClient,
+    options: EvaluateOptions | None = None,
+    *,
+    link_transport: httpx.BaseTransport | None = None,
+) -> FrictionLog:
+    opts = options or EvaluateOptions()
+    segments = segment_markdown(document.markdown)[: opts.max_sections]
+    links = (
+        link_client(transport=link_transport, allow_private_hosts=opts.allow_private_links)
+        if opts.check_links
+        else None
+    )
+
+    def run(index: int) -> StepLog:
+        previous = segments[index - 1] if index else None
+        return evaluate_segment(segments[index], previous, document.title, client, opts, links)
+
+    try:
+        with ThreadPoolExecutor(max_workers=max(1, opts.concurrency)) as pool:
+            steps = tuple(pool.map(run, range(len(segments))))
+    finally:
+        if links is not None:
+            links.close()
+    return FrictionLog(
+        source=document.source,
+        title=document.title,
+        model=_model_name(steps, client.model),
+        generated_at=datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        steps=steps,
+    )
+
+
+def evaluate_segment(
+    segment: Segment,
+    previous: Segment | None,
+    page_title: str,
+    client: JevClient,
+    options: EvaluateOptions,
+    links: httpx.Client | None = None,
+) -> StepLog:
+    result = client.evaluate(build_state(segment, previous, page_title), build_questions(segment))
+    severity, jev_findings = interpret_answers(result.answers, options.thresholds)
+    link_findings = check_links(segment.links, links) if links is not None else ()
+    return StepLog(
+        segment=segment,
+        severity=severity,
+        sentiment=sentiment_for(severity),
+        findings=(*jev_findings, *static_findings(segment), *link_findings),
+        input_tokens=result.input_tokens,
+        output_tokens=result.output_tokens,
+        model=result.model,
+    )
+
+
+def interpret_answers(
+    answers: Mapping[str, Answer], thresholds: Thresholds
+) -> tuple[float | None, tuple[Finding, ...]]:
+    severity_answer = answers.get("severity")
+    severity = float(severity_answer.value) if severity_answer else None
+    actionable = answers.get(IS_ACTIONABLE)
+    is_actionable = actionable is None or float(actionable.value) >= thresholds.actionable_min
+    findings = [
+        *_friction_type_findings(answers.get("friction_type"), thresholds),
+        *(
+            finding
+            for key, answer in answers.items()
+            if answer.type == "noul" and key in NOUL_FAILURE_DETAIL
+            if is_actionable or key not in ACTIONABLE_ONLY
+            for finding in _noul_findings(key, answer, thresholds)
+        ),
+    ]
+    return severity, tuple(findings)
+
+
+def sentiment_for(severity: float | None) -> str:
+    if severity is None:
+        return UNKNOWN_SENTIMENT
+    for name, upper in SENTIMENT_BANDS:
+        if severity < upper:
+            return name
+    return BLOCKED
+
+
+def _friction_type_findings(answer: Answer | None, thresholds: Thresholds) -> tuple[Finding, ...]:
+    if answer is None or answer.value == NO_FRICTION:
+        return ()
+    probability = answer.probability or 0.0
+    if probability < thresholds.friction_min_probability:
+        return ()
+    confidence = answer.confidence
+    return (
+        Finding(
+            check=str(answer.value),
+            source=JEV_SOURCE,
+            detail=FRICTION_TYPES.get(str(answer.value), str(answer.value)),
+            probability=probability,
+            confidence=confidence,
+            needs_review=confidence is not None and confidence < thresholds.low_confidence,
+        ),
+    )
+
+
+def _noul_findings(key: str, answer: Answer, thresholds: Thresholds) -> tuple[Finding, ...]:
+    probability = float(answer.value)
+    if probability >= thresholds.noul_review_below:
+        return ()
+    return (
+        Finding(
+            check=key,
+            source=JEV_SOURCE,
+            detail=NOUL_FAILURE_DETAIL[key],
+            probability=probability,
+            confidence=answer.confidence,
+            needs_review=probability >= thresholds.noul_fail_below,
+        ),
+    )
+
+
+def _model_name(steps: tuple[StepLog, ...], fallback: str) -> str:
+    """Prefer the resolved model id from the API (e.g. jev-1.13.0) over the alias."""
+    return next((step.model for step in steps if step.model), fallback)

docfriction/fetch.py

@@ -0,0 +1,124 @@
+"""Load a documentation page from a URL or a local file and normalise it to Markdown."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import httpx
+from bs4 import BeautifulSoup, Tag
+from markdownify import markdownify
+
+from ._version import __version__
+from .models import Document
+from .segment import document_title
+
+# Most specific first: on GitHub `article.markdown-body` is the README while `main`
+# also wraps the file browser; on Sphinx sites `[role=main]` excludes the sidebar.
+CONTENT_SELECTORS = ("article", ".markdown-body", "[role=main]", "main", "#content", ".content")
+STRIP_TAGS = ("script", "style", "nav", "header", "footer", "aside", "noscript", "svg", "form")
+HTML_SUFFIXES = frozenset({".html", ".htm"})
+LANGUAGE_CLASS_PREFIXES = ("language-", "lang-")
+USER_AGENT = f"docfriction/{__version__} (+https://github.com/Cyvid7-Darus10/docfriction)"
+ACCEPT = "text/markdown, text/html;q=0.9, text/plain;q=0.8, */*;q=0.1"
+DEFAULT_TIMEOUT_SECONDS = 20.0
+MAX_PAGE_BYTES = 5 * 1024 * 1024
+
+
+class FetchError(Exception):
+    pass
+
+
+def load_document(
+    source: str,
+    *,
+    transport: httpx.BaseTransport | None = None,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+) -> Document:
+    if source.startswith(("http://", "https://")):
+        return _fetch_url(source, transport=transport, timeout=timeout)
+    path = Path(source)
+    if not path.is_file():
+        raise FetchError(f"source is neither a URL nor an existing file: {source}")
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        raise FetchError(f"failed to read {source}: {exc}") from exc
+    if path.suffix.lower() in HTML_SUFFIXES:
+        return _from_html(source, text, fallback_title=path.name)
+    return Document(source=source, title=document_title(text) or path.name, markdown=text)
+
+
+def _fetch_url(url: str, *, transport: httpx.BaseTransport | None, timeout: float) -> Document:
+    headers = {"User-Agent": USER_AGENT, "Accept": ACCEPT}
+    try:
+        with (
+            httpx.Client(
+                follow_redirects=True, headers=headers, timeout=timeout, transport=transport
+            ) as client,
+            client.stream("GET", url) as response,
+        ):
+            response.raise_for_status()
+            content_type = response.headers.get("content-type", "")
+            body = _read_capped(response, url)
+    except httpx.HTTPError as exc:
+        raise FetchError(f"failed to fetch {url}: {exc}") from exc
+    if not body.strip():
+        raise FetchError(f"{url} returned an empty body")
+    if _looks_like_html(content_type, body):
+        return _from_html(url, body, fallback_title=url)
+    return Document(source=url, title=document_title(body) or url, markdown=body)
+
+
+def _read_capped(response: httpx.Response, url: str) -> str:
+    """Read at most MAX_PAGE_BYTES so a hostile or huge page cannot exhaust memory."""
+    declared = response.headers.get("content-length")
+    if declared and declared.isdigit() and int(declared) > MAX_PAGE_BYTES:
+        raise FetchError(f"{url} is larger than {MAX_PAGE_BYTES} bytes")
+    chunks: list[bytes] = []
+    total = 0
+    for chunk in response.iter_bytes():
+        total += len(chunk)
+        if total > MAX_PAGE_BYTES:
+            raise FetchError(f"{url} is larger than {MAX_PAGE_BYTES} bytes")
+        chunks.append(chunk)
+    return b"".join(chunks).decode(response.charset_encoding or "utf-8", errors="replace")
+
+
+def _looks_like_html(content_type: str, body: str) -> bool:
+    head = body.lstrip()[:20].lower()
+    return "html" in content_type or head.startswith(("<!doctype", "<html"))
+
+
+def _from_html(source: str, html: str, *, fallback_title: str) -> Document:
+    soup = BeautifulSoup(html, "html.parser")
+    page_title = soup.title.get_text(strip=True) if soup.title else ""
+    for tag in soup(STRIP_TAGS):
+        tag.decompose()
+    root = _content_root(soup)
+    markdown = markdownify(
+        str(root), heading_style="ATX", bullets="-", code_language_callback=_code_language
+    ).strip()
+    if not markdown:
+        raise FetchError(f"no readable content found in {source}")
+    title = document_title(markdown) or page_title or fallback_title
+    return Document(source=source, title=title, markdown=markdown)
+
+
+def _content_root(soup: BeautifulSoup) -> Tag | BeautifulSoup:
+    for selector in CONTENT_SELECTORS:
+        found = soup.select_one(selector)
+        if found is not None and found.get_text(strip=True):
+            return found
+    return soup.body or soup
+
+
+def _code_language(element: Tag) -> str:
+    classes = list(element.get("class") or [])
+    inner = element.find("code")
+    if isinstance(inner, Tag):
+        classes.extend(inner.get("class") or [])
+    for css_class in classes:
+        for prefix in LANGUAGE_CLASS_PREFIXES:
+            if css_class.startswith(prefix):
+                return css_class[len(prefix) :]
+    return ""