ucn

UCN - Navegador Universal de Código

Mira lo que hace el código antes de tocarlo.

Si trabajas con Agentes de IA, añade UCN como una Habilidad o herramienta MCP. Una sola herramienta le da al agente respuestas compactas y vinculadas al código fuente sobre llamadores, impacto y preguntas de pruebas, con incertidumbre etiquetada en lugar de adivinada.

Resumen conceptual · Imagen fija

Usa la CLI directamente, instala la habilidad de agente, o conéctate a través de MCP. Un solo motor suministra los tres:

  Terminal              AI Agents           Agent Skills
       │                    │                    │
      CLI                  MCP                 Skill
       └────────────────────┼────────────────────┘
                            │
                     ┌──────┴──────┐
                     │ UCN Engine  │
                     │  commands   │
                     │ tree-sitter │
                     └─────────────┘

UCN utiliza árboles de sintaxis abstracta (AST) de tree-sitter para análisis estático de código, sin compilar el proyecto ni iniciar un servidor de lenguaje. La CLI se ejecuta bajo demanda y reutiliza un índice incremental; MCP mantiene un proceso disponible para consultas repetidas. No se requiere configuración del proyecto, y la caché vive fuera del repositorio.

Soporta JavaScript, TypeScript, JSX/TSX, Python, Go, Rust, Java, C, C++, C#, y scripts en línea de HTML.

Instalación

npm install -g ucn                    # Node.js 20+

En la terminal

Desde un directorio de proyecto:

ucn repo
ucn show handleRequest --lines
ucn source handleRequest --raw
ucn impact --staged --lines
ucn check --staged

repo mapea el proyecto. show --lines localiza llamadores, source --raw recupera la implementación, y impact y check inspeccionan un cambio en etapa de preparación. Cuando un nombre es ambiguo, find devuelve un identificador file:line:name que los comandos subsiguientes aceptan.

--lines devuelve registros path:line:text; --raw devuelve código fuente. Ambos se ajustan a los scripts existentes de un agente sin necesidad de analizar un informe legible por humanos.

La búsqueda de texto sigue siendo útil para comentarios, configuración, cadenas y código fuera de los lenguajes soportados. usages proporciona el inventario de nombres literales cuando la tarea necesita cada ocurrencia, incluidas aquellas que no son llamadas.

Navegación de código y análisis de cambios

show reúne la firma, fuente, llamadores, llamados y contexto relacionado de un símbolo. Selecciona las secciones que necesites o establece un presupuesto de salida para mantener la respuesta enfocada. trace sigue el grafo de llamadas entre archivos, hacia abajo en los llamados o hacia arriba a través de los llamadores hacia los puntos de entrada. Las relaciones no verificadas permanecen visibles, y el informe del árbol indica dónde se detuvo la exploración.

impact conecta un símbolo o un diff de Git con sus llamadores. tests sigue rutas indexadas de llamadas y referencias para identificar pruebas vinculadas estáticamente, incluyendo enlaces a varios saltos de distancia. plan previsualiza un cambio de nombre o de firma con ubicaciones de fuente y elementos de revisión; no edita archivos. Juntos, estos comandos soportan exploración de código, refactorización y revisión de cambios desde una terminal o un agente de IA.

Lo que establece una respuesta

Para respuestas de llamadores, UCN verifica enlaces, importaciones, tipos de receptor y propiedad para distinguir llamadas a la definición seleccionada de otros usos de su nombre. Las llamadas sin evidencia suficiente permanecen visibles como no verificadas, con una razón. Un nombre de método coincidente por sí solo no establece qué implementación se ejecuta; la evidencia de receptor y propiedad determina cómo se clasifica el candidato.

En ripgrep en 82313cf9, el helper file_name seleccionado tiene cuatro sitios de llamada confirmados y un candidato no verificado. Esta animación explica las 29 líneas coincidentes, junto con relaciones de importación y definiciones de mismo nombre extraídas de la salida de UCN.

Hallazgos capturados · Imagen fija · Datos

La línea ACCOUNT concilia las ocurrencias de nombre observadas: llamadas confirmadas, candidatos no verificados, ocurrencias que no son llamadas y coincidencias atribuidas a otro objetivo. CONTRACT describe el alcance de esa contabilidad. Las advertencias identifican fuente que el índice no pudo cubrir. Estos detalles sobreviven al truncamiento de texto para el presupuesto de salida de un agente.

