@chamoji/cli 0.1.0 → 0.2.0

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.js

@@ -1,7 +1,9 @@
 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
@@ -15,6 +17,10 @@ const HELP = `
 	  --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
@@ -41,6 +47,7 @@ export async function run(argv, io) {
             to: { type: 'string', default: 'HEAD' },
             release: { type: 'string' },
             config: { type: 'string' },
+            ai: { type: 'boolean' },
             help: { type: 'boolean', shortFlag: 'h' },
             version: { type: 'boolean', shortFlag: 'v' },
         },
@@ -56,6 +63,7 @@ export async function run(argv, io) {
     }
     const [command] = cli.input;
     try {
+        const classify = flags.ai ? jevClassifier(io) : undefined;
         switch (command) {
             case 'changelog': {
                 const format = Object.hasOwn(FORMATS, flags.format)
@@ -71,6 +79,7 @@ export async function run(argv, io) {
                     from: flags.from,
                     release: flags.release,
                     today: io.today,
+                    classify,
                 });
                 const output = render(changelog, format);
                 if (flags.output) {
@@ -87,6 +96,8 @@ export async function run(argv, io) {
                     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) {
@@ -109,4 +120,19 @@ export async function run(argv, io) {
         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,6 @@
 {
   "name": "@chamoji/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Changelogs from gitmoji and Conventional Commits",
   "license": "MIT",
   "type": "module",
@@ -15,8 +15,9 @@
     "!dist/**/*.map"
   ],
   "dependencies": {
+    "@typesafe-ai/sdk": "^0.7.0",
     "meow": "^14.1.0",
-    "@chamoji/core": "0.1.0"
+    "@chamoji/core": "0.2.0"
   },
   "keywords": [
     "changelog",

package/readme.md

@@ -1,6 +1,6 @@
 # chamoji
 
-Changelogs from your git history. Chamoji reads [gitmoji](https://gitmoji.dev) and [Conventional Commits](https://www.conventionalcommits.org) messages, groups them into Keep a Changelog sections, and suggests the next semver version.
+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
 
@@ -32,6 +32,7 @@ chamoji next-version                       # e.g. 1.3.0
 | `--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:
 
@@ -54,10 +55,31 @@ git tag "v$version"
   - `✨ (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`:
@@ -80,7 +102,7 @@ git tag "v$version"
 ```
 
 - `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.
+- `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