@dep-radius/core 0.1.0

package/dist/notes/collect.js

@@ -0,0 +1,225 @@
+import semver from "semver";
+import { splitEntries } from "./entries.js";
+import { parseRepository } from "./repo-url.js";
+import { changelogSections } from "./changelog.js";
+import { CHANGELOG_FILE, getTarballFiles } from "../registry/tarball.js";
+import { githubState, rawChangelog, releaseByTag, releasesPage, tagCandidates, } from "./github.js";
+const MAX_TAG_LOOKUPS = 12;
+export async function collectNotes(ctx, cfg, p, c) {
+    const versions = c.range;
+    const bodies = new Map();
+    const failures = new Map();
+    const missing = () => versions.filter((v) => !bodies.has(v));
+    // a major lists its breaking changes in its betas more often than in its x.0.0: read them wherever
+    // a source is already open, never at the cost of a request, and never counted in the coverage
+    const pre = prereleasesIn(p, versions);
+    const preBodies = new Map();
+    const takePre = (sections) => {
+        for (const v of pre) {
+            const body = sections.get(v);
+            if (body?.trim() && !preBodies.has(v))
+                preBodies.set(v, body);
+        }
+    };
+    // 1. a changelog shipped inside the target tarball covers every version up to it, for free
+    const target = p.versions[c.to];
+    if (target) {
+        const tb = await getTarballFiles(ctx, cfg, target);
+        if (tb.ok) {
+            for (const [path, buf] of tb.files) {
+                if (!CHANGELOG_FILE.test(path))
+                    continue;
+                const sections = changelogSections(buf.toString("utf8"));
+                takePre(sections);
+                for (const v of missing()) {
+                    const body = sections.get(v);
+                    if (body !== undefined && body.trim())
+                        bodies.set(v, {
+                            kind: "tarball-changelog",
+                            url: `${c.pkg}@${c.to}/${path}`,
+                            body,
+                        });
+                }
+            }
+        }
+        else if (tb.reason === "offline-uncached") {
+            for (const v of missing())
+                failures.set(v, "offline");
+        }
+    }
+    // 2. GitHub releases
+    const repo = parseRepository(target?.repository ?? p.repository);
+    let repoReachable = false;
+    if (missing().length > 0) {
+        if (!repo)
+            for (const v of missing())
+                failures.set(v, "no-repo");
+        else if (repo.host !== "github")
+            for (const v of missing())
+                failures.set(v, "unsupported-host");
+        else {
+            const page = await releasesPage(ctx, repo);
+            if (page.ok) {
+                repoReachable = true;
+                const byTag = new Map(page.value.map((r) => [r.tag, r]));
+                let scheme;
+                for (const v of versions) {
+                    const cands = tagCandidates(c.pkg, v);
+                    const hit = cands.findIndex((t) => byTag.has(t));
+                    if (hit >= 0) {
+                        scheme ??= hit;
+                        const rel = byTag.get(cands[hit]);
+                        if (!bodies.has(v))
+                            acceptRelease(v, rel, repo.owner, repo.repo);
+                    }
+                }
+                for (const v of pre) {
+                    const rel = tagCandidates(c.pkg, v)
+                        .map((t) => byTag.get(t))
+                        .find(Boolean);
+                    if (rel && !preBodies.has(v) && !isPointerOnly(rel.body))
+                        preBodies.set(v, rel.body);
+                }
+                // versions pushed off the first page: look them up by tag, with the scheme the page taught us
+                let lookups = 0;
+                for (const v of missing()) {
+                    if (lookups >= MAX_TAG_LOOKUPS)
+                        break;
+                    const cands = tagCandidates(c.pkg, v);
+                    const tries = scheme !== undefined ? [cands[scheme]] : cands.slice(0, 3);
+                    for (const tag of tries) {
+                        lookups++;
+                        const r = await releaseByTag(ctx, repo, tag);
+                        if (r.ok) {
+                            acceptRelease(v, r.value, repo.owner, repo.repo);
+                            break;
+                        }
+                        if (r.reason !== "not-found") {
+                            failures.set(v, r.reason === "offline"
+                                ? "offline"
+                                : r.reason === "rate-limited"
+                                    ? "rate-limited"
+                                    : "http-error");
+                            break;
+                        }
+                    }
+                }
+            }
+            else if (page.reason === "not-found") {
+                repoReachable = true;
+            }
+            else {
+                for (const v of missing())
+                    failures.set(v, page.reason === "offline"
+                        ? "offline"
+                        : page.reason === "rate-limited"
+                            ? "rate-limited"
+                            : "http-error");
+            }
+            // 3. the repository's changelog
+            if (missing().length > 0) {
+                const raw = await rawChangelog(ctx, repo);
+                if (raw.ok) {
+                    repoReachable = true;
+                    const sections = changelogSections(raw.value.text);
+                    takePre(sections);
+                    for (const v of missing()) {
+                        const body = sections.get(v);
+                        if (body !== undefined && body.trim()) {
+                            bodies.set(v, {
+                                kind: "repo-changelog",
+                                url: raw.value.url,
+                                body,
+                            });
+                            failures.delete(v);
+                        }
+                    }
+                }
+                else if (raw.reason === "not-found") {
+                    repoReachable = true;
+                }
+            }
+        }
+    }
+    function acceptRelease(v, r, owner, name) {
+        if (isPointerOnly(r.body)) {
+            failures.set(v, "stub-body");
+            return;
+        }
+        bodies.set(v, {
+            kind: "github-release",
+            url: `https://github.com/${owner}/${name}/releases/tag/${encodeURIComponent(r.tag)}`,
+            body: r.body,
+        });
+        failures.delete(v);
+    }
+    const perVersion = versions.map((v) => {
+        const b = bodies.get(v);
+        if (b)
+            return {
+                version: v,
+                status: "found",
+                source: { kind: b.kind, url: b.url },
+            };
+        const reason = failures.get(v);
+        if (reason && reason !== "stub-body")
+            return { version: v, status: "unavailable", reason };
+        return repoReachable || reason === "stub-body"
+            ? { version: v, status: "not-published", ...(reason ? { reason } : {}) }
+            : {
+                version: v,
+                status: "unavailable",
+                reason: reason ?? (githubState.rateLimited ? "rate-limited" : "no-repo"),
+            };
+    });
+    const entries = [...versions, ...preBodies.keys()]
+        .sort(semver.compare)
+        .flatMap((v) => {
+        const body = bodies.get(v)?.body ?? preBodies.get(v);
+        return body ? splitEntries(v, body) : [];
+    });
+    const found = perVersion.filter((x) => x.status === "found").length;
+    const unavailable = perVersion.filter((x) => x.status === "unavailable").length;
+    let coverage;
+    if (versions.length === 0 || found === versions.length)
+        coverage = "complete";
+    else if (found > 0)
+        coverage = "partial";
+    else if (unavailable > 0)
+        coverage = "unavailable";
+    else
+        coverage = "none-published";
+    return { perVersion, entries, coverage };
+}
+// "**Change log available at** <link>" and GitHub's "**Full Changelog**: v1...v2" read as notes and
+// say nothing. Counted as found, they let a major release pass as quiet on no information, so a
+// body is a pointer once its links are gone and what is left only points elsewhere.
+export function isPointerOnly(body) {
+    const text = body
+        .replace(/<!--[\s\S]*?-->/g, "")
+        .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+        .replace(/https?:\/\/\S+/g, "")
+        .replace(/^\s*\**\s*full changelog\s*\**\s*:?.*$/gim, "")
+        .replace(/[*_#>`]/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!text)
+        return true;
+    return (text.length < 120 &&
+        /change ?log|release notes|see |available (at|on|here)|upgrade guide|migration guide|blog post|details/i.test(text));
+}
+const PRERELEASE_TAG = /^(alpha|beta|rc|pre|preview)$/i;
+// Betas, release candidates and alphas of the stable versions in range. Canaries, nightlies and
+// dated builds are left out: a busy package publishes hundreds of them.
+export function prereleasesIn(p, stable) {
+    const inRange = new Set(stable);
+    return Object.keys(p.versions)
+        .filter((v) => {
+        const tags = semver.prerelease(v);
+        if (!tags || !PRERELEASE_TAG.test(String(tags[0])))
+            return false;
+        return inRange.has(`${semver.major(v)}.${semver.minor(v)}.${semver.patch(v)}`);
+    })
+        .sort(semver.compare)
+        .slice(-20);
+}

package/dist/notes/entries.d.ts

@@ -0,0 +1,3 @@
+import type { NoteEntry } from "../model.ts";
+export declare function splitEntries(version: string, markdown: string): NoteEntry[];
+//# sourceMappingURL=entries.d.ts.map

package/dist/notes/entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entries.d.ts","sourceRoot":"","sources":["../../src/notes/entries.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAA;AAmBxD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,CAkG3E"}

package/dist/notes/entries.js

@@ -0,0 +1,209 @@
+import { sha1 } from "../infra/hash.js";
+// A heading says a whole section breaks; a title has to lead with it. "non-breaking" and a bullet that
+// merely mentions breaking somewhere in its prose are not markers.
+const BREAKING_HEADING = /(?<!non[- ])breaking|⚠️|:warning:|major changes/i;
+const BREAKING_TITLE = /^\s*(\*\*|\[|\()?\s*(⚠️|:warning:|breaking|💥|:boom:)|BREAKING CHANGE/i;
+const NOISE = /^(ci|chore|test|tests|docs|doc|build|style|refactor|perf\(bench\)|release|revert)(\([^)]*\))?!?:|^(deps?|dependencies)(\([^)]*\))?:|^bump\s+\S+\s+from\s|^merge (pull request|branch)|^update dependency\b|^v?\d+\.\d+\.\d+$/i;
+// One markdown body (a release, or a changelog section) into entries: a top-level bullet with its
+// nested lines, a heading whose body is prose or code, or a stray paragraph.
+export function splitEntries(version, markdown) {
+    const drafts = [];
+    const stack = [];
+    let current;
+    let headingDraft;
+    let inFence = false;
+    let blankRun = 0;
+    const close = () => {
+        if (current && (current.kind !== "heading" || current.lines.length > 0))
+            drafts.push(current);
+        current = undefined;
+    };
+    const path = () => stack.map((s) => s.text);
+    const lines = preprocess(markdown).split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (/^\s*(```|~~~)/.test(line)) {
+            inFence = !inFence;
+            if (!current) {
+                current =
+                    headingDraft && !drafts.includes(headingDraft)
+                        ? headingDraft
+                        : newDraft("paragraph", firstWords(line), path());
+            }
+            continue;
+        }
+        if (inFence) {
+            current?.lines.push({ text: line, code: true });
+            continue;
+        }
+        const atx = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line);
+        const setext = !atx &&
+            line.trim() &&
+            lines[i + 1] !== undefined &&
+            /^(=+|-{3,})\s*$/.test(lines[i + 1]) &&
+            !/^\s*[-*+]\s/.test(line);
+        if (atx || setext) {
+            close();
+            const level = atx ? atx[1].length : lines[i + 1].startsWith("=") ? 1 : 2;
+            const text = clean(atx ? atx[2] : line.trim());
+            while (stack.length > 0 && stack[stack.length - 1].level >= level)
+                stack.pop();
+            headingDraft = newDraft("heading", text, path());
+            stack.push({ level, text });
+            current = headingDraft;
+            if (setext)
+                i++;
+            blankRun = 0;
+            continue;
+        }
+        if (!line.trim()) {
+            blankRun++;
+            continue;
+        }
+        const bullet = /^(\s{0,1})([-*+]|\d+[.)])\s+(.*)$/.exec(line);
+        const indent = line.length - line.trimStart().length;
+        if (bullet) {
+            close();
+            current = newDraft("bullet", clean(bullet[3] ?? ""), path());
+            blankRun = 0;
+            continue;
+        }
+        if (current?.kind === "bullet" && (indent >= 2 || blankRun === 0)) {
+            current.lines.push({ text: line, code: false });
+            blankRun = 0;
+            continue;
+        }
+        if (current?.kind === "heading" || current?.kind === "paragraph") {
+            current.lines.push({ text: line, code: false });
+            blankRun = 0;
+            continue;
+        }
+        close();
+        current = newDraft("paragraph", clean(firstSentence(line)), path());
+        current.lines.push({ text: line, code: false });
+        blankRun = 0;
+    }
+    close();
+    const kept = drafts.filter((d) => d.title || d.lines.some((l) => l.text.trim()));
+    // an "at a glance" bullet that restates a section of the same release: the section is the entry
+    const headingTitles = kept
+        .filter((d) => d.kind === "heading")
+        .map((d) => normTitle(d.title));
+    const entries = kept
+        .filter((d) => d.kind !== "bullet" ||
+        !headingTitles.some((h) => h.length >= 3 && startsWithTitle(normTitle(d.title), h)))
+        .map((d, index) => toEntry(version, d, index));
+    return dedupeByRefs(entries);
+}
+function normTitle(s) {
+    return s
+        .replace(/[`*_]|\u26A0\uFE0F?/gu, "")
+        .replace(/\s+/g, " ")
+        .trim()
+        .toLowerCase();
+}
+function startsWithTitle(bullet, heading) {
+    return (bullet === heading ||
+        (bullet.startsWith(heading) &&
+            /^[\s—–:(-]/.test(bullet.slice(heading.length))));
+}
+function newDraft(kind, title, headingPath) {
+    return { kind, title, headingPath, lines: [] };
+}
+function toEntry(version, d, index) {
+    const regions = [];
+    const pushText = (text, kind) => {
+        const parts = text.split(/(`[^`]+`)/);
+        for (const p of parts) {
+            if (!p)
+                continue;
+            if (p.startsWith("`") && p.endsWith("`") && p.length > 1)
+                regions.push({ kind: "inline-code", text: p.slice(1, -1) });
+            else if (p.trim())
+                regions.push({ kind, text: p });
+        }
+    };
+    pushText(d.title, "title");
+    let code = [];
+    const flush = () => {
+        if (code.length > 0)
+            regions.push({ kind: "code-block", text: code.join("\n") });
+        code = [];
+    };
+    for (const l of d.lines) {
+        if (l.code)
+            code.push(l.text);
+        else {
+            flush();
+            pushText(clean(l.text), "prose");
+        }
+    }
+    flush();
+    const all = [d.title, ...d.lines.map((l) => l.text)].join("\n");
+    const refs = [
+        ...new Set([...all.matchAll(/(?<![\w/])#(\d{1,7})\b/g)].map((m) => `#${m[1]}`)),
+    ];
+    const bareTitle = d.title
+        .replace(/`/g, "")
+        .replace(/^[0-9a-f]{7,40}\s+/, "")
+        .replace(/^\*\*[^*]+\*\*:?\s*/, "");
+    const titleForDisplay = d.title.replace(/`/g, "");
+    return {
+        id: sha1(`${version}\0${index}\0${all}`).slice(0, 12),
+        version,
+        title: titleForDisplay.length > 200
+            ? `${titleForDisplay.slice(0, 197)}...`
+            : titleForDisplay,
+        headingPath: d.headingPath,
+        regions,
+        breakingMarker: BREAKING_TITLE.test(d.title) ||
+            d.headingPath.some((h) => BREAKING_HEADING.test(h)),
+        noise: NOISE.test(bareTitle.trim()) ||
+            d.headingPath.some((h) => /^(commits|contributors|new contributors)$/i.test(h.trim())),
+        refs,
+    };
+}
+// The "Commits" list of a release repeats the pull requests the sections already describe.
+function dedupeByRefs(entries) {
+    const covered = new Set();
+    for (const e of entries)
+        if (!e.noise &&
+            e.refs.length > 0 &&
+            e.regions.some((r) => r.kind !== "title"))
+            for (const r of e.refs)
+                covered.add(r);
+    return entries.filter((e) => !(e.refs.length > 0 &&
+        e.refs.every((r) => covered.has(r)) &&
+        e.regions.every((r) => r.kind === "title" || r.kind === "inline-code") &&
+        isShadowed(e, entries)));
+}
+function isShadowed(e, entries) {
+    return entries.some((o) => o !== e &&
+        o.regions.length > e.regions.length &&
+        e.refs.every((r) => o.refs.includes(r)));
+}
+function preprocess(md) {
+    return (md
+        .replace(/<!--[\s\S]*?-->/g, "")
+        // a pull request URL is a ref, keep it as one before links are dropped
+        .replace(/https?:\/\/github\.com\/[\w.-]+\/[\w.-]+\/(?:pull|issues)\/(\d+)/g, "#$1")
+        .replace(/!\[[^\]]*\]\([^)]*\)/g, "")
+        .replace(/<img\b[^>]*>/gi, "")
+        .replace(/<\/?(details|summary|p|div|br|sup|sub|b|i|em|strong|span|a)\b[^>]*>/gi, " "));
+}
+function clean(s) {
+    return s
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+        .replace(/\[([^\]]+)\]\[[^\]]*\]/g, "$1")
+        .replace(/https?:\/\/\S+/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function firstSentence(s) {
+    const t = clean(s);
+    const m = /^(.{20,160}?[.!?])(\s|$)/.exec(t);
+    return m?.[1] ?? t.slice(0, 160);
+}
+function firstWords(s) {
+    return s.replace(/[`~]/g, "").trim().slice(0, 40);
+}

package/dist/notes/github.d.ts

@@ -0,0 +1,25 @@
+import type { Ctx } from "../options.ts";
+import type { RepoRef } from "./repo-url.ts";
+export interface Release {
+    tag: string;
+    body: string;
+}
+export type Fetched<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reason: "offline" | "rate-limited" | "http-error" | "not-found";
+};
+export declare const githubState: {
+    rateLimited: boolean;
+    usedToken: boolean;
+};
+export declare function releasesPage(ctx: Ctx, repo: RepoRef): Promise<Fetched<Release[]>>;
+export declare function releaseByTag(ctx: Ctx, repo: RepoRef, tag: string): Promise<Fetched<Release>>;
+export declare function rawChangelog(ctx: Ctx, repo: RepoRef): Promise<Fetched<{
+    url: string;
+    text: string;
+}>>;
+export declare function tagCandidates(pkg: string, version: string): string[];
+//# sourceMappingURL=github.d.ts.map

package/dist/notes/github.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../../src/notes/github.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAA;AAExC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAG5C,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,MAAM,OAAO,CAAC,CAAC,IACjB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACtB;IACE,EAAE,EAAE,KAAK,CAAA;IACT,MAAM,EAAE,SAAS,GAAG,cAAc,GAAG,YAAY,GAAG,WAAW,CAAA;CAChE,CAAA;AAML,eAAO,MAAM,WAAW;;;CAA2C,CAAA;AA2DnE,wBAAsB,YAAY,CAChC,GAAG,EAAE,GAAG,EACR,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAc7B;AAED,wBAAsB,YAAY,CAChC,GAAG,EAAE,GAAG,EACR,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAY3B;AAGD,wBAAsB,YAAY,CAChC,GAAG,EAAE,GAAG,EACR,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CA8CjD;AAGD,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAWpE"}

package/dist/notes/github.js

@@ -0,0 +1,132 @@
+import { safeKey } from "../infra/cache.js";
+import { OfflineError } from "../infra/http.js";
+const PAGE_TTL = 60 * 60 * 1000;
+const BODY_TTL = 24 * 60 * 60 * 1000;
+const MISS_TTL = 6 * 60 * 60 * 1000;
+export const githubState = { rateLimited: false, usedToken: false };
+async function apiGet(ctx, path, ttl, missTtl) {
+    const key = `github/${safeKey(path)}.json`;
+    const cached = await ctx.cache.getJson(key);
+    if (cached &&
+        (ctx.offline ||
+            ctx.now - cached.storedAt < (cached.value.found ? ttl : missTtl))) {
+        return cached.value.found
+            ? { ok: true, value: cached.value.data }
+            : { ok: false, reason: "not-found" };
+    }
+    if (ctx.offline)
+        return { ok: false, reason: "offline" };
+    if (githubState.rateLimited)
+        return { ok: false, reason: "rate-limited" };
+    const token = await ctx.githubToken();
+    if (token)
+        githubState.usedToken = true;
+    const headers = {
+        accept: "application/vnd.github+json",
+        "x-github-api-version": "2022-11-28",
+        "user-agent": "dep-radius",
+        ...(token ? { authorization: `Bearer ${token}` } : {}),
+    };
+    try {
+        const res = await ctx.github(() => ctx.http.get({ url: `https://api.github.com${path}`, headers }));
+        if ((res.status === 403 || res.status === 429) &&
+            res.headers["x-ratelimit-remaining"] === "0") {
+            githubState.rateLimited = true;
+            return { ok: false, reason: "rate-limited" };
+        }
+        if (res.status === 404) {
+            await ctx.cache.setJson(key, { found: false }, ctx.now);
+            return { ok: false, reason: "not-found" };
+        }
+        if (res.status !== 200)
+            return { ok: false, reason: "http-error" };
+        const data = JSON.parse(res.body.toString("utf8"));
+        await ctx.cache.setJson(key, { found: true, data }, ctx.now);
+        return { ok: true, value: data };
+    }
+    catch (error) {
+        if (cached?.value.found)
+            return { ok: true, value: cached.value.data };
+        return {
+            ok: false,
+            reason: error instanceof OfflineError ? "offline" : "http-error",
+        };
+    }
+}
+export async function releasesPage(ctx, repo) {
+    const r = await apiGet(ctx, `/repos/${repo.owner}/${repo.repo}/releases?per_page=100`, PAGE_TTL, PAGE_TTL);
+    if (!r.ok)
+        return r;
+    return {
+        ok: true,
+        value: r.value
+            .filter((x) => !x.draft)
+            .map((x) => ({ tag: x.tag_name, body: x.body ?? "" })),
+    };
+}
+export async function releaseByTag(ctx, repo, tag) {
+    const r = await apiGet(ctx, `/repos/${repo.owner}/${repo.repo}/releases/tags/${encodeURIComponent(tag)}`, BODY_TTL, MISS_TTL);
+    if (!r.ok)
+        return r;
+    return {
+        ok: true,
+        value: { tag: r.value.tag_name, body: r.value.body ?? "" },
+    };
+}
+// raw.githubusercontent.com costs no API quota.
+export async function rawChangelog(ctx, repo) {
+    const dirs = [...new Set([repo.directory, undefined])];
+    const names = ["CHANGELOG.md", "HISTORY.md", "History.md", "CHANGES.md"];
+    let sawError;
+    for (const dir of dirs) {
+        for (const name of names) {
+            const url = `https://raw.githubusercontent.com/${repo.owner}/${repo.repo}/HEAD/${dir ? `${dir}/` : ""}${name}`;
+            const key = `raw/${safeKey(url)}.json`;
+            const cached = await ctx.cache.getJson(key);
+            if (cached &&
+                (ctx.offline ||
+                    ctx.now - cached.storedAt <
+                        (cached.value.found ? BODY_TTL : MISS_TTL))) {
+                if (cached.value.found)
+                    return { ok: true, value: { url, text: cached.value.text ?? "" } };
+                continue;
+            }
+            if (ctx.offline) {
+                sawError = { ok: false, reason: "offline" };
+                continue;
+            }
+            try {
+                const res = await ctx.net(() => ctx.http.get({ url, headers: { "user-agent": "dep-radius" } }));
+                if (res.status === 200) {
+                    const text = res.body.toString("utf8");
+                    await ctx.cache.setJson(key, { found: true, text }, ctx.now);
+                    return { ok: true, value: { url, text } };
+                }
+                if (res.status === 404)
+                    await ctx.cache.setJson(key, { found: false }, ctx.now);
+                else
+                    sawError = { ok: false, reason: "http-error" };
+            }
+            catch (error) {
+                sawError = {
+                    ok: false,
+                    reason: error instanceof OfflineError ? "offline" : "http-error",
+                };
+            }
+        }
+    }
+    return sawError ?? { ok: false, reason: "not-found" };
+}
+// Fixed order: an index into this list is the "scheme" learned from a repository's tags.
+export function tagCandidates(pkg, version) {
+    const unscoped = pkg.includes("/") ? pkg.split("/")[1] : pkg;
+    return [
+        `v${version}`,
+        version,
+        `${pkg}@${version}`,
+        `${unscoped}@${version}`,
+        `${pkg}-v${version}`,
+        `${unscoped}-v${version}`,
+        `release-${version}`,
+    ];
+}

package/dist/notes/match.d.ts

@@ -0,0 +1,13 @@
+import type { NoteEntry, NoteMatch } from "../model.ts";
+export declare function isCodeShaped(name: string): boolean;
+export interface MatchResult {
+    matched: NoteMatch[];
+    unattributedBreaking: NoteEntry[];
+    total: number;
+}
+export interface MatchOptions {
+    demoteShare?: number;
+}
+export declare const DEMOTE_SHARE = 0.25;
+export declare function matchNotes(entries: NoteEntry[], strong: string[], weak: string[], options?: MatchOptions): MatchResult;
+//# sourceMappingURL=match.d.ts.map

package/dist/notes/match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.d.ts","sourceRoot":"","sources":["../../src/notes/match.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAW,SAAS,EAAc,MAAM,aAAa,CAAA;AAK5E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AA0BD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,SAAS,EAAE,CAAA;IACpB,oBAAoB,EAAE,SAAS,EAAE,CAAA;IACjC,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,YAAY;IAG3B,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,eAAO,MAAM,YAAY,OAAO,CAAA;AAEhC,wBAAgB,UAAU,CACxB,OAAO,EAAE,SAAS,EAAE,EACpB,MAAM,EAAE,MAAM,EAAE,EAChB,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE,YAAiB,GACzB,WAAW,CA8Db"}