@chamoji/core 0.0.0-stage → 0.1.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/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @chamoji/core
 
-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.
+The engine behind [`@chamoji/cli`](https://www.npmjs.com/package/@chamoji/cli). It reads git history, parses gitmoji and Conventional Commits messages, groups commits into changelog sections, suggests the next semver version, and renders Markdown, HTML or JSON. It has no UI and makes no network calls. Needs Node.js 22+ and git.
+
+```js
+import {buildChangelog, loadConfig, render} from '@chamoji/core';
+
+const cwd = process.cwd();
+const changelog = await buildChangelog({cwd, config: await loadConfig(cwd)});
+console.log(render(changelog, 'markdown'));
+```
+
+Lower-level pieces are exported too: `parseCommit`, `findGitmoji`, `groupCommits`, `bumpFor`, `nextVersion`, `readCommits`, `listReleaseTags`, `renderMarkdown`, `renderHtml` and `renderJson`.
+
+MIT licensed.

package/dist/changelog.d.ts

@@ -0,0 +1,14 @@
+import type { ChamojiConfig, Changelog } from './types.js';
+export type BuildChangelogOptions = {
+    cwd: string;
+    config: ChamojiConfig;
+    /** Ref treated as the head of history. Defaults to `HEAD`. */
+    to?: string;
+    /** Stop before the release with this tag (it and older ones are left out). */
+    from?: string;
+    /** Version to give the Unreleased section, dated `today`. */
+    release?: string;
+    /** `YYYY-MM-DD`; defaults to the current UTC date. */
+    today?: string;
+};
+export declare function buildChangelog(options: BuildChangelogOptions): Promise<Changelog>;

package/dist/changelog.js

@@ -0,0 +1,64 @@
+import semver from 'semver';
+import { assertGitRepo, assertRevision, getRemoteWebUrl, listReleaseTags, readCommits, } from './git.js';
+import { groupCommits } from './group.js';
+import { parseCommit } from './parse.js';
+import { bumpFor, nextVersion } from './version.js';
+/** The tag a `--release` version will get, following the latest tag's `v` style. */
+function futureTag(release, latestTag) {
+    if (release.startsWith('v')) {
+        return release;
+    }
+    return latestTag === null || latestTag.startsWith('v')
+        ? `v${release}`
+        : release;
+}
+export async function buildChangelog(options) {
+    const { cwd, config, to = 'HEAD', from, release } = options;
+    const today = options.today ?? new Date().toISOString().slice(0, 10);
+    if (release !== undefined && semver.valid(release) === null) {
+        throw new Error(`Invalid release version: ${release}`);
+    }
+    await assertGitRepo(cwd);
+    await assertRevision(cwd, to);
+    const tags = await listReleaseTags(cwd, to);
+    if (from && !tags.some(tag => tag.name === from)) {
+        throw new Error(`Unknown release tag for --from: ${from}`);
+    }
+    const makeRelease = (fields, raw, isUnreleased) => {
+        const commits = raw.map(parseCommit);
+        const bump = bumpFor(commits);
+        return {
+            ...fields,
+            bump,
+            nextVersion: isUnreleased ? nextVersion(fields.previousTag, bump) : null,
+            groups: groupCommits(commits, config.groups),
+        };
+    };
+    const releases = [];
+    const latest = tags[0]?.name ?? null;
+    const unreleased = await readCommits(cwd, latest ? `${latest}..${to}` : to);
+    if (unreleased.length > 0) {
+        releases.push(makeRelease({
+            version: release ?? 'Unreleased',
+            tag: release ? futureTag(release, latest) : null,
+            previousTag: latest,
+            date: release ? today : null,
+        }, unreleased, true));
+    }
+    for (const [index, tag] of tags.entries()) {
+        if (tag.name === from) {
+            break;
+        }
+        const previousTag = tags[index + 1]?.name ?? null;
+        const raw = await readCommits(cwd, previousTag ? `${previousTag}..${tag.name}` : tag.name);
+        releases.push(makeRelease({
+            version: tag.name,
+            tag: tag.name,
+            previousTag,
+            date: tag.date.slice(0, 10) || null,
+        }, raw, false));
+    }
+    const repositoryUrl = config.repositoryUrl ?? (await getRemoteWebUrl(cwd));
+    return { ...(repositoryUrl ? { repositoryUrl } : {}), releases };
+}
+//# sourceMappingURL=changelog.js.map

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+import type { ChamojiConfig, GroupConfig } from './types.js';
+export declare const CONFIG_FILE = "chamoji.config.json";
+/**
+ * Keep a Changelog style sections. Every official gitmoji appears exactly once
+ * (enforced by a test). The retired `apple`, `penguin`, `checkered_flag`,
+ * `robot` and `green_apple` codes stay under Fixed for older histories.
+ */
+export declare const DEFAULT_GROUP_CONFIG: GroupConfig;
+/**
+ * Loads `explicitPath`, or `chamoji.config.json` in `cwd` when present.
+ * A JSON array is treated as a legacy group config.
+ */
+export declare function loadConfig(cwd: string, explicitPath?: string): Promise<ChamojiConfig>;

package/dist/config.js

@@ -0,0 +1,179 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+export const CONFIG_FILE = 'chamoji.config.json';
+/**
+ * Keep a Changelog style sections. Every official gitmoji appears exactly once
+ * (enforced by a test). The retired `apple`, `penguin`, `checkered_flag`,
+ * `robot` and `green_apple` codes stay under Fixed for older histories.
+ */
+export const DEFAULT_GROUP_CONFIG = [
+    {
+        group: 'added',
+        label: 'Added',
+        emojis: [
+            'sparkles',
+            'tada',
+            'white_check_mark',
+            'construction_worker',
+            'chart_with_upwards_trend',
+            'heavy_plus_sign',
+            'loud_sound',
+            'globe_with_meridians',
+            'camera_flash',
+            'seedling',
+            'test_tube',
+            'necktie',
+            'triangular_flag_on_post',
+            'egg',
+            'money_with_wings',
+            'thread',
+            'safety_vest',
+            'airplane',
+            'stethoscope',
+        ],
+    },
+    {
+        group: 'changed',
+        label: 'Changed',
+        emojis: [
+            'art',
+            'zap',
+            'lipstick',
+            'rotating_light',
+            'arrow_down',
+            'arrow_up',
+            'pushpin',
+            'recycle',
+            'wrench',
+            'rewind',
+            'alien',
+            'truck',
+            'bento',
+            'wheelchair',
+            'speech_balloon',
+            'card_file_box',
+            'children_crossing',
+            'building_construction',
+            'iphone',
+            'hammer',
+            'package',
+            'label',
+            'mag',
+            'dizzy',
+            'goal_net',
+            'bricks',
+            'technologist',
+            'page_facing_up',
+            'poop',
+        ],
+    },
+    { group: 'breaking_changes', label: 'Breaking changes', emojis: ['boom'] },
+    { group: 'deprecated', label: 'Deprecated', emojis: ['wastebasket'] },
+    {
+        group: 'removed',
+        label: 'Removed',
+        emojis: ['fire', 'heavy_minus_sign', 'mute', 'coffin'],
+    },
+    {
+        group: 'fixed',
+        label: 'Fixed',
+        emojis: [
+            'bug',
+            'ambulance',
+            'green_heart',
+            'pencil2',
+            'adhesive_bandage',
+            'apple',
+            'penguin',
+            'checkered_flag',
+            'robot',
+            'green_apple',
+        ],
+    },
+    {
+        group: 'security',
+        label: 'Security',
+        emojis: ['lock', 'closed_lock_with_key', 'passport_control'],
+    },
+    {
+        group: 'useless',
+        label: 'Useless',
+        emojis: ['bookmark', 'twisted_rightwards_arrows'],
+        hidden: true,
+    },
+    {
+        group: 'misc',
+        label: 'Miscellaneous',
+        emojis: [
+            'memo',
+            'bulb',
+            'rocket',
+            'construction',
+            'beers',
+            'busts_in_silhouette',
+            'clown_face',
+            'see_no_evil',
+            'alembic',
+            'monocle_face',
+        ],
+    },
+];
+/**
+ * Loads `explicitPath`, or `chamoji.config.json` in `cwd` when present.
+ * A JSON array is treated as a legacy group config.
+ */
+export async function loadConfig(cwd, explicitPath) {
+    const file = path.resolve(cwd, explicitPath ?? CONFIG_FILE);
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+        if (explicitPath) {
+            throw new Error(`Config file not found: ${file}`);
+        }
+        return { groups: DEFAULT_GROUP_CONFIG };
+    }
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`Invalid config ${file}: ${error.message}`);
+    }
+    if (Array.isArray(data)) {
+        return { groups: validateGroups(data, file) };
+    }
+    if (!data || typeof data !== 'object') {
+        throw new Error(`Invalid config ${file}: expected an object or an array`);
+    }
+    const { groups, repositoryUrl } = data;
+    if (repositoryUrl !== undefined && typeof repositoryUrl !== 'string') {
+        throw new Error(`Invalid config ${file}: repositoryUrl must be a string`);
+    }
+    return {
+        groups: groups === undefined
+            ? DEFAULT_GROUP_CONFIG
+            : validateGroups(groups, file),
+        ...(repositoryUrl ? { repositoryUrl } : {}),
+    };
+}
+function validateGroups(value, file) {
+    const valid = Array.isArray(value) &&
+        value.every(item => item &&
+            typeof item.group === 'string' &&
+            typeof item.label === 'string' &&
+            Array.isArray(item.emojis) &&
+            item.emojis.every((code) => typeof code === 'string'));
+    if (!valid) {
+        throw new Error(`Invalid config ${file}: groups must be [{group, label, emojis: string[]}]`);
+    }
+    return value.map(item => ({
+        ...item,
+        emojis: item.emojis.map(code => code.replaceAll(':', '')),
+    }));
+}
+//# sourceMappingURL=config.js.map

