@nghyane/arcane 0.1.0

package/src/commit/analysis/conventional.ts

@@ -0,0 +1,165 @@
+import type { Api, AssistantMessage, Model, ToolCall } from "@nghyane/arcane-ai";
+import { completeSimple, validateToolCall } from "@nghyane/arcane-ai";
+import { Type } from "@sinclair/typebox";
+import analysisSystemPrompt from "../../commit/prompts/analysis-system.md" with { type: "text" };
+import analysisUserPrompt from "../../commit/prompts/analysis-user.md" with { type: "text" };
+import type { ChangelogCategory, ConventionalAnalysis, ConventionalDetail } from "../../commit/types";
+import { renderPromptTemplate } from "../../config/prompt-templates";
+
+const ConventionalAnalysisTool = {
+	name: "create_conventional_analysis",
+	description: "Analyze a diff and return conventional commit classification.",
+	parameters: Type.Object({
+		type: Type.Union([
+			Type.Literal("feat"),
+			Type.Literal("fix"),
+			Type.Literal("refactor"),
+			Type.Literal("docs"),
+			Type.Literal("test"),
+			Type.Literal("chore"),
+			Type.Literal("style"),
+			Type.Literal("perf"),
+			Type.Literal("build"),
+			Type.Literal("ci"),
+			Type.Literal("revert"),
+		]),
+		scope: Type.Union([Type.String(), Type.Null()]),
+		details: Type.Array(
+			Type.Object({
+				text: Type.String(),
+				changelog_category: Type.Optional(
+					Type.Union([
+						Type.Literal("Added"),
+						Type.Literal("Changed"),
+						Type.Literal("Fixed"),
+						Type.Literal("Deprecated"),
+						Type.Literal("Removed"),
+						Type.Literal("Security"),
+						Type.Literal("Breaking Changes"),
+					]),
+				),
+				user_visible: Type.Optional(Type.Boolean()),
+			}),
+		),
+		issue_refs: Type.Array(Type.String()),
+	}),
+};
+
+export interface ConventionalAnalysisInput {
+	model: Model<Api>;
+	apiKey: string;
+	contextFiles?: Array<{ path: string; content: string }>;
+	userContext?: string;
+	typesDescription?: string;
+	recentCommits?: string[];
+	scopeCandidates: string;
+	stat: string;
+	diff: string;
+}
+
+/**
+ * Generate conventional analysis data from a diff and metadata.
+ */
+export async function generateConventionalAnalysis({
+	model,
+	apiKey,
+	contextFiles,
+	userContext,
+	typesDescription,
+	recentCommits,
+	scopeCandidates,
+	stat,
+	diff,
+}: ConventionalAnalysisInput): Promise<ConventionalAnalysis> {
+	const prompt = renderPromptTemplate(analysisUserPrompt, {
+		context_files: contextFiles && contextFiles.length > 0 ? contextFiles : undefined,
+		user_context: userContext,
+		types_description: typesDescription,
+		recent_commits: recentCommits?.join("\n"),
+		scope_candidates: scopeCandidates,
+		stat,
+		diff,
+	});
+
+	const response = await completeSimple(
+		model,
+		{
+			systemPrompt: renderPromptTemplate(analysisSystemPrompt),
+			messages: [{ role: "user", content: prompt, timestamp: Date.now() }],
+			tools: [ConventionalAnalysisTool],
+		},
+		{ apiKey, maxTokens: 2400 },
+	);
+
+	return parseAnalysisFromResponse(response);
+}
+
+function parseAnalysisFromResponse(message: AssistantMessage): ConventionalAnalysis {
+	const toolCall = extractToolCall(message, "create_conventional_analysis");
+	if (toolCall) {
+		const parsed = validateToolCall([ConventionalAnalysisTool], toolCall) as {
+			type: ConventionalAnalysis["type"];
+			scope: string | null;
+			details: Array<{ text: string; changelog_category?: ChangelogCategory; user_visible?: boolean }>;
+			issue_refs: string[];
+		};
+		return normalizeAnalysis(parsed);
+	}
+
+	const text = extractTextContent(message);
+	const parsed = parseJsonPayload(text) as {
+		type: ConventionalAnalysis["type"];
+		scope: string | null;
+		details: Array<{ text: string; changelog_category?: ChangelogCategory; user_visible?: boolean }>;
+		issue_refs: string[];
+	};
+	return normalizeAnalysis(parsed);
+}
+
+function normalizeAnalysis(parsed: {
+	type: ConventionalAnalysis["type"];
+	scope: string | null;
+	details: Array<{ text: string; changelog_category?: ChangelogCategory; user_visible?: boolean }>;
+	issue_refs: string[];
+}): ConventionalAnalysis {
+	const details: ConventionalDetail[] = parsed.details.map(detail => ({
+		text: detail.text.trim(),
+		changelogCategory: detail.user_visible ? detail.changelog_category : undefined,
+		userVisible: detail.user_visible ?? false,
+	}));
+	return {
+		type: parsed.type,
+		scope: parsed.scope?.trim() || null,
+		details,
+		issueRefs: parsed.issue_refs ?? [],
+	};
+}
+
+function extractToolCall(message: AssistantMessage, name: string): ToolCall | undefined {
+	for (const content of message.content) {
+		if (content.type === "toolCall" && content.name === name) {
+			return content;
+		}
+	}
+	return 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 analysis response");
+	}
+	return JSON.parse(match[0]) as unknown;
+}

