validator.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/mcp/validator.py
 
"""
Purpose
-------
Input Validator (Layer 2) for the ``oct-mcp`` six-layer pipeline.
Defines one Pydantic model per MCP tool (9 models for the Phase 5A
read-only tool manifest). All models enforce:
 
- Unknown-field rejection (``model_config = ConfigDict(extra="forbid")``)
- Integer field clamping via ``ge``/``le`` constraints
- Enum allowlists (e.g. for ``profile``)
- Shell-metacharacter rejection for all string fields
- Path containment enforcement for all ``paths`` fields
 
Responsibilities
----------------
- Provide :func:`validate_tool_args` as the single entry point: takes a
  tool name and a raw ``dict`` and returns a validated ``BaseModel``
  instance, or raises :class:`pydantic.ValidationError` on failure.
- Define :func:`check_shell_metacharacters` for reuse by tests.
- Define :func:`validate_path_in_project` for reuse by tests.
 
Diagnostics
-----------
Domain: MCP
Levels:
    L2 - lifecycle: validation outcome
    L3 - (none): the outcome is reported at L2, field values at L4
    L4 - deep trace: individual field values
 
Contracts
---------
- This module does not import ``click`` or the MCP SDK.
- All models are instantiated with ``model_validate(data, context=context)``
  where ``context`` carries ``{"project_root": Path}``.
- :func:`validate_tool_args` raises ``ValueError`` for unknown tool names
  before Pydantic even runs.
- Shell metacharacters are rejected by a @field_validator applied to
  every ``str`` field in every model via the ``_ShellSafe`` mixin.
 
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
- oct.core.project_root (is_within_project_root, the path containment check)
- oct.git.conventional (lazy; validate_commit_message for the oct_git_commit message)
- pydantic (BaseModel, ConfigDict, Field, field_validator and ValidationInfo for the tool argument models)
"""
 
from __future__ import annotations
 
import re
from pathlib import Path
from typing import Annotated, Literal
 
try:
    from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
    from pydantic import ValidationInfo
except ImportError as _pydantic_err:  # pragma: no cover
    raise ImportError(
        # OCT-LINT: disable=no_hardcoded_secrets reason="Error message naming the required pydantic version, not a secret"
        "pydantic>=2.0 is required for oct-mcp. "
        "Install with: pip install 'oct[mcp]'"
    ) from _pydantic_err
 
from oct.core.diagnostics import _dbg
 
try:
    from oct.core.project_root import is_within_project_root
except ImportError:  # pragma: no cover - defensive fallback
    def is_within_project_root(path: Path, project_root: Path) -> bool:
        try:
            return Path(path).resolve().is_relative_to(Path(project_root).resolve())
        except Exception:
            return False
 
 
# ---------------------------------------------------------------------
# Shell metacharacter guard
# ---------------------------------------------------------------------
 
#: Characters that have special meaning in shells and must never appear
#: in validated arg strings. This list covers POSIX and cmd.exe.
_SHELL_METACHARACTERS: frozenset[str] = frozenset(
    ";&|`$><(){}!\\\"'"
)
 
#: Compiled pattern for quick detection of any shell metacharacter.
_SHELL_META_RE: re.Pattern[str] = re.compile(
    r"[;&|`$><(){}!\\\"']"
)
 
 
def check_shell_metacharacters(value: str) -> str:
    """Raise ``ValueError`` if *value* contains any shell metacharacter.
 
    Called by field validators in every model that handles free-form
    string input. Never called on boolean or integer fields.
    """
    if _SHELL_META_RE.search(value):
        raise ValueError(
            f"Shell metacharacters are not allowed in MCP tool arguments. "
            f"Rejected value: {value!r}"
        )
    return value
 
 
