@nghyane/arcane 0.1.0

package/src/commit/changelog/generate.ts

@@ -0,0 +1,110 @@
+import type { Api, AssistantMessage, Model, ToolCall } from "@nghyane/arcane-ai";
+import { completeSimple, validateToolCall } from "@nghyane/arcane-ai";
+import { Type } from "@sinclair/typebox";
+import changelogSystemPrompt from "../../commit/prompts/changelog-system.md" with { type: "text" };
+import changelogUserPrompt from "../../commit/prompts/changelog-user.md" with { type: "text" };
+import type { ChangelogGenerationResult } from "../../commit/types";
+import { renderPromptTemplate } from "../../config/prompt-templates";
+
+const ChangelogTool = {
+	name: "create_changelog_entries",
+	description: "Generate changelog entries grouped by Keep a Changelog categories.",
+	parameters: Type.Object({
+		entries: Type.Record(Type.String(), Type.Array(Type.String())),
+	}),
+};
+
+export interface ChangelogPromptInput {
+	model: Model<Api>;
+	apiKey: string;
+	changelogPath: string;
+	isPackageChangelog: boolean;
+	existingEntries?: string;
+	stat: string;
+	diff: string;
+}
+
+export async function generateChangelogEntries({
+	model,
+	apiKey,
+	changelogPath,
+	isPackageChangelog,
+	existingEntries,
+	stat,
+	diff,
+}: ChangelogPromptInput): Promise<ChangelogGenerationResult> {
+	const prompt = renderPromptTemplate(changelogUserPrompt, {
+		changelog_path: changelogPath,
+		is_package_changelog: isPackageChangelog,
+		existing_entries: existingEntries,
+		stat,
+		diff,
+	});
+	const response = await completeSimple(
+		model,
+		{
+			systemPrompt: renderPromptTemplate(changelogSystemPrompt),
+			messages: [{ role: "user", content: prompt, timestamp: Date.now() }],
+			tools: [ChangelogTool],
+		},
+		{ apiKey, maxTokens: 1200 },
+	);
+
+	const parsed = parseChangelogResponse(response);
+	return { entries: dedupeEntries(parsed.entries) };
+}
+
+function parseChangelogResponse(message: AssistantMessage): ChangelogGenerationResult {
+	const toolCall = extractToolCall(message, "create_changelog_entries");
+	if (toolCall) {
+		const parsed = validateToolCall([ChangelogTool], toolCall) as ChangelogGenerationResult;
+		return { entries: parsed.entries ?? {} };
+	}
+
+	const text = extractTextContent(message);
+	const parsed = parseJsonPayload(text) as ChangelogGenerationResult;
+	return { entries: parsed.entries ?? {} };
+}
+
+function extractToolCall(message: AssistantMessage, name: string): ToolCall | undefined {
+	return message.content.find(content => content.type === "toolCall" && content.name === name) as ToolCall | undefined;
+}
+
+function extractTextContent(message: AssistantMessage): string {
+	return message.content
+		.filter(content => content.type === "text")
+		.map(content => content.text)
+		.join("")
+		.trim();
+}
+
+function parseJsonPayload(text: string): unknown {
+	const trimmed = text.trim();
+	if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+		return JSON.parse(trimmed) as unknown;
+	}
+	const match = trimmed.match(/\{[\s\S]*\}/);
+	if (!match) {
+		throw new Error("No JSON payload found in changelog response");
+	}
+	return JSON.parse(match[0]) as unknown;
+}
+
+function dedupeEntries(entries: Record<string, string[]>): Record<string, string[]> {
+	const result: Record<string, string[]> = {};
+	for (const [category, values] of Object.entries(entries)) {
+		const seen = new Set<string>();
+		const cleaned: string[] = [];
+		for (const value of values) {
+			const trimmed = value.trim().replace(/\.$/, "");
+			const key = trimmed.toLowerCase();
+			if (!trimmed || seen.has(key)) continue;
+			seen.add(key);
+			cleaned.push(trimmed);
+		}
+		if (cleaned.length > 0) {
+			result[category] = cleaned;
+		}
+	}
+	return result;
+}

package/src/commit/changelog/index.ts

