vulnerability-explorer 1.0.0__py3-none-any.whl

vex/utils/filesystem.py

@@ -0,0 +1,49 @@
+import os
+from pathlib import Path
+
+DEFAULT_GLOBAL_CACHE_DIR = Path.home() / ".local" / "share" / "vex"
+
+
+def get_global_cache_dir() -> Path:
+    """Return default global user cache directory for vex catalog."""
+
+    return DEFAULT_GLOBAL_CACHE_DIR
+
+
+def find_repo_root() -> Path:
+    """Find catalog root directory.
+
+    Priority:
+    1. VEX_CATALOG_PATH environment variable (if directory exists and contains data/catalog or is catalog root)
+    2. CWD and parent directories walking up to find data/catalog
+    3. User global cache (~/.local/share/vex) if data/catalog exists there
+    4. CWD as ultimate fallback
+    """
+
+    # 1. Check environment variable
+    env_path = os.getenv("VEX_CATALOG_PATH")
+
+    if env_path:
+        candidate = Path(env_path).resolve()
+
+        if (candidate / "data" / "catalog").is_dir():
+            return candidate
+
+        if candidate.is_dir():
+            return candidate
+
+    # 2. Walk up from CWD
+    path = Path.cwd().resolve()
+
+    for candidate in [path] + list(path.parents):
+        if (candidate / "data" / "catalog").is_dir():
+            return candidate
+
+    # 3. User global cache directory (~/.local/share/vex)
+    global_cache = get_global_cache_dir()
+
+    if (global_cache / "data" / "catalog").is_dir():
+        return global_cache
+
+    # 4. Default to CWD
+    return path

vex_lint/__init__.py

@@ -0,0 +1,5 @@
+"""Vulnerability Explorer Linter Package."""
+
+from vex_lint.service import lint_catalog
+
+__all__ = ["lint_catalog"]

vex_lint/core/context.py

@@ -0,0 +1,25 @@
+"""Linting execution context holding shared state, taxonomy, and errors."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from vex.core.models import LintError
+from vex_lint.core.models import ParsedDocument
+
+
+@dataclass
+class LintContext:
+    """Holds repository root, loaded metadata, parsed documents, and violations."""
+
+    root: Path
+    vocab: dict[str, Any] = field(default_factory=dict)
+    taxonomy_categories: set[str] = field(default_factory=set)
+    documents: list[ParsedDocument] = field(default_factory=list)
+    seen_ids: dict[str, Path] = field(default_factory=dict)
+    errors: list[LintError] = field(default_factory=list)
+
+    def add_error(self, path: Path | str, message: str) -> None:
+        """Helper to append a LintError to context."""
+
+        self.errors.append(LintError(path=path, message=message))

vex_lint/core/engine.py

@@ -0,0 +1,36 @@
+"""Execution engine for registered lint rules."""
+
+from vex.core.models import LintError
+from vex_lint.core.context import LintContext
+from vex_lint.core.rule import BaseRule
+
+
+class LintEngine:
+    """Orchestrates rule execution against a LintContext."""
+
+    def __init__(self) -> None:
+        self.rules: list[BaseRule] = []
+
+    def register_rule(self, rule: BaseRule) -> None:
+        """Register a new lint rule."""
+
+        self.rules.append(rule)
+
+    def run(self, context: LintContext) -> tuple[list[LintError], int, int]:
+        """Execute setup, evaluate, and finish stages for all registered rules.
+
+        Returns:
+            (errors, files_checked_count, unique_ids_count)
+        """
+
+        for rule in self.rules:
+            rule.setup(context)
+
+        for doc in context.documents:
+            for rule in self.rules:
+                rule.evaluate_document(doc, context)
+
+        for rule in self.rules:
+            rule.finish(context)
+
+        return context.errors, len(context.documents), len(context.seen_ids)

vex_lint/core/models.py

@@ -0,0 +1,42 @@
+"""Data models for vex_lint engine."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class Heading:
+    """Represents a Markdown heading extracted from a document AST."""
+
+    level: int
+    text: str
+    line: int
+    raw_markdown: str
+
+
+@dataclass
+class ParsedDocument:
+    """Represents a parsed Markdown catalog document."""
+
+    path: Path
+    rel_path: Path
+    raw_text: str
+    frontmatter_raw: dict[str, Any] | None = None
+    frontmatter_error: str | None = None
+    body: str = ""
+    headings: list[Heading] = field(default_factory=list)
+
+    @property
+    def doc_type(self) -> str | None:
+        if self.frontmatter_raw and isinstance(self.frontmatter_raw.get("type"), str):
+            return str(self.frontmatter_raw["type"])
+
+        return None
+
+    @property
+    def doc_id(self) -> str | None:
+        if self.frontmatter_raw and isinstance(self.frontmatter_raw.get("id"), str):
+            return str(self.frontmatter_raw["id"])
+
+        return None

