sprag-cli 3.45.0 → 3.46.1

package/src/update-check.js

@@ -10,7 +10,16 @@
  *
  * State lives next to the other user-data files:
  *   { checkedAt: <ms>, latest: "3.25.0", current: "3.24.0",
- *     dismissedVersion: "3.25.0"|undefined }
+ *     dismissedVersion: "3.25.0"|undefined,
+ *     highlights: ["…", "…"]|undefined, highlightsFor: "3.25.0"|undefined }
+ *
+ * `highlights` is what the new version actually adds, read from the GitHub
+ * release for that tag. A bare "v3.24 → v3.25 is available" gives the user
+ * nothing to weigh: the answer to "should I upgrade" is in what changed, and
+ * asking them to go find that themselves is how an upgrade notice becomes
+ * something to dismiss. The release body is fetched on the same detached,
+ * once-a-day pass as the version check, and its absence never blocks the
+ * notice — a version number alone is still worth saying.
  *
  * Opt out with CTS_NO_UPDATE_CHECK=1 or NO_UPDATE_NOTIFIER (the de-facto
  * standard env var — anyone who set it for other CLIs meant us too).
@@ -102,6 +111,11 @@ export function updateStatus(currentVersion) {
     // means "ask me again in five minutes", forever.
     dismissed: available && s.dismissedVersion === latest,
     stale: age >= CHECK_INTERVAL_MS,
+    // Only when they describe THIS version. A cache written for an earlier
+    // release would otherwise sell the wrong upgrade. Language is not checked
+    // here: a mismatch is corrected by the next refresh, and showing the other
+    // language in the meantime beats showing nothing.
+    highlights: Array.isArray(s.highlights) && s.highlightsFor === latest ? s.highlights : [],
   };
 }
 
@@ -143,6 +157,139 @@ export function cliEntryPath() {
   return join(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'cli.js');
 }
 
