@chamoji/cli 0.0.0-stage → 0.2.0

package/LICENSE

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

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import { run } from './run.js';
+process.exitCode = await run(process.argv.slice(2), {
+    cwd: process.cwd(),
+    stdout: text => process.stdout.write(text),
+    stderr: text => process.stderr.write(text),
+});
+//# sourceMappingURL=cli.js.map

package/dist/jev-classifier.d.ts

@@ -0,0 +1,38 @@
+import { type CommitClassifier } from '@chamoji/core';
+/** The slice of the TypeSafe client this classifier uses (easy to fake in tests). */
+export type JevClient = {
+    systemOne(request: {
+        state: {
+            commits: Array<{
+                subject: string;
+                body: string;
+            }>;
+        };
+        questions: Record<string, {
+            type: 'choice';
+            instructions: string;
+            criteria: Record<string, string>;
+        }>;
+    }): Promise<{
+        answers: Record<string, {
+            choice: string;
+            confidence: number;
+        }>;
+    }>;
+};
+export type JevClassifierOptions = {
+    /** Commits per request; each question carries all the gitmoji options. */
+    batchSize?: number;
+    /** Requests in flight at once. */
+    concurrency?: number;
+    /** Picks below this confidence are dropped and the commit stays unsorted. */
+    minConfidence?: number;
+    /** Receives one-line progress notes: failures and a final summary. */
+    report?: (line: string) => void;
+};
+/**
+ * Sorts commits with Jev (TypeSafe System One): one `choice` question per
+ * commit over the gitmoji list. Only subjects and the start of each body are
+ * sent, never diffs or code.
+ */
+export declare function createJevClassifier(client: JevClient, options?: JevClassifierOptions): CommitClassifier;

package/dist/jev-classifier.js

@@ -0,0 +1,118 @@
+import { GITMOJIS, } from '@chamoji/core';
+/** Characters of each subject and body sent. */
+const MAX_CHARS = 300;
+/**
+ * Upper bound on batch size. Each question repeats the ~75 gitmoji options
+ * (about 1.4k tokens), and a request may hold 64k tokens, state included.
+ */
+const MAX_BATCH = 30;
+const NONE = 'none';
+/**
+ * Not offered: 💥, because only an author can declare a breaking change, and
+ * the codes the default config hides, so a wrong pick can't make a commit
+ * vanish from the changelog.
+ */
+const NOT_OFFERED = new Set(['boom', 'bookmark', 'twisted_rightwards_arrows']);
+const CRITERIA = Object.fromEntries([
+    ...GITMOJIS.filter(gitmoji => !NOT_OFFERED.has(gitmoji.code)).map(gitmoji => [
+        gitmoji.code,
+        gitmoji.description,
+    ]),
+    [
+        NONE,
+        'None of these fit, or the message is too vague to tell what changed.',
+    ],
+]);
+/**
+ * Sorts commits with Jev (TypeSafe System One): one `choice` question per
+ * commit over the gitmoji list. Only subjects and the start of each body are
+ * sent, never diffs or code.
+ */
+export function createJevClassifier(client, options = {}) {
+    const { batchSize = 25, concurrency = 4, 
+    // A starting point; tune it against labelled history.
+    minConfidence = 0.6, report, } = options;
+    if (!Number.isInteger(batchSize) || batchSize < 1 || batchSize > MAX_BATCH) {
+        throw new RangeError(`batchSize must be an integer from 1 to ${MAX_BATCH}`);
+    }
+    if (!Number.isInteger(concurrency) || concurrency < 1) {
+        throw new RangeError('concurrency must be a positive integer');
+    }
+    const classifyBatch = async (batch) => {
+        const questions = {};
+        for (const index of batch.keys()) {
+            questions[`commit_${index}`] = {
+                type: 'choice',
+                instructions: `Which gitmoji best describes the change made by commit \`commits[${index}]\`, judging from its subject and body? Pick the one a maintainer would use when sorting it into a changelog, or ${NONE} if the message is too vague to tell.`,
+                criteria: CRITERIA,
+            };
+        }
+        const { answers } = await client.systemOne({
+            state: {
+                commits: batch.map(commit => ({
+                    subject: redact(commit.subject).slice(0, MAX_CHARS),
+                    body: redact(withoutTrailers(commit.body)).trim().slice(0, MAX_CHARS),
+                })),
+            },
+            questions,
+        });
+        const picks = [];
+        for (const [index, commit] of batch.entries()) {
+            const answer = answers[`commit_${index}`];
+            if (answer &&
+                answer.choice !== NONE &&
+                answer.confidence >= minConfidence) {
+                picks.push([commit.hash, answer.choice]);
+            }
+        }
+        return picks;
+    };
+    return async (commits) => {
+        const batches = [];
+        for (let start = 0; start < commits.length; start += batchSize) {
+            batches.push(commits.slice(start, start + batchSize));
+        }
+        const result = new Map();
+        let next = 0;
+        let sent = 0;
+        let failure;
+        // `--ai` only improves the output, so a failed request stops further
+        // requests but keeps what earlier ones returned.
+        const worker = async () => {
+            while (next < batches.length && !failure) {
+                const batch = batches[next++];
+                try {
+                    for (const [hash, code] of await classifyBatch(batch)) {
+                        result.set(hash, code);
+                    }
+                    sent += batch.length;
+                }
+                catch (error) {
+                    failure ??= error;
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(concurrency, batches.length) }, worker));
+        if (failure) {
+            report?.(`Jev request failed (${failure.message}); ${commits.length - sent} commits left unsorted`);
+        }
+        report?.(`Jev sorted ${result.size} of ${commits.length} commits no rule could place`);
+        return result;
+    };
+}
+const EMAIL = /[\w.+-]+@[\w-]+(?:\.[\w-]+)+/g;
+const TRAILER_LINE = /^[\w-]+:\s/;
+/** Replaces email addresses, which often appear in commit text. */
+function redact(text) {
+    return text.replaceAll(EMAIL, '<email>');
+}
+/** Drops the final paragraph when it is all `Key: value` trailer lines. */
+function withoutTrailers(body) {
+    const paragraphs = body.trim().split(/\n\s*\n/);
+    const last = paragraphs.at(-1)?.split('\n') ?? [];
+    if (last.length > 0 && last.every(line => TRAILER_LINE.test(line.trim()))) {
+        paragraphs.pop();
+    }
+    return paragraphs.join('\n\n');
+}
+//# sourceMappingURL=jev-classifier.js.map

