Stack Atlas

Map every package, SDK, external API, and config dependency in your project — in one report.

@adhix11/stack-atlas is a developer-friendly project intelligence CLI. It doesn't just look for errors — it builds a map of what your project actually depends on: installed packages, where each one is used, external SDKs, the external APIs your code talks to, lockfile/package-manager conflicts, and heavy dependencies with lighter alternatives.

It runs with zero runtime dependencies, works offline, and produces both a human-readable terminal report and a machine-readable JSON report.

The problem it solves

Real projects accumulate dependencies, and teams slowly lose track:

npm install aws-sdk firebase axios moment lodash @mui/material

Months later nobody can answer:

• Is aws-sdk still used? Are we using the full SDK or only S3?
• Where is Firebase actually used?
• Which external APIs does this codebase call?
• Which packages look unused?
• Are npm / yarn / pnpm lockfiles mixed?
• Why is the bundle heavy?

Tools like depcheck, knip, npm-check-updates, and madge each solve a slice of this. Stack Atlas combines the practical report a developer or team lead actually wants into one "project atlas" — not just one check.

Features

• Dependency inventory — every prod/dev/peer/optional dependency, with declared and installed versions (read from package-lock.json when present).
• Usage mapping — detects import, require, dynamic import(), and re-exports across .js/.jsx/.ts/.tsx/.mjs/.cjs/.vue/.svelte files and tells you where each package is used.
• Smart status classification — used, possibly-unused, config-used, cli-used, and types, so packages used only in config files or npm scripts aren't wrongly flagged.
• SDK intelligence — recognizes AWS, Firebase, Stripe, Razorpay, OpenAI, Twilio, SendGrid, Microsoft Graph, Supabase, Sentry, and more.
• AWS modular suggestion — detects that you only use, say, S3 from the full aws-sdk and recommends @aws-sdk/client-s3 to shrink install/build size.
• External API map — extracts http(s) endpoints from source, .env*, and YAML files, classifies them (Payment / AI / Cloud / Maps / Email / SMS / Internal), and lists locations.
• Heavy-package guidance — flags moment, full lodash, aws-sdk, etc., with lighter alternatives.
• Import-style analysis — distinguishes barrel imports (import _ from 'lodash') from tree-shakeable path imports (lodash/get, @mui/material/Button) and advises accordingly.
• Lockfile / package-manager report — detects npm/yarn/pnpm/bun and warns on multiple lockfiles that can cause divergent dependency trees across machines and CI.
• Duplicate / conflict detection — finds packages installed at multiple versions from the lockfile tree.
• Missing-dependency detection — flags packages imported in source but absent from package.json (ignoring Node builtins and path aliases).
• Outdated check (opt-in --outdated) — queries the npm registry and reports major/minor/patch updates. Off by default, fails gracefully when offline.
• Three outputs — colored terminal report, stack-atlas-report.json, and a self-contained stack-atlas-report.html with a Print / Save-PDF button and print-optimized styling.
• Zero runtime dependencies; offline by default.

Installation

You don't need to install anything — just run it with npx:

npx @adhix11/stack-atlas

Or add it to a project / install globally:

npm install --save-dev @adhix11/stack-atlas
# or
npm install --global @adhix11/stack-atlas

Requires Node.js >= 16.

Usage

Run it from your project root:

npx @adhix11/stack-atlas                 # curated overview (summary + SDKs + APIs + unused)
npx @adhix11/stack-atlas ./path/to/app   # analyze a specific directory
npx @adhix11/stack-atlas --all           # every section + write JSON report
npx @adhix11/stack-atlas --json          # write stack-atlas-report.json

CLI options

| Option | Description | | ------------------- | ------------------------------------------------------------------ | | [path] | Project directory to analyze (defaults to the current directory). | | --all | Show every section and write the JSON report. | | --deps | Show the full dependency / package usage map. | | --sdk | Show only the SDK intelligence report. | | --api-map | Show only the external API map. | | --json | Write a machine-readable stack-atlas-report.json. | | --html | Write a self-contained stack-atlas-report.html. | | --outdated | Check the npm registry for newer versions (network; opt-in). | | --manager <name> | Force the package manager (npm | yarn | pnpm | bun). | | -h, --help | Show help. | | -v, --version | Show the version. |

Set the NO_COLOR environment variable to disable ANSI colors.

Example output

Stack Atlas Report

Project Summary
───────────────
  Project:         sample-app
  Project type:    React + Vite
  Package manager: npm  (package-lock.json, yarn.lock)
  Files scanned:   3
  Dependencies:    10 total
    4 used, 3 possibly unused, 0 config, 2 cli, 1 types
  SDKs detected:   3    Heavy packages: 3
  External APIs:   3    Internal APIs: 1
  Missing deps:    0    Version conflicts: 0
  Warnings:        1

SDK Intelligence
────────────────
  AWS SDK (v2, full) (aws-sdk)  [used]
    used in: src/s3.service.js
    ➜ Only S3 usage detected. Replace the full aws-sdk with modular
      package(s): @aws-sdk/client-s3 to reduce install/build size.
  Firebase (firebase)  [used]
    used in: src/firebase.js

External API Map
────────────────
  api.openai.com  [AI API]
    .env.example: OPENAI_BASE_URL
    src/ai.service.js
  api.razorpay.com  [Payment API]
    .env.example: RAZORPAY_BASE_URL

Warnings & Conflicts
────────────────────
  ! Multiple lockfiles found (package-lock.json, yarn.lock). This can cause
    different dependency trees across developers and CI/CD. Use one package manager.

JSON report written to stack-atlas-report.json

Want to see it live? Clone the repo and run npm run demo against the bundled examples/sample-app fixture.

