kbve 0.1.0__py3-none-any.whl

kbve/__init__.py

@@ -0,0 +1,10 @@
+"""KBVE - Core library for async servers, Nx workspace tooling, and MDX rendering."""
+
+from .models.server_models import ServerConfig  # noqa: F401
+from .server.app_server import AppServer  # noqa: F401
+from .server.grpc_server import GrpcServer  # noqa: F401
+from .server.http_server import HttpServer  # noqa: F401
+from .server.services.health_service import HealthServicer  # noqa: F401
+from .server.services.echo_service import EchoServicer  # noqa: F401
+
+__version__ = "0.1.0"

kbve/api/__init__.py

@@ -0,0 +1 @@
+"""KBVE API utilities."""

kbve/api/clients/__init__.py

@@ -0,0 +1 @@
+"""KBVE API clients."""

kbve/api/utils/__init__.py

@@ -0,0 +1 @@
+"""KBVE API utilities."""

kbve/mdx/__init__.py

@@ -0,0 +1,4 @@
+"""KBVE MDX/Starlight rendering primitives."""
+
+from .escape import escape_mdx  # noqa: F401
+from .renderer import MdxWriter  # noqa: F401

kbve/mdx/escape.py

@@ -0,0 +1,14 @@
+"""MDX/JSX text escaping utilities."""
+
+from __future__ import annotations
+
+
+def escape_mdx(text: str) -> str:
+    """Escape characters that MDX/JSX would interpret as markup."""
+    return (text
+            .replace("&", "&")
+            .replace("<", "&lt;")
+            .replace(">", "&gt;")
+            .replace("{", "&#123;")
+            .replace("}", "&#125;")
+            .replace("|", "\\|"))

kbve/mdx/renderer.py

