Add repository-level code graph support for AI-assisted navigation

[axies20]

Related to an existing integration?

No

Existing integration

N/A

Overview

CommunityToolkit/Aspire contains a growing number of integrations organized across src/, tests/, examples/, documentation, and repository-specific agent guidance.

AI coding assistants can navigate this today with text and code search, but they still need to repeatedly reconstruct relationships between an integration, its hosting extensions, resource types, tests, examples, documentation, and related projects.

I would like to propose adding repository-level code graph support so AI coding assistants can query a machine-readable representation of the repository before falling back to broad file searches.

Useful relationships could include:

• integration project → public hosting extension methods / resource types
• project → references → project / package
• implementation → related unit and integration tests
• implementation → related examples and documentation
• type / member → calls / uses / inherits → type / member

This would be repository tooling only and would not need to become a runtime dependency of any CommunityToolkit Aspire integration.

Graphify is one existing implementation that could be evaluated. The proposal is primarily about the artifact and capability, not a requirement to adopt this specific tool. The generated representation and tooling should remain replaceable.

The graph could be generated or refreshed in CI and then committed, published as an artifact, exposed through MCP, or generated on demand. That delivery choice could be decided separately.

I tested this approach on another .NET repository. The full source corpus was roughly 193k tokens, while graph-backed retrieval averaged roughly 4.3k tokens of relevant context per query. This is not intended as a formal benchmark, but it made repository exploration noticeably cheaper and more focused for an AI agent.

Usage example

Before modifying an Aspire hosting integration, an AI coding assistant could query the graph rather than broadly scanning the repository:

User: Update the hosting integration for a resource.

Agent:
1. Query the repository graph for the integration project.
2. Discover its public hosting extension methods and resource types.
3. Retrieve the related tests, examples, and documentation.
4. Load only those files into context.
5. Make the change and run the relevant test subset.

Another useful scenario is impact analysis:

Agent: What could be affected if this hosting extension changes?

Graph → hosting extension → resource type → referenced packages
      → integration tests → examples → documentation

This could also help human contributors with onboarding and architecture exploration. An interactive visualization could be generated from the same graph, but the main motivation is efficient machine-readable navigation for coding agents.

Breaking change?

No

Alternatives

Current alternatives include:

• letting each coding agent repeatedly use text search, file discovery, and symbol search;
• relying on IDE or LSP indexing available only in the local development environment;
• maintaining hand-written architecture documentation;
• allowing every contributor or agent to generate its own local index independently.

Those approaches work, but they duplicate repository-discovery effort and provide no shared, versioned structural representation of the codebase.

Another alternative would be to define a small CommunityToolkit Aspire-specific graph or index format rather than use Graphify. I would prefer evaluating an existing tool first while keeping the generated representation and tooling replaceable.

Additional context

The repository already includes guidance for AI-assisted development. A repository-level graph could complement that guidance by providing a current structural view of integrations, hosting APIs, tests, examples, documentation, and project dependencies.

The goal is not to make AI-generated changes autonomous or bypass review. It is simply to give tools a cheaper and more deterministic way to answer questions such as where is this implemented, what is connected to it, and which tests and examples are relevant?

Help us help you

Yes, but only if others can assist

[aaronpowell]

Ironically, despite my personal heavy use of GitHub Copilot, this repo is horribly unoptimised for working with AI coding agents. There's a very basic copilot instructions file that I wrote ages ago and has some of what you note, but it probably makes more sense to turn that into a AGENTS.md file.

There's probably some value in generating a bunch of skills for the repo too - currently there are some Prompts and Chat Modes - both of which are pretty legacy in the design of current harnesses.

[axies20]

Thanks — I agree that an AGENTS.md plus repository-specific skills would be useful, especially for documenting conventions and common workflows.

For the structural/navigation side, I also came across [CodeGraph](https://github.com/colbymchenry/codegraph), which may actually be a better fit for this proposal than Graphify.

It builds a local code graph and exposes it to agents through MCP, so the agent can retrieve relevant symbols, call paths, dependencies, and impact information instead of repeatedly reconstructing those relationships through search. It also has C# support and now understands ASP.NET Razor / Blazor relationships.

So these could potentially complement each other rather than compete:

• AGENTS.md / skills → repository conventions and workflows
• CodeGraph → machine-generated, current structural relationships in the codebase

That also keeps the original idea fairly lightweight: the repo wouldn't need to maintain a custom graph format or use an LLM to generate the graph.

[Odonno]

Note that there are graph tools that work locally on your machine.

[nikolai-vysotskyi]

Disclosure: I maintain trace-mcp, which builds code graphs for coding agents across multiple languages including C#.

One architectural trap worth keeping in mind when evaluating code graph tools for this repository: C# namespace import fan-out.

Unlike Python modules or JS/TS files, a C# using Acme.Store; directive does not mean the importing file depends on every file that declares namespace Acme.Store. When we benchmarked naive file-to-file dependency resolution on namespace imports in real .NET codebases (such as Newtonsoft.Json), it produced an average of 86 resolved dependency edges per file because C# namespaces routinely span dozens of files across a project.

If a code graph tool creates edges for plain namespace using statements, the graph becomes a dense hairball that pollutes the agent's context with hundreds of irrelevant connections. Clean graph extraction in C# requires distinguishing between:

• Plain namespace using Namespace; (which only opens scope and should not create file dependency edges).
• Specific type imports (using static Namespace.Type; or using Alias = Namespace.Type;), which map to exact declaring files.
• Actual symbol-level call and reference edges.

[aaronpowell]

I'm not sure that we'd find a whole lot of value in this project from some tool that's doing indexing of the code because this repo isn't really that code heavy or containing much in the way of complex code - a lot of the integrations are really simplistic.

Additionally, there's very little intersection between the code in this repo. The repo is really just a monorepo of isolated projects. Integrations are referenced by their example and test projects, but there's not really anything more than that (yes, there is a small overlap with things like DbGate that are a meta package consumed in other packages).

I think we should start simple - AGENTS.md that outlines the repo structure and the common patterns, then some skills which are for the specific tasks (how to write certain patterns, like the TypeScript tests, the container tags C# file, etc.). This also results in the lowest overhead - no need to bootstrap additional tools or anything.

[Odonno]

Probably a very lightweight AGENTS.md and some interesting skills like:

• bootstrap-hosting-integration
• bootstrap-client-integration
• upgrade-container-tags

And some useful ones I didn't consider.

[aaronpowell]

I did write agents, well chat-modes as they were called then, that did the first two, but they'd be woefully out of date 😅