+// Release notes come from the repository's own releases, because the registry
+// does not carry them: `/latest` answers with package metadata and no changelog
+// of any kind. Unauthenticated reads are allowed at 60/hour, and this runs once
+// a day behind the same interval as the version check, so the budget is ample.
+const RELEASES_API = 'https://api.github.com/repos/rootstudioyaml/sprag/releases/tags';
+const MAX_HIGHLIGHTS = 3;
+const MAX_HIGHLIGHT_LEN = 110;
+
+/**
+ * A release body may carry both languages, English first and Korean under a
+ * heading of its own. Read only the half that matches the reader: mixing them
+ * would put the same change on two of the three lines the notice has room for,
+ * and showing English to someone who set `lang=ko` wastes the notice entirely.
+ *
+ * The Korean half starts at a heading whose text is Korean; everything before
+ * that first Korean heading is the English half. A body in one language only has
+ * no such heading, so English readers get all of it and Korean readers fall back
+ * to the same text rather than to nothing.
+ *
+ * @param {string} body
+ * @param {string} lang - 'ko' | 'en'
+ * @returns {string} the half to read
+ */
+function sectionForLang(body, lang) {
+  const lines = body.split(/\r?\n/);
+  const at = lines.findIndex((l) => /^#{1,6}\s/.test(l) && /[가-힣]/.test(l));
+  if (at < 0) return body;
+  return lang === 'ko' ? lines.slice(at + 1).join('\n') : lines.slice(0, at).join('\n');
+}
+
+/**
+ * The headline items of a release body, as short single lines.
+ *
+ * Release notes are written for people reading a web page: headings, prose
+ * paragraphs, links, and bold runs. A session-start notice has one line per
+ * item and no room for any of that, so this keeps only what reads as an item
+ * of a list and strips it to plain text. Anything that survives is a sentence
+ * the user can judge an upgrade by; anything that does not is left behind
+ * rather than truncated into nonsense.
+ *
+ * @param {string} body - the release body as published
+ * @param {string} [lang] - 'ko' | 'en'; picks the half of a bilingual body
+ * @returns {string[]} at most MAX_HIGHLIGHTS lines, or [] when nothing fits
+ */
+export function releaseHighlights(body, lang = 'en') {
+  const text = sectionForLang(String(body || ''), lang);
+  if (!text.trim()) return [];
+  const out = [];
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    // Bullets only. A heading names a section, and a prose paragraph in a
+    // release body is usually the rationale rather than the change itself.
+    const m = /^[-*+]\s+(.*)$/.exec(line);
+    if (!m) continue;
+    // Markup goes first, so the sentence split below sees the text a reader
+    // would: `**Bash writes are checked.**` is one sentence, not a bold run.
+    // One exception has to be caught before that: a stop followed straight by a
+    // code span (`…checked.\`install\` migrates…`) is a sentence boundary, and
+    // stripping the backtick first leaves a lowercase letter the split ignores.
+    // A space there is what the author meant, and it costs nothing if not.
+    let item = m[1]
+      .replace(/([.。])(`)/g, '$1 $2')
+      .replace(/`([^`]*)`/g, '$1')            // code spans read fine as plain text
+      .replace(/\*\*([^*]*)\*\*/g, '$1')      // bold
+      .replace(/\*([^*]*)\*/g, '$1')          // italics
+      .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') // links keep their label
+      .replace(/\s+/g, ' ')
+      .trim();
+    if (!item) continue;
+    // Release notes lead with the change and follow with the reasoning, often
+    // for several sentences. The first sentence is the change, so that is what
+    // a one-line notice keeps — cutting at a character count instead lands
+    // mid-clause and reads as a broken string rather than a short one.
+    //
+    // The break does not require a space after the stop: "…checked.The matcher…"
+    // is a typo a release body can carry, and requiring one there merged the two
+    // sentences into a single over-long line. A capital letter or a Hangul
+    // syllable directly after the stop is enough to say a new sentence started;
+    // a digit is not, so "0.5s" and "v3.45.0" stay intact.
+    //
+    // Abbreviations are excluded by name. "Fixed e.g. the matcher" would
+    // otherwise end after two words, which is worse than a long line: it reads
+    // as a complete thought and is not one. This list covers what actually turns
+    // up in release prose rather than trying to be exhaustive.
+    // `etc.` is deliberately absent: it ends a sentence as often as it continues
+    // one, so either choice is wrong half the time and the wrong one here merges
+    // two sentences rather than truncating one. Merging is the milder failure,
+    // and the length cap below bounds it.
+    const ABBREV = /\b(?:e\.g|i\.e|vs|cf|Dr|Mr|Ms|St|approx|no)\.$/i;
+    const parts = item.split(/(?<=[.。])(?:\s+|(?=[A-Z가-힣]))/);
+    let first = parts[0];
+    for (let k = 1; k < parts.length && ABBREV.test(first); k += 1) {
+      // The stop belonged to an abbreviation, so the sentence continues.
+      first = `${first} ${parts[k]}`;
+    }
+    item = first || item;
+    // Some first sentences are themselves a paragraph. Those get cut, but at a
+    // word boundary and with the ellipsis that says so.
+    if (item.length > MAX_HIGHLIGHT_LEN) {
+      const cut = item.slice(0, MAX_HIGHLIGHT_LEN);
+      const space = cut.lastIndexOf(' ');
+      item = (space > 40 ? cut.slice(0, space) : cut).replace(/[,;:—\-]$/, '').trim() + '…';
+    }
+    out.push(item);
+    if (out.length >= MAX_HIGHLIGHTS) break;
+  }
+  return out;
+}
+
+/**
+ * Fetch the highlights for one version. Returns [] on any failure: the notice
+ * is worth showing with a bare version number, so a missing release, a rate
+ * limit, or an offline machine must not cost the user the notice itself.
+ */
+export async function fetchHighlights(version, { timeoutMs = FETCH_TIMEOUT_MS, lang = 'en' } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${RELEASES_API}/v${version}`, {
+      signal: controller.signal,
+      headers: { accept: 'application/vnd.github+json' },
+    });
+    if (!res.ok) throw new Error(`releases responded ${res.status}`);
+    const body = await res.json();
+    return releaseHighlights(body && body.body, lang);
+  } catch (e) {
+    debug('update-check:highlights', e);
+    return [];
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 /**
  * Actually hit the registry and persist the answer. Only the detached child
  * and the explicit `update-check --refresh` command call this.
@@ -168,6 +315,36 @@ export async function refreshUpdateState(currentVersion) {
     if (prev.dismissedVersion && isNewer(latest, prev.dismissedVersion)) {
       delete next.dismissedVersion;
     }
+    // What the new version adds, so the notice can answer "why would I".
+    // Only worth a second request when there is actually an upgrade to describe,
+    // and only when we do not already hold the notes for that exact version.
+    // The reader's own language: a release body carries both halves, and the
+    // notice has room for three lines in one of them.
+    let lang = 'en';
+    try {
+      const { userLanguage } = await import('./config.js');
+      lang = userLanguage();
+    } catch (e) { debug('update-check:lang', e); }
+    // Fetch when the version is new, and also when the reader switched language
+    // since these notes were cached — otherwise they keep reading the half they
+    // left behind.
+    const staleLang = prev.highlightsFor === latest && prev.highlightsLang !== lang;
+    if (isNewer(latest, currentVersion) && (prev.highlightsFor !== latest || staleLang)) {
+      const highlights = await fetchHighlights(latest, { lang });
+      if (highlights.length) {
+        next.highlights = highlights;
+        next.highlightsFor = latest;
+        // Which language these are in. Someone who switches `lang` afterwards
+        // would otherwise keep reading the notes in the language they left.
+        next.highlightsLang = lang;
+      } else {
+        // Drop notes belonging to an older version rather than showing them
+        // against this one.
+        delete next.highlights;
+        delete next.highlightsFor;
+        delete next.highlightsLang;
+      }
+    }
     writeUpdateState(next);
     return { ok: true, latest };
   } catch (e) {