sampler-cli 0.2.0__tar.gz

sampler_cli-0.2.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,93 @@
+# 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/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "sampler-cli"
+version = "0.2.0"
+description = "Token-efficient CLI for indexing and searching code symbols (Python-first, designed for minimal LLM/agent context size)"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Samuel Ignacio Carmona Rodriguez" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Code Generators",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "typer>=0.12.0",
+    "rich>=13.7.0",
+    "tree-sitter>=0.21.0",
+    "tree-sitter-python>=0.23.0",
+    "gitignore-parser>=0.1.11",
+    "pydantic>=2.6.0",
+    "pyyaml>=6.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "ruff>=0.5.0",
+    "mypy>=1.7.0",
+]
+mcp = ["fastmcp>=0.1.0"]
+semantic = ["sentence-transformers>=2.2.0"]
+
+[project.scripts]
+sampler = "sampler.cli.main:app"
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[project.urls]
+Homepage = "https://github.com/sicr0/sampler-cli"
+Repository = "https://github.com/sicr0/sampler-cli"
+Issues = "https://github.com/sicr0/sampler-cli/issues"

sampler_cli-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sampler_cli-0.2.0/src/sampler/__init__.py

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

sampler_cli-0.2.0/src/sampler/__main__.py

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

sampler_cli-0.2.0/src/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_cli-0.2.0/src/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())