@riebeckite/plugin-changelog 0.0.6

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright Rerurate_514
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,153 @@
+# @riebeckite/plugin-changelog
+
+Build-time change history derived from local Git history. For every published
+note the plugin adds a "change history" section with commit dates, subjects,
+and authors, and it can build a site-wide changelog dataset from the notes'
+commits. No client-side JavaScript is required.
+
+[日本語](./README_ja.md)
+
+## Overview
+
+`changelog()` reads the local Git repository at build time using the same
+`git` access as [`@riebeckite/plugin-diff`](../diff/README.md) (`execFile` with
+graceful failure). It never invents its own filesystem layer.
+
+Results are published through the manifest `bodySlots` mechanism. Each public
+entry receives its own history in the `article.after-content` slot. The site's
+layout decides whether and where to render that slot, so the plugin stays
+inside the Plugin boundary and does not create application routes. When
+`siteWide` is enabled, the site-wide changelog is written to the slot of the
+note named by `siteWideSlug`; that note (the route) is owned by the app or the
+author, not by this plugin. No client script is registered.
+
+## Usage
+
+```ts
+import { defineConfig } from "@riebeckite/core";
+import { changelog } from "@riebeckite/plugin-changelog";
+
+export default defineConfig({
+  // ...
+  plugins: [
+    changelog({
+      // Point at the content root so Git sees the notes' repository paths.
+      cwd: "./content",
+      lookbackDays: 180,
+      dateFormat: "iso",
+    }),
+  ],
+});
+```
+
+## Options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `cwd` | `string` | `process.cwd()` | Working directory for Git commands |
+| `lookbackDays` | `number` | — (full history) | Only include commits newer than this many days |
+| `dateFormat` | `"iso" \| "long" \| "short"` | `"iso"` | How dates are rendered |
+| `locale` | `string` | `"en"` | Locale for `"long"` / `"short"` dates |
+| `perNote` | `boolean` | `true` | Add a history section to every public note |
+| `siteWide` | `boolean` | `false` | Build and inject the site-wide changelog |
+| `siteWideSlug` | `string` | `"changelog"` | Note that receives the site-wide changelog |
+| `maxPerNote` | `number` | `10` | Maximum commits listed per note |
+| `maxSiteWide` | `number` | `50` | Maximum commits listed site-wide |
+| `showAuthor` | `boolean` | `true` | Show the commit author |
+| `heading` | `boolean` | `true` | Render the `<h2>` heading |
+| `perNoteHeading` | `string` | `"Change history"` | Per-note heading text |
+| `siteWideHeading` | `string` | `"Changelog"` | Site-wide heading text |
+| `className` | `string` | `"rr-changelog"` | Root CSS class |
+
+## Output
+
+The plugin appends a fragment like this to the `article.after-content` slot:
+
+```html
+<section class="rr-changelog rr-changelog--note" data-changelog-note>
+  <h2 class="rr-changelog__heading">Change history</h2>
+  <ol class="rr-changelog__list">
+    <li class="rr-changelog__item">
+      <time class="rr-changelog__date" datetime="2026-09-30T09:00:00+09:00">2026-09-30</time>
+      <span class="rr-changelog__subject">Fix the sidebar offset</span>
+      <span class="rr-changelog__author">Author Name</span>
+      <code class="rr-changelog__hash" title="…full hash…">abc1234</code>
+    </li>
+  </ol>
+</section>
+```
+
+`data-changelog-note` and `data-changelog-site` mark the two fragments for
+styling and idempotency checks.
+
+## App wiring (site-wide changelog)
+
+The site-wide list is data, not a page. The app owns the route; the plugin
+either fills the `article.after-content` slot of an existing note
+(`siteWide: true` + `siteWideSlug`, which requires a public note at that slug)
+or exposes the dataset for the app to render itself:
+
+```ts
+import {
+  buildSiteChangelog,
+  GitChangelogReader,
+  renderSiteChangelog,
+  resolveChangelogOptions,
+} from "@riebeckite/plugin-changelog";
+
+const options = resolveChangelogOptions({ lookbackDays: 90 });
+const manifest = await content.getManifest();
+const reader = new GitChangelogReader({ cwd: "./content" });
+const commits = await reader.getRecentCommits();
+const dataset = buildSiteChangelog({
+  entries: manifest.publicEntries,
+  commits,
+  contentIndex: manifest.contentIndex,
+  options,
+});
+const html = renderSiteChangelog(dataset, options);
+```
+
+The reference app renders manifest `bodySlots` in
+`apps/web/app/components/article/article.tsx`; a dedicated route can render the
+exported HTML directly.
+
+## Failure behavior
+
+When `git` is missing or `cwd` is not a Git repository, the plugin reports a
+`changelog-git-unavailable` warning diagnostic and a logger warning, then leaves
+the build output untouched. The build never fails because history is
+unavailable, and the same guarantee holds for an empty repository.
+
+## Style
+
+The package ships `style.css` with the stable `.rr-changelog` root hook. Themes
+can restyle it without editing the plugin:
+
+```ts
+import "@riebeckite/plugin-changelog/style.css";
+```
+
+## Exports
+
+- `changelog(options?)` — plugin factory
+- `changelogPlugin` — alias of `changelog`
+- `resolveChangelogOptions(options?)` — apply option defaults
+- `GitChangelogReader` — Git-backed history reader (`getFileHistory`,
+  `getRecentCommits`, `isAvailable`)
+- `buildNoteChangeHistory(entry, commits, options)` — per-note dataset
+- `buildSiteChangelog({ entries, commits, contentIndex, options })` — site-wide
+  dataset
+- `renderNoteChangeHistory(history, options)` /
+  `renderSiteChangelog(changelog, options)` — HTML renderers
+- `filterChangelogCommits(commits, options)` /
+  `formatChangelogDate(date, options)` / `resolveLookbackSince(days, now?)` —
+  pure helpers
+- Types: `ChangelogOptions`, `ResolvedChangelogOptions`, `ChangelogCommit`,
+  `ChangelogRecord`, `NoteChangeHistory`, `SiteChangelog`, `SiteChangelogEntry`,
+  `SiteChangelogNote`, `ChangelogDateFormat`, `GitChangelogReaderOptions`
+
+## See also
+
+- [plugin-diff](../diff/README.md) — revision history and line diffs
+- [Plugin guide](../../../docs/en/plugin-system.md)