package/src/commit/analysis/index.ts

@@ -0,0 +1,4 @@
+export { generateConventionalAnalysis } from "./conventional";
+export { extractScopeCandidates } from "./scope";
+export { generateSummary, stripTypePrefix } from "./summary";
+export { validateAnalysis, validateScope, validateSummary } from "./validation";

package/src/commit/analysis/scope.ts

@@ -0,0 +1,242 @@
+import type { NumstatEntry } from "../../commit/types";
+import { isExcludedFile } from "../../commit/utils/exclusions";
+
+interface ScopeCandidate {
+	path: string;
+	percentage: number;
+	confidence: number;
+}
+
+const PLACEHOLDER_DIRS = new Set([
+	"src",
+	"lib",
+	"bin",
+	"crates",
+	"benches",
+	"examples",
+	"internal",
+	"pkg",
+	"include",
+	"tests",
+	"test",
+	"docs",
+	"packages",
+	"modules",
+]);
+
+const SKIP_DIRS = new Set(["test", "tests", "benches", "examples", "target", "build", "node_modules", ".github"]);
+
+export interface ScopeCandidatesResult {
+	scopeCandidates: string;
+	isWide: boolean;
+}
+
+export function extractScopeCandidates(numstat: NumstatEntry[]): ScopeCandidatesResult {
+	const componentLines = new Map<string, number>();
+	const paths: string[] = [];
+	const distinctRoots = new Set<string>();
+	let totalLines = 0;
+
+	for (const entry of numstat) {
+		const linesChanged = entry.additions + entry.deletions;
+		if (linesChanged === 0) continue;
+		const normalizedPath = normalizePathForScope(entry.path);
+		if (isExcludedFile(normalizedPath)) continue;
+		paths.push(normalizedPath);
+		const root = extractTopLevelRoot(normalizedPath);
+		if (root) {
+			distinctRoots.add(root);
+		}
+		totalLines += linesChanged;
+		const components = extractComponentsFromPath(normalizedPath);
+		for (const component of components) {
+			if (component.split("/").some(segment => segment.includes("."))) {
+				continue;
+			}
+			componentLines.set(component, (componentLines.get(component) ?? 0) + linesChanged);
+		}
+	}
+
+	if (totalLines === 0) {
+		return { scopeCandidates: "(none - no measurable changes)", isWide: false };
+	}
+
+	const candidates = buildScopeCandidates(componentLines, totalLines);
+	const isWide = isWideChange(candidates, 0.6, distinctRoots.size);
+	if (isWide) {
+		const pattern = analyzeWideChange(paths);
+		if (pattern) {
+			return { scopeCandidates: `(cross-cutting: ${pattern})`, isWide: true };
+		}
+		return { scopeCandidates: "(none - multi-component change)", isWide: true };
+	}
+
+	const suggestionParts: string[] = [];
+	for (const candidate of candidates.slice(0, 5)) {
+		if (candidate.percentage < 10) continue;
+		const confidenceLabel = candidate.path.includes("/")
+			? candidate.percentage > 60
+				? "high confidence"
+				: "moderate confidence"
+			: "high confidence";
+		suggestionParts.push(`${candidate.path} (${candidate.percentage.toFixed(0)}%, ${confidenceLabel})`);
+	}
+
+	const scopeCandidates =
+		suggestionParts.length === 0
+			? "(none - unclear component)"
+			: `${suggestionParts.join(", ")}\nPrefer 2-segment scopes marked 'high confidence'`;
+
+	return { scopeCandidates, isWide: false };
+}
+
+function buildScopeCandidates(componentLines: Map<string, number>, totalLines: number): ScopeCandidate[] {
+	const candidates: ScopeCandidate[] = [];
+	for (const [path, lines] of componentLines.entries()) {
+		if (!path.includes("/") && PLACEHOLDER_DIRS.has(path)) continue;
+		const root = path.split("/")[0] ?? "";
+		if (PLACEHOLDER_DIRS.has(root)) continue;
+		const percentage = (lines / totalLines) * 100;
+		const isTwoSegment = path.includes("/");
+		const confidence = isTwoSegment ? (percentage > 60 ? percentage * 1.2 : percentage * 0.8) : percentage;
+		candidates.push({ path, percentage, confidence });
+	}
+	return candidates.sort((a, b) => b.confidence - a.confidence);
+}
+
+function isWideChange(candidates: ScopeCandidate[], threshold: number, distinctRoots: number): boolean {
+	if (distinctRoots >= 3) return true;
+	const top = candidates[0];
+	if (!top) return false;
+	return top.percentage / 100 < threshold;
+}
+
+function extractComponentsFromPath(path: string): string[] {
+	const segments = path.split("/");
+	const meaningful: string[] = [];
+
+	const stripExt = (segment: string): string => {
+		const index = segment.lastIndexOf(".");
+		return index > 0 ? segment.slice(0, index) : segment;
+	};
+
+	const isFile = (segment: string): boolean => {
+		return segment.includes(".") && !segment.startsWith(".") && segment.lastIndexOf(".") > 0;
+	};
+
+	for (let index = 0; index < segments.length; index += 1) {
+		const segment = segments[index] ?? "";
+		if (PLACEHOLDER_DIRS.has(segment) && segments.length > index + 1) {
+			continue;
+		}
+		if (isFile(segment)) continue;
+		if (SKIP_DIRS.has(segment)) continue;
+
+		const stripped = stripExt(segment);
+		if (stripped && !stripped.startsWith(".")) {
+			meaningful.push(stripped);
+		}
+	}
+
+	const components: string[] = [];
+	if (meaningful.length > 0) {
+		components.push(meaningful[0]!);
+		if (meaningful.length >= 2) {
+			components.push(`${meaningful[0]}/${meaningful[1]}`);
+		}
+	}
+
+	return components;
+}
+
+function extractTopLevelRoot(path: string): string | null {
+	const segments = path.split("/").filter(segment => segment.length > 0);
+	if (segments.length === 0) return null;
+	if (segments.length === 1) {
+		return segments[0]!.startsWith(".") ? null : "(root)";
+	}
+
+	for (let index = 0; index < segments.length; index += 1) {
+		const segment = segments[index] ?? "";
+		if (PLACEHOLDER_DIRS.has(segment) && segments.length > index + 1) {
+			continue;
+		}
+		if (SKIP_DIRS.has(segment)) continue;
+		if (segment.startsWith(".")) continue;
+		return segment;
+	}
+
+	return null;
+}
+
+function normalizePathForScope(path: string): string {
+	const braceStart = path.indexOf("{");
+	if (braceStart !== -1) {
+		const arrowPos = path.indexOf(" => ", braceStart);
+		if (arrowPos !== -1) {
+			const braceEnd = path.indexOf("}", arrowPos);
+			if (braceEnd !== -1) {
+				const prefix = path.slice(0, braceStart);
+				const newName = path.slice(arrowPos + 4, braceEnd).trim();
+				return `${prefix}${newName}`;
+			}
+		}
+	}
+
+	if (path.includes(" => ")) {
+		const parts = path.split(" => ");
+		return parts[1]?.trim() ?? path.trim();
+	}
+
+	return path.trim();
+}
+
+function analyzeWideChange(paths: string[]): string | null {
+	if (paths.length === 0) return null;
+	const total = paths.length;
+	let mdCount = 0;
+	let testCount = 0;
+	let configCount = 0;
+	let hasCargoToml = false;
+	let hasPackageJson = false;
+	let errorKeywords = 0;
+	let typeKeywords = 0;
+
+	for (const path of paths) {
+		const lowerPath = path.toLowerCase();
+		if (lowerPath.endsWith(".md")) {
+			mdCount += 1;
+		}
+		if (lowerPath.includes("/test") || lowerPath.includes("_test.")) {
+			testCount += 1;
+		}
+		if (
+			lowerPath.endsWith(".toml") ||
+			lowerPath.endsWith(".yaml") ||
+			lowerPath.endsWith(".yml") ||
+			lowerPath.endsWith(".json")
+		) {
+			configCount += 1;
+		}
+		if (path.includes("Cargo.toml")) {
+			hasCargoToml = true;
+		}
+		if (path.includes("package.json")) {
+			hasPackageJson = true;
+		}
+		if (lowerPath.includes("error") || lowerPath.includes("result") || lowerPath.includes("err")) {
+			errorKeywords += 1;
+		}
+		if (lowerPath.includes("type") || lowerPath.includes("struct") || lowerPath.includes("enum")) {
+			typeKeywords += 1;
+		}
+	}
+
+	if (hasCargoToml || hasPackageJson) return "deps";
+	if ((mdCount * 100) / total > 70) return "docs";
+	if ((testCount * 100) / total > 60) return "tests";
+	if ((errorKeywords * 100) / total > 40) return "error-handling";
+	if ((typeKeywords * 100) / total > 40) return "type-refactor";
+	if ((configCount * 100) / total > 50) return "config";
+	return null;
+}

