watchllm-kernel 0.1.0__tar.gz

watchllm_kernel-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: watchllm-kernel
+Version: 0.1.0
+Summary: Deterministic local runtime governance kernel for autonomous coding agents.
+Author: WatchLLM
+License: Apache-2.0
+Keywords: watchllm,kernel,runtime-governance,agent-governance,static-analysis
+Classifier: Development Status :: 1 - Planning
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: tree-sitter>=0.21.0
+Requires-Dist: tree-sitter-javascript>=0.21.0
+Requires-Dist: tree-sitter-typescript>=0.21.0
+Requires-Dist: pyyaml>=6.0.0
+
+# WatchLLM Kernel
+
+```
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+░  ░░░░  ░░░      ░░░        ░░░      ░░░  ░░░░  ░░  ░░░░░░░░  ░░░░░░░░  ░░░░  ░
+▒  ▒  ▒  ▒▒  ▒▒▒▒  ▒▒▒▒▒  ▒▒▒▒▒  ▒▒▒▒  ▒▒  ▒▒▒▒  ▒▒  ▒▒▒▒▒▒▒▒  ▒▒▒▒▒▒▒▒   ▒▒   ▒
+▓        ▓▓  ▓▓▓▓  ▓▓▓▓▓  ▓▓▓▓▓  ▓▓▓▓▓▓▓▓        ▓▓  ▓▓▓▓▓▓▓▓  ▓▓▓▓▓▓▓▓        ▓
+█   ██   ██        █████  █████  ████  ██  ████  ██  ████████  ████████  █  █  █
+█  ████  ██  ████  █████  ██████      ███  ████  ██        ██        ██  ████  █
+████████████████████████████████████████████████████████████████████████████████
+```
+
+Deterministic local write-path governance kernel for autonomous coding agents.
+
+## Current status
+
+Task 14 complete — core model layer, parser abstraction, fixture corpus, rule implementations, deterministic decision engine, CLI evaluation interface, end-to-end regression tests, baseline performance benchmarks, and local blocked-event reporting exist. Save-path editor integration is not implemented yet.
+
+## Installation
+
+```bash
+python -m pip install -e .
+```
+
+## Usage
+
+```bash
+watchllm-kernel --help
+python -m watchllm_kernel --help
+```
+
+## Fixture corpus
+
+Rule evidence fixtures live under `tests/fixtures/rules/`.
+
+Each MVP rule category has a minimal `pass/` and `fail/` fixture set:
+
+- `secrets`
+- `forbidden_imports`
+- `boundary`
+- `auth_flow`
+
+These fixtures are rule evidence examples and are used by rule-specific tests as each rule is implemented.
+
+## Implemented rules
+
+### Secret-literal rule
+
+The secret-literal rule detects hardcoded credential patterns in assignment contexts and dangerous call contexts. It uses AST context to avoid flagging safe retrieval calls such as `process.env.STRIPE_SECRET` or `os.getenv("STRIPE_SECRET")`.
+
+### Forbidden-import rule
+
+The forbidden-import rule blocks dangerous imports such as `child_process` and disallowed relative traversal imports. It extracts ES module imports and CommonJS `require(...)` calls using AST traversal rather than raw text scanning.
+
+### Boundary rule
+
+The boundary rule checks AST-extracted import edges against a small declared boundary map. In the current policy, `auth` may import the public DB contract but must not import `db/internal` paths directly.
+
+Circular dependency detection is explicitly deferred because Task 08 evaluates single-file import edges only, not a repository-wide import graph.
+
+### Auth-flow rule
+
+The auth-flow rule checks calls inside an exported `handler` function and requires an explicit auth guard before protected database operations such as `db.user.update(...)`.
+
+Current Task 09 behaviour is intentionally narrow:
+
+- mutation before auth returns `FAIL`
+- auth before mutation returns `PASS`
+- auth found only inside an ambiguous branch before mutation returns `INCONCLUSIVE`
+
+Repository-wide control-flow analysis is not implemented yet.
+
+## Decision engine
+
+The decision engine runs a supplied ordered list of rules against one source buffer and reduces their rule results into one `KernelResult`.
+
+In enforce mode, any rule failure produces `BLOCK`.
+
+In shadow mode, rule failures are preserved in the result but the final decision remains `ALLOW`.
+
+For Task 10, `INCONCLUSIVE` rule results are recorded but do not block.
+
+## Benchmarks
+
+Run the current Python kernel benchmark suite with:
+
+```bash
+python benchmarks/run_benchmarks.py --iterations 50 --warmup 5 --json
+```
+
+Benchmark baseline documentation lives in `docs/benchmarks/baseline.md`.
+
+## Local violation reporting
+
+Blocked evaluations are written locally as JSONL.
+
+Default path:
+
+```bash
+.watchllm/logs/violations.jsonl
+```
+
+Override path:
+
+```bash
+WATCHLLM_LOG_PATH=/tmp/watchllm-violations.jsonl python -m watchllm_kernel evaluate path/to/file.ts --json
+```
+
+The reporting contract is documented in `docs/specs/reporting-contract.md`.
+
+## Non‑goals (current state)
+
+- No save-path editor integration yet
+- No cloud dependency or network enforcement

watchllm_kernel-0.1.0/README.md