@@ -0,0 +1,220 @@
+"""Starlight MDX rendering primitives.
+
+Provides ``MdxWriter``, a composable builder for generating Astro Starlight
+MDX pages with frontmatter, cards, tabs, mermaid diagrams, tables, and
+admonitions.
+"""
+
+from __future__ import annotations
+
+import io
+from typing import Any
+
+
+class MdxWriter:
+    """Composable builder for Starlight MDX content.
+
+    Usage::
+
+        w = MdxWriter()
+        w.frontmatter(title="My Page", description="A page.")
+        w.imports("Card", "CardGrid", source="@astrojs/starlight/components")
+        w.heading("Hello", level=2)
+        w.admonition("note", "Auto-generated", "Some body text.")
+        w.card_grid_start()
+        w.card("3 Apps", icon="rocket", body="app1, app2, app3")
+        w.card_grid_end()
+        w.mermaid_pie("Title", {"Apps": 3, "Libs": 5})
+        w.table(["Col A", "Col B"], [["a", "b"]])
+        content = w.render()
+    """
+
+    def __init__(self) -> None:
+        self._buf = io.StringIO()
+
+    # ── Frontmatter ──────────────────────────────────────────────
+
+    def frontmatter(self, **kwargs: Any) -> "MdxWriter":
+        """Write YAML frontmatter block.
+
+        Supports flat keys and one level of nesting via dict values::
+
+            w.frontmatter(
+                title="Page",
+                sidebar={"label": "Nav", "order": 1},
+            )
+        """
+        colon = ":"
+        self._buf.write("---\n")
+        for key, val in kwargs.items():
+            if isinstance(val, dict):
+                self._buf.write(f"{key}{colon}\n")
+                for k, v in val.items():
+                    if isinstance(v, str) and "\n" in v:
+                        self._buf.write(f"    {k}{colon} |\n")
+                        for line in v.splitlines():
+                            self._buf.write(f"        {line}\n")
+                    else:
+                        self._buf.write(f"    {k}{colon} {v}\n")
+            elif isinstance(val, bool):
+                bval = "true" if val else "false"
+                self._buf.write(f"{key}{colon} {bval}\n")
+            else:
+                self._buf.write(f"{key}{colon} {val}\n")
+        self._buf.write("---\n\n")
+        return self
+
+    # ── Imports ──────────────────────────────────────────────────
+
+    def imports(self, *components: str, source: str) -> "MdxWriter":
+        """Write an ESM import statement."""
+        names = ", ".join(components)
+        lbrace = "{"
+        rbrace = "}"
+        semi = ";"
+        self._buf.write(
+            f"import {lbrace} {names} {rbrace} from '{source}'{semi}\n\n"
+        )
+        return self
+
+    # ── Headings & text ──────────────────────────────────────────
+
+    def heading(self, text: str, level: int = 2) -> "MdxWriter":
+        prefix = "#" * level
+        self._buf.write(f"{prefix} {text}\n\n")
+        return self
+
+    def text(self, content: str) -> "MdxWriter":
+        self._buf.write(f"{content}\n\n")
+        return self
+
+    def raw(self, content: str) -> "MdxWriter":
+        """Write raw content without trailing newlines."""
+        self._buf.write(content)
+        return self
+
+    # ── Admonitions ──────────────────────────────────────────────
+
+    def admonition(
+        self, kind: str, title: str, body: str,
+    ) -> "MdxWriter":
+        """Write a Starlight admonition (note, tip, caution, danger)."""
+        prefix = ":" * 3
+        self._buf.write(
+            f"{prefix}{kind}[{title}]\n{body}\n{prefix}\n\n"
+        )
+        return self
+
+    # ── Cards ────────────────────────────────────────────────────
+
+    def card_grid_start(self) -> "MdxWriter":
+        self._buf.write("<CardGrid>\n")
+        return self
+
+    def card_grid_end(self) -> "MdxWriter":
+        self._buf.write("</CardGrid>\n\n")
+        return self
+
+    def card(
+        self, title: str, icon: str, body: str,
+    ) -> "MdxWriter":
+        line1 = f'  <Card title="{title}" icon="{icon}">'
+        line2 = f"    {body}"
+        self._buf.write(f"{line1}\n{line2}\n  </Card>\n")
+        return self
+
+    # ── Tabs ─────────────────────────────────────────────────────
+
+    def tabs_start(self) -> "MdxWriter":
+        self._buf.write("<Tabs>\n")
+        return self
+
+    def tabs_end(self) -> "MdxWriter":
+        self._buf.write("</Tabs>\n\n")
+        return self
+
+    def tab_start(self, label: str) -> "MdxWriter":
+        tag = f'  <TabItem label="{label}">'
+        self._buf.write(f"{tag}\n\n")
+        return self
+
+    def tab_end(self) -> "MdxWriter":
+        self._buf.write("  </TabItem>\n")
+        return self
+
+    # ── Mermaid ──────────────────────────────────────────────────
+
+    def mermaid_pie(
+        self, title: str, data: dict[str, int | float],
+    ) -> "MdxWriter":
+        """Write a Mermaid pie chart."""
+        self._buf.write("```mermaid\npie showData\n")
+        self._buf.write(f"    title {title}\n")
+        for label, value in data.items():
+            if value > 0:
+                self._buf.write(
+                    '    "' + label + '" : ' + str(value) + '\n'
+                )
+        self._buf.write("```\n\n")
+        return self
+
+    def mermaid_graph(self, lines: list[str]) -> "MdxWriter":
+        """Write a raw Mermaid graph block."""
+        self._buf.write("```mermaid\n")
+        self._buf.write("\n".join(lines))
+        self._buf.write("\n```\n\n")
+        return self
+
+    # ── Tables ───────────────────────────────────────────────────
+
+    def table(
+        self,
+        headers: list[str],
+        rows: list[list[str]],
+        alignments: list[str] | None = None,
+    ) -> "MdxWriter":
+        """Write a Markdown table.
+
+        ``alignments`` can contain ``"left"``, ``"center"``, or ``"right"``
+        per column.  Defaults to left-aligned.
+        """
+        if alignments is None:
+            alignments = ["left"] * len(headers)
+
+        sep_map = {
+            "left": "---",
+            "center": ":---:",
+            "right": "---:",
+        }
+        header_line = "| " + " | ".join(headers) + " |"
+        sep_line = "| " + " | ".join(
+            sep_map.get(a, "---") for a in alignments
+        ) + " |"
+
+        self._buf.write(header_line + "\n")
+        self._buf.write(sep_line + "\n")
+        for row in rows:
+            self._buf.write("| " + " | ".join(row) + " |\n")
+        self._buf.write("\n")
+        return self
+
+    # ── Details / collapsible ────────────────────────────────────
+
+    def details_start(self, summary: str) -> "MdxWriter":
+        self._buf.write(f"<details>\n<summary>{summary}</summary>\n\n")
+        return self
+
+    def details_end(self) -> "MdxWriter":
+        self._buf.write("\n</details>\n\n")
+        return self
+
+    # ── Render ───────────────────────────────────────────────────
+
+    def render(self) -> str:
+        """Return the accumulated MDX content as a string."""
+        return self._buf.getvalue()
+
+    def write_to(self, path: str) -> None:
+        """Write the accumulated MDX content to a file."""
+        with open(path, "w") as f:
+            f.write(self.render())

kbve/models/__init__.py

@@ -0,0 +1,3 @@
+"""KBVE models."""
+
+from .server_models import ServerConfig  # noqa: F401

kbve/models/server_models.py

@@ -0,0 +1,13 @@
+"""Server configuration models."""
+
+from pydantic import BaseModel
+
+
+class ServerConfig(BaseModel):
+    """Configuration for the unified HTTP + gRPC server."""
+
+    http_host: str = "0.0.0.0"
+    http_port: int = 8000
+    grpc_host: str = "0.0.0.0"
+    grpc_port: int = 50051
+    log_level: str = "info"