@@ -0,0 +1,234 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { Api, Model } from "@nghyane/arcane-ai";
+import { logger } from "@nghyane/arcane-utils";
+import type { ControlledGit } from "../../commit/git";
+import { detectChangelogBoundaries } from "./detect";
+import { generateChangelogEntries } from "./generate";
+import { parseUnreleasedSection } from "./parse";
+
+const CHANGELOG_SECTIONS = ["Breaking Changes", "Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"];
+
+const DEFAULT_MAX_DIFF_CHARS = 120_000;
+
+export interface ChangelogFlowInput {
+	git: ControlledGit;
+	cwd: string;
+	model: Model<Api>;
+	apiKey: string;
+	stagedFiles: string[];
+	dryRun: boolean;
+	maxDiffChars?: number;
+	onProgress?: (message: string) => void;
+}
+
+export interface ChangelogProposalInput {
+	git: ControlledGit;
+	cwd: string;
+	proposals: Array<{
+		path: string;
+		entries: Record<string, string[]>;
+		deletions?: Record<string, string[]>;
+	}>;
+	dryRun: boolean;
+	onProgress?: (message: string) => void;
+}
+
+/**
+ * Update CHANGELOG.md entries for staged changes.
+ */
+export async function runChangelogFlow({
+	git,
+	cwd,
+	model,
+	apiKey,
+	stagedFiles,
+	dryRun,
+	maxDiffChars,
+	onProgress,
+}: ChangelogFlowInput): Promise<string[]> {
+	if (stagedFiles.length === 0) return [];
+	onProgress?.("Detecting changelog boundaries...");
+	const boundaries = await detectChangelogBoundaries(cwd, stagedFiles);
+	if (boundaries.length === 0) return [];
+
+	const updated: string[] = [];
+	for (const boundary of boundaries) {
+		onProgress?.(`Generating entries for ${boundary.changelogPath}…`);
+		const diff = await git.getDiffForFiles(boundary.files, true);
+		if (!diff.trim()) continue;
+		const stat = await git.getStatForFiles(boundary.files, true);
+		const diffForPrompt = truncateDiff(diff, maxDiffChars ?? DEFAULT_MAX_DIFF_CHARS);
+		const changelogContent = await Bun.file(boundary.changelogPath).text();
+		let unreleased: { startLine: number; endLine: number; entries: Record<string, string[]> };
+		try {
+			unreleased = parseUnreleasedSection(changelogContent);
+		} catch (error) {
+			logger.warn("commit changelog parse skipped", { path: boundary.changelogPath, error: String(error) });
+			continue;
+		}
+		const existingEntries = formatExistingEntries(unreleased.entries);
+		const isPackageChangelog = path.resolve(boundary.changelogPath) !== path.resolve(cwd, "CHANGELOG.md");
+		const generated = await generateChangelogEntries({
+			model,
+			apiKey,
+			changelogPath: boundary.changelogPath,
+			isPackageChangelog,
+			existingEntries: existingEntries || undefined,
+			stat,
+			diff: diffForPrompt,
+		});
+		if (Object.keys(generated.entries).length === 0) continue;
+
+		const updatedContent = applyChangelogEntries(changelogContent, unreleased, generated.entries);
+		if (!dryRun) {
+			await Bun.write(boundary.changelogPath, updatedContent);
+			await git.stageFiles([path.relative(cwd, boundary.changelogPath)]);
+		}
+		updated.push(boundary.changelogPath);
+	}
+
+	return updated;
+}
+
+/**
+ * Apply changelog entries provided by the commit agent.
+ */
+export async function applyChangelogProposals({
+	git,
+	cwd,
+	proposals,
+	dryRun,
+	onProgress,
+}: ChangelogProposalInput): Promise<string[]> {
+	const updated: string[] = [];
+	for (const proposal of proposals) {
+		if (
+			Object.keys(proposal.entries).length === 0 &&
+			(!proposal.deletions || Object.keys(proposal.deletions).length === 0)
+		)
+			continue;
+		onProgress?.(`Applying entries for ${proposal.path}…`);
+		const exists = fs.existsSync(proposal.path);
+		if (!exists) {
+			logger.warn("commit changelog path missing", { path: proposal.path });
+			continue;
+		}
+		const changelogContent = await Bun.file(proposal.path).text();
+		let unreleased: { startLine: number; endLine: number; entries: Record<string, string[]> };
+		try {
+			unreleased = parseUnreleasedSection(changelogContent);
+		} catch (error) {
+			logger.warn("commit changelog parse skipped", { path: proposal.path, error: String(error) });
+			continue;
+		}
+		const normalized = normalizeEntries(proposal.entries);
+		const normalizedDeletions = proposal.deletions ? normalizeEntries(proposal.deletions) : undefined;
+		if (Object.keys(normalized).length === 0 && !normalizedDeletions) continue;
+		const updatedContent = applyChangelogEntries(changelogContent, unreleased, normalized, normalizedDeletions);
+		if (!dryRun) {
+			await Bun.write(proposal.path, updatedContent);
+			await git.stageFiles([path.relative(cwd, proposal.path)]);
+		}
+		updated.push(proposal.path);
+	}
+
+	return updated;
+}
+
+function truncateDiff(diff: string, maxChars: number): string {
+	if (diff.length <= maxChars) return diff;
+	return `${diff.slice(0, maxChars)}\n... (truncated)`;
+}
+
+function formatExistingEntries(entries: Record<string, string[]>): string {
+	const lines: string[] = [];
+	for (const section of CHANGELOG_SECTIONS) {
+		const values = entries[section] ?? [];
+		if (values.length === 0) continue;
+		lines.push(`${section}:`);
+		for (const value of values) {
+			lines.push(`- ${value}`);
+		}
+	}
+	return lines.join("\n");
+}
+
+function applyChangelogEntries(
+	content: string,
+	unreleased: { startLine: number; endLine: number; entries: Record<string, string[]> },
+	entries: Record<string, string[]>,
+	deletions?: Record<string, string[]>,
+): string {
+	const lines = content.split("\n");
+	const before = lines.slice(0, unreleased.startLine + 1);
+	const after = lines.slice(unreleased.endLine);
+
+	let base = unreleased.entries;
+	if (deletions) {
+		base = applyDeletions(base, deletions);
+	}
+	const merged = mergeEntries(base, entries);
+	const sectionLines = renderUnreleasedSections(merged);
+	return [...before, ...sectionLines, ...after].join("\n");
+}
+
+function applyDeletions(
+	existing: Record<string, string[]>,
+	deletions: Record<string, string[]>,
+): Record<string, string[]> {
+	const result: Record<string, string[]> = {};
+	for (const [section, items] of Object.entries(existing)) {
+		const toDelete = new Set((deletions[section] ?? []).map(d => d.toLowerCase()));
+		const filtered = items.filter(item => !toDelete.has(item.toLowerCase()));
+		if (filtered.length > 0) {
+			result[section] = filtered;
+		}
+	}
+	return result;
+}
+
+function mergeEntries(
+	existing: Record<string, string[]>,
+	incoming: Record<string, string[]>,
+): Record<string, string[]> {
+	const merged: Record<string, string[]> = { ...existing };
+	for (const [section, items] of Object.entries(incoming)) {
+		const current = merged[section] ?? [];
+		const lower = new Set(current.map(item => item.toLowerCase()));
+		for (const item of items) {
+			if (!lower.has(item.toLowerCase())) {
+				current.push(item);
+			}
+		}
+		merged[section] = current;
+	}
+	return merged;
+}
+
+function renderUnreleasedSections(entries: Record<string, string[]>): string[] {
+	const lines: string[] = [""];
+	for (const section of CHANGELOG_SECTIONS) {
+		const items = entries[section] ?? [];
+		if (items.length === 0) continue;
+		lines.push(`### ${section}`);
+		for (const item of items) {
+			lines.push(`- ${item}`);
+		}
+		lines.push("");
+	}
+	if (lines[lines.length - 1] === "") {
+		lines.pop();
+	}
+	return lines;
+}
+
+function normalizeEntries(entries: Record<string, string[]>): Record<string, string[]> {
+	const result: Record<string, string[]> = {};
+	for (const [section, items] of Object.entries(entries)) {
+		const trimmed = items.map(item => item.trim().replace(/\.$/, "")).filter(item => item.length > 0);
+		if (trimmed.length === 0) continue;
+		result[section] = Array.from(new Set(trimmed.map(item => item.trim())));
+	}
+	return result;
+}

