@absolutejs/changelog 0.1.2 → 0.3.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");
@@ -269,6 +269,10 @@ var migrationsBetween = (changelog, from, upto) => disruptiveBetween(changelog,
 });
 var symbolsDisturbedBetween = (changelog, from, upto) => new Set(disruptiveBetween(changelog, from, upto).flatMap(({ change }) => change.symbols));
 
+// src/surface.ts
+import path from "path";
+import ts from "typescript";
+
 // src/tarball.ts
 var TAR_BLOCK = 512;
 var NAME_LENGTH = 100;
@@ -321,114 +325,185 @@ var readTar = (archive, keep, limits = {}) => {
 };
 
 // src/surface.ts
-var DECLARATION = /\bexport\s+(?:declare\s+)?(?:abstract\s+)?(?:async\s+)?(function|const|let|var|class|interface|type|enum|namespace)\s+([A-Za-z_$][\w$]*)/gu;
-var NAMED_EXPORT = /\bexport\s*\{([^}]*)\}/gu;
-var BODIED = new Set(["class", "interface", "enum", "namespace"]);
-var OPENS = new Set(["{", "(", "["]);
-var CLOSES = new Set(["}", ")", "]"]);
-var IDENTIFIER = /^[A-Za-z_$][\w$]*$/u;
-var LAST2 = -1;
-var NOWHERE = -1;
-var MEMBER = /([A-Za-z_$][\w$]*)\s*[?!]?\s*[:(<]/u;
-var isStub = (declaration) => declaration.startsWith("export {");
-var declarationEnd = (source, from, bodied) => {
-  let depth = 0;
-  for (let index = from;index < source.length; index += 1) {
-    const character = source[index] ?? "";
-    if (OPENS.has(character))
-      depth += 1;
-    else if (CLOSES.has(character))
-      depth -= 1;
-    else if (character === ";" && depth <= 0)
-      return index + 1;
-    if (CLOSES.has(character) && depth <= 0 && bodied)
-      return index + 1;
-  }
-  return source.length;
-};
-var normalize = (declaration) => declaration.replace(/\s+/gu, " ").trim();
-var reExported = (body) => body.split(",").map((part) => part.trim().replace(/^type\s+/u, "")).filter((clause) => clause !== "").map((clause) => [
-  clause.split(/\s+as\s+/u).at(LAST2)?.trim(),
-  clause
-]).filter((pair) => pair[0] !== undefined && IDENTIFIER.test(pair[0]));
-var exportedDeclarations = (source) => {
+var DECLARATION = /\.d\.[cm]?ts$/u;
+var parse = (source, name) => ts.createSourceFile(name, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+var normalize = (text) => text.replace(/\s+/gu, " ").trim();
+var resolveFrom = (files, from, specifier) => {
+  if (!specifier.startsWith("."))
+    return;
+  const base = path.posix.join(path.posix.dirname(from), specifier);
+  const candidates = [
+    base,
+    `${base.replace(/\.js$/u, "")}.d.ts`,
+    `${base.replace(/\.js$/u, "")}.d.mts`,
+    `${base.replace(/\.js$/u, "")}.d.cts`,
+    `${base}/index.d.ts`,
+    `${base}/index.d.mts`,
+    `${base}/index.d.cts`
+  ];
+  return candidates.find((candidate) => files.has(candidate));
+};
+var declaredNameOf = (statement) => {
+  if (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement) || ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement) || ts.isEnumDeclaration(statement) || ts.isModuleDeclaration(statement))
+    return statement.name !== undefined && ts.isIdentifier(statement.name) ? statement.name.text : undefined;
+  return;
+};
+var isExported = (statement) => ts.canHaveModifiers(statement) && ts.getModifiers(statement)?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) === true;
+var variableNamesOf = (statement) => statement.declarationList.declarations.map((declaration) => declaration.name).filter((name) => ts.isIdentifier(name)).map((name) => name.text);
+var declarationsIn = (file) => {
   const found = new Map;
-  const add = (name, declaration) => {
-    const existing = found.get(name);
-    found.set(name, existing === undefined ? declaration : `${existing}
-${declaration}`);
-  };
-  for (const match of source.matchAll(DECLARATION)) {
-    const [, keyword, name] = match;
-    if (name === undefined || match.index === undefined)
+  for (const statement of file.statements) {
+    const text = normalize(statement.getText(file));
+    const named = declaredNameOf(statement);
+    if (named !== undefined)
+      found.set(named, text);
+    if (!ts.isVariableStatement(statement))
       continue;
-    add(name, normalize(source.slice(match.index, declarationEnd(source, match.index + match[0].length, BODIED.has(keyword ?? "")))));
+    for (const name of variableNamesOf(statement))
+      found.set(name, text);
   }
-  for (const match of source.matchAll(NAMED_EXPORT))
-    for (const [exported, clause] of reExported(match[1] ?? ""))
-      add(exported, `export { ${clause} }`);
   return found;
 };
-var surfaceOfArchive = (archive) => surfaceOfFiles([...readTar(archive, (path) => path.endsWith(".d.ts")).values()].map(asText));
-var surfaceOfFiles = (files) => {
+var declaresTypes = (manifest) => {
+  if (typeof manifest !== "object" || manifest === null)
+    return false;
+  const record = new Map(Object.entries(manifest));
+  if (typeof record.get("types") === "string")
+    return true;
+  if (typeof record.get("typings") === "string")
+    return true;
+  return JSON.stringify(record.get("exports") ?? {}).includes('"types"');
+};
+var contributionOf = (input) => {
+  const { file, files, from, local, seen, statement } = input;
+  const nothing = [];
+  if (ts.isExportAssignment(statement))
+    return [
+      [
+        statement.isExportEquals === true ? "export=" : "default",
+        normalize(statement.getText(file))
+      ]
+    ];
+  const named = declaredNameOf(statement);
+  if (named !== undefined && isExported(statement))
+    return [
+      [named, local.get(named) ?? normalize(statement.getText(file))]
+    ];
+  if (ts.isVariableStatement(statement) && isExported(statement)) {
+    const text = normalize(statement.getText(file));
+    return variableNamesOf(statement).map((name) => [name, text]);
+  }
+  if (!ts.isExportDeclaration(statement))
+    return nothing;
+  const specifier = statement.moduleSpecifier !== undefined && ts.isStringLiteral(statement.moduleSpecifier) ? statement.moduleSpecifier.text : undefined;
+  const target = specifier === undefined ? undefined : resolveFrom(files, from, specifier);
+  const theirs = target === undefined ? new Map : exportsOf(files, target, new Set(seen));
+  const clause = statement.exportClause;
+  if (clause === undefined)
+    return [...theirs].filter(([name]) => name !== "default" && name !== "export=");
+  if (ts.isNamespaceExport(clause))
+    return [[clause.name.text, `export * as ${clause.name.text}`]];
+  return clause.elements.map((element) => {
+    const sourceName = (element.propertyName ?? element.name).text;
+    const text = (specifier === undefined ? local.get(sourceName) : theirs.get(sourceName)) ?? `export { ${sourceName} }`;
+    return [element.name.text, text];
+  });
+};
+var exportsOf = (files, from, seen) => {
   const surface = new Map;
-  for (const source of files)
-    for (const [name, declaration] of exportedDeclarations(source)) {
-      const known = surface.get(name);
-      if (known === undefined || isStub(known) && !isStub(declaration))
-        surface.set(name, declaration);
-    }
+  const source = files.get(from);
+  if (source === undefined || seen.has(from))
+    return surface;
+  seen.add(from);
+  const file = parse(source, from);
+  const local = declarationsIn(file);
+  const contributed = file.statements.flatMap((statement) => contributionOf({ file, files, from, local, seen, statement }));
+  for (const [name, text] of contributed)
+    surface.set(name, text);
+  return surface;
+};
+var surfaceOfArchive = (archive) => {
+  const held = readTar(archive, (name) => DECLARATION.test(name) || name === "package.json");
+  const files = new Map([...held].map(([name, bytes]) => [name, asText(bytes)]));
+  const manifest = files.get("package.json");
+  let parsed;
+  try {
+    parsed = manifest === undefined ? undefined : JSON.parse(manifest);
+  } catch {
+    parsed = undefined;
+  }
+  const entries = typeEntriesOf(parsed, files);
+  return entries.length === 0 ? undefined : surfaceOfFiles(files, entries);
+};
+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);
   return surface;
 };
