Metadata-Version: 2.4
Name: devmap
Version: 0.3.6
Summary: Map your machine's dev environment and surface issues (PATH conflicts, ghost binaries, multi-version collisions). fastfetch-for-dev-tools. This PyPI package ships the real devmap CLI (a bundled JavaScript app launched via Node.js or Bun), so `pip install devmap && devmap` works standalone.
Author: devmap contributors
License: MIT
Project-URL: Homepage, https://github.com/StevenLOL/devmap
Project-URL: Repository, https://github.com/StevenLOL/devmap
Keywords: devmap,devtools,environment,scanner,fastfetch,diagnostics,dev-environment,path-conflict,ghost-binary
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# devmap

> A source-of-truth scanner and governance layer for your machine's development environment. One command maps the whole dev setup, draws the PATH-conflict graph, and surfaces ghost binaries and multi-version collisions.

`devmap` is the developer-focused spiritual successor to `fastfetch`: instead of only printing system specs, it scans the *development* surface of your machine — runtimes, package managers, IDEs, per-interpreter pip packages, conda/WSL/Docker environments, Visual Studio dev shells, and project-local virtual environments — and produces a single machine-readable manifest plus an actionable issue list.

## Install

This PyPI package ships the **real devmap CLI**. It bundles the compiled devmap app and launches it via **Node.js** (or **Bun**, if present), so it works standalone — no need to install from npm or build from source:

```bash
pip install devmap
devmap scan
```

Requirements at runtime: a Node.js (or Bun) runtime available on `PATH`. Python itself is only used as the installer/launcher wrapper.

## Features

- **One-command full scan** of the dev environment (runtimes, package managers, IDEs, and the environment layers below).
- **PATH conflict graph**: detects multi-version tools, shadowed binaries, and ghost/broken symlinks (e.g. Windows App Execution Aliases that look broken but aren't).
- **Off-PATH awareness**: reports installed-but-not-on-PATH tools, while correctly treating version-manager environments (conda envs, nvm versions) as by-design off-PATH.
- **Environment layers**: vcpkg packages, per-python pip packages (incl. upgradable), apt packages (Linux), conda environments, Docker (binary + daemon + images/containers), WSL distros, Visual Studio dev shells, and project-local environments (`.venv`, `node_modules`).
- **Dependency auditing (optional)**: with `--audit-deps`, devmap detects and invokes installed SCA tools (osv-scanner, govulncheck, pip-audit, Trivy), parses their JSON, and merges results into a unified view. devmap is a *scanner/orchestrator*, not a CVE database — for authoritative vulnerability data, use those tools directly.
- **Health layer**: converges official self-checks into one view — `pip check` (broken dependency requirements, **offline by default**) and, with `--health-network`, `npm doctor` / `rustup check`. Unavailable or offline probes degrade gracefully to `info`.
- **Three sub-commands**: `scan` (the fact source), `query` (ask the manifest), `devdiff` (compare two manifests — environment drift / cross-machine consistency).
- **Zero Python dependencies.** The bundled app is pure TypeScript compiled to JavaScript.

## Usage

```bash
devmap scan                        # pretty-print to terminal, write ~/.devmap/devmap.json
devmap scan --json                # machine-readable JSON (devmap.json schema) to stdout
devmap scan --report              # full markdown report
devmap scan --scan-root C:\src     # also scan project-local envs under a root (comma-separated for many)
devmap scan --wsl-deep            # also wake stopped WSL distros and probe their tools (slower)
devmap scan --outdated            # hit PyPI to list upgradable pip/conda packages (slower, needs network)
devmap scan --ci                  # exit code 1 if any error-severity issue is found
devmap scan --audit-deps          # invoke installed SCA tools and merge CVE findings
```

Key `scan` flags:

| Flag | Description |
|------|-------------|
| `--json` | Emit machine-readable JSON (the `devmap.json` schema) to stdout. |
| `--report` | Emit a full markdown report. |
| `--no-manifest` | Do not persist the manifest to disk. |
| `--manifest <path>` | Read/write the manifest at a custom path (default `~/.devmap/devmap.json`). |
| `--disable <r1,r2>` | Disable check rules by ID prefix (e.g. `path.duplicate`, `pip.outdated`). |
| `--scan-root <dir>` | Root(s) to scan for project-local environments (comma-separated). Default: cwd. |
| `--outdated` | Network check for upgradable pip/conda packages (off by default). |
| `--wsl-deep` | Probe inside stopped WSL distros (off by default to avoid waking them). |
| `--audit-deps` | Invoke installed SCA tools and merge CVE findings into the report. |
| `--ci` | Exit non-zero on any error-severity issue. |
| `--quiet` | Suppress the live scan progress feedback (for scripts/CI). |
| `--bom` | Prefix output with a UTF-8 BOM so Notepad-like viewers render it correctly (stdout redirect/pipe only). |

### `query` — ask the manifest

```bash
devmap query                       # everything
devmap query node                 # tools whose id contains "node"
devmap query runtime.node         # dot-form category.tool selector (runtime / pkg / ide)
devmap query --issues             # only issues
devmap query --conflicts          # only conflicts (multiVersion / path / ghost)
devmap query --off-path           # only off-PATH installs
devmap query --kind runtime       # filter by category
devmap query --where conda        # filter by install path substring
```

### `devdiff` — compare two manifests

```bash
devmap devdiff                    # stored manifest  vs  current live scan
devmap devdiff <file>             # stored/before    vs  <file>
devmap devdiff <a> <b>            # compare two manifest files
```

Reports added/removed installs, version changes, and issues added/resolved.

## Output

- The default `scan` writes the manifest to **`~/.devmap/devmap.json`** (pure UTF-8, no BOM — directly parseable by Bun/Node/Python/jq).
- Use `query` / `devdiff` against a stored manifest without re-scanning.

## Repository

https://github.com/StevenLOL/devmap

## License

[MIT](https://github.com/StevenLOL/devmap/blob/main/LICENSE)
