npm Package Release Impact & Regression Intelligence

Resolve npm package releases, map them to their public GitHub repositories, and compare bounded GitHub issue windows around the selected package boundary. The Actor emits one explainable impact record per requested package rather than a raw metadata dump or an unbounded issue scrape.

Regression signals describe temporal changes in issue reporting. They do not prove that a package release caused an individual issue.

Input

The default input analyzes vite using the newest stable version whose npm publish time is at least seven days old. packages accepts one to five public package names. Scoped names such as @tanstack/react-query are supported; use package@1.2.3 with specific_version for an exact version.

comparisonMode values are:

• latest_eligible_version — select the newest stable version published at least windowDays ago.
• specific_version — analyze the exact version encoded in every package entry.
• custom_date — use comparisonDate as the temporal boundary and select the newest stable version published by that date.
• recent_vs_previous — compare two adjacent rolling windows without requiring an eligible release.

windowDays is 1–30 and maxIssuesPerPeriod is 10–200. includeEvidence controls bounded representative issue references. An optional githubToken increases GitHub’s public API rate limit; it is never written to output or logs.

Sources and resolution

Package metadata is fetched from the public npm registry’s full package packument so publish timestamps and version-level repository metadata are available. Stable versions are selected using publish time, then deterministic semver ordering for ties. Repository resolution prefers version-level metadata, then package-level metadata, bugs/homepage links, and preserves a monorepo directory when npm provides one.

Issue data comes from the public GitHub REST Issues API with state=all, newest-created ordering, 100 items per page, and a maximum of eight pages. GitHub may return pull requests through this endpoint; every item with pull_request is excluded. Issue bodies and titles are classified with deterministic software taxonomy rules. Comments, discussions, commits, diffs, source code, private repositories, security alerts, and webhooks are outside Version 1.

Output

One Dataset item is emitted per requested package. A package-level registry, version, repository, or GitHub failure becomes a status: "failed" item so other packages can finish. Partial coverage is reported instead of silently presenting an incomplete comparison as complete.

Output fields

Field	Meaning
status	ok, partial, or failed package result status.
package.name	Normalized npm package name.
package.selectedVersion	Version used as the package boundary.
package.previousVersion	Previous lower stable semver version when available.
package.changeType	major, minor, patch, none, or unknown.
package.repository.fullName	Canonical GitHub repository.
boundary.timestamp	UTC comparison boundary timestamp.
impact.direction	Observed regression-signal direction.
impact.level	Low, medium, high, or unknown impact level.
impact.issueVolume.before	Issues analyzed before the boundary.
impact.issueVolume.after	Issues analyzed after the boundary.
impact.issueVolume.absoluteDelta	Difference in analyzed issue counts.
impact.bugSignalRateDelta	Change in bug-related signal share.
impact.regressionSignalRateDelta	Change in regression-related signal share.
coverage.before.coverageStatus	BEFORE coverage: full, partial, or insufficient.
coverage.after.coverageStatus	AFTER coverage: full, partial, or insufficient.
impact.confidence.level	Evidence-quality confidence level.
summary	Deterministic, non-causal summary.
warnings	Bounded collection and coverage warnings.
error.code	Stable error code for failed package items.
fetchedAt	Report generation timestamp.

sources.npm records registry request count and response bytes. sources.github records API request count and rate-limit metadata. The raw npm packument and raw GitHub pages are not emitted.

Coverage and responsible use

full means both requested windows were reached, each has at least eight analyzed issues, and no known truncation occurred. partial means usable evidence exists with an incomplete window or source limitation. insufficient means the sample is too small for directional analysis. Confidence is an evidence-quality score, not a probability of causation.

Use results to prioritize release follow-up, triage, and investigation. Do not treat a changed issue rate as proof of a defect, security finding, customer harm, or release causality. Validate important findings against release notes, reproduction steps, maintainers’ context, and the package’s own tests.

Runtime and limits

The default run is intentionally bounded to five packages, eight GitHub pages per package, and 200 analyzed issues per period. Full npm packuments can be large; the Actor records byte counts and avoids retaining raw metadata in output. Unauthenticated GitHub access is subject to GitHub’s public API rate limits. A rate-limit interruption produces a partial or failed package record with a warning/error code.

Scheduling, pricing, and publication

Scheduled runs can compare rolling windows or monitor newly eligible package versions. This release candidate does not automatically change pricing or publish external content. Store publication requires a separate release gate covering tests, schemas, local runs, Cloud smoke tests, output inspection, and secret-redaction checks; see docs/publish-readiness-report.md.

FAQ

Does this prove a release caused a regression? No. It identifies temporal changes in public issue-reporting signals around a package boundary.

Why is a result partial? The period may be active, contain too few issues, hit the eight-page safety cap, or encounter a GitHub rate limit.

Why did the Actor use a monorepo directory? Version-level npm metadata can identify the package’s directory inside a shared GitHub repository. The directory is provenance, not a claim that every repository issue belongs only to that package.