@absolutejs/changelog 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to `@absolutejs/changelog`.
+
+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.1.0 — 2026-09-10
+
+### Added
+
+- **The changelog contract: typed entries, a gate that checks them against the package's own types, and migrations as data**

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Kahn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# @absolutejs/changelog
+
+The changelog contract for the AbsoluteJS packages.
+
+A changelog is worth having when it can be trusted and acted on. Prose
+changelogs manage neither: they rot because writing them is a discipline, and
+they cannot be acted on because "refactored the server options" is a true
+sentence that does not say which export moved or what to write instead.
+
+This package makes both possible.
+
+- **Entries are typed.** A change is written as TypeScript, so the compiler
+  insists that a breaking change names the exports it breaks and says how to
+  migrate. The entries that cost somebody an afternoon are the ones that
+  cannot be filed empty.
+- **The release gate checks them against the package.** Before a release goes
+  out, the exports that vanished or changed shape are compared with the
+  exports the entries name. Forget an entry and the release stops. Nobody has
+  to remember.
+- **Migrations are data.** A rename and a move are the overwhelming majority
+  of real breaking changes, and both are mechanical. Written as data they can
+  be applied — by a CLI, an editor, or a hosted upgrade button — without
+  running a line of code that came from a registry.
+
+## Adopting it
+
+```sh
+bun add -d @absolutejs/changelog
+bunx absolute-changelog adopt
+```
+
+`adopt` creates `changelog/unreleased/`, keeps whatever `CHANGELOG.md` already
+said as `changelog/history.md`, adds `changelog.json` and `CHANGELOG.md` to the
+package's `files`, and makes sure your tsconfig compiles the entries — that
+last one matters, because an entry nothing compiles is an entry nobody checks.
+
+Then add the gate to the release chain:
+
+```json
+"check:package": "bun run typecheck && bun run build && bun run test && absolute-changelog check"
+```
+
+Put it after `build`: the check compares the types you are about to publish
+against the ones you published last time, and it needs `dist` to exist.
+
+## Writing a change
+
+One file per change, so two branches adding one do not meet over the same
+line:
+
+```sh
+bunx absolute-changelog add --kind added --summary "listen accepts a unix socket path"
+
+bunx absolute-changelog add \
+  --kind breaking \
+  --summary "start is now listen" \
+  --symbol start \
+  --instruction "Import listen instead of start." \
+  --rename-to listen
+```
+
+Which writes `changelog/unreleased/start-is-now-listen.ts`:
+
+```ts
+import type { Change } from "@absolutejs/changelog";
+
+const entry: Change = {
+  kind: "breaking",
+  migration: {
+    instruction: "Import listen instead of start.",
+    rename: { from: "start", to: "listen" },
+  },
+  summary: "start is now listen",
+  symbols: ["start"],
+};
+
+export default entry;
+```
+
+The import is type-only, so an entry has nothing to resolve at run time and
+the gate works in a checkout with no dependencies installed.
+
+### The kinds
+
+`breaking` and `removed` cost a consumer work, and the type refuses them
+without `symbols` and a `migration`. `added`, `changed`, `deprecated`,
+`fixed`, `security` and `internal` do not.
+
+### The migrations
+
+| Shape                         | What it means                                   | Applied |
+| ----------------------------- | ----------------------------------------------- | ------- |
+| `rename: { from, to }`        | An export kept its meaning and changed its name | yes     |
+| `moved: { symbol, from, to }` | An export moved to another entry point          | yes     |
+| `resubpath: { from, to }`     | A whole entry point moved                       | yes     |
+| `manual: true`                | Somebody has to read the call                   | no      |
+
+`manual` is not a failure. A changed meaning is not a rewrite anybody should
+automate, and pretending otherwise is worse than saying so.
+
+## Releasing
+
+```sh
+bunx absolute-changelog release
+```
+
+Works out the version from the entries — a breaking change moves the minor
+below `1.0.0` and the major above it, and a version already on a prerelease
+line moves along that line — then writes `changelog.json` and `CHANGELOG.md`,
+bumps `package.json`, and deletes the entries it consumed.
+
+`--as major|minor|patch|prerelease` overrides the inference, `--version x.y.z`
+overrides it entirely, and `--dry` shows the release without writing anything.
+
+## The gate
+
+```sh
+bunx absolute-changelog check
+```
+
+- every entry parses, and the disruptive ones carry what they must;
+- `CHANGELOG.md` is what the entries say it should be — it is generated, and
+  editing it is how the two copies drift;
+- the version in `package.json` and the newest release agree;
+- the entries name every export that moved since the last published version.
+
+`--offline` skips the last one, which is the only one that talks to the
+registry.
+
+## Reading somebody else's
+
+Anything deciding whether an upgrade is safe reads the published document:
+
+```ts
+import {
+  applyMigrations,
+  migrationsBetween,
+  publishedChangelog,
+} from "@absolutejs/changelog";
+
+const changelog = await publishedChangelog("@absolutejs/example", "2.1.0");
+const migrations = changelog
+  ? migrationsBetween(changelog, "1.4.0", "2.1.0")
+  : [];
+
+const upgraded = applyMigrations(source, {
+  migrations: migrations.map((at) => at.migration),
+  packageName: "@absolutejs/example",
+});
+```
+
+For a package that has not adopted this yet, `publishedSurface` and
+`diffSurface` compare the published types of two versions instead — less than
+a changelog, and much more than nothing.
+
+## Licence
+
+MIT.

