sampler-cli 0.2.0__py3-none-any.whl

sampler/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.2.0"

sampler/__main__.py

@@ -0,0 +1,5 @@
+from sampler.cli.main import app
+
+
+if __name__ == "__main__":
+    app()

sampler/cli/main.py

@@ -0,0 +1,187 @@
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from sampler import __version__
+from sampler.config import ConfigManager
+from sampler.db import Database
+from sampler.indexer.builder import IndexBuilder
+from sampler.query.engine import QueryEngine
+
+app = typer.Typer(help="Sampler CLI")
+project_app = typer.Typer(help="Project management commands")
+app.add_typer(project_app, name="project")
+console = Console()
+
+
+def _database() -> Database:
+    cfg = ConfigManager().load()
+    db_path = Path(cfg.cache_dir).expanduser() / "graph.db"
+    db = Database(db_path=db_path)
+    db.init_schema()
+    return db
+
+
+def _get_project_roots() -> dict[str, Path]:
+    """Map project name -> absolute root path for relative path computation."""
+    config = ConfigManager()
+    roots: dict[str, Path] = {}
+    for p in config.list_projects():
+        try:
+            roots[p.name] = Path(p.path).expanduser().resolve()
+        except Exception:
+            pass
+    return roots
+
+
+def _short_path(project_name: str, full_path: str, roots: dict[str, Path]) -> str:
+    """Return shortest useful path for display: relative to project root if possible, else tail or name."""
+    root = roots.get(project_name)
+    if root:
+        try:
+            return str(Path(full_path).resolve().relative_to(root))
+        except Exception:
+            pass
+    # Fallback: last 1-2 path segments to keep output short (token friendly)
+    p = Path(full_path)
+    if len(p.parts) >= 3:
+        return "/".join(p.parts[-2:])
+    return p.name
+
+
+@app.command("version")
+def version() -> None:
+    """Show installed sampler version."""
+    console.print(f"sampler {__version__}")
+
+
+@app.command("init")
+def init() -> None:
+    """Initialize sampler local data directory."""
+    config = ConfigManager()
+    config.load()
+    data_dir = Path.home() / ".sampler"
+    console.print(f"Initialized [bold]{data_dir}[/bold]")
+
+
+@project_app.command("list")
+def project_list() -> None:
+    """List registered projects."""
+    config = ConfigManager()
+    projects = config.list_projects()
+    home = str(Path.home().resolve())
+
+    for project in projects:
+        try:
+            pp = Path(project.path).resolve()
+            ps = str(pp)
+            if ps.startswith(home):
+                disp = "~" + ps[len(home):]
+            else:
+                parts = pp.parts
+                disp = "/".join(parts[-2:]) if len(parts) > 2 else ps
+        except Exception:
+            disp = project.path
+        console.print(f"{project.name} {disp}")
+
+
+@project_app.command("add")
+def project_add(name: str, path: str, language: str = "python") -> None:
+    """Register project in global config."""
+    config = ConfigManager()
+    try:
+        project = config.add_project(name=name, path=path, language=language)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    console.print(f"Added project [bold]{project.name}[/bold]")
+
+
+@project_app.command("remove")
+def project_remove(name: str) -> None:
+    """Remove project from global config."""
+    config = ConfigManager()
+    try:
+        config.remove_project(name)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    console.print(f"Removed project [bold]{name}[/bold]")
+
+
+@app.command("search")
+def search(
+    query: str,
+    project: str | None = typer.Option(None, "--project", "-p"),
+    type: str | None = typer.Option(None, "--type", "-t", help="filter e.g. function,class"),
+    limit: int = typer.Option(100, "--limit", "-l"),
+) -> None:
+    """Search symbols by name."""
+    engine = QueryEngine(db=_database())
+    types = [x.strip() for x in type.split(",")] if type else None
+    if types:
+        exp = set(types)
+        for t in list(types):
+            if t == "function": exp.add("async function")
+            elif t == "method": exp.add("async method")
+        types = list(exp)
+    rows = engine.search(query=query, project_name=project, types=types, limit=limit)
+    roots = _get_project_roots()
+
+    for r in rows:
+        shortf = _short_path(r["project_name"], r["file_path"], roots)
+        name = r["qualified_name"] or r["name"]
+        sig = r.get("signature") or ""
+        line = f"{r['project_name']}:{shortf}:{r['start_line'] or '-'} {r['type']} {name}"
+        if sig:
+            line += f"  {sig}"
+        console.print(line)
+
+
+@app.command("search-all")
+def search_all(
+    query: str,
+    type: str | None = typer.Option(None, "--type", "-t", help="filter e.g. function,class"),
+    limit: int = typer.Option(100, "--limit", "-l"),
+) -> None:
+    """Search symbols across ALL projects."""
+    search(query=query, project=None, type=type, limit=limit)
+
+
+@app.command("index")
+def index(project: str) -> None:
+    """Index selected project."""
+    config = ConfigManager()
+    project_cfg = config.get_project(project)
+    if project_cfg is None:
+        raise typer.BadParameter(f"Project '{project}' not found. Use 'sampler project list'.")
+
+    builder = IndexBuilder(db=_database())
+    stats = builder.index_project(
+        project_name=project_cfg.name,
+        project_path=project_cfg.path,
+        language=project_cfg.language,
+    )
+    console.print(
+        "Indexed project "
+        f"[bold]{stats['project']}[/bold]: discovered={stats['discovered']} indexed={stats['indexed']} "
+        f"skipped={stats['skipped']} failed={stats['failed']}"
+    )
+
+
+@app.command("overview")
+def overview(filepath: str) -> None:
+    """Show symbols for file."""
+    engine = QueryEngine(db=_database())
+    rows = engine.overview(filepath=filepath)
+
+    for r in rows:
+        name = r["qualified_name"] or r["name"]
+        sig = r.get("signature") or ""
+        line = f"{r['start_line'] or '-'}: {r['type']} {name}"
+        if sig:
+            line += f"  {sig}"
+        console.print(line)
+
+
+if __name__ == "__main__":
+    app()

