velune-cli 0.9.0__py3-none-any.whl

velune/repository/scanner.py

@@ -0,0 +1,193 @@
+"""Gitignore-aware file scanner for workspace discovery."""
+
+import fnmatch
+from pathlib import Path
+
+DEFAULT_VELUNEIGNORE = """\
+# Velune index exclusions
+# Secrets and credentials
+.env
+.env.*
+*.pem
+*.key
+*.p12
+*.pfx
+*.crt
+*.jks
+*.keystore
+id_rsa
+id_dsa
+id_ed25519
+id_ecdsa
+.netrc
+.npmrc
+.pypirc
+.aws/
+credentials.json
+service-account.json
+gcp-credentials.json
+secrets/
+credentials/
+
+# Large generated files
+*.min.js
+*.min.css
+dist/
+build/
+__pycache__/
+*.pyc
+.mypy_cache/
+.ruff_cache/
+
+# Data and media
+*.sqlite
+*.db
+*.csv
+*.parquet
+data/
+datasets/
+*.jpg
+*.jpeg
+*.png
+*.gif
+*.mp4
+*.zip
+*.tar.gz
+
+# IDE
+.idea/
+.vscode/settings.json
+*.swp
+"""
+
+
+class FilesystemScanner:
+    """Discovers source files inside a workspace, strictly adhering to .gitignore rules."""
+
+    def __init__(self, root_path: Path) -> None:
+        self.root_path = root_path.resolve()
+        self.gitignore_patterns = self._load_gitignore() + self._load_veluneignore()
+
+    def _load_gitignore(self) -> list[str]:
+        """Loads and parses .gitignore rules along with core default exclusions."""
+        patterns = [
+            # Default exclusions
+            ".git",
+            ".github",
+            "__pycache__",
+            "*.pyc",
+            "*.pyo",
+            "*.pyd",
+            ".venv",
+            "venv",
+            "env",
+            "node_modules",
+            "dist",
+            "build",
+            ".velune",
+            "*.egg-info",
+            ".pytest_cache",
+            ".mypy_cache",
+            "CVS",
+            ".DS_Store",
+        ]
+
+        gitignore_path = self.root_path / ".gitignore"
+        if gitignore_path.exists():
+            try:
+                with open(gitignore_path, encoding="utf-8", errors="ignore") as f:
+                    for line in f:
+                        line = line.strip()
+                        if line and not line.startswith("#"):
+                            # Normalize trailing slash to match standard glob behavior
+                            if line.endswith("/"):
+                                line = line[:-1]
+                            patterns.append(line)
+            except Exception:
+                pass
+
+        return patterns
+
+    def _load_veluneignore(self) -> list[str]:
+        """Loads and parses .veluneignore rules from the workspace root."""
+        patterns: list[str] = []
+        veluneignore_path = self.root_path / ".veluneignore"
+        if not veluneignore_path.exists():
+            return patterns
+        try:
+            with open(veluneignore_path, encoding="utf-8", errors="ignore") as f:
+                for line in f:
+                    line = line.strip()
+                    if line and not line.startswith("#"):
+                        if line.endswith("/"):
+                            line = line[:-1]
+                        patterns.append(line)
+        except Exception:
+            pass
+        return patterns
+
+    def is_ignored(self, path: Path) -> bool:
+        """Determines if a path is excluded by .gitignore or default ignore rules."""
+        try:
+            rel_path = path.resolve().relative_to(self.root_path)
+        except ValueError:
+            # Not under root
+            return True
+
+        path_parts = rel_path.parts
+        path_str = str(rel_path).replace("\\", "/")
+
+        for pattern in self.gitignore_patterns:
+            # Check direct match or directory component match
+            if fnmatch.fnmatch(path_str, pattern) or fnmatch.fnmatch(path_str, f"*/{pattern}"):
+                return True
+            for part in path_parts:
+                if fnmatch.fnmatch(part, pattern):
+                    return True
+
+        return False
+
+    def scan(self, extensions: list[str] | None = None) -> list[Path]:
+        """Scans the repository recursively and lists all valid files."""
+        files: list[Path] = []
+        self._recursive_scan(self.root_path, extensions, files)
+        return files
+
+    def _recursive_scan(
+        self, current_dir: Path, extensions: list[str] | None, accumulator: list[Path]
+    ) -> None:
+        """Recurses through directory structure, skipping ignored directories entirely to optimize speed."""
+        try:
+            for item in current_dir.iterdir():
+                if self.is_ignored(item):
+                    continue
+
+                if item.is_dir():
+                    self._recursive_scan(item, extensions, accumulator)
+                elif item.is_file():
+                    if extensions is None or item.suffix.lower() in extensions:
+                        accumulator.append(item)
+        except PermissionError:
+            pass  # Fail silently for protected folders
+
+    def scan_code_files(self) -> list[Path]:
+        """Convenience method to scan for common source code extensions."""
+        code_extensions = [
+            ".py",
+            ".js",
+            ".ts",
+            ".jsx",
+            ".tsx",
+            ".go",
+            ".rs",
+            ".java",
+            ".c",
+            ".cpp",
+            ".h",
+            ".cs",
+            ".php",
+            ".rb",
+            ".swift",
+            ".kt",
+        ]
+        return self.scan(code_extensions)