package/changelog.json

@@ -0,0 +1,16 @@
+{
+  "contract": 1,
+  "name": "@absolutejs/changelog",
+  "releases": [
+    {
+      "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/apply.d.ts

@@ -0,0 +1,34 @@
+import { type Migration } from "./types";
+export type MigrationResult = {
+    /** Whether anything in this file changed. */
+    changed: boolean;
+    /** Anything the reader of the diff should know. */
+    notes: string[];
+    source: string;
+};
+/**
+ * Apply one migration to one file.
+ *
+ * A file the migration does not touch comes back unchanged, which is the
+ * ordinary case: a project imports a dozen names from a package that moved a
+ * hundred.
+ */
+export declare const applyMigration: (source: string, input: {
+    migration: Migration;
+    packageName: string;
+}) => {
+    changed: boolean;
+    notes: string[];
+    source: string;
+};
+/**
+ * Apply migrations in order.
+ *
+ * Order matters: a symbol renamed in one release and moved in the next has to
+ * be renamed first, or the move goes looking for a name that is no longer
+ * there.
+ */
+export declare const applyMigrations: (source: string, input: {
+    migrations: readonly Migration[];
+    packageName: string;
+}) => MigrationResult;

package/dist/authoring.d.ts

@@ -0,0 +1,79 @@
+import type { Change, Migration } from "./types";
+/**
+ * Record one change.
+ *
+ * Written as its own file under `changelog/unreleased/`, so two branches each
+ * adding a change do not meet over the same line of the same file. The file
+ * name is yours; something short and about the change reads best in a diff.
+ *
+ * ```ts
+ * import { change } from '@absolutejs/changelog';
+ *
+ * export default change({
+ *   kind: 'breaking',
+ *   summary: 'serve() takes an options object',
+ *   symbols: ['serve'],
+ *   migration: {
+ *     instruction: 'Pass { port } instead of a bare port.',
+ *     manual: true
+ *   }
+ * });
+ * ```
+ */
+export declare const change: <const T extends Change>(entry: T) => T;
+/** A migration nobody should automate, said as such rather than left off. */
+export declare const manual: (instruction: string) => Migration;
+/**
+ * Record an export moving between entry points.
+ *
+ * The second most common, and the one people most often discover by way of a
+ * failed build with no explanation in it.
+ */
+export declare const moved: (input: {
+    symbol: string;
+    from: string;
+    to: string;
+    detail?: string;
+    reference?: string;
+}) => {
+    readonly summary: `\`${string}\` moved to \`${string}\``;
+    readonly symbols: readonly [string];
+    readonly reference?: string | undefined;
+    readonly kind: "breaking";
+    readonly migration: {
+        readonly instruction: `Import \`${string}\` from \`${string}\`.`;
+        readonly moved: {
+            readonly from: string;
+            readonly symbol: string;
+            readonly to: string;
+        };
+    };
+    readonly detail?: string | undefined;
+};
+/**
+ * Record a rename.
+ *
+ * The most common breaking change there is, and the one worth having a
+ * shorthand for -- both because it is written often and because writing it
+ * this way is what makes it applicable rather than readable.
+ */
+export declare const renamed: (input: {
+    from: string;
+    to: string;
+    /** Anything a reader needs beyond "it is called this now". */
+    detail?: string;
+    reference?: string;
+}) => {
+    readonly summary: `\`${string}\` is now \`${string}\``;
+    readonly symbols: readonly [string];
+    readonly reference?: string | undefined;
+    readonly kind: "breaking";
+    readonly migration: {
+        readonly instruction: `Import \`${string}\` instead of \`${string}\`.`;
+        readonly rename: {
+            readonly from: string;
+            readonly to: string;
+        };
+    };
+    readonly detail?: string | undefined;
+};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};