@absolutejs/changelog 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -6,6 +6,27 @@ This file is generated by `absolute-changelog` from the entries in
 `changelog/`. Edit an entry, not this file — and add new ones under
 `changelog/unreleased/`.
 
+## 0.5.1 — 2026-09-10
+
+### Fixed
+
+- **Report a symbols list that is not one, trim a version where it is read, and refuse a fractional contract** (`parseChangelog`)
+
+## 0.5.0 — 2026-09-10
+
+### Breaking
+
+- **A surface records which entry points offer each name, so a name leaving one is a change** (`PackageSurface`, `SurfaceName`, `surfaceOfFiles`, `typeEntriesOf`, `TypeEntry`, `SurfaceDiff`, `Withdrawal`, `Unannounced`)
+  _Migration:_ surfaceOfFiles takes { path, specifier } entries and its values are { declaration, entries }; diffSurface reports withdrawn alongside removed.
+
+### Added
+
+- **Cache what the registry said for five minutes, so a page asking about twenty packages asks once each** (`forgetRegistry`, `packageVersions`)
+
+### Fixed
+
+- **Tell a package that has never been published from a registry that will not answer, so a first release is not refused forever** (`packageVersions`)
+
 ## 0.4.0 — 2026-09-10
 
 ### Added

package/changelog.json

