Skip to content

analyze.md

Latest commit

 

History

History
99 lines (65 loc) · 5.05 KB

analyze.md

File metadata and controls

99 lines (65 loc) · 5.05 KB

Command: analyze

← Back to docs index

Analyzes a package using several built-in checks (publint, replacement suggestions, dependency summary, duplicate versions in the lockfile).

Prerequisites

  • A package.json at the project root.
  • A supported lockfile next to it: pnpm-lock.yaml, package-lock.json, yarn.lock, or bun.lock.

Analysis reads the lockfile and package.json together. If no lockfile is found, the CLI errors instead of guessing.

Examples

# Analyze the current directory (must contain package.json + a supported lockfile)
npx @e18e/cli analyze

# Analyze a different package root
npx @e18e/cli analyze ./packages/app

# JSON on stdout for scripts and CI; exit code reflects --log-level vs findings
npx @e18e/cli analyze --json

# Fail CI only on errors, not warnings or suggestions
npx @e18e/cli analyze --json --log-level error

# Show all findings in JSON, but only fail on errors
npx @e18e/cli analyze --json --log-level error --report-level info

# ESLint-style quiet mode: only show errors in output
npx @e18e/cli analyze --quiet

# Narrow replacement suggestions to the "native" manifest category
npx @e18e/cli analyze --categories native

# Combine categories
npx @e18e/cli analyze --categories native,preferred

# Extra replacement manifests (repeat --manifest for each file)
npx @e18e/cli analyze --manifest ./config/e18e.manifest.json

With a global install, swap npx @e18e/cli for e18e-cli (same arguments).

Optional positional argument

  • [directory] — Root of the package to analyze. If omitted, the current working directory is used. Must be a directory (not a file).

Flags

Flag Description
--log-level <level> debug, info, warn, or error (default: info). Sets the minimum message severity that causes a non-zero exit (see Exit codes). Also enables debug logging when set to debug.
--quiet ESLint-style quiet mode. Only error messages appear in Results and JSON messages. Overrides --report-level.
--report-level <level> auto, debug, info, warn, or error (default: auto). Controls which severities are shown in Results and JSON messages. auto means "follow --log-level."
--categories <list> Replacement manifest scope: all, or comma-separated native, preferred, micro-utilities (e.g. native,preferred). Invalid values exit with code 1.
--manifest <path> Extra replacement manifest file(s); can be passed multiple times.
--json Print { stats, messages } as JSON on stdout and skip the interactive UI. messages follow --quiet or resolved --report-level. Exit code still follows --log-level vs message severities.

What the summary metrics mean

Here’s what each value in the summary represents:

  • Dependencies (production / development) — Counts of direct dependencies only: keys in dependencies and devDependencies in package.json. This is not the number of transitive packages in your install graph.
  • Install size — Sum of file sizes under node_modules for the current install (on-disk footprint). It is not a separate “dependency tree node count.”
  • Duplicate dependency messages — Packages that appear with more than one resolved version in the parsed lockfile, with context about dependents. That reflects lock/install reality, not the direct-dependency counts above.

What analysis includes

Checks are implemented as plugins wired in report() (see src/analyze/report.ts), including:

  • Publint — Package publishing best practices.
  • Replacements — Suggested swaps from the module-replacements manifests (scoped by --categories and optional --manifest).
  • Dependency summary — Direct dependency counts and install size (as described above).
  • Duplicate dependencies — Multiple versions of the same package name in the lockfile.

Exit codes (analyze)

Message severities are error, warning, and suggestion. Output visibility and exit behavior are separate:

  • Shown in Results / JSON messages: controlled by --quiet or --report-level (auto follows --log-level).
  • Exit code: controlled by --log-level.

With either normal or JSON output, the process exits with 1 if any message meets or exceeds the severity implied by --log-level:

--log-level Fails (exit 1) when
debug Never (for exit purposes; still lists all messages)
info Any error, warning, or suggestion
warn error or warning
error error only

Invalid --categories or an invalid analyze path also yields exit code 1.

Running with npx

Some package runners mishandle flags or the -- separator when invoking a package binary (for example npx @e18e/cli -- --help may not do what you expect). If help or subcommand flags behave oddly, run e18e-cli after a global install, or invoke npx @e18e/cli with no extra flags and use the Usage examples on the repository README.