@absolutejs/changelog 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,21 @@ 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.2.0 — 2026-09-10
+
+### Added
+
+- **Adopting writes a prepublishOnly gate, so no publish can go round the check**
+- **Entries can be written against the package's own API, so a symbol that is not an export is a compile error** (`Change`, `change`)
+- **Reconciliation reports migrations that do not describe what the package did** (`Reconciliation`)
+- **The gate catches a package that stopped shipping the documents, and files in the entry directory that no release will read** (`strayEntries`)
+- **The gate checks that a migration describes what the package actually did** (`reconcile`)
+
+### Fixed
+
+- **Compare against the newest published version, not the one being published** (`packageVersions`)
+- **Read a document written against an older contract rather than refusing it** (`parseChangelog`)
+
 ## 0.1.2 — 2026-09-10
 
 ### Fixed

package/changelog.json

@@ -1,42 +1,99 @@
 {
-  "contract": 1,
-  "name": "@absolutejs/changelog",
-  "releases": [
-    {
-      "changes": [
-        {
-          "kind": "fixed",
-          "summary": "Keep each package.json's own indentation when writing it back",
-          "symbols": ["writeJsonLike"]
-        }
-      ],
-      "date": "2026-09-10",
-      "version": "0.1.2"
-    },
-    {
-      "changes": [
-        {
-          "kind": "fixed",
-          "summary": "Fall back to the full packument when the registry has not built the abbreviated one yet",
-          "symbols": ["packageVersions"]
-        },
-        {
-          "kind": "fixed",
-          "summary": "Keep the formatter off the generated changelog copies when adopting"
-        }
-      ],
-      "date": "2026-09-10",
-      "version": "0.1.1"
-    },
-    {
-      "changes": [
-        {
-          "kind": "added",
-          "summary": "The changelog contract: typed entries, a gate that checks them against the package's own types, and migrations as data"
-        }
-      ],
-      "date": "2026-09-10",
-      "version": "0.1.0"
-    }
-  ]
+	"contract": 1,
+	"name": "@absolutejs/changelog",
+	"releases": [
+		{
+			"changes": [
+				{
+					"kind": "added",
+					"summary": "Adopting writes a prepublishOnly gate, so no publish can go round the check"
+				},
+				{
+					"kind": "fixed",
+					"summary": "Compare against the newest published version, not the one being published",
+					"symbols": [
+						"packageVersions"
+					]
+				},
+				{
+					"kind": "added",
+					"summary": "Entries can be written against the package's own API, so a symbol that is not an export is a compile error",
+					"symbols": [
+						"Change",
+						"change"
+					]
+				},
+				{
+					"kind": "fixed",
+					"summary": "Read a document written against an older contract rather than refusing it",
+					"symbols": [
+						"parseChangelog"
+					]
+				},
+				{
+					"kind": "added",
+					"summary": "Reconciliation reports migrations that do not describe what the package did",
+					"symbols": [
+						"Reconciliation"
+					]
+				},
+				{
+					"kind": "added",
+					"summary": "The gate catches a package that stopped shipping the documents, and files in the entry directory that no release will read",
+					"symbols": [
+						"strayEntries"
+					]
+				},
+				{
+					"kind": "added",
+					"summary": "The gate checks that a migration describes what the package actually did",
+					"symbols": [
+						"reconcile"
+					]
+				}
+			],
+			"date": "2026-09-10",
+			"version": "0.2.0"
+		},
+		{
+			"changes": [
+				{
+					"kind": "fixed",
+					"summary": "Keep each package.json's own indentation when writing it back",
+					"symbols": [
+						"writeJsonLike"
+					]
+				}
+			],
+			"date": "2026-09-10",
+			"version": "0.1.2"
+		},
+		{
+			"changes": [
+				{
+					"kind": "fixed",
+					"summary": "Fall back to the full packument when the registry has not built the abbreviated one yet",
+					"symbols": [
+						"packageVersions"
+					]
+				},
+				{
+					"kind": "fixed",
+					"summary": "Keep the formatter off the generated changelog copies when adopting"
+				}
+			],
+			"date": "2026-09-10",
+			"version": "0.1.1"
+		},
+		{
+			"changes": [
+				{
+					"kind": "added",
+					"summary": "The changelog contract: typed entries, a gate that checks them against the package's own types, and migrations as data"
+				}
+			],
+			"date": "2026-09-10",
+			"version": "0.1.0"
+		}
+	]
 }

package/dist/cli.js

@@ -235,8 +235,8 @@ var parseChangelog = (value) => {
     return { problems: ["not an object"] };
   if (!isText(value.name))
     problems.push("needs a package name");
-  if (value.contract !== CHANGELOG_CONTRACT)
-    problems.push(`contract ${JSON.stringify(value.contract)} is not ${CHANGELOG_CONTRACT}`);
+  if (typeof 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))
     problems.push("releases is not a list");
@@ -535,6 +535,10 @@ var readJsonFile = async (path) => {
     return;
   }
 };
