@absolutejs/changelog 0.1.2 → 0.3.0

package/dist/reconcile.d.ts

@@ -1,11 +1,13 @@
-import { type SurfaceDiff } from "./surface";
+import type { SurfaceDiff } from "./surface";
 import { type Change } from "./types";
 export type Unannounced = {
-    /** Why it matters: gone entirely, or the call shape moved. */
-    kind: "removed" | "parameters" | "members";
+    /** Gone entirely, or what about its declaration moved. */
+    kind: "removed" | "parameters" | "members" | "types";
     name: string;
 };
 export type Reconciliation = {
+    /** Entries whose migration does not describe what the package did. */
+    wrongMigrations: string[];
     /** Exports that moved with nothing written about them. */
     unannounced: Unannounced[];
     /** Names entries claim that this package has never exported. A typo, or
@@ -15,9 +17,18 @@ export type Reconciliation = {
 /** What to print when it fails, in the order somebody fixes them. */
 export declare const describeReconciliation: (found: Reconciliation) => string[];
 export declare const reconcile: (input: {
+    /** Every entry that speaks for the versions being compared: the ones
+     *  waiting for a release, and the ones a release already consumed but the
+     *  registry has not seen yet. */
     changes: readonly Change[];
     diff: SurfaceDiff;
     /** Every name the package exported before or after, for catching entries
      *  that name something that was never there. */
     known: ReadonlySet<string>;
+    /** What the package exports now, for checking that a migration describes
+     *  what it says it describes. */
+    after?: ReadonlySet<string>;
+    /** The package's entry points, so a migration cannot point at one that is
+     *  not there. Empty means "not known", and the check is skipped. */
+    subpaths?: ReadonlySet<string>;
 }) => Reconciliation;

package/dist/registry.d.ts

@@ -1,3 +1,4 @@
+export declare const isPackageName: (name: string) => boolean;
 export type RegistryOptions = {
     fetch?: typeof fetch;
     /** For a private registry, or a test. */

package/dist/surface.d.ts

@@ -1,24 +1,17 @@
-/**
- * The exported names of one declaration file, each with the declaration it
- * stands for.
- *
- * Overloads and merged declarations share a name; they are joined, so adding
- * an overload reads as a change to that name rather than as a replacement.
- */
-export declare const exportedDeclarations: (source: string) => Map<string, string>;
 export type PackageSurface = Map<string, string>;
+/** Whether a manifest claims to ship types at all. A package that ships none
+ *  has no promise of this kind to check; one that claims some and has none is
+ *  a package about to publish types it did not build. */
+export declare const declaresTypes: (manifest: unknown) => boolean;
 /** The surface of a package tarball, already gunzipped. */
-export declare const surfaceOfArchive: (archive: Uint8Array) => PackageSurface;
+export declare const surfaceOfArchive: (archive: Uint8Array) => PackageSurface | undefined;
 /**
- * Every exported name in a package's declaration files.
- *
- * A name usually appears twice: where it is declared, and in the index that
- * passes it along. The declaration wins wherever both are found, whichever
- * file the archive happened to put first -- otherwise the same package reads
- * as `export { syncSocket }` in one version and as its full signature in the
- * next, and the two compare as a change nobody made.
+ * The public surface of a package: what its entry points export, and what
+ * each of those names is declared as.
  */
-export declare const surfaceOfFiles: (files: Iterable<string>) => PackageSurface;
+export declare const surfaceOfFiles: (files: ReadonlyMap<string, string>, entries: readonly string[]) => PackageSurface;
+/** The declaration files a manifest points at, as paths inside the package. */
+export declare const typeEntriesOf: (manifest: unknown, files: ReadonlyMap<string, string>) => string[];
 declare const SHAPE: {
     readonly members: "members";
     readonly parameters: "parameters";
@@ -44,12 +37,18 @@ export type SurfaceDiff = {
 /**
  * What moved between two surfaces.
  *
- * Removed is the one that breaks a build outright. Changed is the one that may:
- * a widened parameter is not a break and a narrowed one is, and telling them
- * apart is a job for whoever reads the two declarations -- so both are carried
- * rather than judged here.
+ * Removed is the one that breaks a build outright. Changed is the one that
+ * may: a widened parameter is not a break and a narrowed one is, and telling
+ * them apart is a job for whoever reads the two declarations -- so both are
+ * carried rather than judged here.
  */
 export declare const diffSurface: (before: PackageSurface, after: PackageSurface) => SurfaceDiff;
-/** The changes in a diff that a caller would notice. */
+/**
+ * The changes a consumer would notice, for an advisor deciding what to put in
+ * front of somebody.
+ *
+ * Not for the gate: `types` changes are still changes, and the package that
+ * made one is the party that can say in one line whether it matters.
+ */
 export declare const notable: (diff: SurfaceDiff) => SurfaceChange[];
 export {};

package/dist/types.d.ts

@@ -19,12 +19,12 @@ export type DisruptiveKind = (typeof DISRUPTIVE_KINDS)[number];
  * `manual` is the honest escape hatch. A changed meaning is not a rewrite
  * anybody should automate, and pretending otherwise is worse than saying so.
  */
-export type Migration = 
+export type Migration<TSymbol extends string = string> = 
 /** An export kept its meaning and changed its name. */
 {
     readonly instruction: string;
     readonly rename: {
-        readonly from: string;
+        readonly from: TSymbol;
         readonly to: string;
     };
 }
@@ -32,7 +32,7 @@ export type Migration =
  | {
     readonly instruction: string;
     readonly moved: {
-        readonly symbol: string;
+        readonly symbol: TSymbol;
         readonly from: string;
         readonly to: string;
     };
@@ -50,6 +50,38 @@ export type Migration =
     readonly instruction: string;
     readonly manual: true;
 };
+/**
+ * The names a package exports, for an entry that wants them checked.
+ *
+ * An entry can be written against the package's own public API:
+ *
+ * ```ts
+ * import type * as Api from "../../src/index";
+ * import type { Change } from "@absolutejs/changelog";
+ *
+ * export const change: Change<typeof Api> = {
+ *   kind: "fixed",
+ *   summary: "stops throwing on an empty list",
+ *   symbols: ["listen"] // an export, or the compiler says so
+ * };
+ * ```
+ *
+ * Suggested rather than required, for two reasons that both matter. A
+ * disruptive change is usually about something that has just stopped
+ * existing -- the release that removes `start` is the release that writes the
+ * entry about it -- and `typeof Api` cannot see type-only exports at all, so
+ * insisting would reject an entry about `Change` or `Release` for being
+ * something this package definitely exports.
+ *
+ * What that leaves is an editor that completes the name and a gate that is
+ * certain: the release check reads the published `.d.ts`, which does carry
+ * the type exports, and refuses an entry naming something the package has
+ * never exported.
+ */
+type Exported<TApi> = TApi extends object ? Extract<keyof TApi, string> : string;
+/** Autocompleted, not restricted: an entry may name an export that has just
+ *  stopped being one. */
+type Suggested<TApi> = Exported<TApi> | (string & {});
 type ChangeBase = {
     /** One line, imperative, in the reader's terms rather than the
      *  implementation's. */
@@ -66,19 +98,19 @@ type ChangeBase = {
  * the package's published types, and what lets a project be told whether the
  * change reaches any of its files. An entry without it can only ever be read.
  */
-export type DisruptiveChange = ChangeBase & {
+export type DisruptiveChange<TApi = unknown> = ChangeBase & {
     readonly kind: DisruptiveKind;
-    readonly symbols: NonEmpty<string>;
-    readonly migration: Migration;
+    readonly symbols: NonEmpty<Suggested<TApi>>;
+    readonly migration: Migration<Suggested<TApi>>;
 };
-export type OrdinaryChange = ChangeBase & {
+export type OrdinaryChange<TApi = unknown> = ChangeBase & {
     readonly kind: Exclude<ChangeKind, DisruptiveKind>;
     /** Optional here, and still worth filling in: it is what connects a fix
      *  to the export somebody is looking at. */
-    readonly symbols?: readonly string[];
+    readonly symbols?: readonly Suggested<TApi>[];
     readonly migration?: never;
 };
-export type Change = DisruptiveChange | OrdinaryChange;
+export type Change<TApi = unknown> = DisruptiveChange<TApi> | OrdinaryChange<TApi>;
 export type Release = {
     readonly version: string;
     /** ISO date, the day it was published. */

package/dist/write.d.ts

@@ -1,4 +1,13 @@
 import { type Changelog } from "./types";
+/**
+ * The line that says this file was generated.
+ *
+ * Load-bearing: adopting a package reads whatever `CHANGELOG.md` said before
+ * and keeps it as history, and on a second adoption the file it generated the
+ * first time is what it finds. Without a way to recognise its own output it
+ * files that as history and prints the header underneath itself.
+ */
+export declare const GENERATED_MARKER = "This file is generated by `absolute-changelog`";
 export type MarkdownOptions = {
     /** Whatever the package's changelog said before it was generated, kept
      *  under the releases that came after it. History is not noise. */

package/package.json

@@ -1,72 +1,76 @@
 {
-  "name": "@absolutejs/changelog",
-  "version": "0.1.2",
-  "description": "The changelog contract for the AbsoluteJS packages. Changes are written as typed entries the compiler checks, the release gate reconciles them against the package's own published types so a change nobody wrote down cannot ship, and migrations are data rather than prose so an upgrade can be applied instead of read.",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/absolutejs/changelog.git"
-  },
-  "homepage": "https://github.com/absolutejs/changelog",
-  "bugs": {
-    "url": "https://github.com/absolutejs/changelog/issues"
-  },
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "type": "module",
-  "license": "MIT",
-  "author": "Alex Kahn",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
-    }
-  },
-  "bin": {
-    "absolute-changelog": "dist/cli.js"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "CHANGELOG.md",
-    "LICENSE",
-    "README.md",
-    "changelog.json",
-    "dist"
-  ],
-  "scripts": {
-    "build": "rm -rf dist && bun build src/index.ts src/cli.ts --outdir dist --root src --sourcemap --target=bun && tsc --project tsconfig.build.json",
-    "test": "bun test tests/",
-    "typecheck": "tsc --noEmit",
-    "format": "prettier --write \"./**/*.{ts,json,md}\"",
-    "lint": "eslint . --max-warnings 0",
-    "changelog": "bun src/cli.ts",
-    "check:package": "bun run typecheck && bun run lint && bun run test && bun run build && bun src/cli.ts check",
-    "release": "bun run format && bun run check:package && bun publish"
-  },
-  "keywords": [
-    "absolutejs",
-    "changelog",
-    "codemod",
-    "migration",
-    "release",
-    "semver",
-    "upgrade"
-  ],
-  "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@stylistic/eslint-plugin": "^5.10.0",
-    "@types/bun": "^1.3.14",
-    "@typescript-eslint/parser": "^8.68.0",
-    "eslint": "^10.9.1",
-    "eslint-plugin-absolute": "^0.11.34",
-    "eslint-plugin-promise": "^7.3.0",
-    "eslint-plugin-security": "^4.0.1",
-    "globals": "^17.11.0",
-    "prettier": "^3.5.3",
-    "typescript": "^5.8.3",
-    "typescript-eslint": "^8.56.0"
-  }
+	"name": "@absolutejs/changelog",
+	"version": "0.3.0",
+	"description": "The changelog contract for the AbsoluteJS packages. Changes are written as typed entries the compiler checks, the release gate reconciles them against the package's own published types so a change nobody wrote down cannot ship, and migrations are data rather than prose so an upgrade can be applied instead of read.",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/absolutejs/changelog.git"
+	},
+	"homepage": "https://github.com/absolutejs/changelog",
+	"bugs": {
+		"url": "https://github.com/absolutejs/changelog/issues"
+	},
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"type": "module",
+	"license": "MIT",
+	"author": "Alex Kahn",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"bin": {
+		"absolute-changelog": "dist/cli.js"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"CHANGELOG.md",
+		"LICENSE",
+		"README.md",
+		"changelog.json",
+		"dist"
+	],
+	"scripts": {
+		"build": "rm -rf dist && bun build src/index.ts src/cli.ts --outdir dist --root src --sourcemap --target=bun --external typescript && tsc --project tsconfig.build.json",
+		"test": "bun test tests/",
+		"typecheck": "tsc --noEmit",
+		"format": "prettier --write \"./**/*.{ts,json,md}\"",
+		"lint": "eslint . --max-warnings 0",
+		"changelog": "bun src/cli.ts",
+		"check:package": "bun run typecheck && bun run lint && bun run test && bun run build && bun src/cli.ts check",
+		"release": "bun run format && bun run check:package && bun publish",
+		"prepublishOnly": "bun src/cli.ts check"
+	},
+	"keywords": [
+		"absolutejs",
+		"changelog",
+		"codemod",
+		"migration",
+		"release",
+		"semver",
+		"upgrade"
+	],
+	"devDependencies": {
+		"@eslint/js": "^10.0.1",
+		"@stylistic/eslint-plugin": "^5.10.0",
+		"@types/bun": "^1.3.14",
+		"@typescript-eslint/parser": "^8.68.0",
+		"eslint": "^10.9.1",
+		"eslint-plugin-absolute": "^0.11.34",
+		"eslint-plugin-promise": "^7.3.0",
+		"eslint-plugin-security": "^4.0.1",
+		"globals": "^17.11.0",
+		"prettier": "^3.5.3",
+		"typescript": "^5.8.3",
+		"typescript-eslint": "^8.56.0"
+	},
+	"dependencies": {
+		"typescript": "^5.8.3"
+	}
 }