# Dependency Map

> Generate dependency map diagram from project build files

- Skill: `microsoft/dependency-map` (Agent Skill)
- Install (CLI): `npx skillmds@latest add microsoft/dependency-map`
- Raw SKILL.md: https://api.skillmd.com/api/skills/microsoft/dependency-map/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Microsoft (https://skillmd.com/u/microsoft)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/microsoft/dependency-map

---


# Dependency Map

Analyze project build and package files to generate a visual map of all external dependencies grouped by functional category. Save to `.github/modernize/assessment/engines/facts/dependency-map.md`.

This skill focuses exclusively on **declared external dependencies** (libraries, frameworks, packages). For internal application structure and component relationships, see the `architecture-diagram` skill.

## Input Parameters

- `workspace-path` (optional): Path to the project to analyze (defaults to current directory)

## ⚠ Mermaid Safety Constraints — read BEFORE you write the ```mermaid block

Mermaid is unforgiving: one illegal character anywhere in the block crashes the **whole** diagram with `Syntax error in text`, not just the offending line. Stay strictly inside this subset:

1. **Chart kind.** `flowchart LR` only.
2. **Subgraph form.** Always `subgraph <AlphaNumId>["display label"]` (id matches `[A-Za-z][A-Za-z0-9_]*`, no spaces, no punctuation). NEVER use the anonymous form `subgraph "label"` — it crashes whenever the label contains `(`, `)`, `/`, `-`, etc.
3. **Node form.** Use `Id["label"]` for libraries; pick one shape per node — do not stack brackets.
4. **Arrow form.** Solid `-->`, dotted `-.->` for transitive/indirect. Arrow labels MUST be double-quoted: `-->|"persistence"|`. Never bare `-->|persistence|`.
5. **No line breaks in labels.** The escape `\n` was removed in modern Mermaid and is the #1 cause of failures. Keep labels on one line (e.g., `"Spring Boot 2.7.18"` not `"Spring Boot\n2.7.18"`).
6. **Banned characters inside any label or subgraph title.** Use the ASCII replacement:

   | Banned | Why it breaks | Replacement |
   |---|---|---|
   | `\n` (literal two chars) | escape removed | drop, or `<br/>` |
   | `—` (em-dash, U+2014) | parser treats as edge | `-` (ASCII hyphen) |
   | `–` (en-dash, U+2013) | parser treats as edge | `-` |
   | `{` `}` | opens an entity block | drop braces |
   | `"` inside a label | closes the label early | `'` (single quote) |
   | `\|` inside a label | breaks edge-label parser | rephrase |
   | `@` `#` `$` `%` `&` | unsafe | rephrase or drop |
   | `(` `)` outside `["..."]` | unbalanced parens crash | only inside the quoted label |
   | smart quotes `"` `"` `'` `'` | not ASCII | regular `"` and `'` |

7. **Unique node IDs across the whole diagram.** No two nodes/subgraphs may share an id.
8. **`subgraph` must be closed by a matching `end` on its own line.**

### Mandatory self-attestation

Immediately before writing the ` ```mermaid ` opening fence, emit this exact one-line HTML comment in the markdown (it does not render — it is for your own visible attestation):

```
<!-- mermaid-checked: no \n, no em-dash/en-dash, no {} in labels, subgraphs are id["label"], arrows are -->|"label"|, all subgraphs closed by end, ids unique -->
```

If you cannot truthfully emit that comment, fix the diagram first.

---

## Execution Steps

### Step 1: Generate Dependencies Section

Analyze build files and produce the complete `## Dependencies` section in one pass:

