@repo-toolkit/changelog 0.9.0 → 0.11.0

package/README.md

@@ -11,7 +11,7 @@ pnpm add -D @repo-toolkit/changelog
 ## Config File
 
 Use `--config` when you want repo-specific options such as custom commit `types`,
-scope filtering, ignored commits, or custom issue and commit URLs.
+scope filtering, ignored commits, or custom URL formats.
 
 ```js
 /** @type {import('@repo-toolkit/changelog').ChangelogConfig} */
@@ -38,9 +38,19 @@ repo-toolkit-changelog --config changelog.config.mjs
 
 CLI flags override values from the config file.
 
-Use a JavaScript config file when you need `RegExp` values such as `ignoreCommits`
-or formatter callbacks such as `formatIssueUrl`. JSON config files only work for
-plain data options.
+Use a JavaScript config file when you need `RegExp` values such as `ignoreCommits`.
+JSON config files only work for plain data options.
+
+> **Warning:** A JavaScript config file (`.mjs`, `.js`, `.cjs`) is loaded with
+> `import()`, so it executes as trusted code in the same Node process as the
+> CLI. Only point `--config` at files you control. JSON config files are parsed
+> with `JSON.parse` and do not execute.
+
+Both JSON and JS config files must export an object whose shape matches
+`ChangelogConfig`. Runtime validation rejects unknown top-level keys, unknown
+fields on `types` entries, and unsupported `effect` values (only `'hidden'` is
+recognized) before the generator is built — invalid configs fail fast with an
+actionable error instead of a silent later surprise.
 
 ## CLI
 
@@ -48,21 +58,59 @@ plain data options.
 repo-toolkit-changelog
 ```
 
-Useful flags:
-
-- `--config <path>`
-- `--cwd <path>`
-- `--output <path>`
-- `--tag-prefix <prefix>`
-- `--release-count <number>`
-- `--first-release`
-- `--no-skip-unstable`
-- `--no-output-unreleased`
+All flags:
+
+| Flag                                             | Description                                                                                              | Default                         |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| `--config <path>`                                | Config file (JSON or JS module) with changelog options. JS modules execute trusted code.                 | none                            |
+| `--cwd <path>`                                   | Working directory for reading `package.json` and git metadata.                                           | `process.cwd()`                 |
+| `--output <path>`                                | Output file path (absolute or relative to `--cwd`).                                                      | `CHANGELOG.md`                  |
+| `--tag-prefix <prefix>`                          | Tag prefix to match. Pass `--tag-prefix=` for an empty prefix.                                           | `v`                             |
+| `--release-count <non-negative integer>`         | Number of releases to include. `0` regenerates all releases.                                             | latest release only             |
+| `--append` / `--no-append`                       | Append generated content after the existing file. Without this flag, generated content is prepended.     | `--no-append` (prepend)         |
+| `--first-release` / `--no-first-release`         | Include all commits back to the first tag when no prior release tag exists. Overrides `--release-count`. | `--no-first-release`            |
+| `--skip-unstable` / `--no-skip-unstable`         | Skip prerelease tags (e.g. `v1.0.0-beta.1`).                                                             | `--skip-unstable` (skip)        |
+| `--output-unreleased` / `--no-output-unreleased` | Include the unreleased section.                                                                          | `--output-unreleased` (include) |
+| `-h`, `--help`                                   | Show help and exit.                                                                                      | —                               |
+
+Invalid numeric `--release-count` values exit nonzero with `Invalid numeric value`,
+and unsupported config fields exit nonzero with a precise field-level message.
+
+`--first-release` takes precedence over `--release-count` and regenerates the
+full changelog. Unknown arguments are rejected by default; use `--` to pass
+through trailing args to nested tooling in non-strict mode only.
+
+## Output semantics
+
+`generateChangelog` writes the resulting changelog atomically: it composes the
+generated content into a sibling temporary file and renames it over the
+destination only after the generator stream completes successfully. If the
+generator throws, the existing file is left untouched and the temp file is
+removed.
+
+Existing file behavior:
+
+- **Default (prepend):** generated content is placed above the existing content,
+  separated by a single blank line. Excess trailing newlines on either side are
+  collapsed to keep the separator stable.
+- **`--append`:** generated content is placed below the existing content, also
+  separated by a single blank line.
+- **No existing file:** the generated content is written directly to the
+  destination; no merge is performed.
+- **Empty generated content:** the existing file is left unchanged.
+
+The output always ends with a single trailing newline.
 
 ## JavaScript API
 
 ```ts
-import { generateChangelog } from '@repo-toolkit/changelog';
+import {
+  generateChangelog,
+  createGenerator,
+  createPreset,
+  getDefaultTypes,
+  DEFAULT_TYPES,
+} from '@repo-toolkit/changelog';
 
 await generateChangelog({
   outputFile: 'CHANGELOG.md',
@@ -72,6 +120,36 @@ await generateChangelog({
 });
 ```
 