+var strayEntries = async (packageRoot) => {
+  const names = await readdir(join(packageRoot, UNRELEASED_DIRECTORY)).catch(() => []);
+  return names.filter((name) => !ENTRY.test(name) && name !== ".gitkeep" && !name.startsWith("."));
+};
 
 // src/json.ts
 import { readFile as readFile2, writeFile } from "fs/promises";
@@ -549,27 +553,66 @@ var writeJsonLike = async (path, document) => {
 };
 
 // src/reconcile.ts
+var migrationHolds = (input) => {
+  const { after, change, subpaths } = input;
+  const wrong = [];
+  const { migration } = change;
+  if ("rename" in migration) {
+    const { from } = migration.rename;
+    const into = migration.rename.to;
+    if (!after.has(into))
+      wrong.push(`\`${change.summary}\` renames to \`${into}\`, which this version does not export`);
+    if (after.has(from))
+      wrong.push(`\`${change.summary}\` renames \`${from}\` away, but this version still exports it`);
+    if (!change.symbols.includes(from))
+      wrong.push(`\`${change.summary}\` renames \`${from}\`, which is not in its own symbols`);
+  }
+  if ("moved" in migration) {
+    const { symbol } = migration.moved;
+    const into = migration.moved.to;
+    if (!after.has(symbol))
+      wrong.push(`\`${change.summary}\` moves \`${symbol}\`, which this version does not export`);
+    if (subpaths.size > 0 && !subpaths.has(into))
+      wrong.push(`\`${change.summary}\` moves \`${symbol}\` to \`${into}\`, which is not an entry point of this package`);
+  }
+  if ("resubpath" in migration && subpaths.size > 0 && !subpaths.has(migration.resubpath.to))
+    wrong.push(`\`${change.summary}\` points at \`${migration.resubpath.to}\`, which is not an entry point of this package`);
+  if (change.kind === "removed") {
+    for (const symbol of change.symbols)
+      if (after.has(symbol))
+        wrong.push(`\`${change.summary}\` says \`${symbol}\` was removed, but this version still exports it`);
+  }
+  return wrong;
+};
 var describeReconciliation = (found) => {
   const lines = [];
   for (const entry of found.unannounced)
     lines.push(entry.kind === "removed" ? `\`${entry.name}\` is no longer exported and no entry says so` : `\`${entry.name}\` changed its ${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);
   return lines;
 };
 var reconcile = (input) => {
-  const announced = new Set(input.changes.filter(isDisruptive).flatMap((change) => [...change.symbols]));
+  const disruptive = new Set(input.changes.filter(isDisruptive).flatMap((change) => [...change.symbols]));
+  const mentioned = new Set(input.changes.flatMap((change) => [...change.symbols ?? []]));
   const unannounced = [
-    ...input.diff.removed.map((name) => ({ kind: "removed", name })),
-    ...notable(input.diff).map((change) => ({
+    ...input.diff.removed.filter((name) => !disruptive.has(name)).map((name) => ({ kind: "removed", name })),
+    ...notable(input.diff).filter((change) => !mentioned.has(change.name)).map((change) => ({
       kind: change.shape === "parameters" ? "parameters" : "members",
       name: change.name
     }))
-  ].filter((entry) => !announced.has(entry.name));
+  ];
   const unknownSymbols = [
     ...new Set(input.changes.flatMap((change) => [...change.symbols ?? []]).filter((name) => !input.known.has(name)))
   ];
-  return { unannounced, unknownSymbols };
+  const { after } = input;
+  const wrongMigrations = after === undefined ? [] : input.changes.filter(isDisruptive).flatMap((change) => migrationHolds({
+    after,
+    change,
+    subpaths: input.subpaths ?? new Set
+  }));
+  return { unannounced, unknownSymbols, wrongMigrations };
 };
 
 // src/registry.ts
@@ -820,6 +863,12 @@ var writeBoth = async (root, changelog) => {
   await writeFile2(paths.markdown, renderMarkdown(changelog, history === undefined ? {} : { history }));
 };
 var slug = (summary) => summary.toLowerCase().replace(/[^a-z0-9]+/gu, "-").replace(/^-|-$/gu, "").slice(0, SLUG_MAX_LENGTH) || "change";
+var sourceEntryOf = (root) => {
+  for (const candidate of ["src/index.ts", "src/index.tsx", "index.ts"])
+    if (existsSync(join2(root, candidate)))
+      return `../../${candidate.replace(/\.tsx?$/u, "")}`;
+  return;
+};
 var add = async (root, flags) => {
   const kind = text(flags, "kind");
   const summary = text(flags, "summary");
@@ -843,10 +892,12 @@ var add = async (root, flags) => {
   ] : [
     `	migration: { instruction: ${JSON.stringify(instruction)}, manual: true },`
   ];
+  const api = sourceEntryOf(root);
   const body = [
+    ...api === undefined ? [] : [`import type * as Api from '${api}';`],
     "import type { Change } from '@absolutejs/changelog';",
     "",
-    "export const change: Change = {",
+    `export const change: Change${api === undefined ? "" : "<typeof Api>"} = {`,
     `	kind: ${JSON.stringify(kind)},`,
     ...disruptive ? migration : [],
     `	summary: ${JSON.stringify(summary)}${symbols.length > 0 ? "," : ""}`,
@@ -939,23 +990,46 @@ var check = async (root, flags) => {
   const include = isPackage(tsconfig) ? tsconfig.include : undefined;
   if (Array.isArray(include) && !coversEntries(include))
     failures.push('tsconfig.json does not compile changelog/, so nothing is checking the entries \u2014 add "changelog/**/*" to its include list');
+  for (const stray of await strayEntries(root))
+    failures.push(`${UNRELEASED_DIRECTORY}/${stray} is not an entry, so no release will ever read it`);
+  const shipped = Array.isArray(manifest.files) ? manifest.files : [];
+  for (const file of [CHANGELOG_FILE, CHANGELOG_MARKDOWN])
+    if (shipped.length > 0 && !shipped.includes(file))
+      failures.push(`package.json does not ship ${file}`);
   const offline = flags.offline === true;
   const built = await builtSurface(root);
-  if (!offline && built !== undefined && newest !== undefined) {
-    const published = await publishedSurface(manifest.name ?? "", newest.version);
+  const versions = offline ? undefined : await packageVersions(manifest.name ?? "");
+  const baseline = (versions?.published ?? []).filter((version) => compareVersions(version, manifest.version) <= 0).sort(compareVersions).at(LAST3);
+  if (!offline && built !== undefined && baseline !== undefined) {
+    const published = await publishedSurface(manifest.name ?? "", baseline);
     if (published === undefined)
-      console.warn(`  (could not read ${manifest.name}@${newest.version} from the registry; the types were not checked)`);
+      console.warn(`  (could not read ${manifest.name}@${baseline} from the registry; the types were not checked)`);
+    const speaking = [
+      ...entries.map((entry) => entry.change),
+      ...current.releases.filter((entry) => compareVersions(entry.version, baseline) > 0).flatMap((entry) => [...entry.changes])
+    ];
     failures.push(...published === undefined ? [] : describeReconciliation(reconcile({
-      changes: entries.map((entry) => entry.change),
+      after: new Set(built.keys()),
+      changes: speaking,
       diff: diffSurface(published, built),
-      known: new Set([...published.keys(), ...built.keys()])
+      known: new Set([...published.keys(), ...built.keys()]),
+      subpaths: subpathsOf(manifest)
     })));
   }
+  if (!offline && built === undefined)
+    console.warn("  (no dist to read, so the types were not checked \u2014 run the build before the gate)");
   if (failures.length > 0)
     throw new CliError(["This package\u2019s changelog does not hold:", ...failures].join(`
   `));
   console.log(`${manifest.name}@${manifest.version}: changelog holds (${entries.length} pending, ${current.releases.length} released)`);
 };
+var LAST3 = -1;
+var subpathsOf = (manifest) => {
+  const { exports } = manifest;
+  if (typeof exports !== "object" || exports === null)
+    return new Set;
+  return new Set(Object.keys(exports).map((key) => key === "." ? manifest.name ?? "" : `${manifest.name}${key.slice(1)}`));
+};
 var CHECKING_CONFIGS = ["tsconfig.json", "tsconfig.eslint.json"];
 var coversEntries = (include) => Array.isArray(include) && include.some((entry) => typeof entry === "string" && entry.startsWith("changelog"));
 var includeEntriesIn = async (root, file) => {
@@ -989,6 +1063,16 @@ var ignoreGenerated = async (root) => {
 `)}
 `);
 };
+var PUBLISH_GATE = "absolute-changelog check";
+var withPublishGate = (scripts) => {
+  const existing = scripts.prepublishOnly;
+  if (typeof existing === "string" && existing.includes(PUBLISH_GATE))
+    return;
+  return {
+    ...scripts,
+    prepublishOnly: typeof existing === "string" && existing.trim() !== "" ? `${existing} && ${PUBLISH_GATE}` : PUBLISH_GATE
+  };
+};
 var adopt = async (root) => {
   const manifest = await readPackage(root);
   const paths = changelogPaths(root);
@@ -1002,9 +1086,11 @@ var adopt = async (root) => {
   }
   const files = manifest.files ?? [];
   const wanted = [CHANGELOG_FILE, CHANGELOG_MARKDOWN].filter((entry) => !files.includes(entry));
-  if (wanted.length > 0)
+  const scripts = typeof manifest.scripts === "object" && manifest.scripts !== null ? withPublishGate(manifest.scripts) : undefined;
+  if (wanted.length > 0 || scripts !== undefined)
     await writeJsonLike(join2(root, "package.json"), {
       ...manifest,
+      ...scripts === undefined ? {} : { scripts },
       files: [...files, ...wanted].sort()
     });
   await ignoreGenerated(root);
@@ -1034,5 +1120,5 @@ await main().catch((error) => {
   process.exit(1);
 });
 
-//# debugId=3B21DCC7DC15D28564756E2164756E21
+//# debugId=7CE32A12E2B0BC0C64756E2164756E21
 //# sourceMappingURL=cli.js.map