watchllm-kernel 0.1.0__py3-none-any.whl

watchllm_kernel/__init__.py

@@ -0,0 +1,23 @@
+__version__ = "0.1.0"
+
+from watchllm_kernel.models import (
+    Decision,
+    KernelResult,
+    Rule,
+    RuleDecision,
+    RuleResult,
+    Severity,
+    SourceLocation,
+    Violation,
+)
+
+__all__ = [
+    "Decision",
+    "KernelResult",
+    "Rule",
+    "RuleDecision",
+    "RuleResult",
+    "Severity",
+    "SourceLocation",
+    "Violation",
+]

watchllm_kernel/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

watchllm_kernel/cli.py

@@ -0,0 +1,214 @@
+import argparse
+import dataclasses
+import enum
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from watchllm_kernel.engine import ENFORCE_MODE, SHADOW_MODE, evaluate_source
+from watchllm_kernel.models import Decision
+from watchllm_kernel.reporting import format_human_report, write_block_log
+from watchllm_kernel.rules.auth_flow import AuthFlowRule
+from watchllm_kernel.rules.boundary import BoundaryRule
+from watchllm_kernel.rules.forbidden_imports import ForbiddenImportRule
+from watchllm_kernel.config_loader import load_config
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _to_jsonable(obj: Any) -> Any:
+    """Convert dataclasses and enums to JSON‑serialisable primitives."""
+    if dataclasses.is_dataclass(obj):
+        return {f.name: _to_jsonable(getattr(obj, f.name)) for f in dataclasses.fields(obj)}
+    if isinstance(obj, enum.Enum):
+        return obj.value
+    if isinstance(obj, list):
+        return [_to_jsonable(item) for item in obj]
+    return obj
+
+
+def build_default_rules(config: dict | None = None):
+    """Return the default rule set for the kernel CLI, applying overrides from config.
+    """
+    config = config or {}
+    rules = []
+
+    try:
+        from watchllm_kernel.rules.secrets import SecretLiteralRule
+    except ModuleNotFoundError:
+        SecretLiteralRule = None
+
+    if SecretLiteralRule is not None:
+        secrets_cfg = config.get("rules", {}).get("secrets", {})
+        if secrets_cfg.get("enabled", True):
+            rules.append(SecretLiteralRule())
+
+    # Build Forbidden Import Rule
+    fi_cfg = config.get("rules", {}).get("forbidden_imports", {})
+    if fi_cfg.get("enabled", True):
+        rules.append(ForbiddenImportRule(
+            forbidden_modules=fi_cfg.get("modules"),
+            forbidden_prefixes=fi_cfg.get("forbidden_prefixes"),
+            allowed_relative_prefixes=fi_cfg.get("allowed_relative_prefixes")
+        ))
+
+    # Build Boundary Rule
+    boundary_cfg = config.get("rules", {}).get("boundary", {})
+    if boundary_cfg.get("enabled", True):
+        rules.append(BoundaryRule(
+            boundary_map=boundary_cfg.get("map")
+        ))
+
+    # Build Auth Flow Rule
+    auth_cfg = config.get("rules", {}).get("auth_flow", {})
+    if auth_cfg.get("enabled", True):
+        rules.append(AuthFlowRule())
+
+    return rules
+
+
+# ---------------------------------------------------------------------------
+# Argument parser
+# ---------------------------------------------------------------------------
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="watchllm-kernel",
+        description="Deterministic local write-path governance kernel for autonomous coding agents.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version="%(prog)s 0.1.0",
+    )
+
+    sub = parser.add_subparsers(dest="command", help="sub-command")
+
+    # check
+    check_parser = sub.add_parser("check", help="Check source against rules")
+    check_parser.add_argument(
+        "--stdin",
+        action="store_true",
+        help="Read source from stdin instead of a file path",
+    )
+    check_parser.add_argument(
+        "--filepath",
+        default=None,
+        help="Path to source file (ignored when --stdin is used)",
+    )
+    check_parser.add_argument(
+        "--language",
+        choices=["js", "ts"],
+        default=None,
+        help="Language identifier (js or ts). Inferred from file extension when omitted.",
+    )
+    check_parser.add_argument(
+        "--mode",
+        choices=[ENFORCE_MODE, SHADOW_MODE],
+        default=ENFORCE_MODE,
+        help="Evaluation mode (default: enforce)",
+    )
+    check_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output result as JSON",
+    )
+    return parser
+
+
+# ---------------------------------------------------------------------------
+# Language resolution
+# ---------------------------------------------------------------------------
+
+_LANGUAGE_SHORT_MAP = {
+    "js": "javascript",
+    "ts": "typescript",
+}
+
+
+def _resolve_language(language: str | None, file_path: str | None) -> str | None:
+    if language and language in _LANGUAGE_SHORT_MAP:
+        return _LANGUAGE_SHORT_MAP[language]
+    if language:
+        return language
+    if file_path is None:
+        return None
+    suffix = Path(file_path).suffix.lower()
+    if suffix in (".ts", ".tsx"):
+        return "typescript"
+    if suffix in (".js", ".jsx", ".mjs", ".cjs"):
+        return "javascript"
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    if argv is None:
+        argv = sys.argv[1:]
+
+    if not argv:
+        parser.print_help()
+        return 0
+
+    args = parser.parse_args(argv)
+
+    if args.command != "check":
+        parser.print_help()
+        return 0
+
+    # --- read source ---
+    if args.stdin:
+        source = sys.stdin.read()
+        file_path = None
+    else:
+        if args.filepath is None:
+            print("Error: either --stdin or --filepath is required", file=sys.stderr)
+            return 2
+        file_path = args.filepath
+        try:
+            source = Path(file_path).read_text(encoding="utf-8")
+        except Exception as exc:
+            print(f"Error reading file {file_path}: {exc}", file=sys.stderr)
+            return 2
+
+    language = _resolve_language(args.language, file_path)
+
+    # --- load config ---
+    start_path = str(Path(file_path).parent) if file_path else "."
+    config = load_config(start_path=start_path)
+
+    # --- evaluate ---
+    rules = build_default_rules(config=config)
+    result = evaluate_source(
+        source,
+        file_path=file_path,
+        language=language,
+        rules=rules,
+        mode=args.mode,
+    )
+
+    # --- local blocked-event logging ---
+    write_block_log(result)
+
+    # --- output ---
+    if args.json:
+        payload = _to_jsonable(result)
+        json.dump(payload, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+    else:
+        print(format_human_report(result))
+
+    # exit code
+    if result.decision == Decision.BLOCK:
+        return 1
+    return 0

watchllm_kernel/config_loader.py

@@ -0,0 +1,43 @@
+import os
+import yaml
+from typing import Any, Dict, Optional
+
+CONFIG_FILENAME = ".watchllm.yaml"
+
+def find_config(start_path: str = ".") -> Optional[str]:
+    """Search for .watchllm.yaml starting from start_path and moving upwards."""
+    current_path = os.path.abspath(start_path)
+    
+    while True:
+        potential_config = os.path.join(current_path, CONFIG_FILENAME)
+        if os.path.isfile(potential_config):
+            return potential_config
+            
+        parent = os.path.dirname(current_path)
+        if parent == current_path:
+            break
+        current_path = parent
+        
+    return None
+
+def load_config(config_path: Optional[str] = None, start_path: str = ".") -> Dict[str, Any]:
+    """Load the WatchLLM configuration from the given path or auto-discover it."""
+    if not config_path:
+        config_path = find_config(start_path)
+        
+    if not config_path or not os.path.isfile(config_path):
+        return {}
+        
+    try:
+        with open(config_path, "r", encoding="utf-8") as f:
+            config = yaml.safe_load(f)
+            return config if config else {}
+    except Exception as e:
+        print(f"Warning: Failed to load config from {config_path}: {e}")
+        return {}
+
+def get_rule_config(config: Dict[str, Any], rule_name: str) -> Dict[str, Any]:
+    """Extract configuration for a specific rule."""
+    if not config or "rules" not in config or not config["rules"]:
+        return {}
+    return config["rules"].get(rule_name, {})

watchllm_kernel/engine.py

@@ -0,0 +1,115 @@
+"""Deterministic decision engine for the WatchLLM kernel.
+
+Combines rule results into a single kernel-level decision.
+
+The engine now parses source **once** via ``parser.parse_source`` and
+passes the resulting ``ParseResult`` to every rule, eliminating the
+redundant per-rule parsing that existed previously.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from watchllm_kernel.models import Decision, KernelResult, Rule, RuleDecision, RuleResult, Violation
+from watchllm_kernel.parser import parse_source
+from watchllm_kernel.rules._ast_utils import infer_language_from_path
+
+# ---------------------------------------------------------------------------
+# Mode constants
+# ---------------------------------------------------------------------------
+
+ENFORCE_MODE = "enforce"
+SHADOW_MODE = "shadow"
+VALID_MODES = frozenset({ENFORCE_MODE, SHADOW_MODE})
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def has_blocking_failure(rule_results: list[RuleResult]) -> bool:
+    """Return True if any rule result is a FAIL.
+
+    PASS and INCONCLUSIVE are not considered blocking for Task 10.
+    """
+    return any(rr.status == RuleDecision.FAIL for rr in rule_results)
+
+
+def collect_violations(rule_results: list[RuleResult]) -> list[Violation]:
+    """Return a flat list of all violations from *rule_results*.
+
+    Preserves rule execution order and violation order inside each rule.
+    """
+    violations: list[Violation] = []
+    for rr in rule_results:
+        violations.extend(rr.violations)
+    return violations
+
+
+def reduce_decision(
+    rule_results: list[RuleResult], mode: str = ENFORCE_MODE
+) -> Decision:
+    """Reduce a list of rule results into a single kernel decision.
+
+    Raises ValueError if *mode* is not a recognised mode.
+    """
+    if mode not in VALID_MODES:
+        raise ValueError(
+            f"Unknown mode {mode!r}. Valid modes: {sorted(VALID_MODES)}"
+        )
+
+    if mode == SHADOW_MODE:
+        return Decision.ALLOW
+
+    # enforce mode
+    if has_blocking_failure(rule_results):
+        return Decision.BLOCK
+    return Decision.ALLOW
+
+
+# ---------------------------------------------------------------------------
+# Evaluator
+# ---------------------------------------------------------------------------
+
+
+def evaluate_source(
+    source: str,
+    *,
+    file_path: str | None = None,
+    language: str | None = None,
+    rules: list[Rule] | tuple[Rule, ...],
+    mode: str = ENFORCE_MODE,
+) -> KernelResult:
+    """Run *rules* against *source* and return a coherent KernelResult.
+
+    The engine parses the source **once** and shares the ``ParseResult``
+    with every rule, eliminating redundant tree-sitter work.
+
+    Rules are evaluated in the given order.  Exceptions are not caught in
+    Task 10 – failing fast is acceptable for now.
+    """
+    if mode not in VALID_MODES:
+        raise ValueError(
+            f"Unknown mode {mode!r}. Valid modes: {sorted(VALID_MODES)}"
+        )
+
+    # Parse once — infer language from file_path if not given explicitly.
+    resolved_language = language or infer_language_from_path(file_path)
+    parse_result = parse_source(source, language=resolved_language, file_path=file_path)
+
+    rule_results: list[RuleResult] = []
+    for rule in rules:
+        result = rule.evaluate(source, file_path=file_path, parse_result=parse_result)
+        rule_results.append(result)
+
+    decision = reduce_decision(rule_results, mode=mode)
+
+    return KernelResult(
+        decision=decision,
+        rule_results=rule_results,
+        file_path=file_path,
+        language=resolved_language,
+        mode=mode,
+    )

watchllm_kernel/models.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import dataclasses
+import enum
+from typing import TYPE_CHECKING, Any, Optional
+
+if TYPE_CHECKING:
+    from watchllm_kernel.parser import ParseResult
+
+
+class Decision(enum.Enum):
+    """Top-level decision returned by the kernel."""
+    ALLOW = "ALLOW"
+    BLOCK = "BLOCK"
+
+
+class RuleDecision(enum.Enum):
+    """Per-rule decision."""
+    PASS = "PASS"
+    FAIL = "FAIL"
+    INCONCLUSIVE = "INCONCLUSIVE"
+
+
+class Severity(enum.Enum):
+    """Severity of a rule violation."""
+    CRITICAL = "CRITICAL"
+    HIGH = "HIGH"
+    MEDIUM = "MEDIUM"
+    LOW = "LOW"
+    INFO = "INFO"
+
+
+@dataclasses.dataclass
+class SourceLocation:
+    """Location span in source code."""
+    line: int
+    column: int
+    end_line: Optional[int] = None
+    end_column: Optional[int] = None
+
+
+@dataclasses.dataclass
+class Violation:
+    """A single rule violation."""
+    rule_id: str
+    message: str
+    location: Optional[SourceLocation] = None
+    severity: Severity = Severity.HIGH
+    evidence: Optional[str] = None
+
+
+@dataclasses.dataclass
+class RuleResult:
+    """Result of evaluating a single rule."""
+    rule_id: str
+    status: RuleDecision
+    violations: list[Violation] = dataclasses.field(default_factory=list)
+
+
+@dataclasses.dataclass
+class KernelResult:
+    """Aggregated result from the kernel."""
+    decision: Decision
+    rule_results: list[RuleResult] = dataclasses.field(default_factory=list)
+    file_path: Optional[str] = None
+    language: Optional[str] = None
+    mode: str = "enforce"
+
+
+class Rule:
+    """Abstract base for a deterministic rule.
+
+    Every rule must implement ``evaluate`` and return a ``RuleResult``.
+
+    Parameters passed to ``evaluate``:
+        source:       The raw source text.
+        file_path:    Optional path of the file being evaluated.
+        parse_result: Optional pre-parsed ``ParseResult`` from the engine.
+                      When provided, rules should use it instead of parsing
+                      the source again.  Rules must still work correctly
+                      when ``parse_result`` is ``None``.
+    """
+
+    def __init__(self, rule_id: str, name: str, description: str = ""):
+        self.rule_id = rule_id
+        self.name = name
+        self.description = description
+
+    def evaluate(
+        self,
+        source: str,
+        file_path: Optional[str] = None,
+        parse_result: Optional[ParseResult] = None,
+    ) -> RuleResult:
+        """Evaluate the rule against the given source text.
+
+        Subclasses must override this method.
+        """
+        raise NotImplementedError("Subclasses must implement evaluate()")
+

watchllm_kernel/parser.py

@@ -0,0 +1,128 @@
+"""Parser abstraction for the WatchLLM kernel.
+
+Provides a minimal, deterministic interface to Tree-sitter for JavaScript
+and TypeScript source files.  The module exposes a single `parse_source`
+function that returns a structured parse result containing the raw
+Tree-sitter tree and a convenience traversal helper.
+
+This module is intentionally narrow: it does not perform rule evaluation,
+enforcement, or any decision-making.  It exists solely to give rule
+implementations a stable AST surface.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import Any, Optional
+
+import tree_sitter_javascript
+import tree_sitter_typescript
+from tree_sitter import Language, Parser, Node, Tree
+
+
+# ---------------------------------------------------------------------------
+# Language registry
+# ---------------------------------------------------------------------------
+
+_LANGUAGE_MAP: dict[str, Language] = {
+    "javascript": Language(tree_sitter_javascript.language()),
+    "typescript": Language(tree_sitter_typescript.language_typescript()),
+    "tsx": Language(tree_sitter_typescript.language_tsx()),
+}
+
+
+def _resolve_language(language: str) -> Language:
+    """Return the Tree-sitter Language for *language*.
+
+    Raises `ValueError` when the language is not supported.
+    """
+    lang = _LANGUAGE_MAP.get(language)
+    if lang is None:
+        raise ValueError(
+            f"Unsupported language '{language}'. "
+            f"Supported: {', '.join(sorted(_LANGUAGE_MAP))}"
+        )
+    return lang
+
+
+# ---------------------------------------------------------------------------
+# Parse result
+# ---------------------------------------------------------------------------
+
+
+@dataclasses.dataclass
+class ParseResult:
+    """Result of parsing a single source file.
+
+    Attributes:
+        tree: The raw Tree-sitter parse tree.  Callers may traverse it
+            directly or use the helper methods on this class.
+        source: The original source text (bytes).
+        language: The language identifier that was used for parsing.
+        file_path: Optional path of the file that was parsed.
+    """
+
+    tree: Tree
+    source: bytes
+    language: str
+    file_path: Optional[str] = None
+
+    @property
+    def root_node(self) -> Node:
+        """Convenience accessor for the root syntax node."""
+        return self.tree.root_node
+
+    def walk(self):
+        """Return a Tree-sitter TreeCursor for depth-first traversal."""
+        return self.tree.walk()
+
+    def query(self, query_string: str) -> dict[str, list[Node]]:
+        """Execute a Tree-sitter query against the parse tree.
+
+        Returns a dictionary mapping capture names to lists of captured
+        nodes.  Raises ``tree_sitter.QueryError`` if the query is malformed.
+        """
+        from tree_sitter import Query as _Query, QueryCursor as _QueryCursor
+        lang = _resolve_language(self.language)
+        q = _Query(lang, query_string)
+        return _QueryCursor(q).captures(self.root_node)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def parse_source(
+    source: str,
+    language: str,
+    file_path: Optional[str] = None,
+) -> ParseResult:
+    """Parse *source* text using the Tree-sitter grammar for *language*.
+
+    Parameters:
+        source: The source code to parse (a Python string).
+        language: One of ``"javascript"``, ``"typescript"``, or ``"tsx"``.
+        file_path: Optional path used for reporting; not used for parsing.
+
+    Returns:
+        A `ParseResult` wrapping the raw Tree-sitter tree and the original
+        source bytes.
+
+    Raises:
+        ValueError: If *language* is not supported.
+        tree_sitter.LanguageError: If the grammar cannot be loaded (should
+            not happen with the bundled grammars).
+    """
+    lang = _resolve_language(language)
+    parser = Parser(lang)
+
+    source_bytes = source.encode("utf-8")
+    tree = parser.parse(source_bytes)
+
+    return ParseResult(
+        tree=tree,
+        source=source_bytes,
+        language=language,
+        file_path=file_path,
+    )