kbve/nx/__init__.py

@@ -0,0 +1,20 @@
+"""KBVE Nx workspace integrations — graph analysis and security auditing."""
+
+from .graph import (  # noqa: F401
+    parse_graph,
+    group_projects_by_type,
+    collect_edges,
+    top_hubs,
+    ProjectRow,
+)
+from .security import (  # noqa: F401
+    normalize_severity,
+    parse_npm,
+    parse_cargo,
+    parse_python,
+    parse_codeql,
+    parse_dependabot,
+    build_summary,
+    parse_all_ecosystems,
+    SEVERITY_ORDER,
+)

kbve/nx/graph.py

@@ -0,0 +1,131 @@
+"""Nx project graph parsing and analysis.
+
+Parses Nx graph JSON into structured data for downstream rendering
+(MDX, JSON reports, API responses, etc.).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class ProjectRow:
+    """A single project extracted from the Nx graph."""
+
+    name: str
+    project_type: str
+    root: str
+    dep_count: int
+    dependent_count: int
+
+
+@dataclass
+class GraphData:
+    """Parsed and analysed Nx project graph."""
+
+    nodes: dict[str, Any]
+    deps: dict[str, list[dict[str, str]]]
+    rows: list[ProjectRow]
+    by_type: dict[str, list[str]]
+    edges: set[tuple[str, str]]
+    edges_by_source: dict[str, list[str]]
+
+
+def mermaid_id(name: str) -> str:
+    """Sanitize a project name into a valid Mermaid node ID."""
+    return re.sub(r"[^a-zA-Z0-9_]", "_", name)
+
+
+def parse_graph(source: str | Path | dict) -> GraphData:
+    """Parse an Nx graph from a file path, JSON string, or dict.
+
+    Returns a fully analysed ``GraphData`` with rows, groupings, and edges
+    ready for rendering.
+    """
+    if isinstance(source, dict):
+        data = source
+    elif isinstance(source, Path) or (
+        isinstance(source, str) and not source.lstrip().startswith("{")
+    ):
+        with open(source) as f:
+            data = json.load(f)
+    else:
+        data = json.loads(source)
+
+    nodes: dict[str, Any] = data["graph"]["nodes"]
+    deps: dict[str, list[dict[str, str]]] = data["graph"]["dependencies"]
+
+    by_type = group_projects_by_type(nodes)
+    rows = _build_rows(nodes, deps)
+    edges, edges_by_source = collect_edges(deps)
+
+    return GraphData(
+        nodes=nodes,
+        deps=deps,
+        rows=rows,
+        by_type=by_type,
+        edges=edges,
+        edges_by_source=edges_by_source,
+    )
+
+
+def group_projects_by_type(
+    nodes: dict[str, Any],
+) -> dict[str, list[str]]:
+    """Group project names by their Nx project type."""
+    by_type: dict[str, list[str]] = {}
+    for name, node in sorted(nodes.items()):
+        ptype = node.get("type", "unknown")
+        by_type.setdefault(ptype, []).append(name)
+    return by_type
+
+
+def collect_edges(
+    deps: dict[str, list[dict[str, str]]],
+) -> tuple[set[tuple[str, str]], dict[str, list[str]]]:
+    """Collect unique directed edges from Nx dependency data.
+
+    Returns ``(edge_set, edges_by_source)``.
+    """
+    seen: set[tuple[str, str]] = set()
+    by_source: dict[str, list[str]] = {}
+    for dep_list in deps.values():
+        for d in dep_list:
+            edge = (d["source"], d["target"])
+            if edge not in seen:
+                seen.add(edge)
+                by_source.setdefault(d["source"], []).append(d["target"])
+    return seen, by_source
+
+
+def top_hubs(rows: list[ProjectRow], n: int = 5) -> list[ProjectRow]:
+    """Return the *n* most-depended-on projects."""
+    return sorted(rows, key=lambda r: r.dependent_count, reverse=True)[:n]
+
+
+def _build_rows(
+    nodes: dict[str, Any],
+    deps: dict[str, list[dict[str, str]]],
+) -> list[ProjectRow]:
+    """Build a sorted list of ``ProjectRow`` from raw graph data."""
+    rows: list[ProjectRow] = []
+    for name in sorted(nodes):
+        node = nodes[name]
+        dep_count = len(deps.get(name, []))
+        dependents = sum(
+            1 for d_list in deps.values() for d in d_list
+            if d["target"] == name
+        )
+        rows.append(ProjectRow(
+            name=name,
+            project_type=node.get("type", "unknown"),
+            root=node.get("data", {}).get("root", ""),
+            dep_count=dep_count,
+            dependent_count=dependents,
+        ))
+    return rows