+### Public exports
+
+| Export                                                      | Kind           | Signature                                                                                                 | Returns                                                              |
+| ----------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `generateChangelog`                                         | async function | `(options?: GenerateChangelogOptions) => Promise<string>`                                                 | Resolves with the absolute path of the written changelog file.       |
+| `createGenerator`                                           | async function | `(options?: GenerateChangelogOptions) => Promise<ConventionalChangelog>`                                  | Resolves with the configured `conventional-changelog` generator.     |
+| `createPreset`                                              | async function | `(options?: CreatePresetOptions) => Promise<ConventionalCommitsPreset & { name: 'conventionalcommits' }>` | Resolves with the preset, tagged with `name: 'conventionalcommits'`. |
+| `getDefaultTypes`                                           | function       | `() => ReadonlyArray<Readonly<ChangelogType>>`                                                            | Returns the frozen `DEFAULT_TYPES` array (same reference each call). |
+| `DEFAULT_TYPES`                                             | constant       | `ReadonlyArray<Readonly<ChangelogType>>`                                                                  | Deeply frozen default `types` array.                                 |
+| `GenerateChangelogOptions`                                  | interface      | extends `CreatePresetOptions`                                                                             | —                                                                    |
+| `CreatePresetOptions`                                       | type alias     | = `ConventionalCommitsPresetOptions`                                                                      | —                                                                    |
+| `ChangelogConfig`                                           | type alias     | = `GenerateChangelogOptions`                                                                              | Config file shape.                                                   |
+| `ChangelogType`                                             | interface      | `{ type, section?, scope?, effect?: 'hidden', hidden? }`                                                  | —                                                                    |
+| `ConventionalCommitsPresetOptions`                          | interface      | —                                                                                                         | Mirrors the pinned conventionalcommits API.                          |
+| `ChangelogContext`, `ChangelogReference`, `ChangelogCommit` | interfaces     | —                                                                                                         | Echoed from the upstream parser/writer contracts.                    |
+
+### Defaults immutability
+
+`DEFAULT_TYPES` is deeply frozen at module load: nested entries cannot be
+mutated, even in strict mode. Use `getDefaultTypes()` if you need a stable
+accessor. Mutating attempts throw instead of silently corrupting later preset
+creation.
+
+### `effect` contract
+
+`effect` is the preferred field for visibility control on a `ChangelogType`.
+Only `'hidden'` is supported — it maps to `hidden: true` for the upstream
+conventionalcommits parser. The `hidden` boolean is still accepted on a type
+entry for compatibility with older upstream versions.
+
 ## Supported Preset Options
 
 - `types`