Report sections

| Section | What it tells you | | ---------------------- | ----------------------------------------------------------------------- | | Project Summary | Project name, framework/ecosystem, package manager, and headline counts.| | Package Usage Map | Every dependency with its status, version, type, and the files using it.| | Possibly Unused | Declared dependencies with no detected usage (review manually). | | SDK Intelligence | Recognized SDKs, where they're used, and modular/tree-shaking advice. | | External API Map | External & internal endpoints, classified, with their locations. | | Missing Dependencies | Packages imported in source but not declared in package.json. | | Version Conflicts | Packages installed at multiple versions (duplication / conflict risk). | | Outdated Packages | Newer registry versions, tagged major/minor/patch (with --outdated). | | Warnings & Conflicts | Multiple lockfiles and other reproducibility risks. |

Status taxonomy

Stack Atlas avoids the naive "used vs unused" split, because packages are often used indirectly (config, scripts, dynamic imports). Each dependency gets one status:

| Status | Meaning | | ----------------- | ----------------------------------------------------------------------- | | used | Imported / required in application source code. | | config-used | Imported only in a config file (vite, webpack, jest, eslint, …). | | cli-used | Referenced only in an npm script (e.g. vite build, jest). | | types | A @types/* package (used implicitly by the TypeScript compiler). | | possibly-unused | Declared but no usage detected anywhere — a candidate for removal. |

JSON report

--json / --all write stack-atlas-report.json to the project root. Top-level shape:

{
  "tool": "stack-atlas",
  "generatedAt": "2026-06-29T00:00:00.000Z",
  "root": "/abs/path/to/project",
  "project": { "name", "type", "frameworks": [], "ecosystems": [] },
  "packageManager": { "primary", "managers": [], "lockfiles": [], "multipleLockfiles" },
  "summary": { "totalDependencies", "used", "possiblyUnused", "configUsed", "cliUsed",
               "types", "sdks", "heavy", "externalApis", "internalApis",
               "missing", "conflicts", "warnings" },
  "packages": [ { "name", "type", "declared", "installed", "status", "locations" } ],
  "missing":  [ { "name", "locations": [] } ],
  "sdks":     [ { "package", "name", "category", "status", "usedIn", "recommendation" } ],
  "heavy":    [ { "package", "installed", "note", "status", "barrelImport" } ],
  "apis":     { "external": [ { "host", "type", "locations" } ], "internal": [ ... ] },
  "conflicts": [ { "name", "versions": [] } ],
  "outdated": { "checked", "offline", "outdated": [ { "name", "current", "latest", "type" } ] },
  "warnings": [ "..." ]
}

This is ideal for CI dashboards, audits, and project-handover documentation. The outdated field is present only when --outdated is passed.

HTML report

--html renders the same data as a styled, self-contained stack-atlas-report.html — no external CSS, fonts, or scripts, so you can open it anywhere or commit it as an artifact. It includes a Print / Save PDF button; the print stylesheet automatically switches to a light, ink-friendly theme and hides the button so you get a clean PDF for audits or handovers.

npx @adhix11/stack-atlas --html            # writes stack-atlas-report.html
npx @adhix11/stack-atlas --all --html      # full report + JSON + HTML

Programmatic API

Stack Atlas can be used as a library:

const { analyze } = require('@adhix11/stack-atlas');

const report = analyze(process.cwd(), { manager: 'npm' });
console.log(report.summary);
console.log(report.apis.external);

analyze(root, options) returns the same object that is serialized to the JSON report.

How it works

Stack Atlas is split into two layers so it stays honest about what it can detect:

Layer 1 — Universal manifest awareness. It recognizes the ecosystem from manifest files (package.json, requirements.txt, pyproject.toml, pom.xml, build.gradle, go.mod, Cargo.toml, composer.json, pubspec.yaml, Gemfile) and the package manager from lockfiles (package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb/bun.lock, plus the corepack packageManager field).

Layer 2 — Deep usage analysis (Node / JS / TS today). It walks your source tree (skipping node_modules, build output, and dotfolders), extracts module specifiers, maps them back to declared dependencies, scans .env*/YAML for endpoints, and matches packages against a curated SDK catalog.

Ecosystem support

| Layer | Ecosystems | | ----------------------------- | ----------------------------------------------------------------- | | Deep usage + API + SDK | JavaScript, TypeScript, React, Next.js, Node, Express, NestJS, LoopBack, Vue, Svelte | | Manifest / package-manager | Python, Java, Go, Rust, PHP, Dart/Flutter, Ruby (detected & reported) |

Limitations

• Usage detection is static and regex-based. Packages loaded through unusual dynamic patterns, string concatenation, or non-JS config may show as possibly-unused — always review before removing.
• Installed versions and duplicate-version conflicts are read from package-lock.json only; other lockfiles are detected but not deeply parsed yet.
• --outdated is the only feature that makes network calls; everything else runs fully offline. When the registry is unreachable, the outdated section is skipped gracefully.

Roadmap

• [x] HTML report (--html)
• [x] Outdated / latest-version checking via the npm registry (--outdated)
• [x] Duplicate-version conflict detection
• [x] Missing-dependency detection
• [ ] Peer-dependency mismatch detection
• [ ] Deep parsing of yarn.lock / pnpm-lock.yaml / bun.lock
• [ ] Deep usage analysis for Python, Go, and PHP
• [ ] --ci mode with a non-zero exit code on policy violations

Contributing

Issues and PRs are welcome.

git clone https://github.com/adhix11/stack-atlas.git
cd stack-atlas
npm test          # run the test suite (node --test)
npm run demo      # run against the bundled example app

License

MIT © adhix11