qa-bundle-check

name	qa-bundle-check
description	[QA Methodology] Check a VirtoCommerce stable bundle (bundles/vN/package.json) for available module/Platform/Theme HOTFIXES — newer patch releases on the SAME major.minor line that the bundle has not yet picked up. Use when asked to verify a bundle is up to date, audit pinned versions, or check 'есть ли хотфиксы / are there newer patches'. Does NOT flag newer minors (a frozen bundle intentionally trails master).
argument-hint	vN | <package.json-url> [--json] [--no-platform] [--no-theme] [--no-trace] [--no-links|--links]

Bundle Hotfix Check

A VirtoCommerce stable bundle (vc-modules/bundles/vN/package.json) pins every module, the Platform, and the storefront Theme to one coherent generation (e.g. v12 → Platform 3.917.x). The recurring question is not "is each module on the absolute latest release" — a frozen bundle is meant to trail master. The real question is:

For each pinned version A.B.C, has a newer hotfix A.B.(C+n) shipped on the same A.B line that this bundle hasn't absorbed yet?

That is the only comparison this skill makes.

Why a deterministic script (not agents)

Version comparison is mechanical: parse JSON → query GitHub → compare integers. LLM agents are the wrong tool here — slow, token-expensive, and non-deterministic (a re-run can miss a module or misread a page). So:

• Primary engine: scripts/hotfix/bundle-version-check.ts does 99% of the work.
• Agent fan-out is a FALLBACK only — used when a module Id doesn't resolve to a repo (new/renamed module absent from the map) or the GitHub API is unavailable.

Run it

npm run bundle:check -- v12        # short bundle name → bundles/v12/package.json
npm run bundle:check -- "https://github.com/VirtoCommerce/vc-modules/blob/master/bundles/v14/package.json"
# or directly:
npx tsx scripts/hotfix/bundle-version-check.ts "<vN | bundle-url>" [--json] [--no-platform] [--no-theme] [--no-trace] [--concurrency=N]

• Accepts a github.com/.../blob/... URL or a raw URL (normalized internally).
• GIT_TOKEN is read from .env.local (raises the GitHub limit to 5000 req/h; without it the API caps at 60/h and the run will likely rate-limit → exit 2).

How it works (scripts/hotfix/bundle-version-check.ts)

1. Fetch + parse the bundle: modules from Sources[].Modules[] ({Id, Version}), PlatformVersion → repo vc-platform, and the version embedded in the ThemeB2BVue download URL → repo vc-frontend.
2. Resolve each Id → GitHub repo via config/module-repo-map.json (a cache, not a hand-maintained allowlist — many repo names are irregular: Contracts→contract, Xapi→x-api, ApplicationInsights→app-insights, FileSystemAssets→ filesystem-assets, PageBuilderModule→pagebuilder, …). The module set varies per bundle (vN), so the map always lags. Any Id absent from it is auto-resolved at runtime: the tool generates repo-name candidates (kebab, drop-Module, collapsed casing, singular) and verifies each by checking the bundle's pinned tag exists in it (one call proves both repo + version line). The discovered mapping is persisted back into the map (self-healing), so the next run is deterministic and free. Only an Id that no candidate resolves is flagged ⚠ unresolved → exit 2 (then use the agent fan-out below).
3. For each target, confirm the pinned tag exists, then probe A.B.(patch+1), A.B.(patch+2), … until a 404 (GitHub git-ref existence check). The highest tag that exists on the line is the answer — cheap (1–3 calls each), no pagination.
4. Provenance (hotfixes only): for every new patch above the pinned one, read the GitHub release notes to find the PR that produced it, fetch that PR, and extract the JIRA task key(s) from its title / branch / body (regex [A-Z]{2,}-\d+ → linked as JIRA_BASE_URL/browse/KEY, default virtocommerce.atlassian.net). If a release has no notes (e.g. theme releases with body: null), it falls back to diffing prev..tag and mining commit messages for PR refs + task keys. Disable with --no-trace. Set JIRA_BASE_URL to point at a different tracker.

Output & exit codes

	Meaning
✓ current	pinned == highest patch on its line — nothing to do
⬆ HOTFIX AVAILABLE → X.Y.Z	a newer same-line patch exists; bundle should bump
⚠ unresolved / ✗ line-missing	repo/version couldn't be verified — see fallback

• Exit 0 = all current · 1 = ≥1 hotfix available · 2 = tool error / unresolved.
• --json emits { bundle, checkedAt, counts, results[] } (each hotfix result carries traces[] → { version, date, releaseUrl, prs[{number,title,url,taskKeys,taskUrls}], commitTaskKeys }).
• When hotfixes exist the table is followed by a provenance list — per module, each new patch with the PR that raised it and the JIRA task it links to, e.g.: 3.815.4 (2026-06-23) — PR #162 "VCST-5328: …" / task: VCST-5328, VP-9216. The PR number and each task key are emitted as OSC 8 terminal hyperlinks — the label itself is clickable (VS Code / Windows Terminal / iTerm2) when stdout is a TTY. Piped/redirected output (and --no-links) falls back to label (url) so the URL is never lost; --links forces hyperlinks even when piping.

CI gating

bundle:check is exit-code driven, so it drops into a pipeline directly: run it against the current stable bundle on a schedule (or on bundle PRs); exit 1 means "new hotfixes to absorb", exit 2 means "the check itself needs attention" (an unmapped module or an auth/rate-limit problem) — treat those differently.

Fallback: still-unresolved repo (agent fan-out)

Runtime auto-resolution (step 2 above) handles the normal "new module" case and self-heals the map. This fallback is only for an Id that even auto-resolution couldn't crack (the repo name matches none of the generated candidates, e.g. an unusual rename), shown as ⚠ unresolved / ✗ line-missing:

1. Find the correct repo: web-search VirtoCommerce vc-module-* <ModuleName>, or open https://github.com/VirtoCommerce/<repo>/releases for likely variants.
2. Confirm the pinned tag exists and probe the next patch directly: https://github.com/VirtoCommerce/<repo>/releases/tag/A.B.(C+1) (200 = hotfix exists, 404 = current).
3. Add the verified mapping to config/module-repo-map.json (and, if the candidate generator should have caught it, widen repoCandidates() in the script).

Only when several modules are unresolved at once, parallelize step 1–2 across a few general-purpose agents (one batch each) — but still record the results back into the map.

Reporting

This is tooling output, not one of the five tracked report categories (.claude/rules/reports.md) — print the table to the user / CI log; do not create a file under reports/. If a hotfix matters for a release decision, it flows into the normal release/regression report, not a standalone bundle file.

Maintenance

• config/module-repo-map.json is a self-healing cache — the tool appends auto-resolved modules to it (verified against v12/v14 on 2026-06-23). It should rarely need hand-editing; if it does, that means repoCandidates() missed a naming variant worth adding.
• Tag scheme assumed: bare Major.Minor.Patch (VC's release convention). If a repo ever switches to v-prefixed tags, adjust tagOf() in the script.