package/README_ja.md

@@ -0,0 +1,125 @@
+# @riebeckite/plugin-changelog
+
+ローカル Git の履歴からビルド時に変更履歴を生成するプラグインです。公開ノートごとにコミット日・件名・作成者を並べた「変更履歴」セクションを追加し、サイト全体の変更履歴データセットも組み立てられます。クライアント JavaScript は不要です。
+
+[English](./README.md)
+
+## できること
+
+`changelog()` は [`@riebeckite/plugin-diff`](../diff/README_ja.md) と同じ方法でローカル Git を読み取ります（`execFile` で `git` を実行し、失敗時は安全に縮退）。独自のファイルシステム層は作りません。
+
+結果はマニフェストの `bodySlots` に出力します。公開エントリは `article.after-content` スロットに自分の履歴を受け取り、サイト側のレイアウトがそのスロットを描画するかどうかを決めます。プラグインは Plugin の境界を越えず、アプリケーションのルートも作りません。`siteWide` を有効にすると、`siteWideSlug` で指定したノートのスロットにサイト全体の変更履歴を書き込みます。そのノート（＝ルート）はアプリまたは作者が所有するもので、プラグインが作るものではありません。クライアントスクリプトは登録しません。
+
+## 使い方
+
+```ts
+import { defineConfig } from "@riebeckite/core";
+import { changelog } from "@riebeckite/plugin-changelog";
+
+export default defineConfig({
+  // ...
+  plugins: [
+    changelog({
+      // ノートのリポジトリ上のパスが見えるよう、コンテンツのルートを指定します。
+      cwd: "./content",
+      lookbackDays: 180,
+      dateFormat: "iso",
+    }),
+  ],
+});
+```
+
+## オプション
+
+| オプション | 型 | 初期値 | 説明 |
+| --- | --- | --- | --- |
+| `cwd` | `string` | `process.cwd()` | Git コマンドを実行するディレクトリ |
+| `lookbackDays` | `number` | なし（全履歴） | 直近この日数以内のコミットだけを含める |
+| `dateFormat` | `"iso" \| "long" \| "short"` | `"iso"` | 日付の表示形式 |
+| `locale` | `string` | `"en"` | `"long"` / `"short"` のロケール |
+| `perNote` | `boolean` | `true` | 公開ノートごとに履歴セクションを追加する |
+| `siteWide` | `boolean` | `false` | サイト全体の変更履歴を生成して注入する |
+| `siteWideSlug` | `string` | `"changelog"` | サイト全体の変更履歴を受け取るノート |
+| `maxPerNote` | `number` | `10` | ノートごとに表示するコミット上限 |
+| `maxSiteWide` | `number` | `50` | サイト全体で表示するコミット上限 |
+| `showAuthor` | `boolean` | `true` | コミット作成者を表示する |
+| `heading` | `boolean` | `true` | `<h2>` 見出しを描画する |
+| `perNoteHeading` | `string` | `"Change history"` | ノートごとの見出し文言 |
+| `siteWideHeading` | `string` | `"Changelog"` | サイト全体の見出し文言 |
+| `className` | `string` | `"rr-changelog"` | ルート CSS クラス |
+
+## 出力
+
+`article.after-content` スロットに次のような断片を追加します。
+
+```html
+<section class="rr-changelog rr-changelog--note" data-changelog-note>
+  <h2 class="rr-changelog__heading">Change history</h2>
+  <ol class="rr-changelog__list">
+    <li class="rr-changelog__item">
+      <time class="rr-changelog__date" datetime="2026-09-30T09:00:00+09:00">2026-09-30</time>
+      <span class="rr-changelog__subject">Fix the sidebar offset</span>
+      <span class="rr-changelog__author">Author Name</span>
+      <code class="rr-changelog__hash" title="…完全なハッシュ…">abc1234</code>
+    </li>
+  </ol>
+</section>
+```
+
+`data-changelog-note` と `data-changelog-site` は、2 種類の断片をスタイリングと重複防止のために識別する属性です。
+
+## アプリ側の接続（サイト全体の変更履歴）
+
+サイト全体の一覧はページではなくデータです。ルートはアプリが所有します。プラグインは既存ノートの `article.after-content` スロットに書き込む（`siteWide: true` と `siteWideSlug`。その slug の公開ノートが必要）か、データセットを公開してアプリ自身に描画させます。
+
+```ts
+import {
+  buildSiteChangelog,
+  GitChangelogReader,
+  renderSiteChangelog,
+  resolveChangelogOptions,
+} from "@riebeckite/plugin-changelog";
+
+const options = resolveChangelogOptions({ lookbackDays: 90 });
+const manifest = await content.getManifest();
+const reader = new GitChangelogReader({ cwd: "./content" });
+const commits = await reader.getRecentCommits();
+const dataset = buildSiteChangelog({
+  entries: manifest.publicEntries,
+  commits,
+  contentIndex: manifest.contentIndex,
+  options,
+});
+const html = renderSiteChangelog(dataset, options);
+```
+
+参照アプリはマニフェストの `bodySlots` を `apps/web/app/components/article/article.tsx` で描画します。専用ルートでは公開された HTML をそのまま描画できます。
+
+## 失敗時の挙動
+
+`git` が無い、または `cwd` が Git リポジトリでない場合、プラグインは `changelog-git-unavailable` 警告診断とロガー警告を出し、ビルド成果物には何も加えません。履歴が取得できないことを理由にビルドが失敗することはなく、空のリポジトリでも同じです。
+
+## スタイル
+
+パッケージは安定した `.rr-changelog` ルートフックを持つ `style.css` を同梱します。テーマはプラグインを編集せずに見た目を変更できます。
+
+```ts
+import "@riebeckite/plugin-changelog/style.css";
+```
+
+## 公開 API
+
+- `changelog(options?)` — プラグインファクトリ
+- `changelogPlugin` — `changelog` の別名
+- `resolveChangelogOptions(options?)` — 既定値を適用
+- `GitChangelogReader` — Git 履歴リーダー（`getFileHistory`、`getRecentCommits`、`isAvailable`）
+- `buildNoteChangeHistory(entry, commits, options)` — ノート単位のデータセット
+- `buildSiteChangelog({ entries, commits, contentIndex, options })` — サイト全体のデータセット
+- `renderNoteChangeHistory(history, options)` / `renderSiteChangelog(changelog, options)` — HTML レンダラ
+- `filterChangelogCommits(commits, options)` / `formatChangelogDate(date, options)` / `resolveLookbackSince(days, now?)` — 純粋な補助関数
+- 型: `ChangelogOptions`、`ResolvedChangelogOptions`、`ChangelogCommit`、`ChangelogRecord`、`NoteChangeHistory`、`SiteChangelog`、`SiteChangelogEntry`、`SiteChangelogNote`、`ChangelogDateFormat`、`GitChangelogReaderOptions`
+
+## 関連資料
+
+- [plugin-diff](../diff/README_ja.md) — リビジョン履歴と行差分
+- [プラグインシステム](../../../docs/ja/plugin-system.md)

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import type { ChangelogOptions } from "./src/types.js";
+export { buildNoteChangeHistory, buildSiteChangelog, filterChangelogCommits, formatChangelogDate, resolveLookbackSince, } from "./src/changelog.js";
+export { GitChangelogReader, type GitLogWindow, } from "./src/git/history_reader.js";
+export { DEFAULT_CHANGELOG_CLASS_NAME, DEFAULT_CHANGELOG_HEADING, DEFAULT_CHANGELOG_LOCALE, DEFAULT_CHANGELOG_MAX_PER_NOTE, DEFAULT_CHANGELOG_MAX_SITE_WIDE, DEFAULT_CHANGELOG_PER_NOTE_HEADING, DEFAULT_CHANGELOG_SITE_WIDE_HEADING, DEFAULT_CHANGELOG_SITE_WIDE_SLUG, resolveChangelogOptions, } from "./src/options.js";
+export { CHANGELOG_NOTE_ATTRIBUTE, CHANGELOG_SITE_ATTRIBUTE, renderNoteChangeHistory, renderSiteChangelog, } from "./src/render.js";
+export type { ChangelogCommit, ChangelogDateFormat, ChangelogOptions, ChangelogRecord, GitChangelogReaderOptions, NoteChangeHistory, ResolvedChangelogOptions, SiteChangelog, SiteChangelogEntry, SiteChangelogNote, } from "./src/types.js";
+export declare const CHANGELOG_PLUGIN_NAME = "changelog";
+/** Site layout slot the generated history is written to. */
+export declare const CHANGELOG_BODY_SLOT = "article.after-content";
+/**
+ * Git-backed change history for Riebeckite sites.
+ *
+ * At build time the plugin reads local Git history and publishes HTML
+ * fragments through the manifest `bodySlots` mechanism:
+ *
+ * - every public note gets its own "change history" section;
+ * - optionally, a designated note gets the site-wide changelog.
+ *
+ * The plugin never creates a route. The Site owns the note and the layout; the
+ * plugin only fills the `article.after-content` slot. The same dataset is also
+ * exported (`buildSiteChangelog`, `renderSiteChangelog`) so a Site can render
+ * it from its own route. No client JavaScript is required.
+ *
+ * When Git is unavailable the build is left untouched and a warning diagnostic
+ * is reported instead of failing.
+ */
+export declare function changelog(options?: ChangelogOptions): import("@riebeckite/core").RiebeckitePlugin<ChangelogOptions>;
+/** Alias matching the `*Plugin` suffix used by other plugin factories. */
+export declare const changelogPlugin: typeof changelog;