# ---------------------------------------------------------------------
# Path containment helper
# ---------------------------------------------------------------------
 
 
def validate_path_in_project(path_str: str, project_root: Path | None) -> str:
    """Validate that *path_str* resolves inside *project_root*.
 
    Relative paths are resolved against *project_root* (not the process
    cwd) so that ``"src"`` is interpreted as ``<project_root>/src``.
    Absolute paths are resolved as-is.
 
    Raises ``ValueError`` on path traversal attempts. When
    ``project_root`` is ``None``, the check is skipped (permissive
    fallback for contexts where the root is not yet bound).
    """
    if not project_root:
        return path_str
    p = Path(path_str)
    if p.is_absolute():
        resolved = p.resolve()
    else:
        resolved = (project_root / p).resolve()
    if not is_within_project_root(resolved, project_root):
        raise ValueError(
            f"Path {path_str!r} resolves outside the project root "
            f"{project_root!r}. Path traversal is not permitted."
        )
    return path_str
 
 
# ---------------------------------------------------------------------
# Shared validation helpers
# ---------------------------------------------------------------------
 
def _check_str(v: str) -> str:
    """Combined: shell-metachar check for a single string value."""
    return check_shell_metacharacters(v)
 
 
def _check_paths(paths: list[str], info: ValidationInfo) -> list[str]:
    """Shell-safe + path-containment check for a list of paths."""
    root: Path | None = (info.context or {}).get("project_root")
    result: list[str] = []
    for p in paths:
        p = check_shell_metacharacters(p)
        p = validate_path_in_project(p, root)
        result.append(p)
    return result
 
 
# ---------------------------------------------------------------------
# Tool argument models (one per tool in the Phase 5A manifest)
# ---------------------------------------------------------------------
 
#: Valid lint profiles (matches oct linter --profile options).
_LINT_PROFILES = Literal["proto", "compact", "strict"]
 
 
class LintArgs(BaseModel):
    """Arguments for the ``oct_lint`` tool (``oct lint``)."""
 
    model_config = ConfigDict(extra="forbid")
 
    paths: list[str] = []
    json_output: bool = True
    jobs: int = Field(default=1, ge=1, le=8)
    changed: bool = False
    fix_headers: bool = False
    profile: _LINT_PROFILES | None = None
 
    @field_validator("paths", mode="after")
    @classmethod
    def paths_inside_project(cls, v: list[str], info: ValidationInfo) -> list[str]:
        return _check_paths(v, info)
 
 
class HealthArgs(BaseModel):
    """Arguments for the ``oct_health`` tool (``oct health``)."""
 
    model_config = ConfigDict(extra="forbid")
 
    json_output: bool = True
    verbose: bool = False
 
 
class SkeletonArgs(BaseModel):
    """Arguments for the ``oct_skeleton`` tool (``oct export-skeleton``).
 
    OI-502: previously exposed an ``output_dir`` field that the CLI does
    not accept. Removed to restore model/CLI parity; the CLI always writes
    into ``_skeleton_code-*`` under the project root.
    """
 
    model_config = ConfigDict(extra="forbid")
 
    json_output: bool = True
 
 
class DepsArgs(BaseModel):
    """Arguments for the ``oct_deps`` tool (``oct deps``).
 
    OI-502: previously exposed a ``check`` boolean that the CLI does not
    accept. Removed to restore parity; callers that want pin-auditing
    should use ``oct deps --audit-pins`` directly (not yet modelled).
    """
 
    model_config = ConfigDict(extra="forbid")
 
    json_output: bool = True
 
 
class OctTestArgs(BaseModel):
    """Arguments for the ``oct_test`` tool (``oct test``).
 
    OI-502: previously exposed a ``jobs`` integer that the CLI does not
    accept. Removed to restore parity. Note that ``pytest-xdist`` is
    now declared in the ``oct[test]`` and ``oct[dev]`` extras, so
    parallel runs are available - invoke them via the existing
    pass-through ``args`` (e.g. ``oct test -- -n auto``). A first-class
    ``jobs`` field can be re-added if/when MCP clients need to drive
    parallelism programmatically.
    """
 
    model_config = ConfigDict(extra="forbid")
 
    json_output: bool = True
    paths: list[str] = []
    changed: bool = False
 
    @field_validator("paths", mode="after")
    @classmethod
    def paths_inside_project(cls, v: list[str], info: ValidationInfo) -> list[str]:
        return _check_paths(v, info)
 
 