package/dist/git.d.ts

@@ -0,0 +1,20 @@
+import type { RawCommit } from './types.js';
+export type ReleaseTag = {
+    name: string;
+    date: string;
+};
+/** Runs git without a shell and returns stdout. */
+export declare function runGit(args: string[], cwd: string): Promise<string>;
+export declare function assertGitRepo(cwd: string): Promise<void>;
+export declare function assertRevision(cwd: string, ref: string): Promise<void>;
+/** Non-merge commits in `range` (anything `git log` accepts), newest first. */
+export declare function readCommits(cwd: string, range: string): Promise<RawCommit[]>;
+/**
+ * Semver tags reachable from `to`, newest first. `date` is the tagged
+ * commit's committer date, so annotated and lightweight tags agree.
+ */
+export declare function listReleaseTags(cwd: string, to: string): Promise<ReleaseTag[]>;
+/** `origin` as an https web URL, or undefined when there is none. */
+export declare function getRemoteWebUrl(cwd: string): Promise<string | undefined>;
+/** Converts an ssh, scp-style or http(s) git remote to a browsable URL. */
+export declare function toWebUrl(remote: string): string | undefined;

package/dist/git.js

@@ -0,0 +1,133 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import semver from 'semver';
+const execFileAsync = promisify(execFile);
+const FIELD = '\u001F';
+const RECORD = '\u001E';
+/** Runs git without a shell and returns stdout. */
+export async function runGit(args, cwd) {
+    const { stdout } = await execFileAsync('git', args, {
+        cwd,
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    return stdout;
+}
+export async function assertGitRepo(cwd) {
+    try {
+        await runGit(['rev-parse', '--is-inside-work-tree'], cwd);
+    }
+    catch (error) {
+        const { code, stderr } = error;
+        if (code === 'ENOENT') {
+            throw new Error('git is not installed or not on PATH');
+        }
+        if (stderr?.includes('not a git repository')) {
+            throw new Error(`Not a git repository: ${cwd}`);
+        }
+        throw new Error(stderr?.trim() || error.message);
+    }
+}
+export async function assertRevision(cwd, ref) {
+    try {
+        await runGit(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], cwd);
+    }
+    catch {
+        throw new Error(ref === 'HEAD'
+            ? 'Repository has no commits yet'
+            : `Unknown revision: ${ref}`);
+    }
+}
+/** Non-merge commits in `range` (anything `git log` accepts), newest first. */
+export async function readCommits(cwd, range) {
+    const format = [
+        '%H',
+        '%h',
+        '%an',
+        '%ae',
+        '%aI',
+        '%s',
+        '%b',
+        '%(trailers:only,unfold)',
+    ].join('%x1f');
+    const stdout = await runGit([
+        'log',
+        '--no-merges',
+        '--no-show-signature',
+        `--format=${format}%x1e`,
+        '--end-of-options',
+        range,
+        '--',
+    ], cwd);
+    return stdout
+        .split(RECORD)
+        .map(record => record.replace(/^\n/, ''))
+        .filter(record => record.length > 0)
+        .map(record => {
+        const [hash, shortHash, authorName, authorEmail, date, subject, body, trailers,] = record.split(FIELD);
+        return {
+            hash: hash,
+            shortHash: shortHash,
+            authorName: authorName,
+            authorEmail: authorEmail,
+            date: date,
+            subject: subject,
+            body: body,
+            trailers: trailers ?? '',
+        };
+    });
+}
+/**
+ * Semver tags reachable from `to`, newest first. `date` is the tagged
+ * commit's committer date, so annotated and lightweight tags agree.
+ */
+export async function listReleaseTags(cwd, to) {
+    const stdout = await runGit([
+        'tag',
+        `--merged=${to}`,
+        '--format=%(refname:strip=2)%1f%(committerdate:iso-strict)%1f%(*committerdate:iso-strict)',
+    ], cwd);
+    return stdout
+        .split('\n')
+        .filter(Boolean)
+        .map(line => {
+        const [name, direct, dereferenced] = line.split(FIELD);
+        return { name: name, date: dereferenced || direct || '' };
+    })
+        .filter(tag => semver.valid(tag.name) !== null)
+        .sort((a, b) => semver.rcompare(a.name, b.name));
+}
+/** `origin` as an https web URL, or undefined when there is none. */
+export async function getRemoteWebUrl(cwd) {
+    try {
+        return toWebUrl((await runGit(['remote', 'get-url', 'origin'], cwd)).trim());
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Converts an ssh, scp-style or http(s) git remote to a browsable URL. */
+export function toWebUrl(remote) {
+    const scp = /^(?:[^@\s/]+@)?([^:/\s]+):(?!\/)(.+)$/.exec(remote);
+    if (scp && !/^[a-z][a-z\d+.-]*:\/\//i.test(remote)) {
+        return `https://${scp[1]}/${stripGitSuffix(scp[2])}`;
+    }
+    let url;
+    try {
+        url = new URL(remote);
+    }
+    catch {
+        return undefined;
+    }
+    if (!['https:', 'http:', 'ssh:', 'git:'].includes(url.protocol)) {
+        return undefined;
+    }
+    const protocol = url.protocol === 'http:' ? 'http' : 'https';
+    const host = url.protocol === 'https:' || url.protocol === 'http:'
+        ? url.host
+        : url.hostname;
+    return `${protocol}://${host}/${stripGitSuffix(url.pathname.replace(/^\/+/, ''))}`;
+}
+function stripGitSuffix(repoPath) {
+    return repoPath.replace(/\/+$/, '').replace(/\.git$/, '');
+}
+//# sourceMappingURL=git.js.map

package/dist/gitmojis.d.ts

@@ -0,0 +1,22 @@
+import type { SemverBump } from './types.js';
+export type GitmojiInfo = {
+    /** Code without colons, e.g. `white_check_mark`. */
+    code: string;
+    emoji: string;
+    description: string;
+    semver: SemverBump | null;
+};
+export type GitmojiMatch = {
+    code: string;
+    index: number;
+    length: number;
+};
+/** Removes U+FE0F so `⚡` and `⚡️` compare equal. */
+export declare function normalizeEmoji(text: string): string;
+export declare const GITMOJIS: readonly GitmojiInfo[];
+export declare function getGitmoji(code: string): GitmojiInfo | undefined;
+/**
+ * Finds the earliest gitmoji in already-normalized `text`, either as a known
+ * `:code:` or as its unicode character.
+ */
+export declare function findGitmoji(text: string): GitmojiMatch | null;

package/dist/gitmojis.js

@@ -0,0 +1,47 @@
+import { gitmojis } from 'gitmojis';
+/** Removes U+FE0F so `⚡` and `⚡️` compare equal. */
+export function normalizeEmoji(text) {
+    return text.replaceAll('️', '');
+}
+export const GITMOJIS = gitmojis.map(gitmoji => ({
+    code: gitmoji.code.slice(1, -1),
+    emoji: gitmoji.emoji,
+    description: gitmoji.description,
+    semver: gitmoji.semver,
+}));
+const byCode = new Map(GITMOJIS.map(gitmoji => [gitmoji.code, gitmoji]));
+const byEmoji = GITMOJIS.map(gitmoji => ({
+    code: gitmoji.code,
+    emoji: normalizeEmoji(gitmoji.emoji),
+}));
+export function getGitmoji(code) {
+    return byCode.get(code);
+}
+/**
+ * Finds the earliest gitmoji in already-normalized `text`, either as a known
+ * `:code:` or as its unicode character.
+ */
+export function findGitmoji(text) {
+    let best = null;
+    const consider = (match) => {
+        if (!best ||
+            match.index < best.index ||
+            (match.index === best.index && match.length > best.length)) {
+            best = match;
+        }
+    };
+    for (const match of text.matchAll(/:([a-z\d_+-]+):/g)) {
+        if (byCode.has(match[1])) {
+            consider({ code: match[1], index: match.index, length: match[0].length });
+            break;
+        }
+    }
+    for (const { code, emoji } of byEmoji) {
+        const index = text.indexOf(emoji);
+        if (index !== -1) {
+            consider({ code, index, length: emoji.length });
+        }
+    }
+    return best;
+}
+//# sourceMappingURL=gitmojis.js.map

package/dist/group.d.ts

@@ -0,0 +1,7 @@
+import type { Group, GroupConfig, ParsedCommit } from './types.js';
+/**
+ * Sorts commits into the configured sections. Breaking commits go to
+ * Breaking changes whatever their gitmoji; unmatched ones go to misc.
+ * Returns groups in config order, without empty or hidden ones.
+ */
+export declare function groupCommits(commits: ParsedCommit[], config: GroupConfig): Group[];

package/dist/group.js

@@ -0,0 +1,32 @@
+const BREAKING_GROUP = 'breaking_changes';
+const FALLBACK_GROUP = 'misc';
+/**
+ * Sorts commits into the configured sections. Breaking commits go to
+ * Breaking changes whatever their gitmoji; unmatched ones go to misc.
+ * Returns groups in config order, without empty or hidden ones.
+ */
+export function groupCommits(commits, config) {
+    const buckets = new Map(config.map(item => [item.group, []]));
+    const groupByCode = new Map();
+    for (const item of config) {
+        for (const code of item.emojis) {
+            if (!groupByCode.has(code)) {
+                groupByCode.set(code, item.group);
+            }
+        }
+    }
+    for (const commit of commits) {
+        const target = commit.breaking && buckets.has(BREAKING_GROUP)
+            ? BREAKING_GROUP
+            : (commit.gitmoji && groupByCode.get(commit.gitmoji)) || FALLBACK_GROUP;
+        buckets.get(target)?.push(commit);
+    }
+    return config
+        .filter(item => !item.hidden && buckets.get(item.group).length > 0)
+        .map(item => ({
+        group: item.group,
+        label: item.label,
+        commits: buckets.get(item.group),
+    }));
+}
+//# sourceMappingURL=group.js.map

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { buildChangelog, type BuildChangelogOptions } from './changelog.js';
+export { CONFIG_FILE, DEFAULT_GROUP_CONFIG, loadConfig } from './config.js';
+export { getRemoteWebUrl, listReleaseTags, readCommits, runGit, toWebUrl, type ReleaseTag, } from './git.js';
+export { GITMOJIS, findGitmoji, getGitmoji, normalizeEmoji, type GitmojiInfo, type GitmojiMatch, } from './gitmojis.js';
+export { groupCommits } from './group.js';
+export { parseCommit } from './parse.js';
+export { escapeHtml, render, renderHtml, renderJson, renderMarkdown, type OutputFormat, } from './render/index.js';
+export type * from './types.js';
+export { bumpFor, nextVersion } from './version.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+export { buildChangelog } from './changelog.js';
+export { CONFIG_FILE, DEFAULT_GROUP_CONFIG, loadConfig } from './config.js';
+export { getRemoteWebUrl, listReleaseTags, readCommits, runGit, toWebUrl, } from './git.js';
+export { GITMOJIS, findGitmoji, getGitmoji, normalizeEmoji, } from './gitmojis.js';
+export { groupCommits } from './group.js';
+export { parseCommit } from './parse.js';
+export { escapeHtml, render, renderHtml, renderJson, renderMarkdown, } from './render/index.js';
+export { bumpFor, nextVersion } from './version.js';
+//# sourceMappingURL=index.js.map

package/dist/parse.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedCommit, RawCommit } from './types.js';
+export declare function parseCommit(raw: RawCommit): ParsedCommit;

package/dist/parse.js

@@ -0,0 +1,85 @@
+import { findGitmoji, normalizeEmoji } from './gitmojis.js';
+/** Conventional Commits types we recognize, and the gitmoji each implies. */
+const TYPE_TO_GITMOJI = {
+    feat: 'sparkles',
+    fix: 'bug',
+    docs: 'memo',
+    style: 'art',
+    refactor: 'recycle',
+    perf: 'zap',
+    test: 'white_check_mark',
+    build: 'package',
+    ci: 'construction_worker',
+    chore: 'wrench',
+    revert: 'rewind',
+};
+const CONVENTIONAL_PREFIX = /^(\w+)(?:\(([^)]+)\))?(!)?:\s*/;
+const GITMOJI_CLI_SCOPE = /^\(([^)]+)\):\s*/;
+const BREAKING_FOOTER = /^BREAKING[ -]CHANGE:/m;
+const GIT_REVERT = /^Revert "(.+)"$/;
+export function parseCommit(raw) {
+    const revert = GIT_REVERT.exec(raw.subject.trim());
+    if (revert) {
+        // `git revert` quotes the original subject; classify by the revert, not
+        // by the reverted commit's gitmoji.
+        const original = parseCommit({ ...raw, subject: revert[1], body: '' });
+        return {
+            ...original,
+            body: raw.body,
+            gitmoji: 'rewind',
+            type: null,
+            description: `Revert "${original.description}"`,
+            breaking: BREAKING_FOOTER.test(raw.body),
+        };
+    }
+    let text = normalizeEmoji(raw.subject).trim();
+    let type = null;
+    let scope = null;
+    let bang = false;
+    const prefix = CONVENTIONAL_PREFIX.exec(text);
+    // Known types always count; any other word counts only with a `!`, so
+    // prose like "Note: …" is left alone.
+    if (prefix && (prefix[1].toLowerCase() in TYPE_TO_GITMOJI || prefix[3])) {
+        type = prefix[1].toLowerCase();
+        scope = prefix[2] ?? null;
+        bang = Boolean(prefix[3]);
+        text = text.slice(prefix[0].length);
+    }
+    let gitmoji = null;
+    const found = findGitmoji(text);
+    if (found) {
+        gitmoji = found.code;
+        text = (text.slice(0, found.index) + text.slice(found.index + found.length))
+            .replaceAll(/\s{2,}/g, ' ')
+            .trim();
+    }
+    const cliScope = scope ? null : GITMOJI_CLI_SCOPE.exec(text);
+    if (cliScope) {
+        scope = cliScope[1];
+        text = text.slice(cliScope[0].length);
+    }
+    if (!gitmoji && type) {
+        gitmoji = TYPE_TO_GITMOJI[type] ?? null;
+    }
+    const { trailers: rawTrailers, ...rest } = raw;
+    return {
+        ...rest,
+        gitmoji,
+        type,
+        scope,
+        description: text.trim(),
+        breaking: gitmoji === 'boom' || bang || BREAKING_FOOTER.test(raw.body),
+        trailers: parseTrailers(rawTrailers),
+    };
+}
+function parseTrailers(text) {
+    const trailers = [];
+    for (const line of text.split('\n')) {
+        const match = /^([\w-]+):\s*(.*)$/.exec(line.trim());
+        if (match) {
+            trailers.push({ key: match[1], value: match[2] });
+        }
+    }
+    return trailers;
+}
+//# sourceMappingURL=parse.js.map

