@riebeckite/plugin-changelog 0.0.14 → 0.0.16

package/README.md

@@ -44,7 +44,7 @@ export default defineConfig({
 
 | Option | Type | Default | Description |
 | ------ | ---- | ------- | ----------- |
-| `cwd` | `string` | `process.cwd()` | Working directory for Git commands |
+| `cwd` | `string` | `config.content.directory`, else `process.cwd()` | Content root used to locate the Git work tree |
 | `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 |
@@ -114,10 +114,12 @@ 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.
+When `git` cannot be started, the plugin reports a `changelog-git-unavailable`
+warning diagnostic. When the content directory is not inside a Git working
+tree, it reports `changelog-content-outside-repository`. Either way a logger
+warning accompanies it and the build output is left untouched. The build never
+fails because history is unavailable, and the same guarantee holds for an empty
+repository.
 
 ## Style
 
@@ -150,4 +152,5 @@ import "@riebeckite/plugin-changelog/style.css";
 ## See also
 
 - [plugin-diff](../diff/README.md) — revision history and line diffs
-- [Plugin guide](../../../docs/en/reference/plugin-api.md)
+- [Plugin guide](../../../docs/en/docs/reference/plugin-api.md)
+

package/README_ja.md

@@ -33,7 +33,7 @@ export default defineConfig({
 
 | オプション | 型 | 初期値 | 説明 |
 | --- | --- | --- | --- |
-| `cwd` | `string` | `process.cwd()` | Git コマンドを実行するディレクトリ |
+| `cwd` | `string` | `config.content.directory`、無ければ `process.cwd()` | Git リポジトリを探すためのコンテンツルート |
 | `lookbackDays` | `number` | なし（全履歴） | 直近この日数以内のコミットだけを含める |
 | `dateFormat` | `"iso" \| "long" \| "short"` | `"iso"` | 日付の表示形式 |
 | `locale` | `string` | `"en"` | `"long"` / `"short"` のロケール |
@@ -97,7 +97,7 @@ const html = renderSiteChangelog(dataset, options);
 
 ## 失敗時の挙動
 
-`git` が無い、または `cwd` が Git リポジトリでない場合、プラグインは `changelog-git-unavailable` 警告診断とロガー警告を出し、ビルド成果物には何も加えません。履歴が取得できないことを理由にビルドが失敗することはなく、空のリポジトリでも同じです。
+`git` を起動できない場合は `changelog-git-unavailable` 警告診断、コンテンツディレクトリが Git ワーキングツリーの外にある場合は `changelog-content-outside-repository` 警告診断を出し、どちらの場合もロガー警告を伴い、ビルド成果物には何も加えません。履歴が取得できないことを理由にビルドが失敗することはなく、空のリポジトリでも同じです。
 
 ## スタイル
 
@@ -122,4 +122,5 @@ import "@riebeckite/plugin-changelog/style.css";
 ## 関連資料
 
 - [plugin-diff](../diff/README_ja.md) — リビジョン履歴と行差分
-- [プラグインシステム](../../../docs/ja/reference/plugin-api.md)
+- [プラグインシステム](../../../docs/ja/docs/reference/plugin-api.md)
+

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { ChangelogOptions } from "./src/types.js";
-export { buildNoteChangeHistory, buildSiteChangelog, filterChangelogCommits, formatChangelogDate, resolveLookbackSince, } from "./src/changelog.js";
+export { buildNoteChangeHistory, buildSiteChangelog, filterChangelogCommits, formatChangelogDate, resolveContentFilePath, 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";

package/dist/index.js

@@ -71,11 +71,15 @@ function resolveCommitNotes(commit, byPath, bySlug) {
 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);
+    const path3 = resolveContentFilePath(contentIndex, entry.slug);
+    if (path3) byPath.set(path3, entry.slug);
   }
   return byPath;
 }
+function resolveContentFilePath(contentIndex, slug) {
+  const indexedPath = contentIndex.get(slug.toLowerCase());
+  return indexedPath ? `${normalizePath(indexedPath)}.md` : null;
+}
 function resolveCutoff(lookbackDays) {
   if (lookbackDays === void 0) return null;
   return Date.now() - lookbackDays * 24 * 60 * 60 * 1e3;
@@ -90,23 +94,143 @@ function normalizePath(filePath) {
 }
 
 // src/git/history_reader.ts
+import path2 from "node:path";
+
+// src/git/repo_paths.ts
+import path from "node:path";
+
+// src/git/run_git.ts
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 var execFileAsync = promisify(execFile);
+function isGitCommandFailure(result) {
+  return result.ok === false;
+}
+async function runGit(args, cwd) {
+  try {
+    const { stdout } = await execFileAsync(
+      "git",
+      ["-c", "core.quotePath=false", ...args],
+      {
+        ...cwd === void 0 ? {} : { cwd },
+        maxBuffer: 1024 * 1024 * 10
+      }
+    );
+    return { ok: true, stdout };
+  } catch (error) {
+    return {
+      ok: false,
+      spawnError: isSpawnFailure(readErrorCode(error)),
+      detail: describeGitFailure(error)
+    };
+  }
+}
+function readErrorCode(error) {
+  return typeof error === "object" && error !== null && "code" in error ? error.code : void 0;
+}
+function isSpawnFailure(code) {
+  return typeof code === "string" && !code.startsWith("ERR_");
+}
+function describeGitFailure(error) {
+  if (typeof error !== "object" || error === null) {
+    return error instanceof Error ? error.message : String(error);
+  }
+  const stderr = "stderr" in error ? error.stderr : void 0;
+  if (typeof stderr === "string" && stderr.trim()) return stderr.trim();
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+
+// src/git/repo_paths.ts
+async function resolveRepositoryPaths(contentRoot) {
+  const resolvedContentRoot = path.resolve(contentRoot);
+  const result = await runGit([
+    "-C",
+    resolvedContentRoot,
+    "rev-parse",
+    "--show-toplevel",
+    "--show-prefix"
+  ]);
+  if (isGitCommandFailure(result)) {
+    return result.spawnError ? { kind: "git-unavailable", detail: result.detail } : { kind: "content-outside-repository", detail: result.detail };
+  }
+  const [toplevel, prefix] = parseRevParseOutput(result.stdout);
+  if (!toplevel) {
+    return {
+      kind: "content-outside-repository",
+      detail: "git rev-parse reported no work tree root"
+    };
+  }
+  return {
+    kind: "resolved",
+    paths: {
+      repositoryRoot: toPosixPath(path.normalize(toplevel)),
+      contentRoot: toPosixPath(resolvedContentRoot),
+      contentPrefix: toPosixPath(prefix).replace(/\/+$/, "")
+    }
+  };
+}
+function toRepositoryPath(paths, contentRelativePath) {
+  const normalized = normalizeContentPath(contentRelativePath);
+  if (!paths.contentPrefix) return normalized;
+  if (!normalized) return paths.contentPrefix;
+  return `${paths.contentPrefix}/${normalized}`;
+}
+function toContentPath(paths, repositoryRelativePath) {
+  const normalized = normalizeContentPath(repositoryRelativePath);
+  if (!normalized) return null;
+  if (!paths.contentPrefix) return normalized;
+  if (!normalized.startsWith(`${paths.contentPrefix}/`)) return null;
+  return normalized.slice(paths.contentPrefix.length + 1);
+}
+function normalizeContentPath(value) {
+  return value.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function isResolvedRepository(resolution) {
+  return resolution.kind === "resolved";
+}
+function isRepositoryUnavailable(resolution) {
+  return resolution.kind !== "resolved";
+}
+function parseRevParseOutput(stdout) {
+  const [toplevel = "", prefix = ""] = stdout.split(/\r?\n/);
+  return [toplevel.trim(), prefix.trim()];
+}
+function toPosixPath(value) {
+  return value.replace(/\\/g, "/");
+}
+
+// src/git/history_reader.ts
 var fieldSeparator = "";
 var recordSeparator = "";
 var logFormat = ["%H", "%h", "%cI", "%s", "%an"].join(fieldSeparator);
 var GitChangelogReader = class {
-  #cwd;
+  #contentRoot;
   #fileCache = /* @__PURE__ */ new Map();
   #recentCache;
-  #repositoryAvailable;
+  #repository;
   constructor(options = {}) {
-    this.#cwd = options.cwd ?? process.cwd();
+    this.#contentRoot = path2.resolve(options.cwd ?? process.cwd());
   }
-  /** Commit history for one file, newest first, following renames. */
+  /**
+   * Resolves the Git work tree that owns the content directory, or the reason
+   * it cannot be resolved. Memoized: every Git query reuses the same answer.
+   */
+  resolveRepository() {
+    this.#repository ??= resolveRepositoryPaths(this.#contentRoot);
+    return this.#repository;
+  }
+  /** True when the content directory lives inside a Git work tree. */
+  async isAvailable() {
+    return isResolvedRepository(await this.resolveRepository());
+  }
+  /**
+   * Commit history for one file, newest first, following renames.
+   *
+   * @param filePath Content-relative path, e.g. `notes/hello.md`.
+   */
   getFileHistory(filePath, window = {}) {
-    const normalizedPath = normalizeGitPath(filePath);
+    const normalizedPath = normalizeContentPath(filePath);
     if (window.since)
       return this.#readFileHistory(normalizedPath, window.since);
     const cached = this.#fileCache.get(normalizedPath);
@@ -116,43 +240,46 @@ var GitChangelogReader = class {
     return history;
   }
   /**
-   * Recent commits that touch the working directory, newest first, each with
-   * the paths it changed.
+   * Recent commits that touch the content directory, newest first, each with
+   * the content-relative 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 repository = await this.#resolvePaths();
+    if (!repository) return [];
     const args = ["log", "--follow", `--format=${recordSeparator}${logFormat}`];
     if (since) args.push(`--since=${since}`);
-    args.push("--", filePath);
-    const result = await runGit(this.#cwd, args);
+    args.push("--", toRepositoryPath(repository, filePath));
+    const result = await runGit(args, repository.repositoryRoot);
     if (!result.ok) return [];
     return parseCommitRecords(result.stdout);
   }
   async #readRecentCommits(since) {
-    if (!await this.isAvailable()) return [];
+    const repository = await this.#resolvePaths();
+    if (!repository) return [];
     const args = [
       "log",
       `--format=${recordSeparator}${logFormat}`,
       "--name-only"
     ];
     if (since) args.push(`--since=${since}`);
-    args.push("--", ".");
-    const result = await runGit(this.#cwd, args);
+    args.push("--", repository.contentPrefix || ".");
+    const result = await runGit(args, repository.repositoryRoot);
     if (!result.ok) return [];
-    return parseCommitRecords(result.stdout);
+    return parseCommitRecords(result.stdout).map((commit) => ({
+      ...commit,
+      files: commit.files.map((file) => toContentPath(repository, file)).filter((file) => file !== null)
+    }));
+  }
+  /** `null` when the content directory has no readable work tree. */
+  async #resolvePaths() {
+    const resolution = await this.resolveRepository();
+    if (!isResolvedRepository(resolution)) return null;
+    return resolution.paths;
   }
 };
 function parseCommitRecords(stdout) {
@@ -169,24 +296,9 @@ function parseCommitRecord(chunk) {
     date,
     subject: subject ?? "",
     author: author ?? "",
-    files: rest.map((line) => line.trim()).filter(Boolean).map(normalizeGitPath)
+    files: rest.map((line) => line.trim()).filter(Boolean).map(normalizeContentPath)
   };
 }
-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";
@@ -278,6 +390,7 @@ function changelog(options = {}) {
   const resolved = resolveChangelogOptions(options);
   return definePlugin({
     name: CHANGELOG_PLUGIN_NAME,
+    outputDependencies: [{ type: "unknown" }],
     options,
     validateOptions: validateChangelogOptions,
     onManifestCreated: (context) => applyChangelog(context, resolved),
@@ -287,9 +400,12 @@ function changelog(options = {}) {
 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);
+  const reader = new GitChangelogReader({
+    cwd: resolveContentRoot(context, options)
+  });
+  const resolution = await reader.resolveRepository();
+  if (isRepositoryUnavailable(resolution)) {
+    reportRepositoryUnavailable(context, resolution);
     return;
   }
   const since = resolveLookbackSince(options.lookbackDays);
@@ -341,19 +457,23 @@ async function applySiteChangelog(context, options, reader, since) {
   if (html) appendContentBodySlot(target, CHANGELOG_BODY_SLOT, html);
 }
 function resolveEntryFilePath(entry, contentIndex) {
-  const indexedPath = contentIndex.get(entry.slug.toLowerCase());
-  return indexedPath ?? `${entry.slug}.md`;
+  return resolveContentFilePath(contentIndex, entry.slug) ?? `${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.";
+function resolveContentRoot(context, options) {
+  return options.cwd ?? context.config?.content.directory ?? process.cwd();
+}
+function reportRepositoryUnavailable(context, resolution) {
+  const gitUnavailable = resolution.kind === "git-unavailable";
+  const message = gitUnavailable ? `changelog: Git could not be started; change history was skipped. (${resolution.detail})` : `changelog: the content directory is not inside a Git working tree; change history was skipped. (${resolution.detail})`;
   context.diagnostics.push({
-    code: "changelog-git-unavailable",
+    code: gitUnavailable ? "changelog-git-unavailable" : "changelog-content-outside-repository",
     severity: "warning",
     pluginName: CHANGELOG_PLUGIN_NAME,
-    message
+    message,
+    suggestion: gitUnavailable ? "Install Git and make sure it is available on PATH." : "Move the content directory inside a Git working tree, or set the plugin's cwd option to a path inside one."
   });
   context.logger.warn(message);
 }
@@ -441,5 +561,6 @@ export {
   renderNoteChangeHistory,
   renderSiteChangelog,
   resolveChangelogOptions,
+  resolveContentFilePath,
   resolveLookbackSince
 };

package/dist/src/changelog.d.ts

@@ -25,3 +25,13 @@ export declare function buildSiteChangelog(args: {
     contentIndex: Map<string, string>;
     options: ResolvedChangelogOptions;
 }): SiteChangelog;
+/**
+ * Resolves the content-relative file path of a note from the content index.
+ *
+ * Index values drop the `.md` extension of Markdown notes, so it is restored
+ * here: Git needs the real on-disk path, not the slug-shaped key the index is
+ * built for.
+ *
+ * Returns `null` when the slug is not in the index.
+ */
+export declare function resolveContentFilePath(contentIndex: Map<string, string>, slug: string): string | null;

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

@@ -1,25 +1,39 @@
 import type { ChangelogCommit, GitChangelogReaderOptions } from "../types.js";
+import { type RepositoryPathsResolution } from "./repo_paths.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
+ * Reads local Git history for individual files and for the whole content
  * 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.
+ * the content directory is not a repository.
+ *
+ * Callers speak content-relative paths — the same paths the content index
+ * reports. The reader resolves the owning work tree once and translates every
+ * path itself, so the process working directory never influences a result.
  */
 export declare class GitChangelogReader {
     #private;
     constructor(options?: GitChangelogReaderOptions);
-    /** Commit history for one file, newest first, following renames. */
+    /**
+     * Resolves the Git work tree that owns the content directory, or the reason
+     * it cannot be resolved. Memoized: every Git query reuses the same answer.
+     */
+    resolveRepository(): Promise<RepositoryPathsResolution>;
+    /** True when the content directory lives inside a Git work tree. */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Commit history for one file, newest first, following renames.
+     *
+     * @param filePath Content-relative path, e.g. `notes/hello.md`.
+     */
     getFileHistory(filePath: string, window?: GitLogWindow): Promise<ChangelogCommit[]>;
     /**
-     * Recent commits that touch the working directory, newest first, each with
-     * the paths it changed.
+     * Recent commits that touch the content directory, newest first, each with
+     * the content-relative paths it changed.
      */
     getRecentCommits(window?: GitLogWindow): Promise<ChangelogCommit[]>;
-    /** True when `cwd` is inside a Git working tree. */
-    isAvailable(): Promise<boolean>;
 }

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

@@ -0,0 +1,76 @@
+/**
+ * The paths that locate a content directory inside a Git work tree.
+ *
+ * Every field is a POSIX-separated path (`git` prints and accepts those on every
+ * platform, including Windows).
+ */
+export type GitRepositoryPaths = {
+    /** Work tree root reported by `git rev-parse --show-toplevel`. */
+    repositoryRoot: string;
+    /** Absolute path of the content directory. */
+    contentRoot: string;
+    /**
+     * Content directory relative to `repositoryRoot`, without a trailing slash.
+     * Empty when the content directory is the work tree root itself.
+     */
+    contentPrefix: string;
+};
+/**
+ * Why Git history cannot be read for a content directory.
+ *
+ * The reason is modelled explicitly so a plugin can report an actionable
+ * diagnostic instead of quietly rendering nothing.
+ */
+export type RepositoryPathsResolution = {
+    kind: "resolved";
+    paths: GitRepositoryPaths;
+}
+/** Git is not installed, or could not be started. */
+ | {
+    kind: "git-unavailable";
+    detail: string;
+}
+/** Git ran, but the content directory does not live in a work tree. */
+ | {
+    kind: "content-outside-repository";
+    detail: string;
+};
+/**
+ * Locates the Git work tree that owns `contentRoot`.
+ *
+ * Both the work tree root and the content prefix come from Git itself, so their
+ * casing and symlink resolution always agree with the paths `git log` prints —
+ * the reason content-relative paths can be translated without guessing.
+ *
+ * The work tree is resolved through `git -C <contentRoot>` rather than by
+ * running Git in `contentRoot`, so a missing directory surfaces as a Git
+ * failure instead of an indistinguishable spawn failure.
+ */
+export declare function resolveRepositoryPaths(contentRoot: string): Promise<RepositoryPathsResolution>;
+/**
+ * Translates a content-relative path into the work tree-relative path that
+ * `git log` pathspecs and `git show <rev>:<path>` expect.
+ */
+export declare function toRepositoryPath(paths: GitRepositoryPaths, contentRelativePath: string): string;
+/**
+ * Translates a work tree-relative path printed by `git` back into a
+ * content-relative path, or returns `null` when the path lies outside the
+ * content directory.
+ */
+export declare function toContentPath(paths: GitRepositoryPaths, repositoryRelativePath: string): string | null;
+/** Normalizes a path to the POSIX form used for content and work tree paths. */
+export declare function normalizeContentPath(value: string): string;
+/**
+ * True when the content directory has a usable work tree. Narrows the
+ * resolution so callers can read `paths`.
+ */
+export declare function isResolvedRepository(resolution: RepositoryPathsResolution): resolution is Extract<RepositoryPathsResolution, {
+    kind: "resolved";
+}>;
+/**
+ * True when history cannot be read and a reason is available. Narrows the
+ * resolution so callers can read `detail`.
+ */
+export declare function isRepositoryUnavailable(resolution: RepositoryPathsResolution): resolution is Exclude<RepositoryPathsResolution, {
+    kind: "resolved";
+}>;

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

@@ -0,0 +1,43 @@
+/**
+ * Result of a `git` invocation.
+ *
+ * Failures are returned instead of thrown: a site whose Git history cannot be
+ * read must still build, so every caller decides what an unavailable repository
+ * means for its own output.
+ */
+export type GitCommandResult = {
+    ok: true;
+    stdout: string;
+}
+/**
+ * `spawnError` separates "Git could not be started" (missing or unexecutable
+ * binary) from "Git ran and rejected the command" (not a work tree, unknown
+ * revision, unreadable path). The distinction drives which diagnostic a
+ * plugin reports.
+ */
+ | {
+    ok: false;
+    spawnError: boolean;
+    detail: string;
+};
+/**
+ * Narrows a failed command so its failure fields can be read.
+ *
+ * Type predicates are used instead of `result.ok` checks throughout this
+ * package because the build type-checks without `strictNullChecks`, where
+ * discriminant narrowing of an inline condition does not apply.
+ */
+export declare function isGitCommandFailure(result: GitCommandResult): result is Extract<GitCommandResult, {
+    ok: false;
+}>;
+/**
+ * Runs `git` with `args`.
+ *
+ * `core.quotePath=false` keeps non-ASCII paths verbatim so the printed paths
+ * match the ones the content index reports; Git otherwise escapes them into
+ * octal sequences that no path lookup can resolve.
+ *
+ * @param cwd Directory Git runs in. Omit when the command carries its own
+ *   `-C <dir>` argument.
+ */
+export declare function runGit(args: readonly string[], cwd?: string): Promise<GitCommandResult>;

package/dist/src/types.d.ts

@@ -3,8 +3,10 @@ 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.
+     * Content root: the directory holding the notes, used to locate the owning
+     * Git work tree. Defaults to `config.content.directory` when the plugin runs
+     * inside a build, otherwise `process.cwd()`. A relative value is resolved
+     * against `process.cwd()`.
      */
     cwd?: string;
     /**
@@ -66,7 +68,7 @@ export type ChangelogCommit = {
     date: string;
     subject: string;
     author: string;
-    /** Paths changed by the commit, relative to the Git working directory. */
+    /** Content-relative path of the file changed by the commit. */
     files: string[];
 };
 /** A commit prepared for rendering. */
@@ -103,6 +105,6 @@ export type SiteChangelog = {
 };
 /** Options accepted by `GitChangelogReader`. */
 export type GitChangelogReaderOptions = {
-    /** Working directory for Git commands. Defaults to `process.cwd()`. */
+    /** Content root used to locate the Git work tree. Defaults to `process.cwd()`. */
     cwd?: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riebeckite/plugin-changelog",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,10 +15,11 @@
     "./style.css": "./style.css"
   },
   "dependencies": {
-    "@riebeckite/core": "0.0.14"
+    "@riebeckite/core": "0.0.16"
   },
   "devDependencies": {
-    "@types/node": "^24.5.2"
+    "@types/node": "^24.5.2",
+    "tsx": "^4.22.4"
   },
   "publishConfig": {
     "access": "public"
@@ -53,6 +54,7 @@
     "./style.css"
   ],
   "scripts": {
-    "build": "node ../../../scripts/build_package.mjs"
+    "build": "node ../../../scripts/build_package.mjs",
+    "test": "node --import tsx --test \"test/*.test.ts\""
   }
 }