@@ -0,0 +1,114 @@
+# WatchLLM Kernel
+
+```
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+░  ░░░░  ░░░      ░░░        ░░░      ░░░  ░░░░  ░░  ░░░░░░░░  ░░░░░░░░  ░░░░  ░
+▒  ▒  ▒  ▒▒  ▒▒▒▒  ▒▒▒▒▒  ▒▒▒▒▒  ▒▒▒▒  ▒▒  ▒▒▒▒  ▒▒  ▒▒▒▒▒▒▒▒  ▒▒▒▒▒▒▒▒   ▒▒   ▒
+▓        ▓▓  ▓▓▓▓  ▓▓▓▓▓  ▓▓▓▓▓  ▓▓▓▓▓▓▓▓        ▓▓  ▓▓▓▓▓▓▓▓  ▓▓▓▓▓▓▓▓        ▓
+█   ██   ██        █████  █████  ████  ██  ████  ██  ████████  ████████  █  █  █
+█  ████  ██  ████  █████  ██████      ███  ████  ██        ██        ██  ████  █
+████████████████████████████████████████████████████████████████████████████████
+```
+
+Deterministic local write-path governance kernel for autonomous coding agents.
+
+## Current status
+
+Task 14 complete — core model layer, parser abstraction, fixture corpus, rule implementations, deterministic decision engine, CLI evaluation interface, end-to-end regression tests, baseline performance benchmarks, and local blocked-event reporting exist. Save-path editor integration is not implemented yet.
+
+## Installation
+
+```bash
+python -m pip install -e .
+```
+
+## Usage
+
+```bash
+watchllm-kernel --help
+python -m watchllm_kernel --help
+```
+
+## Fixture corpus
+
+Rule evidence fixtures live under `tests/fixtures/rules/`.
+
+Each MVP rule category has a minimal `pass/` and `fail/` fixture set:
+
+- `secrets`
+- `forbidden_imports`
+- `boundary`
+- `auth_flow`
+
+These fixtures are rule evidence examples and are used by rule-specific tests as each rule is implemented.
+
+## Implemented rules
+
+### Secret-literal rule
+
+The secret-literal rule detects hardcoded credential patterns in assignment contexts and dangerous call contexts. It uses AST context to avoid flagging safe retrieval calls such as `process.env.STRIPE_SECRET` or `os.getenv("STRIPE_SECRET")`.
+
+### Forbidden-import rule
+
+The forbidden-import rule blocks dangerous imports such as `child_process` and disallowed relative traversal imports. It extracts ES module imports and CommonJS `require(...)` calls using AST traversal rather than raw text scanning.
+
+### Boundary rule
+
+The boundary rule checks AST-extracted import edges against a small declared boundary map. In the current policy, `auth` may import the public DB contract but must not import `db/internal` paths directly.
+
+Circular dependency detection is explicitly deferred because Task 08 evaluates single-file import edges only, not a repository-wide import graph.
+
+### Auth-flow rule
+
+The auth-flow rule checks calls inside an exported `handler` function and requires an explicit auth guard before protected database operations such as `db.user.update(...)`.
+
+Current Task 09 behaviour is intentionally narrow:
+
+- mutation before auth returns `FAIL`
+- auth before mutation returns `PASS`
+- auth found only inside an ambiguous branch before mutation returns `INCONCLUSIVE`
+
+Repository-wide control-flow analysis is not implemented yet.
+
+## Decision engine
+
+The decision engine runs a supplied ordered list of rules against one source buffer and reduces their rule results into one `KernelResult`.
+
+In enforce mode, any rule failure produces `BLOCK`.
+
+In shadow mode, rule failures are preserved in the result but the final decision remains `ALLOW`.
+
+For Task 10, `INCONCLUSIVE` rule results are recorded but do not block.
+
+## Benchmarks
+
+Run the current Python kernel benchmark suite with:
+
+```bash
+python benchmarks/run_benchmarks.py --iterations 50 --warmup 5 --json
+```
+
+Benchmark baseline documentation lives in `docs/benchmarks/baseline.md`.
+
+## Local violation reporting
+
+Blocked evaluations are written locally as JSONL.
+
+Default path:
+
+```bash
+.watchllm/logs/violations.jsonl
+```
+
+Override path:
+
+```bash
+WATCHLLM_LOG_PATH=/tmp/watchllm-violations.jsonl python -m watchllm_kernel evaluate path/to/file.ts --json
+```
+
+The reporting contract is documented in `docs/specs/reporting-contract.md`.
+
+## Non‑goals (current state)
+
+- No save-path editor integration yet
+- No cloud dependency or network enforcement

watchllm_kernel-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "watchllm-kernel"
+version = "0.1.0"
+description = "Deterministic local runtime governance kernel for autonomous coding agents."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [
+  { name = "WatchLLM" }
+]
+keywords = [
+  "watchllm",
+  "kernel",
+  "runtime-governance",
+  "agent-governance",
+  "static-analysis"
+]
+classifiers = [
+  "Development Status :: 1 - Planning",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Quality Assurance",
+  "Topic :: Security"
+]
+dependencies = [
+  "tree-sitter>=0.21.0",
+  "tree-sitter-javascript>=0.21.0",
+  "tree-sitter-typescript>=0.21.0",
+  "pyyaml>=6.0.0",
+]
+
+[project.scripts]
+watchllm-kernel = "watchllm_kernel.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

watchllm_kernel-0.1.0/setup.cfg

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

watchllm_kernel-0.1.0/src/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-0.1.0/src/watchllm_kernel/__main__.py

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

watchllm_kernel-0.1.0/src/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-0.1.0/src/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, {})