@@ -80,10 +158,11 @@ await generateChangelog({
 - `scope`
 - `scopeOnly`
 - `preMajor`
-- `formatIssueUrl`
-- `formatCommitUrl`
-- `formatCompareUrl`
-- `formatUserUrl`
+- `issueUrlFormat`
+- `commitUrlFormat`
+- `compareUrlFormat`
+- `userUrlFormat`
+- `bumpStrict`
 
 ## Default Sections
 

package/cli.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { parseFlags, INTERACTIVE_FLAG, resolveCliOptions } from "@repo-toolkit/publish-package";
+import { pathToFileURL } from "url";
+import { parseFlags, resolveCliOptions } from "@repo-toolkit/publish-package";
 
 // src/index.ts
-import { createWriteStream } from "fs";
-import { mkdir } from "fs/promises";
+import { mkdir, readFile, rename, rm, writeFile } from "fs/promises";
 import { dirname, isAbsolute, resolve } from "path";
+import { randomUUID } from "crypto";
+import { isPlainObject } from "@repo-toolkit/publish-package";
 import { ConventionalChangelog } from "conventional-changelog";
 import createConventionalCommitsPreset from "conventional-changelog-conventionalcommits";
 var PIPELINE_OPTION_KEYS = [
@@ -29,65 +31,67 @@ function splitPresetOptions(options) {
   }
   return presetOptions;
 }
-var DEFAULT_TYPES = [
-  {
-    type: "feat",
-    section: "Features"
-  },
-  {
-    type: "fix",
-    scope: "deps",
-    effect: "hidden"
-  },
-  {
-    type: "fix",
-    section: "Bug Fixes"
-  },
-  {
-    type: "revert",
-    section: "Reverts"
-  },
-  {
-    type: "docs",
-    section: "Documentation"
-  },
-  {
-    type: "refactor",
-    section: "Code Refactoring"
-  },
-  {
-    type: "perf",
-    section: "Performance Improvements"
-  },
-  {
-    type: "build",
-    section: "Build System"
-  },
-  {
-    type: "e2e",
-    section: "End-to-end Testing"
-  },
-  {
-    type: "ci",
-    effect: "hidden"
-  },
-  {
-    type: "chore",
-    effect: "hidden"
-  },
-  {
-    type: "style",
-    effect: "hidden"
-  },
-  {
-    type: "test",
-    effect: "hidden"
-  },
-  {
-    type: "release",
-    effect: "hidden"
-  }
-];
+var DEFAULT_TYPES = Object.freeze(
+  [
+    {
+      type: "feat",
+      section: "Features"
+    },
+    {
+      type: "fix",
+      scope: "deps",
+      effect: "hidden"
+    },
+    {
+      type: "fix",
+      section: "Bug Fixes"
+    },
+    {
+      type: "revert",
+      section: "Reverts"
+    },
+    {
+      type: "docs",
+      section: "Documentation"
+    },
+    {
+      type: "refactor",
+      section: "Code Refactoring"
+    },
+    {
+      type: "perf",
+      section: "Performance Improvements"
+    },
+    {
+      type: "build",
+      section: "Build System"
+    },
+    {
+      type: "e2e",
+      section: "End-to-end Testing"
+    },
+    {
+      type: "ci",
+      effect: "hidden"
+    },
+    {
+      type: "chore",
+      effect: "hidden"
+    },
+    {
+      type: "style",
+      effect: "hidden"
+    },
+    {
+      type: "test",
+      effect: "hidden"
+    },
+    {
+      type: "release",
+      effect: "hidden"
+    }
+  ].map((entry) => Object.freeze(entry))
+);
 function normalizeTypes(types) {
   return types.map((entry) => ({
     ...entry,
@@ -100,32 +104,209 @@ function resolvePresetOptions(options = {}) {
     types: normalizeTypes(options.types ?? DEFAULT_TYPES)
   };
 }
+function resolveTagOptions(options) {
+  const tags = {};
+  if (options.tagPrefix !== void 0) {
+    tags.prefix = options.tagPrefix;
+  }
+  if (options.skipUnstable !== void 0) {
+    tags.skipUnstable = options.skipUnstable;
+  }
+  return tags;
+}
+function resolveGeneratorOptions(options) {
+  const resolvedOptions = {
+    append: options.append ?? false,
+    outputUnreleased: options.outputUnreleased ?? true
+  };
+  if (options.firstRelease === true) {
+    resolvedOptions.releaseCount = 0;
+  } else if (options.releaseCount !== void 0) {
+    resolvedOptions.releaseCount = validateReleaseCount(options.releaseCount);
+  }
+  return resolvedOptions;
+}
+function validateGenerateChangelogOptions(options) {
+  if (options.releaseCount !== void 0) {
+    validateReleaseCount(options.releaseCount);
+  }
+  validatePresetOptions(splitPresetOptions(options));
+}
+function validateReleaseCount(value) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`releaseCount must be a non-negative safe integer, got: ${value}`);
+  }
+  return value;
+}
+var PRESET_OPTION_KEYS = [
+  "types",
+  "ignoreCommits",
+  "issuePrefixes",
+  "scope",
+  "scopeOnly",
+  "preMajor",
+  "issueUrlFormat",
+  "commitUrlFormat",
+  "compareUrlFormat",
+  "userUrlFormat",
+  "bumpStrict"
+];
+var STRING_FORMAT_KEYS = ["issueUrlFormat", "commitUrlFormat", "compareUrlFormat", "userUrlFormat"];
+function validatePresetOptions(options) {
+  for (const key of Object.keys(options)) {
+    if (!PRESET_OPTION_KEYS.includes(key)) {
+      throw new Error(`Unknown changelog config option: ${key}`);
+    }
+  }
+  if (options.types !== void 0) {
+    validateTypes(options.types);
+  }
+  if (options.ignoreCommits !== void 0 && !(options.ignoreCommits instanceof RegExp)) {
+    throw new Error("ignoreCommits must be a RegExp");
+  }
+  if (options.issuePrefixes !== void 0) {
+    validateStringArray(options.issuePrefixes, "issuePrefixes");
+  }
+  if (options.scope !== void 0) {
+    if (typeof options.scope !== "string" && !Array.isArray(options.scope)) {
+      throw new Error("scope must be a string or an array of strings");
+    }
+    if (Array.isArray(options.scope)) {
+      validateStringArray(options.scope, "scope");
+    }
+  }
+  if (options.scopeOnly !== void 0 && typeof options.scopeOnly !== "boolean") {
+    throw new Error("scopeOnly must be a boolean");
+  }
+  if (options.preMajor !== void 0 && typeof options.preMajor !== "boolean") {
+    throw new Error("preMajor must be a boolean");
+  }
+  for (const key of STRING_FORMAT_KEYS) {
+    const value = options[key];
+    if (value !== void 0 && typeof value !== "string") {
+      throw new Error(`${key} must be a string`);
+    }
+  }
+  if (options.bumpStrict !== void 0 && typeof options.bumpStrict !== "boolean") {
+    throw new Error("bumpStrict must be a boolean");
+  }
+}
+function validateTypes(types) {
+  if (!Array.isArray(types)) {
+    throw new Error("types must be an array");
+  }
+  types.forEach((entry, index) => {
+    if (!isPlainObject(entry)) {
+      throw new Error(`types[${index}] must be an object`);
+    }
+    if (typeof entry.type !== "string" || entry.type.length === 0) {
+      throw new Error(`types[${index}].type must be a non-empty string`);
+    }
+    if (entry.section !== void 0 && typeof entry.section !== "string") {
+      throw new Error(`types[${index}].section must be a string`);
+    }
+    if (entry.scope !== void 0 && typeof entry.scope !== "string") {
+      throw new Error(`types[${index}].scope must be a string`);
+    }
+    if (entry.effect !== void 0 && entry.effect !== "hidden") {
+      throw new Error(`types[${index}].effect must be 'hidden'`);
+    }
+    if (entry.hidden !== void 0 && typeof entry.hidden !== "boolean") {
+      throw new Error(`types[${index}].hidden must be a boolean`);
+    }
+    const knownKeys = /* @__PURE__ */ new Set(["type", "section", "scope", "effect", "hidden"]);
+    for (const key of Object.keys(entry)) {
+      if (!knownKeys.has(key)) {
+        throw new Error(`types[${index}] has unknown field: ${key}`);
+      }
+    }
+  });
+}
+function validateStringArray(value, label) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an array of strings`);
+  }
+  value.forEach((entry, index) => {
+    if (typeof entry !== "string") {
+      throw new Error(`${label}[${index}] must be a string`);
+    }
+  });
+}
 function resolveOutputPath(cwd, outputFile) {
   return isAbsolute(outputFile) ? outputFile : resolve(cwd, outputFile);
 }
-function pipeGeneratorToFile(generator, outputPath) {
+async function pipeGeneratorToFile(generator, outputPath, append) {
+  const tempPath = `${outputPath}.${randomUUID()}.tmp`;
+  const generated = await readGeneratorOutput(generator.writeStream());
+  const existing = await readExistingOutput(outputPath);
+  const contents = combineChangelogContents(existing, generated, append);
+  try {
+    await writeFile(tempPath, contents, "utf8");
+    await rename(tempPath, outputPath);
+  } catch (error) {
+    await rm(tempPath, { force: true });
+    throw error;
+  }
+  return outputPath;
+}
+function readGeneratorOutput(stream) {
   return new Promise((resolvePromise, reject) => {
-    const generatorStream = generator.writeStream();
-    const fileStream = createWriteStream(outputPath);
+    const chunks = [];
+    const onData = (chunk) => {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    };
     const onError = (error) => {
-      generatorStream.off("error", onError);
-      fileStream.off("error", onError);
-      fileStream.off("finish", onFinish);
+      cleanup();
       reject(error);
     };
-    const onFinish = () => {
-      generatorStream.off("error", onError);
-      fileStream.off("error", onError);
-      fileStream.off("finish", onFinish);
-      resolvePromise(outputPath);
+    const onEnd = () => {
+      cleanup();
+      resolvePromise(Buffer.concat(chunks).toString("utf8"));
     };
-    generatorStream.on("error", onError);
-    fileStream.on("error", onError);
-    fileStream.on("finish", onFinish);
-    generatorStream.pipe(fileStream);
+    const cleanup = () => {
+      stream.off("data", onData);
+      stream.off("error", onError);
+      stream.off("end", onEnd);
+    };
+    stream.on("data", onData);
+    stream.on("error", onError);
+    stream.on("end", onEnd);
   });
 }
+async function readExistingOutput(outputPath) {
+  try {
+    return await readFile(outputPath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return void 0;
+    }
+    throw error;
+  }
+}
+function combineChangelogContents(existing, generated, append) {
+  const next = trimTrailingNewlines(generated);
+  const current = trimTrailingNewlines(existing ?? "");
+  if (current.length === 0) {
+    return `${next}
+`;
+  }
+  if (next.length === 0) {
+    return `${current}
+`;
+  }
+  return append ? `${current}
+
+${next}
+` : `${next}
+
+${current}
+`;
+}
+function trimTrailingNewlines(value) {
+  return value.replace(/\n+$/u, "");
+}
 async function createPreset(options = {}) {
+  validatePresetOptions(options);
   const preset = await createConventionalCommitsPreset(resolvePresetOptions(options));
   return {
     ...preset,
@@ -134,19 +315,16 @@ async function createPreset(options = {}) {
 }
 async function createGenerator(options = {}) {
   const cwd = resolve(options.cwd ?? process.cwd());
+  validateGenerateChangelogOptions(options);
   const presetOptions = splitPresetOptions(options);
   const preset = await createPreset(presetOptions);
   const generator = new ConventionalChangelog(cwd);
-  const generatorOptions = {
-    append: options.append ?? false,
-    releaseCount: options.releaseCount ?? 0,
-    skipUnstable: options.skipUnstable ?? true,
-    outputUnreleased: options.outputUnreleased ?? true,
-    tagPrefix: options.tagPrefix ?? "v",
-    firstRelease: options.firstRelease ?? false
-  };
-  generator.readPackage(resolve(cwd, "package.json")).loadPreset(preset).options(generatorOptions).config({
-    tags: preset.tags,
+  generator.readPackage(resolve(cwd, "package.json")).loadPreset(preset).options(resolveGeneratorOptions(options)).tags(
+    resolveTagOptions({
+      tagPrefix: options.tagPrefix ?? "v",
+      skipUnstable: options.skipUnstable ?? true
+    })
+  ).config({
     commits: preset.commits,
     parser: preset.parser,
     writer: preset.writer
@@ -158,7 +336,7 @@ async function generateChangelog(options = {}) {
   const outputPath = resolveOutputPath(cwd, options.outputFile ?? "CHANGELOG.md");
   await mkdir(dirname(outputPath), { recursive: true });
   const generator = await createGenerator({ ...options, cwd });
-  return await pipeGeneratorToFile(generator, outputPath);
+  return await pipeGeneratorToFile(generator, outputPath, options.append ?? false);
 }
 
 // src/cli.ts
@@ -171,8 +349,7 @@ var SPECS = [
   { name: "append", boolean: true, negatable: true },
   { name: "first-release", boolean: true, negatable: true },
   { name: "skip-unstable", boolean: true, negatable: true },
-  { name: "output-unreleased", boolean: true, negatable: true },
-  INTERACTIVE_FLAG
+  { name: "output-unreleased", boolean: true, negatable: true }
 ];
 function printHelp() {
   console.log(`repo-toolkit-changelog
@@ -181,31 +358,33 @@ Usage:
   repo-toolkit-changelog [options]
 
 Options:
-  --config <path>               Config file with changelog options such as custom types
-  --cwd <path>                  Working directory to read package and git metadata from
-  --output <path>               Output file path (default: CHANGELOG.md)
-  --tag-prefix <prefix>         Tag prefix to match (default: v)
-  --release-count <number>      Number of releases to include (default: 0)
-  --append                      Append to the output instead of prepending
-  --first-release               Include all commits when no prior release tag exists
-  --no-skip-unstable            Include unstable releases
-  --no-output-unreleased        Omit the unreleased section
-  -i, --interactive             Prompt for missing required values interactively
-  -h, --help                    Show this help message
+  --config <path>                       Config file (JSON or JS module) with changelog options
+  --cwd <path>                          Working directory to read package and git metadata from
+  --output <path>                       Output file path (default: CHANGELOG.md)
+  --tag-prefix <prefix>                 Tag prefix to match (default: v; use --tag-prefix= for empty)
+  --release-count <non-negative int>     Number of releases to include (default: latest release only)
+  --append / --no-append                Append to or prepend to the output (default: prepend)
+  --first-release / --no-first-release  Include all commits when no prior release tag exists
+  --skip-unstable / --no-skip-unstable  Skip prerelease tags (default: skip)
+  --output-unreleased / --no-output-unreleased  Include the unreleased section (default: include)
+  -h, --help                            Show this help message
 `);
 }
 function parseNumber(value, flag) {
   const parsed = Number.parseInt(value, 10);
-  if (Number.isNaN(parsed)) {
+  if (Number.isNaN(parsed) || !Number.isSafeInteger(parsed) || parsed < 0) {
     throw new Error(`Invalid numeric value for ${flag}: ${value}`);
   }
   return parsed;
 }
+function resolveGenerateChangelogCliOptions(result) {
+  return buildOptions(result.values);
+}
 function buildOptions(values) {
   const options = {};
   if (values.cwd) options.cwd = values.cwd;
   if (values.output) options.outputFile = values.output;
-  if (values["tag-prefix"]) options.tagPrefix = values["tag-prefix"];
+  if (Object.prototype.hasOwnProperty.call(values, "tag-prefix")) options.tagPrefix = values["tag-prefix"];
   if (values["release-count"] !== void 0)
     options.releaseCount = parseNumber(values["release-count"], "--release-count");
   if (values.append !== void 0) options.append = values.append === "true";
@@ -222,13 +401,21 @@ async function main() {
   }
   const merged = await resolveCliOptions({
     result,
-    buildOptions: (flags) => buildOptions(flags.values)
+    buildOptions: resolveGenerateChangelogCliOptions
   });
   const outputPath = await generateChangelog(merged);
   console.log(`Changelog generated at ${outputPath}.`);
 }
-main().catch((error) => {
-  const message = error instanceof Error ? error.message : String(error);
-  console.error(message);
-  process.exitCode = 1;
-});
+var executedAsEntryPoint = process.argv[1] ? import.meta.url === pathToFileURL(process.argv[1]).href : false;
+if (executedAsEntryPoint) {
+  main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exitCode = 1;
+  });
+}
+export {
+  SPECS,
+  printHelp,
+  resolveGenerateChangelogCliOptions
+};

package/index.d.ts

@@ -4,7 +4,7 @@ interface ChangelogType {
     type: string;
     section?: string;
     scope?: string;
-    effect?: 'bump' | 'changelog' | 'hidden';
+    effect?: 'hidden';
     hidden?: boolean;
 }
 interface ChangelogContext {
@@ -29,10 +29,11 @@ interface ConventionalCommitsPresetOptions {
     scope?: string | ReadonlyArray<string>;
     scopeOnly?: boolean;
     preMajor?: boolean;
-    formatIssueUrl?: (context: ChangelogContext, reference: ChangelogReference) => string;
-    formatCommitUrl?: (context: ChangelogContext, commit: ChangelogCommit) => string;
-    formatCompareUrl?: (context: ChangelogContext) => string;
-    formatUserUrl?: (context: ChangelogContext, user: string) => string;
+    issueUrlFormat?: string;
+    commitUrlFormat?: string;
+    compareUrlFormat?: string;
+    userUrlFormat?: string;
+    bumpStrict?: boolean;
 }
 type CreatePresetOptions = ConventionalCommitsPresetOptions;
 interface GenerateChangelogOptions extends CreatePresetOptions {
@@ -46,9 +47,19 @@ interface GenerateChangelogOptions extends CreatePresetOptions {
     firstRelease?: boolean;
 }
 type ChangelogConfig = GenerateChangelogOptions;
-declare const DEFAULT_TYPES: ReadonlyArray<ChangelogType>;
-declare function createPreset(options?: CreatePresetOptions): Promise<any>;
+declare const DEFAULT_TYPES: ReadonlyArray<Readonly<ChangelogType>>;
+declare function getDefaultTypes(): ReadonlyArray<Readonly<ChangelogType>>;
+declare function createPreset(options?: CreatePresetOptions): Promise<{
+    name: string;
+    commits?: GetCommitsParams;
+    parser?: ParserStreamOptions;
+    writer?: WriterOptions;
+    whatBump?: (commits: Commit[]) => {
+        level: number;
+        reason: string;
+    } | null;
+}>;
 declare function createGenerator(options?: GenerateChangelogOptions): Promise<ConventionalChangelog>;
 declare function generateChangelog(options?: GenerateChangelogOptions): Promise<string>;
 
-export { type ChangelogCommit, type ChangelogConfig, type ChangelogContext, type ChangelogReference, type ChangelogType, type ConventionalCommitsPresetOptions, type CreatePresetOptions, DEFAULT_TYPES, type GenerateChangelogOptions, createGenerator, createPreset, generateChangelog };
+export { type ChangelogCommit, type ChangelogConfig, type ChangelogContext, type ChangelogReference, type ChangelogType, type ConventionalCommitsPresetOptions, type CreatePresetOptions, DEFAULT_TYPES, type GenerateChangelogOptions, createGenerator, createPreset, generateChangelog, getDefaultTypes };

package/index.js

@@ -1,7 +1,8 @@
 // src/index.ts
-import { createWriteStream } from "fs";
-import { mkdir } from "fs/promises";
+import { mkdir, readFile, rename, rm, writeFile } from "fs/promises";
 import { dirname, isAbsolute, resolve } from "path";
+import { randomUUID } from "crypto";
+import { isPlainObject } from "@repo-toolkit/publish-package";
 import { ConventionalChangelog } from "conventional-changelog";
 import createConventionalCommitsPreset from "conventional-changelog-conventionalcommits";
 var PIPELINE_OPTION_KEYS = [
@@ -24,65 +25,70 @@ function splitPresetOptions(options) {
   }
   return presetOptions;
 }
-var DEFAULT_TYPES = [
-  {
-    type: "feat",
-    section: "Features"
-  },
-  {
-    type: "fix",
-    scope: "deps",
-    effect: "hidden"
-  },
-  {
-    type: "fix",
-    section: "Bug Fixes"
-  },
-  {
-    type: "revert",
-    section: "Reverts"
-  },
-  {
-    type: "docs",
-    section: "Documentation"
-  },
-  {
-    type: "refactor",
-    section: "Code Refactoring"
-  },
-  {
-    type: "perf",
-    section: "Performance Improvements"
-  },
-  {
-    type: "build",
-    section: "Build System"
-  },
-  {
-    type: "e2e",
-    section: "End-to-end Testing"
-  },
-  {
-    type: "ci",
-    effect: "hidden"
-  },
-  {
-    type: "chore",
-    effect: "hidden"
-  },
-  {
-    type: "style",
-    effect: "hidden"
-  },
-  {
-    type: "test",
-    effect: "hidden"
-  },
-  {
-    type: "release",
-    effect: "hidden"
-  }
-];
+var DEFAULT_TYPES = Object.freeze(
+  [
+    {
+      type: "feat",
+      section: "Features"
+    },
+    {
+      type: "fix",
+      scope: "deps",
+      effect: "hidden"
+    },
+    {
+      type: "fix",
+      section: "Bug Fixes"
+    },
+    {
+      type: "revert",
+      section: "Reverts"
+    },
+    {
+      type: "docs",
+      section: "Documentation"
+    },
+    {
+      type: "refactor",
+      section: "Code Refactoring"
+    },
+    {
+      type: "perf",
+      section: "Performance Improvements"
+    },
+    {
+      type: "build",
+      section: "Build System"
+    },
+    {
+      type: "e2e",
+      section: "End-to-end Testing"
+    },
+    {
+      type: "ci",
+      effect: "hidden"
+    },
+    {
+      type: "chore",
+      effect: "hidden"
+    },
+    {
+      type: "style",
+      effect: "hidden"
+    },
+    {
+      type: "test",
+      effect: "hidden"
+    },
+    {
+      type: "release",
+      effect: "hidden"
+    }
+  ].map((entry) => Object.freeze(entry))
+);
+function getDefaultTypes() {
+  return DEFAULT_TYPES;
+}
 function normalizeTypes(types) {
   return types.map((entry) => ({
     ...entry,
@@ -95,32 +101,209 @@ function resolvePresetOptions(options = {}) {
     types: normalizeTypes(options.types ?? DEFAULT_TYPES)
   };
 }
+function resolveTagOptions(options) {
+  const tags = {};
+  if (options.tagPrefix !== void 0) {
+    tags.prefix = options.tagPrefix;
+  }
+  if (options.skipUnstable !== void 0) {
+    tags.skipUnstable = options.skipUnstable;
+  }
+  return tags;
+}
+function resolveGeneratorOptions(options) {
+  const resolvedOptions = {
+    append: options.append ?? false,
+    outputUnreleased: options.outputUnreleased ?? true
+  };
+  if (options.firstRelease === true) {
+    resolvedOptions.releaseCount = 0;
+  } else if (options.releaseCount !== void 0) {
+    resolvedOptions.releaseCount = validateReleaseCount(options.releaseCount);
+  }
+  return resolvedOptions;
+}
+function validateGenerateChangelogOptions(options) {
+  if (options.releaseCount !== void 0) {
+    validateReleaseCount(options.releaseCount);
+  }
+  validatePresetOptions(splitPresetOptions(options));
+}
+function validateReleaseCount(value) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`releaseCount must be a non-negative safe integer, got: ${value}`);
+  }
+  return value;
+}
+var PRESET_OPTION_KEYS = [
+  "types",
+  "ignoreCommits",
+  "issuePrefixes",
+  "scope",
+  "scopeOnly",
+  "preMajor",
+  "issueUrlFormat",
+  "commitUrlFormat",
+  "compareUrlFormat",
+  "userUrlFormat",
+  "bumpStrict"
+];
+var STRING_FORMAT_KEYS = ["issueUrlFormat", "commitUrlFormat", "compareUrlFormat", "userUrlFormat"];
+function validatePresetOptions(options) {
+  for (const key of Object.keys(options)) {
+    if (!PRESET_OPTION_KEYS.includes(key)) {
+      throw new Error(`Unknown changelog config option: ${key}`);
+    }
+  }
+  if (options.types !== void 0) {
+    validateTypes(options.types);
+  }
+  if (options.ignoreCommits !== void 0 && !(options.ignoreCommits instanceof RegExp)) {
+    throw new Error("ignoreCommits must be a RegExp");
+  }
+  if (options.issuePrefixes !== void 0) {
+    validateStringArray(options.issuePrefixes, "issuePrefixes");
+  }
+  if (options.scope !== void 0) {
+    if (typeof options.scope !== "string" && !Array.isArray(options.scope)) {
+      throw new Error("scope must be a string or an array of strings");
+    }
+    if (Array.isArray(options.scope)) {
+      validateStringArray(options.scope, "scope");
+    }
+  }
+  if (options.scopeOnly !== void 0 && typeof options.scopeOnly !== "boolean") {
+    throw new Error("scopeOnly must be a boolean");
+  }
+  if (options.preMajor !== void 0 && typeof options.preMajor !== "boolean") {
+    throw new Error("preMajor must be a boolean");
+  }
+  for (const key of STRING_FORMAT_KEYS) {
+    const value = options[key];
+    if (value !== void 0 && typeof value !== "string") {
+      throw new Error(`${key} must be a string`);
+    }
+  }
+  if (options.bumpStrict !== void 0 && typeof options.bumpStrict !== "boolean") {
+    throw new Error("bumpStrict must be a boolean");
+  }
+}
+function validateTypes(types) {
+  if (!Array.isArray(types)) {
+    throw new Error("types must be an array");
+  }
+  types.forEach((entry, index) => {
+    if (!isPlainObject(entry)) {
+      throw new Error(`types[${index}] must be an object`);
+    }
+    if (typeof entry.type !== "string" || entry.type.length === 0) {
+      throw new Error(`types[${index}].type must be a non-empty string`);
+    }
+    if (entry.section !== void 0 && typeof entry.section !== "string") {
+      throw new Error(`types[${index}].section must be a string`);
+    }
+    if (entry.scope !== void 0 && typeof entry.scope !== "string") {
+      throw new Error(`types[${index}].scope must be a string`);
+    }
+    if (entry.effect !== void 0 && entry.effect !== "hidden") {
+      throw new Error(`types[${index}].effect must be 'hidden'`);
+    }
+    if (entry.hidden !== void 0 && typeof entry.hidden !== "boolean") {
+      throw new Error(`types[${index}].hidden must be a boolean`);
+    }
+    const knownKeys = /* @__PURE__ */ new Set(["type", "section", "scope", "effect", "hidden"]);
+    for (const key of Object.keys(entry)) {
+      if (!knownKeys.has(key)) {
+        throw new Error(`types[${index}] has unknown field: ${key}`);
+      }
+    }
+  });
+}
+function validateStringArray(value, label) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an array of strings`);
+  }
+  value.forEach((entry, index) => {
+    if (typeof entry !== "string") {
+      throw new Error(`${label}[${index}] must be a string`);
+    }
+  });
+}
 function resolveOutputPath(cwd, outputFile) {
   return isAbsolute(outputFile) ? outputFile : resolve(cwd, outputFile);
 }