package/dist/run.d.ts

@@ -0,0 +1,9 @@
+export type Io = {
+    cwd: string;
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    /** `YYYY-MM-DD` used for `--release`; defaults to today. */
+    today?: string;
+};
+export declare const NO_RELEASE_NEEDED = 3;
+export declare function run(argv: string[], io: Io): Promise<number>;

package/dist/run.js

@@ -0,0 +1,138 @@
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { buildChangelog, loadConfig, render, } from '@chamoji/core';
+import { TypeSafeClient } from '@typesafe-ai/sdk';
+import meow from 'meow';
+import { createJevClassifier } from './jev-classifier.js';
+const HELP = `
+	Usage
+	  $ chamoji changelog [options]    Generate a changelog from git history
+	  $ chamoji next-version [options] Print the next semver version
+	                                   (exits 3 when no release is needed)
+
+	Options
+	  --format   markdown (default), md, json or html
+	  --output   Write to this file instead of stdout
+	  --from     Leave out this release tag and everything older
+	  --to       Ref to treat as the head of history (default: HEAD)
+	  --release  Name the unreleased section with this version
+	  --config   Config file (default: chamoji.config.json if present)
+	  --ai       Sort commits no rule can place with Jev (TypeSafe).
+	             Needs TYPESAFE_API_KEY. Sends up to 300 characters of
+	             each such commit's subject and body, with emails and
+	             trailer lines removed; never diffs, code or authors.
+
+	Examples
+	  $ chamoji changelog --output CHANGELOG.md
+	  $ version=$(chamoji next-version) && chamoji changelog --release "$version" -o CHANGELOG.md
+	  $ chamoji changelog --format html --output changelog.html
+`;
+export const NO_RELEASE_NEEDED = 3;
+const FORMATS = {
+    markdown: 'markdown',
+    md: 'markdown',
+    json: 'json',
+    html: 'html',
+};
+export async function run(argv, io) {
+    const cli = meow(HELP, {
+        importMeta: import.meta,
+        argv,
+        autoHelp: false,
+        autoVersion: false,
+        flags: {
+            format: { type: 'string', default: 'markdown' },
+            output: { type: 'string', shortFlag: 'o' },
+            from: { type: 'string' },
+            to: { type: 'string', default: 'HEAD' },
+            release: { type: 'string' },
+            config: { type: 'string' },
+            ai: { type: 'boolean' },
+            help: { type: 'boolean', shortFlag: 'h' },
+            version: { type: 'boolean', shortFlag: 'v' },
+        },
+    });
+    const { flags } = cli;
+    if (flags.help) {
+        io.stdout(`${cli.help}\n`);
+        return 0;
+    }
+    if (flags.version) {
+        io.stdout(`${cli.pkg.version ?? 'unknown'}\n`);
+        return 0;
+    }
+    const [command] = cli.input;
+    try {
+        const classify = flags.ai ? jevClassifier(io) : undefined;
+        switch (command) {
+            case 'changelog': {
+                const format = Object.hasOwn(FORMATS, flags.format)
+                    ? FORMATS[flags.format]
+                    : undefined;
+                if (!format) {
+                    throw new Error(`Unknown format "${flags.format}" (use markdown, json or html)`);
+                }
+                const changelog = await buildChangelog({
+                    cwd: io.cwd,
+                    config: await loadConfig(io.cwd, flags.config),
+                    to: flags.to,
+                    from: flags.from,
+                    release: flags.release,
+                    today: io.today,
+                    classify,
+                });
+                const output = render(changelog, format);
+                if (flags.output) {
+                    await writeFile(path.resolve(io.cwd, flags.output), output);
+                    io.stderr(`Wrote ${flags.output}\n`);
+                }
+                else {
+                    io.stdout(output);
+                }
+                return 0;
+            }
+            case 'next-version': {
+                const { releases } = await buildChangelog({
+                    cwd: io.cwd,
+                    config: await loadConfig(io.cwd, flags.config),
+                    to: flags.to,
+                    classify,
+                    classifyReleases: 'unreleased',
+                });
+                const next = releases.find(release => release.tag === null)?.nextVersion;
+                if (!next) {
+                    // Non-zero and silent on stdout, so `$(chamoji next-version)` in a
+                    // release script stops instead of producing a release called "none".
+                    io.stderr('chamoji: no release needed (no commits since the last tag imply a version bump)\n');
+                    return NO_RELEASE_NEEDED;
+                }
+                io.stdout(`${next}\n`);
+                return 0;
+            }
+            default: {
+                io.stderr(`${command ? `chamoji: unknown command "${command}"\n` : ''}${cli.help}\n`);
+                return 2;
+            }
+        }
+    }
+    catch (error) {
+        io.stderr(`chamoji: ${error.message}\n`);
+        return 1;
+    }
+}
+function jevClassifier(io) {
+    const key = process.env['TYPESAFE_API_KEY']?.trim();
+    if (!key) {
+        throw new Error('--ai needs a TypeSafe API key: set TYPESAFE_API_KEY (get one at https://typesafe.ai)');
+    }
+    // Keys copied from a dashboard often end in "…"; headers can't carry it.
+    const invalid = /[^\x21-\x7E]/.exec(key);
+    if (invalid) {
+        throw new Error(invalid[0] === '\u2026'
+            ? 'TYPESAFE_API_KEY contains "…", so it looks truncated; copy the full key again'
+            : 'TYPESAFE_API_KEY contains a character that is not plain ASCII; copy the full key again');
+    }
+    const client = new TypeSafeClient();
+    return createJevClassifier({ systemOne: async (request) => client.systemOne(request) }, { report: line => io.stderr(`${line}\n`) });
+}
+//# sourceMappingURL=run.js.map

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@chamoji/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Changelogs from gitmoji and Conventional Commits",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "chamoji": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "dependencies": {
+    "@typesafe-ai/sdk": "^0.7.0",
+    "meow": "^14.1.0",
+    "@chamoji/core": "0.2.0"
+  },
+  "keywords": [
+    "changelog",
+    "gitmoji",
+    "conventional-commits",
+    "semver",
+    "release",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p ."
+  }
 }

