Skip to main content
Glama
README.md
# depmap

A monorepo is easy to lose track of: which packages actually
depend on which other packages in the set, what sits at the
top with nothing depending on it, what sits at the bottom
depending on nothing internal, and whether the internal
graph loops back on itself. depmap takes the package graph —
every package's name and the names it depends on — and draws
the whole map:

- **Per-package entries** — for every package, its internal
  dependencies (`depends_on`), the packages that depend on
  it (`depended_by`), and `external_count`: how many of its
  dependency names point outside the set. External names are
  counted, never mapped, and never an error — a package may
  freely depend on libraries the monorepo does not contain.
- **Edges, roots, and leaves** — every internal dependency
  as a `{from, to}` edge, the roots (packages nothing
  internal depends on), and the leaves (packages with no
  internal dependencies).
- **Cycles, two ways** — `cyclic_packages` lists every
  package that lies on any cycle: members of a strongly
  connected component of more than one package, plus any
  package that depends on itself. Alongside it, `cycle`
  reports one concrete cycle, found by a depth-first search
  that visits names and dependencies in ascending order. A
  cycle is a finding, not an error.
- **A Mermaid graph** — the map rendered as a `graph TD`
  diagram you can paste into any Mermaid renderer. Package
  names that are not valid Mermaid ids get a sanitised id
  (`@scope/app` becomes `_scope_app`) with a declaration
  line tying the id back to the real name.

Duplicate entries in one package's `dependencies` are
de-duplicated before mapping, and every list in the result
is sorted ascending, so the same graph always yields
exactly the same map. Malformed input — a missing or empty
package list, a missing or duplicate package name, a
wrongly typed field — is a validation error naming the
offending path (for example
`packages[1].dependencies[0] must be a string`), and no
partial map is produced. The computation is pure and
local: no network, no configuration, no files read beyond
the input you pass in.

## CLI

```bash
npx @reneturcios/depmap map --input args.json
npx @reneturcios/depmap --version
```

`args.json` contains the full arguments object:

```json
{
  "packages": [
    { "name": "core" },
    { "name": "lib", "dependencies": ["core"] },
    { "name": "app", "dependencies": ["lib", "react"] }
  ]
}
```

`dependencies` defaults to `[]` per package; here `react`
is external to the set, so it appears only in `app`'s
`external_count`. The map is printed as JSON:

```json
{
  "packages": [
    { "name": "app", "depends_on": ["lib"], "depended_by": [], "external_count": 1 },
    { "name": "core", "depends_on": [], "depended_by": ["lib"], "external_count": 0 },
    { "name": "lib", "depends_on": ["core"], "depended_by": ["app"], "external_count": 0 }
  ],
  "edges": [
    { "from": "app", "to": "lib" },
    { "from": "lib", "to": "core" }
  ],
  "roots": ["app"],
  "leaves": ["core"],
  "has_cycle": false,
  "cycle": [],
  "cyclic_packages": [],
  "mermaid": "graph TD\n  app --> lib\n  lib --> core"
}
```

Exit codes: `0` on success, `1` on a runtime error (including
an unreadable or invalid input file, or invalid input), `2`
on a usage error.

## MCP server

```bash
npx -y @reneturcios/depmap mcp
```

MCP client config:

```json
{
  "mcpServers": {
    "depmap": {
      "command": "npx",
      "args": ["-y", "@reneturcios/depmap", "mcp"]
    }
  }
}
```

### Tools

- `map_internal_dependencies` — Map a monorepo's internal
  dependencies.
  - `packages` (array, required, at least one) — packages as
    `{name, dependencies?}` objects; `name` is unique across
    the set, and each `dependencies` entry either names
    another supplied package (internal) or anything else
    (external, counted only)

  Returns `{packages, edges, roots, leaves, has_cycle, cycle,
  cyclic_packages, mermaid}`.

## Docker

```bash
docker run -i ghcr.io/cloudcorprecords/depmap
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/depmap map --input /w/args.json
```

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source
```

## License

MIT — Copyright (c) 2026 Rene Turcios