Un resultado vacío, por lo tanto, significa algo específico sobre el código inspeccionado. No puede establecer que la reflexión, el código generado, el registro en tiempo de ejecución o los consumidores externos nunca alcancen un símbolo. deadcode suministra candidatos para investigar; la eliminación aún necesita corroboración. Una vista previa de refactorización aún necesita el compilador y las pruebas.

Precisión y validación

Las puertas de lanzamiento comparan las respuestas de UCN con compiladores independientes y servidores de lenguaje en un tablero de diez repositorios de bases de código de producción fijadas. La evaluación local del 6 de septiembre de 2026 registró estos resultados de llamadores muestreados:

| Repositorio | Commit fijado | Oráculo | Símbolos muestreados | Precisión confirmada | Recuerdo en alcance | |---|---:|---:|---:|---:| | preact-signals | e0ce9fdf | ts-morph | 27 | 100% | 100% | | httpx | b5addb64 | Pyright | 50 | 100% | 100% | | cobra | ad460ea8 | gopls | 50 | 100% | 100% | | viper | 528f7416 | gopls | 50 | 100% | 100% | | ripgrep | 82313cf9 | rust-analyzer | 41 | 100% | 100% | | clap | d3e59a9a | rust-analyzer | 50 | 100% | 100% | | javapoet | b9017a95 | JDT LS | 50 | 100% | 100% | | newtonsoft-json | 4f73e743 | Roslyn | 50 | 100% | 100% | | cjson | c859b25d | clangd | 50 | 100% | 100% | | fmt | e424e3f2 | clangd | 50 | 100% | 100% |

Esa evaluación informó cero bordes de oráculo en alcance faltantes tanto en respuestas de llamadores como de llamados, y 8,000 comparaciones entre comandos con cero desacuerdos. La auditoría predeterminada de código muerto encontró cero resultados falsos muertos entre 13 afirmaciones puntuadas; 13 afirmaciones adicionales no pudieron ser fijadas por el oráculo y no fueron puntuadas. Los diez repositorios pasaron los presupuestos de rendimiento, con p95 de consulta en estado estable de 4.5 a 76.2 ms. Esos tiempos excluyen el inicio del proceso y la indexación; las compilaciones en frío y la carga de caché se miden por separado.

Las muestras son deterministas y estratificadas por actividad de referencia. La precisión confirmada se aplica a afirmaciones puntuadas; el recuerdo cuenta bordes de oráculo en alcance encontrados en la banda confirmada o no verificada. Los candidatos no verificados, las abstenciones del oráculo y los hallazgos no puntuados permanecen separados. Estas mediciones no establecen conocimiento completo del tiempo de ejecución ni rendimiento idéntico en cada máquina.

El tablero programado cubre 24 repositorios fijados: los diez anteriores más zod, express, hono, zustand, fastify, rich, click, attrs, grpc-go, chi, cursive, itertools, gson y jsoup. Un brazo rotatorio de repositorios frescos verifica bases de código fuera de ese tablero fijado.

El manifiesto del repositorio registra los commits completos. El flujo de trabajo de Publicación controla los lanzamientos, y el flujo de trabajo de Evaluación ejecuta las verificaciones según lo programado y bajo demanda. Sus páginas de ejecución proporcionan resultados de CI y artefactos de evaluación. Reproduce las verificaciones localmente con las dependencias del oráculo instaladas:

npm run verify
npm run trust:gate

Comandos

deps --cycles agrupa dependencias circulares y distingue importaciones ansiosas de bordes diferidos o solo de tipo. Los límites de enumeración se divulgan. repo informa la cobertura de fuente así como la estructura del proyecto; su clasificación HOT rápida tiene un presupuesto de refinamiento divulgado, y repo --sections=stats --hot solicita la clasificación exacta.

endpoints --bridge coincide rutas de servidor y solicitudes de cliente reconocidas por sus extractores de framework. plan maneja relaciones de código como importaciones, anulaciones y métodos de interfaz o trait cuando se resuelve la propiedad; las relaciones ambiguas permanecen como elementos de revisión.

Ejecuta ucn --help para ver las banderas, o usa la referencia de comandos.

Salida de terminal

