Fix: Add PNPM Workspace scan fallback for better reliability

[JosephMaynard]

Summary by CodeRabbit

Release Notes

• Documentation

  • Added Getting Started section with quick setup instructions.
  • Clarified how the tool analyzes dependencies using npm, pnpm, or yarn and generates self-contained HTML reports.
  • Expanded script examples and usage documentation.
  • Added information about premium team offerings.

• Bug Fixes

  • Improved error handling for edge cases when no dependencies are found.
  • Enhanced pnpm support with fallback mechanisms for better reliability.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR enhances dependency analysis by introducing pnpm multi-depth fallback retry logic, improved error tracking with separate failure collections, expanded package manager support with enhanced progress reporting, and updated CLI behavior to conditionally produce outputs. Documentation is updated with getting-started examples and premium offering information.

Changes

Cohort / File(s)	Summary
Documentation README.md	Removed "local-first" emphasis, added getting-started section with example usage, expanded "What it does" to describe package manager tooling integration, added premium offering section, and clarified output format and behavior (HTML report is self-contained, no external assets).
CLI Logic src/cli.ts	Introduced outputCreated flag to track output production; enhanced npm ls invocation with contextLabel and onProgress callback; replaced single failure checks with separate lsFailures and importFailures collections that log warnings instead of throwing; conditional output writing only when dependencies found; adjusted auto-open to respect output creation state.
NPM/PNPM/Yarn Runner src/runners/npmLs.ts	Introduced pnpm multi-depth fallback mechanism (attempting depths: Infinity, 8, 4, 2, 1) with progress callbacks and per-attempt metadata tracking; added robust JSON parsing for standard and JSONL outputs; enhanced error handling via buildLsFailureMessage helper; added node memory management (ensureNodeMaxOldSpaceSize); extended normalization routines for npm, pnpm, and yarn; added utilities for progress reporting and OOM detection.
Process Utilities src/utils.ts	Extended runCommand API with optional env parameter, enabling custom environment variable injection while preserving existing cwd and shell options.

Sequence Diagram(s)

sequenceDiagram
    participant CLI as CLI Handler
    participant Runner as npmLs Runner
    participant PnpmFallback as Pnpm Fallback
    participant PnpmTool as Pnpm Tool

    CLI->>Runner: runNpmLs(path, dir, "pnpm", {contextLabel, onProgress})
    Runner->>PnpmFallback: runPnpmLsWithFallback()
    
    loop Depth attempts: [Infinity, 8, 4, 2, 1]
        PnpmFallback->>PnpmTool: pnpm ls --depth=N --json
        alt Success
            PnpmTool-->>PnpmFallback: JSON output
            PnpmFallback->>PnpmFallback: parseJsonOutput()
            PnpmFallback->>Runner: return parsed tree
        else Parse failure
            PnpmFallback->>PnpmFallback: Track attempt metadata<br/>(depth, exit code, OOM status)
            PnpmFallback->>PnpmFallback: Continue to next depth
        end
    end
    
    PnpmFallback->>PnpmFallback: buildLsFailureMessage()
    PnpmFallback-->>Runner: Error metadata or parsed result
    Runner->>CLI: aggregated dependency data

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• Feat: Better handling of sub dependencies #5: Both PRs modify src/runners/npmLs.ts and update the runNpmLs method signature to accept additional parameters for enhanced control flow and error handling.
• Fix PNPM Workspace Dependencies Scan and Add New License Discovery System #7: Both PRs introduce pnpm-specific handling changes, including fallback mechanisms and environment variable management in the npm/pnpm runner logic.
• Feat/audit in pnpm and yarn #6: Both PRs modify CLI behavior in src/cli.ts to propagate new arguments and metadata through the dependency analysis pipeline.

Poem

🐰 Hops through depths with retry cheer,
When pnpm stumbles, fallbacks appear,
From Infinity down to one,
Each attempt brings progress fun,
No more silent fails in sight—
Error tracking shines so bright! 🌟

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title accurately describes the main change: adding a pnpm workspace scan fallback mechanism to improve reliability, which is supported by the comprehensive changes to npmLs.ts introducing runPnpmLsWithFallback and multi-depth retry logic.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/pnpm-workspace-scan-again

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}