class TypecheckArgs(BaseModel):
    """Arguments for the ``oct_typecheck`` tool (``oct typecheck``)."""
 
    model_config = ConfigDict(extra="forbid")
 
    json_output: bool = True
    paths: list[str] = []
 
    @field_validator("paths", mode="after")
    @classmethod
    def paths_inside_project(cls, v: list[str], info: ValidationInfo) -> list[str]:
        return _check_paths(v, info)
 
 
class DiagArgs(BaseModel):
    """Arguments for the ``oct_diag`` tool (``oct diag``).
 
    OI-502: the historical ``Literal`` included ``show-config`` and
    ``list-checks`` but the CLI exposes only ``validate-config``,
    ``list-domains``, and ``set-level``. Narrowed to the two
    zero-argument subcommands; ``set-level`` takes positional arguments
    that are out of scope for this read-only tool.
 
    ``json_output`` is retained for model uniformity but the executor
    does not emit ``--json`` because the diag subcommands don't accept
    it (yet - see OI-534 for strict-mode output).
    """
 
    model_config = ConfigDict(extra="forbid")
 
    json_output: bool = True
    subcommand: Literal["validate-config", "list-domains"] = "validate-config"
 
 
class GitStatusArgs(BaseModel):
    """Arguments for the ``oct_git_status`` tool (``oct git status``)."""
 
    model_config = ConfigDict(extra="forbid")
 
    json_output: bool = True
    verbose: bool = False
 
 
class GitCheckArgs(BaseModel):
    """Arguments for the ``oct_git_check`` tool (``oct git check``)."""
 
    model_config = ConfigDict(extra="forbid")
 
    json_output: bool = True
    verbose: bool = False
 
 
# ---------------------------------------------------------------------
# Phase 5B - write tool models (11)
# All include confirm: bool = False for HITL gating.
# ---------------------------------------------------------------------
 
 
class FormatArgs(BaseModel):
    """Arguments for the ``oct_format`` tool (``oct format``).
 
    Double-guard: ``confirm=True`` AND ``apply=True`` are both required
    before changes are written. With ``apply=False`` the executor passes
    ``--dry-run``; with ``apply=True`` it passes ``--fix``.
 
    OI-502: ``jobs`` removed (CLI argparser exposes no ``--jobs``).
    ``json_output`` added so the executor can request ``--json`` output
    consistently with other read models.
    """
 
    model_config = ConfigDict(extra="forbid")
 
    paths: list[str] = []
    apply: bool = False       # must be True + confirm=True to write
    confirm: bool = False
    changed: bool = False
    verbose: bool = False
    json_output: bool = True
 
    @field_validator("paths", mode="after")
    @classmethod
    def paths_inside_project(cls, v: list[str], info: ValidationInfo) -> list[str]:
        return _check_paths(v, info)
 
 
class DocsArgs(BaseModel):
    """Arguments for the ``oct_docs`` tool (``oct docs``).
 
    OI-502: ``json_output`` added for model uniformity; the CLI does not
    accept ``--json`` so the executor silently omits it.
    """
 
    model_config = ConfigDict(extra="forbid")
 
    sphinx: bool = False
    doxygen: bool = False
    all_docs: bool = False    # maps to --all flag
    clean: bool = False
    dry_run: bool = True
    confirm: bool = False
    json_output: bool = True
 
 
class ExportSourceArgs(BaseModel):
    """Arguments for the ``oct_export_source`` tool (``oct export-source``).
 
    OI-502: ``json_output`` added for model uniformity.
    """
 
    model_config = ConfigDict(extra="forbid")
 
    confirm: bool = False
    verbose: bool = False
    single_dir: bool = False
    warn_secrets: bool = True
    block_secrets: bool = False
    json_output: bool = True
 
 