Los registros y el código van a stdout; la contabilidad y las notas van a stderr. Los registros no verificados llevan una razón separada por tabulaciones. Una lista vacía sale con 1, un error sale con 2, y una lista exitosa sale con 0. --lines soporta find, show, usages, search y impact; show --lines lista llamadores por defecto. Usa --json cuando el script necesite campos estructurados o un resultado de árbol.

Las listas no tienen un límite de filas predeterminado. Los límites explícitos divulgan lo que omiten, y un presupuesto de caracteres en modo terminal falla antes de escribir salida parcial. source --raw extrae funciones y clases completas a menos que se solicite un límite de líneas explícito; cualquier truncamiento resultante se informa en stderr.

Los errores de comandos ordinarios en modo texto también salen con 2. JSON mantiene salida 0 para resultados vacíos exitosos y salida 1 para errores de comando (meta.ok: false más error). check sin objetivo sale con 1 cuando TRUST es BLOCKED, 0 para otras verificaciones completadas, y 2 si no pudo ejecutarse.

Fuera de --lines, find, texto search, deadcode, api y repo --sections=files tienen un máximo predeterminado de 500 resultados. Usa --limit=N para solicitar más; usages lista cada sitio a menos que se dé un límite. Las consultas amplias de find seleccionan candidatos por totales de uso aproximados antes de calcular la actividad de llamadores fijada por definición, y divulgan esa selección cuando está limitada.

Los archivos nombrados *.min.js, *.bundle.js y *.map se informan como fuentes omitidas y hacen que la completitud sea parcial. --include-bundled (MCP include_bundled=true) indexa los paquetes de JavaScript respetando las exclusiones del usuario; omite la caché compartida. Los mapas de fuente permanecen divulgados pero no indexados.

Configuración de IA

Una herramienta, 18 comandos, respuestas compactas vinculadas a la fuente que mantienen sus metadatos de confianza incluso cuando se truncan.

MCP

# Claude Code
claude mcp add ucn -- npx -y ucn --mcp

# OpenAI Codex CLI
codex mcp add ucn -- npx -y ucn --mcp

# VS Code Copilot
code --add-mcp '{"name":"ucn","command":"npx","args":["-y","ucn","--mcp"]}'

{
  "mcpServers": {
    "ucn": {
      "command": "npx",
      "args": ["-y", "ucn", "--mcp"]
    }
  }
}

{
  "servers": {
    "ucn": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "ucn", "--mcp"]
    }
  }
}

Habilidad de Agente (sin necesidad de servidor)

macOS / Linux:

# Claude Code
mkdir -p ~/.claude/skills
cp -r "$(npm root -g)/ucn/.claude/skills/ucn" ~/.claude/skills/

# OpenAI Codex CLI
mkdir -p ~/.agents/skills
cp -r "$(npm root -g)/ucn/.claude/skills/ucn" ~/.agents/skills/

Windows PowerShell:

$npmRoot = npm root -g
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills"
Copy-Item -Recurse "$npmRoot\ucn\.claude\skills\ucn" "$env:USERPROFILE\.claude\skills\"

New-Item -ItemType Directory -Force "$env:USERPROFILE\.agents\skills"
Copy-Item -Recurse "$npmRoot\ucn\.claude\skills\ucn" "$env:USERPROFILE\.agents\skills\"

La habilidad enseña a un agente cómo orientarse, fijar símbolos, elegir el comando útil más pequeño, interpretar los niveles de evidencia y recuperarse de respuestas incompletas. Es orientación sobre el mismo motor, no una segunda implementación.

Alcance

UCN analiza fuente indexada en un proyecto. No ejecuta el programa ni indexa dependencias instaladas como node_modules y site-packages. repo --sections=health --deep informa la cobertura de fuente y los límites de análisis conocidos.

C y C++ pueden usar compile_commands.json para rutas de inclusión y contexto de encabezados, pero UCN no ejecuta el preprocesador ni reproduce la vista específica de compilación de un compilador. Los generadores de fuente de C# y los ensamblados externos también están fuera del índice. HTML tiene cobertura de regresión pero no un oráculo de compilador/LSP de repositorio.

La CLI, MCP y la habilidad comparten las mismas reglas de resolución y evidencia. Cambiar el transporte no cambia lo que el motor sabe sobre el código.

MIT