package/src/commit/analysis/summary.ts

@@ -0,0 +1,112 @@
+import type { Api, AssistantMessage, Model, ToolCall } from "@nghyane/arcane-ai";
+import { completeSimple, validateToolCall } from "@nghyane/arcane-ai";
+import { Type } from "@sinclair/typebox";
+import summarySystemPrompt from "../../commit/prompts/summary-system.md" with { type: "text" };
+import summaryUserPrompt from "../../commit/prompts/summary-user.md" with { type: "text" };
+import type { CommitSummary } from "../../commit/types";
+import { renderPromptTemplate } from "../../config/prompt-templates";
+
+const SummaryTool = {
+	name: "create_commit_summary",
+	description: "Generate the summary line for a conventional commit message.",
+	parameters: Type.Object({
+		summary: Type.String(),
+	}),
+};
+
+export interface SummaryInput {
+	model: Model<Api>;
+	apiKey: string;
+	commitType: string;
+	scope: string | null;
+	details: string[];
+	stat: string;
+	maxChars: number;
+	userContext?: string;
+}
+
+/**
+ * Generate a commit summary line for the conventional commit header.
+ */
+export async function generateSummary({
+	model,
+	apiKey,
+	commitType,
+	scope,
+	details,
+	stat,
+	maxChars,
+	userContext,
+}: SummaryInput): Promise<CommitSummary> {
+	const systemPrompt = renderSummaryPrompt({ commitType, scope, maxChars });
+	const userPrompt = renderPromptTemplate(summaryUserPrompt, {
+		user_context: userContext,
+		details: details.join("\n"),
+		stat,
+	});
+
+	const response = await completeSimple(
+		model,
+		{
+			systemPrompt,
+			messages: [{ role: "user", content: userPrompt, timestamp: Date.now() }],
+			tools: [SummaryTool],
+		},
+		{ apiKey, maxTokens: 200 },
+	);
+
+	return parseSummaryFromResponse(response, commitType, scope);
+}
+
+function renderSummaryPrompt({
+	commitType,
+	scope,
+	maxChars,
+}: {
+	commitType: string;
+	scope: string | null;
+	maxChars: number;
+}): string {
+	const scopePrefix = scope ? `(${scope})` : "";
+	return renderPromptTemplate(summarySystemPrompt, {
+		commit_type: commitType,
+		scope_prefix: scopePrefix,
+		chars: String(maxChars),
+	});
+}
+
+function parseSummaryFromResponse(message: AssistantMessage, commitType: string, scope: string | null): CommitSummary {
+	const toolCall = extractToolCall(message, "create_commit_summary");
+	if (toolCall) {
+		const parsed = validateToolCall([SummaryTool], toolCall) as { summary: string };
+		return { summary: stripTypePrefix(parsed.summary, commitType, scope) };
+	}
+	const text = extractTextContent(message);
+	return { summary: stripTypePrefix(text, commitType, scope) };
+}
+
+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();
+}
+
+export function stripTypePrefix(summary: string, commitType: string, scope: string | null): string {
+	const trimmed = summary.trim();
+	const scopePart = scope ? `(${scope})` : "";
+	const withScope = `${commitType}${scopePart}: `;
+	if (trimmed.startsWith(withScope)) {
+		return trimmed.slice(withScope.length).trim();
+	}
+	const withoutScope = `${commitType}: `;
+	if (trimmed.startsWith(withoutScope)) {
+		return trimmed.slice(withoutScope.length).trim();
+	}
+	return trimmed;
+}