package/src/commit/changelog/parse.ts

@@ -0,0 +1,44 @@
+import type { UnreleasedSection } from "../../commit/types";
+
+const UNRELEASED_PATTERN = /^##\s+\[?Unreleased\]?/i;
+const SECTION_PATTERN = /^###\s+(.*)$/;
+
+export function parseUnreleasedSection(content: string): UnreleasedSection {
+	const lines = content.split("\n");
+	const startIndex = lines.findIndex(line => UNRELEASED_PATTERN.test(line.trim()));
+	if (startIndex === -1) {
+		throw new Error("No [Unreleased] section found in changelog");
+	}
+
+	let endIndex = lines.length;
+	for (let i = startIndex + 1; i < lines.length; i += 1) {
+		if (lines[i]?.startsWith("## ")) {
+			endIndex = i;
+			break;
+		}
+	}
+
+	const sectionLines = lines.slice(startIndex + 1, endIndex);
+	const entries: Record<string, string[]> = {};
+	let currentSection: string | null = null;
+	for (const line of sectionLines) {
+		const sectionMatch = line.match(SECTION_PATTERN);
+		if (sectionMatch) {
+			currentSection = sectionMatch[1]?.trim() || null;
+			if (currentSection) {
+				entries[currentSection] = entries[currentSection] ?? [];
+			}
+			continue;
+		}
+
+		if (!currentSection) continue;
+		const trimmed = line.trim();
+		if (!trimmed.startsWith("-")) continue;
+		const entry = trimmed.replace(/^[-*]\s*/, "");
+		if (entry) {
+			entries[currentSection]?.push(entry);
+		}
+	}
+
+	return { startLine: startIndex, endLine: endIndex, entries };
+}