package/dist/render/html.d.ts

@@ -0,0 +1,3 @@
+import type { Changelog } from '../types.js';
+export declare const escapeHtml: (text: string) => string;
+export declare function renderHtml(changelog: Changelog): string;

package/dist/render/html.js

@@ -0,0 +1,60 @@
+import { commitLink, emojiFor, issueLink, releaseLink, safeRepositoryUrl, splitIssues, } from './shared.js';
+const ESCAPES = {
+    '&': '&',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#x27;',
+};
+export const escapeHtml = (text) => text.replaceAll(/[&<>"']/g, char => ESCAPES[char]);
+const anchor = (href, content) => `<a href="${escapeHtml(href)}">${content}</a>`;
+const STYLE = `body{font-family:system-ui,sans-serif;line-height:1.6;max-width:48rem;margin:2rem auto;padding:0 1rem}
+h2{margin-top:2rem;border-bottom:1px solid #ddd}time{color:#666;font-size:.9em;font-weight:normal}
+code{font-size:.85em}`;
+export function renderHtml(changelog) {
+    const url = safeRepositoryUrl(changelog);
+    const out = [
+        '<!doctype html>',
+        '<html lang="en">',
+        '<head>',
+        '<meta charset="utf-8">',
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        '<title>Changelog</title>',
+        `<style>${STYLE}</style>`,
+        '</head>',
+        '<body>',
+        '<h1>Changelog</h1>',
+    ];
+    for (const release of changelog.releases) {
+        const link = releaseLink(release, url);
+        const version = escapeHtml(release.version);
+        const date = release.date
+            ? ` <time datetime="${escapeHtml(release.date)}">${escapeHtml(release.date)}</time>`
+            : '';
+        out.push(`<section id="${version}">`, `<h2>${link ? anchor(link, version) : version}${date}</h2>`);
+        for (const group of release.groups) {
+            out.push(`<h3>${escapeHtml(group.label)}</h3>`, '<ul>');
+            for (const commit of group.commits) {
+                out.push(`<li>${renderCommit(commit, url)}</li>`);
+            }
+            out.push('</ul>');
+        }
+        out.push('</section>');
+    }
+    out.push('</body>', '</html>', '');
+    return out.join('\n');
+}
+function renderCommit(commit, url) {
+    const emoji = emojiFor(commit);
+    const scope = commit.scope
+        ? `<strong>${escapeHtml(commit.scope)}:</strong> `
+        : '';
+    const description = splitIssues(commit.description)
+        .map(part => part.issue && url
+        ? anchor(issueLink(part.issue, url), escapeHtml(part.text))
+        : escapeHtml(part.text))
+        .join('');
+    const hash = `<code>${escapeHtml(commit.shortHash)}</code>`;
+    return `${emoji ? `${escapeHtml(emoji)} ` : ''}${scope}${description} (${url ? anchor(commitLink(commit, url), hash) : hash})`;
+}
+//# sourceMappingURL=html.js.map

package/dist/render/index.d.ts

@@ -0,0 +1,6 @@
+import type { Changelog } from '../types.js';
+export type OutputFormat = 'markdown' | 'json' | 'html';
+export declare const renderJson: (changelog: Changelog) => string;
+export declare function render(changelog: Changelog, format: OutputFormat): string;
+export { escapeHtml, renderHtml } from './html.js';
+export { renderMarkdown } from './markdown.js';

package/dist/render/index.js

@@ -0,0 +1,19 @@
+import { renderHtml } from './html.js';
+import { renderMarkdown } from './markdown.js';
+export const renderJson = (changelog) => `${JSON.stringify(changelog, null, 2)}\n`;
+export function render(changelog, format) {
+    switch (format) {
+        case 'markdown': {
+            return renderMarkdown(changelog);
+        }
+        case 'html': {
+            return renderHtml(changelog);
+        }
+        case 'json': {
+            return renderJson(changelog);
+        }
+    }
+}
+export { escapeHtml, renderHtml } from './html.js';
+export { renderMarkdown } from './markdown.js';
+//# sourceMappingURL=index.js.map

package/dist/render/markdown.d.ts

@@ -0,0 +1,2 @@
+import type { Changelog } from '../types.js';
+export declare function renderMarkdown(changelog: Changelog): string;

package/dist/render/markdown.js

@@ -0,0 +1,55 @@
+import { commitLink, emojiFor, issueLink, releaseLink, safeRepositoryUrl, splitIssues, } from './shared.js';
+/**
+ * Makes commit text inert outside code spans: no raw HTML, and no links or
+ * images, since squash-merged PR titles can come from anyone. Backticks are
+ * escaped too: any left here are unpaired, and an unpaired run could open a
+ * code span a Markdown parser sees differently from `splitCodeSpans`.
+ */
+const escapeMarkdown = (text) => text
+    .replaceAll(/[\\[\]`]/g, char => `\\${char}`)
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+/**
+ * Splits text into single-backtick `code spans` and the parts between. A span
+ * holds no backticks, so emitting it as-is is safe once the surrounding text
+ * has its stray backticks escaped.
+ */
+const splitCodeSpans = (text) => text
+    .split(/(`[^`\n]+`)/)
+    .filter(part => part.length > 0)
+    .map(part => ({ text: part, code: /^`[^`\n]+`$/.test(part) }));
+export function renderMarkdown(changelog) {
+    const url = safeRepositoryUrl(changelog);
+    const lines = ['# Changelog', ''];
+    for (const release of changelog.releases) {
+        const link = releaseLink(release, url);
+        const title = link ? `[${release.version}](${link})` : release.version;
+        lines.push(`## ${title}${release.date ? ` - ${release.date}` : ''}`, '');
+        for (const group of release.groups) {
+            lines.push(`### ${group.label}`, '');
+            for (const commit of group.commits) {
+                lines.push(`- ${renderCommit(commit, url)}`);
+            }
+            lines.push('');
+        }
+    }
+    return lines.join('\n').replace(/\n+$/, '\n');
+}
+function renderCommit(commit, url) {
+    const emoji = emojiFor(commit);
+    const scope = commit.scope ? `**${escapeMarkdown(commit.scope)}:** ` : '';
+    const description = splitCodeSpans(commit.description)
+        .map(span => span.code
+        ? span.text
+        : splitIssues(span.text)
+            .map(part => part.issue && url
+            ? `[${part.text}](${issueLink(part.issue, url)})`
+            : escapeMarkdown(part.text))
+            .join(''))
+        .join('');
+    const hash = url
+        ? `[${commit.shortHash}](${commitLink(commit, url)})`
+        : commit.shortHash;
+    return `${emoji ? `${emoji} ` : ''}${scope}${description} (${hash})`;
+}
+//# sourceMappingURL=markdown.js.map

package/dist/render/shared.d.ts

@@ -0,0 +1,17 @@
+import type { Changelog, ParsedCommit, Release } from '../types.js';
+/** The repository URL if it is plain http(s), without a trailing slash. */
+export declare function safeRepositoryUrl(changelog: Changelog): string | undefined;
+/** Where a release heading links to: a compare view, when one exists. */
+export declare function releaseLink(release: Release, url: string | undefined): string | undefined;
+export declare function commitLink(commit: ParsedCommit, url: string): string;
+export declare function issueLink(issue: string, url: string): string;
+/** The commit's gitmoji as a character, `:code:` for retired ones, or ''. */
+export declare function emojiFor(commit: ParsedCommit): string;
+/**
+ * Splits text into plain parts and `#123` issue references, so renderers can
+ * escape the plain parts and link the references.
+ */
+export declare function splitIssues(text: string): Array<{
+    text: string;
+    issue?: string;
+}>;

package/dist/render/shared.js

@@ -0,0 +1,39 @@
+import { getGitmoji } from '../gitmojis.js';
+/** The repository URL if it is plain http(s), without a trailing slash. */
+export function safeRepositoryUrl(changelog) {
+    const url = changelog.repositoryUrl;
+    return url && /^https?:\/\/[^\s"'<>]+$/.test(url)
+        ? url.replace(/\/+$/, '')
+        : undefined;
+}
+/** Where a release heading links to: a compare view, when one exists. */
+export function releaseLink(release, url) {
+    if (!url || !release.previousTag) {
+        return undefined;
+    }
+    return `${url}/compare/${release.previousTag}...${release.tag ?? 'HEAD'}`;
+}
+export function commitLink(commit, url) {
+    return `${url}/commit/${commit.hash}`;
+}
+export function issueLink(issue, url) {
+    return `${url}/issues/${issue}`;
+}
+/** The commit's gitmoji as a character, `:code:` for retired ones, or ''. */
+export function emojiFor(commit) {
+    if (!commit.gitmoji) {
+        return '';
+    }
+    return getGitmoji(commit.gitmoji)?.emoji ?? `:${commit.gitmoji}:`;
+}
+/**
+ * Splits text into plain parts and `#123` issue references, so renderers can
+ * escape the plain parts and link the references.
+ */
+export function splitIssues(text) {
+    return text
+        .split(/(#\d+)\b/)
+        .filter(part => part.length > 0)
+        .map(part => /^#\d+$/.test(part) ? { text: part, issue: part.slice(1) } : { text: part });
+}
+//# sourceMappingURL=shared.js.map

package/dist/types.d.ts

@@ -0,0 +1,66 @@
+export type SemverBump = 'major' | 'minor' | 'patch';
+/** One commit as read from `git log`, before any interpretation. */
+export type RawCommit = {
+    hash: string;
+    shortHash: string;
+    authorName: string;
+    authorEmail: string;
+    /** ISO 8601 author date. */
+    date: string;
+    subject: string;
+    body: string;
+    /** Raw `%(trailers:only,unfold)` output: one `Key: value` per line. */
+    trailers: string;
+};
+export type Trailer = {
+    key: string;
+    value: string;
+};
+export type ParsedCommit = Omit<RawCommit, 'trailers'> & {
+    /** Gitmoji code without colons, e.g. `sparkles`. */
+    gitmoji: string | null;
+    /** Conventional Commits type, e.g. `feat`. */
+    type: string | null;
+    scope: string | null;
+    /** Subject with the type, scope and gitmoji removed. */
+    description: string;
+    breaking: boolean;
+    trailers: Trailer[];
+};
+export type GroupConfigItem = {
+    group: string;
+    label: string;
+    /** Gitmoji codes without colons. */
+    emojis: string[];
+    /** Hidden groups are matched but left out of the output. */
+    hidden?: boolean;
+};
+export type GroupConfig = GroupConfigItem[];
+export type ChamojiConfig = {
+    groups: GroupConfig;
+    repositoryUrl?: string;
+};
+export type Group = {
+    group: string;
+    label: string;
+    commits: ParsedCommit[];
+};
+export type Release = {
+    /** Tag name, the `--release` version, or `Unreleased`. */
+    version: string;
+    /**
+     * The release's tag. For a `--release` section, the tag it will get
+     * (e.g. `v1.2.0`); null for an unnamed Unreleased section.
+     */
+    tag: string | null;
+    previousTag: string | null;
+    /** `YYYY-MM-DD`, or null for an undated Unreleased section. */
+    date: string | null;
+    bump: SemverBump | null;
+    nextVersion: string | null;
+    groups: Group[];
+};
+export type Changelog = {
+    repositoryUrl?: string;
+    releases: Release[];
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/version.d.ts

@@ -0,0 +1,5 @@
+import type { ParsedCommit, SemverBump } from './types.js';
+/** The release bump implied by `commits`, from gitmoji semver data. */
+export declare function bumpFor(commits: ParsedCommit[]): SemverBump | null;
+/** `current` bumped by `bump`, without a `v` prefix. */
+export declare function nextVersion(current: string | null, bump: SemverBump | null): string | null;

package/dist/version.js

@@ -0,0 +1,22 @@
+import semver from 'semver';
+import { getGitmoji } from './gitmojis.js';
+const RANK = { patch: 1, minor: 2, major: 3 };
+/** The release bump implied by `commits`, from gitmoji semver data. */
+export function bumpFor(commits) {
+    let bump = null;
+    for (const commit of commits) {
+        if (commit.breaking) {
+            return 'major';
+        }
+        const level = commit.gitmoji ? getGitmoji(commit.gitmoji)?.semver : null;
+        if (level && (!bump || RANK[level] > RANK[bump])) {
+            bump = level;
+        }
+    }
+    return bump;
+}
+/** `current` bumped by `bump`, without a `v` prefix. */
+export function nextVersion(current, bump) {
+    return bump ? semver.inc(current ?? '0.0.0', bump) : null;
+}
+//# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@chamoji/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Changelog engine for gitmoji and Conventional Commits",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "dependencies": {
+    "gitmojis": "^3.15.0",
+    "semver": "^7.7.3"
+  },
+  "devDependencies": {
+    "@types/semver": "^7.7.1"
+  },
+  "keywords": [
+    "changelog",
+    "gitmoji",
+    "conventional-commits",
+    "semver",
+    "git"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p ."
+  }
 }