DuckLens

Extensión de VS Code rápida y ligera estilo GitLens, sin telemetría ni dependencias en runtime. Solo usa el git de tu sistema.

Instalación

La extensión se distribuye como archivo .vsix; no hace falta compilar nada para usarla. Si ya está publicada en el Marketplace, también puedes instalarla desde el panel de Extensiones buscando DuckLens.

Requisitos

• VS Code 1.90 o superior (también funciona en forks compatibles como Cursor o VSCodium).
• Git instalado y disponible en el PATH; la extensión usa el git del sistema.
• Opcional: un endpoint compatible con OpenAI (Ollama, LM Studio, llama.cpp, vLLM, OpenAI…) para el commit con IA.
• Opcional: Node.js 18+ solo si vas a compilarla o empaquetarla desde el código fuente.

Instalar el VSIX (recomendado)

Usa el paquete ya empaquetado que acompaña al proyecto, ducklens-0.2.0.vsix.

Desde la interfaz de VS Code

1. Abre VS Code y el panel de Extensiones (Ctrl+Shift+X).
2. Pulsa el menú … de la esquina superior derecha del panel y elige Install from VSIX….
3. Selecciona ducklens-<versión>.vsix y confirma la instalación.
4. Si VS Code lo pide, recarga la ventana: Ctrl+Shift+P → Developer: Reload Window.

Desde la terminal

code --install-extension .\ducklens-0.2.0.vsix

• VS Code Insiders: code-insiders --install-extension .\ducklens-0.2.0.vsix.
• Cursor / VSCodium: cursor --install-extension … / codium --install-extension ….
• macOS/Linux: code --install-extension ducklens-0.2.0.vsix.
• Si el comando code no existe: Ctrl+Shift+P → Shell Command: Install 'code' command in PATH (macOS y Linux); en Windows, reinstala VS Code con la opción "Add to PATH".
• Para forzar la reinstalación de la misma versión, añade --force.

Comprueba que quedó instalada buscando DuckLens en el panel de Extensiones o con:

code --list-extensions | Select-String ducklens

Instalar desde el código fuente

npm install
npm run compile
npm run package        # genera ducklens-<versión>.vsix
code --install-extension .\ducklens-0.2.0.vsix

Para probar sin empaquetar, pulsa F5 en VS Code (Extension Development Host) o deja npm run watch en marcha mientras desarrollas.

Primeros pasos

1. Abre una carpeta que sea un repositorio Git con al menos un commit.
2. Pon el cursor en una línea: el blame aparece al final y la tarjeta al pasar el ratón.
3. El botón de la barra de estado (o Ctrl+Alt+B / Cmd+Alt+B) activa o desactiva el blame inline.
4. Para el commit con IA, configura ducklens.ai.baseUrl y ducklens.ai.model (ver IA local), stagea los cambios y pulsa ✨ o Ctrl+Alt+G / Cmd+Alt+G.

Actualizar y desinstalar

• Actualizar: instala el .vsix de la versión nueva; VS Code reemplaza la anterior. Desde la terminal puedes añadir --force.
• Desinstalar: panel de Extensiones → DuckLens → Uninstall, o code --uninstall-extension ducklens.ducklens.
• Los ajustes ducklens.* permanecen en settings.json; bórralos a mano si quieres dejarlo limpio.

Qué hace

Por qué es ligera

• Cero dependencias en runtime; un solo git blame --line-porcelain por archivo, cacheado por versión del documento.
• Mover el cursor no relanza git: solo repinta la decoración (debounce configurable, 250 ms por defecto).
• La tarjeta hover cachea metadatos, diff y avatar por commit/autor: abrirla una vez por commit y luego es instantánea.
• Sin telemetría, sin cuentas, sin indexar el repo entero. Las peticiones a GitHub (solo para el avatar) son opcionales y se pueden desactivar.

Tarjeta hover

Al pasar el ratón sobre una línea, la tarjeta se ordena así:

1. Cabecera — asunto del commit, avatar de GitHub del autor (si se puede resolver), autor, email y fecha absoluta + relativa.
2. Mensaje — cuerpo del commit, si lo tiene.
3. Cambios — estadísticas del archivo y del commit, y el fragmento de diff que contiene la línea: + agregadas en verde, - eliminadas en rojo, contexto atenuado.
4. Acciones — copiar hash, ver commit y abrir el commit en GitHub (cuando el remoto es GitHub).

{
  "ducklens.hover.enabled": true,
  "ducklens.hover.diff": true,          // muestra el fragmento de diff coloreado
  "ducklens.hover.diffMaxLines": 14,    // tope de líneas del fragmento

  "ducklens.github.avatars": true,      // avatar de GitHub del autor (requiere red)
  "ducklens.github.token": ""           // opcional: PAT sin scopes, o env DUCKLENS_GITHUB_TOKEN
}

El avatar se resuelve contra la API pública de GitHub (github.com) y se cachea por autor. Si no hay red, el autor no tiene cuenta de GitHub o se alcanza el límite de peticiones, la tarjeta se muestra igualmente sin imagen. Para muchos autores distintos o repos privados, configura ducklens.github.token (un PAT sin permisos basta).

IA local (OpenAI-compatible)

Funciona con cualquier endpoint /v1/chat/completions: Ollama, LM Studio, llama.cpp server, vLLM, OpenAI, OpenRouter…

Ajustes en settings.json:

{
  // Ollama (por defecto)
  "ducklens.ai.baseUrl": "http://localhost:11434/v1",
  "ducklens.ai.model": "llama3.2",

  // LM Studio
  // "ducklens.ai.baseUrl": "http://localhost:1234/v1",
  // "ducklens.ai.model": "qwen2.5-coder-7b-instruct",

  // OpenAI
  // "ducklens.ai.baseUrl": "https://api.openai.com/v1",
  // "ducklens.ai.model": "gpt-4o-mini",
  // "ducklens.ai.apiKey": "sk-…"   // o env DUCKLENS_AI_API_KEY

  "ducklens.ai.language": "es",          // es | en | auto
  "ducklens.ai.conventionalCommits": true,
  "ducklens.ai.maxDiffChars": 12000
}

Arranque rápido con Ollama:

ollama serve
ollama pull llama3.2

Luego: stagea tus cambios (git add), abre la vista Source Control y pulsa ✨.

Blame inline a tu gusto

{
  "ducklens.blame.enabled": true,
  "ducklens.blame.delayMs": 250,
  "ducklens.blame.format": "{author}, {relativeTime} • {summary}",
  "ducklens.blame.maxSummaryLength": 60,
  "ducklens.hover.enabled": true
}

Tokens de format: {author} {relativeTime} {date} {summary} {hash} {shortHash}.

Desarrollo

npm install
npm run compile   # o npm run watch
npm test          # tests puros: blame, formato, diff, GitHub y tarjeta hover

Pulsa F5 en VS Code para lanzar el Extension Development Host. Para empaquetar: npm run package (genera el .vsix).

Licencia

MIT