Graphify C#: index semántico para agentes IA en C#

Graphify C#: el indexador Roslyn que faltaba para agentes

Graphify C# es un indexador headless basado en Roslyn/MSBuild que convierte código fuente C# en un grafo semántico consultable: callers resueltos por el compilador, implementaciones de interfaces, herencia, overrides y referencias — incluso entre overloads, genéricos y proyectos. Lanzado bajo MIT en NuGet, su promesa es simple: darle a un agente de IA la misma precisión de "Find Usages" que tiene un humano dentro de JetBrains Rider, sin abrir un IDE.

La motivación es directa. Cuando le preguntas a Codex, Claude Code u otro coding agent "¿qué métodos solo se usan desde tests?", una búsqueda por texto solo encuentra coincidencias léxicas: no distingue qué overload fue bindeado, en qué proyecto está el caller, ni si esa implementación de interfaz es exactamente el símbolo que querías. Graphify C# carga la solución a través de MSBuild y le pide a Roslyn el significado real de cada símbolo. El resultado es un JSON determinista con nodos, aristas e hyperedges que el agente puede consultar en lugar de inferir.

Qué resuelve y qué no (el límite estático)

El repositorio incluye un ejemplo concreto. El método interno DeclarationCatalogBuilder.ForTesting(...) aparece en el grafo con una única llamada entrante, resuelta por el compilador:

Graphify.CSharp.Roslyn.DeclarationCatalogBuilder.ForTesting(...)
└── llamado por Graphify.CSharp.Tests.Roslyn.CSharp14FeatureTests
    en tests/Graphify.CSharp.Tests/Roslyn/CSharp14FeatureTests.cs:143

Eso es evidencia semántica, no un conteo de coincidencias. El consumidor puede clasificar al caller por convención de proyecto o namespace y reportar el método como de uso exclusivo de tests para revisión humana.

El proyecto documenta con claridad su frontera de análisis estático: reflexión, dependency injection, callbacks nativos e invocación dinámica pueden crear relaciones runtime que no aparecen como aristas directas. En consecuencia, cero referencias entrantes significa cero referencias estáticas observadas, no prueba de inalcanzabilidad en ejecución. Cada candidato a borrado sigue requiriendo criterio humano.

Compatibilidad de runtime y lenguajes

El paquete expone dos tool assets según el runtime que elijas al instalar:

• net10.0 → .NET 10 con Roslyn 5.9 y soporte de C# 14.
• net11.0 → .NET 11 SDK con Roslyn / C# 15 preview.

Se instala con dotnet tool install --global Graphify.CSharp --framework net10.0. Si trabajas en un proyecto multi-target, el flag --target-framework elige una compilación específica a analizar. Los proyectos single-target no lo necesitan.

Qué declaraciones y relaciones indexa

Declaraciones cubiertas: namespaces, classes, structs, interfaces, records, enums y delegates; constructores, métodos, operadores y funciones locales; propiedades, indexers, fields, enum members y eventos; parámetros, locals, type parameters, aliases, labels y query range variables.

Relaciones resueltas por el compilador: llamadas directas, llamadas a constructores, method groups y member access; referencias a fields, types, attributes, generics, typeof y headers de declaración; inherits, implements, overrides; operadores, conversiones, deconstrucción, foreach, await, using, patterns, ranges y collection expressions seleccionadas por el compilador; argumentos de invocación y constructor bindeados a parámetros formales; relaciones cross-project con identidad consciente de overload y de TFM.

Cada arista apunta desde la declaración donde se observó la relación hasta la declaración que Roslyn resolvió. Source location y provenance se conservan. Las formas semánticas no soportadas se reportan como diagnostics en lugar de desaparecer silenciosamente.

Cómo encaja frente a Rider y NDepend

El propio README posiciona a Graphify C# en una capa específica:

• Rider y ReSharper cubren navegación interactiva, inspections, refactorings y quick fixes dentro del IDE.
• NDepend ofrece una suite comercial amplia de arquitectura y calidad centrada en dependencias, métricas, reglas, reportes y baselines.
• Graphify C# entrega evidencia semántica C# headless y en formato abierto, pensada para que agentes y otras herramientas construyan encima.

