npm-dependency-visualizer 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Nikolche Kolev
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,101 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
1
+ # npm Dependency Visualizer
2
+
3
+ Generate a dependency graph from a local `package.json` and `package-lock.json`.
4
+ The output is a Markdown document with a Mermaid diagram.
5
+ Package nodes show locked versions, and arrows show the original dependency specifications and roles.
6
+
7
+ The CLI requires Node.js 22.12.0 or later and a `package-lock.json` matching the project's `package.json` (lockfile version 2 or 3).
8
+ It uses the lockfile, not the contents of `node_modules`, so dependencies do not need to be installed.
9
+ The CLI has no runtime dependencies, makes no network requests, and does not change the inputs.
10
+
11
+ If `package-lock.json` is missing, provide an existing lockfile or run `npm install --package-lock-only` in the project directory.
12
+ Generating a lockfile is a separate npm operation that may access the network and resolve different versions than an existing installation.
13
+
14
+ ## Usage
15
+
16
+ Run the CLI from this repository:
17
+
18
+ ```powershell
19
+ # Read the current directory and write Markdown to stdout.
20
+ node .\cli.js
21
+
22
+ # Read another project and write a Markdown report.
23
+ node .\cli.js C:\src\project --output graph.md
24
+
25
+ # Include root and workspace development dependencies.
26
+ node .\cli.js C:\src\project --include-dev --output graph.md
27
+
28
+ # Generate the default npm/cli graph, including reached workspaces, from the pinned fixture.
29
+ node .\cli.js .\test\fixtures\npm-cli --output npm-cli.md
30
+
31
+ # Start the graph at one workspace, selected by name or location.
32
+ node .\cli.js .\test\fixtures\npm-cli --workspace @npmcli/arborist --output arborist.md
33
+
34
+ # Show only the root graph, excluding workspaces.
35
+ node .\cli.js .\test\fixtures\npm-cli --no-workspaces --output npm-cli-root.md
36
+
37
+ # Highlight glob and its ancestor paths without removing the rest of the graph.
38
+ node .\cli.js .\test\fixtures\npm-cli --focus glob --output npm-glob.md
39
+
40
+ # Use a smaller focused view when a graph is too dense to read.
41
+ node .\cli.js .\test\fixtures\npm-cli --focus read --focus-mode filter --depth 2 --output npm-read.md
42
+ ```
43
+
44
+ Alternatively, install the local CLI with `npm install --global --omit=dev .` and run `npm-dependency-visualizer`.
45
+ The optional directory argument defaults to the current directory, and `--output` is relative to the current directory.
46
+ Generated reports from the pinned npm/cli fixture:
47
+
48
+ | Example | Arguments | Shows |
49
+ | --- | --- | --- |
50
+ | `examples\npm-cli.md` | (none) | Full graph, 149 nodes and 359 relationships, no focus |
51
+ | `examples\npm-cli-focus-highlight.md` | `--focus glob` | Same full graph; `glob` and its 26 ancestors are colored, other branches keep their normal style |
52
+ | `examples\npm-cli-focus-filter.md` | `--focus glob --focus-mode filter` | Only `glob` and its ancestors: 27 nodes and 70 relationships, with the same colors |
53
+ | `examples\npm-cli-arborist.md` | `--workspace @npmcli/arborist` | Graph started at the `@npmcli/arborist` workspace |
54
+
55
+ | Option | Description |
56
+ | --- | --- |
57
+ | `--output <file>` | Write a report to a file instead of stdout |
58
+ | `--include-dev` | Include development dependencies of the root and every workspace |
59
+ | `--depth <n>` | Keep nodes at most `n` dependency edges from the start node |
60
+ | `--workspace <name>` | Start the graph at one workspace, matched by package name or location |
61
+ | `--no-workspaces` | Exclude workspaces and show only the root graph |
62
+ | `--focus <name>` | Highlight every matching dependency instance and its ancestor paths, keeping the rest of the graph |
63
+ | `--focus-mode highlight\|filter` | Keep all branches (default), or keep only matches and ancestors; requires `--focus` |
64
+ | `--help`, `--version` | Display usage or the CLI version |
65
+
66
+ Without focus, the complete selected graph is shown without highlighting.
67
+ Focus uses the Sunset Boulevard palette: coral, thick-bordered nodes are matches; warm-sand nodes are ancestors; thick burnt-orange arrows trace the ancestor subgraph.
68
+ Unrelated nodes and edges keep their normal style.
69
+ The node index also labels matches and ancestors so the report does not rely on color alone.
70
+ `--focus-mode filter` applies the same colors but removes unrelated branches.
71
+ Focus is computed before depth, and the report notes any matches hidden by the explicit depth limit.
72
+ Visible ancestors can therefore remain highlighted even when a matching instance is deeper than the limit.
73
+ Diagnostics are written to stderr; the document includes warnings and counts of filtered nodes, excluded links, and excluded project records.
74
+ An output file is replaced only after the report is generated, and input files and their filesystem aliases cannot be used as output.
75
+
76
+ | Exit code | Meaning |
77
+ | --- | --- |
78
+ | `0` | Report generated, possibly with optional-dependency or link warnings |
79
+ | `1` | Invalid arguments or input, unmatched focus, or output failure |
80
+ | `2` | Diagnostic report generated for missing required dependencies in the lockfile, missing non-root versions, or unsupported private peer placement |
81
+
82
+ ## Scope and limitations
83
+
84
+ The default graph includes reachable production, optional, and peer dependencies.
85
+ `--include-dev` also includes development dependencies of the root and of every workspace, but not transitive packages' development requirements.
86
+ With `--include-dev`, every workspace becomes an extra graph entry point, so workspaces nothing depends on appear as separate unconnected starting nodes (no synthetic root edges). With `--workspace`, only the selected workspace and the workspaces it reaches contribute development dependencies.
87
+ Distinct installation locations remain distinct nodes, including when their names and versions match.
88
+ Mermaid's default `maxEdges` limit is 500, so large graphs (for example, npm/cli with `--include-dev`, 2,406 relationships) need `--depth`, `--focus <name> --focus-mode filter`, or a renderer configured with a higher limit.
89
+
90
+ Workspaces declared in the root `package.json` are included by default.
91
+ Without `--include-dev`, a workspace appears only when a declared dependency reaches it through its `node_modules` link in the lockfile; there are never synthetic root-to-workspace edges.
92
+ Workspace nodes use Mermaid's double-bordered subroutine shape and a `(workspace)` label, and the report states how many declared workspaces were reached.
93
+ Workspace dependencies resolve using the lockfile's `node_modules` locations, starting with the workspace and then the root.
94
+ Use `--workspace <name>` to start at one workspace, or `--no-workspaces` to restore the root-only graph.
95
+ Non-workspace local-directory links (such as `file:` dependencies) are excluded and reported.
96
+ The original edge specifications are displayed even when root overrides are present; the tool does not calculate effective override ranges.
97
+
98
+ Use `--focus` to inspect current parent chains to a dependency, not to calculate an upgrade plan.
99
+ Determining which releases enable a new dependency version requires additional release metadata and constraint analysis.
100
+
101
+ Large graphs may exceed a viewer's layout limits; use `--depth` or `--focus <name> --focus-mode filter` for a smaller view.
package/cli.js ADDED
@@ -0,0 +1,126 @@
1
+ #!/usr/bin/env node
2
+ import { readFile } from 'node:fs/promises'
3
+ import { resolve } from 'node:path'
4
+ import { parseArgs } from 'node:util'
5
+ import { InputError } from './src/errors.js'
6
+ import { buildGraph } from './src/graph.js'
7
+ import { readInputs } from './src/input.js'
8
+ import { writeReport, writeStream } from './src/output.js'
9
+ import { formatDiagnostic, renderReport } from './src/render.js'
10
+ import { selectView } from './src/select.js'
11
+
12
+ const help = `Usage: npm-dependency-visualizer [directory] [options]
13
+
14
+ Read package.json and package-lock.json from directory (default: current directory).
15
+ Write Markdown with Mermaid to stdout unless --output is specified.
16
+
17
+ Options:
18
+ --output <file> Write a complete report to a file
19
+ --include-dev Include root and workspace development dependencies
20
+ --depth <n> Limit the graph to n edges from the start node
21
+ --workspace <name> Start at a workspace (package name or location)
22
+ --no-workspaces Exclude workspaces; graph only the root project
23
+ --focus <name> Highlight matches and ancestor paths, keeping the graph
24
+ --focus-mode <mode> highlight (default) or filter; requires --focus
25
+ --help Show this help
26
+ --version Show the version
27
+
28
+ Exit codes: 0 for a report, 1 for an error, 2 for a report with graph defects.
29
+ `
30
+
31
+ function optionsFrom(argv) {
32
+ let parsed
33
+ try {
34
+ parsed = parseArgs({
35
+ args: argv,
36
+ allowPositionals: true,
37
+ allowNegative: true,
38
+ options: {
39
+ output: { type: 'string' },
40
+ 'include-dev': { type: 'boolean' },
41
+ depth: { type: 'string' },
42
+ workspace: { type: 'string' },
43
+ workspaces: { type: 'boolean' },
44
+ focus: { type: 'string' },
45
+ 'focus-mode': { type: 'string' },
46
+ help: { type: 'boolean' },
47
+ version: { type: 'boolean' },
48
+ },
49
+ })
50
+ } catch (error) {
51
+ throw new InputError(error.message)
52
+ }
53
+
54
+ const { values, positionals } = parsed
55
+ if (positionals.length > 1) throw new InputError('Only one project directory may be specified')
56
+ if (values.output === '') throw new InputError('--output must not be empty')
57
+ if (values.focus === '') throw new InputError('--focus must not be empty')
58
+ if (values.workspace === '') throw new InputError('--workspace must not be empty')
59
+ if (values.workspace !== undefined && values.workspaces === false) {
60
+ throw new InputError('--workspace cannot be combined with --no-workspaces')
61
+ }
62
+ if (values['focus-mode'] !== undefined) {
63
+ if (!['highlight', 'filter'].includes(values['focus-mode'])) {
64
+ throw new InputError('--focus-mode must be highlight or filter')
65
+ }
66
+ if (values.focus === undefined) throw new InputError('--focus-mode requires --focus')
67
+ }
68
+ let depth
69
+ if (values.depth !== undefined) {
70
+ if (!/^\d+$/.test(values.depth) || !Number.isSafeInteger(Number(values.depth))) {
71
+ throw new InputError('--depth must be a nonnegative safe integer')
72
+ }
73
+ depth = Number(values.depth)
74
+ }
75
+ return {
76
+ directory: resolve(positionals[0] ?? '.'),
77
+ output: values.output,
78
+ includeDev: values['include-dev'] ?? false,
79
+ depth,
80
+ workspace: values.workspace,
81
+ workspaces: values.workspaces ?? true,
82
+ focus: values.focus,
83
+ focusMode: values['focus-mode'] ?? 'highlight',
84
+ help: values.help ?? false,
85
+ version: values.version ?? false,
86
+ }
87
+ }
88
+
89
+ async function main() {
90
+ const options = optionsFrom(process.argv.slice(2))
91
+ if (options.help) {
92
+ await writeStream(process.stdout, help)
93
+ return 0
94
+ }
95
+ if (options.version) {
96
+ const metadata = JSON.parse(await readFile(new URL('./package.json', import.meta.url), 'utf8'))
97
+ await writeStream(process.stdout, `${metadata.version}\n`)
98
+ return 0
99
+ }
100
+
101
+ const inputs = await readInputs(options.directory)
102
+ const graph = buildGraph(inputs, {
103
+ includeDev: options.includeDev,
104
+ workspaces: options.workspaces,
105
+ workspace: options.workspace,
106
+ })
107
+ const view = selectView(graph, { focus: options.focus, focusMode: options.focusMode, depth: options.depth })
108
+ const report = renderReport(view)
109
+ if (options.output !== undefined) {
110
+ await writeReport(options.output, inputs.inputPaths, report)
111
+ } else {
112
+ await writeStream(process.stdout, report)
113
+ }
114
+ for (const diagnostic of graph.diagnostics) {
115
+ await writeStream(process.stderr, `${formatDiagnostic(diagnostic)}\n`)
116
+ }
117
+ return graph.exitCode
118
+ }
119
+
120
+ try {
121
+ process.exitCode = await main()
122
+ } catch (error) {
123
+ const message = error instanceof InputError ? error.message : error.stack ?? String(error)
124
+ await writeStream(process.stderr, `error: ${message}\n`)
125
+ process.exitCode = 1
126
+ }