code-map

日本語版は README.ja.md です。

code-map is a GitHub Copilot CLI extension that adds the /code-map custom command. It analyzes a .NET solution and renders a project dependency map as a text summary, Mermaid diagram, and interactive preview when the host supports canvases.

Features

• Discovers .sln and .slnx files from a solution path or directory.
• Parses .csproj, .fsproj, .vbproj, and .vcxproj projects.
• Summarizes project references, package references, project kinds, test projects, and dependency hubs.
• Detects circular dependencies at the project level and reports each cycle group.
• Builds a namespace-level dependency graph for C# projects and detects namespace cycles.
• Generates Mermaid flowchart LR output for inline fallback rendering, with cycle nodes and edges styled in red.
• Opens a Code Map canvas when Copilot CLI canvas support is available, with a Projects/Namespaces granularity toggle.
• Serves a local browser preview on 127.0.0.1 with per-instance access keys.

Requirements

• GitHub Copilot CLI with extension and canvas support.
• dotnet available on PATH.
• A dotnet version that can run C# file-based apps, because the extension invokes .github/code-map/code-map.cs directly.
• Network access on the first run so NuGet can restore Microsoft.CodeAnalysis.CSharp, which the analyzer uses for namespace analysis. Later runs work offline once the package is cached.
• Network access to cdn.jsdelivr.net for the browser preview to load Mermaid. The command still prints Mermaid source when the preview cannot be rendered.

Repository layout

.github/code-map/
  extension.mjs  # Copilot CLI extension entry point and canvas preview
  code-map.cs    # C# analyzer invoked by the extension
LICENSE          # MIT License
README.md
README.ja.md
SECURITY.md

Usage

Run the command from Copilot CLI in a repository or directory that contains a .NET solution:

/code-map [directory-or-solution] [max-projects] [max-edges]

Arguments:

Argument	Description	Default
directory-or-solution	A .sln or .slnx file, or a directory to search for solution files.	Current working directory
max-projects	Maximum number of projects shown in the diagram.	40
max-edges	Maximum number of project-reference edges shown in the diagram.	80

Examples:

/code-map
/code-map ./MyApp.sln
/code-map ./src 25 50

If a directory contains multiple solution files, the extension asks you to choose one when interactive UI is available. Without interactive UI, it uses the first discovered solution.

Output

The command reports:

• solution name and path
• project count
• project-reference count
• package-reference count
• test-project count
• project-kind summary
• dependency hub summary
• analyzed namespace count and namespace-dependency count
• circular dependencies, listed as project and namespace cycle groups
• notes and warnings

When a canvas is available, /code-map opens an interactive dependency map. Use the Projects/Namespaces toggle to switch granularity, and click a node to highlight connected references. Cycle nodes and edges stay highlighted in red. When a canvas is unavailable, the command logs Mermaid source inline.

Analyzer behavior

The C# analyzer:

• supports .sln and .slnx inputs
• detects solution folders and groups projects in Mermaid subgraphs
• recognizes test projects from common test packages, IsTestProject, and project naming conventions
• classifies projects as test, web, desktop, app, or library
• summarizes package references instead of drawing package nodes
• detects circular project dependencies and marks the nodes and edges involved
• derives namespace dependencies for C# projects from using directives (syntax only, no build), and detects namespace cycles
• warns about project references outside the selected solution
• warns when conditional ProjectReference items are detected
• truncates large diagrams based on max-projects and max-edges

Namespace analysis covers C# projects only. It reads *.cs files under each project (excluding bin/obj), so it includes namespaces that are referenced through using directives and may include unused usings. Cycle detection runs on the full dependency graph, so cycles are still reported even when the diagram is truncated.

Troubleshooting

Problem	What to check
dotnet execution fails	Confirm dotnet is installed, on PATH, and supports C# file-based apps.
No solution is found	Pass a .sln or .slnx file directly, or run from a directory containing one.
Invalid limit error	max-projects and max-edges must be positive integers.
Canvas does not open	The current Copilot CLI host may not support canvases; use the Mermaid output fallback.
Namespaces toggle is disabled	No namespace graph was produced. Namespace analysis only runs for C# (.csproj) projects.
First run is slow or fails offline	The first analyzer run restores Microsoft.CodeAnalysis.CSharp from NuGet. Run once with network access to cache it.
Browser preview cannot render	Check network access to cdn.jsdelivr.net; the local preview loads Mermaid from that CDN.
Some project references are missing	References outside the selected solution are summarized as warnings instead of being drawn as nodes.

Development

There is no package manifest in this repository. The extension is implemented as a single JavaScript module and a C# file-based analyzer.

Useful checks:

node --check .github\code-map\extension.mjs
dotnet .github\code-map\code-map.cs -- --output <output.json> --solution <solution.sln>

License

This project is licensed under the MIT License. See LICENSE.

Security

See SECURITY.md for supported versions and vulnerability reporting guidance.