docs: add format-specific lockfile parser limitations

[mvanhorn]

Summary

Adds a new "Format-specific limitations" section to docs/parser-coverage.md so bug reporters can tell which lockfile-format behaviors are intentional vs bugs.

Closes #3

Why this matters

The existing docs/parser-coverage.md covered general edge cases (monorepos, nested node_modules, optional deps, private registries) and the supported-formats table, but did not document the format-specific behaviors each parser actually has today. Issue #3 asks for that coverage across all four parsers plus the package.json fallback, with the explicit goal of making bug reports easier to submit.

Each bullet is cross-referenced against the current implementation in src/parsers/*.ts - not from memory:

• src/parsers/package-lock.ts - v1 legacy and v2/v3 flat paths; node_modules/-path filter at line 11; dev flag read directly from the lockfile
• src/parsers/pnpm-lock.ts - branches on lockfileVersion >= 9; normalizePnpmDepRef strips link: / workspace: (lines 189, 206) and returns null for relative-path refs
• src/parsers/yarn-lock.ts - no prodOnly parameter (yarn.lock Classic has no dev/prod distinction); path is always ["project", name]; matches the MVP note already in src/parsers/index.ts
• src/parsers/bun-lock.ts - JSONC trailing-comma strip (line 7); dev inferred from workspace section membership
• src/parsers/package-json.ts - skipped.slice(0, 50) report cap

Changes

• docs/parser-coverage.md: added "Format-specific limitations" section between the package.json fallback block and the existing "Known edge cases" block. No existing content was modified.

Testing

Docs-only change. Verified the diff renders correctly and all claims match the parser source.

This contribution was developed with AI assistance (Claude Code).

[sonukapoor]

Thanks for the PR - this is a useful addition overall.

I checked the new documentation against the current parser implementation, and I think the pnpm section needs to be toned down before merge.

Right now the docs say:

• v5, v6, and v9+ are supported
• v9+ uses the newer snapshots model
• the parser branches on lockfileVersion

But the current parser does not branch on lockfileVersion, and it only reads packages + importers. I don’t see logic that reads snapshots, so that wording looks stronger than what the implementation currently guarantees.

I think the rest of the additions look broadly aligned with the code. If you update just the pnpm wording to be more implementation-accurate, this should be in good shape.

[mvanhorn]

Thanks @sonukapoor. Double-checked src/parsers/pnpm-lock.ts on main before softening, and I think the current wording actually matches the code:

// src/parsers/pnpm-lock.ts, lines 8-13 on main
export function loadFromPnpmLock(filePath: string, prodOnly: boolean): PackageRef[] {
  const content = fs.readFileSync(filePath, "utf8");
  const parsed = YAML.parse(content) as any;
  const majorVersion = parseInt(String(parsed?.lockfileVersion ?? "0"), 10);
  return majorVersion >= 9 ? loadV9(parsed, prodOnly) : loadLegacy(parsed, prodOnly);
}

And loadV9 does read from snapshots:

// src/parsers/pnpm-lock.ts, line 93 on main
function loadV9(parsed: any, prodOnly: boolean): PackageRef[] {
  const snapshotsSection = parsed?.snapshots ?? {};
  // ...
}

Both were added in #198 ("feat: add pnpm lockfile v9 support") so they've been in since v1.7.0. If you're looking at a local branch that predates that, my docs would read stronger than the code you're seeing. Happy to tone things down if you'd still prefer the docs be conservative about v9 coverage - just wanted to flag the mismatch before changing the wording.

[sonukapoor]

That makes sense. Thank you for your contribution @mvanhorn

[mvanhorn]

Thanks for the docs merge, @sonukapoor. Calling out parser limits up front saves debugging.