class NewArgs(BaseModel):
    """Arguments for the ``oct_new`` tool (``oct new``).
 
    OI-502: ``json_output`` added for model uniformity.
    """
 
    model_config = ConfigDict(extra="forbid")
 
    path: str                  # required; shell-safe + path-validated
    confirm: bool = False
    force: bool = False
    create_test: bool = False
    dry_run: bool = True
    verbose: bool = False
    json_output: bool = True
 
    @field_validator("path", mode="after")
    @classmethod
    def path_safe(cls, v: str, info: ValidationInfo) -> str:
        v = check_shell_metacharacters(v)
        root = (info.context or {}).get("project_root")
        return validate_path_in_project(v, root)
 
 
class ScaffoldArgs(BaseModel):
    """Arguments for the ``oct_scaffold`` tool (``oct scaffold``).
 
    OI-502: ``json_output`` added for model uniformity.
    """
 
    model_config = ConfigDict(extra="forbid")
 
    name: str                  # required; shell-safe (no path traversal)
    confirm: bool = False
    dry_run: bool = True
    json_output: bool = True
 
    @field_validator("name", mode="after")
    @classmethod
    def name_shell_safe(cls, v: str) -> str:
        return check_shell_metacharacters(v)
 
 
class CleanArgs(BaseModel):
    """Arguments for the ``oct_clean`` tool (``oct clean``).
 
    OI-502: ``json_output`` added for model uniformity.
    """
 
    model_config = ConfigDict(extra="forbid")
 
    path: str | None = None    # optional; path-validated if provided
    confirm: bool = False
    dry_run: bool = True
    json_output: bool = True
 
    @field_validator("path", mode="after")
    @classmethod
    def path_safe(cls, v: str | None, info: ValidationInfo) -> str | None:
        if v is None:
            return v
        v = check_shell_metacharacters(v)
        root = (info.context or {}).get("project_root")
        return validate_path_in_project(v, root)
 
 
class InstallHooksArgs(BaseModel):
    """Arguments for the ``oct_install_hooks`` tool (``oct install-hooks``).
 
    OI-502: ``json_output`` added for model uniformity.
    """
 
    model_config = ConfigDict(extra="forbid")
 
    confirm: bool = False
    force: bool = False
    json_output: bool = True
 
 
class GitCommitArgs(BaseModel):
    """Arguments for the ``oct_git_commit`` tool (``oct git commit``).
 
    Note: there is deliberately no ``no_verify`` field. Bypassing
    pre-commit hooks is never permitted via MCP (D-5B-6).
 
    OI-502 / FS-502: ``message`` was previously run through
    :func:`check_shell_metacharacters`, which rejected Conventional
    Commits syntax such as scoped types (``feat(core): add x``) and
    breaking-change markers (``feat!: drop y``). Git receives the
    message as a single ``-m <message>`` argv element - never as a
    shell-interpreted string - so shell-metacharacter filtering was
    both over-broad and protection-for-nothing. Validation now delegates
    to :func:`oct.git.conventional.validate_commit_message`, which is
    also what ``oct git commit`` enforces at the CLI.
    """
 
    model_config = ConfigDict(extra="forbid")
 
    message: str               # required; Conventional Commits compliant
    confirm: bool = False
    force: bool = False        # maps to --force (skip lint/format checks)
    json_output: bool = True
 
    @field_validator("message", mode="after")
    @classmethod
    def message_conventional(cls, v: str) -> str:
        # Import locally so that importing the validator module does not
        # pull in the entire git helper graph unless this model is used.
        from oct.git.conventional import validate_commit_message
 
        errors = validate_commit_message(v)
        if errors:
            raise ValueError(
                "Commit message is not valid Conventional Commits: "
                + "; ".join(errors)
            )
        return v
 
 
