bezoar 1.0.0a2__py3-none-any.whl

bezoar/__init__.py

@@ -0,0 +1,24 @@
+"""bezoar — offline scanner for the AI-agent supply chain."""
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+from .models import CONTRACT_VERSION, Verdict
+
+try:
+    __version__ = version("bezoar")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.1.0"
+
+
+def scan(root: Path) -> Verdict:
+    """P0 facade: ``scan(Path) -> Verdict``. Delegates to ``engine.scan`` until WS-F."""
+    import importlib
+
+    engine = importlib.import_module("bezoar.engine")
+    result: Verdict = engine.scan(root)
+    return result
+
+
+__all__ = ["CONTRACT_VERSION", "Verdict", "__version__", "scan"]

bezoar/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m bezoar`` entry point — delegates to :func:`bezoar.cli.main`."""
+from __future__ import annotations
+
+from bezoar.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

bezoar/adapters/__init__.py

@@ -0,0 +1,15 @@
+"""Adapter auto-discovery stub. Never hand-edited (draft-claude §6.3 / §13.1)."""
+from __future__ import annotations
+
+from typing import Any
+
+
+def __getattr__(name: str) -> Any:
+    if name == "ALL_ADAPTERS":
+        from bezoar.registry import load_adapters
+
+        return load_adapters()
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = ["ALL_ADAPTERS"]

bezoar/adapters/base.py

@@ -0,0 +1,505 @@
+"""Shared adapter helpers (draft-claude §6.2)."""
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Iterator, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from bezoar.errors import ParseError
+from bezoar.models import (
+    Capability,
+    Component,
+    ComponentFile,
+    ComponentKind,
+    Dependency,
+    Location,
+    Platform,
+    Provenance,
+    Scope,
+)
+from bezoar.parsing.frontmatter import FrontmatterResult
+from bezoar.parsing.frontmatter import parse as parse_frontmatter
+from bezoar.parsing.mcp_config import McpServerRecord
+from bezoar.parsing.text import (
+    DEFAULT_MAX_FILE_BYTES,
+    language_from_path,
+    load_text,
+)
+
+DEFAULT_MAX_DEPTH = 12
+
+DEFAULT_EXCLUDE: tuple[str, ...] = (
+    "**/.git/**",
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/venv/**",
+    "**/dist/**",
+    "**/__pycache__/**",
+    "**/.tox/**",
+    "**/.mypy_cache/**",
+    "**/.ruff_cache/**",
+    "**/.pytest_cache/**",
+)
+
+_HEAVY_DIRS = frozenset({
+    ".git",
+    "node_modules",
+    ".venv",
+    "venv",
+    "dist",
+    "__pycache__",
+    ".tox",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".pytest_cache",
+})
+
+_PINNED_SPEC = re.compile(
+    r"@\d|==|@sha256:|@[0-9a-fA-F]{7,}|==\s*\d|@v?\d+\.\d+"
+)
+
+
+def _glob_to_re(pattern: str) -> re.Pattern[str]:
+    pattern = pattern.replace("\\", "/")
+    parts: list[str] = []
+    i = 0
+    while i < len(pattern):
+        if pattern.startswith("**/", i):
+            parts.append("(?:.*/)?")
+            i += 3
+        elif pattern.startswith("**", i):
+            parts.append(".*")
+            i += 2
+        elif pattern[i] == "*":
+            parts.append("[^/]*")
+            i += 1
+        elif pattern[i] == "?":
+            parts.append("[^/]")
+            i += 1
+        else:
+            parts.append(re.escape(pattern[i]))
+            i += 1
+    return re.compile("^" + "".join(parts) + "$")
+
+
+def _compile_globs(patterns: Sequence[str]) -> list[re.Pattern[str]]:
+    return [_glob_to_re(p) for p in patterns]
+
+
+def _posix_rel(root: Path, path: Path) -> str:
+    try:
+        return path.relative_to(root).as_posix()
+    except ValueError:
+        return path.name
+
+
+def _matches(rel: str, patterns: Sequence[re.Pattern[str]]) -> bool:
+    posix = rel.replace("\\", "/")
+    return any(p.match(posix) or p.match(posix + "/") for p in patterns)
+
+
+def walk(
+    root: Path,
+    *,
+    include: Sequence[str],
+    exclude: Sequence[str],
+    max_depth: int,
+) -> Iterator[Path]:
+    """Yield files under ``root`` without following symlinks.
+
+    Empty ``include`` means every file. Heavy VCS/vendor directories are always
+    skipped in addition to ``exclude`` globs.
+    """
+    root = root.resolve()
+    include_re = _compile_globs(include) if include else []
+    exclude_re = _compile_globs(exclude if exclude else DEFAULT_EXCLUDE)
+
+    def _allowed(rel: str) -> bool:
+        if _matches(rel, exclude_re):
+            return False
+        return not include_re or _matches(rel, include_re)
+
+    if root.is_file():
+        rel = root.name
+        if _allowed(rel):
+            yield root
+        return
+    if not root.is_dir():
+        return
+
+    stack: list[tuple[Path, int]] = [(root, 0)]
+    while stack:
+        current, depth = stack.pop()
+        if depth > max_depth:
+            continue
+        try:
+            with os.scandir(current) as entries:
+                children = sorted(entries, key=lambda e: e.name)
+        except OSError:
+            continue
+        for entry in children:
+            try:
+                is_link = entry.is_symlink()
+            except OSError:
+                continue
+            if is_link:
+                continue
+            name = entry.name
+            child = Path(entry.path)
+            rel = _posix_rel(root, child)
+            if entry.is_dir(follow_symlinks=False):
+                if name in _HEAVY_DIRS:
+                    continue
+                if _matches(rel + "/", exclude_re) or _matches(rel + "/**", exclude_re):
+                    continue
+                if _matches("**/" + name + "/**", exclude_re):
+                    continue
+                stack.append((child, depth + 1))
+                continue
+            if entry.is_file(follow_symlinks=False) and _allowed(rel):
+                yield child
+
+
+@dataclass(slots=True)
+class ReadComponentFile(ComponentFile):
+    """ComponentFile that carries read-time truncation / I/O diagnostics."""
+
+    diagnostics: list[dict[str, Any]] = field(default_factory=list)
+
+
+def file_read_diagnostics(file: ComponentFile) -> list[dict[str, Any]]:
+    extra = getattr(file, "diagnostics", None)
+    if not isinstance(extra, list):
+        return []
+    return [dict(item) for item in extra if isinstance(item, dict)]
+
+
+def read_component_file(
+    path: Path,
+    *,
+    relpath: str,
+    max_file_bytes: int,
+) -> ReadComponentFile:
+    """Single-file bounded read with truncation / unreadable diagnostics."""
+    loaded = load_text(path, max_file_bytes=max_file_bytes, relpath=relpath)
+    return ReadComponentFile(
+        path=path,
+        relpath=relpath,
+        text=loaded.text,
+        sha256=loaded.sha256,
+        size=loaded.size,
+        is_binary=loaded.is_binary,
+        language=language_from_path(path),
+        diagnostics=loaded.diagnostics_list(),
+    )
+
+
+def read_component_files(
+    root: Path,
+    *,
+    max_file_bytes: int,
+    exclude: Sequence[str],
+    diagnostics: list[dict[str, Any]] | None = None,
+) -> list[ComponentFile]:
+    files: list[ComponentFile] = []
+    root = root.resolve()
+    paths = walk(root, include=(), exclude=exclude, max_depth=DEFAULT_MAX_DEPTH)
+    for path in sorted(paths, key=lambda p: p.as_posix()):
+        rel = (_posix_rel(root, path) if root.is_dir() else path.name).replace("\\", "/")
+        file = read_component_file(path, relpath=rel, max_file_bytes=max_file_bytes)
+        if diagnostics is not None:
+            diagnostics.extend(file_read_diagnostics(file))
+        files.append(file)
+    return files
+
+
+def _tools_from_frontmatter(
+    data: dict[str, Any],
+    line_map: dict[str, int],
+    relpath: str,
+) -> list[Capability]:
+    raw = data.get("allowed-tools", data.get("allowed_tools", data.get("tools")))
+    key = "allowed-tools" if "allowed-tools" in data else (
+        "allowed_tools" if "allowed_tools" in data else "tools"
+    )
+    line = line_map.get(key, line_map.get("allowed-tools", 1))
+    source = Location(relpath=relpath, line=line)
+    caps: list[Capability] = []
+    values: list[str] = []
+    if isinstance(raw, str):
+        values = [part.strip() for part in re.split(r"[\s,]+", raw) if part.strip()]
+    elif isinstance(raw, (list, tuple)):
+        values = [str(v) for v in raw]
+    for value in values:
+        lowered = value.lower()
+        cap_kind: Any = "tool"
+        if "bypass" in lowered:
+            cap_kind = "bypass"
+        elif "bash" in lowered:
+            cap_kind = "exec"
+        caps.append(Capability(kind=cap_kind, value=value, source=source))
+    mode = data.get("permissionMode") or data.get("permission_mode")
+    if isinstance(mode, str) and "bypass" in mode.lower():
+        caps.append(
+            Capability(
+                kind="bypass",
+                value=mode,
+                source=Location(relpath=relpath, line=line_map.get("permissionMode", line)),
+            )
+        )
+    return caps
+
+
+def _frontmatter_diag(relpath: str, message: str, line: int) -> dict[str, Any]:
+    return {
+        "code": "adapter/parse-error",
+        "message": message,
+        "location": {"relpath": relpath, "line": line, "column": 1},
+    }
+
+
+def _safe_frontmatter(text: str, *, relpath: str) -> tuple[FrontmatterResult, list[dict[str, Any]]]:
+    """Parse frontmatter; recoverable YAML shape never raises."""
+    diags: list[dict[str, Any]] = []
+    try:
+        fm = parse_frontmatter(text, relpath=relpath)
+    except ParseError as exc:
+        fm = FrontmatterResult(data={}, line_map={}, body=text, body_start_line=1)
+        diags.append(_frontmatter_diag(relpath, str(exc), exc.line or 1))
+        return fm, diags
+    if fm.recovered:
+        diags.append(
+            _frontmatter_diag(
+                relpath,
+                fm.warning or "invalid YAML frontmatter recovered as strings",
+                fm.recover_line or 1,
+            )
+        )
+    return fm, diags
+
+
+def _frontmatter_component(
+    path: Path,
+    *,
+    kind: ComponentKind,
+    platform: Platform,
+    scope: Scope,
+    max_file_bytes: int,
+    entrypoint: str | None,
+) -> Component:
+    relpath = path.name
+    file = read_component_file(path, relpath=relpath, max_file_bytes=max_file_bytes)
+    fm, diags = _safe_frontmatter(file.text, relpath=relpath)
+    diags.extend(file_read_diagnostics(file))
+    name = str(fm.data.get("name") or path.stem)
+    description = fm.data.get("description")
+    metadata: dict[str, Any] = {
+        "frontmatter_line_map": fm.line_map,
+        "body_start_line": fm.body_start_line,
+    }
+    if diags:
+        metadata["diagnostics"] = diags
+    return Component(
+        kind=kind,
+        root=path if path.is_file() else path.parent,
+        name=name,
+        provenance=Provenance(platform=platform, scope=scope, origin="local"),
+        manifest=dict(fm.data),
+        files=[file],
+        version=str(fm.data["version"]) if fm.data.get("version") is not None else None,
+        description=str(description) if description is not None else None,
+        entrypoint=entrypoint,
+        capabilities=_tools_from_frontmatter(fm.data, fm.line_map, relpath),
+        metadata=metadata,
+    )
+
+
+def skill_from_dir(
+    root: Path,
+    platform: Platform,
+    scope: Scope,
+    *,
+    max_file_bytes: int = DEFAULT_MAX_FILE_BYTES,
+    exclude: Sequence[str] = DEFAULT_EXCLUDE,
+) -> Component:
+    """SKILL.md + frontmatter → Component."""
+    root = root.resolve()
+    read_diags: list[dict[str, Any]] = []
+    files = read_component_files(
+        root, max_file_bytes=max_file_bytes, exclude=exclude, diagnostics=read_diags
+    )
+    skill = next((f for f in files if Path(f.relpath).name == "SKILL.md"), None)
+    fm, diags = _safe_frontmatter(skill.text if skill else "", relpath="SKILL.md")
+    diags.extend(read_diags)
+    name = str(fm.data.get("name") or root.name)
+    description = fm.data.get("description")
+    caps = _tools_from_frontmatter(fm.data, fm.line_map, "SKILL.md")
+    metadata: dict[str, Any] = {"frontmatter_line_map": fm.line_map}
+    if diags:
+        metadata["diagnostics"] = diags
+    return Component(
+        kind=ComponentKind.SKILL,
+        root=root,
+        name=name,
+        provenance=Provenance(platform=platform, scope=scope, origin="local"),
+        manifest=dict(fm.data),
+        files=files,
+        version=str(fm.data["version"]) if fm.data.get("version") is not None else None,
+        description=str(description) if description is not None else None,
+        entrypoint="SKILL.md",
+        capabilities=caps,
+        metadata=metadata,
+    )
+
+
+def subagent_from_file(
+    path: Path,
+    platform: Platform,
+    scope: Scope,
+    *,
+    max_file_bytes: int = DEFAULT_MAX_FILE_BYTES,
+) -> Component:
+    return _frontmatter_component(
+        path,
+        kind=ComponentKind.SUBAGENT,
+        platform=platform,
+        scope=scope,
+        max_file_bytes=max_file_bytes,
+        entrypoint=path.name,
+    )
+
+
+def rules_from_file(
+    path: Path,
+    platform: Platform,
+    scope: Scope,
+    *,
+    max_file_bytes: int = DEFAULT_MAX_FILE_BYTES,
+) -> Component:
+    return _frontmatter_component(
+        path,
+        kind=ComponentKind.RULES,
+        platform=platform,
+        scope=scope,
+        max_file_bytes=max_file_bytes,
+        entrypoint=path.name,
+    )
+
+
+def _dep_from_command(command: str, args: Sequence[str], source: Location) -> Dependency:
+    tokens = [command, *args]
+    joined = " ".join(tokens)
+    kind: Any = "binary"
+    spec = joined
+    if command in {"npx", "npm", "pnpm", "yarn"} or command.endswith("npx"):
+        kind = "npm"
+        spec = next((a for a in args if a not in {"-y", "--yes", "-p", "--package"}), command)
+    elif command in {"uvx", "uv", "pip", "pipx", "python", "python3"}:
+        kind = "pypi"
+        spec = next((a for a in args if not a.startswith("-")), command)
+    elif command in {"docker"}:
+        kind = "docker"
+        spec = joined
+    pinned = _PINNED_SPEC.search(spec) is not None
+    return Dependency(kind=kind, spec=spec, pinned=pinned, source=source)
+
+
+def mcp_from_record(
+    rec: McpServerRecord,
+    platform: Platform,
+    scope: Scope,
+    *,
+    config_path: Path | None = None,
+    max_file_bytes: int = DEFAULT_MAX_FILE_BYTES,
+) -> Component:
+    source = rec.source
+    caps: list[Capability] = []
+    deps: list[Dependency] = []
+    if rec.command:
+        caps.append(Capability(kind="exec", value=rec.command, source=source))
+        deps.append(_dep_from_command(rec.command, rec.args, source))
+    if rec.url:
+        caps.append(Capability(kind="network", value=rec.url, source=source))
+    for key in sorted(rec.env):
+        caps.append(Capability(kind="env", value=key, source=source))
+    files: list[ComponentFile] = []
+    root = config_path if config_path is not None else Path(rec.source.relpath)
+    extra_diags: list[dict[str, Any]] = []
+    if config_path is not None and config_path.is_file():
+        file = read_component_file(
+            config_path,
+            relpath=config_path.name,
+            max_file_bytes=max_file_bytes,
+        )
+        files.append(file)
+        extra_diags.extend(file_read_diagnostics(file))
+    manifest: dict[str, Any] = {
+        "name": rec.name,
+        "transport": rec.transport,
+        "command": rec.command,
+        "args": list(rec.args),
+        "env": dict(rec.env),
+        "url": rec.url,
+        "headers": dict(rec.headers),
+        "raw": rec.raw,
+    }
+    metadata: dict[str, Any] = {}
+    if extra_diags:
+        metadata["diagnostics"] = extra_diags
+    return Component(
+        kind=ComponentKind.MCP,
+        root=root,
+        name=rec.name,
+        provenance=Provenance(
+            platform=platform,
+            scope=scope,
+            origin="config",
+            declared_in=source,
+        ),
+        manifest=manifest,
+        files=files,
+        entrypoint=rec.command or rec.url,
+        capabilities=caps,
+        dependencies=deps,
+        metadata=metadata,
+    )
+
+
+def _xdg_config_home() -> Path:
+    raw = os.environ.get("XDG_CONFIG_HOME")
+    if raw:
+        return Path(raw)
+    return Path.home() / ".config"
+
+
+def home_roots(platform: Platform) -> list[Path]:
+    """User-scope roots, honouring ``$CLAUDE_CONFIG_DIR``, ``$CODEX_HOME``, ``$XDG_*``."""
+    home = Path.home()
+    xdg = _xdg_config_home()
+    roots: list[Path] = []
+    if platform is Platform.CLAUDE_CODE:
+        env = os.environ.get("CLAUDE_CONFIG_DIR")
+        roots.append(Path(env) if env else home / ".claude")
+        roots.append(xdg / "claude")
+    elif platform is Platform.CURSOR:
+        roots.extend([home / ".cursor", xdg / "cursor"])
+    elif platform is Platform.CODEX:
+        env = os.environ.get("CODEX_HOME")
+        roots.append(Path(env) if env else home / ".codex")
+        roots.append(xdg / "codex")
+    elif platform is Platform.GEMINI_CLI:
+        roots.extend([home / ".gemini", xdg / "gemini"])
+    elif platform is Platform.COPILOT:
+        roots.extend([home / ".copilot", xdg / "github-copilot"])
+    seen: set[Path] = set()
+    out: list[Path] = []
+    for root in roots:
+        resolved = root.expanduser()
+        if resolved in seen:
+            continue
+        seen.add(resolved)
+        out.append(resolved)
+    return out