package/readme.md

@@ -0,0 +1,116 @@
+# chamoji
+
+Changelogs from your git history. Chamoji reads [gitmoji](https://gitmoji.dev), [Conventional Commits](https://www.conventionalcommits.org) and plain messages like "Fix crash on startup". It groups them into Keep a Changelog sections and suggests the next semver version.
+
+## Install
+
+```bash
+npm install --global @chamoji/cli
+```
+
+Or run it without installing: `npx @chamoji/cli changelog`.
+
+Requires Node.js 22 or newer and git.
+
+## Usage
+
+```bash
+chamoji changelog                          # Markdown to stdout
+chamoji changelog --output CHANGELOG.md    # write a file
+chamoji changelog --format html --output changelog.html
+chamoji changelog --format json            # machine-readable
+chamoji next-version                       # e.g. 1.3.0
+```
+
+`next-version` exits with code 3 and prints nothing to stdout when no commit since the last tag implies a version bump (only docs, tests or refactors, say).
+
+| Option                | Meaning                                                                                                                                                 |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--format`            | `markdown` (default), `md`, `json` or `html`                                                                                                            |
+| `--output`, `-o`      | Write to a file instead of stdout                                                                                                                       |
+| `--from <tag>`        | Leave out this release and everything older                                                                                                             |
+| `--to <ref>`          | Ref to treat as the head of history (default `HEAD`)                                                                                                    |
+| `--release <version>` | Name and date the unreleased section, e.g. when cutting a release. Its compare link targets the tag it will get (`v<version>` when your tags use a `v`) |
+| `--config <file>`     | Config file (default `chamoji.config.json` when present)                                                                                                |
+| `--ai`                | Sort the commits no rule can place with [Jev](https://typesafe.ai) (see below)                                                                          |
+
+Typical release flow:
+
+```bash
+set -e
+version=$(chamoji next-version)   # stops here when nothing needs releasing
+chamoji changelog --release "$version" --output CHANGELOG.md
+git commit -am "🔖 Release v$version"
+git tag "v$version"
+```
+
+## How commits are read
+
+- **Releases** are semver tags reachable from `--to` (`v1.2.0` or `1.2.0`, prereleases included), ordered by semver. Commits after the newest tag form the Unreleased section.
+- **Merge commits** are skipped.
+- **`git revert` commits** (`Revert "✨ Add login"`) are listed as ⏪ reverts, not by the emoji of the commit they undo.
+- **The gitmoji** can be a character (`✨`, with or without the invisible U+FE0F variation selector) or a shortcode (`:sparkles:`). Chamoji uses the earliest one in the subject. The list comes from the official [`gitmojis`](https://www.npmjs.com/package/gitmojis) package.
+- **These subject forms all work:**
+  - `✨ Add login`
+  - `✨ (auth): Add login`
+  - `feat(auth): ✨ Add login`
+  - `feat: Add login`. A Conventional type without an emoji maps to one: `feat`→✨, `fix`→🐛, `docs`→📝, and so on.
+- **Plain messages** are sorted by their wording:
+  - "Add …" goes to Added, "Fix …" to Fixed, "Remove …" to Removed, "Deprecate …" to Deprecated.
+  - Messages about docs, typos, tests, CI, performance, security and refactoring each go to their own section.
+  - Version-only commits (`1.2.1`, `Release 3.0.0`) are hidden.
+  - "Require Node.js 20" counts as a breaking change.
+  - Chamoji doesn't add emojis to plain messages, so they appear as written.
+- **Dependency updates** (⬆️ ⬇️ 📌 ➕ ➖, `chore(deps):`, `fix(deps):` and Dependabot or Renovate subjects) are collapsed into a single line, such as `⬆️ 47 dependency updates: jest, vite, … and 12 more`. The JSON output keeps every commit.
+- **Breaking changes** are 💥, a `!` after any type (`feat!:`, `deps!:`), or a `BREAKING CHANGE:` footer. They are listed under Breaking changes and give a major bump.
+- **The next version** comes from each gitmoji's `semver` field (✨ minor, 🐛 patch, …).
+- **Commit trailers** (`Key: value` lines at the end of a message) are parsed and included in the JSON output.
+
+## Sorting the rest with AI (`--ai`)
+
+Some messages are too vague for rules, such as "Accept camelCase flags" or "Tidelift tasks". `--ai` sends just those commits to [Jev](https://typesafe.ai), TypeSafe's fast classification model. It picks a gitmoji for each one. Picks below 60% confidence are dropped, and those commits stay in Miscellaneous.
+
+```bash
+export TYPESAFE_API_KEY=...   # from https://typesafe.ai
+chamoji changelog --ai
+```
+
+- **What is sent:** only the commits no rule could sort, at most 300 characters each of subject and body, with email addresses and trailer lines such as `Signed-off-by:` removed. Never diffs, code or author details. `next-version --ai` sends only unreleased commits.
+- **If a request fails:** chamoji stops sending, keeps the picks it already has, and leaves the rest in Miscellaneous.
+- **What it never does:** override an emoji or type the author wrote, or mark a change as breaking. Only authors declare breaking changes.
+- **Without `--ai`:** chamoji makes no network calls.
+
+## Config
+
+`chamoji.config.json`:
+
+```json
+{
+	"repositoryUrl": "https://github.com/acme/widgets",
+	"groups": [
+		{"group": "added", "label": "Added", "emojis": ["sparkles", "tada"]},
+		{"group": "fixed", "label": "Fixed", "emojis": ["bug", "ambulance"]},
+		{
+			"group": "useless",
+			"label": "Useless",
+			"emojis": ["bookmark"],
+			"hidden": true
+		},
+		{"group": "misc", "label": "Miscellaneous", "emojis": []}
+	]
+}
+```
+
+- `repositoryUrl` defaults to the `origin` remote. It is used for commit, issue (`#12`) and compare links.
+- `groups` replaces the default sections. Emojis are gitmoji codes without colons. Commits that match no group go to `misc` when that group exists. Hidden groups are left out of the output, and `"collapse": true` renders a group as one summary line, as the default Dependencies group does.
+- A plain JSON array of groups, the older format, is also accepted.
+
+## Development
+
+```bash
+pnpm install
+pnpm test     # vitest
+pnpm check    # build (type-check) + prettier
+```
+
+`packages/core` is the engine: git reading, parsing, grouping and rendering, with no UI. `packages/cli` is the `chamoji` command. See `docs/research/` for where the project is heading.

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.