cwe-explorer 0.1.0__py3-none-any.whl

cwe_explorer/__init__.py

@@ -0,0 +1,3 @@
+"""Explorador de la jerarquía CWE (vista 1000 de MITRE) en la terminal y en el navegador."""
+
+__version__ = "0.1.0"

cwe_explorer/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

cwe_explorer/cli.py

@@ -0,0 +1,181 @@
+"""Punto de entrada: ``cwex 79`` (terminal), ``--tui`` (interactivo) o ``--web`` (navegador)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import webbrowser
+
+from . import __version__
+from .data import cache_dir, load_catalog
+from .hierarchy import CWENotFound, Hierarchy
+from .render_html import write_html
+from .render_term import BADGES, print_relatives, print_tree, to_ansi, use_color
+
+DEFAULT_DEPTH = 2  # árbol, --tui y --web
+DEFAULT_LIST_DEPTH = 1  # --ancestors / --descendants: sólo los directos
+UNSET = object()  # distingue «sin --depth» de «--depth all» (None)
+
+
+def parse_depth(raw: str) -> int | None:
+    if raw.lower() in ("all", "todos", "todo", "*"):
+        return None
+    try:
+        value = int(raw)
+    except ValueError:
+        raise argparse.ArgumentTypeError("usa un número >= 0 o 'all'") from None
+    if value < 0:
+        raise argparse.ArgumentTypeError("usa un número >= 0 o 'all'")
+    return value
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cwex",
+        description="Muestra la jerarquía de una CWE en la vista 1000 de MITRE "
+        "(Complete Weakness Hierarchy) en la terminal o en el navegador.",
+        epilog="Ejemplos:\n"
+        "  cwex 79                 árbol en la terminal\n"
+        "  cwex CWE-79 --tui       explorador interactivo (ratón y teclado)\n"
+        "  cwex 79 --web           grafo interactivo en el navegador\n"
+        "  cwex 664 --depth all    todos los descendientes\n"
+        "  cwex --search overflow  buscar por nombre\n"
+        "  cwex 79 --ancestors              padres directos (modo 1)\n"
+        "  cwex 79 --descendants            hijos directos (modo 2)\n"
+        "  cwex 82 --ancestors --depth all  todos los ascendientes hasta el pilar\n"
+        "  cwex 664 --descendants -d all --json   todos los descendientes en JSON",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("cwe", nargs="?", help="identificador CWE (79, CWE-79...)")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument("--tui", action="store_true", help="explorador interactivo en la terminal")
+    mode.add_argument("--web", action="store_true", help="genera el grafo HTML y lo abre en el navegador")
+    mode.add_argument("--search", metavar="TEXTO", help="busca debilidades por nombre")
+    mode.add_argument("--ancestors", "--ascendientes", dest="relatives", action="store_const", const="ancestors",
+                      help="lista los ascendientes: por defecto sólo los padres directos (modo 1)")
+    mode.add_argument("--descendants", "--descendientes", dest="relatives", action="store_const",
+                      const="descendants", help="lista los descendientes: por defecto sólo los hijos directos (modo 2)")
+    parser.add_argument("-d", "--depth", type=parse_depth, default=UNSET, metavar="N",
+                        help=f"niveles a recorrer, o 'all'. Por defecto {DEFAULT_DEPTH} en el árbol, "
+                        f"--tui y --web, y {DEFAULT_LIST_DEPTH} (sólo directos) con --ancestors/--descendants")
+    parser.add_argument("--json", action="store_true", help="con --ancestors/--descendants, salida en JSON")
+    parser.add_argument("-o", "--output", metavar="FICHERO", help="ruta del HTML generado con --web")
+    parser.add_argument("--no-open", action="store_true", help="con --web, no abrir el navegador")
+    parser.add_argument("--xml", metavar="RUTA", help="usa un cwec_*.xml o .zip local en vez de descargarlo")
+    parser.add_argument("--update", action="store_true", help="vuelve a descargar el catálogo de MITRE")
+    color = parser.add_mutually_exclusive_group()
+    color.add_argument("--color", dest="color", action="store_true", default=None, help="fuerza colores ANSI")
+    color.add_argument("--no-color", dest="color", action="store_false", help="desactiva los colores")
+    return parser
+
+
+def open_web(h: Hierarchy, cid: int, depth: int | None, output: str | None = None, launch: bool = True) -> str:
+    path = write_html(h, cid, depth, output)
+    if launch:
+        webbrowser.open(path.as_uri())
+    return f"Grafo web generado en {path}"
+
+
+def relatives_payload(h: Hierarchy, cid: int, direction: str, depth: int | None) -> dict:
+    node = h.nodes[cid]
+    rels = h.relatives(cid, direction, depth)
+    return {
+        "cwe": node.id,
+        "name": node.name,
+        "abstraction": node.abstraction,
+        "mode": direction,
+        "depth": "all" if depth is None else depth,
+        "view": "1000",
+        "catalog": {"version": h.version, "date": h.date},
+        "count": len(rels),
+        "results": [
+            {
+                "id": r.id,
+                "name": h.nodes[r.id].name,
+                "abstraction": h.nodes[r.id].abstraction,
+                "status": h.nodes[r.id].status,
+                "distance": r.distance,
+                "via": r.via,
+                "primary_parent": r.primary_parent,
+                "primary_lineage": r.primary_lineage,
+                "url": h.nodes[r.id].url,
+            }
+            for r in rels
+        ],
+        "note": h.relatives_note(cid, direction),
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        code = _main(argv)
+        sys.stdout.flush()  # si la tubería ya se cerró, el error salta aquí y no al salir
+        return code
+    except KeyboardInterrupt:
+        return 130
+    except BrokenPipeError:  # p. ej. `cwex 664 --depth all | head`
+        os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+        return 0
+
+
+def _main(argv: list[str] | None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not args.cwe and not args.search and not args.update:
+        parser.print_usage(sys.stderr)
+        print("cwex: indica un identificador CWE, por ejemplo: cwex 79", file=sys.stderr)
+        return 2
+    if args.json and not args.relatives:
+        parser.error("--json sólo se puede usar con --ancestors o --descendants")
+    if args.depth is UNSET:
+        args.depth = DEFAULT_LIST_DEPTH if args.relatives else DEFAULT_DEPTH
+    elif args.relatives and args.depth == 0:
+        parser.error("con --ancestors/--descendants la profundidad debe ser 1 o más (o 'all')")
+
+    try:
+        h = Hierarchy(load_catalog(args.xml, refresh=args.update))
+    except Exception as exc:  # red, XML corrupto, permisos...
+        print(f"cwex: no se pudo cargar el catálogo CWE: {exc}", file=sys.stderr)
+        return 1
+
+    if args.update and not args.cwe and not args.search:
+        print(f"Catálogo CWE {h.version} ({h.date}) guardado en {cache_dir()}: {len(h.nodes)} debilidades en la vista 1000.")
+        return 0
+
+    if args.search:
+        hits = h.search(args.search, limit=25)
+        if not hits:
+            print(f"Sin resultados para «{args.search}».")
+            return 1
+        color = use_color(args.color)
+        for n in hits:
+            line = [(BADGES.get(n.abstraction, "??"), f"badge:{n.abstraction}"), (" ", "plain"),
+                    (f"{n.label:<9}", "bold"), (" " + n.name, "plain")]
+            print(to_ansi(line, color))
+        return 0
+
+    try:
+        node = h.get(args.cwe)
+    except (ValueError, CWENotFound) as exc:
+        print(f"cwex: {exc}", file=sys.stderr)
+        return 1
+
+    if args.relatives and args.json:
+        print(json.dumps(relatives_payload(h, node.id, args.relatives, args.depth), ensure_ascii=False, indent=2))
+    elif args.relatives:
+        print_relatives(h, node.id, args.relatives, args.depth, color=args.color)
+    elif args.web:
+        print(open_web(h, node.id, args.depth, args.output, launch=not args.no_open))
+    elif args.tui:
+        if not sys.stdin.isatty() or not sys.stdout.isatty():
+            print("cwex: --tui necesita una terminal interactiva.", file=sys.stderr)
+            return 1
+        from . import tui  # curses no existe en algunos Windows: se importa sólo si hace falta
+
+        tui.run(h, node.id, args.depth, lambda cid, depth: open_web(h, cid, depth))
+    else:
+        print_tree(h, node.id, args.depth, color=args.color)
+    return 0

cwe_explorer/data.py

@@ -0,0 +1,159 @@
+"""Descarga, parseo y caché del catálogo CWE de MITRE.
+
+El XML oficial (~19 MB) se descarga una vez y se reduce a un JSON compacto con
+sólo lo necesario para recorrer la vista 1000 (Complete Weakness Hierarchy).
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import os
+import shutil
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+import zipfile
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+CATALOG_URL = "https://cwe.mitre.org/data/xml/cwec_latest.xml.zip"
+HIERARCHY_VIEW = "1000"
+CACHE_FORMAT = 1
+
+# Naturalezas de relación que no son jerárquicas pero aportan contexto
+# (cadenas, compuestos, solapamientos...).
+EXTRA_NATURES = ("CanPrecede", "CanFollow", "Requires", "StartsWith", "PeerOf", "CanAlsoBe", "Overlaps")
+
+
+def cache_dir() -> Path:
+    override = os.environ.get("CWEX_CACHE")
+    if override:
+        return Path(override).expanduser()
+    base = os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache"
+    return Path(base) / "cwe-explorer"
+
+
+def _local(tag: str) -> str:
+    """Nombre del elemento sin namespace (el esquema cambia: cwe-7, cwe-8...)."""
+    return tag.rsplit("}", 1)[-1]
+
+
+def _text(elem: ET.Element | None) -> str:
+    if elem is None:
+        return ""
+    return " ".join("".join(elem.itertext()).split())
+
+
+def _child(elem: ET.Element, name: str) -> ET.Element | None:
+    for c in elem:
+        if _local(c.tag) == name:
+            return c
+    return None
+
+
+def parse_catalog(source) -> dict:
+    """Convierte el XML de CWE (ruta, fichero o .zip) en el diccionario de caché."""
+    source = Path(source) if isinstance(source, (str, os.PathLike)) else source
+    if isinstance(source, Path) and source.suffix == ".zip":
+        with zipfile.ZipFile(source) as zf:
+            member = next(n for n in zf.namelist() if n.endswith(".xml"))
+            root = ET.parse(io.BytesIO(zf.read(member))).getroot()
+    else:
+        root = ET.parse(source).getroot()
+
+    weaknesses: dict[str, dict] = {}
+    others: dict[str, dict] = {}
+
+    for elem in root.iter():
+        kind = _local(elem.tag)
+        if kind == "Weakness":
+            parents: list[int] = []
+            relations: list[list] = []
+            rels = _child(elem, "Related_Weaknesses")
+            for rel in rels if rels is not None else ():
+                nature, target, view = rel.get("Nature"), rel.get("CWE_ID"), rel.get("View_ID")
+                if not target or not target.isdigit():
+                    continue
+                if nature == "ChildOf":
+                    if view != HIERARCHY_VIEW:
+                        continue
+                    if rel.get("Ordinal") == "Primary":
+                        parents.insert(0, int(target))
+                    elif int(target) not in parents:
+                        parents.append(int(target))
+                elif nature in EXTRA_NATURES:
+                    entry = [nature, int(target)]
+                    if entry not in relations:
+                        relations.append(entry)
+            weaknesses[elem.get("ID")] = {
+                "name": elem.get("Name", ""),
+                "abstraction": elem.get("Abstraction", ""),
+                "structure": elem.get("Structure", ""),
+                "status": elem.get("Status", ""),
+                "description": _text(_child(elem, "Description")),
+                "extended": _text(_child(elem, "Extended_Description")),
+                "parents": parents,
+                "relations": relations,
+            }
+        elif kind in ("Grouping", "Category", "View"):
+            others[elem.get("ID")] = {
+                "kind": "Grouping" if kind == "Category" else kind,
+                "name": elem.get("Name", ""),
+                "status": elem.get("Status", ""),
+            }
+
+    return {
+        "format": CACHE_FORMAT,
+        "version": root.get("Version", "?"),
+        "date": root.get("Date", "?"),
+        "weaknesses": weaknesses,
+        "others": others,
+    }
+
+
+def download_catalog(dest: Path, url: str = CATALOG_URL) -> Path:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    tmp = dest.with_suffix(".part")
+    print(f"Descargando catálogo CWE desde {url} ...", file=sys.stderr)
+    try:
+        with urllib.request.urlopen(url, timeout=60) as resp, open(tmp, "wb") as fh:
+            shutil.copyfileobj(resp, fh)
+    except (urllib.error.URLError, OSError) as exc:
+        # Algunos Python de macOS no traen certificados raíz: se recurre a curl.
+        if not shutil.which("curl"):
+            raise RuntimeError(f"No se pudo descargar el catálogo: {exc}") from exc
+        result = subprocess.run(["curl", "-fsSL", "-o", str(tmp), url], capture_output=True, text=True)
+        if result.returncode != 0:
+            raise RuntimeError(f"No se pudo descargar el catálogo: {result.stderr.strip() or exc}") from exc
+    tmp.replace(dest)
+    return dest
+
+
+def load_catalog(xml_path: str | os.PathLike | None = None, refresh: bool = False) -> dict:
+    """Devuelve el catálogo parseado, usando la caché JSON siempre que sea posible.
+
+    - ``xml_path``: XML o .zip local (no se descarga nada ni se toca la caché).
+    - ``refresh``: fuerza una nueva descarga del catálogo más reciente.
+    """
+    if xml_path:
+        return parse_catalog(Path(xml_path).expanduser())
+
+    cdir = cache_dir()
+    json_path = cdir / "catalog.json"
+    zip_path = cdir / "cwec_latest.xml.zip"
+
+    if not refresh and json_path.exists():
+        try:
+            data = json.loads(json_path.read_text(encoding="utf-8"))
+            if data.get("format") == CACHE_FORMAT:
+                return data
+        except (OSError, ValueError):
+            pass
+
+    if refresh or not zip_path.exists():
+        download_catalog(zip_path)
+    data = parse_catalog(zip_path)
+    json_path.write_text(json.dumps(data, ensure_ascii=False, separators=(",", ":")), encoding="utf-8")
+    return data