class GitHooksInstallArgs(BaseModel):
    """Arguments for the ``oct_git_hooks_install`` tool (``oct git hooks install``).
 
    OI-502: ``json_output`` added for model uniformity.
    """
 
    model_config = ConfigDict(extra="forbid")
 
    confirm: bool = False
    force: bool = False
    json_output: bool = True
 
 
class GitInitArgs(BaseModel):
    """Arguments for the ``oct_git_init`` tool (``oct git init``).
 
    OI-502: ``json_output`` added for model uniformity.
    """
 
    model_config = ConfigDict(extra="forbid")
 
    confirm: bool = False
    dry_run: bool = True
    github: bool = False       # also generate GitHub Actions workflow
    no_hooks: bool = False     # skip hook installation
    json_output: bool = True
 
 
class GitChangelogArgs(BaseModel):
    """Arguments for the ``oct_git_changelog`` tool (``oct git changelog``)."""
 
    model_config = ConfigDict(extra="forbid")
 
    confirm: bool = False
    dry_run: bool = True       # True → print to stdout, do not write CHANGELOG.md
    since: str | None = None   # e.g. ``"v0.14.0"``; shell-safe
    version: str | None = None # release version tag, e.g. ``"v0.15.0"``
 
    @field_validator("since", "version", mode="after")
    @classmethod
    def ref_shell_safe(cls, v: str | None) -> str | None:
        if v is not None:
            return check_shell_metacharacters(v)
        return v
 
 
# ---------------------------------------------------------------------
# Tool → model registry + entry point
# ---------------------------------------------------------------------
 
#: Maps MCP tool names to their Pydantic model class.
_TOOL_MODEL_MAP: dict[str, type[BaseModel]] = {
    # Phase 5A - read-only
    "oct_lint":             LintArgs,
    "oct_health":           HealthArgs,
    "oct_skeleton":         SkeletonArgs,
    "oct_deps":             DepsArgs,
    "oct_test":             OctTestArgs,
    "oct_typecheck":        TypecheckArgs,
    "oct_diag":             DiagArgs,
    "oct_git_status":       GitStatusArgs,
    "oct_git_check":        GitCheckArgs,
    # Phase 5B - write tools
    "oct_format":           FormatArgs,
    "oct_docs":             DocsArgs,
    "oct_export_source":    ExportSourceArgs,
    "oct_new":              NewArgs,
    "oct_scaffold":         ScaffoldArgs,
    "oct_clean":            CleanArgs,
    "oct_install_hooks":    InstallHooksArgs,
    "oct_git_commit":       GitCommitArgs,
    "oct_git_hooks_install": GitHooksInstallArgs,
    "oct_git_init":         GitInitArgs,
    "oct_git_changelog":    GitChangelogArgs,
}
 
 
def validate_tool_args(
    tool_name: str,
    raw_args: dict,
    project_root: Path | None = None,
) -> BaseModel:
    """Validate *raw_args* against the model for *tool_name*.
 
    Parameters
    ----------
    tool_name
        One of the 20 tool names in the manifest (e.g. ``"oct_lint"``).
    raw_args
        Unvalidated dict from the MCP client.
    project_root
        Absolute project root path, threaded through to path-containment
        validators via Pydantic's ``model_validate`` context.
 
    Returns
    -------
    A fully validated Pydantic model instance.
 
    Raises
    ------
    ValueError
        If *tool_name* is not in the tool manifest.
    pydantic.ValidationError
        If *raw_args* fails any field validator.
    """
    func = "validate_tool_args"
    model_cls = _TOOL_MODEL_MAP.get(tool_name)
    if model_cls is None:
        raise ValueError(
            f"Unknown MCP tool: {tool_name!r}. "
            f"Valid tools: {sorted(_TOOL_MODEL_MAP)}"
        )
    context: dict = {}
    if project_root is not None:
        context["project_root"] = project_root
 
    validated = model_cls.model_validate(raw_args, context=context)
    _dbg("MCP", func, f"validated tool={tool_name}", 4)
    return validated