+var typeCandidatesIn = (value) => {
+  if (typeof value === "string")
+    return [value];
+  if (typeof value !== "object" || value === null)
+    return [];
+  return Object.entries(value).flatMap(([key, nested]) => key === "types" || key === "typings" ? typeCandidatesIn(nested) : typeCandidatesIn(nested));
+};
+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 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])];
+};
 var SHAPE = {
   members: "members",
   parameters: "parameters",
   types: "types",
   unknown: "unknown"
 };
+var isStub = (declaration) => declaration.startsWith("export {");
+var signatureOf = (declaration) => {
+  const file = parse(`${declaration}
+`, "declaration.d.ts");
+  const [statement] = file.statements;
+  if (statement === undefined)
+    return;
+  return statement;
+};
 var parametersOf = (declaration) => {
-  let depth = 0;
-  let start = NOWHERE;
-  for (const [index, character] of [...declaration].entries()) {
-    if (character === "{" && depth === 0)
-      return "";
-    depth += character === "(" ? 1 : 0;
-    if (character === "(" && depth === 1)
-      start = index;
-    depth -= character === ")" ? 1 : 0;
-    if (character === ")" && depth === 0 && start > NOWHERE)
-      return declaration.slice(start, index + 1);
-  }
-  return "";
+  const statement = signatureOf(declaration);
+  if (statement === undefined)
+    return "";
+  const found = [];
+  const visit = (node) => {
+    if (ts.isFunctionTypeNode(node) || ts.isFunctionDeclaration(node) || ts.isMethodSignature(node) || ts.isMethodDeclaration(node) || ts.isConstructSignatureDeclaration(node) || ts.isConstructorDeclaration(node))
+      found.push(node.parameters.map((parameter) => normalize(parameter.getText())).join(", "));
+    ts.forEachChild(node, visit);
+  };
+  visit(statement);
+  return found.join(" | ");
 };
 var membersOf = (declaration) => {
-  const opened = declaration.indexOf("{");
-  if (opened < 0)
-    return new Set;
+  const statement = signatureOf(declaration);
   const members = new Set;
-  let depth = 0;
-  let segment = "";
-  const take = () => {
-    const [, name] = MEMBER.exec(segment.trim()) ?? [];
-    if (name !== undefined)
-      members.add(name);
-    segment = "";
+  if (statement === undefined)
+    return members;
+  const visit = (node) => {
+    if ((ts.isPropertySignature(node) || ts.isMethodSignature(node) || ts.isPropertyDeclaration(node) || ts.isMethodDeclaration(node) || ts.isEnumMember(node)) && node.name !== undefined && (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name)))
+      members.add(node.name.text);
+    ts.forEachChild(node, visit);
   };
-  for (const character of declaration.slice(opened)) {
-    const opening = OPENS.has(character);
-    const closing = CLOSES.has(character);
-    depth += opening ? 1 : 0;
-    if (opening && depth === 1)
-      segment = "";
-    depth -= closing ? 1 : 0;
-    if (opening || closing || depth !== 1)
-      continue;
-    if (character === ";" || character === ",")
-      take();
-    else
-      segment += character;
-  }
-  take();
+  visit(statement);
   return members;
 };
 var sameNames = (left, right) => left.size === right.size && [...left].every((name) => right.has(name));