Hay solapamiento real con NDepend en callers, dependencias, herencia e investigación de dead code. La diferencia es de frontera de producto: Graphify C# no pretende ser un clon gratuito de NDepend ni un reemplazo de IDE. Es un índice semántico Roslyn-native sobre el que otros agentes y herramientas pueden construir.

Quick start: tres pasos para darle al agente lo que necesita

1. Instalar el tool apuntando al runtime que prefieras (net10.0 o net11.0).
2. Indexar el codebase corriendo graphify-csharp --input ./src/MyProduct.sln --root . --configuration Release --output ./graphify-out/csharp.json. Acepta .sln, .slnx, .csproj y apps .cs file-based del SDK.
3. Enseñar al agente a usarlo. El repo incluye un skill instalable que le dice a Codex cuándo refrescar el índice y cómo seguir las aristas semánticas. Para Claude Code, se copia en .claude/skills/graphify-csharp/SKILL.md. Tras instalar o actualizar el skill, se recarga la sesión del agente.

Si no usas skills, basta con agregar al AGENTS.md del proyecto una instrucción como: "Para preguntas sobre estructura y usages en C#, refresca graphify-out/csharp.json con graphify-csharp antes de responder. Identifica declaraciones por symbol_key e inspecciona las aristas entrantes calls y references. Trata cero referencias entrantes como evidencia estática observada, no como prueba de inalcanzabilidad runtime."

Para trabajo iterativo del agente, el flag --watch mantiene el workspace de Roslyn caliente y prepara los proyectos cambiados en background. Una invocación normal actúa como barrera de refresco explícita y devuelve solo cuando el snapshot está completo. Sin watcher corriendo, la misma orden hace un refresh one-shot. --rebuild invalida el caché incremental.

Qué le puedes preguntar al agente con el índice armado

Con graphify-out/csharp.json en su contexto, el agente puede responder con precisión de compilador a preguntas como:

• ¿Qué llama a este overload o constructor exacto?
• ¿Qué declaraciones referencian este field, property, event o type?
• ¿Qué clases implementan esta interfaz?
• ¿Qué miembros hacen override de este virtual o interface member?
• ¿Qué declaraciones tienen cero referencias entrantes observadas?
• ¿Qué métodos se referencian solo desde proyectos de test?

Cada respuesta está anclada a un symbol_key estable con identidad de proyecto y TFM, no a un grep.

¿Qué significa esto para tu startup?

Si tu equipo usa Codex o Claude Code sobre código C# y nota que el agente "adivina" cuando le preguntas por callers o implementaciones, Graphify C# te da el reemplazo headless de la navegación de Rider. La ventaja concreta es menos alucinaciones en refactors grandes: antes de borrar un método, el agente te muestra el grafo de llamadas resuelto por Roslyn, con archivo, línea y proyecto de cada caller.

Tres acciones que puedes aplicar esta semana:

1. Pilota en una sola solución. Instala el tool con --framework net10.0, indexa una .sln real y agrega la instrucción de refresco al AGENTS.md o CLAUDE.md del repo. Mide cuántos falsos positivos en tareas de refactor desaparecen.
2. Convierte preguntas de código en queries al JSON. Entrena al equipo a no preguntar "¿dónde se usa X?" en chat, sino a invocar graphify-csharp y abrir el JSON con jq o desde tu propio código. El agente deja de improvisar y empieza a verificar.
3. Separa tests de producción con el grafo. Como cada arista preserva proyecto y namespace, puedes marcar como test-only los métodos cuya única llamada entrante venga de un proyecto de tests. Útil para candidatos a borrado antes de una migración a .NET 11 o una limpieza de deuda técnica.

Fuentes

• zachsaw/graphify-csharp (GitHub)
• AI Coding Agents Skip Package Verification, and Attackers Are Exploiting It — TechTimes