package/src/commit/analysis/validation.ts

@@ -0,0 +1,66 @@
+import type { ConventionalAnalysis } from "../../commit/types";
+
+export interface ValidationResult {
+	valid: boolean;
+	errors: string[];
+}
+
+export function validateSummary(summary: string, maxChars: number): ValidationResult {
+	const errors: string[] = [];
+	if (!summary.trim()) {
+		errors.push("Summary is empty");
+	}
+	if (summary.length > maxChars) {
+		errors.push(`Summary exceeds ${maxChars} characters`);
+	}
+	if (summary.trimEnd().endsWith(".")) {
+		errors.push("Summary must not end with a period");
+	}
+	if (summary.includes("\n")) {
+		errors.push("Summary must be a single line");
+	}
+	return { valid: errors.length === 0, errors };
+}
+
+export function validateScope(scope: string | null): ValidationResult {
+	if (!scope) return { valid: true, errors: [] };
+	const errors: string[] = [];
+	const segments = scope.split("/");
+	if (segments.length > 2) {
+		errors.push("Scope may contain at most two segments");
+	}
+	for (const segment of segments) {
+		if (!segment) {
+			errors.push("Scope segments cannot be empty");
+			continue;
+		}
+		if (segment !== segment.toLowerCase()) {
+			errors.push("Scope must be lowercase");
+		}
+		if (!/^[a-z0-9][a-z0-9-_]*$/.test(segment)) {
+			errors.push(`Scope segment has invalid characters: ${segment}`);
+		}
+	}
+	return { valid: errors.length === 0, errors };
+}
+
+export function validateAnalysis(analysis: ConventionalAnalysis): ValidationResult {
+	const errors: string[] = [];
+	const scopeResult = validateScope(analysis.scope);
+	if (!scopeResult.valid) {
+		errors.push(...scopeResult.errors);
+	}
+	for (const detail of analysis.details) {
+		if (!detail.text.trim()) {
+			errors.push("Detail text is empty");
+			continue;
+		}
+		if (!detail.text.trim().endsWith(".")) {
+			errors.push(`Detail must end with a period: ${detail.text}`);
+		}
+		if (detail.text.length > 120) {
+			errors.push(`Detail exceeds 120 characters: ${detail.text}`);
+		}
+	}
+	return { valid: errors.length === 0, errors };
+}