cwe_explorer/hierarchy.py

@@ -0,0 +1,297 @@
+"""Modelo de la vista 1000 de CWE como grafo dirigido acíclico (relaciones ChildOf)."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+ABSTRACTION_ORDER = ("Pillar", "Class", "Base", "Variant", "Compound")
+
+ABSTRACTION_INFO = {
+    "Pillar": "el nivel más abstracto; agrupa todas las debilidades de un mismo tema.",
+    "Class": "debilidad descrita de forma muy abstracta, normalmente independiente "
+    "del lenguaje o la tecnología.",
+    "Base": "debilidad todavía abstracta, pero con el detalle suficiente para deducir "
+    "métodos concretos de detección y prevención.",
+    "Variant": "debilidad ligada a un lenguaje, tecnología o tipo de recurso concreto.",
+    "Compound": "combinación de dos o más debilidades, ya sea una cadena (Chain) "
+    "o un compuesto (Composite).",
+}
+
+STRUCTURE_INFO = {
+    "Simple": "Simple",
+    "Chain": "Cadena: una debilidad provoca la siguiente",
+    "Composite": "Compuesto: requiere varias debilidades a la vez",
+}
+
+RELATION_LABELS = {
+    "CanPrecede": "Puede preceder a",
+    "CanFollow": "Puede seguir a",
+    "Requires": "Requiere",
+    "StartsWith": "Empieza con",
+    "PeerOf": "Par de",
+    "CanAlsoBe": "También puede ser",
+    "Overlaps": "Se solapa con",
+}
+
+MAX_LINEAGES = 50
+
+
+class CWENotFound(LookupError):
+    pass
+
+
+@dataclass
+class Relative:
+    """Un ascendiente o descendiente de una CWE, a la distancia más corta a la que aparece."""
+
+    id: int
+    distance: int  # 1 = padre o hijo directo
+    via: list[int]  # nodos de la distancia anterior por los que se llega (en distancia 1, el origen)
+    # Sólo en distancia 1: si el ChildOf entre ambos es el primario (Ordinal="Primary").
+    primary_parent: bool | None
+    # Ascendientes: está en el linaje principal del origen. Descendientes: el origen está en el suyo.
+    primary_lineage: bool
+
+
+@dataclass
+class Weakness:
+    id: int
+    name: str
+    abstraction: str
+    structure: str
+    status: str
+    description: str
+    extended: str = ""
+    parents: list[int] = field(default_factory=list)  # el padre primario va primero
+    relations: list[tuple[str, int]] = field(default_factory=list)
+
+    @property
+    def label(self) -> str:
+        return f"CWE-{self.id}"
+
+    @property
+    def url(self) -> str:
+        return f"https://cwe.mitre.org/data/definitions/{self.id}.html"
+
+    @property
+    def primary_parent(self) -> int | None:
+        return self.parents[0] if self.parents else None
+
+    @property
+    def deprecated(self) -> bool:
+        return self.status == "Deprecated"
+
+
+def parse_cwe_id(raw: str | int) -> int:
+    match = re.fullmatch(r"\s*(?:cwe)?[\s\-_:]*(\d+)\s*", str(raw), re.IGNORECASE)
+    if not match:
+        raise ValueError(f"'{raw}' no es un identificador CWE válido (ejemplos: 79, CWE-79)")
+    return int(match.group(1))
+
+
+class Hierarchy:
+    """Vista 1000: todas las debilidades no obsoletas unidas por ChildOf."""
+
+    def __init__(self, catalog: dict):
+        self.version = catalog.get("version", "?")
+        self.date = catalog.get("date", "?")
+        self.nodes: dict[int, Weakness] = {}
+        self.deprecated: dict[int, Weakness] = {}
+        for sid, w in catalog["weaknesses"].items():
+            node = Weakness(
+                id=int(sid),
+                name=w["name"],
+                abstraction=w["abstraction"],
+                structure=w["structure"],
+                status=w["status"],
+                description=w["description"],
+                extended=w.get("extended", ""),
+                parents=list(w["parents"]),
+                relations=[(n, t) for n, t in w.get("relations", [])],
+            )
+            (self.deprecated if node.status == "Deprecated" else self.nodes)[node.id] = node
+        self.others = {int(k): v for k, v in catalog.get("others", {}).items()}
+
+        # El catálogo a veces conserva ChildOf hacia debilidades ya obsoletas (en CWE 5.0,
+        # CWE-378 y CWE-379 cuelgan de la obsoleta CWE-377). Se mantienen como nodos
+        # marcados para no inventar un linaje distinto del publicado por MITRE.
+        for node in list(self.nodes.values()):
+            for p in node.parents:
+                if p in self.deprecated and p not in self.nodes:
+                    self.nodes[p] = self.deprecated[p]
+        for node in self.nodes.values():
+            node.parents = [p for p in node.parents if p in self.nodes]
+        self.children: dict[int, list[int]] = {i: [] for i in self.nodes}
+        for node in self.nodes.values():
+            for p in node.parents:
+                self.children[p].append(node.id)
+        for kids in self.children.values():
+            kids.sort()
+        self.roots = sorted(i for i, n in self.nodes.items() if not n.parents)
+
+    # -- búsqueda ---------------------------------------------------------
+
+    def get(self, raw: str | int) -> Weakness:
+        cid = parse_cwe_id(raw)
+        if cid in self.nodes:
+            return self.nodes[cid]
+        if cid in self.deprecated:
+            dep = self.deprecated[cid]
+            raise CWENotFound(
+                f"CWE-{cid} ({dep.name}) está obsoleta (Deprecated) y no forma parte de la vista 1000."
+            )
+        if cid in self.others:
+            other = self.others[cid]
+            kind = {"Grouping": "una agrupación (antes «Category»)", "View": "una vista"}.get(
+                other["kind"], other["kind"]
+            )
+            raise CWENotFound(
+                f"CWE-{cid} ({other['name']}) es {kind}, no una debilidad: no aparece en la vista 1000."
+            )
+        raise CWENotFound(f"CWE-{cid} no existe en el catálogo CWE {self.version}.")
+
+    def search(self, text: str, limit: int = 10) -> list[Weakness]:
+        text = text.strip().lower()
+        if not text:
+            return []
+        hits = [n for n in self.nodes.values() if text in n.name.lower() or text == str(n.id)]
+        hits.sort(key=lambda n: (not n.name.lower().startswith(text), n.id))
+        return hits[:limit]
+
+    # -- recorridos -------------------------------------------------------
+
+    def ancestors(self, cid: int) -> set[int]:
+        seen: set[int] = set()
+        stack = list(self.nodes[cid].parents)
+        while stack:
+            p = stack.pop()
+            if p not in seen:
+                seen.add(p)
+                stack.extend(self.nodes[p].parents)
+        return seen
+
+    def descendants(self, cid: int, depth: int | None = None) -> set[int]:
+        seen: set[int] = set()
+        frontier = [cid]
+        level = 0
+        while frontier and (depth is None or level < depth):
+            nxt = []
+            for n in frontier:
+                for c in self.children[n]:
+                    if c not in seen:
+                        seen.add(c)
+                        nxt.append(c)
+            frontier = nxt
+            level += 1
+        return seen
+
+    def primary_lineage(self, cid: int) -> list[int]:
+        """Camino desde el pilar hasta ``cid`` siguiendo siempre el padre primario."""
+        path = [cid]
+        while (parent := self.nodes[path[-1]].primary_parent) is not None and parent not in path:
+            path.append(parent)
+        return path[::-1]
+
+    def lineages(self, cid: int, limit: int = MAX_LINEAGES) -> list[list[int]]:
+        """Todos los caminos raíz → ``cid`` (el primario primero)."""
+        paths: list[list[int]] = []
+
+        def walk(node: int, suffix: list[int]) -> None:
+            if len(paths) >= limit:
+                return
+            parents = self.nodes[node].parents
+            if not parents:
+                paths.append([node] + suffix)
+                return
+            for p in parents:
+                if p not in suffix:
+                    walk(p, [node] + suffix)
+
+        walk(cid, [])
+        primary = self.primary_lineage(cid)
+        if primary in paths:
+            paths.remove(primary)
+        return [primary] + paths
+
+    def relatives(self, cid: int, direction: str, depth: int | None = 1) -> list[Relative]:
+        """Ascendientes (``"ancestors"``) o descendientes (``"descendants"``) por niveles.
+
+        Recorrido en anchura: cada nodo sale una sola vez, en la distancia más corta, con
+        todos los nodos del nivel anterior que lo enlazan. ``depth=None`` recorre todo.
+        """
+        if direction not in ("ancestors", "descendants"):
+            raise ValueError(f"dirección desconocida: {direction}")
+        up = direction == "ancestors"
+        dist = {cid: 0}
+        via: dict[int, list[int]] = {}
+        frontier = [cid]
+        level = 0
+        while frontier and (depth is None or level < depth):
+            level += 1
+            nxt = []
+            for n in frontier:
+                for m in self.nodes[n].parents if up else self.children[n]:
+                    if m not in dist:
+                        dist[m] = level
+                        via[m] = [n]
+                        nxt.append(m)
+                    elif dist[m] == level:
+                        via[m].append(n)
+            frontier = nxt
+
+        lineage = set(self.primary_lineage(cid))
+        result = []
+        for m, d in dist.items():
+            if m == cid:
+                continue
+            if up:
+                primary_parent = m == self.nodes[cid].primary_parent if d == 1 else None
+                on_lineage = m in lineage
+            else:
+                primary_parent = self.nodes[m].primary_parent == cid if d == 1 else None
+                on_lineage = cid in self.primary_lineage(m)
+            result.append(Relative(m, d, sorted(via[m]), primary_parent, on_lineage))
+        # Hacia arriba, el nodo del linaje principal encabeza cada nivel; hacia abajo, orden por ID.
+        result.sort(key=lambda r: (r.distance, up and not r.primary_parent, up and not r.primary_lineage, r.id))
+        return result
+
+    def relatives_note(self, cid: int, direction: str) -> str | None:
+        """Explica un resultado vacío o incompleto de :meth:`relatives`."""
+        node = self.nodes[cid]
+        if direction == "ancestors":
+            if node.parents:
+                return self.lineage_warning(cid)
+            if node.abstraction == "Pillar":
+                return f"{node.label} es un Pillar: es la raíz de su rama y no tiene ascendientes en la vista 1000."
+            if node.deprecated:
+                kids = ", ".join(self.nodes[k].label for k in self.children[cid])
+                return (
+                    f"{node.label} está obsoleta y no tiene padre en la vista 1000; sólo aparece "
+                    f"porque {kids} siguen figurando como hijas suyas."
+                )
+            return f"{node.label} no tiene padre en la vista 1000."
+        if self.children[cid]:
+            return None
+        if node.abstraction == "Compound":
+            parts = [f"CWE-{t}" for nature, t in node.relations if nature in ("Requires", "StartsWith")]
+            return (
+                f"{node.label} es un Compound: en la vista 1000 no tiene hijos. Sus componentes "
+                f"({', '.join(parts) or 'ninguno declarado'}) se enlazan con Requires/StartsWith, no con ChildOf."
+            )
+        return f"{node.label} no tiene descendientes en la vista 1000: es una hoja de la jerarquía."
+
+    def depth_of(self, cid: int) -> int:
+        return len(self.primary_lineage(cid)) - 1
+
+    def lineage_warning(self, cid: int) -> str | None:
+        """Explica por qué un linaje no termina en un Pillar, si es el caso."""
+        top = self.nodes[self.primary_lineage(cid)[0]]
+        if top.abstraction == "Pillar":
+            return None
+        if top.deprecated:
+            return (
+                f"Linaje incompleto: {top.label} está obsoleta en el catálogo CWE {self.version} "
+                "pero sigue figurando como padre en la vista 1000."
+            )
+        return f"Linaje incompleto: {top.label} no tiene padre en la vista 1000."