agent-wiki-cli 0.3.28__py3-none-any.whl

llm_wiki_cli/config.py

@@ -0,0 +1,318 @@
+"""Shared constants and utilities for agent-wiki-cli."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from fnmatch import fnmatch
+from pathlib import Path
+
+DEFAULT_WIKI_DIR = "docs/llm_wiki"
+
+# Directories excluded from source-file scans.  This intentionally covers both
+# conventional environment names (``.venv``) and environment internals
+# (``site-packages``) so renamed virtualenvs still stay out of the wiki.
+EXCLUDED_DIRS: set[str] = {
+    ".cache",
+    ".direnv",
+    ".eggs",
+    ".env",
+    ".git",
+    ".mypy_cache",
+    ".next",
+    ".nox",
+    ".npm",
+    ".nuxt",
+    ".parcel-cache",
+    ".pnpm-store",
+    ".pyre",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".svelte-kit",
+    ".tox",
+    ".venv",
+    ".virtualenv",
+    ".vite",
+    ".yarn",
+    "__pycache__",
+    "__pypackages__",
+    "bower_components",
+    "build",
+    "coverage",
+    "dist",
+    "env",
+    "htmlcov",
+    "jspm_packages",
+    "node_modules",
+    "out",
+    "site-packages",
+    "target",
+    "venv",
+    "virtualenv",
+}
+
+AGENT_CHOICES = ["claude", "cursor", "copilot", "aider", "opencode", "generic"]
+
+# Agents that have a real CLI executable (key=agent name, value=executable)
+CLI_AGENTS: dict[str, str] = {
+    "claude": "claude",
+    "aider": "aider",
+    "opencode": "opencode",
+}
+
+# Agents that are IDE-only and cannot run headlessly
+IDE_AGENTS: set[str] = {"cursor", "copilot", "generic"}
+
+# Docker file discovery patterns
+DOCKERFILE_PATTERNS: list[str] = [
+    "Dockerfile",
+    "Dockerfile.*",
+    "*.dockerfile",
+]
+COMPOSE_PATTERNS: list[str] = [
+    "docker-compose.yml",
+    "docker-compose.*.yml",
+    "docker-compose.yaml",
+    "docker-compose.*.yaml",
+    "compose.yml",
+    "compose.*.yml",
+    "compose.yaml",
+    "compose.*.yaml",
+]
+
+
+class PathValidationError(ValueError):
+    """Raised when a user-provided path escapes the project root."""
+
+
+def validate_path(path: str, label: str = "path") -> Path:
+    """Ensure *path* resolves inside the current working directory.
+
+    Raises PathValidationError with a clear message if the resolved path escapes the
+    repository root (cwd).
+    """
+    resolved = (Path.cwd() / path).resolve()
+    cwd = Path.cwd().resolve()
+    try:
+        resolved.relative_to(cwd)
+    except ValueError:
+        raise PathValidationError(
+            f"Error: {label} '{path}' resolves to '{resolved}', "
+            f"which is outside the project root '{cwd}'."
+        )
+    return resolved
+
+
+# Registry mapping language name → extractor entry point.
+# Format: "module.path:ClassName"
+# New extractors (TypeScript, Go, Rust, …) are registered here.
+EXTRACTOR_REGISTRY: dict[str, str] = {
+    "python": "llm_wiki_cli.extractors.python_extractor:PythonExtractor",
+    "typescript": "llm_wiki_cli.extractors.ts_extractor:TypeScriptExtractor",
+    "go": "llm_wiki_cli.extractors.go_extractor:GoExtractor",
+    "rust": "llm_wiki_cli.extractors.rust_extractor:RustExtractor",
+}
+
+
+def get_agent_config_path(wiki_dir: "str | Path") -> Path:
+    """Return the local-only agent config file path.
+
+    Stored at ``.git/.llm-wiki-agent`` so it is never committed and each
+    developer on a shared repo can use their own preferred agent without
+    affecting teammates.
+
+    Falls back to ``wiki_dir/.llm-wiki-agent`` when not inside a git
+    repository (e.g. bare CI environments or tests that don't init git).
+    """
+    if Path(".git").is_dir():
+        return Path(".git") / ".llm-wiki-agent"
+    return Path(wiki_dir) / ".llm-wiki-agent"
+
+
+# Default config values for new installations.
+_DEFAULT_CONFIG: dict[str, object] = {
+    "agent": "generic",
+    "quality_hints": True,
+}
+
+
+@dataclass(frozen=True)
+class _GitignoreRule:
+    base: str
+    pattern: str
+    negated: bool
+    directory_only: bool
+    anchored: bool
+
+
+class GitIgnoreMatcher:
+    """Ordered gitignore matcher for repository scans.
+
+    This supports the semantics the extractors need without reparsing the same
+    .gitignore file for every source file: negation, root-anchored patterns,
+    nested .gitignore files, directory-only rules, and common ``**`` patterns.
+    """
+
+    def __init__(self, rules: list[_GitignoreRule]):
+        self._rules = rules
+
+    def is_ignored(self, rel_path: str) -> bool:
+        rel_path = rel_path.replace("\\", "/").strip("/")
+        ignored = False
+        for rule in self._rules:
+            if _rule_matches(rel_path, rule):
+                ignored = not rule.negated
+        return ignored
+
+
+def _parse_gitignore_file(gitignore_path: Path, base: str = "") -> list[_GitignoreRule]:
+    rules: list[_GitignoreRule] = []
+    if not gitignore_path.exists():
+        return rules
+
+    try:
+        with open(gitignore_path, "r", encoding="utf-8") as f:
+            for raw in f:
+                line = raw.rstrip("\n\r")
+                if not line or line.startswith("#"):
+                    continue
+                negated = line.startswith("!")
+                if negated:
+                    line = line[1:]
+                anchored = line.startswith("/")
+                if anchored:
+                    line = line[1:]
+                directory_only = line.endswith("/")
+                line = line.rstrip("/")
+                if line:
+                    rules.append(_GitignoreRule(
+                        base=base.strip("/"),
+                        pattern=line.replace("\\", "/"),
+                        negated=negated,
+                        directory_only=directory_only,
+                        anchored=anchored,
+                    ))
+    except OSError:
+        pass
+    return rules
+
+
+def _match_gitignore_pattern(rel_path: str, pattern: str, *, directory_only: bool = False) -> bool:
+    """Check if a relative path matches a gitignore pattern."""
+    rel_path = rel_path.replace("\\", "/").strip("/")
+    pattern = pattern.replace("\\", "/").strip("/")
+
+    if not rel_path or not pattern:
+        return False
+
+    if directory_only:
+        if "/" in pattern:
+            return rel_path == pattern or rel_path.startswith(pattern + "/") or fnmatch(rel_path, pattern + "/**")
+        parts = rel_path.split("/")
+        return any(fnmatch(part, pattern) for part in parts[:-1])
+
+    if pattern.endswith("/**"):
+        prefix = pattern[:-3].rstrip("/")
+        return rel_path == prefix or rel_path.startswith(prefix + "/")
+
+    if "/" in pattern:
+        return fnmatch(rel_path, pattern) or fnmatch(rel_path, pattern + "/**")
+
+    return any(fnmatch(part, pattern) for part in rel_path.split("/"))
+
+
+def _rule_matches(rel_path: str, rule: _GitignoreRule) -> bool:
+    if rule.base:
+        if rel_path == rule.base:
+            candidate = ""
+        elif rel_path.startswith(rule.base + "/"):
+            candidate = rel_path[len(rule.base) + 1:]
+        else:
+            return False
+    else:
+        candidate = rel_path
+    if not candidate:
+        return False
+
+    if rule.anchored:
+        pattern = rule.pattern
+        if rule.directory_only:
+            return (
+                candidate == pattern
+                or candidate.startswith(pattern + "/")
+                or fnmatch(candidate, pattern + "/**")
+            )
+        if "/" not in pattern:
+            return "/" not in candidate and fnmatch(candidate, pattern)
+        return fnmatch(candidate, pattern) or fnmatch(candidate, pattern + "/**")
+
+    return _match_gitignore_pattern(
+        candidate,
+        rule.pattern,
+        directory_only=rule.directory_only,
+    )
+
+
+def build_gitignore_matcher(root: "str | Path") -> GitIgnoreMatcher:
+    """Parse root and nested .gitignore files once for a source scan."""
+    root_path = Path(root)
+    rules: list[_GitignoreRule] = []
+    if not root_path.exists():
+        return GitIgnoreMatcher(rules)
+
+    for gitignore in sorted(root_path.rglob(".gitignore")):
+        try:
+            rel_parent = gitignore.parent.relative_to(root_path)
+        except ValueError:
+            continue
+        if not EXCLUDED_DIRS.isdisjoint(rel_parent.parts):
+            continue
+        base = "" if rel_parent == Path(".") else rel_parent.as_posix()
+        rules.extend(_parse_gitignore_file(gitignore, base))
+    return GitIgnoreMatcher(rules)
+
+
+def is_ignored_by_gitignore(rel_path: str, gitignore_path: Path = Path(".gitignore")) -> bool:
+    """Check if a relative path is ignored according to one .gitignore file."""
+    matcher = GitIgnoreMatcher(_parse_gitignore_file(gitignore_path, ""))
+    return matcher.is_ignored(rel_path)
+
+
+def read_config(wiki_dir: "str | Path") -> dict:
+    """Read the persisted llm-wiki config as a dict.
+
+    Handles backward compatibility: if the file contains a bare agent name
+    string (pre-v0.3 format), it is treated as ``{"agent": "<value>", "quality_hints": true}``.
+
+    Returns *_DEFAULT_CONFIG* values for any missing keys.
+    """
+    config_path = get_agent_config_path(wiki_dir)
+    if not config_path.exists():
+        return dict(_DEFAULT_CONFIG)
+
+    raw = config_path.read_text(encoding="utf-8").strip()
+
+    # Backward compat: bare string = old format (just the agent name)
+    if not raw.startswith("{"):
+        result = dict(_DEFAULT_CONFIG)
+        result["agent"] = raw
+        return result
+
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        # Corrupted file — treat as defaults
+        result = dict(_DEFAULT_CONFIG)
+        return result
+
+    # Fill in any missing keys from defaults
+    for key, default in _DEFAULT_CONFIG.items():
+        data.setdefault(key, default)
+    return data
+
+
+def write_config(wiki_dir: "str | Path", data: dict) -> None:
+    """Persist the llm-wiki config dict to the agent config file."""
+    config_path = get_agent_config_path(wiki_dir)
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")

llm_wiki_cli/extractors/__init__.py

@@ -0,0 +1,46 @@
+"""Extractor plugin architecture for agent-wiki-cli."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class ExtractorProtocol(Protocol):
+    """Protocol that all language extractors must implement.
+
+    An extractor is responsible for scanning source files of a particular
+    language, parsing their structure (classes, functions, imports, etc.)
+    and returning a uniform inventory dict.
+
+    Each value in the returned inventory dict **must** include a
+    ``"language"`` key identifying which language produced the entry.
+    """
+
+    def extract(
+        self,
+        src_dir: str,
+        only_files: list[str] | None = None,
+        deep: bool = False,
+    ) -> dict:
+        """Scan *src_dir* and return an inventory dict mapping filepath → file_entry.
+
+        Parameters
+        ----------
+        src_dir:
+            Root directory to scan.
+        only_files:
+            Optional list of paths (relative to *src_dir*) to restrict
+            extraction to.  When ``None``, all files of the supported
+            language found under *src_dir* are scanned.
+        deep:
+            When ``True``, include enriched data (docstrings, attributes,
+            method details, imports).  When ``False``, return a slim
+            name-only summary suitable for quick index generation.
+
+        Returns
+        -------
+        dict
+            ``{filepath: file_entry}`` where each ``file_entry`` contains
+            at minimum ``"classes"``, ``"functions"``, and ``"language"``.
+        """
+        ...

llm_wiki_cli/extractors/common.py

@@ -0,0 +1,90 @@
+"""Shared helpers for source-file extractor discovery and filtering."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+from ..config import EXCLUDED_DIRS, GitIgnoreMatcher, build_gitignore_matcher
+
+LANGUAGE_EXTENSIONS: dict[str, tuple[str, ...]] = {
+    "python": (".py",),
+    "typescript": (".ts", ".tsx"),
+    "go": (".go",),
+    "rust": (".rs",),
+}
+
+
+def should_skip_source_path(path: Path, src_path: Path, matcher: GitIgnoreMatcher | None = None) -> bool:
+    """Return True when *path* should be skipped for source extraction."""
+    rel = path.relative_to(src_path)
+    if not EXCLUDED_DIRS.isdisjoint(rel.parts):
+        return True
+    if matcher and matcher.is_ignored(rel.as_posix()):
+        return True
+    return False
+
+
+def discover_source_files(
+    src_dir: str,
+    extensions: Iterable[str],
+    *,
+    only_files: list[str] | None = None,
+    language: str | None = None,
+    matcher: GitIgnoreMatcher | None = None,
+) -> list[str]:
+    """Return matching source files relative to *src_dir*.
+
+    The returned paths use forward slashes and respect excluded directories and
+    gitignore rules. Language-specific conventions that avoid generated or
+    duplicate files are handled here so Python wrappers can skip toolchains when
+    there is nothing useful to scan.
+    """
+    src_path = Path(src_dir).resolve()
+    matcher = matcher or build_gitignore_matcher(src_path)
+    extensions = tuple(extensions)
+
+    if only_files is not None:
+        candidates = [src_path / f for f in only_files]
+    else:
+        candidates = []
+        for ext in extensions:
+            candidates.extend(src_path.rglob(f"*{ext}"))
+
+    result: list[str] = []
+    seen: set[str] = set()
+    for path in candidates:
+        try:
+            resolved = path.resolve()
+            rel = resolved.relative_to(src_path)
+        except (OSError, ValueError):
+            continue
+        if not resolved.is_file() or resolved.suffix not in extensions:
+            continue
+        if should_skip_source_path(resolved, src_path, matcher):
+            continue
+        if language == "typescript" and resolved.name.endswith(".d.ts"):
+            continue
+        if language == "go" and resolved.name.endswith("_test.go"):
+            continue
+        rel_posix = rel.as_posix()
+        if rel_posix not in seen:
+            result.append(rel_posix)
+            seen.add(rel_posix)
+    return sorted(result)
+
+
+def filter_bundled_inventory(inventory: dict, scripts_dir: Path) -> dict:
+    """Remove extractor implementation files from a subprocess inventory."""
+    scripts_abs = scripts_dir.resolve().as_posix() + "/"
+    filtered: dict = {}
+    for fp, data in inventory.items():
+        fp_posix = fp.replace("\\", "/")
+        try:
+            resolved = Path(fp).resolve().as_posix()
+        except OSError:
+            resolved = fp_posix
+        if fp_posix.startswith(scripts_abs) or resolved.startswith(scripts_abs):
+            continue
+        filtered[fp_posix] = data
+    return filtered

llm_wiki_cli/extractors/go_extractor.py

@@ -0,0 +1,143 @@
+"""Go AST extractor for agent-wiki-cli.
+
+Implements :class:`~llm_wiki_cli.extractors.ExtractorProtocol` by delegating
+to a bundled Go script (``go_scripts/main.go``) that uses ``go/ast`` and
+``go/parser`` for Go AST traversal.
+
+Requirements
+------------
+* Go toolchain (``go``) on PATH.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from .common import discover_source_files, filter_bundled_inventory
+
+_GO_SCRIPTS_DIR = Path(__file__).parent / "go_scripts"
+
+
+class GoExtractor:
+    """Extractor for Go source files using a ``go run`` subprocess.
+
+    Implements :class:`~llm_wiki_cli.extractors.ExtractorProtocol`.
+
+    Each returned file entry includes ``"language": "go"``.
+    """
+
+    last_error: str | None = None
+
+    def extract(
+        self,
+        src_dir: str,
+        only_files: list[str] | None = None,
+        deep: bool = False,
+    ) -> dict:
+        """Scan *src_dir* for Go files and return an inventory dict.
+
+        Parameters
+        ----------
+        src_dir:
+            Root directory to scan.
+        only_files:
+            Optional list of paths (relative to *src_dir*) to restrict
+            extraction to.  When ``None``, all ``.go`` files found under
+            *src_dir* are scanned (excluding ``_test.go``, ``vendor/``, etc.).
+        deep:
+            When ``True``, include enriched data (doc comments, struct fields,
+            method details, imports).  When ``False``, return a slim format.
+
+        Returns
+        -------
+        dict
+            ``{filepath: file_entry}`` where each ``file_entry`` contains at
+            minimum ``"classes"``, ``"functions"``, and ``"language"``.
+        """
+        self.last_error = None
+        source_files = discover_source_files(
+            src_dir, (".go",), only_files=only_files, language="go",
+        )
+        if not source_files:
+            return {}
+
+        if not shutil.which("go"):
+            self.last_error = "go not found. Install Go (https://go.dev/dl/) to enable Go extraction."
+            print(f"llm-wiki Go extractor: {self.last_error}", file=sys.stderr)
+            return {}
+
+        cmd = [
+            "go", "run", ".",
+            "--src-dir", str(Path(src_dir).resolve()),
+        ]
+        cmd += ["--only-files", ",".join(source_files)]
+        if deep:
+            cmd.append("--deep")
+
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                check=True,
+                timeout=120,
+                cwd=str(_GO_SCRIPTS_DIR),
+            )
+        except subprocess.CalledProcessError as exc:
+            self.last_error = "extraction failed"
+            print(
+                f"llm-wiki Go extractor: extraction failed.\n{exc.stderr}",
+                file=sys.stderr,
+            )
+            return {}
+        except subprocess.TimeoutExpired:
+            self.last_error = "extraction timed out after 120 s"
+            print(
+                "llm-wiki Go extractor: extraction timed out after 120 s.",
+                file=sys.stderr,
+            )
+            return {}
+        except FileNotFoundError:
+            self.last_error = "go executable not found"
+            print(
+                "llm-wiki Go extractor: go executable not found.",
+                file=sys.stderr,
+            )
+            return {}
+
+        # Forward any warnings the Go script wrote to stderr.
+        if result.stderr.strip():
+            sys.stderr.write(result.stderr)
+
+        if not result.stdout.strip():
+            return {}
+
+        try:
+            inventory: dict = json.loads(result.stdout)
+        except json.JSONDecodeError as exc:
+            self.last_error = "malformed JSON output"
+            print(
+                f"llm-wiki Go extractor: malformed JSON output — {exc}",
+                file=sys.stderr,
+            )
+            return {}
+
+        for entry in inventory.values():
+            entry["language"] = "go"
+
+        inventory = filter_bundled_inventory(inventory, _GO_SCRIPTS_DIR)
+
+        src_root = Path(src_dir).resolve()
+        normalized_inventory: dict = {}
+        for fp, data in inventory.items():
+            try:
+                rel = Path(fp).resolve().relative_to(src_root).as_posix()
+            except ValueError:
+                rel = fp.replace("\\", "/")
+            normalized_inventory[rel] = data
+
+        return normalized_inventory

llm_wiki_cli/extractors/go_scripts/go.mod

@@ -0,0 +1,3 @@
+module llm-wiki-go-extractor
+
+go 1.21