package/dist/index.js

@@ -0,0 +1,445 @@
+// index.ts
+import {
+  appendContentBodySlot,
+  createStyleAsset,
+  definePlugin
+} from "@riebeckite/core";
+
+// src/changelog.ts
+function resolveLookbackSince(lookbackDays, now = /* @__PURE__ */ new Date()) {
+  if (lookbackDays === void 0) return void 0;
+  const since = now.getTime() - lookbackDays * 24 * 60 * 60 * 1e3;
+  return new Date(since).toISOString();
+}
+function formatChangelogDate(isoDate, options) {
+  if (options.dateFormat === "iso") return isoDate.slice(0, 10);
+  const date = new Date(isoDate);
+  if (Number.isNaN(date.getTime())) return isoDate;
+  return new Intl.DateTimeFormat(options.locale, {
+    dateStyle: options.dateFormat === "long" ? "long" : "medium",
+    timeZone: "UTC"
+  }).format(date);
+}
+function filterChangelogCommits(commits, options) {
+  const cutoff = resolveCutoff(options.lookbackDays);
+  return commits.filter((commit) => cutoff === null || Date.parse(commit.date) >= cutoff).toSorted(compareCommitsDescending);
+}
+function buildNoteChangeHistory(entry, commits, options) {
+  return {
+    slug: entry.slug,
+    permalink: entry.permalink,
+    title: entry.title,
+    commits: filterChangelogCommits(commits, options).slice(0, options.maxPerNote).map((commit) => toChangelogRecord(commit, options))
+  };
+}
+function buildSiteChangelog(args) {
+  const byPath = invertContentIndex(args.contentIndex, args.entries);
+  const bySlug = new Map(args.entries.map((entry) => [entry.slug, entry]));
+  const entries = filterChangelogCommits(args.commits, args.options).slice(0, args.options.maxSiteWide).map(
+    (commit) => ({
+      ...toChangelogRecord(commit, args.options),
+      notes: resolveCommitNotes(commit, byPath, bySlug)
+    })
+  );
+  return { entries };
+}
+function toChangelogRecord(commit, options) {
+  return {
+    hash: commit.hash,
+    shortHash: commit.shortHash,
+    date: formatChangelogDate(commit.date, options),
+    dateIso: commit.date,
+    subject: commit.subject,
+    author: commit.author
+  };
+}
+function resolveCommitNotes(commit, byPath, bySlug) {
+  const notes = /* @__PURE__ */ new Map();
+  for (const file of commit.files) {
+    const slug = byPath.get(normalizePath(file));
+    if (!slug) continue;
+    const entry = bySlug.get(slug);
+    if (!entry) continue;
+    notes.set(slug, {
+      slug: entry.slug,
+      permalink: entry.permalink,
+      title: entry.title
+    });
+  }
+  return [...notes.values()].toSorted((a, b) => a.title.localeCompare(b.title));
+}
+function invertContentIndex(contentIndex, entries) {
+  const byPath = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const path = contentIndex.get(entry.slug.toLowerCase());
+    if (path) byPath.set(normalizePath(path), entry.slug);
+  }
+  return byPath;
+}
+function resolveCutoff(lookbackDays) {
+  if (lookbackDays === void 0) return null;
+  return Date.now() - lookbackDays * 24 * 60 * 60 * 1e3;
+}
+function compareCommitsDescending(a, b) {
+  const difference = Date.parse(b.date) - Date.parse(a.date);
+  if (difference !== 0) return difference;
+  return b.hash.localeCompare(a.hash);
+}
+function normalizePath(filePath) {
+  return filePath.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+// src/git/history_reader.ts
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+var execFileAsync = promisify(execFile);
+var fieldSeparator = "";
+var recordSeparator = "";
+var logFormat = ["%H", "%h", "%cI", "%s", "%an"].join(fieldSeparator);
+var GitChangelogReader = class {
+  #cwd;
+  #fileCache = /* @__PURE__ */ new Map();
+  #recentCache;
+  #repositoryAvailable;
+  constructor(options = {}) {
+    this.#cwd = options.cwd ?? process.cwd();
+  }
+  /** Commit history for one file, newest first, following renames. */
+  getFileHistory(filePath, window = {}) {
+    const normalizedPath = normalizeGitPath(filePath);
+    if (window.since)
+      return this.#readFileHistory(normalizedPath, window.since);
+    const cached = this.#fileCache.get(normalizedPath);
+    if (cached) return cached;
+    const history = this.#readFileHistory(normalizedPath);
+    this.#fileCache.set(normalizedPath, history);
+    return history;
+  }
+  /**
+   * Recent commits that touch the working directory, newest first, each with
+   * the paths it changed.
+   */
+  getRecentCommits(window = {}) {
+    if (window.since) return this.#readRecentCommits(window.since);
+    this.#recentCache ??= this.#readRecentCommits();
+    return this.#recentCache;
+  }
+  /** True when `cwd` is inside a Git working tree. */
+  async isAvailable() {
+    this.#repositoryAvailable ??= runGit(this.#cwd, [
+      "rev-parse",
+      "--is-inside-work-tree"
+    ]).then((result) => result.ok && result.stdout.trim() === "true");
+    return this.#repositoryAvailable;
+  }
+  async #readFileHistory(filePath, since) {
+    if (!await this.isAvailable()) return [];
+    const args = ["log", "--follow", `--format=${recordSeparator}${logFormat}`];
+    if (since) args.push(`--since=${since}`);
+    args.push("--", filePath);
+    const result = await runGit(this.#cwd, args);
+    if (!result.ok) return [];
+    return parseCommitRecords(result.stdout);
+  }
+  async #readRecentCommits(since) {
+    if (!await this.isAvailable()) return [];
+    const args = [
+      "log",
+      `--format=${recordSeparator}${logFormat}`,
+      "--name-only"
+    ];
+    if (since) args.push(`--since=${since}`);
+    args.push("--", ".");
+    const result = await runGit(this.#cwd, args);
+    if (!result.ok) return [];
+    return parseCommitRecords(result.stdout);
+  }
+};
+function parseCommitRecords(stdout) {
+  if (!stdout.trim()) return [];
+  return stdout.split(recordSeparator).map((chunk) => chunk.replace(/^\n+/, "").replace(/\n+$/, "")).filter(Boolean).map(parseCommitRecord).filter((commit) => commit !== null);
+}
+function parseCommitRecord(chunk) {
+  const [header = "", ...rest] = chunk.split("\n");
+  const [hash, shortHash, date, subject, author] = header.split(fieldSeparator);
+  if (!hash || !shortHash || !date) return null;
+  return {
+    hash,
+    shortHash,
+    date,
+    subject: subject ?? "",
+    author: author ?? "",
+    files: rest.map((line) => line.trim()).filter(Boolean).map(normalizeGitPath)
+  };
+}
+function normalizeGitPath(filePath) {
+  return filePath.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+async function runGit(cwd, args) {
+  try {
+    const { stdout } = await execFileAsync("git", args, {
+      cwd,
+      maxBuffer: 1024 * 1024 * 10
+    });
+    return { ok: true, stdout };
+  } catch (error) {
+    const stdout = typeof error === "object" && error !== null && "stdout" in error && typeof error.stdout === "string" ? error.stdout : "";
+    return { ok: false, stdout };
+  }
+}
+
+// src/options.ts
+var DEFAULT_CHANGELOG_DATE_FORMAT = "iso";
+var DEFAULT_CHANGELOG_LOCALE = "en";
+var DEFAULT_CHANGELOG_PER_NOTE = true;
+var DEFAULT_CHANGELOG_SITE_WIDE = false;
+var DEFAULT_CHANGELOG_SITE_WIDE_SLUG = "changelog";
+var DEFAULT_CHANGELOG_MAX_PER_NOTE = 10;
+var DEFAULT_CHANGELOG_MAX_SITE_WIDE = 50;
+var DEFAULT_CHANGELOG_SHOW_AUTHOR = true;
+var DEFAULT_CHANGELOG_HEADING = true;
+var DEFAULT_CHANGELOG_PER_NOTE_HEADING = "Change history";
+var DEFAULT_CHANGELOG_SITE_WIDE_HEADING = "Changelog";
+var DEFAULT_CHANGELOG_CLASS_NAME = "rr-changelog";
+function resolveChangelogOptions(options = {}) {
+  return {
+    cwd: optionalText(options.cwd),
+    lookbackDays: options.lookbackDays,
+    dateFormat: options.dateFormat ?? DEFAULT_CHANGELOG_DATE_FORMAT,
+    locale: optionalText(options.locale) ?? DEFAULT_CHANGELOG_LOCALE,
+    perNote: options.perNote ?? DEFAULT_CHANGELOG_PER_NOTE,
+    siteWide: options.siteWide ?? DEFAULT_CHANGELOG_SITE_WIDE,
+    siteWideSlug: optionalText(options.siteWideSlug) ?? DEFAULT_CHANGELOG_SITE_WIDE_SLUG,
+    maxPerNote: options.maxPerNote ?? DEFAULT_CHANGELOG_MAX_PER_NOTE,
+    maxSiteWide: options.maxSiteWide ?? DEFAULT_CHANGELOG_MAX_SITE_WIDE,
+    showAuthor: options.showAuthor ?? DEFAULT_CHANGELOG_SHOW_AUTHOR,
+    heading: options.heading ?? DEFAULT_CHANGELOG_HEADING,
+    perNoteHeading: optionalText(options.perNoteHeading) ?? DEFAULT_CHANGELOG_PER_NOTE_HEADING,
+    siteWideHeading: optionalText(options.siteWideHeading) ?? DEFAULT_CHANGELOG_SITE_WIDE_HEADING,
+    className: optionalText(options.className) ?? DEFAULT_CHANGELOG_CLASS_NAME
+  };
+}
+function optionalText(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed === "" ? void 0 : trimmed;
+}
+
+// src/render.ts
+import { escapeHtml, escapeHtmlAttribute } from "@riebeckite/core";
+var CHANGELOG_NOTE_ATTRIBUTE = "data-changelog-note";
+var CHANGELOG_SITE_ATTRIBUTE = "data-changelog-site";
+function renderNoteChangeHistory(history, options) {
+  if (history.commits.length === 0) return "";
+  const className = escapeHtmlAttribute(options.className);
+  const heading = options.heading ? renderHeading(className, options.perNoteHeading) : "";
+  const items = history.commits.map((commit) => renderCommit(commit, className, options, [])).join("");
+  return `<section class="${className} ${className}--note" ${CHANGELOG_NOTE_ATTRIBUTE}>${heading}<ol class="${className}__list">${items}</ol></section>`;
+}
+function renderSiteChangelog(changelog2, options) {
+  if (changelog2.entries.length === 0) return "";
+  const className = escapeHtmlAttribute(options.className);
+  const heading = options.heading ? renderHeading(className, options.siteWideHeading) : "";
+  const items = changelog2.entries.map((entry) => renderCommit(entry, className, options, entry.notes)).join("");
+  return `<section class="${className} ${className}--site" ${CHANGELOG_SITE_ATTRIBUTE}>${heading}<ol class="${className}__list">${items}</ol></section>`;
+}
+function renderHeading(className, text) {
+  return `<h2 class="${className}__heading">${escapeHtml(text)}</h2>`;
+}
+function renderCommit(commit, className, options, notes) {
+  const author = options.showAuthor ? `<span class="${className}__author">${escapeHtml(commit.author)}</span>` : "";
+  const subject = `<span class="${className}__subject">${escapeHtml(
+    commit.subject
+  )}</span>`;
+  const hash = `<code class="${className}__hash" title="${escapeHtmlAttribute(
+    commit.hash
+  )}">${escapeHtml(commit.shortHash)}</code>`;
+  const date = `<time class="${className}__date" datetime="${escapeHtmlAttribute(
+    commit.dateIso
+  )}">${escapeHtml(commit.date)}</time>`;
+  const noteList = renderNotes(notes, className);
+  return `<li class="${className}__item">${date}${subject}${author}${hash}${noteList}</li>`;
+}
+function renderNotes(notes, className) {
+  if (notes.length === 0) return "";
+  const items = notes.map(
+    (note) => `<li class="${className}__note"><a class="${className}__note-link" href="${escapeHtmlAttribute(
+      note.permalink
+    )}">${escapeHtml(note.title)}</a></li>`
+  ).join("");
+  return `<ul class="${className}__notes">${items}</ul>`;
+}
+
+// index.ts
+var CHANGELOG_PLUGIN_NAME = "changelog";
+var CHANGELOG_BODY_SLOT = "article.after-content";
+var PER_NOTE_CONCURRENCY = 4;
+function changelog(options = {}) {
+  const resolved = resolveChangelogOptions(options);
+  return definePlugin({
+    name: CHANGELOG_PLUGIN_NAME,
+    options,
+    validateOptions: validateChangelogOptions,
+    onManifestCreated: (context) => applyChangelog(context, resolved),
+    assets: [createStyleAsset(CHANGELOG_PLUGIN_NAME)]
+  });
+}
+var changelogPlugin = changelog;
+async function applyChangelog(context, options) {
+  if (!options.perNote && !options.siteWide) return;
+  const reader = new GitChangelogReader({ cwd: options.cwd });
+  if (!await reader.isAvailable()) {
+    reportGitUnavailable(context);
+    return;
+  }
+  const since = resolveLookbackSince(options.lookbackDays);
+  if (options.perNote) {
+    await forEachWithConcurrency(
+      context.manifest.publicEntries,
+      PER_NOTE_CONCURRENCY,
+      async (entry) => {
+        if (options.siteWide && entry.slug === options.siteWideSlug) return;
+        await applyNoteHistory(context, options, reader, entry, since);
+      }
+    );
+  }
+  if (options.siteWide) {
+    await applySiteChangelog(context, options, reader, since);
+  }
+}
+async function applyNoteHistory(context, options, reader, entry, since) {
+  if (hasSlot(entry, CHANGELOG_NOTE_ATTRIBUTE)) return;
+  const filePath = resolveEntryFilePath(entry, context.manifest.contentIndex);
+  const commits = await reader.getFileHistory(filePath, { since });
+  const history = buildNoteChangeHistory(entry, commits, options);
+  const html = renderNoteChangeHistory(history, options);
+  if (html) appendContentBodySlot(entry, CHANGELOG_BODY_SLOT, html);
+}
+async function applySiteChangelog(context, options, reader, since) {
+  const target = context.manifest.publicEntries.find(
+    (entry) => entry.slug === options.siteWideSlug
+  );
+  if (!target) {
+    context.diagnostics.push({
+      code: "changelog-target-missing",
+      severity: "warning",
+      pluginName: CHANGELOG_PLUGIN_NAME,
+      message: `changelog: the site-wide target note "${options.siteWideSlug}" was not found; the site-wide changelog was skipped.`,
+      suggestion: `Create a public note with slug "${options.siteWideSlug}" or set siteWideSlug to an existing note.`
+    });
+    return;
+  }
+  if (hasSlot(target, CHANGELOG_SITE_ATTRIBUTE)) return;
+  const commits = await reader.getRecentCommits({ since });
+  const changelog2 = buildSiteChangelog({
+    entries: context.manifest.publicEntries,
+    commits,
+    contentIndex: context.manifest.contentIndex,
+    options
+  });
+  const html = renderSiteChangelog(changelog2, options);
+  if (html) appendContentBodySlot(target, CHANGELOG_BODY_SLOT, html);
+}
+function resolveEntryFilePath(entry, contentIndex) {
+  const indexedPath = contentIndex.get(entry.slug.toLowerCase());
+  return indexedPath ?? `${entry.slug}.md`;
+}
+function hasSlot(entry, attribute) {
+  return entry.bodySlots?.[CHANGELOG_BODY_SLOT]?.includes(attribute) ?? false;
+}
+function reportGitUnavailable(context) {
+  const message = "changelog: Git is unavailable or this directory is not a Git repository; change history was skipped.";
+  context.diagnostics.push({
+    code: "changelog-git-unavailable",
+    severity: "warning",
+    pluginName: CHANGELOG_PLUGIN_NAME,
+    message
+  });
+  context.logger.warn(message);
+}
+async function forEachWithConcurrency(items, limit, work) {
+  let index = 0;
+  const workers = Array.from(
+    { length: Math.min(limit, items.length) },
+    async () => {
+      while (index < items.length) {
+        const current = items[index];
+        index += 1;
+        await work(current);
+      }
+    }
+  );
+  await Promise.all(workers);
+}
+function validateChangelogOptions(options) {
+  if (!options) return [];
+  const issues = [];
+  const assertNonEmptyString = (key) => {
+    const value = options[key];
+    if (value !== void 0 && (typeof value !== "string" || value.trim() === "")) {
+      issues.push({ path: key, message: "Expected a non-empty string." });
+    }
+  };
+  const assertBoolean = (key) => {
+    if (options[key] !== void 0 && typeof options[key] !== "boolean") {
+      issues.push({ path: key, message: "Expected a boolean." });
+    }
+  };
+  const assertNonNegativeInteger = (key) => {
+    const value = options[key];
+    if (value !== void 0 && (typeof value !== "number" || !Number.isInteger(value) || value < 0)) {
+      issues.push({
+        path: key,
+        message: "Expected a non-negative integer."
+      });
+    }
+  };
+  for (const key of [
+    "cwd",
+    "locale",
+    "siteWideSlug",
+    "perNoteHeading",
+    "siteWideHeading",
+    "className"
+  ]) {
+    assertNonEmptyString(key);
+  }
+  for (const key of ["perNote", "siteWide", "showAuthor", "heading"]) {
+    assertBoolean(key);
+  }
+  for (const key of ["lookbackDays", "maxPerNote", "maxSiteWide"]) {
+    assertNonNegativeInteger(key);
+  }
+  if (options.dateFormat !== void 0 && options.dateFormat !== "iso" && options.dateFormat !== "long" && options.dateFormat !== "short") {
+    issues.push({
+      path: "dateFormat",
+      message: 'Expected "iso", "long", or "short".'
+    });
+  }
+  return issues;
+}
+export {
+  CHANGELOG_BODY_SLOT,
+  CHANGELOG_NOTE_ATTRIBUTE,
+  CHANGELOG_PLUGIN_NAME,
+  CHANGELOG_SITE_ATTRIBUTE,
+  DEFAULT_CHANGELOG_CLASS_NAME,
+  DEFAULT_CHANGELOG_HEADING,
+  DEFAULT_CHANGELOG_LOCALE,
+  DEFAULT_CHANGELOG_MAX_PER_NOTE,
+  DEFAULT_CHANGELOG_MAX_SITE_WIDE,
+  DEFAULT_CHANGELOG_PER_NOTE_HEADING,
+  DEFAULT_CHANGELOG_SITE_WIDE_HEADING,
+  DEFAULT_CHANGELOG_SITE_WIDE_SLUG,
+  GitChangelogReader,
+  buildNoteChangeHistory,
+  buildSiteChangelog,
+  changelog,
+  changelogPlugin,
+  filterChangelogCommits,
+  formatChangelogDate,
+  renderNoteChangeHistory,
+  renderSiteChangelog,
+  resolveChangelogOptions,
+  resolveLookbackSince
+};

package/dist/src/changelog.d.ts

@@ -0,0 +1,27 @@
+import type { ContentManifestEntry } from "@riebeckite/core";
+import type { ChangelogCommit, NoteChangeHistory, ResolvedChangelogOptions, SiteChangelog } from "./types.js";
+/**
+ * Converts a lookback window in days to the ISO timestamp Git's `--since`
+ * accepts. Pure so callers can compute it once per build.
+ */
+export declare function resolveLookbackSince(lookbackDays: number | undefined, now?: Date): string | undefined;
+/** Formats an ISO commit date for display. */
+export declare function formatChangelogDate(isoDate: string, options: ResolvedChangelogOptions): string;
+/**
+ * Filters commits to the lookback window and returns them newest first.
+ * Git already returns newest first; sorting keeps the dataset deterministic
+ * when commits share a timestamp.
+ */
+export declare function filterChangelogCommits(commits: readonly ChangelogCommit[], options: ResolvedChangelogOptions): ChangelogCommit[];
+/** Builds the per-note history for one entry. */
+export declare function buildNoteChangeHistory(entry: ContentManifestEntry, commits: readonly ChangelogCommit[], options: ResolvedChangelogOptions): NoteChangeHistory;
+/**
+ * Builds the site-wide changelog dataset. Each commit is linked to the notes
+ * it touched by matching changed paths against the manifest content index.
+ */
+export declare function buildSiteChangelog(args: {
+    entries: readonly ContentManifestEntry[];
+    commits: readonly ChangelogCommit[];
+    contentIndex: Map<string, string>;
+    options: ResolvedChangelogOptions;
+}): SiteChangelog;

package/dist/src/git/history_reader.d.ts

@@ -0,0 +1,25 @@
+import type { ChangelogCommit, GitChangelogReaderOptions } from "../types.js";
+/** Optional window applied to a Git query. */
+export type GitLogWindow = {
+    /** ISO timestamp passed to `git log --since`. */
+    since?: string;
+};
+/**
+ * Reads local Git history for individual files and for the whole working
+ * directory. Mirrors the Git access used by `@riebeckite/plugin-diff`: it runs
+ * `git` through `execFile` and degrades to empty results when Git is missing or
+ * the directory is not a repository.
+ */
+export declare class GitChangelogReader {
+    #private;
+    constructor(options?: GitChangelogReaderOptions);
+    /** Commit history for one file, newest first, following renames. */
+    getFileHistory(filePath: string, window?: GitLogWindow): Promise<ChangelogCommit[]>;
+    /**
+     * Recent commits that touch the working directory, newest first, each with
+     * the paths it changed.
+     */
+    getRecentCommits(window?: GitLogWindow): Promise<ChangelogCommit[]>;
+    /** True when `cwd` is inside a Git working tree. */
+    isAvailable(): Promise<boolean>;
+}

package/dist/src/options.d.ts

@@ -0,0 +1,18 @@
+import type { ChangelogDateFormat, ChangelogOptions, ResolvedChangelogOptions } from "./types.js";
+export declare const DEFAULT_CHANGELOG_DATE_FORMAT: ChangelogDateFormat;
+export declare const DEFAULT_CHANGELOG_LOCALE = "en";
+export declare const DEFAULT_CHANGELOG_PER_NOTE = true;
+export declare const DEFAULT_CHANGELOG_SITE_WIDE = false;
+export declare const DEFAULT_CHANGELOG_SITE_WIDE_SLUG = "changelog";
+export declare const DEFAULT_CHANGELOG_MAX_PER_NOTE = 10;
+export declare const DEFAULT_CHANGELOG_MAX_SITE_WIDE = 50;
+export declare const DEFAULT_CHANGELOG_SHOW_AUTHOR = true;
+export declare const DEFAULT_CHANGELOG_HEADING = true;
+export declare const DEFAULT_CHANGELOG_PER_NOTE_HEADING = "Change history";
+export declare const DEFAULT_CHANGELOG_SITE_WIDE_HEADING = "Changelog";
+export declare const DEFAULT_CHANGELOG_CLASS_NAME = "rr-changelog";
+/**
+ * Applies defaults to `ChangelogOptions`. Pure and deterministic so the plugin
+ * can resolve options once and reuse them for every manifest entry.
+ */
+export declare function resolveChangelogOptions(options?: ChangelogOptions): ResolvedChangelogOptions;

package/dist/src/render.d.ts

@@ -0,0 +1,15 @@
+import type { NoteChangeHistory, ResolvedChangelogOptions, SiteChangelog } from "./types.js";
+/** Boolean attribute that marks a rendered per-note history section. */
+export declare const CHANGELOG_NOTE_ATTRIBUTE = "data-changelog-note";
+/** Boolean attribute that marks the rendered site-wide changelog section. */
+export declare const CHANGELOG_SITE_ATTRIBUTE = "data-changelog-site";
+/**
+ * Renders a note's change history. Returns an empty string when there is
+ * nothing to show, so callers can leave the entry's HTML untouched.
+ */
+export declare function renderNoteChangeHistory(history: NoteChangeHistory, options: ResolvedChangelogOptions): string;
+/**
+ * Renders the site-wide changelog dataset. Returns an empty string when there
+ * are no commits, so callers can leave the target's HTML untouched.
+ */
+export declare function renderSiteChangelog(changelog: SiteChangelog, options: ResolvedChangelogOptions): string;

package/dist/src/types.d.ts

@@ -0,0 +1,108 @@
+/** How commit dates are formatted in rendered output. */
+export type ChangelogDateFormat = "iso" | "long" | "short";
+/** Options accepted by `changelog()`. */
+export type ChangelogOptions = {
+    /**
+     * Working directory for Git commands. Defaults to `process.cwd()`. Point it
+     * at the content directory when the site is built from elsewhere.
+     */
+    cwd?: string;
+    /**
+     * Only include commits newer than this many days. When omitted, the full
+     * history is used.
+     */
+    lookbackDays?: number;
+    /** Date format for rendered entries. Defaults to `"iso"`. */
+    dateFormat?: ChangelogDateFormat;
+    /** Locale used by `"long"` and `"short"` dates. Defaults to `"en"`. */
+    locale?: string;
+    /** Render a per-note history section on every public note. Defaults to `true`. */
+    perNote?: boolean;
+    /**
+     * Build the site-wide changelog and inject it into the note at
+     * `siteWideSlug`. Defaults to `false`. The note itself is owned by the app;
+     * the plugin only fills its body slot.
+     */
+    siteWide?: boolean;
+    /** Slug of the note that receives the site-wide changelog. Defaults to `"changelog"`. */
+    siteWideSlug?: string;
+    /** Maximum commits listed per note. Defaults to `10`. */
+    maxPerNote?: number;
+    /** Maximum commits listed in the site-wide changelog. Defaults to `50`. */
+    maxSiteWide?: number;
+    /** Show the commit author. Defaults to `true`. */
+    showAuthor?: boolean;
+    /** Render an `<h2>` heading above each listing. Defaults to `true`. */
+    heading?: boolean;
+    /** Heading text for per-note history. Defaults to `"Change history"`. */
+    perNoteHeading?: string;
+    /** Heading text for the site-wide changelog. Defaults to `"Changelog"`. */
+    siteWideHeading?: string;
+    /** Root CSS class. Defaults to `"rr-changelog"`. */
+    className?: string;
+};
+/** `ChangelogOptions` with every default applied. */
+export type ResolvedChangelogOptions = {
+    cwd?: string;
+    lookbackDays?: number;
+    dateFormat: ChangelogDateFormat;
+    locale: string;
+    perNote: boolean;
+    siteWide: boolean;
+    siteWideSlug: string;
+    maxPerNote: number;
+    maxSiteWide: number;
+    showAuthor: boolean;
+    heading: boolean;
+    perNoteHeading: string;
+    siteWideHeading: string;
+    className: string;
+};
+/** A commit exactly as returned by the Git-backed reader. */
+export type ChangelogCommit = {
+    hash: string;
+    shortHash: string;
+    /** ISO 8601 committer date. */
+    date: string;
+    subject: string;
+    author: string;
+    /** Paths changed by the commit, relative to the Git working directory. */
+    files: string[];
+};
+/** A commit prepared for rendering. */
+export type ChangelogRecord = {
+    hash: string;
+    shortHash: string;
+    /** Display date formatted for the resolved options. */
+    date: string;
+    /** Machine-readable ISO 8601 date. */
+    dateIso: string;
+    subject: string;
+    author: string;
+};
+/** Per-note change history, ready to render. */
+export type NoteChangeHistory = {
+    slug: string;
+    permalink: string;
+    title: string;
+    commits: ChangelogRecord[];
+};
+/** A note touched by a site-wide changelog commit. */
+export type SiteChangelogNote = {
+    slug: string;
+    permalink: string;
+    title: string;
+};
+/** A site-wide changelog entry: a commit plus the notes it touched. */
+export type SiteChangelogEntry = ChangelogRecord & {
+    notes: SiteChangelogNote[];
+};
+/** The site-wide changelog dataset, ready for the app to render. */
+export type SiteChangelog = {
+    entries: SiteChangelogEntry[];
+};
+/** Options accepted by `GitChangelogReader`. */
+export type GitChangelogReaderOptions = {
+    /** Working directory for Git commands. Defaults to `process.cwd()`. */
+    cwd?: string;
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@riebeckite/plugin-changelog",
+  "version": "0.0.6",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "source": "./index.ts",
+      "default": "./dist/index.js"
+    },
+    "./style.css": "./style.css"
+  },
+  "dependencies": {
+    "@riebeckite/core": "0.0.6"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "README_ja.md",
+    "dist",
+    "style.css"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Rerurate514/riebeckite.git",
+    "directory": "packages/plugins/changelog"
+  },
+  "homepage": "https://github.com/Rerurate514/riebeckite#readme",
+  "bugs": {
+    "url": "https://github.com/Rerurate514/riebeckite/issues"
+  },
+  "description": "Git-backed change history and changelogs for Riebeckite.",
+  "keywords": [
+    "riebeckite",
+    "plugin",
+    "git",
+    "changelog"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "sideEffects": [
+    "./style.css"
+  ],
+  "scripts": {
+    "build": "node ../../../scripts/build_package.mjs"
+  }
+}