vex_lint/core/rule.py

@@ -0,0 +1,30 @@
+"""Abstract Base Rule interface for vex-lint."""
+
+from abc import ABC, abstractmethod
+
+from vex_lint.core.context import LintContext
+from vex_lint.core.models import ParsedDocument
+
+
+class BaseRule(ABC):
+    """Abstract base class for all catalog linting rules."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Unique identifier for the rule."""
+
+    @property
+    def description(self) -> str:
+        """Brief summary of what this rule validates."""
+
+        return ""
+
+    def setup(self, context: LintContext) -> None:
+        """Optional hook executed before per-document evaluation."""
+
+    def evaluate_document(self, doc: ParsedDocument, context: LintContext) -> None:
+        """Evaluate a single parsed document."""
+
+    def finish(self, context: LintContext) -> None:
+        """Optional hook executed after all documents have been evaluated."""

vex_lint/linter.py

@@ -0,0 +1,5 @@
+"""Catalog validation logic and linting entry point."""
+
+from vex_lint.service import lint_catalog
+
+__all__ = ["lint_catalog"]

vex_lint/loaders/markdown.py

@@ -0,0 +1,88 @@
+"""Markdown parser using markdown-it-py AST to extract frontmatter and top-level headings."""
+
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+from markdown_it import MarkdownIt
+
+from vex_lint.core.models import Heading, ParsedDocument
+
+FRONTMATTER_RE = re.compile(r"\A---\n(.*?\n)---\n?(.*)\Z", re.DOTALL)
+
+_md_parser = MarkdownIt("commonmark")
+
+
+def parse_markdown_file(path: Path, root: Path) -> ParsedDocument:
+    """Parse a Markdown file, splitting YAML frontmatter and extracting AST headings."""
+
+    rel_path = path.relative_to(root)
+    text = path.read_text(encoding="utf-8")
+
+    match = FRONTMATTER_RE.match(text)
+
+    if not match:
+        return ParsedDocument(
+            path=path,
+            rel_path=rel_path,
+            raw_text=text,
+            frontmatter_error="no valid --- frontmatter block found",
+        )
+
+    fm_text, body = match.group(1), match.group(2)
+
+    try:
+        fm_data: Any = yaml.safe_load(fm_text)
+    except yaml.YAMLError as err:
+        return ParsedDocument(
+            path=path,
+            rel_path=rel_path,
+            raw_text=text,
+            frontmatter_error=f"frontmatter is not valid YAML: {err}",
+            body=body,
+        )
+
+    if not isinstance(fm_data, dict):
+        return ParsedDocument(
+            path=path,
+            rel_path=rel_path,
+            raw_text=text,
+            frontmatter_raw=None,
+            frontmatter_error="frontmatter did not parse to a mapping",
+            body=body,
+        )
+
+    # Extract headings using AST tokens
+    tokens = _md_parser.parse(body)
+    headings: list[Heading] = []
+
+    for i, token in enumerate(tokens):
+        if token.type == "heading_open":
+            level = int(token.tag[1:]) if (token.tag and len(token.tag) > 1) else 1
+            line = token.map[0] if token.map else 0
+
+            # The next token is usually inline containing children/text
+            heading_text = ""
+
+            if i + 1 < len(tokens) and tokens[i + 1].type == "inline":
+                heading_text = tokens[i + 1].content.strip()
+
+            raw_heading = f"{'#' * level} {heading_text}"
+            headings.append(
+                Heading(
+                    level=level,
+                    text=heading_text,
+                    line=line,
+                    raw_markdown=raw_heading,
+                )
+            )
+
+    return ParsedDocument(
+        path=path,
+        rel_path=rel_path,
+        raw_text=text,
+        frontmatter_raw=fm_data,
+        body=body,
+        headings=headings,
+    )