@@ -2,6 +2,58 @@
 	"contract": 1,
 	"name": "@absolutejs/changelog",
 	"releases": [
+		{
+			"changes": [
+				{
+					"kind": "fixed",
+					"summary": "Report a symbols list that is not one, trim a version where it is read, and refuse a fractional contract",
+					"symbols": [
+						"parseChangelog"
+					]
+				}
+			],
+			"date": "2026-09-10",
+			"version": "0.5.1"
+		},
+		{
+			"changes": [
+				{
+					"kind": "breaking",
+					"migration": {
+						"instruction": "surfaceOfFiles takes { path, specifier } entries and its values are { declaration, entries }; diffSurface reports withdrawn alongside removed.",
+						"manual": true
+					},
+					"summary": "A surface records which entry points offer each name, so a name leaving one is a change",
+					"symbols": [
+						"PackageSurface",
+						"SurfaceName",
+						"surfaceOfFiles",
+						"typeEntriesOf",
+						"TypeEntry",
+						"SurfaceDiff",
+						"Withdrawal",
+						"Unannounced"
+					]
+				},
+				{
+					"kind": "added",
+					"summary": "Cache what the registry said for five minutes, so a page asking about twenty packages asks once each",
+					"symbols": [
+						"forgetRegistry",
+						"packageVersions"
+					]
+				},
+				{
+					"kind": "fixed",
+					"summary": "Tell a package that has never been published from a registry that will not answer, so a first release is not refused forever",
+					"symbols": [
+						"packageVersions"
+					]
+				}
+			],
+			"date": "2026-09-10",
+			"version": "0.5.0"
+		},
 		{
 			"changes": [
 				{

package/dist/cli.js

@@ -113,7 +113,14 @@ var isKind = (value) => typeof value === "string" && CHANGE_KINDS.some((known) =
 var isDisruptiveKind = (kind) => kind === "breaking" || kind === "removed";
 var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var isText = (value) => typeof value === "string" && value.trim().length > 0;
-var textList = (value) => Array.isArray(value) && value.length > 0 && value.every(isText) ? value : undefined;
+var textList = (value, where, problems) => {
+  if (value === undefined)
+    return;
+  if (Array.isArray(value) && value.length > 0 && value.every(isText))
+    return value.filter((entry) => typeof entry === "string");
+  problems.push(`${where}: symbols is not a list of names`);
+  return;
+};
 var readMigration = (value, where, problems) => {
   if (!isRecord(value) || !isText(value.instruction)) {
     problems.push(`${where}: migration needs an instruction`);
@@ -162,7 +169,7 @@ var readChange = (value, where, problems) => {
     ...isText(value.reference) ? { reference: value.reference } : {},
     summary: value.summary
   };
-  const symbols = textList(value.symbols);
+  const symbols = textList(value.symbols, where, problems);
   const [first, ...rest] = symbols ?? [];
   if (kind === "breaking" || kind === "removed") {
     const migration = readMigration(value.migration, where, problems);
@@ -193,7 +200,8 @@ var readRelease = (value, where, problems) => {
     problems.push(`${where}: not an object`);
     return;
   }
-  if (!isText(value.version) || parseVersion(value.version) === undefined) {
+  const version = isText(value.version) ? value.version.trim() : undefined;
+  if (version === undefined || parseVersion(version) === undefined) {
     problems.push(`${where}: version is not a version`);
     return;
   }
@@ -216,7 +224,7 @@ var readRelease = (value, where, problems) => {
     changes: [head, ...tail],
     date: value.date,
     ...isText(value.note) ? { note: value.note } : {},
-    version: value.version
+    version
   };
   return release;
 };
@@ -236,7 +244,7 @@ var parseChangelog = (value) => {
     return { problems: ["not an object"] };
   if (!isText(value.name))
     problems.push("needs a package name");
-  if (typeof value.contract !== "number" || value.contract > CHANGELOG_CONTRACT)
+  if (!Number.isInteger(value.contract) || Number(value.contract) > CHANGELOG_CONTRACT)
     problems.push(`contract ${JSON.stringify(value.contract)} is newer than ${CHANGELOG_CONTRACT}, which this reader understands`);
   const raw = value.releases;
   if (!Array.isArray(raw))
@@ -438,33 +446,55 @@ var surfaceOfArchive = (archive) => {
 };
 var surfaceOfFiles = (files, entries) => {
   const surface = new Map;
-  for (const entry of entries)
-    for (const [name, text] of exportsOf(files, entry, new Set))
-      if (!surface.has(name))
-        surface.set(name, text);
+  const offered = entries.flatMap((entry) => [...exportsOf(files, entry.path, new Set)].map(([name, declaration]) => ({ declaration, name, specifier: entry.specifier })));
+  for (const { declaration, name, specifier } of offered) {
+    const known = surface.get(name);
+    if (known === undefined)
+      surface.set(name, { declaration, entries: [specifier] });
+    else if (!known.entries.includes(specifier))
+      known.entries.push(specifier);
+  }
+  for (const value of surface.values())
+    value.entries.sort();
   return surface;
 };
-var typeCandidatesIn = (value) => {
+var exportEntries = (value, packageName, specifier) => {
+  const here = specifier ?? packageName;
   if (typeof value === "string")
-    return [value];
+    return [{ specifier: here, value }];
   if (typeof value !== "object" || value === null)
     return [];
-  return Object.entries(value).flatMap(([key, nested]) => key === "types" || key === "typings" ? typeCandidatesIn(nested) : typeCandidatesIn(nested));
+  return Object.entries(value).flatMap(([key, nested]) => key.startsWith(".") ? exportEntries(nested, packageName, key === "." ? packageName : `${packageName}${key.slice(1)}`) : exportEntries(nested, packageName, here));
 };
 var typeEntriesOf = (manifest, files) => {
   const record = typeof manifest === "object" && manifest !== null ? new Map(Object.entries(manifest)) : new Map;
-  const claimed = [
-    record.get("types"),
-    record.get("typings"),
-    ...typeCandidatesIn(record.get("exports"))
+  const named = record.get("name");
+  const packageName = typeof named === "string" ? named : "";
+  const resolved = (value, specifier) => {
+    if (typeof value !== "string")
+      return [];
+    const cleaned = value.replace(/^\.\//u, "");
+    const candidates = DECLARATION.test(cleaned) ? [cleaned] : [
+      cleaned.replace(/\.[cm]?js$/u, ".d.ts"),
+      cleaned.replace(/\.[cm]?js$/u, ".d.mts"),
+      cleaned.replace(/\.[cm]?js$/u, ".d.cts")
+    ];
+    return candidates.filter((candidate) => files.has(candidate)).map((resolvedPath) => ({ path: resolvedPath, specifier }));
+  };
+  const found = [
+    ...resolved(record.get("types"), packageName),
+    ...resolved(record.get("typings"), packageName),
+    ...exportEntries(record.get("exports"), packageName).flatMap((entry) => resolved(entry.value, entry.specifier))
   ];
-  const entries = claimed.filter((value) => typeof value === "string").map((value) => value.replace(/^\.\//u, "")).flatMap((cleaned) => DECLARATION.test(cleaned) ? [cleaned] : [
-    cleaned.replace(/\.[cm]?js$/u, ".d.ts"),
-    cleaned.replace(/\.[cm]?js$/u, ".d.mts"),
-    cleaned.replace(/\.[cm]?js$/u, ".d.cts")
-  ]).filter((candidate) => files.has(candidate));
-  const fallback = entries.length === 0 && files.has("dist/index.d.ts") ? ["dist/index.d.ts"] : [];
-  return [...new Set([...entries, ...fallback])];
+  const fallback = found.length === 0 && files.has("dist/index.d.ts") ? [{ path: "dist/index.d.ts", specifier: packageName }] : [];
+  const seen = new Set;
+  return [...found, ...fallback].filter((entry) => {
+    const key = `${entry.specifier}\x00${entry.path}`;
+    if (seen.has(key))
+      return false;
+    seen.add(key);
+    return true;
+  });
 };
 var SHAPE = {
   members: "members",
@@ -519,23 +549,33 @@ var changeShape = (change) => {
 };
 var diffSurface = (before, after) => {
   const removed = [];
+  const withdrawn = [];
   const changed = [];
-  for (const [name, declaration] of before) {
+  for (const [name, was] of before) {
     const now = after.get(name);
     if (now === undefined)
       removed.push(name);
-    else if (now !== declaration)
+    if (now === undefined)
+      continue;
+    const lost = was.entries.filter((entry) => !now.entries.includes(entry));
+    if (lost.length > 0)
+      withdrawn.push({ from: lost, name });
+    if (now.declaration !== was.declaration)
       changed.push({
-        after: now,
-        before: declaration,
+        after: now.declaration,
+        before: was.declaration,
         name,
-        shape: changeShape({ after: now, before: declaration })
+        shape: changeShape({
+          after: now.declaration,
+          before: was.declaration
+        })
       });
   }
   return {
     added: [...after.keys()].filter((name) => !before.has(name)),
     changed,
-    removed
+    removed,
+    withdrawn
   };
 };
 var notable = (diff) => diff.changed.filter((change) => change.shape === "parameters" || change.shape === "members");
@@ -671,10 +711,11 @@ var describeReconciliation = (found) => {
     members: "changed the members of its type",
     parameters: "changed what it is called with",
     removed: "is no longer exported",
-    types: "changed its declaration"
+    types: "changed its declaration",
+    withdrawn: "is no longer exported from"
   };
   for (const entry of found.unannounced)
-    lines.push(`\`${entry.name}\` ${moved[entry.kind]} and no entry says so`);
+    lines.push(entry.kind === "withdrawn" ? `\`${entry.name}\` ${moved.withdrawn} ${(entry.from ?? []).join(", ")} and no entry says so` : `\`${entry.name}\` ${moved[entry.kind]} and no entry says so`);
   for (const name of found.unknownSymbols)
     lines.push(`an entry names \`${name}\`, which this package does not export`);
   lines.push(...found.wrongMigrations);
@@ -685,6 +726,7 @@ var reconcile = (input) => {
   const mentioned = new Set(input.changes.flatMap((change) => [...change.symbols ?? []]));
   const unannounced = [
     ...input.diff.removed.filter((name) => !disruptive.has(name)).map((name) => ({ kind: "removed", name })),
+    ...input.diff.withdrawn.filter((entry) => !disruptive.has(entry.name)).map((entry) => ({ from: entry.from, kind: "withdrawn", name: entry.name })),
     ...input.diff.changed.filter((change) => !mentioned.has(change.name) && change.shape !== "unknown").map((change) => ({ kind: change.shape, name: change.name }))
   ];
   const unknownSymbols = [
@@ -710,6 +752,8 @@ var MAX_ARCHIVE_BYTES = MAX_ARCHIVE_MEBIBYTES * MEBIBYTE2;
 var MAX_DOWNLOAD_MEBIBYTES = 32;
 var MAX_DOWNLOAD_BYTES = MAX_DOWNLOAD_MEBIBYTES * MEBIBYTE2;
 var TIMEOUT_MS = 20000;
+var NOT_FOUND = 404;
+var NOTHING_PUBLISHED = { published: [], tarballs: {} };
 var PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u;
 var MAX_NAME_LENGTH = 214;
 var isPackageName = (name) => name.length <= MAX_NAME_LENGTH && PACKAGE_NAME.test(name);
@@ -753,9 +797,25 @@ var packageArchive = async (name, version, options = {}) => {
     return;
   }
 };
+var packuments = new Map;
+var SECONDS_PER_MINUTE = 60;
+var MILLISECONDS_PER_SECOND = 1000;
+var PACKUMENT_MINUTES = 5;
+var PACKUMENT_TTL_MS = PACKUMENT_MINUTES * SECONDS_PER_MINUTE * MILLISECONDS_PER_SECOND;
+var forgetRegistry = () => packuments.clear();
 var packageVersions = async (name, options = {}) => {
   if (!isPackageName(name))
     return;
+  const cacheable = options.fetch === undefined && options.registry === undefined;
+  const known = cacheable ? packuments.get(name) : undefined;
+  if (known !== undefined && Date.now() - known.asked < PACKUMENT_TTL_MS)
+    return known.value;
+  const value = askRegistry(name, options);
+  if (cacheable)
+    packuments.set(name, { asked: Date.now(), value });
+  return value;
+};
+var askRegistry = async (name, options) => {
   const call = options.fetch ?? fetch;
   const url = `${options.registry ?? DEFAULT_REGISTRY}/${name.replace("/", "%2f")}`;
   try {
@@ -764,9 +824,9 @@ var packageVersions = async (name, options = {}) => {
       signal: AbortSignal.timeout(TIMEOUT_MS)
     });
     const response = abbreviated.ok ? abbreviated : await call(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
-    if (!response.ok)
-      return;
-    return readPackument(await response.json());
+    if (response.ok)
+      return readPackument(await response.json());
+    return response.status === NOT_FOUND ? NOTHING_PUBLISHED : undefined;
   } catch {
     return;
   }
@@ -1111,9 +1171,11 @@ var check = async (root, flags) => {
   const versions = offline ? undefined : await packageVersions(manifest.name ?? "");
   if (!offline && versions === undefined)
     failures.push(`the registry did not answer for ${manifest.name}, so nothing was compared \u2014 pass --offline to skip the comparison deliberately`);
+  if (versions !== undefined && versions.published.length === 0)
+    console.warn(`  (${manifest.name} has never been published, so there was nothing to compare)`);
   const baseline = (versions?.published ?? []).filter((version) => compareVersions(version, manifest.version) <= 0).sort(compareVersions).at(LAST2);
-  if (versions !== undefined && baseline === undefined && !offline)
-    console.warn(`  (nothing published at or below ${manifest.version}; this looks like a first release)`);
+  if (versions !== undefined && versions.published.length > 0 && baseline === undefined && !offline)
+    console.warn(`  (nothing published at or below ${manifest.version}, so there was nothing to compare)`);
   if (built !== undefined && baseline !== undefined) {
     const published = await publishedSurface(manifest.name ?? "", baseline);
     if (published === undefined)
@@ -1249,5 +1311,5 @@ await main().catch((error) => {
   process.exit(1);
 });
 
-//# debugId=4CD69EF0E551B35864756E2164756E21
+//# debugId=3D35EBE83A76D8A664756E2164756E21
 //# sourceMappingURL=cli.js.map