fix(npm-registry): cherry-pick npm engine + maxResults:0 guard from #403

[fuleinist]

Summary

Cherry-picks the npm registry engine + maxResults:0 guard from fix/maxresults-zero onto main, addressing the valid coderabbitai finding on PR #261 that parseObjects() would return one result when maxResults: 0.

Fix: parseObjects() now returns [] early when maxResults <= 0 (line 79).

Context

PR #261 introduced the npm registry engine but the coderabbitai pre-merge check flagged that the maxResults: 0 edge case was not handled — the cap check happened after the first valid package was pushed. This PR applies the same fix stack to the main branch directly, resolving the finding.

All 6 commits are included to ensure the npm registry engine lands cleanly on main with all the review-motivated fixes (UA header, quality tier, null guards).

Test Plan

• All 19 existing unit tests pass
• Regression test added: maxResults: 0 returns empty array

Summary by CodeRabbit

• New Features

  • Added npm registry search results to code searches.
  • npm package results include package details, snippets, and canonical links.
  • Results are safely handled when responses are incomplete or invalid.

• Bug Fixes

  • Improved resilience when the npm registry is unavailable or returns malformed data.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: eb96bf84-91de-438b-b371-0a9ce2d2561f

📥 Commits

Reviewing files that changed from the base of the PR and between c6ad447 and 2ec1ae6.

📒 Files selected for processing (5)

• src/search/core/engine-quality.ts
• src/search/core/verticals/code.ts
• src/search/engines/npm-registry.ts
• tests/unit/search/engines/npm-registry.test.ts
• tests/unit/search/v1/verticals/code.test.ts

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds an npm registry search engine. It maps npm package metadata to search results, validates API responses, handles limits and errors, and registers the engine as a high-quality secondary engine in the code vertical.

Changes

npm Registry Search

Layer / File(s)	Summary
Implement npm registry search src/search/engines/npm-registry.ts, tests/unit/search/engines/npm-registry.test.ts	NpmRegistryEngine queries npm’s search API, validates responses, maps package metadata, builds canonical URLs, applies result limits, and handles invalid entries and errors.
Register npm engine in code search src/search/core/engine-quality.ts, src/search/core/verticals/code.ts, tests/unit/search/v1/verticals/code.test.ts	The code vertical registers npm-registry as a high-quality secondary engine with weight 0.3. Tests expect seven default engines and three secondary engines.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 2ec1a

This change adds a localized guard so npm registry searches return no results when maxResults is zero, with a regression test covering the behavior. No actionable merge-blocking risk remains beyond normal checks and review.

Suggested reviewers: knockoutez

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant NpmRegistryEngine
  participant NpmSearchAPI
  Caller->>NpmRegistryEngine: Search for a package query
  NpmRegistryEngine->>NpmSearchAPI: Request encoded query
  NpmSearchAPI-->>NpmRegistryEngine: Return package metadata
  NpmRegistryEngine-->>Caller: Return mapped search results

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 5 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the npm registry engine change and the maxResults:0 guard. Both changes are central to the pull request.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[fuleinist]

Ping @KnockOutEZ — this PR (#481) is a cherry-pick of the maxResults:0 guard from #403, with all CodeRabbit findings addressed and CI passing. It's the minimal fix needed before #403 can be merged properly. Any chance you could take a look?

[KnockOutEZ]

Hi @fuleinist — thank you for this PR, and I'm sorry it's been sitting here without a proper review.

I've been heads-down building some pretty big features and improvements for wigolo, and as a solo dev, shipping that while also reviewing and maintaining every issue and PR has been genuinely hard. This one isn't forgotten — it just hasn't had the attention it deserves yet.

I'd really appreciate your patience here. I'm going to work through the open PRs and issues properly over the next few weeks (sooner if I can free up), and I'll follow up right here.

In the meantime, the wigolo Discord is open if you'd like to follow what's being built, ask questions, or nudge me directly: https://discord.gg/BkUUgz2bNF

Thanks again for contributing, and for understanding — it genuinely means a lot. 🙏