-function pipeGeneratorToFile(generator, outputPath) {
+async function pipeGeneratorToFile(generator, outputPath, append) {
+  const tempPath = `${outputPath}.${randomUUID()}.tmp`;
+  const generated = await readGeneratorOutput(generator.writeStream());
+  const existing = await readExistingOutput(outputPath);
+  const contents = combineChangelogContents(existing, generated, append);
+  try {
+    await writeFile(tempPath, contents, "utf8");
+    await rename(tempPath, outputPath);
+  } catch (error) {
+    await rm(tempPath, { force: true });
+    throw error;
+  }
+  return outputPath;
+}
+function readGeneratorOutput(stream) {
   return new Promise((resolvePromise, reject) => {
-    const generatorStream = generator.writeStream();
-    const fileStream = createWriteStream(outputPath);
+    const chunks = [];
+    const onData = (chunk) => {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    };
     const onError = (error) => {
-      generatorStream.off("error", onError);
-      fileStream.off("error", onError);
-      fileStream.off("finish", onFinish);
+      cleanup();
       reject(error);
     };
-    const onFinish = () => {
-      generatorStream.off("error", onError);
-      fileStream.off("error", onError);
-      fileStream.off("finish", onFinish);
-      resolvePromise(outputPath);
+    const onEnd = () => {
+      cleanup();
+      resolvePromise(Buffer.concat(chunks).toString("utf8"));
     };
-    generatorStream.on("error", onError);
-    fileStream.on("error", onError);
-    fileStream.on("finish", onFinish);
-    generatorStream.pipe(fileStream);
+    const cleanup = () => {
+      stream.off("data", onData);
+      stream.off("error", onError);
+      stream.off("end", onEnd);
+    };
+    stream.on("data", onData);
+    stream.on("error", onError);
+    stream.on("end", onEnd);
   });
 }
+async function readExistingOutput(outputPath) {
+  try {
+    return await readFile(outputPath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return void 0;
+    }
+    throw error;
+  }
+}
+function combineChangelogContents(existing, generated, append) {
+  const next = trimTrailingNewlines(generated);
+  const current = trimTrailingNewlines(existing ?? "");
+  if (current.length === 0) {
+    return `${next}
+`;
+  }
+  if (next.length === 0) {
+    return `${current}
+`;
+  }
+  return append ? `${current}
+
+${next}
+` : `${next}
+
+${current}
+`;
+}
+function trimTrailingNewlines(value) {
+  return value.replace(/\n+$/u, "");
+}
 async function createPreset(options = {}) {
+  validatePresetOptions(options);
   const preset = await createConventionalCommitsPreset(resolvePresetOptions(options));
   return {
     ...preset,
@@ -129,19 +312,16 @@ async function createPreset(options = {}) {
 }
 async function createGenerator(options = {}) {
   const cwd = resolve(options.cwd ?? process.cwd());
+  validateGenerateChangelogOptions(options);
   const presetOptions = splitPresetOptions(options);
   const preset = await createPreset(presetOptions);
   const generator = new ConventionalChangelog(cwd);
-  const generatorOptions = {
-    append: options.append ?? false,
-    releaseCount: options.releaseCount ?? 0,
-    skipUnstable: options.skipUnstable ?? true,
-    outputUnreleased: options.outputUnreleased ?? true,
-    tagPrefix: options.tagPrefix ?? "v",
-    firstRelease: options.firstRelease ?? false
-  };
-  generator.readPackage(resolve(cwd, "package.json")).loadPreset(preset).options(generatorOptions).config({
-    tags: preset.tags,
+  generator.readPackage(resolve(cwd, "package.json")).loadPreset(preset).options(resolveGeneratorOptions(options)).tags(
+    resolveTagOptions({
+      tagPrefix: options.tagPrefix ?? "v",
+      skipUnstable: options.skipUnstable ?? true
+    })
+  ).config({
     commits: preset.commits,
     parser: preset.parser,
     writer: preset.writer
@@ -153,11 +333,12 @@ async function generateChangelog(options = {}) {
   const outputPath = resolveOutputPath(cwd, options.outputFile ?? "CHANGELOG.md");
   await mkdir(dirname(outputPath), { recursive: true });
   const generator = await createGenerator({ ...options, cwd });
-  return await pipeGeneratorToFile(generator, outputPath);
+  return await pipeGeneratorToFile(generator, outputPath, options.append ?? false);
 }
 export {
   DEFAULT_TYPES,
   createGenerator,
   createPreset,
-  generateChangelog
+  generateChangelog,
+  getDefaultTypes
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@repo-toolkit/changelog",
   "description": "Shared conventional changelog preset, generator, and CLI for repository releases",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "type": "module",
   "sideEffects": false,
   "keywords": [
@@ -27,7 +27,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@repo-toolkit/publish-package": "0.9.0",
+    "@repo-toolkit/publish-package": "0.11.0",
     "conventional-changelog": "^7.2.1",
     "conventional-changelog-conventionalcommits": "^9.3.1"
   },