package/src/commit/changelog/detect.ts

@@ -0,0 +1,37 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ChangelogBoundary } from "../../commit/types";
+
+const CHANGELOG_NAME = "CHANGELOG.md";
+
+export async function detectChangelogBoundaries(cwd: string, stagedFiles: string[]): Promise<ChangelogBoundary[]> {
+	const boundaries = new Map<string, string[]>();
+	for (const file of stagedFiles) {
+		if (file.toLowerCase().endsWith("changelog.md")) continue;
+		const changelogPath = await findNearestChangelog(cwd, file);
+		if (!changelogPath) continue;
+		const list = boundaries.get(changelogPath) ?? [];
+		list.push(file);
+		boundaries.set(changelogPath, list);
+	}
+
+	return Array.from(boundaries.entries()).map(([changelogPath, files]) => ({
+		changelogPath,
+		files,
+	}));
+}
+
+async function findNearestChangelog(cwd: string, filePath: string): Promise<string | null> {
+	let current = path.resolve(cwd, path.dirname(filePath));
+	const root = path.resolve(cwd);
+	while (true) {
+		const candidate = path.resolve(current, CHANGELOG_NAME);
+		if (fs.existsSync(candidate)) {
+			return candidate;
+		}
+		if (current === root) return null;
+		const parent = path.dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+}