vex_lint/loaders/taxonomy.py

@@ -0,0 +1,32 @@
+"""Loaders for controlled vocabularies and taxonomy markdown specifications."""
+
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+TAXONOMY_HEADING_RE = re.compile(r"^###\s+`([a-z0-9-]+)`\s+—", re.MULTILINE)
+
+
+def load_vocab(contributing_dir: Path) -> dict[str, Any]:
+    """Load controlled vocabularies from YAML file."""
+
+    vocab_path = contributing_dir / "references" / "controlled-vocabularies.yaml"
+
+    with open(vocab_path, encoding="utf-8") as f:
+        data: Any = yaml.safe_load(f)
+
+        if isinstance(data, dict):
+            return data
+
+        return {}
+
+
+def load_taxonomy_categories(contributing_dir: Path) -> set[str]:
+    """Load category headings from the taxonomy Markdown file."""
+
+    taxonomy_path = contributing_dir / "references" / "taxonomy.md"
+    text = taxonomy_path.read_text(encoding="utf-8")
+
+    return set(TAXONOMY_HEADING_RE.findall(text))

vex_lint/main.py

@@ -0,0 +1,34 @@
+"""Main entrypoint for vex-lint CLI app."""
+
+import typer
+
+from vex.commands.options import OptRoot
+from vex.utils.filesystem import find_repo_root
+from vex_lint.linter import lint_catalog
+
+app = typer.Typer(name="vex-lint", help="Structural and referential integrity linter for the vulnerability catalog.")
+
+
+@app.callback(invoke_without_command=True)
+def main(root: OptRoot = None) -> None:
+    """Lint the vulnerability catalog structure and references."""
+
+    repo_root = root.resolve() if root else find_repo_root()
+
+    errors, files_count, ids_count = lint_catalog(repo_root)
+
+    if errors:
+        typer.echo(f"lint_catalog: {len(errors)} violation(s) found\n", err=True)
+
+        for err in errors:
+            typer.echo(f"  - {err}", err=True)
+
+        raise typer.Exit(code=1)
+
+    typer.echo(f"lint_catalog: OK ({files_count} files checked, {ids_count} ids)")
+
+    raise typer.Exit(code=0)
+
+
+if __name__ == "__main__":
+    app()

vex_lint/rules/cross_reference_rule.py

@@ -0,0 +1,47 @@
+"""Rule validating cross-document references (parent, related_files, applies_to_mechanisms)."""
+
+from vex_lint.core.context import LintContext
+from vex_lint.core.rule import BaseRule
+
+
+class CrossReferenceRule(BaseRule):
+    """Validates that referenced IDs exist in the parsed catalog."""
+
+    @property
+    def name(self) -> str:
+        return "cross-reference"
+
+    @property
+    def description(self) -> str:
+        return "Validates that IDs in parent, related_files, and applies_to_mechanisms exist."
+
+    def finish(self, context: LintContext) -> None:
+        seen_ids = context.seen_ids
+
+        for doc in context.documents:
+            if doc.frontmatter_raw is None:
+                continue
+
+            fm = doc.frontmatter_raw
+
+            parent = fm.get("parent")
+
+            if parent and parent not in seen_ids:
+                context.add_error(
+                    doc.rel_path,
+                    f"`parent: {parent}` does not match any existing `id`",
+                )
+
+            related_files = fm.get("related_files")
+
+            if isinstance(related_files, list):
+                for ref in related_files:
+                    if ref not in seen_ids:
+                        context.add_error(doc.rel_path, f"`related_files` entry '{ref}' does not match any existing `id`")
+
+            applies_to = fm.get("applies_to_mechanisms")
+
+            if isinstance(applies_to, list):
+                for ref in applies_to:
+                    if ref not in seen_ids:
+                        context.add_error(doc.rel_path, f"`applies_to_mechanisms` entry '{ref}' does not match any existing `id`")

vex_lint/rules/frontmatter_schema_rule.py

