feat: add npm registry search engine adapter (#144)

[josephkehan-prog]

Closes #144

Adds NpmRegistryEngine using the npm registry public JSON search API (registry.npmjs.org/-/v1/search) — no scraping, no key.

• Maps name@version → title, links.npm → url, description (truncated 200 chars) → snippet, date → published_date; rank-based relevance_score matching other adapters (registry's raw score.final is unnormalized, deliberately unused)
• Descriptive User-Agent following the wikipedia/marginalia/lobsters convention
• Registered in the code vertical (weight 0.9, quality medium per the engine-quality registry default)
• 11 unit tests mirroring hn-algolia.test.ts mocked-fetch pattern; updated code.test.ts engine-count assertions (same collateral as prior engine additions)

Test plan

• npx vitest run tests/unit/search/engines/npm-registry.test.ts tests/unit/search/v1/verticals/code.test.ts — 19/19
• npx tsc --noEmit clean

Summary by CodeRabbit

• New Features

  • Added npm registry search to code-focused results, returning package name, version (when available), description snippets, direct links, relevance scoring, and publication dates when present.
  • Supports configurable timeouts and maximum result limits.

• Bug Fixes

  • More resilient handling of incomplete registry responses and non-successful HTTP results.

• Tests

  • Added unit tests covering request construction (query encoding, headers, limits, timeouts), result mapping, snippet truncation, filtering of invalid entries, error handling, and network failure propagation.

[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: 1b5760f7-91b4-49ea-9348-f910f6d9a82f

📥 Commits

Reviewing files that changed from the base of the PR and between 564866f and 3ecd34d.

📒 Files selected for processing (1)

• src/search/engines/npm-registry.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/search/engines/npm-registry.ts

---

📝 Walkthrough

Walkthrough

Adds an npm registry search engine, maps registry packages into shared search results, registers it in the code vertical, and adds unit tests for requests, parsing, errors, and engine membership.

Changes

NPM registry search integration

Layer / File(s)	Summary
NPM registry adapter implementation src/search/engines/npm-registry.ts, tests/unit/search/engines/npm-registry.test.ts	Implements timed npm registry requests, response validation, package-result mapping, snippet truncation, relevance scoring, publication dates, and related unit coverage.
Code vertical registration and validation src/search/core/verticals/code.ts, tests/unit/search/v1/verticals/code.test.ts	Adds NpmRegistryEngine to the code engine set with configured weight, quality, and date-filter support, and updates engine-list expectations.

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

Sequence Diagram(s)

sequenceDiagram
  participant SearchCaller
  participant NpmRegistryEngine
  participant NpmRegistryAPI
  SearchCaller->>NpmRegistryEngine: Submit code search query
  NpmRegistryEngine->>NpmRegistryAPI: Request package results
  NpmRegistryAPI-->>NpmRegistryEngine: Return registry JSON
  NpmRegistryEngine-->>SearchCaller: Return mapped RawSearchResult[]

Loading

Possibly related issues

• Add a crates.io search engine adapter #145 — Adds a similar public package-registry search engine and registers it in the code vertical.

Possibly related PRs

• KnockOutEZ/wigolo#191 — Registers a different package-registry engine in the same code vertical and updates its engine-list tests.

🚥 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%.	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 accurately summarizes the main change: adding an npm registry search engine adapter.
Linked Issues check	✅ Passed	The adapter, code-vertical registration, timeout/maxResults support, tests, and API-based implementation all match #144.
Out of Scope Changes check	✅ Passed	The changes stay focused on the npm registry adapter, its registration, and supporting tests.

✨ 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.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/search/engines/npm-registry.ts`:
- Around line 66-68: Update the parsing loop around the objects array access so
malformed null or undefined entries are handled safely before reading package.
Use optional chaining on the array item while preserving the existing name
extraction and invalid-item skipping behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c965f29a-8050-492a-be5a-a5a8618deec3

📥 Commits

Reviewing files that changed from the base of the PR and between a15277b and 564866f.

📒 Files selected for processing (4)

• 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