@kors/generate-changelog 0.2.4 → 1.0.4

package/README.md

@@ -1,5 +1,95 @@
-## Generate changelog from git commit history
+<p align="center">
+<h1 align="center">generate-changelog</h1>
+</p>
+
+#### Supported Platforms
+<img src="https://stefkors.com/api/platform/index.svg?os=terminal,web" />
+
+Generate structured changelog JSON from git commit history. Works with local repos and remote GitHub repositories.
+
+## Install
+
+```bash
+npm install @kors/generate-changelog
+```
+
+## Usage
+
+### CLI
 
 ```bash
-npx @kors/generate-changelog
-```
+# Generate from local repo and write to changelog.json
+npx @kors/generate-changelog --write
+
+# Generate from a remote GitHub repo
+npx @kors/generate-changelog --owner="StefKors" --repo="generate-changelog"
+
+# Remote repo with a GitHub token (private repos, or to avoid unauthenticated rate limits)
+GITHUB_TOKEN=ghp_xxx npx @kors/generate-changelog --owner="StefKors" --repo="my-private-repo"
+# or pass the token explicitly
+npx @kors/generate-changelog --owner="StefKors" --repo="my-private-repo" --token="ghp_xxx"
+```
+
+### Programmatic
+
+```typescript
+import { generateChangelog } from "@kors/generate-changelog"
+
+const changelog = await generateChangelog({ write: true })
+// or from a remote repo (optional githubToken for private repos / rate limits)
+const remote = await generateChangelog({
+  owner: "StefKors",
+  repo: "generate-changelog",
+  githubToken: process.env["GITHUB_TOKEN"],
+})
+```
+
+## CLI Options
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--write` | `-w` | Write output to `changelog.json` |
+| `--owner` | `-o` | GitHub repo owner (use with `--repo`) |
+| `--repo` | `-r` | GitHub repo name (use with `--owner`) |
+| `--token` | `-t` | GitHub token (optional; also reads `GITHUB_TOKEN` or `GH_TOKEN` if unset) |
+| `--version` | | Print current version |
+| `--help` | | Print help message |
+
+## Output Format
+
+```json
+{
+  "releases": {
+    "1.2.0": [
+      { "type": "Added", "message": "New feature description" },
+      { "type": "Fixed", "message": "Bug fix description" }
+    ],
+    "1.1.0": [
+      { "type": "Improved", "message": "Performance improvement" }
+    ]
+  }
+}
+```
+
+Change types are auto-detected from commit messages: **Added**, **Fixed**, **Improved**, **Removed**.
+
+## GitHub authentication
+
+When using `--owner` and `--repo`, the GitHub REST API is called without a token by default. That works for public repositories but is subject to [lower rate limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api). For **private** repositories, or to use authenticated rate limits, provide a token in either of these ways:
+
+- **Environment variable:** set `GITHUB_TOKEN` (or `GH_TOKEN`) before running the CLI. The CLI reads `GITHUB_TOKEN` automatically.
+- **CLI flag:** `--token` / `-t` overrides the environment when both are set.
+
+Create a token under GitHub → Settings → Developer settings → Personal access tokens. The token needs read access to repository contents (for private repos, use a classic token with `repo` scope, or a fine-grained token with Contents read access).
+
+## Features
+
+- Parses git tags to group commits by version
+- Auto-classifies changes by type from commit messages
+- Filters out merge commits and version bumps
+- Supports local git repos and remote GitHub repos via Octokit
+- Outputs structured JSON for use in release notes, changelogs, or UIs
+
+## License
+
+MIT

package/distribution/cli.js

@@ -9,6 +9,7 @@ const cli = meow(`
 	  --write, -w 	Write output to changelog.json
 	  --owner, -o 	Fetch commits from github owner (used with --repo)
 	  --repo, -r 		Fetch commit from github repo (used with --owner)
+	  --token, -t 	GitHub token (or set GITHUB_TOKEN in the environment)
 	  --version 		Print current version
 	  --help 				Print help message
 
@@ -17,7 +18,10 @@ const cli = meow(`
         $ generate-changelog --write 
 
         Generate from remote repo:
-        $ generate-changelog --owner="StefKors" --repo="generate-changelog" 
+        $ generate-changelog --owner="StefKors" --repo="generate-changelog"
+
+        With authentication (private repos or higher API rate limits):
+        $ generate-changelog --owner="StefKors" --repo="generate-changelog" --token="$GITHUB_TOKEN"
 `, {
     importMeta: import.meta,
     flags: {
@@ -32,7 +36,16 @@ const cli = meow(`
         repo: {
             type: 'string',
             shortFlag: 'r'
+        },
+        token: {
+            type: 'string',
+            shortFlag: 't'
         }
     }
 });
-generateChangelog(cli.flags);
+generateChangelog({
+    write: cli.flags.write,
+    owner: cli.flags.owner,
+    repo: cli.flags.repo,
+    githubToken: cli.flags.token ?? process.env['GITHUB_TOKEN'] ?? process.env['GH_TOKEN'],
+});

package/distribution/lib/fetchGitHubCommits.d.ts

@@ -1 +1 @@
-export declare const fetchGitHubCommits: (owner: string, repo: string) => Promise<string[]>;
+export declare const fetchGitHubCommits: (owner: string, repo: string, token?: string) => Promise<string[]>;

package/distribution/lib/fetchGitHubCommits.js

@@ -1,6 +1,6 @@
 import { Octokit } from 'octokit';
-export const fetchGitHubCommits = async (owner, repo) => {
-    const octokit = new Octokit({});
+export const fetchGitHubCommits = async (owner, repo, token) => {
+    const octokit = new Octokit(token ? { auth: token } : {});
     const data = await octokit.paginate('GET /repos/{owner}/{repo}/commits', {
         owner: owner,
         repo: repo,

package/distribution/lib/index.d.ts

@@ -13,6 +13,8 @@ export interface Options {
     write?: boolean;
     repo?: string;
     owner?: string;
+    /** GitHub personal access token or fine-grained token (higher rate limits; required for private repos). */
+    githubToken?: string;
 }
-declare const generateChangelog: ({ write, owner, repo }: Options) => Promise<Changelog>;
+declare const generateChangelog: ({ write, owner, repo, githubToken }: Options) => Promise<Changelog>;
 export { generateChangelog };

package/distribution/lib/index.js

@@ -1,12 +1,12 @@
 import * as fs from 'node:fs';
 import { getLocalCommits } from './getLocalCommits.js';
 import { fetchGitHubCommits } from './fetchGitHubCommits.js';
-const generateChangelog = async ({ write, owner, repo }) => {
+const generateChangelog = async ({ write, owner, repo, githubToken }) => {
     try {
         let lines = [];
         if (repo && owner) {
             console.log("fetching from remote", owner, repo);
-            lines = await fetchGitHubCommits(owner, repo);
+            lines = await fetchGitHubCommits(owner, repo, githubToken);
         }
         else {
             console.log("reading local commits");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kors/generate-changelog",
   "description": "Generate a changelog json from a git commit history",
-  "version": "0.2.4",
+  "version": "1.0.4",
   "type": "module",
   "bin": {
     "generate-changelog": "./distribution/cli.js"