@@ -0,0 +1,68 @@
+"""Rule validating YAML frontmatter syntax, required fields, and controlled vocabulary values."""
+
+from vex_lint.core.context import LintContext
+from vex_lint.core.models import ParsedDocument
+from vex_lint.core.rule import BaseRule
+from vex_lint.schemas.frontmatter import validate_frontmatter_schema
+
+ENUM_FIELDS: dict[str, str] = {
+    "type": "type",
+    "status": "status",
+    "category": "category",
+    "severity_baseline": "severity_baseline",
+}
+
+LIST_ENUM_FIELDS: dict[str, str] = {
+    "analysis_modes": "analysis_modes",
+    "architectures": "architectures",
+}
+
+
+class FrontmatterSchemaRule(BaseRule):
+    """Rule that validates frontmatter YAML structure and vocabulary fields."""
+
+    @property
+    def name(self) -> str:
+        return "frontmatter-schema"
+
+    @property
+    def description(self) -> str:
+        return "Validates that frontmatter is valid YAML, matches Pydantic schema, and complies with controlled vocabularies."
+
+    def evaluate_document(self, doc: ParsedDocument, context: LintContext) -> None:
+        if doc.frontmatter_error:
+            context.add_error(doc.rel_path, doc.frontmatter_error)
+            return
+
+        fm = doc.frontmatter_raw
+
+        if fm is None:
+            return
+
+        schema_err = validate_frontmatter_schema(fm)
+
+        if schema_err:
+            context.add_error(doc.rel_path, schema_err)
+
+        # Validate controlled vocabulary enums
+        vocab = context.vocab
+
+        for field, vocab_key in ENUM_FIELDS.items():
+            if field in fm and fm[field] is not None:
+                allowed = set(vocab.get(vocab_key, []))
+                val = fm[field]
+
+                if val not in allowed:
+                    context.add_error(doc.rel_path, f"`{field}` value '{val}' not in controlled vocabulary `{vocab_key}`")
+
+        for field, vocab_key in LIST_ENUM_FIELDS.items():
+            if field in fm and fm[field] is not None:
+                allowed = set(vocab.get(vocab_key, []))
+                val = fm[field]
+
+                if not isinstance(val, list):
+                    context.add_error(doc.rel_path, f"`{field}` must be a list")
+                else:
+                    for item in val:
+                        if item not in allowed:
+                            context.add_error(doc.rel_path, f"`{field}` entry '{item}' not in controlled vocabulary `{vocab_key}`")

vex_lint/rules/markdown_structure_rule.py

@@ -0,0 +1,49 @@
+"""Rule validating presence and sequential ordering of required Markdown headings and subheadings."""
+
+from vex_lint.core.context import LintContext
+from vex_lint.core.models import ParsedDocument
+from vex_lint.core.rule import BaseRule
+from vex_lint.schemas.sections import REQUIRED_SECTIONS, REQUIRED_SUBSECTIONS
+
+
+class MarkdownStructureRule(BaseRule):
+    """Validates that documents contain all required sections and subsections in correct order."""
+
+    @property
+    def name(self) -> str:
+        return "markdown-structure"
+
+    @property
+    def description(self) -> str:
+        return "Checks that Markdown documents possess required headings (h2) and subheadings (h3) in prescribed order."
+
+    def evaluate_document(self, doc: ParsedDocument, context: LintContext) -> None:
+        ftype = doc.doc_type
+
+        if not ftype:
+            return
+
+        if ftype in REQUIRED_SECTIONS:
+            self._check_sections(doc, REQUIRED_SECTIONS[ftype], context)
+
+        if ftype in REQUIRED_SUBSECTIONS:
+            self._check_sections(doc, REQUIRED_SUBSECTIONS[ftype], context)
+
+    def _check_sections(self, doc: ParsedDocument, required: list[str], context: LintContext) -> None:
+        heading_positions: dict[str, int] = {}
+
+        for idx, heading in enumerate(doc.headings):
+            raw = heading.raw_markdown
+
+            if raw in required and raw not in heading_positions:
+                heading_positions[raw] = idx
+
+        for req in required:
+            if req not in heading_positions:
+                context.add_error(doc.rel_path, f"missing required section '{req}'")
+
+        found_order = [h for h in required if h in heading_positions]
+        positions = [heading_positions[h] for h in found_order]
+
+        if positions != sorted(positions):
+            context.add_error(doc.rel_path, "required sections are present but out of order")

