@4da/mcp-server 6.1.0 → 6.2.0

package/dist/live/changelog.js

@@ -8,6 +8,8 @@
  *   conventional          `## [7.0.0](https://…/compare/…) (2025-06-24)`
  *   plain / prefixed      `## 1.2.3`, `# v1.2.3 (2024-01-01)`, `### Version 1.2.3`, `## fastembed 5.0.0`
  *   setext                `1.2.3` underlined with `===` / `---`
+ *   reStructuredText      `Version 3.0.0` underlined (or over- and underlined)
+ *                         with any of `= - ~ ^ * + # " '`, then `Released 2023-09-30`
  *   History.md (express)  `1.2.3 / 2020-01-01`
  * A heading only opens a section when the rest of it looks like a trailer
  * (date, link, "yanked") — `## Upgrading from 1.x` or `#### Rust 1.70 support`
@@ -25,7 +27,7 @@ import { classifyEntry, classifyHeading, sanitizeEntry } from "./changelog-class
  * for a week unless this changes: bump it with every change to parseChangelog
  * or changelog-classify.ts that can alter a section or an entry's kind.
  */
-export const CHANGELOG_PARSER_VERSION = 2;
+export const CHANGELOG_PARSER_VERSION = 4;
 const NAME_STEMS = ["changelog", "changes", "history", "releases", "release-notes", "release_notes", "releasenotes", "news"];
 const NAME_EXTS = ["", ".md", ".markdown", ".txt", ".rst"];
 /** True for a root-level basename that names a changelog (case-insensitive). */