package/src/commit/cli.ts

@@ -0,0 +1,93 @@
+import chalk from "chalk";
+import type { CommitCommandArgs } from "./types";
+
+const FLAG_ALIASES = new Map<string, string>([
+	["-c", "--context"],
+	["-m", "--model"],
+]);
+
+export function parseCommitArgs(args: string[]): CommitCommandArgs | undefined {
+	if (args.length === 0 || args[0] !== "commit") {
+		return undefined;
+	}
+
+	const result: CommitCommandArgs = {
+		push: false,
+		dryRun: false,
+		noChangelog: false,
+	};
+
+	for (let i = 1; i < args.length; i += 1) {
+		const raw = args[i] ?? "";
+		const flag = FLAG_ALIASES.get(raw) ?? raw;
+		switch (flag) {
+			case "--push":
+				result.push = true;
+				break;
+			case "--dry-run":
+				result.dryRun = true;
+				break;
+			case "--no-changelog":
+				result.noChangelog = true;
+				break;
+			case "--legacy":
+				result.legacy = true;
+				break;
+			case "--context": {
+				const value = args[i + 1];
+				if (!value || value.startsWith("-")) {
+					writeStderr(chalk.red("Error: --context requires a value"));
+					process.exit(1);
+				}
+				result.context = value;
+				i += 1;
+				break;
+			}
+			case "--model": {
+				const value = args[i + 1];
+				if (!value || value.startsWith("-")) {
+					writeStderr(chalk.red("Error: --model requires a value"));
+					process.exit(1);
+				}
+				result.model = value;
+				i += 1;
+				break;
+			}
+			case "--help":
+			case "-h":
+				break;
+			default:
+				if (flag.startsWith("-")) {
+					writeStderr(chalk.red(`Error: Unknown flag ${flag}`));
+					process.exit(1);
+				}
+		}
+	}
+
+	return result;
+}
+
+export function printCommitHelp(): void {
+	const lines = [
+		"Usage:",
+		"  arcane commit [options]",
+		"",
+		"Options:",
+		"  --push           Push after committing",
+		"  --dry-run        Preview without committing",
+		"  --no-changelog   Skip changelog updates",
+		"  --legacy         Use legacy deterministic pipeline",
+		"  --context, -c    Additional context for the model",
+		"  --model, -m      Override model selection",
+		"  --help, -h       Show this help message",
+	];
+	writeStdout(lines.join("\n"));
+}
+
+function writeStdout(message: string): void {
+	process.stdout.write(`${message}\n`);
+}
+
+function writeStderr(message: string): void {
+	process.stderr.write(`${message}\n`);
+}

package/src/commit/git/diff.ts