vex_lint/rules/path_convention_rule.py

@@ -0,0 +1,72 @@
+"""Rule validating path naming conventions, path-derived IDs/types, and ID uniqueness."""
+
+from pathlib import Path
+
+from vex_lint.core.context import LintContext
+from vex_lint.core.models import ParsedDocument
+from vex_lint.core.rule import BaseRule
+
+
+def expected_id_and_type(rel_path: Path) -> tuple[str | None, str | None]:
+    """Given a path relative to repo root, return (expected_id, expected_type)."""
+    parts = rel_path.parts
+
+    if len(parts) >= 2 and parts[0] == "data" and parts[1] == "catalog":
+        if len(parts) == 5 and parts[4] == "README.md":
+            category, mechanism = parts[2], parts[3]
+            return f"{category}.{mechanism}", "concept"
+
+        if len(parts) == 5 and parts[4].endswith(".md"):
+            category, mechanism, filename = parts[2], parts[3], parts[4][:-3]
+
+            if "_" not in filename:
+                return None, None
+
+            variant, context = filename.split("_", 1)
+
+            return f"{category}.{mechanism}.{variant}.{context}", "manifestation"
+
+    if len(parts) >= 2 and parts[0] == "data" and parts[1] == "signatures" and len(parts) == 3 and parts[2].endswith(".md"):
+        name = parts[2][:-3]
+
+        return f"runtime-signature.{name.replace('_', '.')}", "runtime-signature"
+
+    return None, None
+
+
+class PathConventionRule(BaseRule):
+    """Validates file path naming conventions, derived ID matching, and unique IDs."""
+
+    @property
+    def name(self) -> str:
+        return "path-convention"
+
+    @property
+    def description(self) -> str:
+        return "Validates that file paths follow standard hierarchy and match internal frontmatter IDs and types."
+
+    def evaluate_document(self, doc: ParsedDocument, context: LintContext) -> None:
+        if doc.frontmatter_raw is None:
+            return
+
+        fm = doc.frontmatter_raw
+        ftype = fm.get("type")
+
+        expected_id, expected_type = expected_id_and_type(doc.rel_path)
+
+        if expected_id is None:
+            context.add_error(doc.rel_path, "path does not match any recognized naming pattern")
+        else:
+            if ftype != expected_type:
+                context.add_error(doc.rel_path, f"`type: {ftype}` does not match path pattern (expected `{expected_type}`)")
+
+            if fm.get("id") != expected_id:
+                context.add_error(doc.rel_path, f"`id: {fm.get('id')}` does not match path-derived id `{expected_id}`")
+
+        fid = fm.get("id")
+
+        if isinstance(fid, str) and fid:
+            if fid in context.seen_ids:
+                context.add_error(doc.rel_path, f"duplicate `id` '{fid}', already used by {context.seen_ids[fid]}")
+            else:
+                context.seen_ids[fid] = doc.rel_path

vex_lint/rules/taxonomy_rule.py

@@ -0,0 +1,30 @@
+"""Rule validating consistency between controlled vocabularies and taxonomy documentation."""
+
+from vex_lint.core.context import LintContext
+from vex_lint.core.rule import BaseRule
+
+
+class TaxonomyRule(BaseRule):
+    """Ensures category lists match between controlled-vocabularies.yaml and taxonomy.md."""
+
+    @property
+    def name(self) -> str:
+        return "taxonomy-consistency"
+
+    @property
+    def description(self) -> str:
+        return "Checks that taxonomy categories in docs/contributing/references match controlled vocabularies."
+
+    def setup(self, context: LintContext) -> None:
+        vocab_categories = set(context.vocab.get("category", []))
+        taxonomy_categories = context.taxonomy_categories
+
+        if vocab_categories != taxonomy_categories:
+            only_vocab = vocab_categories - taxonomy_categories
+            only_taxonomy = taxonomy_categories - vocab_categories
+
+            if only_vocab:
+                context.add_error("docs/contributing/references/controlled-vocabularies.yaml", f"categories not documented in references/taxonomy.md: {sorted(only_vocab)}")
+
+            if only_taxonomy:
+                context.add_error("docs/contributing/references/taxonomy.md", f"categories not registered in references/controlled-vocabularies.yaml: {sorted(only_taxonomy)}")