spec-probe 0.1.0__py3-none-any.whl

spec_probe/__init__.py

@@ -0,0 +1,3 @@
+"""spec-probe — functional requirement coverage scanner for C/C++ modules."""
+
+__version__ = "0.1.0"

spec_probe/cache/store.py

@@ -0,0 +1,84 @@
+"""Persistent cache for per-FR verification results."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import threading
+from pathlib import Path
+from typing import Any
+
+from spec_probe.kb.verification_store import entry_from_verified, upsert_entry
+from spec_probe.models import VerifiedCoverage
+from spec_probe.user_home import ensure_cache_dir
+
+_CACHE_LOCK = threading.RLock()
+
+
+def _cache_key(module_path: str, spec_path: str) -> str:
+    raw = f"{module_path}|{spec_path}"
+    return hashlib.sha256(raw.encode()).hexdigest()[:16]
+
+
+def cache_path(module_path: str, spec_path: str) -> Path:
+    return ensure_cache_dir() / f"coverage_{_cache_key(module_path, spec_path)}.json"
+
+
+def load_cache(module_path: str, spec_path: str) -> dict[str, Any]:
+    path = cache_path(module_path, spec_path)
+    if not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return data if isinstance(data, dict) else {}
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def save_cache(module_path: str, spec_path: str, entries: dict[str, Any]) -> Path:
+    path = cache_path(module_path, spec_path)
+    path.write_text(json.dumps(entries, indent=2, ensure_ascii=False), encoding="utf-8")
+    return path
+
+
+def get_cached_result(
+    module_path: str,
+    spec_path: str,
+    fr_id: str,
+) -> dict[str, Any] | None:
+    with _CACHE_LOCK:
+        cache = load_cache(module_path, spec_path)
+        entry = cache.get(fr_id)
+        return entry if isinstance(entry, dict) else None
+
+
+def set_cached_result(
+    module_path: str,
+    spec_path: str,
+    fr_id: str,
+    result: dict[str, Any],
+) -> None:
+    with _CACHE_LOCK:
+        cache = load_cache(module_path, spec_path)
+        cache[fr_id] = result
+        save_cache(module_path, spec_path, cache)
+
+
+def persist_verification_result(
+    result: VerifiedCoverage,
+    *,
+    module_path: str,
+    spec_path: str,
+    kb_path: str | None = None,
+    search_keywords: list[str] | None = None,
+) -> None:
+    """Append successful verification to the cross-project knowledge base."""
+    if result.final_verdict.value not in ("IMPLEMENTED", "PARTIAL", "NEEDS_REVIEW"):
+        return
+    entry = entry_from_verified(
+        result,
+        module_path=module_path,
+        spec_path=spec_path,
+        search_keywords=search_keywords,
+    )
+    upsert_entry(entry, kb_path)

spec_probe/collab/__init__.py

@@ -0,0 +1,26 @@
+"""Collab (Confluence) integration for spec-probe."""
+
+from spec_probe.collab.client import (
+    extract_base_url,
+    find_child_page,
+    find_or_create_child_page,
+    find_or_create_page,
+    make_confluence_client,
+    parse_collab_url,
+    read_page,
+)
+from spec_probe.collab.converter import md_to_confluence_html
+from spec_probe.collab.publisher import build_page_title, publish_coverage_report
+
+__all__ = [
+    "build_page_title",
+    "extract_base_url",
+    "find_child_page",
+    "find_or_create_child_page",
+    "find_or_create_page",
+    "make_confluence_client",
+    "md_to_confluence_html",
+    "parse_collab_url",
+    "publish_coverage_report",
+    "read_page",
+]

spec_probe/collab/client.py

@@ -0,0 +1,248 @@
+"""Confluence client helper — connect, read, and write pages."""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Any, Optional
+from loguru import logger
+
+try:
+    from atlassian import Confluence
+except ImportError:
+    Confluence = None
+
+try:
+    import requests as _requests
+    from requests.adapters import HTTPAdapter as _HTTPAdapter
+
+    class _TimeoutAdapter(_HTTPAdapter):
+        """HTTP adapter with default 30s timeout to prevent hanging connections."""
+
+        def __init__(self, timeout: int = 30, *args: Any, **kwargs: Any) -> None:
+            self.timeout = timeout
+            super().__init__(*args, **kwargs)
+
+        def send(self, request: Any, **kwargs: Any) -> Any:
+            kwargs.setdefault("timeout", self.timeout)
+            return super().send(request, **kwargs)
+
+except ImportError:
+    _requests = None
+    _TimeoutAdapter = None
+
+
+def parse_collab_url(url: str) -> tuple[Optional[str], Optional[str], Optional[str]]:
+    """
+    Extract (space_key, title, page_id) from a Collab/Confluence URL.
+    Returns (space_key, title, page_id) — title or page_id may be None.
+    """
+    if not url:
+        return None, None, None
+
+    # New-style: /spaces/SPACEKEY/pages/PAGEID/Page+Title
+    m = re.search(r"/spaces/([^/?#]+)/pages/(\d+)(?:/([^?#]+))?", url)
+    if m:
+        title = (m.group(3) or "").replace("+", " ").replace("%20", " ") or None
+        return m.group(1), title, m.group(2)
+
+    # Classic: /display/SPACEKEY/Page+Title
+    m = re.search(r"/display/([^/?#]+)/([^?#]+)", url)
+    if m:
+        return m.group(1), m.group(2).replace("+", " ").replace("%20", " "), None
+
+    # URL with pageId query parameter: ...?pageId=12345
+    m = re.search(r"pageId=(\d+)", url)
+    if m:
+        return None, None, m.group(1)
+
+    return None, None, None
+
+
+def extract_base_url(url: str) -> str:
+    """Extract Confluence base URL (strips path after /main, /spaces, /display, /pages)."""
+    if not url:
+        return ""
+    base_url = url
+    for marker in ["/spaces/", "/display/", "/pages/"]:
+        idx = base_url.find(marker)
+        if idx != -1:
+            base_url = base_url[:idx]
+            break
+    return base_url.rstrip("/")
+
+
+def make_confluence_client(
+    collab_url: str = "",
+    *,
+    api_token: str = "",
+    timeout: int = 30,
+) -> Optional[Confluence]:
+    """
+    Build Confluence client from token in environment (CONFLUENCE_API_TOKEN) or parameter.
+    """
+    if Confluence is None:
+        logger.error(
+            "atlassian-python-api is not installed. Run: pip install atlassian-python-api"
+        )
+        return None
+
+    base_url = extract_base_url(collab_url)
+    if not base_url:
+        logger.error("No valid Collab URL provided.")
+        return None
+
+    token = api_token or os.environ.get("CONFLUENCE_API_TOKEN", "")
+    if not token:
+        logger.error(
+            "Missing Confluence credentials: set CONFLUENCE_API_TOKEN in ~/.config/spec-probe/.env"
+        )
+        return None
+
+    kwargs: dict[str, Any] = {}
+    if _requests is not None and _TimeoutAdapter is not None:
+        session = _requests.Session()
+        session.mount("http://", _TimeoutAdapter(timeout))
+        session.mount("https://", _TimeoutAdapter(timeout))
+        kwargs["session"] = session
+
+    try:
+        return Confluence(url=base_url, token=token, cloud=False, **kwargs)
+    except Exception as exc:
+        logger.error(f"Failed to initialize Confluence client: {exc}")
+        return None
+
+
+def read_page(
+    client: Confluence,
+    *,
+    page_id: str = "",
+    space_key: str = "",
+    title: str = "",
+) -> Optional[dict[str, Any]]:
+    """Read a Confluence page by page_id or (space_key, title)."""
+    try:
+        if page_id:
+            return client.get_page_by_id(page_id, expand="space,version,body.storage")
+        if space_key and title:
+            return client.get_page_by_title(space_key, title, expand="space,version,body.storage")
+    except Exception as exc:
+        logger.warning(f"Failed to read Confluence page (id={page_id}, space={space_key}, title={title}): {exc}")
+    return None
+
+
+def _normalize_child_page_results(result: Any) -> list:
+    if result is None:
+        return []
+    if isinstance(result, list):
+        return result
+    if isinstance(result, dict):
+        return result.get("results", [])
+    try:
+        return list(result)
+    except TypeError:
+        return []
+
+
+def find_child_page(
+    client: Confluence,
+    parent_id: str,
+    title: str,
+) -> tuple[Optional[str], int]:
+    """Find a direct child page under parent_id by exact title."""
+    try:
+        start = 0
+        limit = 100
+        while True:
+            result = client.get_page_child_by_type(
+                parent_id, type="page", start=start, limit=limit
+            )
+            pages = _normalize_child_page_results(result)
+            for page in pages:
+                if page.get("title") == title:
+                    return page.get("id", ""), page.get("version", {}).get("number", 1)
+            if len(pages) < limit:
+                break
+            start += limit
+    except Exception as exc:
+        logger.warning(f"Could not list child pages under {parent_id}: {exc}")
+    return None, 0
+
+
+def find_page_by_title(
+    client: Confluence,
+    space_key: str,
+    title: str,
+) -> tuple[Optional[str], int]:
+    """Find a page anywhere in the space by exact title."""
+    try:
+        page = client.get_page_by_title(space_key, title, expand="version")
+        if page:
+            return page.get("id", ""), page.get("version", {}).get("number", 1)
+    except Exception as exc:
+        logger.warning(f"Could not find page by title '{title}': {exc}")
+    return None, 0
+
+
+def find_or_create_child_page(
+    client: Confluence,
+    parent_id: str,
+    space_key: str,
+    title: str,
+) -> tuple[str, int]:
+    """Find existing child page under parent or create a new child page."""
+    page_id, version = find_child_page(client, parent_id, title)
+    if page_id:
+        logger.info(f"[collab] Found child page: '{title}' (ID: {page_id}, version: {version})")
+        return page_id, version
+
+    logger.info(f"[collab] Creating child page: '{title}' under parent {parent_id}")
+    try:
+        result = client.create_page(
+            space=space_key,
+            title=title,
+            body="<p>Loading coverage report...</p>",
+            parent_id=parent_id,
+            representation="storage",
+        )
+        page_id = result.get("id", "")
+        logger.info(f"[collab] Created child page ID: {page_id}")
+        return page_id, 1
+    except Exception as exc:
+        err = str(exc).lower()
+        if "already exists" in err or "same title" in err:
+            page_id, version = find_page_by_title(client, space_key, title)
+            if page_id:
+                logger.info(f"[collab] Page already exists: '{title}' (ID: {page_id}, version: {version})")
+                return page_id, version
+        raise
+
+
+def find_or_create_page(
+    client: Confluence,
+    space_key: str,
+    title: str,
+) -> tuple[str, int]:
+    """Find existing page in space or create a new one."""
+    page_id, version = find_page_by_title(client, space_key, title)
+    if page_id:
+        logger.info(f"[collab] Found existing page: '{title}' (ID: {page_id}, version: {version})")
+        return page_id, version
+
+    logger.info(f"[collab] Creating new page: '{title}' in space {space_key}")
+    try:
+        result = client.create_page(
+            space=space_key,
+            title=title,
+            body="<p>Loading coverage report...</p>",
+            representation="storage",
+        )
+        page_id = result.get("id", "")
+        return page_id, 1
+    except Exception as exc:
+        err = str(exc).lower()
+        if "already exists" in err or "same title" in err:
+            page_id, version = find_page_by_title(client, space_key, title)
+            if page_id:
+                return page_id, version
+        raise

spec_probe/collab/converter.py

@@ -0,0 +1,286 @@
+"""Markdown to Confluence Storage Format XHTML converter."""
+
+from __future__ import annotations
+
+import html as html_module
+import re
+from loguru import logger
+
+try:
+    import markdown
+except ImportError:
+    markdown = None
+
+
+def _escape_raw_angle_brackets(md_text: str) -> str:
+    """
+    Escape < and > outside fenced code blocks and inline code.
+    Prevents malformed XML tags when publishing to Confluence storage format.
+    """
+    parts = re.split(r"(```.*?```|`[^`\n]+`)", md_text, flags=re.DOTALL)
+    escaped: list[str] = []
+    for i, part in enumerate(parts):
+        if i % 2 == 1:
+            # Code block or inline code
+            escaped.append(part)
+        else:
+            escaped.append(part.replace("<", "&lt;").replace(">", "&gt;"))
+    return "".join(escaped)
+
+
+def _md_to_html_fallback(md_text: str) -> str:
+    """Basic fallback parser for markdown to HTML without python-markdown."""
+    lines = md_text.split("\n")
+    html_lines: list[str] = []
+    in_table = False
+    in_code = False
+    in_list = False
+    code_buffer: list[str] = []
+    code_lang = ""
+
+    def _close_list() -> None:
+        nonlocal in_list
+        if in_list:
+            html_lines.append("</ul>")
+            in_list = False
+
+    for line in lines:
+        if line.startswith("```"):
+            if in_code:
+                lang = code_lang or "cpp"
+                html_lines.append(
+                    _confluence_code_macro("".join(code_buffer).rstrip("\n"), lang)
+                )
+                code_buffer = []
+                code_lang = ""
+                in_code = False
+            else:
+                code_lang = line[3:].strip() or "cpp"
+                in_code = True
+            continue
+        if in_code:
+            code_buffer.append(line + "\n")
+            continue
+
+        if line.startswith("### "):
+            _close_list()
+            html_lines.append(f"<h3>{line[4:]}</h3>")
+        elif line.startswith("## "):
+            _close_list()
+            html_lines.append(f"<h2>{line[3:]}</h2>")
+        elif line.startswith("# "):
+            _close_list()
+            html_lines.append(f"<h1>{line[2:]}</h1>")
+        elif re.match(r"^[\s\|:-]+$", line) and "|" in line:
+            continue
+        elif line.startswith("|") and line.endswith("|"):
+            cells = [c.strip() for c in line.split("|")[1:-1]]
+            if not in_table:
+                html_lines.append("<table><tbody>")
+                in_table = True
+                html_lines.append("<tr>" + "".join(f"<th>{c}</th>" for c in cells) + "</tr>")
+            else:
+                html_lines.append("<tr>" + "".join(f"<td>{c}</td>" for c in cells) + "</tr>")
+        else:
+            if in_table:
+                html_lines.append("</tbody></table>")
+                in_table = False
+            if line.strip() == "":
+                _close_list()
+                continue
+            elif line.startswith("- ") or line.startswith("* "):
+                if not in_list:
+                    html_lines.append("<ul>")
+                    in_list = True
+                item = line[2:]
+                item = re.sub(r"\*\*(.+?)\*\*", r"<strong>\1</strong>", item)
+                item = re.sub(r"`(.+?)`", r"<code>\1</code>", item)
+                item = re.sub(r"\[(.+?)\]\((.+?)\)", r'<a href="\2">\1</a>', item)
+                html_lines.append(f"<li>{item}</li>")
+            elif line.startswith("  - ") or line.startswith("  * "):
+                if not in_list:
+                    html_lines.append("<ul>")
+                    in_list = True
+                html_lines.append(f"<li style='margin-left:20px'>{line[4:]}</li>")
+            else:
+                _close_list()
+                text = re.sub(r"\*\*(.+?)\*\*", r"<strong>\1</strong>", line)
+                text = re.sub(r"`(.+?)`", r"<code>\1</code>", text)
+                text = re.sub(r"\[(.+?)\]\((.+?)\)", r'<a href="\2">\1</a>', text)
+                html_lines.append(f"<p>{text}</p>")
+
+    _close_list()
+    if in_table:
+        html_lines.append("</tbody></table>")
+    if in_code:
+        html_lines.append(
+            _confluence_code_macro("".join(code_buffer).rstrip("\n"), code_lang or "cpp")
+        )
+
+    return "\n".join(html_lines)
+
+
+def _confluence_code_macro(code: str, language: str = "cpp") -> str:
+    """Confluence storage-format code block with syntax highlighting."""
+    lang = (language or "text").strip().lower()
+    body = code.replace("]]>", "]]&gt;")
+    return (
+        '<ac:structured-macro ac:name="code" ac:schema-version="1">'
+        f'<ac:parameter ac:name="language">{lang}</ac:parameter>'
+        f"<ac:plain-text-body><![CDATA[{body}]]></ac:plain-text-body>"
+        "</ac:structured-macro>"
+    )
+
+
+def _plain_code_from_html_fragment(fragment: str) -> str:
+    raw = html_module.unescape(fragment or "")
+    return re.sub(r"<[^>]+>", "", raw).strip()
+
+
+def _code_pre_blocks_to_confluence_macros(html: str) -> str:
+    """Replace HTML <pre><code> blocks with Confluence ``code`` macros (C++ highlight)."""
+
+    def repl_pre(m: re.Match[str]) -> str:
+        lang = (m.group(1) or "cpp").strip().lower()
+        return _confluence_code_macro(_plain_code_from_html_fragment(m.group(2)), lang)
+
+    # codehilite (python-markdown) wrapper — must run before bare <pre>
+    html = re.sub(
+        r'<div class="(?:highlight|codehilite)"[^>]*>\s*<pre[^>]*>(?:<span></span>)?'
+        r"<code[^>]*>(.*?)</code></pre>\s*</div>",
+        lambda m: _confluence_code_macro(_plain_code_from_html_fragment(m.group(1)), "cpp"),
+        html,
+        flags=re.DOTALL | re.IGNORECASE,
+    )
+    html = re.sub(
+        r'<pre[^>]*><code(?:\s+class="[^"]*language-(\w+)[^"]*")?[^>]*>(.*?)</code></pre>',
+        repl_pre,
+        html,
+        flags=re.DOTALL | re.IGNORECASE,
+    )
+    return html
+
+
+def _rewrite_links_for_confluence(html: str) -> str:
+    """OpenGrok/http links in new tab; rewrite IDE file links to OpenGrok when configured."""
+    from spec_probe.report.links import code_browser_uri, get_code_link_config
+
+    cfg = get_code_link_config()
+
+    def repl(m: re.Match[str]) -> str:
+        href = m.group(1)
+        text = m.group(2)
+        if href.startswith(("http://", "https://")):
+            return (
+                f'<a href="{href}" target="_blank" rel="noopener noreferrer">{text}</a>'
+            )
+        if cfg and cfg.code_browser_base_url.strip():
+            for prefix in ("vscode://file", "cursor://file"):
+                if href.startswith(prefix):
+                    path_part = href[len(prefix) :]
+                    match = re.match(r"^(.+?):(\d+)(?::\d+)?$", path_part)
+                    if match:
+                        path = match.group(1)
+                        line = int(match.group(2))
+                        new_href = code_browser_uri(
+                            path,
+                            line,
+                            base_url=cfg.code_browser_base_url.strip(),
+                            path_marker=cfg.code_browser_path_marker,
+                        )
+                        return (
+                            f'<a href="{new_href}" target="_blank" '
+                            f'rel="noopener noreferrer">{text}</a>'
+                        )
+        if href.startswith(("vscode://", "cursor://", "file://")):
+            return text
+        return m.group(0)
+
+    return re.sub(
+        r'<a href="([^"]+)"[^>]*>(.*?)</a>',
+        repl,
+        html,
+        flags=re.DOTALL,
+    )
+
+
+def _style_verdicts(html: str) -> str:
+    """Add visual badge styling for verdicts in Confluence tables/headings."""
+    replacements = {
+        r"\bIMPLEMENTED\b": '<span style="color:#00875A;font-weight:bold;background-color:#E3FCEF;padding:2px 6px;border-radius:3px;">IMPLEMENTED</span>',
+        r"\bPARTIAL\b": '<span style="color:#FF8B00;font-weight:bold;background-color:#FFF0B3;padding:2px 6px;border-radius:3px;">PARTIAL</span>',
+        r"\bNOT_FOUND\b": '<span style="color:#DE350B;font-weight:bold;background-color:#FFEBE6;padding:2px 6px;border-radius:3px;">NOT_FOUND</span>',
+        r"\bNEEDS_REVIEW\b": '<span style="color:#42526E;font-weight:bold;background-color:#EBECF0;padding:2px 6px;border-radius:3px;">NEEDS_REVIEW</span>',
+    }
+    for pattern, badge in replacements.items():
+        # Only replace inside table cells <td> or list items <li> to avoid replacing code blocks
+        html = re.sub(
+            rf"(<td[^>]*>.*?){pattern}(.*?</td>)",
+            rf"\1{badge}\2",
+            html,
+            flags=re.IGNORECASE,
+        )
+    return html
+
+
+def md_to_confluence_html(
+    md_text: str,
+    *,
+    jira_url: str = "",
+    codebeamer_url: str = "",
+) -> str:
+    """
+    Convert Markdown to Confluence storage-format HTML.
+    Handles linkification, table styling, code blocks, and escaping.
+    """
+    safe_md = _escape_raw_angle_brackets(md_text)
+
+    if markdown is None:
+        logger.warning("[collab] markdown library not installed, using fallback HTML converter")
+        html = _md_to_html_fallback(safe_md)
+    else:
+        extensions = [
+            "markdown.extensions.extra",
+            "markdown.extensions.codehilite",
+            "markdown.extensions.tables",
+            "markdown.extensions.smarty",
+        ]
+        html = markdown.markdown(safe_md, extensions=extensions)
+
+    # Linkify raw HTTP(S) URLs if not already inside an <a> tag
+    existing_spans = [m.span() for m in re.finditer(r"<a\b[^>]*>.*?</a>", html, flags=re.DOTALL)]
+
+    def _in_existing_link(pos: int) -> bool:
+        return any(start <= pos < end for start, end in existing_spans)
+
+    def _linkify_url(m: re.Match) -> str:
+        if m.group(0).startswith("&quot;") or _in_existing_link(m.start()):
+            return m.group(0)
+        return f'<a href="{m.group(1)}">{m.group(1)}</a>'
+
+    html = re.sub(r"(https?://[^\s<)\"]+)", _linkify_url, html)
+
+    # Jira keys: PROJECT-1234
+    if jira_url:
+        jira_base = jira_url.rstrip("/")
+        html = re.sub(
+            r"(<t[dh][^>]*>)\s*([A-Z][A-Z0-9]+-\d+)\s*(</t[dh]>)",
+            lambda m: f'{m.group(1)}<a href="{jira_base}/browse/{m.group(2)}">{m.group(2)}</a>{m.group(3)}',
+            html,
+        )
+
+    # Codebeamer ticket IDs: 8 digits
+    if codebeamer_url:
+        cb_base = codebeamer_url.rstrip("/")
+        html = re.sub(
+            r"(<t[dh][^>]*>)\s*(\d{8})\s*(</t[dh]>)",
+            lambda m: f'{m.group(1)}<a href="{cb_base}/issue/{m.group(2)}">{m.group(2)}</a>{m.group(3)}',
+            html,
+        )
+
+    # Style verdict badges
+    html = _style_verdicts(html)
+    html = _code_pre_blocks_to_confluence_macros(html)
+    html = _rewrite_links_for_confluence(html)
+
+    return html