@@ -0,0 +1,148 @@
+import type { DiffHunk, FileDiff, FileHunks, NumstatEntry } from "../../commit/types";
+
+export function parseNumstat(output: string): NumstatEntry[] {
+	const entries: NumstatEntry[] = [];
+	for (const line of output.split("\n")) {
+		if (!line.trim()) continue;
+		const parts = line.split("\t");
+		if (parts.length < 3) continue;
+		const [addedRaw, deletedRaw, pathRaw] = parts;
+		const additions = Number.parseInt(addedRaw, 10);
+		const deletions = Number.parseInt(deletedRaw, 10);
+		const path = extractPathFromRename(pathRaw);
+		entries.push({
+			path,
+			additions: Number.isNaN(additions) ? 0 : additions,
+			deletions: Number.isNaN(deletions) ? 0 : deletions,
+		});
+	}
+	return entries;
+}
+
+export function parseFileDiffs(diff: string): FileDiff[] {
+	const sections: FileDiff[] = [];
+	const parts = diff.split("\ndiff --git ");
+	for (let index = 0; index < parts.length; index += 1) {
+		const part = index === 0 ? parts[index] : `diff --git ${parts[index]}`;
+		if (!part.trim()) continue;
+		const lines = part.split("\n");
+		const header = lines[0] ?? "";
+		const match = header.match(/diff --git a\/(.+?) b\/(.+)$/);
+		if (!match) continue;
+		const filename = match[2];
+		const content = part;
+		const isBinary = lines.some(line => line.startsWith("Binary files "));
+		let additions = 0;
+		let deletions = 0;
+		for (const line of lines) {
+			if (line.startsWith("+++") || line.startsWith("---")) continue;
+			if (line.startsWith("+")) additions += 1;
+			else if (line.startsWith("-")) deletions += 1;
+		}
+		sections.push({
+			filename,
+			content,
+			additions,
+			deletions,
+			isBinary,
+		});
+	}
+	return sections;
+}
+
+export function parseDiffHunks(diff: string): FileHunks[] {
+	const files = parseFileDiffs(diff);
+	return files.map(file => parseFileHunks(file));
+}
+
+export function parseFileHunks(fileDiff: FileDiff): FileHunks {
+	if (fileDiff.isBinary) {
+		return { filename: fileDiff.filename, isBinary: true, hunks: [] };
+	}
+
+	const lines = fileDiff.content.split("\n");
+	const hunks: DiffHunk[] = [];
+	let current: DiffHunk | null = null;
+	let buffer: string[] = [];
+	let index = 0;
+
+	for (const line of lines) {
+		if (line.startsWith("@@")) {
+			if (current) {
+				current.content = buffer.join("\n");
+				hunks.push(current);
+			}
+			const headerData = parseHunkHeader(line);
+			current = {
+				index,
+				header: line,
+				oldStart: headerData.oldStart,
+				oldLines: headerData.oldLines,
+				newStart: headerData.newStart,
+				newLines: headerData.newLines,
+				content: "",
+			};
+			buffer = [line];
+			index += 1;
+			continue;
+		}
+		if (current) {
+			buffer.push(line);
+		}
+	}
+
+	if (current) {
+		current.content = buffer.join("\n");
+		hunks.push(current);
+	}
+
+	return {
+		filename: fileDiff.filename,
+		isBinary: fileDiff.isBinary,
+		hunks,
+	};
+}
+
+function extractPathFromRename(pathPart: string): string {
+	const braceStart = pathPart.indexOf("{");
+	if (braceStart !== -1) {
+		const arrowPos = pathPart.indexOf(" => ", braceStart);
+		if (arrowPos !== -1) {
+			const braceEnd = pathPart.indexOf("}", arrowPos);
+			if (braceEnd !== -1) {
+				const prefix = pathPart.slice(0, braceStart);
+				const newName = pathPart.slice(arrowPos + 4, braceEnd).trim();
+				return `${prefix}${newName}`;
+			}
+		}
+	}
+
+	if (pathPart.includes(" => ")) {
+		const parts = pathPart.split(" => ");
+		return parts[1]?.trim() ?? pathPart.trim();
+	}
+
+	return pathPart.trim();
+}
+
+function parseHunkHeader(line: string): {
+	oldStart: number;
+	oldLines: number;
+	newStart: number;
+	newLines: number;
+} {
+	const match = line.match(/@@\s-([0-9]+)(?:,([0-9]+))?\s\+([0-9]+)(?:,([0-9]+))?\s@@/);
+	if (!match) {
+		return { oldStart: 0, oldLines: 0, newStart: 0, newLines: 0 };
+	}
+	const oldStart = Number.parseInt(match[1] ?? "0", 10);
+	const oldLines = Number.parseInt(match[2] ?? "1", 10);
+	const newStart = Number.parseInt(match[3] ?? "0", 10);
+	const newLines = Number.parseInt(match[4] ?? "1", 10);
+	return {
+		oldStart: Number.isNaN(oldStart) ? 0 : oldStart,
+		oldLines: Number.isNaN(oldLines) ? 0 : oldLines,
+		newStart: Number.isNaN(newStart) ? 0 : newStart,
+		newLines: Number.isNaN(newLines) ? 0 : newLines,
+	};
+}

package/src/commit/git/errors.ts

@@ -0,0 +1,9 @@
+export class GitError extends Error {
+	constructor(
+		readonly command: string,
+		readonly stderr: string,
+	) {
+		super(`${command} failed: ${stderr || "unknown error"}`);
+		this.name = "GitError";
+	}
+}