mongo-x-ray-risk 2.0.0__tar.gz

mongo_x_ray_risk-2.0.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: mongo-x-ray-risk
+Version: 2.0.0
+Summary: Known-risks knowledge base (ChromaDB vector search) for x-ray
+Requires-Python: <4,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mongo-x-ray>=2.0.0
+Requires-Dist: chromadb==1.5.9
+
+# mongo-x-ray-risk
+
+[![CI](https://github.com/zhangyaoxing/mongo-x-ray-risk/actions/workflows/ci.yml/badge.svg)](https://github.com/zhangyaoxing/mongo-x-ray-risk/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mongo-x-ray-risk.svg)](https://pypi.org/project/mongo-x-ray-risk/)
+
+Known-risks knowledge base for [x-ray](https://github.com/mongodb-ps/ce-mongo-x-ray): a ChromaDB-backed
+vector search that matches analysis findings against known MongoDB risks.
+
+This is an optional plugin: it ships the `ingest` command to load the risk register, the `search`
+command to look risks up by name, and the analysis plugins (healthcheck, log, gmd) detect it at
+runtime — when it is installed, their reports are enriched with matched risks; when it is missing,
+the enrichment is silently skipped.
+
+## Install
+
+```bash
+pip install mongo-x-ray mongo-x-ray-risk
+```
+
+## Usage
+
+Load a risk register CSV into the ChromaDB knowledge base:
+
+```bash
+x-ray ingest risk_register.csv
+# start from an empty register, then ingest
+x-ray ingest --clear risk_register.csv
+# clear the register without ingesting (no CSV needed)
+x-ray ingest --clear
+```
+
+Check whether a risk is already known by searching the `Name` column
+(case-insensitive substring match). Prints the `Name` and `Risk description`
+of every matching risk; exits 0 when something matches, 1 when nothing does:
+
+```bash
+x-ray search "Replication Lag"
+x-ray search replication
+```
+
+The CSV must have the columns `ID, Risk level, Impact, Name, Risk description`
+(UTF-8, a BOM is tolerated; header names are matched case-insensitively). Any
+other columns, such as `Other Notes`, are ignored. Rows without an ID or a
+Name are skipped; entries with an existing ID are replaced. The data is
+stored under `~/.x-ray/chroma`.
+
+Once ingested, the plugin is used automatically by the other plugins — no CLI
+flags needed. It also exposes a small API for tooling:
+
+```python
+from mongo_x_ray_risk import Risk, load_risks_from_csv, ingest_risks, match_risk, enrich_test_results
+```
+
+## Development
+
+Requires Python 3.10+, MongoDB 5.0 or later, and the [mongo-x-ray](https://github.com/mongodb-ps/ce-mongo-x-ray) core package.
+
+```bash
+make unit-test   # run the unit tests
+make lint        # ruff check + ruff format --check
+```

mongo_x_ray_risk-2.0.0/README.md

@@ -0,0 +1,61 @@
+# mongo-x-ray-risk
+
+[![CI](https://github.com/zhangyaoxing/mongo-x-ray-risk/actions/workflows/ci.yml/badge.svg)](https://github.com/zhangyaoxing/mongo-x-ray-risk/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mongo-x-ray-risk.svg)](https://pypi.org/project/mongo-x-ray-risk/)
+
+Known-risks knowledge base for [x-ray](https://github.com/mongodb-ps/ce-mongo-x-ray): a ChromaDB-backed
+vector search that matches analysis findings against known MongoDB risks.
+
+This is an optional plugin: it ships the `ingest` command to load the risk register, the `search`
+command to look risks up by name, and the analysis plugins (healthcheck, log, gmd) detect it at
+runtime — when it is installed, their reports are enriched with matched risks; when it is missing,
+the enrichment is silently skipped.
+
+## Install
+
+```bash
+pip install mongo-x-ray mongo-x-ray-risk
+```
+
+## Usage
+
+Load a risk register CSV into the ChromaDB knowledge base:
+
+```bash
+x-ray ingest risk_register.csv
+# start from an empty register, then ingest
+x-ray ingest --clear risk_register.csv
+# clear the register without ingesting (no CSV needed)
+x-ray ingest --clear
+```
+
+Check whether a risk is already known by searching the `Name` column
+(case-insensitive substring match). Prints the `Name` and `Risk description`
+of every matching risk; exits 0 when something matches, 1 when nothing does:
+
+```bash
+x-ray search "Replication Lag"
+x-ray search replication
+```
+
+The CSV must have the columns `ID, Risk level, Impact, Name, Risk description`
+(UTF-8, a BOM is tolerated; header names are matched case-insensitively). Any
+other columns, such as `Other Notes`, are ignored. Rows without an ID or a
+Name are skipped; entries with an existing ID are replaced. The data is
+stored under `~/.x-ray/chroma`.
+
+Once ingested, the plugin is used automatically by the other plugins — no CLI
+flags needed. It also exposes a small API for tooling:
+
+```python
+from mongo_x_ray_risk import Risk, load_risks_from_csv, ingest_risks, match_risk, enrich_test_results
+```
+
+## Development
+
+Requires Python 3.10+, MongoDB 5.0 or later, and the [mongo-x-ray](https://github.com/mongodb-ps/ce-mongo-x-ray) core package.
+
+```bash
+make unit-test   # run the unit tests
+make lint        # ruff check + ruff format --check
+```

mongo_x_ray_risk-2.0.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools==83.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mongo-x-ray-risk"
+version = "2.0.0"
+description = "Known-risks knowledge base (ChromaDB vector search) for x-ray"
+readme = "README.md"
+requires-python = ">=3.10,<4"
+dependencies = [
+  "mongo-x-ray>=2.0.0",
+  "chromadb==1.5.9",
+]
+
+[project.entry-points."mongo_x_ray.plugins"]
+ingest = "mongo_x_ray_risk.plugin:IngestPlugin"
+search = "mongo_x_ray_risk.plugin:SearchPlugin"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["mongo_x_ray_risk*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+markers = [
+  "slow: marks tests as slow",
+  "integration: marks tests as integration tests",
+  "unit: marks tests as unit tests",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+exclude = [".venv", "build", "dist"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["mongo_x_ray", "mongo_x_ray_ftdc", "mongo_x_ray_gmd", "mongo_x_ray_hc", "mongo_x_ray_log", "mongo_x_ray_risk"]
+
+[tool.pyright]
+pythonVersion = "3.10"
+venvPath = "../ce-mongo-x-ray"
+venv = ".venv"
+typeCheckingMode = "basic"
+extraPaths = [
+  "src",
+  "../ce-mongo-x-ray/src",
+]

mongo_x_ray_risk-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mongo_x_ray_risk-2.0.0/src/mongo_x_ray_risk/__init__.py

@@ -0,0 +1,40 @@
+"""
+Copyright (c) 2026 MongoDB Inc.
+
+DISCLAIMER: THESE CODE SAMPLES ARE PROVIDED FOR EDUCATIONAL AND ILLUSTRATIVE PURPOSES ONLY,
+TO DEMONSTRATE THE FUNCTIONALITY OF SPECIFIC MONGODB FEATURES.
+THEY ARE NOT PRODUCTION-READY AND MAY LACK THE SECURITY HARDENING, ERROR HANDLING, AND TESTING REQUIRED FOR A LIVE ENVIRONMENT.
+YOU ARE RESPONSIBLE FOR TESTING, VALIDATING, AND SECURING THIS CODE WITHIN YOUR OWN ENVIRONMENT BEFORE IMPLEMENTATION.
+THIS MATERIAL IS PROVIDED "AS IS" WITHOUT WARRANTY OR LIABILITY.
+
+Risk Register — ChromaDB-backed vector search for known risks.
+
+The public API is re-exported here; consumers should import from this package
+rather than from the ``db``/``shared`` submodules, which are implementation
+details. The enrichment functions operate on plain values (a ``list[dict]`` of
+test results, a ``str`` category), so they never depend on any analysis
+module's item types.
+"""
+
+from mongo_x_ray_risk.db import (
+    clear_risks,
+    enrich_test_results,
+    find_risks_by_name,
+    has_risks,
+    ingest_risks,
+    match_risk,
+    search_risks,
+)
+from mongo_x_ray_risk.shared import Risk, load_risks_from_csv
+
+__all__ = [
+    "Risk",
+    "load_risks_from_csv",
+    "ingest_risks",
+    "search_risks",
+    "find_risks_by_name",
+    "clear_risks",
+    "match_risk",
+    "enrich_test_results",
+    "has_risks",
+]

mongo_x_ray_risk-2.0.0/src/mongo_x_ray_risk/db.py

@@ -0,0 +1,259 @@
+"""
+Copyright (c) 2026 MongoDB Inc.
+
+DISCLAIMER: THESE CODE SAMPLES ARE PROVIDED FOR EDUCATIONAL AND ILLUSTRATIVE PURPOSES ONLY,
+TO DEMONSTRATE THE FUNCTIONALITY OF SPECIFIC MONGODB FEATURES.
+THEY ARE NOT PRODUCTION-READY AND MAY LACK THE SECURITY HARDENING, ERROR HANDLING, AND TESTING REQUIRED FOR A LIVE ENVIRONMENT.
+YOU ARE RESPONSIBLE FOR TESTING, VALIDATING, AND SECURING THIS CODE WITHIN YOUR OWN ENVIRONMENT BEFORE IMPLEMENTATION.
+THIS MATERIAL IS PROVIDED "AS IS" WITHOUT WARRANTY OR LIABILITY.
+
+ChromaDB-backed risk register with vector search.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Mapping, Optional
+
+from mongo_x_ray_risk.shared import (
+    CHROMA_COLLECTION,
+    CHROMA_COLLECTION_DESCRIPTION,
+    Risk,
+    get_db_path,
+)
+
+# Mute chromadb telemetry errors (posthog API mismatch)
+logging.getLogger("chromadb.telemetry").setLevel(logging.CRITICAL)
+
+_logger = logging.getLogger(__name__)
+
+
+def _collection(collection_name: str = CHROMA_COLLECTION):
+    """Return an initialized ChromaDB collection (lazy singleton)."""
+    # Import chromadb lazily so importing this module stays cheap and the risk
+    # register remains an optional best-effort enrichment. ChromaDB is not
+    # bundled into the frozen x-ray binary, so a missing import surfaces as a
+    # clear error instead of a raw traceback.
+    try:
+        import chromadb
+        from chromadb.config import Settings
+    except ImportError as exc:
+        raise RuntimeError(
+            "ChromaDB is not available in this build. Install the "
+            "'mongo-x-ray-risk' pip package (which depends on chromadb) "
+            "to use the risk register."
+        ) from exc
+
+    db_path = get_db_path() / "chroma"
+    db_path.mkdir(parents=True, exist_ok=True)
+    client = chromadb.PersistentClient(
+        path=str(db_path),
+        settings=Settings(anonymized_telemetry=False),
+    )
+    return client.get_or_create_collection(collection_name)
+
+
+def ingest_risks(risks: list[Risk]) -> int:
+    """Upsert risks into ChromaDB, returning the number of documents ingested.
+
+    Each risk is embedded twice — once for the ``Name`` field and once for the
+    ``Risk Description`` field — stored in two separate collections so that
+    matching can fall back from Name to Risk Description. Risks without a Risk
+    Description are only embedded in the Name collection. Existing documents
+    with the same ID are replaced (upsert).
+    """
+    if not risks:
+        return 0
+
+    name_col = _collection(CHROMA_COLLECTION)
+    desc_col = _collection(CHROMA_COLLECTION_DESCRIPTION)
+
+    name_ids: list[str] = []
+    name_documents: list[str] = []
+    name_metadatas: list[Mapping[str, Any]] = []
+    desc_ids: list[str] = []
+    desc_documents: list[str] = []
+    desc_metadatas: list[Mapping[str, Any]] = []
+
+    for risk in risks:
+        metadata = {
+            "id": risk.id,
+            "risk_level": risk.risk_level,
+            "impact": risk.impact,
+            "name": risk.name,
+            "description": risk.description,
+        }
+        name_ids.append(risk.id)
+        name_documents.append(risk.name)
+        name_metadatas.append(metadata)
+        if risk.description.strip():
+            desc_ids.append(risk.id)
+            desc_documents.append(risk.description)
+            desc_metadatas.append(metadata)
+
+    name_col.upsert(ids=name_ids, documents=name_documents, metadatas=name_metadatas)
+    if desc_ids:
+        desc_col.upsert(ids=desc_ids, documents=desc_documents, metadatas=desc_metadatas)
+    _logger.info("Ingested %d risks into ChromaDB", len(risks))
+    return len(risks)
+
+
+def search_risks(
+    query: str,
+    n_results: int = 3,
+    collection_name: str = CHROMA_COLLECTION,
+) -> list[dict]:
+    """Vector search for risks matching the query text.
+
+    Args:
+        query: The text to search for.
+        n_results: Maximum number of results to return.
+        collection_name: Which field collection to search; defaults to the
+            risk ``Name`` collection.
+
+    Returns:
+        A list of dicts with keys: id, risk_level, impact, name,
+        description, distance.
+    """
+    col = _collection(collection_name)
+    results = col.query(query_texts=[query], n_results=n_results)
+    entries: list[dict] = []
+    if not results["ids"] or not results["ids"][0]:
+        return entries
+    for i, doc_id in enumerate(results["ids"][0]):
+        meta = results["metadatas"][0][i] if results["metadatas"] else {}
+        distance = results["distances"][0][i] if results["distances"] else None
+        entries.append(
+            {
+                "id": meta.get("id", doc_id),
+                "risk_level": meta.get("risk_level", ""),
+                "impact": meta.get("impact", ""),
+                "name": meta.get("name", ""),
+                "description": meta.get("description", ""),
+                "distance": distance,
+            }
+        )
+    return entries
+
+
+def find_risks_by_name(query: str) -> list[dict]:
+    """Return risks whose ``Name`` contains *query* (case-insensitive).
+
+    Unlike :func:`search_risks` (vector similarity), this is a deterministic
+    substring match on the risk ``Name`` field — the right tool for checking
+    whether a proposed new risk name already exists in the register.
+
+    Args:
+        query: The name fragment to search for. Leading/trailing whitespace
+            is ignored; an empty query matches nothing.
+
+    Returns:
+        A list of dicts with keys: id, risk_level, impact, name, description.
+        Matches are returned in insertion order; no ``distance`` is included.
+    """
+    needle = query.strip().lower()
+    if not needle:
+        return []
+    col = _collection(CHROMA_COLLECTION)
+    got = col.get(include=["metadatas"])
+    entries: list[dict] = []
+    for doc_id, meta in zip(got["ids"], got["metadatas"] or []):
+        meta = meta or {}
+        name = str(meta.get("name", "") or "")
+        if needle in name.lower():
+            entries.append(
+                {
+                    "id": str(meta.get("id", doc_id)),
+                    "risk_level": str(meta.get("risk_level", "") or ""),
+                    "impact": str(meta.get("impact", "") or ""),
+                    "name": name,
+                    "description": str(meta.get("description", "") or ""),
+                }
+            )
+    return entries
+
+
+def clear_risks() -> None:
+    """Delete all documents from all risk collections."""
+    for collection_name in (CHROMA_COLLECTION, CHROMA_COLLECTION_DESCRIPTION):
+        col = _collection(collection_name)
+        ids = col.get()["ids"]
+        if ids:
+            col.delete(ids=ids)
+            _logger.info("Cleared %d risks from %s", len(ids), collection_name)
+
+
+def _collection_count() -> int:
+    """Return the number of documents in the Name collection."""
+    col = _collection(CHROMA_COLLECTION)
+    return col.count()
+
+
+def has_risks() -> bool:
+    """Return True if the risk register contains any ingested risks.
+
+    Never raises: a missing/corrupt ChromaDB or an empty register both mean
+    ``False``, so callers can decide whether to show risk-related UI.
+    """
+    try:
+        return _collection_count() > 0
+    except Exception:
+        return False
+
+
+def match_risk(category: str, max_distance: float = 0.9) -> Optional[dict]:
+    """Find the closest matching risk for a given issue.
+
+    Two-stage fallback search:
+    1. Match ``category`` against the risk ``Name`` field.
+    2. If no ``Name`` match is found, fall back to matching the same
+       ``category`` against the risk ``Risk Description`` field.
+
+    Args:
+        category: The issue category to match — the ``Alert Category``
+            column in the reports (each item's ``title``).
+        max_distance: Maximum vector distance for a match to be considered
+            valid. Lower values mean closer matches. Default 0.9.
+
+    Returns:
+        The best matching risk dict, or ``None`` if no match found.
+    """
+    for collection_name in (CHROMA_COLLECTION, CHROMA_COLLECTION_DESCRIPTION):
+        results = search_risks(category, n_results=1, collection_name=collection_name)
+        if not results:
+            continue
+        top = results[0]
+        if top["distance"] is not None and top["distance"] > max_distance:
+            continue
+        return top
+    return None
+
+
+def enrich_test_results(test_results: list[dict], max_distance: float = 0.9) -> int:
+    """Enrich a list of test results with matched risk information.
+
+    Each result dict that has a ``title`` key (the ``Alert Category`` column
+    in the reports) will be matched against the risk register's ``Name``
+    field using the two-stage fallback search. If a match is found, a
+    ``matched_risk`` key is added.
+
+    Args:
+        test_results: List of test result dicts (each has a ``title`` key).
+        max_distance: Maximum vector distance for a match.
+
+    Returns:
+        Number of results that were successfully matched to a risk.
+    """
+    if _collection_count() == 0:
+        _logger.warning("\033[33mRisk register is empty — run `x-ray ingest <csv>` first\033[0m")
+        return 0
+    matched = 0
+    for result in test_results:
+        title = result.get("title", "")
+        if not title:
+            continue
+        risk = match_risk(title, max_distance=max_distance)
+        if risk:
+            result["matched_risk"] = risk
+            matched += 1
+    return matched

mongo_x_ray_risk-2.0.0/src/mongo_x_ray_risk/plugin.py

@@ -0,0 +1,144 @@
+"""
+Copyright (c) 2026 MongoDB Inc.
+
+DISCLAIMER: THESE CODE SAMPLES ARE PROVIDED FOR EDUCATIONAL AND ILLUSTRATIVE PURPOSES ONLY,
+TO DEMONSTRATE THE FUNCTIONALITY OF SPECIFIC MONGODB FEATURES.
+THEY ARE NOT PRODUCTION-READY AND MAY LACK THE SECURITY HARDENING, ERROR HANDLING, AND TESTING REQUIRED FOR A LIVE ENVIRONMENT.
+YOU ARE RESPONSIBLE FOR TESTING, VALIDATING, AND SECURING THIS CODE WITHIN YOUR OWN ENVIRONMENT BEFORE IMPLEMENTATION.
+THIS MATERIAL IS PROVIDED "AS IS" WITHOUT WARRANTY OR LIABILITY.
+"""
+
+import logging
+from pathlib import Path
+
+from mongo_x_ray.plugin import Plugin
+from mongo_x_ray_risk import (
+    clear_risks,
+    find_risks_by_name,
+    ingest_risks,
+    load_risks_from_csv,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class IngestPlugin(Plugin):
+    name = "ingest"
+    distribution = "mongo-x-ray-risk"
+    help = "Ingest a risk register CSV into the risk knowledge base"
+    description = """
+Ingest a risk register CSV into the ChromaDB-backed risk knowledge base used
+by the analysis plugins (healthcheck, log, gmd) to match findings against
+known risks.
+
+The CSV must have the following columns:
+  ID, Risk level, Impact, Name, Risk description
+
+Header names are matched case-insensitively; any other columns (e.g.
+Other Notes) are ignored. Rows without an ID or a Name are skipped. Existing
+entries with the same ID are replaced; use --clear to start from an empty
+register.
+
+Run 'x-ray ingest --clear' alone to clear the register without a CSV.
+"""
+    epilog = """
+Examples:
+  x-ray ingest risk_register.csv
+  x-ray ingest --clear risk_register.csv   # clear, then ingest
+  x-ray ingest --clear                      # clear only
+"""
+
+    def add_arguments(self, parser):
+        parser.add_argument("csv", nargs="?", help="Path to the risk register CSV file.")
+        parser.add_argument(
+            "--clear",
+            help="Clear the existing risk register before ingesting.",
+            action="store_true",
+            default=False,
+        )
+
+    def run(self, args) -> int:
+        """Clear the risk register and/or ingest a CSV, reporting what was done."""
+        if not args.csv:
+            if args.clear:
+                try:
+                    clear_risks()
+                except Exception as exc:
+                    logger.error("Risk register unavailable: %s", exc)
+                    return 1
+                logger.info("Cleared the existing risk register")
+                return 0
+            logger.error(
+                "No CSV file given. Use 'x-ray ingest <csv>' to ingest, "
+                "or 'x-ray ingest --clear' to clear the register."
+            )
+            return 1
+        csv_path = Path(args.csv)
+        if not csv_path.is_file():
+            logger.error("CSV file not found: %s", csv_path)
+            return 1
+        try:
+            risks = load_risks_from_csv(csv_path)
+        except Exception as exc:
+            logger.error("Failed to read CSV %s: %s", csv_path, exc)
+            return 1
+        if not risks:
+            logger.error(
+                "No valid risk rows found in %s (expected columns: ID, Risk level, Impact, Name, Risk description)",
+                csv_path,
+            )
+            return 1
+        try:
+            if args.clear:
+                clear_risks()
+                logger.info("Cleared the existing risk register")
+            count = ingest_risks(risks)
+            logger.info("Ingested %d risks into the risk register", count)
+            return 0
+        except Exception as exc:
+            logger.error("Risk register unavailable: %s", exc)
+            return 1
+
+
+class SearchPlugin(Plugin):
+    name = "search"
+    distribution = "mongo-x-ray-risk"
+    help = "Search the risk register for risks by name"
+    description = """
+Search the risk register for risks whose Name contains the given string
+(case-insensitive substring match). Use it to check whether a newly
+suggested risk is already known before adding it to the register.
+
+For every matching risk the Name and Risk description are printed.
+
+Exits 0 when at least one risk matches, 1 when nothing matches (so callers
+can tell "already known" from "new risk").
+"""
+    epilog = """
+Examples:
+  x-ray search "Replication Lag"
+  x-ray search replication
+"""
+
+    def add_arguments(self, parser):
+        parser.add_argument("string", help="Risk name (or part of one) to search for.")
+
+    def run(self, args) -> int:
+        """Search the register by risk name and print matching risks."""
+        query = (args.string or "").strip()
+        if not query:
+            logger.error("No search string given. Use 'x-ray search <string>'.")
+            return 1
+        try:
+            matches = find_risks_by_name(query)
+        except Exception as exc:
+            logger.error("Failed to search the risk register: %s", exc)
+            return 1
+        if not matches:
+            logger.info("No risks found matching %r", query)
+            return 1
+        for risk in matches:
+            print(f"Name: {risk['name']}")
+            print(f"Risk description: {risk['description']}")
+            print()
+        return 0

mongo_x_ray_risk-2.0.0/src/mongo_x_ray_risk/shared.py

@@ -0,0 +1,78 @@
+"""
+Copyright (c) 2026 MongoDB Inc.
+
+DISCLAIMER: THESE CODE SAMPLES ARE PROVIDED FOR EDUCATIONAL AND ILLUSTRATIVE PURPOSES ONLY,
+TO DEMONSTRATE THE FUNCTIONALITY OF SPECIFIC MONGODB FEATURES.
+THEY ARE NOT PRODUCTION-READY AND MAY LACK THE SECURITY HARDENING, ERROR HANDLING, AND TESTING REQUIRED FOR A LIVE ENVIRONMENT.
+YOU ARE RESPONSIBLE FOR TESTING, VALIDATING, AND SECURING THIS CODE WITHIN YOUR OWN ENVIRONMENT BEFORE IMPLEMENTATION.
+THIS MATERIAL IS PROVIDED "AS IS" WITHOUT WARRANTY OR LIABILITY.
+
+Shared constants and data model for the Risk Register module.
+"""
+
+from __future__ import annotations
+
+import csv
+from dataclasses import dataclass
+from pathlib import Path
+
+# Embed the Risk Name and Risk Description fields for vector search.
+# Each field lives in its own collection so matching can fall back from
+# Name to Risk Description.
+CHROMA_COLLECTION = "risk_register"
+CHROMA_COLLECTION_DESCRIPTION = "risk_register_description"
+EMBED_FIELDS = ("Name", "Risk Description")
+
+
+@dataclass
+class Risk:
+    """A single risk entry from the CSV risk register."""
+
+    id: str
+    risk_level: str
+    impact: str
+    name: str
+    description: str
+
+
+def _normalize_header(header: str) -> str:
+    """Normalize a CSV header for case/whitespace-insensitive matching."""
+    return (header or "").strip().lower()
+
+
+def load_risks_from_csv(csv_path: Path) -> list[Risk]:
+    """Parse a CSV risk register file.
+
+    Used columns (matched case-insensitively; any other columns, e.g.
+    ``Other Notes``, are ignored):
+        ID, Risk level, Impact, Name, Risk description
+
+    Rows without an ID or a Name are skipped.
+    """
+    risks: list[Risk] = []
+    with open(csv_path, newline="", encoding="utf-8-sig") as fh:
+        reader = csv.DictReader(fh)
+        headers = {_normalize_header(h): h for h in (reader.fieldnames or [])}
+        for row in reader:
+            risk = Risk(
+                id=(row.get(headers.get("id", "")) or "").strip(),
+                risk_level=(row.get(headers.get("risk level", "")) or "").strip(),
+                impact=(row.get(headers.get("impact", "")) or "").strip(),
+                name=(row.get(headers.get("name", "")) or "").strip(),
+                description=(row.get(headers.get("risk description", "")) or "").strip(),
+            )
+            if risk.id and risk.name:
+                risks.append(risk)
+    return risks
+
+
+def get_db_path() -> Path:
+    """Return the platform-specific database directory path."""
+    import platform
+
+    system = platform.system()
+    if system == "Windows":
+        base = Path.home() / "AppData" / "Roaming"
+    else:
+        base = Path.home()
+    return base / ".x-ray"

mongo_x_ray_risk-2.0.0/src/mongo_x_ray_risk.egg-info/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: mongo-x-ray-risk
+Version: 2.0.0
+Summary: Known-risks knowledge base (ChromaDB vector search) for x-ray
+Requires-Python: <4,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mongo-x-ray>=2.0.0
+Requires-Dist: chromadb==1.5.9
+
+# mongo-x-ray-risk
+
+[![CI](https://github.com/zhangyaoxing/mongo-x-ray-risk/actions/workflows/ci.yml/badge.svg)](https://github.com/zhangyaoxing/mongo-x-ray-risk/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mongo-x-ray-risk.svg)](https://pypi.org/project/mongo-x-ray-risk/)
+
+Known-risks knowledge base for [x-ray](https://github.com/mongodb-ps/ce-mongo-x-ray): a ChromaDB-backed
+vector search that matches analysis findings against known MongoDB risks.
+
+This is an optional plugin: it ships the `ingest` command to load the risk register, the `search`
+command to look risks up by name, and the analysis plugins (healthcheck, log, gmd) detect it at
+runtime — when it is installed, their reports are enriched with matched risks; when it is missing,
+the enrichment is silently skipped.
+
+## Install
+
+```bash
+pip install mongo-x-ray mongo-x-ray-risk
+```
+
+## Usage
+
+Load a risk register CSV into the ChromaDB knowledge base:
+
+```bash
+x-ray ingest risk_register.csv
+# start from an empty register, then ingest
+x-ray ingest --clear risk_register.csv
+# clear the register without ingesting (no CSV needed)
+x-ray ingest --clear
+```
+
+Check whether a risk is already known by searching the `Name` column
+(case-insensitive substring match). Prints the `Name` and `Risk description`
+of every matching risk; exits 0 when something matches, 1 when nothing does:
+
+```bash
+x-ray search "Replication Lag"
+x-ray search replication
+```
+
+The CSV must have the columns `ID, Risk level, Impact, Name, Risk description`
+(UTF-8, a BOM is tolerated; header names are matched case-insensitively). Any
+other columns, such as `Other Notes`, are ignored. Rows without an ID or a
+Name are skipped; entries with an existing ID are replaced. The data is
+stored under `~/.x-ray/chroma`.
+
+Once ingested, the plugin is used automatically by the other plugins — no CLI
+flags needed. It also exposes a small API for tooling:
+
+```python
+from mongo_x_ray_risk import Risk, load_risks_from_csv, ingest_risks, match_risk, enrich_test_results
+```
+
+## Development
+
+Requires Python 3.10+, MongoDB 5.0 or later, and the [mongo-x-ray](https://github.com/mongodb-ps/ce-mongo-x-ray) core package.
+
+```bash
+make unit-test   # run the unit tests
+make lint        # ruff check + ruff format --check
+```

mongo_x_ray_risk-2.0.0/src/mongo_x_ray_risk.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+src/mongo_x_ray_risk/__init__.py
+src/mongo_x_ray_risk/db.py
+src/mongo_x_ray_risk/plugin.py
+src/mongo_x_ray_risk/shared.py
+src/mongo_x_ray_risk.egg-info/PKG-INFO
+src/mongo_x_ray_risk.egg-info/SOURCES.txt
+src/mongo_x_ray_risk.egg-info/dependency_links.txt
+src/mongo_x_ray_risk.egg-info/entry_points.txt
+src/mongo_x_ray_risk.egg-info/requires.txt
+src/mongo_x_ray_risk.egg-info/top_level.txt
+tests/test_csv_parsing.py
+tests/test_ingest_plugin.py
+tests/test_risk_register.py
+tests/test_search_plugin.py

mongo_x_ray_risk-2.0.0/src/mongo_x_ray_risk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mongo_x_ray_risk-2.0.0/src/mongo_x_ray_risk.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[mongo_x_ray.plugins]
+ingest = mongo_x_ray_risk.plugin:IngestPlugin
+search = mongo_x_ray_risk.plugin:SearchPlugin

mongo_x_ray_risk-2.0.0/src/mongo_x_ray_risk.egg-info/requires.txt

@@ -0,0 +1,2 @@
+mongo-x-ray>=2.0.0
+chromadb==1.5.9

mongo_x_ray_risk-2.0.0/src/mongo_x_ray_risk.egg-info/top_level.txt

@@ -0,0 +1 @@
+mongo_x_ray_risk

mongo_x_ray_risk-2.0.0/tests/test_csv_parsing.py

@@ -0,0 +1,76 @@
+"""
+Copyright (c) 2026 MongoDB Inc.
+
+DISCLAIMER: THESE CODE SAMPLES ARE PROVIDED FOR EDUCATIONAL AND ILLUSTRATIVE PURPOSES ONLY,
+TO DEMONSTRATE THE FUNCTIONALITY OF SPECIFIC MONGODB FEATURES.
+THEY ARE NOT PRODUCTION-READY AND MAY LACK THE SECURITY HARDENING, ERROR HANDLING, AND TESTING REQUIRED FOR A LIVE ENVIRONMENT.
+YOU ARE RESPONSIBLE FOR TESTING, VALIDATING, AND SECURING THIS CODE WITHIN YOUR OWN ENVIRONMENT BEFORE IMPLEMENTATION.
+THIS MATERIAL IS PROVIDED "AS IS" WITHOUT WARRANTY OR LIABILITY.
+
+Tests for CSV risk register parsing.
+"""
+
+from mongo_x_ray_risk.shared import load_risks_from_csv
+
+
+def _write(tmp_path, text, name="risks.csv"):
+    path = tmp_path / name
+    path.write_text(text, encoding="utf-8")
+    return path
+
+
+def test_parses_new_column_names_and_ignores_other_notes(tmp_path):
+    csv_path = _write(
+        tmp_path,
+        "ID,Risk level,Impact,Name,Risk description,Other Notes\n"
+        "R1,High,Medium,Replication Lag,oplog falls behind,internal note\n"
+        "R2,Medium,Low,Missing Index,no matching index,\n",
+    )
+    risks = load_risks_from_csv(csv_path)
+    assert [r.id for r in risks] == ["R1", "R2"]
+    assert risks[0].risk_level == "High"
+    assert risks[0].impact == "Medium"
+    assert risks[0].name == "Replication Lag"
+    assert risks[0].description == "oplog falls behind"
+    assert risks[1].description == "no matching index"
+
+
+def test_accepts_old_casing_of_headers(tmp_path):
+    csv_path = _write(
+        tmp_path,
+        "ID,Risk Level,Impact,Name,Risk Description\nR1,High,Medium,Replication Lag,oplog falls behind\n",
+    )
+    risks = load_risks_from_csv(csv_path)
+    assert risks[0].risk_level == "High"
+    assert risks[0].description == "oplog falls behind"
+
+
+def test_ignores_unknown_columns(tmp_path):
+    csv_path = _write(
+        tmp_path,
+        "ID,Risk level,Impact,Name,Risk description,Random field,Owner\n"
+        "R1,High,Medium,Replication Lag,oplog falls behind,whatever,alice\n",
+    )
+    risks = load_risks_from_csv(csv_path)
+    assert len(risks) == 1
+    assert risks[0].id == "R1"
+
+
+def test_skips_rows_without_id_or_name(tmp_path):
+    csv_path = _write(
+        tmp_path,
+        "ID,Risk level,Impact,Name,Risk description\n"
+        "R1,High,Medium,Replication Lag,oplog falls behind\n"
+        ",High,Medium,No Id,has id? no\n"
+        "R3,Low,Low,,no name\n",
+    )
+    risks = load_risks_from_csv(csv_path)
+    assert [r.id for r in risks] == ["R1"]
+
+
+def test_handles_bom_utf8(tmp_path):
+    csv_path = tmp_path / "bom.csv"
+    csv_path.write_bytes(b"\xef\xbb\xbfID,Risk level,Impact,Name,Risk description\nR1,Low,Low,Backup Failure,failing\n")
+    risks = load_risks_from_csv(csv_path)
+    assert risks[0].id == "R1"
+    assert risks[0].name == "Backup Failure"

mongo_x_ray_risk-2.0.0/tests/test_ingest_plugin.py

@@ -0,0 +1,102 @@
+"""
+Copyright (c) 2026 MongoDB Inc.
+
+DISCLAIMER: THESE CODE SAMPLES ARE PROVIDED FOR EDUCATIONAL AND ILLUSTRATIVE PURPOSES ONLY,
+TO DEMONSTRATE THE FUNCTIONALITY OF SPECIFIC MONGODB FEATURES.
+THEY ARE NOT PRODUCTION-READY AND MAY LACK THE SECURITY HARDENING, ERROR HANDLING, AND TESTING REQUIRED FOR A LIVE ENVIRONMENT.
+YOU ARE RESPONSIBLE FOR TESTING, VALIDATING, AND SECURING THIS CODE WITHIN YOUR OWN ENVIRONMENT BEFORE IMPLEMENTATION.
+THIS MATERIAL IS PROVIDED "AS IS" WITHOUT WARRANTY OR LIABILITY.
+
+Tests for the risk register ``ingest`` command plugin.
+"""
+
+import argparse
+
+from mongo_x_ray_risk.plugin import IngestPlugin
+
+
+def _args(**overrides) -> argparse.Namespace:
+    ns = argparse.Namespace(csv=None, clear=False)
+    ns.__dict__.update(overrides)
+    return ns
+
+
+def test_plugin_metadata():
+    assert IngestPlugin.name == "ingest"
+    assert IngestPlugin.distribution == "mongo-x-ray-risk"
+    assert "CSV" in IngestPlugin.help
+    assert "ID, Risk level, Impact, Name, Risk description" in IngestPlugin.description
+    assert "Other Notes" in IngestPlugin.description
+    assert "x-ray ingest risk_register.csv" in IngestPlugin.epilog
+
+
+def test_run_ingests_csv_rows(monkeypatch, tmp_path):
+    csv_path = tmp_path / "risks.csv"
+    csv_path.write_text(
+        "ID,Risk level,Impact,Name,Risk description,Other Notes\n"
+        "R1,High,Medium,Replication Lag,oplog falls behind,internal note\n"
+        "R2,Medium,Low,Missing Index,no matching index,\n"
+        ",,Low,No Id Here,skipped,note\n",
+        encoding="utf-8",
+    )
+    seen = {}
+
+    def fake_ingest(risks):
+        seen["risks"] = risks
+        return len(risks)
+
+    monkeypatch.setattr("mongo_x_ray_risk.plugin.ingest_risks", fake_ingest)
+
+    assert IngestPlugin().run(_args(csv=str(csv_path))) == 0
+    assert [r.id for r in seen["risks"]] == ["R1", "R2"]
+    assert seen["risks"][0].name == "Replication Lag"
+    assert seen["risks"][0].risk_level == "High"
+    assert seen["risks"][0].impact == "Medium"
+    assert seen["risks"][0].description == "oplog falls behind"
+
+
+def test_run_clear_empties_register_first(monkeypatch, tmp_path):
+    csv_path = tmp_path / "risks.csv"
+    csv_path.write_text("ID,Risk level,Impact,Name,Risk description\nR1,Low,Low,One Risk,x\n", encoding="utf-8")
+    cleared = []
+    monkeypatch.setattr("mongo_x_ray_risk.plugin.clear_risks", lambda: cleared.append(True))
+    monkeypatch.setattr("mongo_x_ray_risk.plugin.ingest_risks", len)
+
+    assert IngestPlugin().run(_args(csv=str(csv_path), clear=True)) == 0
+    assert cleared == [True]
+
+
+def test_run_clear_without_csv_only_clears(monkeypatch):
+    cleared = []
+    ingest_called = []
+    monkeypatch.setattr("mongo_x_ray_risk.plugin.clear_risks", lambda: cleared.append(True))
+    monkeypatch.setattr("mongo_x_ray_risk.plugin.ingest_risks", lambda risks: ingest_called.append(risks))
+
+    assert IngestPlugin().run(_args(clear=True)) == 0
+    assert cleared == [True]
+    assert ingest_called == []
+
+
+def test_run_without_csv_or_clear_returns_error():
+    assert IngestPlugin().run(_args()) == 1
+
+
+def test_run_missing_csv_returns_error(tmp_path):
+    assert IngestPlugin().run(_args(csv=str(tmp_path / "nope.csv"))) == 1
+
+
+def test_run_csv_without_valid_rows_returns_error(tmp_path):
+    csv_path = tmp_path / "empty.csv"
+    csv_path.write_text("ID,Risk level,Impact,Name,Risk description\n", encoding="utf-8")
+    assert IngestPlugin().run(_args(csv=str(csv_path))) == 1
+
+
+def test_run_unreadable_csv_returns_error(monkeypatch, tmp_path):
+    csv_path = tmp_path / "broken.csv"
+    csv_path.write_text("x\n", encoding="utf-8")
+
+    def boom(_path):
+        raise OSError("boom")
+
+    monkeypatch.setattr("mongo_x_ray_risk.plugin.load_risks_from_csv", boom)
+    assert IngestPlugin().run(_args(csv=str(csv_path))) == 1

mongo_x_ray_risk-2.0.0/tests/test_risk_register.py

@@ -0,0 +1,245 @@
+"""
+Copyright (c) 2026 MongoDB Inc.
+
+DISCLAIMER: THESE CODE SAMPLES ARE PROVIDED FOR EDUCATIONAL AND ILLUSTRATIVE PURPOSES ONLY,
+TO DEMONSTRATE THE FUNCTIONALITY OF SPECIFIC MONGODB FEATURES.
+THEY ARE NOT PRODUCTION-READY AND MAY LACK THE SECURITY HARDENING, ERROR HANDLING, AND TESTING REQUIRED FOR A LIVE ENVIRONMENT.
+YOU ARE RESPONSIBLE FOR TESTING, VALIDATING, AND SECURING THIS CODE WITHIN YOUR OWN ENVIRONMENT BEFORE IMPLEMENTATION.
+THIS MATERIAL IS PROVIDED "AS IS" WITHOUT WARRANTY OR LIABILITY.
+"""
+
+import pytest
+
+from mongo_x_ray_risk import db
+from mongo_x_ray_risk.shared import (
+    CHROMA_COLLECTION,
+    CHROMA_COLLECTION_DESCRIPTION,
+    Risk,
+)
+
+RISK_R1 = {
+    "id": "R1",
+    "risk_level": "High",
+    "impact": "Medium",
+    "name": "Replication Lag",
+    "description": "oplog falls behind",
+    "distance": 0.1,
+}
+
+
+def test_match_risk_uses_name_collection_first(monkeypatch):
+    calls = []
+
+    def fake_search(query, n_results=3, collection_name=CHROMA_COLLECTION):
+        calls.append((query, n_results, collection_name))
+        return [dict(RISK_R1)]
+
+    monkeypatch.setattr(db, "search_risks", fake_search)
+
+    risk = db.match_risk("Replication Lag")
+
+    assert risk == RISK_R1
+    assert calls == [("Replication Lag", 1, CHROMA_COLLECTION)]
+
+
+def test_match_risk_falls_back_to_description_with_same_query(monkeypatch):
+    calls = []
+
+    def fake_search(query, n_results=3, collection_name=CHROMA_COLLECTION):
+        calls.append((query, n_results, collection_name))
+        if collection_name == CHROMA_COLLECTION:
+            return []
+        return [dict(RISK_R1)]
+
+    monkeypatch.setattr(db, "search_risks", fake_search)
+
+    risk = db.match_risk("Unrelated Topic")
+
+    assert risk == RISK_R1
+    assert calls == [
+        ("Unrelated Topic", 1, CHROMA_COLLECTION),
+        ("Unrelated Topic", 1, CHROMA_COLLECTION_DESCRIPTION),
+    ]
+
+
+def test_match_risk_falls_back_when_name_match_is_too_far(monkeypatch):
+    calls = []
+
+    def fake_search(query, n_results=3, collection_name=CHROMA_COLLECTION):
+        calls.append((query, n_results, collection_name))
+        far = dict(RISK_R1)
+        far["distance"] = 2.0
+        return [far] if collection_name == CHROMA_COLLECTION else [dict(RISK_R1)]
+
+    monkeypatch.setattr(db, "search_risks", fake_search)
+
+    risk = db.match_risk("Replication Lag", max_distance=1.0)
+
+    assert risk == RISK_R1
+    assert len(calls) == 2
+
+
+def test_match_risk_returns_none_when_both_stages_miss(monkeypatch):
+    def fake_search(query, n_results=3, collection_name=CHROMA_COLLECTION):
+        return []
+
+    monkeypatch.setattr(db, "search_risks", fake_search)
+
+    assert db.match_risk("Unrelated Topic") is None
+
+
+def test_has_risks_reflects_collection_count(monkeypatch):
+    monkeypatch.setattr(db, "_collection_count", lambda: 3)
+    assert db.has_risks() is True
+    monkeypatch.setattr(db, "_collection_count", lambda: 0)
+    assert db.has_risks() is False
+
+
+def test_has_risks_returns_false_when_chromadb_unavailable(monkeypatch):
+    def boom():
+        raise RuntimeError("chromadb unavailable")
+
+    monkeypatch.setattr(db, "_collection_count", boom)
+    assert db.has_risks() is False
+
+
+def test_enrich_test_results_matches_by_title(monkeypatch):
+    monkeypatch.setattr(db, "_collection_count", lambda: 1)
+    captured = {}
+
+    def fake_match_risk(title, max_distance=1.0):
+        captured["title"] = title
+        return dict(RISK_R1)
+
+    monkeypatch.setattr(db, "match_risk", fake_match_risk)
+
+    results = [{"host": "h", "severity": "High", "title": "Replication Lag", "message": "secondary oplog behind"}]
+    matched = db.enrich_test_results(results)
+
+    assert matched == 1
+    assert results[0]["matched_risk"] == RISK_R1
+    assert captured == {"title": "Replication Lag"}
+
+
+class _FakeNameCollection:
+    """Minimal stand-in for a Chroma collection of risk names."""
+
+    def __init__(self, metadatas):
+        self._metadatas = metadatas
+
+    def get(self, include=None):
+        return {"ids": [m["id"] for m in self._metadatas], "metadatas": self._metadatas}
+
+
+def _install_fake_collection(monkeypatch, metadatas):
+    monkeypatch.setattr(db, "_collection", lambda name: _FakeNameCollection(metadatas))
+
+
+def test_find_risks_by_name_matches_substring_case_insensitive(monkeypatch):
+    _install_fake_collection(
+        monkeypatch,
+        [
+            {
+                "id": "R1",
+                "risk_level": "High",
+                "impact": "Medium",
+                "name": "Replication Lag",
+                "description": "oplog falls behind",
+            },
+            {
+                "id": "R2",
+                "risk_level": "Medium",
+                "impact": "Low",
+                "name": "Missing Index",
+                "description": "no matching index",
+            },
+        ],
+    )
+    hits = db.find_risks_by_name("replication")
+    assert [h["id"] for h in hits] == ["R1"]
+    assert hits[0]["name"] == "Replication Lag"
+    assert hits[0]["description"] == "oplog falls behind"
+
+
+def test_find_risks_by_name_returns_all_matching(monkeypatch):
+    _install_fake_collection(
+        monkeypatch,
+        [
+            {"id": "R1", "risk_level": "High", "impact": "Medium", "name": "Replication Lag", "description": "a"},
+            {"id": "R2", "risk_level": "Medium", "impact": "Low", "name": "Index on Replication", "description": "b"},
+            {"id": "R3", "risk_level": "Low", "impact": "Low", "name": "Backup Failure", "description": "c"},
+        ],
+    )
+    hits = db.find_risks_by_name("replication")
+    assert [h["id"] for h in hits] == ["R1", "R2"]
+
+
+def test_find_risks_by_name_no_match_returns_empty_list(monkeypatch):
+    _install_fake_collection(
+        monkeypatch,
+        [
+            {
+                "id": "R1",
+                "risk_level": "High",
+                "impact": "Medium",
+                "name": "Replication Lag",
+                "description": "oplog falls behind",
+            }
+        ],
+    )
+    assert db.find_risks_by_name("Unrelated Topic XYZ") == []
+
+
+def test_find_risks_by_name_empty_query_returns_empty_list(monkeypatch):
+    _install_fake_collection(monkeypatch, [])
+    assert db.find_risks_by_name("   ") == []
+
+
+@pytest.mark.integration
+def test_ingest_and_two_stage_search(tmp_path, monkeypatch):
+    monkeypatch.setattr(db, "get_db_path", lambda: tmp_path)
+
+    risks = [
+        Risk(
+            id="R1",
+            risk_level="High",
+            impact="Medium",
+            name="Replication Lag",
+            description="Replication lag occurs when the secondary's oplog application falls behind the primary.",
+        ),
+        Risk(
+            id="R2",
+            risk_level="Medium",
+            impact="Low",
+            name="Missing Index",
+            description="Queries scan the entire collection because no matching index exists.",
+        ),
+        Risk(id="R3", risk_level="Low", impact="Low", name="Backup Failure", description="   "),
+    ]
+
+    assert db.ingest_risks(risks) == 3
+
+    name_col = db._collection(CHROMA_COLLECTION)
+    desc_col = db._collection(CHROMA_COLLECTION_DESCRIPTION)
+    assert name_col.count() == 3
+    assert desc_col.count() == 2  # R3 has no Risk Description
+
+    # Stage 1: title matches risk Name.
+    title_risk = db.match_risk("Replication Lag")
+    assert title_risk is not None
+    assert title_risk["id"] == "R1"
+    index_risk = db.match_risk("Missing Index")
+    assert index_risk is not None
+    assert index_risk["id"] == "R2"
+
+    # Stage 2: Name misses, the same title matches Risk Description.
+    risk = db.match_risk("the secondary's oplog application falls behind the primary")
+    assert risk is not None and risk["id"] == "R1"
+
+    # No match at either stage.
+    assert db.match_risk("Unrelated Topic XYZ") is None
+
+    # clear_risks empties both collections.
+    db.clear_risks()
+    assert name_col.count() == 0
+    assert desc_col.count() == 0

mongo_x_ray_risk-2.0.0/tests/test_search_plugin.py

@@ -0,0 +1,79 @@
+"""
+Copyright (c) 2026 MongoDB Inc.
+
+DISCLAIMER: THESE CODE SAMPLES ARE PROVIDED FOR EDUCATIONAL AND ILLUSTRATIVE PURPOSES ONLY,
+TO DEMONSTRATE THE FUNCTIONALITY OF SPECIFIC MONGODB FEATURES.
+THEY ARE NOT PRODUCTION-READY AND MAY LACK THE SECURITY HARDENING, ERROR HANDLING, AND TESTING REQUIRED FOR A LIVE ENVIRONMENT.
+YOU ARE RESPONSIBLE FOR TESTING, VALIDATING, AND SECURING THIS CODE WITHIN YOUR OWN ENVIRONMENT BEFORE IMPLEMENTATION.
+THIS MATERIAL IS PROVIDED "AS IS" WITHOUT WARRANTY OR LIABILITY.
+
+Tests for the risk register ``search`` command plugin.
+"""
+
+import argparse
+
+from mongo_x_ray_risk.plugin import SearchPlugin
+
+
+def _args(**overrides) -> argparse.Namespace:
+    ns = argparse.Namespace(string=None)
+    ns.__dict__.update(overrides)
+    return ns
+
+
+def test_plugin_metadata():
+    assert SearchPlugin.name == "search"
+    assert SearchPlugin.distribution == "mongo-x-ray-risk"
+    assert "risk register" in SearchPlugin.help
+    assert "case-insensitive" in SearchPlugin.description
+    assert "x-ray search" in SearchPlugin.epilog
+
+
+def test_run_prints_matching_risks(monkeypatch, capsys):
+    matches = [
+        {
+            "id": "R1",
+            "risk_level": "High",
+            "impact": "Medium",
+            "name": "Replication Lag",
+            "description": "oplog falls behind",
+        },
+        {
+            "id": "R2",
+            "risk_level": "Medium",
+            "impact": "Low",
+            "name": "Missing Index",
+            "description": "no matching index",
+        },
+    ]
+    seen = {}
+
+    def fake_find(query):
+        seen["query"] = query
+        return matches
+
+    monkeypatch.setattr("mongo_x_ray_risk.plugin.find_risks_by_name", fake_find)
+
+    assert SearchPlugin().run(_args(string="Replication")) == 0
+    assert seen == {"query": "Replication"}
+    out = capsys.readouterr().out
+    assert "Name: Replication Lag" in out
+    assert "Risk description: oplog falls behind" in out
+    assert "Name: Missing Index" in out
+
+
+def test_run_no_match_returns_1(monkeypatch):
+    monkeypatch.setattr("mongo_x_ray_risk.plugin.find_risks_by_name", lambda query: [])
+    assert SearchPlugin().run(_args(string="Nothing Here")) == 1
+
+
+def test_run_empty_string_returns_error():
+    assert SearchPlugin().run(_args(string="   ")) == 1
+
+
+def test_run_search_failure_returns_error(monkeypatch):
+    def boom(_query):
+        raise RuntimeError("chromadb unavailable")
+
+    monkeypatch.setattr("mongo_x_ray_risk.plugin.find_risks_by_name", boom)
+    assert SearchPlugin().run(_args(string="Replication")) == 1