velune-cli 1.0.0__py3-none-any.whl

velune/repository/project_type.py

@@ -0,0 +1,293 @@
+"""Project type detector — classifies workspaces and builds context profiles."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+
+class ProjectType(Enum):
+    PYTHON_FASTAPI = "python-fastapi"
+    PYTHON_DJANGO  = "python-django"
+    PYTHON_FLASK   = "python-flask"
+    PYTHON_CLI     = "python-cli"
+    PYTHON_GENERIC = "python"
+    NODE_REACT     = "node-react"
+    NODE_NEXTJS    = "node-nextjs"
+    NODE_EXPRESS   = "node-express"
+    NODE_GENERIC   = "node"
+    RUST           = "rust"
+    GO             = "go"
+    JAVA_SPRING    = "java-spring"
+    JAVA_GENERIC   = "java"
+    DOTNET         = "dotnet"
+    FLUTTER        = "flutter"
+    UNKNOWN        = "unknown"
+
+
+@dataclass
+class ProjectProfile:
+    project_type: ProjectType
+    display_name: str
+    primary_language: str
+    detected_frameworks: list[str]
+    entry_points: list[str]
+    test_directories: list[str]
+    config_files: list[str]
+    suggested_model_skill: str    # "coding" | "reasoning" | "balanced"
+    context_hints: list[str]
+    system_prompt_addon: str
+
+
+PROJECT_SYSTEM_PROMPTS: dict[ProjectType, str] = {
+    ProjectType.PYTHON_FASTAPI: (
+        "This is a Python FastAPI project. When suggesting code changes, "
+        "prefer async/await patterns, Pydantic models for validation, "
+        "and dependency injection. Routes are in routers/. Models in models/."
+    ),
+    ProjectType.PYTHON_DJANGO: (
+        "This is a Django project. Follow Django conventions: fat models, "
+        "thin views, use Django ORM patterns, signals, and class-based views "
+        "where appropriate. Settings are in settings.py or settings/."
+    ),
+    ProjectType.PYTHON_FLASK: (
+        "This is a Flask project. Follow Flask patterns: blueprints for "
+        "routing, application factory pattern, SQLAlchemy for ORM if present."
+    ),
+    ProjectType.NODE_REACT: (
+        "This is a React frontend project. Prefer functional components "
+        "with hooks, TypeScript if tsconfig.json exists, and modern React "
+        "patterns. Components in src/components/."
+    ),
+    ProjectType.NODE_NEXTJS: (
+        "This is a Next.js project. Use App Router patterns if app/ exists, "
+        "Pages Router if pages/ exists. Server components by default, "
+        "client components only when needed."
+    ),
+    ProjectType.RUST: (
+        "This is a Rust project. Follow Rust idioms: ownership semantics, "
+        "Result/Option for error handling, no unwrap() in library code. "
+        "Check Cargo.toml for edition and features."
+    ),
+    ProjectType.GO: (
+        "This is a Go project. Follow Go conventions: simple interfaces, "
+        "error returns, goroutines and channels for concurrency. "
+        "Entry point is main.go or cmd/."
+    ),
+}
+
+_DISPLAY_NAMES: dict[ProjectType, str] = {
+    ProjectType.PYTHON_FASTAPI: "Python / FastAPI",
+    ProjectType.PYTHON_DJANGO:  "Python / Django",
+    ProjectType.PYTHON_FLASK:   "Python / Flask",
+    ProjectType.PYTHON_CLI:     "Python / CLI",
+    ProjectType.PYTHON_GENERIC: "Python",
+    ProjectType.NODE_REACT:     "Node.js / React",
+    ProjectType.NODE_NEXTJS:    "Node.js / Next.js",
+    ProjectType.NODE_EXPRESS:   "Node.js / Express",
+    ProjectType.NODE_GENERIC:   "Node.js",
+    ProjectType.RUST:           "Rust",
+    ProjectType.GO:             "Go",
+    ProjectType.JAVA_SPRING:    "Java / Spring",
+    ProjectType.JAVA_GENERIC:   "Java",
+    ProjectType.DOTNET:         ".NET",
+    ProjectType.FLUTTER:        "Flutter / Dart",
+    ProjectType.UNKNOWN:        "Unknown",
+}
+
+_LANGUAGE_MAP: dict[ProjectType, str] = {
+    ProjectType.PYTHON_FASTAPI: "python",
+    ProjectType.PYTHON_DJANGO:  "python",
+    ProjectType.PYTHON_FLASK:   "python",
+    ProjectType.PYTHON_CLI:     "python",
+    ProjectType.PYTHON_GENERIC: "python",
+    ProjectType.NODE_REACT:     "typescript",
+    ProjectType.NODE_NEXTJS:    "typescript",
+    ProjectType.NODE_EXPRESS:   "javascript",
+    ProjectType.NODE_GENERIC:   "javascript",
+    ProjectType.RUST:           "rust",
+    ProjectType.GO:             "go",
+    ProjectType.JAVA_SPRING:    "java",
+    ProjectType.JAVA_GENERIC:   "java",
+    ProjectType.DOTNET:         "csharp",
+    ProjectType.FLUTTER:        "dart",
+    ProjectType.UNKNOWN:        "unknown",
+}
+
+
+class ProjectTypeDetector:
+    """Detects the project type of a workspace by inspecting root-level files."""
+
+    def detect(self, workspace: Path) -> ProjectProfile:
+        files = self._list_root_files(workspace)
+        project_type, frameworks = self._classify(workspace, files)
+        entry_points = self._find_entry_points(workspace, project_type)
+        test_dirs = self._find_test_dirs(workspace)
+        config_files = self._find_config_files(workspace, files)
+        context_hints = self._build_context_hints(project_type)
+        system_prompt = PROJECT_SYSTEM_PROMPTS.get(project_type, "")
+
+        return ProjectProfile(
+            project_type=project_type,
+            display_name=_DISPLAY_NAMES.get(project_type, "Unknown"),
+            primary_language=_LANGUAGE_MAP.get(project_type, "unknown"),
+            detected_frameworks=frameworks,
+            entry_points=entry_points,
+            test_directories=test_dirs,
+            config_files=config_files,
+            suggested_model_skill="coding",
+            context_hints=context_hints,
+            system_prompt_addon=system_prompt,
+        )
+
+    def _list_root_files(self, workspace: Path) -> set[str]:
+        try:
+            return {f.name for f in workspace.iterdir() if not f.name.startswith(".")}
+        except Exception:
+            return set()
+
+    def _classify(
+        self, workspace: Path, files: set[str]
+    ) -> tuple[ProjectType, list[str]]:
+        # ── Rust ──────────────────────────────────────────────────────
+        if "Cargo.toml" in files:
+            return ProjectType.RUST, ["cargo"]
+
+        # ── Go ────────────────────────────────────────────────────────
+        if "go.mod" in files:
+            return ProjectType.GO, ["go modules"]
+
+        # ── Flutter / Dart ────────────────────────────────────────────
+        if "pubspec.yaml" in files:
+            return ProjectType.FLUTTER, ["flutter", "dart"]
+
+        # ── .NET ──────────────────────────────────────────────────────
+        if any(f.endswith(".csproj") or f.endswith(".sln") for f in files):
+            return ProjectType.DOTNET, ["dotnet"]
+
+        # ── Node / JavaScript / TypeScript ────────────────────────────
+        if "package.json" in files:
+            try:
+                import json
+                pkg = json.loads((workspace / "package.json").read_text())
+                deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
+                if "next" in deps:
+                    return ProjectType.NODE_NEXTJS, ["nextjs", "react"]
+                if "react" in deps or "react-dom" in deps:
+                    frameworks = ["react"]
+                    if "typescript" in deps or (workspace / "tsconfig.json").exists():
+                        frameworks.append("typescript")
+                    return ProjectType.NODE_REACT, frameworks
+                if "express" in deps:
+                    return ProjectType.NODE_EXPRESS, ["express"]
+            except Exception:
+                pass
+            return ProjectType.NODE_GENERIC, []
+
+        # ── Python ────────────────────────────────────────────────────
+        has_python = (
+            "pyproject.toml" in files
+            or "setup.py" in files
+            or "requirements.txt" in files
+            or any(f.endswith(".py") for f in files)
+        )
+        if has_python:
+            combined = self._read_requirement_sources(workspace)
+            if "fastapi" in combined:
+                frameworks = ["fastapi", "uvicorn"]
+                if "sqlalchemy" in combined:
+                    frameworks.append("sqlalchemy")
+                if "pydantic" in combined:
+                    frameworks.append("pydantic")
+                return ProjectType.PYTHON_FASTAPI, frameworks
+            if "django" in combined:
+                frameworks: list[str] = ["django"]
+                if "drf" in combined or "rest_framework" in combined:
+                    frameworks.append("drf")
+                return ProjectType.PYTHON_DJANGO, frameworks
+            if "flask" in combined:
+                return ProjectType.PYTHON_FLASK, ["flask"]
+            if "typer" in combined or "click" in combined or "argparse" in combined:
+                return ProjectType.PYTHON_CLI, ["cli"]
+            return ProjectType.PYTHON_GENERIC, []
+
+        # ── Java ──────────────────────────────────────────────────────
+        if "pom.xml" in files or "build.gradle" in files:
+            combined = ""
+            for fname in ("pom.xml", "build.gradle"):
+                fp = workspace / fname
+                if fp.exists():
+                    try:
+                        combined += fp.read_text().lower()
+                    except Exception:
+                        pass
+            if "spring" in combined:
+                return ProjectType.JAVA_SPRING, ["spring"]
+            return ProjectType.JAVA_GENERIC, []
+
+        return ProjectType.UNKNOWN, []
+
+    def _read_requirement_sources(self, workspace: Path) -> str:
+        parts: list[str] = []
+        for fname in ("requirements.txt", "requirements.in", "pyproject.toml", "setup.py"):
+            fp = workspace / fname
+            if fp.exists():
+                try:
+                    parts.append(fp.read_text().lower())
+                except Exception:
+                    pass
+        return " ".join(parts)
+
+    def _find_entry_points(self, workspace: Path, pt: ProjectType) -> list[str]:
+        candidates: dict[ProjectType, list[str]] = {
+            ProjectType.PYTHON_FASTAPI: ["main.py", "app/main.py", "src/main.py"],
+            ProjectType.PYTHON_DJANGO:  ["manage.py"],
+            ProjectType.PYTHON_FLASK:   ["app.py", "run.py", "main.py"],
+            ProjectType.PYTHON_CLI:     ["main.py", "cli.py", "__main__.py"],
+            ProjectType.PYTHON_GENERIC: ["main.py", "__main__.py"],
+            ProjectType.NODE_REACT:     ["src/main.tsx", "src/App.tsx", "src/index.tsx"],
+            ProjectType.NODE_NEXTJS:    ["app/page.tsx", "pages/index.tsx"],
+            ProjectType.NODE_EXPRESS:   ["index.js", "server.js", "app.js"],
+            ProjectType.RUST:           ["src/main.rs", "src/lib.rs"],
+            ProjectType.GO:             ["main.go", "cmd/main.go"],
+        }
+        found = []
+        for rel in candidates.get(pt, []):
+            if (workspace / rel).exists():
+                found.append(rel)
+        return found[:3]
+
+    def _find_test_dirs(self, workspace: Path) -> list[str]:
+        names = ["tests", "test", "__tests__", "spec", "specs", "e2e"]
+        return [d for d in names if (workspace / d).is_dir()]
+
+    def _find_config_files(self, workspace: Path, files: set[str]) -> list[str]:
+        candidates = [
+            "pyproject.toml", "package.json", "Cargo.toml", "go.mod",
+            "tsconfig.json", ".eslintrc.json", "webpack.config.js",
+            "vite.config.ts", "next.config.js", "docker-compose.yml",
+            "Dockerfile", ".env.example",
+        ]
+        return [f for f in candidates if f in files]
+
+    def _build_context_hints(self, pt: ProjectType) -> list[str]:
+        hints: list[str] = []
+        if pt in (
+            ProjectType.PYTHON_FASTAPI,
+            ProjectType.PYTHON_DJANGO,
+            ProjectType.PYTHON_FLASK,
+            ProjectType.PYTHON_GENERIC,
+        ):
+            hints.append("Always check imports and type hints in Python files")
+            hints.append("Prefer pathlib over os.path for file operations")
+        if pt == ProjectType.NODE_REACT:
+            hints.append("Check for TypeScript types in *.d.ts files")
+            hints.append("Components use named exports, not default where possible")
+        if pt == ProjectType.RUST:
+            hints.append("Check Cargo.toml features before suggesting dependencies")
+            hints.append("Use ? operator for error propagation")
+        if pt == ProjectType.GO:
+            hints.append("Follow Go error handling: always check returned errors")
+            hints.append("Check go.sum when suggesting new imports")
+        return hints

velune/repository/scanner.py

@@ -0,0 +1,177 @@
+"""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)