{"_id":"@adhix11/stack-atlas","_rev":"2-ac97a34d4a2909c1705ac75575d2fb9b","name":"@adhix11/stack-atlas","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@adhix11/stack-atlas","version":"1.0.0","keywords":["dependencies","dependency-graph","dependency-analysis","sdk","api","external-api","lockfile","audit","cli","intelligence","atlas","unused-dependencies","depcheck","aws-sdk"],"author":{"name":"adhix11"},"license":"MIT","_id":"@adhix11/stack-atlas@1.0.0","maintainers":[{"name":"adhix11","email":"adhix11@gmail.com"}],"homepage":"https://github.com/adhix11/stack-atlas#readme","bugs":{"url":"https://github.com/adhix11/stack-atlas/issues"},"bin":{"stack-atlas":"bin/stack-atlas.js"},"dist":{"shasum":"0984245cb99d1deabb975c8dc97219082df4a3a5","tarball":"https://registry.npmjs.org/@adhix11/stack-atlas/-/stack-atlas-1.0.0.tgz","fileCount":20,"integrity":"sha512-9OM1HTrbMYlB+Hyz0CLQy/XN+yBTlc2JFRRWvJJiKgwt1MMnar7dJzOMOK1l76ZTrRwnJ5q8P26eIFHFXMWR5w==","signatures":[{"sig":"MEYCIQD3Do5PW5cPdRp+d1IvPCzDFuqRt3/7odTPx829IK46ZQIhAOp7fFHygpf31NrbZckS/1DN/2sGZaoxc5fdH4a+WF6L","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":72142},"main":"src/index.js","engines":{"node":">=16"},"scripts":{"demo":"node bin/stack-atlas.js examples/sample-app --all","test":"node --test","start":"node bin/stack-atlas.js","prepublishOnly":"npm test"},"_npmUser":{"name":"adhix11","email":"adhix11@gmail.com"},"repository":{"url":"git+https://github.com/adhix11/stack-atlas.git","type":"git"},"_npmVersion":"11.6.2","description":"A developer-friendly project intelligence CLI that maps packages, SDKs, external APIs, lockfiles, and dependency risks across your application.","directories":{},"_nodeVersion":"22.19.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/stack-atlas_1.0.0_1782743800781_0.9470981119964434","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@adhix11/stack-atlas","version":"1.1.0","description":"A developer-friendly project intelligence CLI that maps packages, SDKs, external APIs, lockfiles, and dependency risks across your application.","bin":{"stack-atlas":"bin/stack-atlas.js"},"main":"src/index.js","scripts":{"start":"node bin/stack-atlas.js","test":"node --test","demo":"node bin/stack-atlas.js examples/sample-app --all","prepublishOnly":"npm test"},"keywords":["dependencies","dependency-graph","dependency-analysis","sdk","api","external-api","lockfile","audit","cli","intelligence","atlas","unused-dependencies","depcheck","aws-sdk"],"author":{"name":"adhix11"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/adhix11/stack-atlas.git"},"bugs":{"url":"https://github.com/adhix11/stack-atlas/issues"},"homepage":"https://github.com/adhix11/stack-atlas#readme","publishConfig":{"access":"public"},"engines":{"node":">=16"},"_id":"@adhix11/stack-atlas@1.1.0","_nodeVersion":"22.19.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-GGxtU9V8FklHZRxRo4phVpQhLAsRkSqoELrTI8UIP0yOnv+T5XdDGk2+JT702vA1nCeVsa02+yYONsrlxCWw8Q==","shasum":"3d1188ba0cc69485021668e14b1aa007ed10dfac","tarball":"https://registry.npmjs.org/@adhix11/stack-atlas/-/stack-atlas-1.1.0.tgz","fileCount":20,"unpackedSize":76158,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCrEsT5EyA1M/1+2ADWGVv0k85ElOWr2X4Pu0etu6bztAIhAKUnpovw1xJIskHX0Xfz/AFRUioRMw9itvq0kETLcm3t"}]},"_npmUser":{"name":"adhix11","email":"adhix11@gmail.com"},"directories":{},"maintainers":[{"name":"adhix11","email":"adhix11@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/stack-atlas_1.1.0_1782745623932_0.6545169625574889"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-29T14:36:40.618Z","modified":"2026-06-29T15:07:04.176Z","1.0.0":"2026-06-29T14:36:40.923Z","1.1.0":"2026-06-29T15:07:04.053Z"},"bugs":{"url":"https://github.com/adhix11/stack-atlas/issues"},"author":{"name":"adhix11"},"license":"MIT","homepage":"https://github.com/adhix11/stack-atlas#readme","keywords":["dependencies","dependency-graph","dependency-analysis","sdk","api","external-api","lockfile","audit","cli","intelligence","atlas","unused-dependencies","depcheck","aws-sdk"],"repository":{"type":"git","url":"git+https://github.com/adhix11/stack-atlas.git"},"description":"A developer-friendly project intelligence CLI that maps packages, SDKs, external APIs, lockfiles, and dependency risks across your application.","maintainers":[{"name":"adhix11","email":"adhix11@gmail.com"}],"readme":"# Stack Atlas\n\n> Map every package, SDK, external API, and config dependency in your project — in one report.\n\n[![npm version](https://img.shields.io/npm/v/@adhix11/stack-atlas.svg)](https://www.npmjs.com/package/@adhix11/stack-atlas)\n[![node](https://img.shields.io/node/v/@adhix11/stack-atlas.svg)](https://nodejs.org)\n[![license](https://img.shields.io/npm/l/@adhix11/stack-atlas.svg)](./LICENSE)\n\n`@adhix11/stack-atlas` is a developer-friendly **project intelligence CLI**. It doesn't just\nlook for errors — it builds a *map* of what your project actually depends on: installed\npackages, where each one is used, external SDKs, the external APIs your code talks to,\nlockfile/package-manager conflicts, and heavy dependencies with lighter alternatives.\n\nIt runs with **zero runtime dependencies**, works **offline**, and produces both a\nhuman-readable terminal report and a machine-readable JSON report.\n\n---\n\n## The problem it solves\n\nReal projects accumulate dependencies, and teams slowly lose track:\n\n```bash\nnpm install aws-sdk firebase axios moment lodash @mui/material\n```\n\nMonths later nobody can answer:\n\n- Is `aws-sdk` still used? Are we using the full SDK or only S3?\n- Where is Firebase actually used?\n- Which external APIs does this codebase call?\n- Which packages look unused?\n- Are `npm` / `yarn` / `pnpm` lockfiles mixed?\n- Why is the bundle heavy?\n\nTools like `depcheck`, `knip`, `npm-check-updates`, and `madge` each solve a *slice* of this.\n**Stack Atlas combines the practical report a developer or team lead actually wants into one\n\"project atlas\" — not just one check.**\n\n---\n\n## Features\n\n- **Dependency inventory** — every prod/dev/peer/optional dependency, with declared and\n  installed versions (read from `package-lock.json` when present).\n- **Usage mapping** — detects `import`, `require`, dynamic `import()`, and re-exports across\n  `.js/.jsx/.ts/.tsx/.mjs/.cjs/.vue/.svelte` files and tells you *where* each package is used.\n- **Smart status classification** — `used`, `possibly-unused`, `config-used`, `cli-used`,\n  and `types`, so packages used only in config files or npm scripts aren't wrongly flagged.\n- **SDK intelligence** — recognizes AWS, Firebase, Stripe, Razorpay, OpenAI, Twilio,\n  SendGrid, Microsoft Graph, Supabase, Sentry, and more.\n- **AWS modular suggestion** — detects that you only use, say, S3 from the full `aws-sdk`\n  and recommends `@aws-sdk/client-s3` to shrink install/build size.\n- **External API map** — extracts `http(s)` endpoints from source, `.env*`, and YAML files,\n  classifies them (Payment / AI / Cloud / Maps / Email / SMS / Internal), and lists locations.\n- **Heavy-package guidance** — flags `moment`, full `lodash`, `aws-sdk`, etc., with\n  lighter alternatives.\n- **Import-style analysis** — distinguishes barrel imports (`import _ from 'lodash'`) from\n  tree-shakeable path imports (`lodash/get`, `@mui/material/Button`) and advises accordingly.\n- **Lockfile / package-manager report** — detects npm/yarn/pnpm/bun and warns on multiple\n  lockfiles that can cause divergent dependency trees across machines and CI.\n- **Duplicate / conflict detection** — finds packages installed at multiple versions from the\n  lockfile tree.\n- **Missing-dependency detection** — flags packages imported in source but absent from\n  `package.json` (ignoring Node builtins and path aliases).\n- **Outdated check** (opt-in `--outdated`) — queries the npm registry and reports\n  major/minor/patch updates. Off by default, fails gracefully when offline.\n- **Three outputs** — colored terminal report, `stack-atlas-report.json`, and a\n  self-contained `stack-atlas-report.html` with a **Print / Save-PDF** button and\n  print-optimized styling.\n- **Zero runtime dependencies; offline by default.**\n\n---\n\n## Installation\n\nYou don't need to install anything — just run it with `npx`:\n\n```bash\nnpx @adhix11/stack-atlas\n```\n\nOr add it to a project / install globally:\n\n```bash\nnpm install --save-dev @adhix11/stack-atlas\n# or\nnpm install --global @adhix11/stack-atlas\n```\n\nRequires **Node.js >= 16**.\n\n---\n\n## Usage\n\nRun it from your project root:\n\n```bash\nnpx @adhix11/stack-atlas                 # curated overview (summary + SDKs + APIs + unused)\nnpx @adhix11/stack-atlas ./path/to/app   # analyze a specific directory\nnpx @adhix11/stack-atlas --all           # every section + write JSON report\nnpx @adhix11/stack-atlas --json          # write stack-atlas-report.json\n```\n\n### CLI options\n\n| Option              | Description                                                        |\n| ------------------- | ------------------------------------------------------------------ |\n| `[path]`            | Project directory to analyze (defaults to the current directory).  |\n| `--all`             | Show every section **and** write the JSON report.                  |\n| `--deps`            | Show the full dependency / package usage map.                      |\n| `--sdk`             | Show only the SDK intelligence report.                             |\n| `--api-map`         | Show only the external API map.                                    |\n| `--json`            | Write a machine-readable `stack-atlas-report.json`.                |\n| `--html`            | Write a self-contained `stack-atlas-report.html`.                  |\n| `--outdated`        | Check the npm registry for newer versions (network; opt-in).       |\n| `--manager <name>`  | Force the package manager (`npm` \\| `yarn` \\| `pnpm` \\| `bun`).    |\n| `-h`, `--help`      | Show help.                                                         |\n| `-v`, `--version`   | Show the version.                                                  |\n\n> Set the `NO_COLOR` environment variable to disable ANSI colors.\n\n---\n\n## Example output\n\n```text\nStack Atlas Report\n\nProject Summary\n───────────────\n  Project:         sample-app\n  Project type:    React + Vite\n  Package manager: npm  (package-lock.json, yarn.lock)\n  Files scanned:   3\n  Dependencies:    10 total\n    4 used, 3 possibly unused, 0 config, 2 cli, 1 types\n  SDKs detected:   3    Heavy packages: 3\n  External APIs:   3    Internal APIs: 1\n  Missing deps:    0    Version conflicts: 0\n  Warnings:        1\n\nSDK Intelligence\n────────────────\n  AWS SDK (v2, full) (aws-sdk)  [used]\n    used in: src/s3.service.js\n    ➜ Only S3 usage detected. Replace the full aws-sdk with modular\n      package(s): @aws-sdk/client-s3 to reduce install/build size.\n  Firebase (firebase)  [used]\n    used in: src/firebase.js\n\nExternal API Map\n────────────────\n  api.openai.com  [AI API]\n    .env.example: OPENAI_BASE_URL\n    src/ai.service.js\n  api.razorpay.com  [Payment API]\n    .env.example: RAZORPAY_BASE_URL\n\nWarnings & Conflicts\n────────────────────\n  ! Multiple lockfiles found (package-lock.json, yarn.lock). This can cause\n    different dependency trees across developers and CI/CD. Use one package manager.\n\nJSON report written to stack-atlas-report.json\n```\n\n> Want to see it live? Clone the repo and run `npm run demo` against the bundled\n> `examples/sample-app` fixture.\n\n---\n\n## Report sections\n\n| Section                | What it tells you                                                       |\n| ---------------------- | ----------------------------------------------------------------------- |\n| **Project Summary**    | Project name, framework/ecosystem, package manager, and headline counts.|\n| **Package Usage Map**  | Every dependency with its status, version, type, and the files using it.|\n| **Possibly Unused**    | Declared dependencies with no detected usage (review manually).         |\n| **SDK Intelligence**   | Recognized SDKs, where they're used, and modular/tree-shaking advice.   |\n| **External API Map**   | External & internal endpoints, classified, with their locations.        |\n| **Missing Dependencies** | Packages imported in source but not declared in `package.json`.       |\n| **Version Conflicts**  | Packages installed at multiple versions (duplication / conflict risk).  |\n| **Outdated Packages**  | Newer registry versions, tagged major/minor/patch (with `--outdated`).  |\n| **Warnings & Conflicts** | Multiple lockfiles and other reproducibility risks.                   |\n\n### Status taxonomy\n\nStack Atlas avoids the naive \"used vs unused\" split, because packages are often used\nindirectly (config, scripts, dynamic imports). Each dependency gets one status:\n\n| Status            | Meaning                                                                 |\n| ----------------- | ----------------------------------------------------------------------- |\n| `used`            | Imported / required in application source code.                         |\n| `config-used`     | Imported only in a config file (vite, webpack, jest, eslint, …).        |\n| `cli-used`        | Referenced only in an npm script (e.g. `vite build`, `jest`).           |\n| `types`           | A `@types/*` package (used implicitly by the TypeScript compiler).      |\n| `possibly-unused` | Declared but no usage detected anywhere — a candidate for removal.      |\n\n---\n\n## JSON report\n\n`--json` / `--all` write `stack-atlas-report.json` to the project root. Top-level shape:\n\n```jsonc\n{\n  \"tool\": \"stack-atlas\",\n  \"generatedAt\": \"2026-06-29T00:00:00.000Z\",\n  \"root\": \"/abs/path/to/project\",\n  \"project\": { \"name\", \"type\", \"frameworks\": [], \"ecosystems\": [] },\n  \"packageManager\": { \"primary\", \"managers\": [], \"lockfiles\": [], \"multipleLockfiles\" },\n  \"summary\": { \"totalDependencies\", \"used\", \"possiblyUnused\", \"configUsed\", \"cliUsed\",\n               \"types\", \"sdks\", \"heavy\", \"externalApis\", \"internalApis\",\n               \"missing\", \"conflicts\", \"warnings\" },\n  \"packages\": [ { \"name\", \"type\", \"declared\", \"installed\", \"status\", \"locations\" } ],\n  \"missing\":  [ { \"name\", \"locations\": [] } ],\n  \"sdks\":     [ { \"package\", \"name\", \"category\", \"status\", \"usedIn\", \"recommendation\" } ],\n  \"heavy\":    [ { \"package\", \"installed\", \"note\", \"status\", \"barrelImport\" } ],\n  \"apis\":     { \"external\": [ { \"host\", \"type\", \"locations\" } ], \"internal\": [ ... ] },\n  \"conflicts\": [ { \"name\", \"versions\": [] } ],\n  \"outdated\": { \"checked\", \"offline\", \"outdated\": [ { \"name\", \"current\", \"latest\", \"type\" } ] },\n  \"warnings\": [ \"...\" ]\n}\n```\n\nThis is ideal for CI dashboards, audits, and project-handover documentation. The `outdated`\nfield is present only when `--outdated` is passed.\n\n### HTML report\n\n`--html` renders the same data as a styled, self-contained `stack-atlas-report.html` —\nno external CSS, fonts, or scripts, so you can open it anywhere or commit it as an artifact.\nIt includes a **Print / Save PDF** button; the print stylesheet automatically switches to\na light, ink-friendly theme and hides the button so you get a clean PDF for audits or handovers.\n\n```bash\nnpx @adhix11/stack-atlas --html            # writes stack-atlas-report.html\nnpx @adhix11/stack-atlas --all --html      # full report + JSON + HTML\n```\n\n---\n\n## Programmatic API\n\nStack Atlas can be used as a library:\n\n```js\nconst { analyze } = require('@adhix11/stack-atlas');\n\nconst report = analyze(process.cwd(), { manager: 'npm' });\nconsole.log(report.summary);\nconsole.log(report.apis.external);\n```\n\n`analyze(root, options)` returns the same object that is serialized to the JSON report.\n\n---\n\n## How it works\n\nStack Atlas is split into two layers so it stays honest about what it can detect:\n\n**Layer 1 — Universal manifest awareness.** It recognizes the ecosystem from manifest files\n(`package.json`, `requirements.txt`, `pyproject.toml`, `pom.xml`, `build.gradle`, `go.mod`,\n`Cargo.toml`, `composer.json`, `pubspec.yaml`, `Gemfile`) and the package manager from\nlockfiles (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lockb`/`bun.lock`, plus\nthe corepack `packageManager` field).\n\n**Layer 2 — Deep usage analysis (Node / JS / TS today).** It walks your source tree (skipping\n`node_modules`, build output, and dotfolders), extracts module specifiers, maps them back to\ndeclared dependencies, scans `.env*`/YAML for endpoints, and matches packages against a\ncurated SDK catalog.\n\n### Ecosystem support\n\n| Layer                         | Ecosystems                                                        |\n| ----------------------------- | ----------------------------------------------------------------- |\n| Deep usage + API + SDK        | JavaScript, TypeScript, React, Next.js, Node, Express, NestJS, LoopBack, Vue, Svelte |\n| Manifest / package-manager    | Python, Java, Go, Rust, PHP, Dart/Flutter, Ruby (detected & reported) |\n\n---\n\n## Limitations\n\n- Usage detection is static and regex-based. Packages loaded through unusual dynamic\n  patterns, string concatenation, or non-JS config may show as `possibly-unused` — always\n  **review before removing**.\n- Installed versions and duplicate-version conflicts are read from `package-lock.json` only;\n  other lockfiles are detected but not deeply parsed yet.\n- `--outdated` is the only feature that makes network calls; everything else runs fully offline.\n  When the registry is unreachable, the outdated section is skipped gracefully.\n\n---\n\n## Roadmap\n\n- [x] HTML report (`--html`)\n- [x] Outdated / latest-version checking via the npm registry (`--outdated`)\n- [x] Duplicate-version conflict detection\n- [x] Missing-dependency detection\n- [ ] Peer-dependency mismatch detection\n- [ ] Deep parsing of `yarn.lock` / `pnpm-lock.yaml` / `bun.lock`\n- [ ] Deep usage analysis for Python, Go, and PHP\n- [ ] `--ci` mode with a non-zero exit code on policy violations\n\n---\n\n## Contributing\n\nIssues and PRs are welcome.\n\n```bash\ngit clone https://github.com/adhix11/stack-atlas.git\ncd stack-atlas\nnpm test          # run the test suite (node --test)\nnpm run demo      # run against the bundled example app\n```\n\n---\n\n## License\n\n[MIT](./LICENSE) © adhix11\n","readmeFilename":"README.md"}