velune/repository/schemas.py

@@ -0,0 +1,102 @@
+"""Strictly-typed schemas for repository cognition."""
+
+import hashlib
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+
+
+def build_qualified_name(file_path: str, name: str, parent: str | None = None) -> str:
+    """Builds a dotted qualified name for a symbol from its file path and parent scope."""
+    p = file_path.replace("\\", "/")
+
+    # Extract package path relative to 'velune/' if absolute
+    if "/velune/" in p:
+        p = p.split("/velune/", 1)[1]
+        p = "velune/" + p
+    elif p.startswith("c:") or p.startswith("C:") or ":" in p:
+        p = p.split(":", 1)[1].lstrip("/")
+
+    p = p.rsplit(".", 1)[0]
+    dotted = p.replace("/", ".").strip(".")
+
+    if parent:
+        return f"{dotted}.{parent}.{name}"
+    return f"{dotted}.{name}"
+
+
+def compute_symbol_id(file_path: str, qualified_name: str, kind: str) -> str:
+    """Computes a stable, deterministic, line-independent SHA256 identity for a symbol."""
+    p = file_path.replace("\\", "/")
+    if "/velune/" in p:
+        p = p.split("/velune/", 1)[1]
+        p = "velune/" + p
+    elif p.startswith("c:") or p.startswith("C:") or ":" in p:
+        p = p.split(":", 1)[1].lstrip("/")
+
+    payload = f"{p}:{qualified_name}:{kind.lower()}"
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+class RepositoryLanguage(StrEnum):
+    PYTHON = "python"
+    JAVASCRIPT = "javascript"
+    TYPESCRIPT = "typescript"
+    GO = "go"
+    RUST = "rust"
+    UNKNOWN = "unknown"
+
+
+class RepositorySymbolKind(StrEnum):
+    CLASS = "class"
+    FUNCTION = "function"
+    METHOD = "method"
+    IMPORT = "import"
+    UNKNOWN = "unknown"
+
+
+class RepositorySymbol(BaseModel):
+    name: str
+    kind: RepositorySymbolKind
+    file_path: str
+    line_start: int = 1
+    line_end: int = 1
+    docstring: str | None = None
+    parent: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    symbol_id: str | None = None
+    qualified_name: str | None = None
+
+    @model_validator(mode="after")
+    def populate_identity(self) -> "RepositorySymbol":
+        """Ensures stable symbol_id and qualified_name are automatically calculated if missing."""
+        if not self.qualified_name:
+            self.qualified_name = build_qualified_name(self.file_path, self.name, self.parent)
+        if not self.symbol_id:
+            self.symbol_id = compute_symbol_id(self.file_path, self.qualified_name, self.kind.value)
+        return self
+
+
+class RepositoryFile(BaseModel):
+    path: str
+    language: RepositoryLanguage
+    size_bytes: int
+    sha256: str
+    symbols: list[RepositorySymbol] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class RepositoryEdge(BaseModel):
+    source: str
+    target: str
+    edge_type: str  # e.g., "imports", "calls", "contains"
+    weight: float = 1.0
+
+
+class RepositorySnapshot(BaseModel):
+    root_path: str
+    files: list[RepositoryFile] = Field(default_factory=list)
+    symbols: list[RepositorySymbol] = Field(default_factory=list)
+    edges: list[RepositoryEdge] = Field(default_factory=list)
+    summary: dict[str, Any] = Field(default_factory=dict)