sampler/config.py

@@ -0,0 +1,77 @@
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, Field
+
+
+def default_data_dir() -> Path:
+    return Path.home() / ".sampler"
+
+
+class ProjectConfig(BaseModel):
+    name: str
+    path: str
+    language: str
+    enabled: bool = True
+
+
+class GlobalConfig(BaseModel):
+    version: int = 1
+    cache_dir: str = str(default_data_dir())
+    projects: dict[str, ProjectConfig] = Field(default_factory=dict)
+
+
+class ConfigManager:
+    def __init__(self, config_path: Path | None = None) -> None:
+        self.config_path = config_path or (default_data_dir() / "config.yaml")
+
+    def load(self) -> GlobalConfig:
+        if not self.config_path.exists():
+            config = GlobalConfig()
+            self.save(config)
+            return config
+
+        with self.config_path.open("r", encoding="utf-8") as f:
+            raw = yaml.safe_load(f) or {}
+        config = GlobalConfig.model_validate(raw)
+
+        if config.version != 1:
+            config.version = 1
+            self.save(config)
+
+        return config
+
+    def save(self, config: GlobalConfig) -> None:
+        self.config_path.parent.mkdir(parents=True, exist_ok=True)
+        payload = config.model_dump(mode="python")
+        with self.config_path.open("w", encoding="utf-8") as f:
+            yaml.safe_dump(payload, f, sort_keys=False)
+
+    def add_project(self, name: str, path: str, language: str, enabled: bool = True) -> ProjectConfig:
+        config = self.load()
+        if name in config.projects:
+            raise ValueError(f"Project '{name}' already exists")
+
+        project_path = str(Path(path).expanduser().resolve())
+        if not Path(project_path).exists():
+            raise ValueError(f"Project path does not exist: {project_path}")
+
+        project = ProjectConfig(name=name, path=project_path, language=language, enabled=enabled)
+        config.projects[name] = project
+        self.save(config)
+        return project
+
+    def remove_project(self, name: str) -> None:
+        config = self.load()
+        if name not in config.projects:
+            raise ValueError(f"Project '{name}' does not exist")
+        del config.projects[name]
+        self.save(config)
+
+    def get_project(self, name: str) -> ProjectConfig | None:
+        config = self.load()
+        return config.projects.get(name)
+
+    def list_projects(self) -> list[ProjectConfig]:
+        config = self.load()
+        return list(config.projects.values())

sampler/db.py