@@ -106,7 +108,13 @@ export function parseVersionHeading(raw) {
     return { version, date: extractDate(rest) };
 }
 const ATX = /^(#{1,6})\s+(.*?)\s*#*\s*$/;
-const SETEXT_RULE = /^\s*(=+|-+)\s*$/;
+/**
+ * A setext / reStructuredText underline. `=` and `-` at any length (Markdown);
+ * the other RST adornments need three, so a stray `**` is not a heading rule.
+ */
+const SETEXT_RULE = /^\s*(=+|-+|~{3,}|\^{3,}|\*{3,}|\+{3,}|#{3,}|"{3,}|'{3,})\s*$/;
+/** `Released 2023-09-30`, `Released on 2024-01-01`, `Release date: ...`, `Unreleased`: a date line under an RST heading. */
+const RELEASED_LINE = /^\s*(?:\*{0,2}(?:released|release date|date)\*{0,2}(?:\s+on)?\s*:?\s*(.*)|unreleased|\(unreleased\))\s*$/i;
 const BULLET = /^(\s*)(?:[-*+•]|\d+[.)])\s+(.*)$/;
 const LINK_DEF = /^\s*\[[^\]]+\]:\s*\S+/;
 const FENCE = /^\s*(```|~~~)/;
@@ -238,6 +246,37 @@ function addLine(state, line) {
     state.parentEntry = null;
     state.pending = { text: line, context: state.headingKind, indent: -1, under: state.headingText };
 }
+/** A heading that is not a release: a category inside the current release, or the end of it. */
+function subHeading(state, raw, level, setext = false) {
+    flush(state);
+    // A setext title ends the release only from a strictly higher level: "text" over
+    // "---" is also how a paragraph followed by a rule reads.
+    if (setext && level >= state.sectionLevel)
+        level = state.sectionLevel + 1;
+    // "## Migration guide" after the last release must not be read as part of it.
+    // A change-category heading ("## Changed", "## Breaking Changes") at the
+    // release's own level is still inside it: date-fns 3.0.0 writes
+    // "## v3.0.0" then "## Changed", and its ten BREAKING entries were dropped.
+    if (state.current && level <= state.sectionLevel && !isCategoryHeading(raw))
+        state.current = null;
+    state.headingKind = classifyHeading(raw);
+    state.headingText = contextText(raw);
+    state.parentKind = null;
+    state.parentIndent = null;
+    state.parentText = null;
+    state.parentEntry = null;
+}
+/**
+ * Setext / RST title level by adornment. Markdown fixes `=` at 1 and `-` at 2;
+ * reStructuredText ranks adornments in the order a document first uses them,
+ * so the rest rank below both, in a fixed order: close enough to compare a
+ * sub-heading with the release title above it.
+ */
+function adornmentLevel(ch) {
+    const order = "=-~^*+#\"'";
+    const i = order.indexOf(ch);
+    return i === -1 ? 3 : i + 1;
+}
 /** Parse a changelog into version sections, in document order (usually newest first). */
 export function parseChangelog(text) {
     const lines = text.replace(/\r\n?/g, "\n").split("\n");
@@ -285,31 +324,30 @@ export function parseChangelog(text) {
             const level = atx[1].length;
             if (heading)
                 openSection(state, heading, level);
-            else {
-                flush(state);
-                // "## Migration guide" after the last release must not be read as part of it.
-                // A change-category heading ("## Changed", "## Breaking Changes") at the
-                // release's own level is still inside it: date-fns 3.0.0 writes
-                // "## v3.0.0" then "## Changed", and its ten BREAKING entries were dropped.
-                if (state.current && level <= state.sectionLevel && !isCategoryHeading(atx[2]))
-                    state.current = null;
-                state.headingKind = classifyHeading(atx[2]);
-                state.headingText = contextText(atx[2]);
-                state.parentKind = null;
-                state.parentIndent = null;
-                state.parentText = null;
-                state.parentEntry = null;
-            }
+            else
+                subHeading(state, atx[2], level);
             continue;
         }
         const next = lines[i + 1];
-        if (next !== undefined && SETEXT_RULE.test(next) && line.trim() !== "" && !BULLET.test(line)) {
+        if (next !== undefined && SETEXT_RULE.test(next) && line.trim() !== "" && !BULLET.test(line) && !SETEXT_RULE.test(line)) {
+            const level = adornmentLevel(next.trim()[0]);
             const heading = parseVersionHeading(line);
+            i++;
             if (heading) {
-                openSection(state, heading, next.trim().startsWith("=") ? 1 : 2);
-                i++;
+                openSection(state, heading, level);
                 continue;
             }
+            // A non-release setext / RST title is a sub-heading ("Breaking Changes" over
+            // `~~~~`), as an ATX one is: it was an entry until parser version 3.
+            subHeading(state, line, level, true);
+            continue;
+        }
+        // `Released 2023-09-30` right under an RST release title is its date, not a change (flask, werkzeug, click).
+        const released = state.current && state.current.entries.length === 0 && !state.pending ? RELEASED_LINE.exec(line) : null;
+        if (released && (released[1] === undefined || extractDate(released[1]) || /^(?:unreleased|tbd|-)?$/i.test(released[1].trim()))) {
+            if (released[1])
+                state.current.date ??= extractDate(released[1]);
+            continue;
         }
         // History.md style without an underline: `1.2.3 / 2020-01-01` alone on a line.
         const history = new RegExp(String.raw `^v?(${VERSION})\s+/\s+(.+)$`).exec(line.trim());
@@ -352,10 +390,10 @@ export function parseChangelog(text) {
     flush(state);
     return state.sections;
 }
-/** True when `version` lies in (from, to] by semver precedence; unreadable versions are out. */
-export function inRange(version, from, to) {
-    const lower = compareVersionPrecedence(version, from);
-    const upper = compareVersionPrecedence(version, to);
+/** True when `version` lies in (from, to] by `order`; unreadable versions are out. */
+export function inRange(version, from, to, order = compareVersionPrecedence) {
+    const lower = order(version, from);
+    const upper = order(version, to);
     return lower !== null && upper !== null && lower > 0 && upper <= 0;
 }
 /**
@@ -365,10 +403,10 @@ export function inRange(version, from, to) {
  * stopped being maintained two majors ago is reported as not covering the
  * range instead of silently presenting a partial history as the whole one.
  */
-export function selectRange(sections, from, to, firstInRange) {
-    const readable = sections.filter((s) => compareVersionPrecedence(s.version, s.version) !== null);
-    const selected = readable.filter((s) => inRange(s.version, from, to));
-    const reachesTop = readable.some((s) => (compareVersionPrecedence(s.version, to) ?? -1) >= 0);
-    const reachesBottom = readable.some((s) => (compareVersionPrecedence(s.version, firstInRange) ?? 1) <= 0);
+export function selectRange(sections, from, to, firstInRange, order = compareVersionPrecedence) {
+    const readable = sections.filter((s) => order(s.version, s.version) !== null);
+    const selected = readable.filter((s) => inRange(s.version, from, to, order));
+    const reachesTop = readable.some((s) => (order(s.version, to) ?? -1) >= 0);
+    const reachesBottom = readable.some((s) => (order(s.version, firstInRange) ?? 1) <= 0);
     return { sections: selected, coversRange: selected.length > 0 && reachesTop && reachesBottom };
 }

package/dist/live/fix-paths.js

@@ -39,7 +39,7 @@ const VERSIONS_TTL = 6 * 3600;
 const VERSION_DEPS_TTL = 30 * 86_400;
 const MAX_OSV_PAGES = 10;
 /** Bump when the shape of anything this module caches changes. */
-const CACHE_VERSION = 2;
+const CACHE_VERSION = 3;
 export class FixPathSources {
     cache;
     rateLimiter;

package/dist/live/github-releases.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Opt-in changelog fallback for `upgrade_impact`: GitHub releases, and a
+ * changelog FILE a PyPI project links from `project_urls` when that file is
+ * on GitHub (Decision 1, option B, approved 2026-10-11).
+ *
+ * Off by default. The default contract stays option A: only the package's own
+ * registry and OSV.dev are contacted. A user who wants release notes for the
+ * many packages whose archive ships no changelog (vite, zod, cobra, most Go
+ * modules) sets FOURDA_GITHUB_CHANGELOG=true; GitHub then learns the
+ * repository and the version range, nothing else. GITHUB_TOKEN, when set, is
+ * sent as a bearer token (5,000 requests an hour instead of 60).
+ *
+ * What is parsed is what the project itself published as release notes: the
+ * release body (Markdown), read by the same parser and classifier as an
+ * archive changelog, one section per release whose tag names a version of
+ * this package. A docs page (HTML) is never parsed. Rate limits are reported,
+ * not retried: the answer says when the limit resets and how to raise it.
+ */
+import { type ChangelogSection, type VersionOrder } from "./changelog.js";
+import type { ChangelogResult, UpgradeNet } from "./upgrade-sources.js";
+export declare const GITHUB_CHANGELOG_ENV = "FOURDA_GITHUB_CHANGELOG";
+/** True when the user opted in: FOURDA_GITHUB_CHANGELOG is 1 / true / yes / on. */
+export declare function githubChangelogEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** `owner/repo` of a GitHub URL (https, git+https, git@, shorthand), or null. */
+export declare function parseGithubRepo(url: string | null | undefined): {
+    owner: string;
+    repo: string;
+} | null;
+interface GithubRelease {
+    tag_name?: string;
+    name?: string | null;
+    body?: string | null;
+    draft?: boolean;
+    published_at?: string | null;
+    created_at?: string | null;
+    html_url?: string;
+}
+export declare class GithubRateLimitError extends Error {
+}
+/**
+ * The version a release tag names for this package, or null when the tag is
+ * another package's (monorepos) or not a version. `tagPrefix` is a Go
+ * module's subdirectory (`service/s3`): its tags are `service/s3/v1.2.3`.
+ */
+export declare function versionFromTag(tag: string, pkg: string, tagPrefix: string | null): string | null;
+/** One section per release that names a version of this package, entries parsed from its notes. */
+export declare function releasesToSections(releases: GithubRelease[], pkg: string, tagPrefix: string | null): ChangelogSection[];
+export interface GithubFallbackInput {
+    pkg: string;
+    ecosystem: string;
+    repository: string | null;
+    /** Changelog links the project published (PyPI `project_urls`). */
+    changelogLinks?: string[];
+    from: string;
+    to: string;
+    /** Go: the module's subdirectory in its repository, which prefixes its tags. */
+    tagPrefix?: string | null;
+    order: VersionOrder;
+}
+/** `https://github.com/o/r/blob/<ref>/<path>` (or raw.githubusercontent.com) to a raw file URL, when it names a changelog file. */
+export declare function rawChangelogUrl(link: string): string | null;
+export declare function githubCacheKey(kind: string, where: string, input: GithubFallbackInput): string;
+/**
+ * The fallback: a GitHub changelog file the project links (PyPI), then the
+ * repository's releases. Caller checks the opt-in. Returns a not-found result
+ * with the reason (no GitHub repository, rate limit, no matching releases).
+ */
+export declare function getGithubChangelog(net: UpgradeNet, input: GithubFallbackInput): Promise<ChangelogResult>;
+export {};

package/dist/live/github-releases.js

@@ -0,0 +1,252 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Opt-in changelog fallback for `upgrade_impact`: GitHub releases, and a
+ * changelog FILE a PyPI project links from `project_urls` when that file is
+ * on GitHub (Decision 1, option B, approved 2026-10-11).
+ *
+ * Off by default. The default contract stays option A: only the package's own
+ * registry and OSV.dev are contacted. A user who wants release notes for the
+ * many packages whose archive ships no changelog (vite, zod, cobra, most Go
+ * modules) sets FOURDA_GITHUB_CHANGELOG=true; GitHub then learns the
+ * repository and the version range, nothing else. GITHUB_TOKEN, when set, is
+ * sent as a bearer token (5,000 requests an hour instead of 60).
+ *
+ * What is parsed is what the project itself published as release notes: the
+ * release body (Markdown), read by the same parser and classifier as an
+ * archive changelog, one section per release whose tag names a version of
+ * this package. A docs page (HTML) is never parsed. Rate limits are reported,
+ * not retried: the answer says when the limit resets and how to raise it.
+ */
+import { CHANGELOG_PARSER_VERSION, isChangelogName, parseChangelog } from "./changelog.js";
+import { ArchiveError, MAX_FILE_BYTES } from "./package-archive.js";
+export const GITHUB_CHANGELOG_ENV = "FOURDA_GITHUB_CHANGELOG";
+const CACHE_SOURCE = "upgrade-impact";
+/** A range whose target release is published: release notes rarely change after. */
+const FOUND_TTL = 24 * 3600;
+const MISS_TTL = 3600;
+const PER_PAGE = 100;
+const MAX_PAGES = 5;
+const GITHUB_TIMEOUT_MS = 15_000;
+const USER_AGENT = "4da-mcp-server (https://4da.ai; upgrade_impact)";
+/** True when the user opted in: FOURDA_GITHUB_CHANGELOG is 1 / true / yes / on. */
+export function githubChangelogEnabled(env = process.env) {
+    return /^(?:1|true|yes|on)$/i.test(String(env[GITHUB_CHANGELOG_ENV] ?? "").trim());
+}
+/** `owner/repo` of a GitHub URL (https, git+https, git@, shorthand), or null. */
+export function parseGithubRepo(url) {
+    if (!url)
+        return null;
+    const raw = url.trim();
+    const m = /^(?:github:)?([\w.-]+)\/([\w.-]+)$/.exec(raw) ??
+        /github\.com[/:]([\w.-]+)\/([\w.-]+?)(?:\.git)?(?:[/#?].*)?$/i.exec(raw);
+    if (!m)
+        return null;
+    const repo = m[2].replace(/\.git$/, "");
+    if (!repo || m[1] === "." || repo === "." || repo === "..")
+        return null;
+    return { owner: m[1], repo };
+}
+export class GithubRateLimitError extends Error {
+}
+function headers() {
+    const h = {
+        Accept: "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+        "User-Agent": USER_AGENT,
+    };
+    const token = process.env.GITHUB_TOKEN?.trim();
+    if (token)
+        h.Authorization = `Bearer ${token}`;
+    return h;
+}
+/** A 403/429 that is a rate limit, with when it lifts. */
+function rateLimitMessage(res) {
+    if (res.status !== 403 && res.status !== 429)
+        return null;
+    const remaining = res.headers.get("x-ratelimit-remaining");
+    const retryAfter = res.headers.get("retry-after");
+    if (remaining !== "0" && !retryAfter && res.status !== 429)
+        return null;
+    const reset = Number(res.headers.get("x-ratelimit-reset"));
+    const when = Number.isFinite(reset) && reset > 0
+        ? `resets at ${new Date(reset * 1000).toISOString()}`
+        : retryAfter
+            ? `retry after ${retryAfter} s`
+            : "try again later";
+    const auth = process.env.GITHUB_TOKEN?.trim()
+        ? "GITHUB_TOKEN is set; its hourly limit is spent"
+        : "set GITHUB_TOKEN to raise the limit from 60 to 5,000 requests an hour";
+    return `GitHub API rate limit reached (${when}); ${auth}`;
+}
+const KNOWN_TAG_PREFIX = /^(?:v|version[-_]?|release[-_]?|rel[-_]?)?$/i;
+/**
+ * The version a release tag names for this package, or null when the tag is
+ * another package's (monorepos) or not a version. `tagPrefix` is a Go
+ * module's subdirectory (`service/s3`): its tags are `service/s3/v1.2.3`.
+ */
+export function versionFromTag(tag, pkg, tagPrefix) {
+    let rest = tag.trim();
+    if (tagPrefix) {
+        if (!rest.startsWith(`${tagPrefix}/`))
+            return null;
+        rest = rest.slice(tagPrefix.length + 1);
+    }
+    const m = /^(.*?)(\d+\.\d+(?:\.\d+)*(?:[-.+]?[0-9A-Za-z][0-9A-Za-z.+-]*)?)$/.exec(rest);
+    if (!m)
+        return null;
+    const prefix = m[1];
+    if (KNOWN_TAG_PREFIX.test(prefix))
+        return m[2];
+    // A monorepo tag: `pkg@1.2.3`, `pkg-v1.2.3`, `@scope/pkg@1.2.3`, `pkg/v1.2.3`.
+    const fold = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "");
+    const bare = prefix.replace(/(?:[@/_-]v?|v)$/i, "");
+    const name = pkg.split("/").pop() ?? pkg;
+    return fold(bare) === fold(pkg) || fold(bare) === fold(name) ? m[2] : null;
+}
+/** Release-body lines that are bookkeeping, not changes. */
+const NOISE = /made their first contribution|^\W*full changelog\W|^\W*(?:new )?contributors?\W*$/i;
+/** One section per release that names a version of this package, entries parsed from its notes. */
+export function releasesToSections(releases, pkg, tagPrefix) {
+    const sections = [];
+    for (const r of releases) {
+        if (r.draft || typeof r.tag_name !== "string")
+            continue;
+        const version = versionFromTag(r.tag_name, pkg, tagPrefix);
+        if (!version)
+            continue;
+        const date = (r.published_at ?? r.created_at ?? "").slice(0, 10) || null;
+        // A synthetic heading makes the body one release; a body that repeats its own
+        // version heading opens the same version again, and those entries are kept too.
+        const parsed = parseChangelog(`# ${version}\n\n${(r.body ?? "").slice(0, MAX_FILE_BYTES)}`);
+        const entries = parsed
+            .filter((s, i) => i === 0 || s.version.replace(/^v/, "") === version.replace(/^v/, ""))
+            .flatMap((s) => s.entries)
+            .filter((e) => !NOISE.test(e.text) && !(e.under && /^\W*new contributors\W*$/i.test(e.under)));
+        sections.push({ version, date, entries });
+    }
+    return sections;
+}
+/**
+ * Release notes for `pkg` from `owner/repo`, newest first, paging until a
+ * release at or below `from` is seen (at most MAX_PAGES pages of 100).
+ */
+async function fetchReleases(net, repo, stop, pkg, tagPrefix) {
+    const out = [];
+    for (let page = 1; page <= MAX_PAGES; page++) {
+        const url = `https://api.github.com/repos/${encodeURIComponent(repo.owner)}/${encodeURIComponent(repo.repo)}/releases?per_page=${PER_PAGE}&page=${page}`;
+        const res = await net.fetch(url, { headers: headers() }, GITHUB_TIMEOUT_MS);
+        const limited = rateLimitMessage(res);
+        if (limited)
+            throw new GithubRateLimitError(limited);
+        if (res.status === 404)
+            throw new Error(`github.com/${repo.owner}/${repo.repo} has no public releases API (not found or private)`);
+        if (!res.ok)
+            throw new Error(`GitHub API HTTP ${res.status}`);
+        const batch = (await res.json());
+        if (!Array.isArray(batch))
+            throw new Error("GitHub API returned an unexpected releases payload");
+        out.push(...batch);
+        const reachedFrom = batch.some((r) => {
+            const v = typeof r.tag_name === "string" ? versionFromTag(r.tag_name, pkg, tagPrefix) : null;
+            return v !== null && stop(v);
+        });
+        if (batch.length < PER_PAGE || reachedFrom)
+            break;
+    }
+    return out;
+}
+/** `https://github.com/o/r/blob/<ref>/<path>` (or raw.githubusercontent.com) to a raw file URL, when it names a changelog file. */
+export function rawChangelogUrl(link) {
+    let m = /^https:\/\/github\.com\/([\w.-]+)\/([\w.-]+)\/(?:blob|raw)\/([^?#]+)$/i.exec(link.trim());
+    let rawUrl = m ? `https://raw.githubusercontent.com/${m[1]}/${m[2]}/${m[3]}` : null;
+    if (!rawUrl) {
+        m = /^https:\/\/raw\.githubusercontent\.com\/[\w.-]+\/[\w.-]+\/[^?#]+$/i.exec(link.trim());
+        rawUrl = m ? link.trim() : null;
+    }
+    if (!rawUrl)
+        return null;
+    const base = rawUrl.split("/").pop() ?? "";
+    return isChangelogName(base) ? rawUrl : null;
+}
+async function fetchChangelogFile(net, url) {
+    const res = await net.fetch(url, { headers: { "User-Agent": USER_AGENT } }, GITHUB_TIMEOUT_MS);
+    const limited = rateLimitMessage(res);
+    if (limited)
+        throw new GithubRateLimitError(limited);
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status} for ${url}`);
+    const declared = Number(res.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > MAX_FILE_BYTES)
+        throw new ArchiveError(`${url} is over ${MAX_FILE_BYTES} bytes`);
+    const text = await res.text();
+    if (text.length > MAX_FILE_BYTES)
+        throw new ArchiveError(`${url} is over ${MAX_FILE_BYTES} bytes`);
+    return parseChangelog(text);
+}
+function inRangeCount(sections, from, to, order) {
+    return sections.filter((s) => (order(s.version, from) ?? 0) > 0 && (order(s.version, to) ?? 1) <= 0).length;
+}
+export function githubCacheKey(kind, where, input) {
+    return `upgrade-impact:github:p${CHANGELOG_PARSER_VERSION}:${kind}:${where}:${input.tagPrefix ?? ""}:${input.ecosystem}:${input.pkg}:${input.from}:${input.to}`;
+}
+/**
+ * The fallback: a GitHub changelog file the project links (PyPI), then the
+ * repository's releases. Caller checks the opt-in. Returns a not-found result
+ * with the reason (no GitHub repository, rate limit, no matching releases).
+ */
+export async function getGithubChangelog(net, input) {
+    const reasons = [];
+    for (const link of input.changelogLinks ?? []) {
+        const raw = rawChangelogUrl(link);
+        if (!raw)
+            continue;
+        const key = githubCacheKey("file", raw, input);
+        const hit = net.cache?.get(key);
+        if (hit)
+            return hit;
+        try {
+            const sections = await fetchChangelogFile(net, raw);
+            if (inRangeCount(sections, input.from, input.to, input.order) > 0) {
+                const result = { found: true, file: raw.split("/").pop(), sections, source: "github-file", url: link };
+                net.cache?.set(key, result, CACHE_SOURCE, FOUND_TTL);
+                return result;
+            }
+            reasons.push(`the changelog the project links (${link}) has no section for these releases`);
+        }
+        catch (err) {
+            if (err instanceof GithubRateLimitError)
+                return { found: false, reason: err.message };
+            reasons.push(`the changelog the project links could not be read: ${err.message}`);
+        }
+    }
+    const repo = parseGithubRepo(input.repository);
+    if (!repo) {
+        reasons.push("the package names no GitHub repository, so there are no GitHub releases to read");
+        return { found: false, reason: reasons.join("; ") };
+    }
+    const where = `${repo.owner}/${repo.repo}`;
+    const key = githubCacheKey("releases", where, input);
+    const hit = net.cache?.get(key);
+    if (hit)
+        return hit;
+    const releasesUrl = `https://github.com/${where}/releases`;
+    try {
+        const releases = await fetchReleases(net, repo, (v) => (input.order(v, input.from) ?? 1) <= 0, input.pkg, input.tagPrefix ?? null);
+        const sections = releasesToSections(releases, input.pkg, input.tagPrefix ?? null);
+        const hits = inRangeCount(sections, input.from, input.to, input.order);
+        const result = hits > 0
+            ? { found: true, file: "GitHub releases", sections, source: "github-releases", url: releasesUrl }
+            : {
+                found: false,
+                url: releasesUrl,
+                reason: [...reasons, `${where} has no GitHub release for ${input.pkg} between ${input.from} and ${input.to}`].join("; "),
+            };
+        const targetFound = sections.some((s) => input.order(s.version, input.to) === 0);
+        net.cache?.set(key, result, CACHE_SOURCE, targetFound ? FOUND_TTL : MISS_TTL);
+        return result;
+    }
+    catch (err) {
+        // A rate limit or network failure is not remembered: the next call may succeed.
+        return { found: false, url: releasesUrl, reason: [...reasons, `GitHub releases could not be read: ${err.message}`].join("; ") };
+    }
+}

package/dist/live/go-releases.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Go module release index for dependency_check, from the module proxy
+ * (proxy.golang.org, the host `go get` downloads from):
+ *
+ * - `/@v/list`: the tagged versions, `+incompatible` ones included (a module
+ *   that predates modules and tags v2+ without a `/v2` path).
+ * - `/@v/<version>.info`: one release's time. The list carries no dates, so
+ *   this is read for the versions being judged only (cached; a published
+ *   version never changes). A pseudo-version (`v0.0.0-20240102150405-abcdef123456`)
+ *   is not in the list; its `.info` both confirms it exists and dates it.
+ * - The latest version's `go.mod`: its `retract` directives withdraw versions
+ *   (`go get` skips them), reported like a yank.
+ * - An untagged module: `@latest` gives its newest pseudo-version.
+ *
+ * Major versions 2+ are different module paths (`.../v5`); the proxy lists
+ * each path's own versions only.
+ *
+ * Not applicable to Go and reported so by the signals: publisher identity
+ * (integrity is checked against sum.golang.org instead), install hooks (Go
+ * runs no package code at download), per-release dependency lists.
+ */
+import type { LiveCache } from "./cache.js";
+import type { RateLimiter } from "./rate-limiter.js";
+import type { PackageReleaseIndex, RegistryLookup, ReleaseMetadataSource } from "./release-metadata.js";
+export declare const GO_NOT_APPLICABLE = "not applicable to Go modules: the proxy carries no publisher identity (downloads are checked against sum.golang.org)";
+/** A Go version: release, prerelease, pseudo-version, optional `+incompatible`. */
+export declare const GO_VERSION: RegExp;
+/** `v`-prefixed spelling of a Go version ("1.2.3" -> "v1.2.3"). */
+export declare function goVersion(raw: string): string;
+/** The commit time a pseudo-version embeds, as ISO, or null when `version` is not one. */
+export declare function pseudoVersionTime(version: string): string | null;
+export interface Retraction {
+    low: string;
+    high: string;
+    rationale: string | null;
+}
+/** `retract` directives of a go.mod: single versions, `[low, high]` intervals, and blocks of either. */
+export declare function parseRetractions(goMod: string): Retraction[];
+export declare class GoReleasesReader implements ReleaseMetadataSource {
+    private cache;
+    private rateLimiter;
+    constructor(cache: LiveCache, rateLimiter: RateLimiter);
+    getReleases(module: string, wanted: string[]): Promise<RegistryLookup<PackageReleaseIndex>>;
+    getCreatedAt(): Promise<RegistryLookup<string | null>>;
+    private list;
+    private info;
+    private get;
+}