velune/repository/symbol_registry.py

@@ -0,0 +1,365 @@
+"""SQLite-backed symbol registry for tracking code symbols."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import aiosqlite
+
+from velune.repository.ast_parser import Symbol, SymbolKind
+
+logger = logging.getLogger("velune.repository.symbol_registry")
+
+
+class SymbolRegistry:
+    """Persistent symbol registry using SQLite."""
+
+    def __init__(self, db_path: Path) -> None:
+        """Initialize symbol registry.
+
+        Args:
+            db_path: Path to SQLite database file
+        """
+        self.db_path = db_path
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+
+    async def initialize(self) -> None:
+        """Initialize database schema."""
+        async with aiosqlite.connect(str(self.db_path)) as db:
+            await db.executescript("""
+                CREATE TABLE IF NOT EXISTS symbols (
+                    id TEXT PRIMARY KEY,
+                    name TEXT NOT NULL,
+                    kind TEXT NOT NULL,
+                    file_path TEXT NOT NULL,
+                    line_start INTEGER NOT NULL,
+                    line_end INTEGER NOT NULL,
+                    docstring TEXT,
+                    parameters TEXT,  -- JSON array
+                    return_type TEXT,
+                    is_exported BOOLEAN DEFAULT 0,
+                    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                    UNIQUE(file_path, name, line_start)
+                );
+
+                CREATE INDEX IF NOT EXISTS idx_symbols_file ON symbols(file_path);
+                CREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);
+                CREATE INDEX IF NOT EXISTS idx_symbols_kind ON symbols(kind);
+            """)
+            await db.commit()
+
+    async def upsert_symbols(self, file_path: str, symbols: list[Symbol]) -> None:
+        """Store or update symbols from a file.
+
+        Updates existing symbols by (file_path, name, line_start).
+        Preserves stable IDs when possible.
+
+        Args:
+            file_path: Relative path to file
+            symbols: List of symbols to store
+        """
+        import json
+
+        async with aiosqlite.connect(str(self.db_path)) as db:
+            db.row_factory = aiosqlite.Row
+            for symbol in symbols:
+                params = json.dumps(symbol.parameters) if symbol.parameters else None
+
+                # 1. Check if ID exists
+                async with db.execute("SELECT 1 FROM symbols WHERE id = ?", (symbol.id,)) as cursor:
+                    exists_by_id = await cursor.fetchone()
+
+                if exists_by_id:
+                    # Update by ID (rename or modification)
+                    await db.execute(
+                        """
+                        UPDATE symbols SET
+                            name = ?,
+                            kind = ?,
+                            file_path = ?,
+                            line_start = ?,
+                            line_end = ?,
+                            docstring = ?,
+                            parameters = ?,
+                            return_type = ?,
+                            is_exported = ?,
+                            updated_at = CURRENT_TIMESTAMP
+                        WHERE id = ?
+                        """,
+                        (
+                            symbol.name,
+                            symbol.kind.value,
+                            file_path,
+                            symbol.line_start,
+                            symbol.line_end,
+                            symbol.docstring,
+                            params,
+                            symbol.return_type,
+                            1 if symbol.is_exported else 0,
+                            symbol.id,
+                        ),
+                    )
+                else:
+                    # 2. Check if file_path, name, line_start exists
+                    async with db.execute(
+                        "SELECT id FROM symbols WHERE file_path = ? AND name = ? AND line_start = ?",
+                        (file_path, symbol.name, symbol.line_start),
+                    ) as cursor:
+                        existing_row = await cursor.fetchone()
+
+                    if existing_row:
+                        # Update by file_path/name/line_start, preserving existing ID
+                        existing_id = existing_row[0]
+                        await db.execute(
+                            """
+                            UPDATE symbols SET
+                                kind = ?,
+                                line_end = ?,
+                                docstring = ?,
+                                parameters = ?,
+                                return_type = ?,
+                                is_exported = ?,
+                                updated_at = CURRENT_TIMESTAMP
+                            WHERE id = ?
+                            """,
+                            (
+                                symbol.kind.value,
+                                symbol.line_end,
+                                symbol.docstring,
+                                params,
+                                symbol.return_type,
+                                1 if symbol.is_exported else 0,
+                                existing_id,
+                            ),
+                        )
+                    else:
+                        # 3. Insert new row
+                        await db.execute(
+                            """
+                            INSERT INTO symbols (
+                                id, name, kind, file_path, line_start, line_end,
+                                docstring, parameters, return_type, is_exported
+                            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                            """,
+                            (
+                                symbol.id,
+                                symbol.name,
+                                symbol.kind.value,
+                                file_path,
+                                symbol.line_start,
+                                symbol.line_end,
+                                symbol.docstring,
+                                params,
+                                symbol.return_type,
+                                1 if symbol.is_exported else 0,
+                            ),
+                        )
+
+            await db.commit()
+
+    async def get_symbols(self, file_path: str) -> list[Symbol]:
+        """Retrieve all symbols from a file.
+
+        Args:
+            file_path: Relative path to file
+
+        Returns:
+            List of symbols in the file
+        """
+        import json
+
+        symbols: list[Symbol] = []
+        async with aiosqlite.connect(str(self.db_path)) as db:
+            async with db.execute(
+                "SELECT id, name, kind, file_path, line_start, line_end, "
+                "docstring, parameters, return_type, is_exported FROM symbols "
+                "WHERE file_path = ? ORDER BY line_start",
+                (file_path,),
+            ) as cursor:
+                async for row in cursor:
+                    params = json.loads(row[7]) if row[7] else []
+                    symbol = Symbol(
+                        id=row[0],
+                        name=row[1],
+                        kind=SymbolKind(row[2]),
+                        file_path=row[3],
+                        line_start=row[4],
+                        line_end=row[5],
+                        docstring=row[6],
+                        parameters=params,
+                        return_type=row[8],
+                        is_exported=bool(row[9]),
+                    )
+                    symbols.append(symbol)
+
+        return symbols
+
+    async def search_symbols(self, name_pattern: str) -> list[Symbol]:
+        """Search for symbols by name pattern (LIKE search).
+
+        Args:
+            name_pattern: SQL LIKE pattern (e.g., 'validate%')
+
+        Returns:
+            List of matching symbols
+        """
+        import json
+
+        symbols: list[Symbol] = []
+        async with aiosqlite.connect(str(self.db_path)) as db:
+            async with db.execute(
+                "SELECT id, name, kind, file_path, line_start, line_end, "
+                "docstring, parameters, return_type, is_exported FROM symbols "
+                "WHERE name LIKE ? ORDER BY file_path, line_start",
+                (name_pattern,),
+            ) as cursor:
+                async for row in cursor:
+                    params = json.loads(row[7]) if row[7] else []
+                    symbol = Symbol(
+                        id=row[0],
+                        name=row[1],
+                        kind=SymbolKind(row[2]),
+                        file_path=row[3],
+                        line_start=row[4],
+                        line_end=row[5],
+                        docstring=row[6],
+                        parameters=params,
+                        return_type=row[8],
+                        is_exported=bool(row[9]),
+                    )
+                    symbols.append(symbol)
+
+        return symbols
+
+    async def get_symbol_by_id(self, symbol_id: str) -> Symbol | None:
+        """Retrieve a symbol by its stable ID.
+
+        Args:
+            symbol_id: Unique symbol ID
+
+        Returns:
+            Symbol if found, None otherwise
+        """
+        import json
+
+        async with aiosqlite.connect(str(self.db_path)) as db:
+            async with db.execute(
+                "SELECT id, name, kind, file_path, line_start, line_end, "
+                "docstring, parameters, return_type, is_exported FROM symbols "
+                "WHERE id = ?",
+                (symbol_id,),
+            ) as cursor:
+                row = await cursor.fetchone()
+
+        if not row:
+            return None
+
+        params = json.loads(row[7]) if row[7] else []
+        return Symbol(
+            id=row[0],
+            name=row[1],
+            kind=SymbolKind(row[2]),
+            file_path=row[3],
+            line_start=row[4],
+            line_end=row[5],
+            docstring=row[6],
+            parameters=params,
+            return_type=row[8],
+            is_exported=bool(row[9]),
+        )
+
+    async def remove_file_symbols(self, file_path: str) -> None:
+        """Remove all symbols from a file.
+
+        Called when a file is deleted or removed from tracking.
+
+        Args:
+            file_path: Relative path to file
+        """
+        async with aiosqlite.connect(str(self.db_path)) as db:
+            await db.execute("DELETE FROM symbols WHERE file_path = ?", (file_path,))
+            await db.commit()
+
+    async def get_all_symbols(self) -> list[Symbol]:
+        """Retrieve all symbols in registry.
+
+        Returns:
+            List of all symbols
+        """
+        import json
+
+        symbols: list[Symbol] = []
+        async with aiosqlite.connect(str(self.db_path)) as db:
+            async with db.execute(
+                "SELECT id, name, kind, file_path, line_start, line_end, "
+                "docstring, parameters, return_type, is_exported FROM symbols "
+                "ORDER BY file_path, line_start"
+            ) as cursor:
+                async for row in cursor:
+                    params = json.loads(row[7]) if row[7] else []
+                    symbol = Symbol(
+                        id=row[0],
+                        name=row[1],
+                        kind=SymbolKind(row[2]),
+                        file_path=row[3],
+                        line_start=row[4],
+                        line_end=row[5],
+                        docstring=row[6],
+                        parameters=params,
+                        return_type=row[8],
+                        is_exported=bool(row[9]),
+                    )
+                    symbols.append(symbol)
+
+        return symbols
+
+    async def get_symbols_by_kind(self, kind: SymbolKind) -> list[Symbol]:
+        """Retrieve all symbols of a specific kind.
+
+        Args:
+            kind: Symbol kind to filter by
+
+        Returns:
+            List of symbols of specified kind
+        """
+        import json
+
+        symbols: list[Symbol] = []
+        async with aiosqlite.connect(str(self.db_path)) as db:
+            async with db.execute(
+                "SELECT id, name, kind, file_path, line_start, line_end, "
+                "docstring, parameters, return_type, is_exported FROM symbols "
+                "WHERE kind = ? ORDER BY file_path, line_start",
+                (kind.value,),
+            ) as cursor:
+                async for row in cursor:
+                    params = json.loads(row[7]) if row[7] else []
+                    symbol = Symbol(
+                        id=row[0],
+                        name=row[1],
+                        kind=SymbolKind(row[2]),
+                        file_path=row[3],
+                        line_start=row[4],
+                        line_end=row[5],
+                        docstring=row[6],
+                        parameters=params,
+                        return_type=row[8],
+                        is_exported=bool(row[9]),
+                    )
+                    symbols.append(symbol)
+
+        return symbols
+
+    async def count_symbols(self) -> int:
+        """Count total symbols in registry.
+
+        Returns:
+            Total number of symbols
+        """
+        async with aiosqlite.connect(str(self.db_path)) as db:
+            async with db.execute("SELECT COUNT(*) FROM symbols") as cursor:
+                row = await cursor.fetchone()
+
+        return row[0] if row else 0