@@ -0,0 +1,316 @@
+import sqlite3
+import json
+from pathlib import Path
+
+
+class Database:
+    def __init__(self, db_path: Path) -> None:
+        self.db_path = db_path
+
+    def connect(self) -> sqlite3.Connection:
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def init_schema(self) -> None:
+        with self.connect() as conn:
+            conn.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS projects (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    name TEXT UNIQUE NOT NULL,
+                    path TEXT NOT NULL,
+                    language TEXT,
+                    indexed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                    file_count INTEGER DEFAULT 0
+                );
+
+                CREATE TABLE IF NOT EXISTS files (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    project_id INTEGER REFERENCES projects(id),
+                    path TEXT NOT NULL,
+                    language TEXT,
+                    hash TEXT,
+                    last_indexed TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                    UNIQUE(project_id, path)
+                );
+
+                CREATE TABLE IF NOT EXISTS symbols (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    file_id INTEGER REFERENCES files(id),
+                    type TEXT NOT NULL,
+                    name TEXT NOT NULL,
+                    qualified_name TEXT,
+                    signature TEXT,
+                    docstring TEXT,
+                    start_line INTEGER,
+                    end_line INTEGER,
+                    metadata JSON
+                );
+
+                CREATE TABLE IF NOT EXISTS relationships (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    source_id INTEGER REFERENCES symbols(id),
+                    target_id INTEGER REFERENCES symbols(id),
+                    type TEXT NOT NULL,
+                    line INTEGER,
+                    metadata JSON
+                );
+
+                CREATE TABLE IF NOT EXISTS project_dependencies (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    source_project_id INTEGER REFERENCES projects(id),
+                    target_project_id INTEGER REFERENCES projects(id),
+                    type TEXT NOT NULL,
+                    metadata JSON,
+                    UNIQUE(source_project_id, target_project_id, type)
+                );
+
+                CREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);
+                CREATE INDEX IF NOT EXISTS idx_symbols_qualified ON symbols(qualified_name);
+                CREATE INDEX IF NOT EXISTS idx_relations_source ON relationships(source_id);
+                CREATE INDEX IF NOT EXISTS idx_relations_target ON relationships(target_id);
+                CREATE INDEX IF NOT EXISTS idx_files_project ON files(project_id);
+                """
+            )
+            conn.commit()
+
+    def add_project(self, name: str, path: str, language: str) -> int:
+        with self.connect() as conn:
+            cur = conn.execute(
+                """
+                INSERT INTO projects(name, path, language)
+                VALUES (?, ?, ?)
+                ON CONFLICT(name) DO UPDATE SET
+                    path=excluded.path,
+                    language=excluded.language,
+                    indexed_at=CURRENT_TIMESTAMP
+                """,
+                (name, path, language),
+            )
+            conn.commit()
+
+            if cur.lastrowid:
+                return int(cur.lastrowid)
+
+            row = conn.execute("SELECT id FROM projects WHERE name = ?", (name,)).fetchone()
+            if row is None:
+                raise RuntimeError("Failed to upsert project")
+            return int(row["id"])
+
+    def list_projects(self) -> list[sqlite3.Row]:
+        with self.connect() as conn:
+            rows = conn.execute(
+                """
+                SELECT id, name, path, language, indexed_at, file_count
+                FROM projects
+                ORDER BY name
+                """
+            ).fetchall()
+            return rows
+
+    def get_project(self, name: str) -> sqlite3.Row | None:
+        with self.connect() as conn:
+            return conn.execute(
+                "SELECT id, name, path, language, indexed_at, file_count FROM projects WHERE name = ?",
+                (name,),
+            ).fetchone()
+
+    def remove_project(self, name: str) -> None:
+        with self.connect() as conn:
+            row = conn.execute("SELECT id FROM projects WHERE name = ?", (name,)).fetchone()
+            if row is None:
+                return
+            project_id = int(row["id"])
+            conn.execute(
+                "DELETE FROM relationships WHERE source_id IN (SELECT id FROM symbols WHERE file_id IN (SELECT id FROM files WHERE project_id = ?))",
+                (project_id,),
+            )
+            conn.execute(
+                "DELETE FROM relationships WHERE target_id IN (SELECT id FROM symbols WHERE file_id IN (SELECT id FROM files WHERE project_id = ?))",
+                (project_id,),
+            )
+            conn.execute(
+                "DELETE FROM symbols WHERE file_id IN (SELECT id FROM files WHERE project_id = ?)",
+                (project_id,),
+            )
+            conn.execute("DELETE FROM files WHERE project_id = ?", (project_id,))
+            conn.execute("DELETE FROM project_dependencies WHERE source_project_id = ? OR target_project_id = ?", (project_id, project_id))
+            conn.execute("DELETE FROM projects WHERE id = ?", (project_id,))
+            conn.commit()
+
+    def get_file(self, project_id: int, path: str) -> sqlite3.Row | None:
+        with self.connect() as conn:
+            return conn.execute(
+                "SELECT id, project_id, path, language, hash, last_indexed FROM files WHERE project_id = ? AND path = ?",
+                (project_id, path),
+            ).fetchone()
+
+    def upsert_file(self, project_id: int, path: str, language: str, file_hash: str) -> int:
+        with self.connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO files(project_id, path, language, hash)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT(project_id, path) DO UPDATE SET
+                    language=excluded.language,
+                    hash=excluded.hash,
+                    last_indexed=CURRENT_TIMESTAMP
+                """,
+                (project_id, path, language, file_hash),
+            )
+            row = conn.execute(
+                "SELECT id FROM files WHERE project_id = ? AND path = ?",
+                (project_id, path),
+            ).fetchone()
+            conn.commit()
+            if row is None:
+                raise RuntimeError("Failed to upsert file")
+            return int(row["id"])
+
+    def clear_file_data(self, file_id: int) -> None:
+        with self.connect() as conn:
+            conn.execute(
+                "DELETE FROM relationships WHERE source_id IN (SELECT id FROM symbols WHERE file_id = ?)",
+                (file_id,),
+            )
+            conn.execute(
+                "DELETE FROM relationships WHERE target_id IN (SELECT id FROM symbols WHERE file_id = ?)",
+                (file_id,),
+            )
+            conn.execute("DELETE FROM symbols WHERE file_id = ?", (file_id,))
+            conn.commit()
+
+    def insert_symbol(self, file_id: int, symbol: dict) -> int:
+        with self.connect() as conn:
+            metadata = symbol.get("metadata")
+            row = conn.execute(
+                """
+                INSERT INTO symbols(
+                    file_id, type, name, qualified_name, signature,
+                    docstring, start_line, end_line, metadata
+                )
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    file_id,
+                    symbol.get("type"),
+                    symbol.get("name"),
+                    symbol.get("qualified_name"),
+                    symbol.get("signature"),
+                    symbol.get("docstring"),
+                    symbol.get("start_line"),
+                    symbol.get("end_line"),
+                    json.dumps(metadata) if metadata is not None else None,
+                ),
+            )
+            conn.commit()
+            return int(row.lastrowid)
+
+    def find_symbol_id_in_project(self, project_id: int, symbol_name: str) -> int | None:
+        with self.connect() as conn:
+            row = conn.execute(
+                """
+                SELECT s.id
+                FROM symbols s
+                JOIN files f ON s.file_id = f.id
+                WHERE f.project_id = ?
+                  AND (s.qualified_name = ? OR s.name = ?)
+                ORDER BY s.id ASC
+                LIMIT 1
+                """,
+                (project_id, symbol_name, symbol_name),
+            ).fetchone()
+            return None if row is None else int(row["id"])
+
+    def insert_relationship(self, source_id: int, target_id: int, relation: dict) -> None:
+        with self.connect() as conn:
+            metadata = relation.get("metadata")
+            conn.execute(
+                """
+                INSERT INTO relationships(source_id, target_id, type, line, metadata)
+                VALUES (?, ?, ?, ?, ?)
+                """,
+                (
+                    source_id,
+                    target_id,
+                    relation.get("type"),
+                    relation.get("line"),
+                    json.dumps(metadata) if metadata is not None else None,
+                ),
+            )
+            conn.commit()
+
+    def update_project_file_count(self, project_id: int) -> None:
+        with self.connect() as conn:
+            conn.execute(
+                """
+                UPDATE projects
+                SET file_count = (SELECT COUNT(*) FROM files WHERE project_id = ?),
+                    indexed_at = CURRENT_TIMESTAMP
+                WHERE id = ?
+                """,
+                (project_id, project_id),
+            )
+            conn.commit()
+
+    def search_symbols(self, query: str, project_name: str | None = None, types: list[str] | None = None, limit: int | None = None, offset: int = 0) -> list[sqlite3.Row]:
+        where = "WHERE (lower(s.name) LIKE lower(?) OR lower(COALESCE(s.qualified_name, '')) LIKE lower(?))"
+        params: list = [f"%{query}%", f"%{query}%"]
+        if project_name:
+            where += " AND p.name = ?"
+            params.append(project_name)
+        if types:
+            ph = ",".join("?" * len(types))
+            where += f" AND s.type IN ({ph})"
+            params.extend(types)
+
+        sql = f"""
+                SELECT
+                    s.type,
+                    s.name,
+                    s.qualified_name,
+                    s.signature,
+                    s.start_line,
+                    f.path AS file_path,
+                    p.name AS project_name
+                FROM symbols s
+                JOIN files f ON s.file_id = f.id
+                JOIN projects p ON f.project_id = p.id
+                {where}
+                ORDER BY p.name, f.path, s.start_line
+                """
+        if limit is not None:
+            sql += " LIMIT ? OFFSET ?"
+            params.extend([limit, offset])
+
+        with self.connect() as conn:
+            return conn.execute(sql, params).fetchall()
+
+    def get_symbols_by_filepath(self, filepath: str, project_name: str | None = None) -> list[sqlite3.Row]:
+        where = "WHERE f.path = ?"
+        params: list[str] = [filepath]
+        if project_name:
+            where += " AND p.name = ?"
+            params.append(project_name)
+
+        with self.connect() as conn:
+            return conn.execute(
+                f"""
+                SELECT
+                    s.type,
+                    s.name,
+                    s.qualified_name,
+                    s.signature,
+                    s.start_line,
+                    f.path AS file_path,
+                    p.name AS project_name
+                FROM symbols s
+                JOIN files f ON s.file_id = f.id
+                JOIN projects p ON f.project_id = p.id
+                {where}
+                ORDER BY s.start_line
+                """,
+                params,
+            ).fetchall()

sampler/indexer/builder.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from sampler.db import Database
+from sampler.indexer.discover import discover_files
+from sampler.indexer.parsers.go import GoParser
+from sampler.indexer.parsers.python import PythonParser
+from sampler.indexer.parsers.typescript import TypeScriptParser
+from sampler.indexer.store import SymbolStore
+
+
+class IndexBuilder:
+    def __init__(self, db: Database) -> None:
+        self.db = db
+        self.store = SymbolStore(db)
+        self.parsers = {
+            "python": PythonParser(),
+            "go": GoParser(),
+            "typescript": TypeScriptParser(),
+            "javascript": TypeScriptParser(),
+        }
+
+    def index_project(self, project_name: str, project_path: str, language: str, force: bool = False) -> dict:
+        parser = self.parsers.get(language)
+        if parser is None:
+            raise ValueError(f"Unsupported language: {language}")
+
+        project_abs_path = str(Path(project_path).expanduser().resolve())
+        project_id = self.db.add_project(name=project_name, path=project_abs_path, language=language)
+
+        files = discover_files(project_path=project_abs_path, language=language)
+        indexed = 0
+        skipped = 0
+        failed = 0
+
+        for filepath in files:
+            try:
+                content = Path(filepath).read_text(encoding="utf-8")
+            except UnicodeDecodeError:
+                failed += 1
+                continue
+
+            file_hash = hashlib.sha256(content.encode("utf-8")).hexdigest()
+            previous = self.db.get_file(project_id=project_id, path=filepath)
+            if not force and previous is not None and previous["hash"] == file_hash:
+                skipped += 1
+                continue
+
+            symbols, relationships = parser.parse(content=content, filepath=filepath)
+            self.store.save_symbols(
+                project_id=project_id,
+                filepath=filepath,
+                language=language,
+                file_hash=file_hash,
+                symbols=symbols,
+                relationships=relationships,
+            )
+            indexed += 1
+
+        self.db.update_project_file_count(project_id)
+        return {
+            "project": project_name,
+            "language": language,
+            "discovered": len(files),
+            "indexed": indexed,
+            "skipped": skipped,
+            "failed": failed,
+        }

sampler/indexer/discover.py

@@ -0,0 +1,53 @@
+from pathlib import Path
+
+from gitignore_parser import parse_gitignore
+
+
+LANGUAGE_EXTENSIONS: dict[str, set[str]] = {
+    "python": {".py"},
+    "go": {".go"},
+    "typescript": {".ts", ".tsx", ".js", ".jsx"},
+    "javascript": {".js", ".jsx", ".mjs", ".cjs"},
+}
+
+DEFAULT_IGNORE_PARTS = {
+    ".git",
+    "node_modules",
+    "venv",
+    ".venv",
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    "dist",
+    "build",
+}
+
+
+def discover_files(project_path: str, language: str, ignore_patterns: list[str] | None = None) -> list[str]:
+    root = Path(project_path)
+    if not root.exists() or not root.is_dir():
+        return []
+
+    exts = LANGUAGE_EXTENSIONS.get(language.lower())
+    if exts is None:
+        return []
+
+    gitignore = root / ".gitignore"
+    gitignore_matcher = parse_gitignore(gitignore) if gitignore.exists() else None
+
+    discovered: list[str] = []
+    for file_path in root.rglob("*"):
+        if not file_path.is_file():
+            continue
+        if file_path.suffix.lower() not in exts:
+            continue
+        if any(part in DEFAULT_IGNORE_PARTS for part in file_path.parts):
+            continue
+        if ignore_patterns and any(pattern in str(file_path) for pattern in ignore_patterns):
+            continue
+        if gitignore_matcher and gitignore_matcher(str(file_path)):
+            continue
+        discovered.append(str(file_path.resolve()))
+
+    return sorted(discovered)

sampler/indexer/parsers/base.py

@@ -0,0 +1,9 @@
+from abc import ABC, abstractmethod
+
+
+class BaseParser(ABC):
+    language: str
+
+    @abstractmethod
+    def parse(self, content: str, filepath: str) -> tuple[list[dict], list[dict]]:
+        raise NotImplementedError

sampler/indexer/parsers/go.py

@@ -0,0 +1,9 @@
+from sampler.indexer.parsers.base import BaseParser
+
+
+class GoParser(BaseParser):
+    language = "go"
+
+    def parse(self, content: str, filepath: str) -> tuple[list[dict], list[dict]]:
+        _ = content, filepath
+        return [], []

sampler/indexer/parsers/python.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import ast
+
+from sampler.indexer.parsers.base import BaseParser
+
+
+class PythonParser(BaseParser):
+    language = "python"
+
+    def parse(self, content: str, filepath: str) -> tuple[list[dict], list[dict]]:
+        symbols: list[dict] = []
+        relationships: list[dict] = []
+
+        try:
+            module = ast.parse(content)
+        except SyntaxError:
+            # Syntax error: no symbols extracted for this file (indexing continues).
+            return symbols, relationships
+
+        for stmt in module.body:
+            if isinstance(stmt, ast.Assign):
+                for target in stmt.targets:
+                    if isinstance(target, ast.Name):
+                        symbols.append(
+                            {
+                                "type": "variable",
+                                "name": target.id,
+                                "qualified_name": target.id,
+                                "signature": None,
+                                "docstring": None,
+                                "start_line": getattr(stmt, "lineno", 1),
+                                "end_line": getattr(stmt, "end_lineno", getattr(stmt, "lineno", 1)),
+                                "metadata": {"scope": "module"},
+                            }
+                        )
+
+            elif isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                self._append_function(stmt, symbols, relationships, class_name=None)
+
+            elif isinstance(stmt, ast.ClassDef):
+                decos = [ast.unparse(d) if not isinstance(d, ast.Name) else d.id for d in stmt.decorator_list] or None
+                symbols.append(
+                    {
+                        "type": "class",
+                        "name": stmt.name,
+                        "qualified_name": stmt.name,
+                        "signature": f"class {stmt.name}",
+                        "docstring": ast.get_docstring(stmt),
+                        "start_line": getattr(stmt, "lineno", 1),
+                        "end_line": getattr(stmt, "end_lineno", getattr(stmt, "lineno", 1)),
+                        "metadata": {"decorators": decos} if decos else None,
+                    }
+                )
+                for class_stmt in stmt.body:
+                    if isinstance(class_stmt, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                        self._append_function(class_stmt, symbols, relationships, class_name=stmt.name)
+                        relationships.append(
+                            {
+                                "source": stmt.name,
+                                "target": f"{stmt.name}.{class_stmt.name}",
+                                "type": "CONTAINS",
+                                "line": getattr(class_stmt, "lineno", 1),
+                                "metadata": None,
+                            }
+                        )
+
+        return symbols, relationships
+
+    def _append_function(
+        self,
+        func: ast.FunctionDef | ast.AsyncFunctionDef,
+        symbols: list[dict],
+        relationships: list[dict],
+        class_name: str | None,
+    ) -> None:
+        qualified = f"{class_name}.{func.name}" if class_name else func.name
+        signature = self._build_signature(func)
+        is_async = isinstance(func, ast.AsyncFunctionDef)
+        typ = ("async method" if class_name else "async function") if is_async else ("method" if class_name else "function")
+        decos = [ast.unparse(d) if not isinstance(d, ast.Name) else d.id for d in func.decorator_list] or None
+        meta = {"class": class_name} if class_name else {}
+        if decos:
+            meta["decorators"] = decos
+        symbols.append(
+            {
+                "type": typ,
+                "name": func.name,
+                "qualified_name": qualified,
+                "signature": signature,
+                "docstring": ast.get_docstring(func),
+                "start_line": getattr(func, "lineno", 1),
+                "end_line": getattr(func, "end_lineno", getattr(func, "lineno", 1)),
+                "metadata": meta or None,
+            }
+        )
+
+        for node in ast.walk(func):
+            if not isinstance(node, ast.Call):
+                continue
+            callee = self._call_name(node.func)
+            if not callee:
+                continue
+            relationships.append(
+                {
+                    "source": qualified,
+                    "target": callee,
+                    "type": "CALLS",
+                    "line": getattr(node, "lineno", getattr(func, "lineno", 1)),
+                    "metadata": None,
+                }
+            )
+
+    def _build_signature(self, func: ast.FunctionDef | ast.AsyncFunctionDef) -> str:
+        prefix = "async def" if isinstance(func, ast.AsyncFunctionDef) else "def"
+        args = []
+        for arg in func.args.args:
+            a = arg.arg
+            if arg.annotation:
+                a += f": {ast.unparse(arg.annotation)}"
+            args.append(a)
+        sig = f"{prefix} {func.name}({', '.join(args)})"
+        if func.returns:
+            sig += f" -> {ast.unparse(func.returns)}"
+        return sig
+
+    def _call_name(self, func_expr: ast.expr) -> str | None:
+        if isinstance(func_expr, ast.Name):
+            return func_expr.id
+        if isinstance(func_expr, ast.Attribute):
+            chain: list[str] = []
+            current: ast.expr | None = func_expr
+            while isinstance(current, ast.Attribute):
+                chain.append(current.attr)
+                current = current.value
+            if isinstance(current, ast.Name):
+                chain.append(current.id)
+            return ".".join(reversed(chain)) if chain else None
+        return None

sampler/indexer/parsers/typescript.py

@@ -0,0 +1,9 @@
+from sampler.indexer.parsers.base import BaseParser
+
+
+class TypeScriptParser(BaseParser):
+    language = "typescript"
+
+    def parse(self, content: str, filepath: str) -> tuple[list[dict], list[dict]]:
+        _ = content, filepath
+        return [], []

sampler/indexer/store.py

@@ -0,0 +1,47 @@
+from sampler.db import Database
+
+
+class SymbolStore:
+    def __init__(self, db: Database) -> None:
+        self.db = db
+
+    def save_symbols(
+        self,
+        project_id: int,
+        filepath: str,
+        language: str,
+        file_hash: str,
+        symbols: list[dict],
+        relationships: list[dict],
+    ) -> None:
+        file_id = self.db.upsert_file(project_id=project_id, path=filepath, language=language, file_hash=file_hash)
+        self.db.clear_file_data(file_id)
+
+        symbol_id_map: dict[str, int] = {}
+        for symbol in symbols:
+            inserted_id = self.db.insert_symbol(file_id=file_id, symbol=symbol)
+            qualified = symbol.get("qualified_name") or symbol.get("name")
+            if qualified:
+                symbol_id_map[qualified] = inserted_id
+            name = symbol.get("name")
+            if name and name not in symbol_id_map:
+                symbol_id_map[name] = inserted_id
+
+        for relation in relationships:
+            source_key = relation.get("source")
+            target_key = relation.get("target")
+            if not source_key or not target_key:
+                continue
+
+            source_id = symbol_id_map.get(source_key)
+            if source_id is None:
+                source_id = self.db.find_symbol_id_in_project(project_id=project_id, symbol_name=source_key)
+
+            target_id = symbol_id_map.get(target_key)
+            if target_id is None:
+                target_id = self.db.find_symbol_id_in_project(project_id=project_id, symbol_name=target_key)
+
+            if source_id is None or target_id is None:
+                continue
+
+            self.db.insert_relationship(source_id=source_id, target_id=target_id, relation=relation)

sampler/mcp/server.py

@@ -0,0 +1,2 @@
+def run_server() -> None:
+    raise NotImplementedError("MCP server planned for later")

sampler/models.py

@@ -0,0 +1,35 @@
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass
+class Project:
+    id: int | None
+    name: str
+    path: str
+    language: str
+    indexed_at: datetime | None = None
+
+
+@dataclass
+class Symbol:
+    id: int | None
+    file_id: int
+    type: str
+    name: str
+    qualified_name: str | None = None
+    signature: str | None = None
+    docstring: str | None = None
+    start_line: int = 0
+    end_line: int = 0
+    metadata: dict | None = None
+
+
+@dataclass
+class Relationship:
+    id: int | None
+    source_id: int
+    target_id: int
+    type: str
+    line: int | None = None
+    metadata: dict | None = None

sampler/query/engine.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from sampler.db import Database
+
+
+class QueryEngine:
+    def __init__(self, db: Database) -> None:
+        self.db = db
+
+    def search(self, query: str, project_name: str | None = None, types: list[str] | None = None, limit: int | None = None, offset: int = 0) -> list[dict]:
+        rows = self.db.search_symbols(query=query, project_name=project_name, types=types, limit=limit, offset=offset)
+        return [dict(row) for row in rows]
+
+    def overview(self, filepath: str, project_name: str | None = None) -> list[dict]:
+        rows = self.db.get_symbols_by_filepath(filepath=filepath, project_name=project_name)
+        return [dict(row) for row in rows]

sampler/query/semantic.py

@@ -0,0 +1,4 @@
+class SemanticEngine:
+    def semantic_search(self, query: str, project_name: str | None = None) -> list:
+        _ = query, project_name
+        return []

sampler_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: sampler-cli
+Version: 0.2.0
+Summary: Token-efficient CLI for indexing and searching code symbols (Python-first, designed for minimal LLM/agent context size)
+Author: Samuel Ignacio Carmona Rodriguez
+License: MIT
+Project-URL: Homepage, https://github.com/sicr0/sampler-cli
+Project-URL: Repository, https://github.com/sicr0/sampler-cli
+Project-URL: Issues, https://github.com/sicr0/sampler-cli/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: tree-sitter>=0.21.0
+Requires-Dist: tree-sitter-python>=0.23.0
+Requires-Dist: gitignore-parser>=0.1.11
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: pyyaml>=6.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: mypy>=1.7.0; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=0.1.0; extra == "mcp"
+Provides-Extra: semantic
+Requires-Dist: sentence-transformers>=2.2.0; extra == "semantic"
+Dynamic: license-file
+
+# Sampler
+
+CLI indexer para navegar símbolos y relaciones en codebases multiproyecto.
+
+Versión actual: 0.1.2
+
+## Requisitos
+
+- Python 3.11+
+- `uv` (recomendado)
+- Go (instalado para soporte parser Fase 1)
+
+## Instalación de Go (macOS)
+
+```bash
+brew install go
+go version
+```
+
+## Instalación
+
+```bash
+pip install sampler-cli
+```
+
+Para desarrollo (incluye tests, linters):
+
+```bash
+pip install -e '.[dev]'
+```
+
+## Uso rápido
+
+```bash
+pip install sampler-cli
+sampler init
+sampler project add myproj /absolute/path --language python
+sampler project list
+sampler index myproj
+sampler search add --project myproj
+sampler overview /absolute/path/file.py
+```
+
+**Demo / LLM use (token-efficient by design):**
+- Default outputs are compact single-line (no tables, short paths, no noise).
+- Ideal for pasting into agents/LLMs with minimal context size.
+- Example: `sampler search worker --project myproj` → `myproj:src/tasks.py:42 function process  def process()`
+
+## Estado actual
+
+Implementado:
+
+- Bootstrap inicial de Fase 0
+- Configuración global con archivo `~/.sampler/config.yaml`
+- CRUD de proyectos en config (`add`, `list`, `remove`)
+- Esquema SQLite core + queries de index/search en `src/sampler/db.py`
+- Discovery de archivos por lenguaje con soporte `.gitignore`
+- Parser Python estable basado en AST
+- Indexer real (hash incremental + persistencia)
+- Query engine real (`search`, `overview`)
+- CI básico con GitHub Actions (`pytest -q`)
+- Tests: smoke, config, db, cli, discovery, python_parser, index_query
+
+Nota de estabilidad:
+
+- Se desactivó uso runtime de tree-sitter en parser Python por crash nativo (`BUS/SEGV`) en indexación real.
+- Se mantiene estrategia AST para estabilidad en producción local.
+
+Pendiente inmediato:
+
+- Filtros y paginación en búsqueda
+- Comandos `callers`, `usages`, `related`
+- Parsers Go y TypeScript/JavaScript
+
+## Estructura clave
+
+```text
+src/sampler/cli/main.py          # comandos CLI
+src/sampler/config.py            # config global YAML
+src/sampler/db.py                # capa SQLite
+src/sampler/indexer/builder.py   # indexación de proyectos
+src/sampler/indexer/store.py     # persistencia de símbolos/relaciones
+src/sampler/indexer/parsers/python.py # parser python estable
+src/sampler/query/engine.py      # search/overview
+src/sampler/indexer/discover.py  # discovery y filtros
+tests/                           # pruebas base
+```
+
+## Ejecutar pruebas
+
+```bash
+pytest -q
+```

sampler_cli-0.2.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+sampler/__init__.py,sha256=QwLGZDZhVE7dBKbOwCLRt3tRMXTtg8fYYHHDXi3sZ1c,49
+sampler/__main__.py,sha256=9_JuHaFFFklO51USpVH94P871geP25UsshaZE2fMjP8,72
+sampler/config.py,sha256=BcSQtNSP1fVVDLObbrgdq9GCk8GfhDfVk4kvf1vnUfg,2431
+sampler/db.py,sha256=iuNX5fgUkIB56ZDQWSxfkHpB0zP4e8woWc709HC7WRU,12421
+sampler/models.py,sha256=aem6T8cyTjK0mUeXfjlSYi52sFKq6YzBtFQdRYJIri0,635
+sampler/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sampler/cli/main.py,sha256=8-zLT-xObraEYCDiQXIY_QDZZKzvW9f0Ooj6AE2n6SI,5873
+sampler/indexer/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sampler/indexer/builder.py,sha256=fyaMT7iVnuIPm08r_EYclXeR7eIc4nz00phMA8Ru2n0,2439
+sampler/indexer/discover.py,sha256=_Gwi4BprW6jvnf0ChqDM_9_uioMdkWtp-aLNGpHLhXI,1449
+sampler/indexer/store.py,sha256=LnAALWacbvKV2S80Xbvu84rG1GAKACnVhZtdOJdyCbw,1727
+sampler/indexer/parsers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sampler/indexer/parsers/base.py,sha256=gdnUahZj_oSnn2QxhSVn_05UjQ7CNCtwi0Azjyn4NiM,217
+sampler/indexer/parsers/go.py,sha256=lIa0SJ9L4pk5Ho8WE6MNHfWuo2JkORXPGsOM3ohCjc0,238
+sampler/indexer/parsers/python.py,sha256=6pIK-WndxQcgdlb6pUf5mYPArLPi-LgXOfk-R4DnEoo,5775
+sampler/indexer/parsers/typescript.py,sha256=QAQADo5UIHJ-VqKRMcAuUrxAIwCJay8T7bz6maOg5MA,254
+sampler/mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sampler/mcp/server.py,sha256=uGSobXj8wQ0zNeWDCFHTgAgLC-J_xPMtMWf--ZrugpQ,88
+sampler/query/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sampler/query/engine.py,sha256=t5_5lOsxnjvPCk4AqOuM67RBkpvm-EmGU44bpK3ayIE,698
+sampler/query/semantic.py,sha256=iOIumz6horMJMWIi45gEQMdD35EEXdj4vKjP0Mg1fTw,156
+sampler_cli-0.2.0.dist-info/licenses/LICENSE,sha256=0HU6UzeTcc_a14ihCQwRzQXvlOtUZLWHyk4ZxSWiLFY,1089
+sampler_cli-0.2.0.dist-info/METADATA,sha256=UUC5F6gSO8_Hyw6P7U8vnj_gKj4EggYfC8eSZrJupmw,3932
+sampler_cli-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sampler_cli-0.2.0.dist-info/entry_points.txt,sha256=HYeHAaX1KKmdPjpLFjULGqWpBnUCOVDrEM8EJbNe-Oc,49
+sampler_cli-0.2.0.dist-info/top_level.txt,sha256=s2IbPtyHmWaMta20F-P53OMgvEDarZO8uSzVN3uchgc,8
+sampler_cli-0.2.0.dist-info/RECORD,,

sampler_cli-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sampler_cli-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sampler = sampler.cli.main:app

sampler_cli-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Samuel Ignacio Carmona Rodriguez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sampler_cli-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sampler