**Analysis — examine only build and package management files** (do NOT scan source code — that is the `architecture-diagram` skill's job):

- Java: pom.xml, build.gradle, settings.gradle, gradle.properties, gradle lockfiles
- .NET: *.csproj, Directory.Build.props, packages.config, Directory.Packages.props
- JavaScript/TypeScript: package.json, package-lock.json, yarn.lock, pnpm-lock.yaml

For each dependency extract:
- Group/package name and artifact name
- Declared version (or version range)
- Scope (compile, runtime, test, provided)

Also detect:
- Parent POM / BOM imports (Java)
- Central package management (.NET Directory.Packages.props)
- Transitive dependencies where visible from lock files or BOM

**Categorize** dependencies into functional groups:

| Category | Examples |
|----------|----------|
| Web Frameworks | Spring Web, ASP.NET Core MVC, JAX-RS |
| Database / ORM | Hibernate, Entity Framework, JDBC drivers |
| Messaging | Kafka client, RabbitMQ, Azure Service Bus |
| Caching | Redis, EhCache, MemoryCache |
| Logging | SLF4J, Log4j, Serilog, NLog |
| Security | Spring Security, Microsoft.Identity, OAuth libs |
| Observability | Micrometer, OpenTelemetry, Application Insights |
| Utilities | Guava, Apache Commons, Lombok, AutoMapper |

Rules:
- Exclude test-scoped dependencies (JUnit, xUnit, Mockito, etc.) from the main diagram and Dependency Summary table — they are not relevant for modernization planning
- If a dependency doesn't fit any category, put it under "Utilities"
- Collect test-scoped dependencies separately for the Test Dependencies section (Step 2)

**Diagram — Mermaid `flowchart LR`** (re-read the Safety Constraints above before writing):
- Application as the central left-side node
- One `subgraph` per functional category, using the `subgraph Id["display label"]` form
- Each dependency as a node showing name and version: `Lib["Library Name 1.2.3"]` (single line, no `\n`)
- Arrows from Application to each category subgraph
- If a BOM/parent POM manages versions, show it as a separate node linked to the dependencies it governs

Reference example (this block satisfies every Safety Constraint — match its shape):

<!-- mermaid-checked: no \n, no em-dash/en-dash, no {} in labels, subgraphs are id["label"], arrows are -->|"label"|, all subgraphs closed by end, ids unique -->
~~~mermaid
flowchart LR
    App["MyApplication"]

    subgraph Web["Web Frameworks"]
        SpringMVC["Spring MVC 5.3.x"]
        Thymeleaf["Thymeleaf 3.0"]
    end
    subgraph DB["Database / ORM"]
        Hibernate["Hibernate 5.6"]
        PgDriver["PostgreSQL Driver 42.6"]
    end
    subgraph Messaging["Messaging"]
        Kafka["Kafka Client 3.4"]
    end
    subgraph Cache["Caching"]
        Redis["Jedis 4.3"]
    end
    subgraph Log["Logging"]
        SLF4J["SLF4J 1.7"]
        Logback["Logback 1.2"]
    end
    subgraph Sec["Security"]
        SpringSec["Spring Security 5.7"]
    end
    subgraph Util["Utilities"]
        Lombok["Lombok 1.18"]
        Jackson["Jackson 2.14"]
    end

    App -->|"web"| Web
    App -->|"persistence"| DB
    App -->|"messaging"| Messaging
    App -->|"caching"| Cache
    App -->|"logging"| Log
    App -->|"security"| Sec
    App -->|"utilities"| Util
    SLF4J -.->|"implementation"| Logback
~~~

**Textual explanations (write immediately after the diagram):**
- **Dependency Summary table**: Category | Count | Key Libraries | Notes (e.g., Web Frameworks | 2 | ASP.NET MVC 5.2.7, Razor 3.2.7 | Legacy MVC stack on .NET Framework)
- **Version & Compatibility Risks**: A short paragraph highlighting dependencies that are outdated, end-of-life, or have known migration concerns (e.g., ".NET Framework 4.7.2 is in maintenance mode; Entity Framework 6 has a migration path to EF Core")
- **Notable Observations**: 2-4 bullet points on anything noteworthy — duplicate functionality across libraries, deprecated packages, security-sensitive dependencies, or unusually large transitive trees

### Step 2: Generate Test Dependencies Section

Collect all test-scoped dependencies (excluded from the main diagram) and produce the complete `## Test Dependencies` section:

- List detected test frameworks and supporting libraries with their versions (e.g., JUnit 5, Mockito, AssertJ, Testcontainers, xUnit, Jest)
- Report the total number of test-scope dependencies
- Note any test infrastructure concerns (e.g., outdated test framework version, missing contract-testing library, no integration test framework detected)

### Step 3: Save Output

Save to `.github/modernize/assessment/engines/facts/dependency-map.md` with this exact structure:

```
# Dependency Map

A brief introduction (1-2 sentences) stating project name and total dependency count.

## Dependencies

< Mermaid flowchart LR here >

### Dependency Summary

[Table: Category | Count | Key Libraries | Notes]

### Version & Compatibility Risks

[Short paragraph on outdated or end-of-life dependencies]

### Notable Observations

[2-4 bullet points on noteworthy findings]

## Test Dependencies

[Table: Framework | Version | Notes]

Total test-scope dependencies: N
[1-2 sentences on test infrastructure observations, or "No test dependencies detected."]
```

## Scaling Rules

- If the project has **more than 50 declared dependencies**, collapse minor utilities into a single aggregate node (e.g., `Utils["12 utility libraries"]`) and only show individually the top dependencies by importance
- Keep the diagram under **40 nodes** to ensure readability and GitHub rendering compatibility
- For multi-module projects (e.g., multi-module Maven/Gradle, multi-project .sln), show shared dependencies once and module-specific dependencies grouped by module

## Common failure patterns observed in past runs

Each row below is something the model actually produced that crashed the diagram. Use the ✅ form.

| ❌ Past mistake | ✅ Safe form | Why the ❌ crashed |
|---|---|---|
| `subgraph "Database / ORM"` | `subgraph DB["Database / ORM"]` | Anonymous subgraph + `/` in title |
| `Spring["Spring Boot\n2.5.12"]` | `Spring["Spring Boot 2.5.12"]` | Literal `\n` |
| `App -->\|persistence\| DB` | `App -->\|"persistence"\| DB` | Bare arrow label |
| `Lib["Spring Boot — 2.5"]` | `Lib["Spring Boot - 2.5"]` | em-dash inside label |
| `Lib["foo {bar}"]` | `Lib["foo bar"]` | `{}` inside label |

## Error Handling

- **Unsupported project type**: Output a single line: `> ERROR: Unsupported project type. This skill supports Java, .NET, JavaScript, and TypeScript projects only.`
- **No build files found**: Output: `> ERROR: No recognized build files found at workspace-path. Verify the path is correct.`
- **Incomplete dependency info**: Generate a best-effort diagram from available data. Add a note inside the diagram: `Note["Some dependencies could not be fully resolved"]`

## Success Criteria

- Mermaid diagram renders correctly with dependencies grouped by functional category
- Each dependency shows name and version
- Dependency Summary table lists categories with counts and key libraries
- Version & Compatibility Risks paragraph highlights outdated or end-of-life dependencies
- Notable Observations lists 2-4 noteworthy findings
- Test Dependencies section lists detected test frameworks with versions and total count
- The ```mermaid block is preceded by the `<!-- mermaid-checked: ... -->` attestation comment
- File saved to `.github/modernize/assessment/engines/facts/dependency-map.md`