@@ -465,9 +540,9 @@ var diffSurface = (before, after) => {
 var notable = (diff) => diff.changed.filter((change) => change.shape === "parameters" || change.shape === "members");
 
 // src/entries.ts
-var loadEntry = async (path) => {
+var loadEntry = async (path2) => {
   try {
-    const module = await import(pathToFileURL(path).href);
+    const module = await import(pathToFileURL(path2).href);
     const named = typeof module === "object" && module !== null && "change" in module ? module.change : undefined;
     const exported = named ?? (typeof module === "object" && module !== null && "default" in module ? module.default : undefined);
     const read = { exported };
@@ -480,23 +555,28 @@ var loadEntry = async (path) => {
   }
 };
 var ENTRY = /\.[cm]?ts$/u;
-var builtSurface = async (packageRoot, out = "dist") => {
-  const root = join(packageRoot, out);
-  const sources = [];
+var DECLARATION2 = /\.d\.[cm]?ts$/u;
+var OUTPUT_DIRECTORIES = ["dist", "build", "lib", "types", "out"];
+var builtSurface = async (packageRoot) => {
+  const manifest = await readJsonFile(join(packageRoot, "package.json"));
+  const files = new Map;
   const walk = async (directory) => {
-    const found = await readdir(directory, { withFileTypes: true }).catch(() => []);
+    const found = await readdir(join(packageRoot, directory), {
+      withFileTypes: true
+    }).catch(() => []);
     await Promise.all(found.map(async (entry) => {
-      const path = join(directory, entry.name);
+      const relative = `${directory}/${entry.name}`;
       if (entry.isDirectory())
-        return walk(path);
-      if (!entry.name.endsWith(".d.ts"))
+        return walk(relative);
+      if (!DECLARATION2.test(entry.name))
         return;
-      sources.push(await readFile(path, "utf8").catch(() => ""));
+      files.set(relative, await readFile(join(packageRoot, relative), "utf8").catch(() => ""));
       return;
     }));
   };
-  await walk(root);
-  return sources.length === 0 ? undefined : surfaceOfFiles(sources);
+  await Promise.all(OUTPUT_DIRECTORIES.map((directory) => walk(directory)));
+  const entries = typeEntriesOf(manifest, files);
+  return entries.length === 0 ? undefined : surfaceOfFiles(files, entries);
 };
 var changelogPaths = (packageRoot) => ({
   history: join(packageRoot, "changelog", "history.md"),
@@ -522,8 +602,8 @@ var loadUnreleased = async (packageRoot) => {
   }
   return { entries, problems };
 };
-var readJsonFile = async (path) => {
-  const source = await readFile(path, "utf8").catch(() => {
+var readJsonFile = async (path2) => {
+  const source = await readFile(path2, "utf8").catch(() => {
     return;
   });
   if (source === undefined)
@@ -535,6 +615,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";
@@ -542,40 +626,92 @@ var indentOf = (source) => {
   const found = /\n([\t ]+)\S/u.exec(source)?.[1];
   return found === undefined || found === "" ? "\t" : found;
 };
-var writeJsonLike = async (path, document) => {
-  const source = await readFile2(path, "utf8").catch(() => "");
-  await writeFile(path, `${JSON.stringify(document, null, indentOf(source))}
+var writeJsonLike = async (path2, document) => {
+  const source = await readFile2(path2, "utf8").catch(() => "");
+  await writeFile(path2, `${JSON.stringify(document, null, indentOf(source))}
 `);
 };
 
 // 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 = [];
+  const moved = {
+    members: "changed the members of its type",
+    parameters: "changed what it is called with",
+    removed: "is no longer exported",
+    types: "changed its declaration"
+  };
   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`);
+    lines.push(`\`${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);
   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) => ({
-      kind: change.shape === "parameters" ? "parameters" : "members",
-      name: change.name
-    }))
-  ].filter((entry) => !announced.has(entry.name));
+    ...input.diff.removed.filter((name) => !disruptive.has(name)).map((name) => ({ kind: "removed", name })),
+    ...input.diff.changed.filter((change) => !mentioned.has(change.name) && change.shape !== "unknown").map((change) => ({ kind: change.shape, name: change.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
 import { gunzipSync } from "zlib";
 var ABBREVIATED = "application/vnd.npm.install-v1+json";
 var DEFAULT_REGISTRY = "https://registry.npmjs.org";
+var KIBIBYTE2 = 1024;
+var MEBIBYTE2 = KIBIBYTE2 * KIBIBYTE2;
+var MAX_ARCHIVE_MEBIBYTES = 96;
+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 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);
 var isRecord2 = (value) => typeof value === "object" && value !== null;
 var readPackument = (body) => {
   if (!isRecord2(body) || !isRecord2(body.versions))
@@ -603,20 +739,30 @@ var packageArchive = async (name, version, options = {}) => {
   if (url === undefined)
     return;
   try {
-    const response = await call(url);
+    const response = await call(url, {
+      signal: AbortSignal.timeout(TIMEOUT_MS)
+    });
     if (!response.ok)
       return;
-    return new Uint8Array(gunzipSync(new Uint8Array(await response.arrayBuffer())));
+    const compressed = new Uint8Array(await response.arrayBuffer());
+    if (compressed.byteLength > MAX_DOWNLOAD_BYTES)
+      return;
+    return new Uint8Array(gunzipSync(compressed, { maxOutputLength: MAX_ARCHIVE_BYTES }));
   } catch {
     return;
   }
 };
 var packageVersions = async (name, options = {}) => {
+  if (!isPackageName(name))
+    return;
   const call = options.fetch ?? fetch;
   const url = `${options.registry ?? DEFAULT_REGISTRY}/${name.replace("/", "%2f")}`;
   try {
-    const abbreviated = await call(url, { headers: { accept: ABBREVIATED } });
-    const response = abbreviated.ok ? abbreviated : await call(url);
+    const abbreviated = await call(url, {
+      headers: { accept: ABBREVIATED },
+      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());
@@ -628,7 +774,7 @@ var publishedChangelog = async (name, version, options = {}) => {
   const archive = await packageArchive(name, version, options);
   if (!archive)
     return;
-  const file = readTar(archive, (path) => path === CHANGELOG_FILE).get(CHANGELOG_FILE);
+  const file = readTar(archive, (path2) => path2 === CHANGELOG_FILE).get(CHANGELOG_FILE);
   if (!file)
     return;
   try {
@@ -706,6 +852,7 @@ var renderRelease = (release) => {
   ].join(`
 `);
 };
+var GENERATED_MARKER = "This file is generated by `absolute-changelog`";
 var renderChangelogJson = (changelog) => `${JSON.stringify({
   contract: CHANGELOG_CONTRACT,
   name: changelog.name,
@@ -731,7 +878,7 @@ var renderMarkdown = (changelog, options = {}) => {
     "",
     `All notable changes to \`${changelog.name}\`.`,
     "",
-    "This file is generated by `absolute-changelog` from the entries in",
+    `${GENERATED_MARKER} from the entries in`,
     "`changelog/`. Edit an entry, not this file \u2014 and add new ones under",
     "`changelog/unreleased/`."
   ].join(`
@@ -820,6 +967,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 +996,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 ? "," : ""}`,
@@ -933,22 +1088,45 @@ var check = async (root, flags) => {
   const actual = await readFile3(changelogPaths(root).markdown, "utf8").catch(() => {
     return;
   });
-  if (newest !== undefined && actual !== expected)
+  if (actual !== expected)
     failures.push(`${CHANGELOG_MARKDOWN} is not what the entries say it should be \u2014 it is generated; run \`absolute-changelog release\` or restore it`);
   const tsconfig = await readJsonFile(join2(root, "tsconfig.json"));
   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 shipsTypes = declaresTypes(await readJsonFile(join2(root, "package.json")));
+  if (built === undefined && shipsTypes)
+    failures.push("there are no declaration files where package.json says its types are \u2014 build before the gate, or nothing compares them");
+  if (!shipsTypes)
+    console.warn("  (this package ships no types, so none were compared)");
+  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`);
+  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 (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)`);
+      failures.push(`could not read the published types of ${manifest.name}@${baseline}, so nothing was compared`);
+    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 (failures.length > 0)
@@ -956,16 +1134,23 @@ var check = async (root, flags) => {
   `));
   console.log(`${manifest.name}@${manifest.version}: changelog holds (${entries.length} pending, ${current.releases.length} released)`);
 };
+var LAST2 = -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) => {
-  const path = join2(root, file);
-  const document = await readJsonFile(path);
+  const path2 = join2(root, file);
+  const document = await readJsonFile(path2);
   if (!isPackage(document) || !Array.isArray(document.include))
     return false;
   if (coversEntries(document.include))
     return false;
-  await writeJsonLike(path, {
+  await writeJsonLike(path2, {
     ...document,
     include: [...document.include, "changelog/**/*"]
   });
@@ -976,8 +1161,8 @@ var includeEntries = async (root) => {
   return wired.some(Boolean) ? undefined : "no tsconfig include list to wire \u2014 make sure changelog/ is compiled by something";
 };
 var ignoreGenerated = async (root) => {
-  const path = join2(root, ".prettierignore");
-  const existing = await readFile3(path, "utf8").catch(() => "");
+  const path2 = join2(root, ".prettierignore");
+  const existing = await readFile3(path2, "utf8").catch(() => "");
   const wanted = [CHANGELOG_FILE, CHANGELOG_MARKDOWN].filter((name) => !existing.split(`
 `).includes(name));
   if (wanted.length === 0)
@@ -985,26 +1170,38 @@ var ignoreGenerated = async (root) => {
   const head = existing.trim() === "" ? `# Generated by absolute-changelog. Edit the entries, not these.
 ` : `${existing.trimEnd()}
 `;
-  await writeFile2(path, `${head}${wanted.join(`
+  await writeFile2(path2, `${head}${wanted.join(`
 `)}
 `);
 };
+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);
   await mkdir(paths.unreleased, { recursive: true });
   await writeFile2(join2(paths.unreleased, ".gitkeep"), "# Entries wait here. One file per change; `absolute-changelog release` consumes them.\n");
-  if (existsSync(paths.markdown) && !existsSync(paths.history)) {
-    const previous = await readFile3(paths.markdown, "utf8");
+  const previous = existsSync(paths.markdown) ? await readFile3(paths.markdown, "utf8") : undefined;
+  if (previous !== undefined && !previous.includes(GENERATED_MARKER) && !existsSync(paths.history)) {
     await mkdir(join2(root, "changelog"), { recursive: true });
     await writeFile2(paths.history, previous.replace(/^#\s+Changelog\s*/u, "").trimStart());
     await rm(paths.markdown, { force: true });
   }
   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 +1231,5 @@ await main().catch((error) => {
   process.exit(1);
 });
 
-//# debugId=3B21DCC7DC15D28564756E2164756E21
+//# debugId=0E6F1175A8DDD6A464756E2164756E21
 //# sourceMappingURL=cli.js.map