package/style.css

@@ -0,0 +1,97 @@
+.rr-changelog {
+  margin-block: 3rem 2rem;
+  border-block-start: 1px solid
+    var(--rb-color-border, color-mix(in srgb, currentColor 18%, transparent));
+  padding-block-start: 1.25rem;
+  color: var(--rb-color-ink, currentColor);
+}
+
+.rr-changelog__heading {
+  margin: 0 0 0.75rem;
+  font-size: 0.8125rem;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.rr-changelog__list {
+  display: grid;
+  gap: 0.75rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.rr-changelog__item {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  gap: 0.5rem 0.75rem;
+  border-block-start: 1px solid
+    var(--rb-color-border, color-mix(in srgb, currentColor 12%, transparent));
+  padding-block-start: 0.75rem;
+}
+
+.rr-changelog__item:first-child {
+  border-block-start: 0;
+  padding-block-start: 0;
+}
+
+.rr-changelog__date {
+  min-width: 6rem;
+  color: var(
+    --rb-color-muted,
+    color-mix(in srgb, currentColor 62%, transparent)
+  );
+  font-size: 0.8125rem;
+  font-variant-numeric: tabular-nums;
+}
+
+.rr-changelog__subject {
+  flex: 1 1 12rem;
+  overflow-wrap: anywhere;
+  font-size: 0.9375rem;
+  line-height: 1.45;
+}
+
+.rr-changelog__author {
+  color: var(
+    --rb-color-muted,
+    color-mix(in srgb, currentColor 62%, transparent)
+  );
+  font-size: 0.8125rem;
+}
+
+.rr-changelog__hash {
+  font-family: var(
+    --rb-font-mono,
+    ui-monospace,
+    SFMono-Regular,
+    Consolas,
+    monospace
+  );
+  font-size: 0.75rem;
+  color: var(
+    --rb-color-muted,
+    color-mix(in srgb, currentColor 56%, transparent)
+  );
+}
+
+.rr-changelog__notes {
+  display: flex;
+  flex-basis: 100%;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.rr-changelog__note-link {
+  color: var(--rb-color-accent, currentColor);
+  font-size: 0.8125rem;
+}
+
+.rr-changelog--site .rr-changelog__item {
+  padding-block-end: 0.25rem;
+}