@nghyane/arcane 0.1.0

package/src/commit/agentic/tools/recent-commits.ts

@@ -0,0 +1,81 @@
+import { Type } from "@sinclair/typebox";
+import type { ControlledGit } from "../../../commit/git";
+import type { CustomTool } from "../../../extensibility/custom-tools/types";
+
+const recentCommitsSchema = Type.Object({
+	count: Type.Optional(Type.Number({ description: "Number of commits to fetch", minimum: 1, maximum: 50 })),
+});
+
+interface RecentCommitStats {
+	scopeUsagePercent: number;
+	commonVerbs: Record<string, number>;
+	summaryLength: { min: number; max: number; average: number };
+	lowercaseSummaryPercent: number;
+	topScopes: Record<string, number>;
+}
+
+function extractSummary(subject: string): string {
+	const match = subject.match(/^[a-z]+(?:\([^)]+\))?:\s+(.*)$/i);
+	if (match?.[1]) return match[1].trim();
+	return subject.trim();
+}
+
+function extractScope(subject: string): string | null {
+	const match = subject.match(/^[a-z]+\(([^)]+)\):/i);
+	return match?.[1]?.trim() ?? null;
+}
+
+export function createRecentCommitsTool(git: ControlledGit): CustomTool<typeof recentCommitsSchema> {
+	return {
+		name: "recent_commits",
+		label: "Recent Commits",
+		description: "Return recent commit subjects with style statistics.",
+		parameters: recentCommitsSchema,
+		async execute(_toolCallId, params) {
+			const count = params.count ?? 8;
+			const commits = await git.getRecentCommits(count);
+			const verbs: Record<string, number> = {};
+			const scopes: Record<string, number> = {};
+			const lengths: number[] = [];
+			let scopeCount = 0;
+			let lowercaseCount = 0;
+
+			for (const subject of commits) {
+				const summary = extractSummary(subject);
+				const scope = extractScope(subject);
+				if (scope) {
+					scopeCount += 1;
+					scopes[scope] = (scopes[scope] ?? 0) + 1;
+				}
+				if (summary[0] && summary[0] === summary[0].toLowerCase()) {
+					lowercaseCount += 1;
+				}
+				const firstWord = summary.split(/\s+/)[0]?.toLowerCase();
+				if (firstWord) {
+					verbs[firstWord] = (verbs[firstWord] ?? 0) + 1;
+				}
+				lengths.push(summary.length);
+			}
+
+			const min = lengths.length > 0 ? Math.min(...lengths) : 0;
+			const max = lengths.length > 0 ? Math.max(...lengths) : 0;
+			const average = lengths.length > 0 ? lengths.reduce((sum, value) => sum + value, 0) / lengths.length : 0;
+			const scopeUsagePercent = commits.length > 0 ? Math.round((scopeCount / commits.length) * 100) : 0;
+			const lowercaseSummaryPercent = commits.length > 0 ? Math.round((lowercaseCount / commits.length) * 100) : 0;
+
+			const stats: RecentCommitStats = {
+				scopeUsagePercent,
+				commonVerbs: verbs,
+				summaryLength: { min, max, average: Number(average.toFixed(1)) },
+				lowercaseSummaryPercent,
+				topScopes: scopes,
+			};
+
+			const payload = { commits, stats };
+			return {
+				content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+				details: payload,
+			};
+		},
+	};
+}

package/src/commit/agentic/tools/split-commit.ts

@@ -0,0 +1,280 @@
+import { Type } from "@sinclair/typebox";
+import type { CommitAgentState, SplitCommitGroup, SplitCommitPlan } from "../../../commit/agentic/state";
+import { computeDependencyOrder } from "../../../commit/agentic/topo-sort";
+import {
+	capDetails,
+	MAX_DETAIL_ITEMS,
+	normalizeSummary,
+	SUMMARY_MAX_CHARS,
+	validateSummaryRules,
+	validateTypeConsistency,
+} from "../../../commit/agentic/validation";
+import { validateScope } from "../../../commit/analysis/validation";
+import type { ControlledGit } from "../../../commit/git";
+import type { ConventionalDetail } from "../../../commit/types";
+import type { CustomTool } from "../../../extensibility/custom-tools/types";
+
+const commitTypeSchema = Type.Union([
+	Type.Literal("feat"),
+	Type.Literal("fix"),
+	Type.Literal("refactor"),
+	Type.Literal("perf"),
+	Type.Literal("docs"),
+	Type.Literal("test"),
+	Type.Literal("build"),
+	Type.Literal("ci"),
+	Type.Literal("chore"),
+	Type.Literal("style"),
+	Type.Literal("revert"),
+]);
+
+const detailSchema = 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()),
+});
+
+const hunkSelectorSchema = Type.Union([
+	Type.Object({ type: Type.Literal("all") }),
+	Type.Object({ type: Type.Literal("indices"), indices: Type.Array(Type.Number(), { minItems: 1 }) }),
+	Type.Object({ type: Type.Literal("lines"), start: Type.Number(), end: Type.Number() }),
+]);
+
+const fileChangeSchema = Type.Object({
+	path: Type.String(),
+	hunks: hunkSelectorSchema,
+});
+
+const splitCommitSchema = Type.Object({
+	commits: Type.Array(
+		Type.Object({
+			changes: Type.Array(fileChangeSchema, { minItems: 1 }),
+			type: commitTypeSchema,
+			scope: Type.Union([Type.String(), Type.Null()]),
+			summary: Type.String(),
+			details: Type.Optional(Type.Array(detailSchema)),
+			issue_refs: Type.Optional(Type.Array(Type.String())),
+			rationale: Type.Optional(Type.String()),
+			dependencies: Type.Optional(Type.Array(Type.Number())),
+		}),
+		{ minItems: 2 },
+	),
+});
+
+interface SplitCommitResponse {
+	valid: boolean;
+	errors: string[];
+	warnings: string[];
+	proposal?: SplitCommitPlan;
+}
+
+function normalizeDetails(
+	details: Array<{
+		text: string;
+		changelog_category?: ConventionalDetail["changelogCategory"];
+		user_visible?: boolean;
+	}>,
+): ConventionalDetail[] {
+	return details.map(detail => ({
+		text: detail.text.trim(),
+		changelogCategory: detail.user_visible ? detail.changelog_category : undefined,
+		userVisible: detail.user_visible ?? false,
+	}));
+}
+
+export function createSplitCommitTool(
+	git: ControlledGit,
+	state: CommitAgentState,
+	changelogTargets: string[],
+): CustomTool<typeof splitCommitSchema> {
+	return {
+		name: "split_commit",
+		label: "Split Commit",
+		description: "Propose multiple atomic commits for unrelated changes.",
+		parameters: splitCommitSchema,
+		async execute(_toolCallId, params) {
+			const stagedFiles = state.overview?.files ?? (await git.getStagedFiles());
+			const stagedSet = new Set(stagedFiles);
+			const changelogSet = new Set(changelogTargets);
+			const usedFiles = new Set<string>();
+			const errors: string[] = [];
+			const warnings: string[] = [];
+			const diffText = await git.getDiff(true);
+
+			const commits: SplitCommitGroup[] = params.commits.map((commit, index) => {
+				const scope = commit.scope?.trim() || null;
+				const summary = normalizeSummary(commit.summary, commit.type, scope);
+				const detailInput = normalizeDetails(commit.details ?? []);
+				const detailResult = capDetails(detailInput);
+				warnings.push(...detailResult.warnings.map(warning => `Commit ${index + 1}: ${warning}`));
+				const issueRefs = commit.issue_refs ?? [];
+				const dependencies = (commit.dependencies ?? []).map(dep => Math.floor(dep));
+				const changes = commit.changes.map(change => ({
+					path: change.path,
+					hunks: change.hunks,
+				}));
+				const files = changes.map(change => change.path);
+
+				const summaryValidation = validateSummaryRules(summary);
+				const scopeValidation = validateScope(scope);
+				const typeValidation = validateTypeConsistency(commit.type, files, {
+					diffText,
+					summary,
+					details: detailResult.details,
+				});
+
+				if (summaryValidation.errors.length > 0) {
+					errors.push(...summaryValidation.errors.map(error => `Commit ${index + 1}: ${error}`));
+				}
+				if (!scopeValidation.valid) {
+					errors.push(...scopeValidation.errors.map(error => `Commit ${index + 1}: ${error}`));
+				}
+				if (typeValidation.errors.length > 0) {
+					errors.push(...typeValidation.errors.map(error => `Commit ${index + 1}: ${error}`));
+				}
+				warnings.push(...summaryValidation.warnings.map(warning => `Commit ${index + 1}: ${warning}`));
+				warnings.push(...typeValidation.warnings.map(warning => `Commit ${index + 1}: ${warning}`));
+				const hunkValidation = validateHunkSelectors(index, changes, files);
+				warnings.push(...hunkValidation.warnings);
+				errors.push(...hunkValidation.errors);
+				errors.push(...validateDependencies(index, dependencies, params.commits.length));
+
+				return {
+					changes,
+					type: commit.type,
+					scope,
+					summary,
+					details: detailResult.details,
+					issueRefs,
+					rationale: commit.rationale?.trim() || undefined,
+					dependencies,
+				};
+			});
+
+			for (const commit of commits) {
+				const seen = new Set<string>();
+				for (const change of commit.changes) {
+					const file = change.path;
+					if (!stagedSet.has(file) && !changelogSet.has(file)) {
+						errors.push(`File not staged: ${file}`);
+						continue;
+					}
+					if (seen.has(file)) {
+						errors.push(`File listed multiple times in commit ${commit.summary}: ${file}`);
+						continue;
+					}
+					if (usedFiles.has(file)) {
+						errors.push(`File appears in multiple commits: ${file}`);
+						continue;
+					}
+					seen.add(file);
+					usedFiles.add(file);
+				}
+			}
+
+			for (const file of stagedFiles) {
+				if (!usedFiles.has(file)) {
+					errors.push(`Staged file missing from split plan: ${file}`);
+				}
+			}
+
+			const dependencyCheck = computeDependencyOrder(commits);
+			if ("error" in dependencyCheck) {
+				errors.push(dependencyCheck.error);
+			}
+
+			const response: SplitCommitResponse = {
+				valid: errors.length === 0,
+				errors,
+				warnings,
+			};
+
+			if (response.valid) {
+				response.proposal = { commits, warnings };
+				state.splitProposal = response.proposal;
+			}
+
+			const text = JSON.stringify(
+				{
+					...response,
+					constraints: {
+						maxSummaryChars: SUMMARY_MAX_CHARS,
+						maxDetailItems: MAX_DETAIL_ITEMS,
+					},
+				},
+				null,
+				2,
+			);
+
+			return {
+				content: [{ type: "text", text }],
+				details: response,
+			};
+		},
+	};
+}
+
+function validateHunkSelectors(
+	commitIndex: number,
+	changes: SplitCommitGroup["changes"],
+	files: string[],
+): { errors: string[]; warnings: string[] } {
+	const errors: string[] = [];
+	const warnings: string[] = [];
+	const prefix = `Commit ${commitIndex + 1}`;
+	if (files.length === 0) {
+		errors.push(`${prefix}: no files specified`);
+		return { errors, warnings };
+	}
+	for (const change of changes) {
+		if (change.hunks.type === "indices") {
+			const invalid = change.hunks.indices.filter(
+				value => !Number.isFinite(value) || Math.floor(value) !== value || value < 1,
+			);
+			if (invalid.length > 0) {
+				errors.push(`${prefix}: invalid hunk indices for ${change.path}`);
+			}
+			continue;
+		}
+		if (change.hunks.type === "lines") {
+			const { start, end } = change.hunks;
+			if (!Number.isFinite(start) || !Number.isFinite(end)) {
+				errors.push(`${prefix}: invalid line range for ${change.path}`);
+				continue;
+			}
+			if (Math.floor(start) !== start || Math.floor(end) !== end || start < 1 || end < start) {
+				errors.push(`${prefix}: invalid line range for ${change.path}`);
+			}
+		}
+	}
+	return { errors, warnings };
+}
+
+function validateDependencies(commitIndex: number, dependencies: number[], totalCommits: number): string[] {
+	const errors: string[] = [];
+	const prefix = `Commit ${commitIndex + 1}`;
+	for (const dependency of dependencies) {
+		if (!Number.isFinite(dependency) || Math.floor(dependency) !== dependency) {
+			errors.push(`${prefix}: dependency index must be an integer`);
+			continue;
+		}
+		if (dependency === commitIndex) {
+			errors.push(`${prefix}: cannot depend on itself`);
+			continue;
+		}
+		if (dependency < 0 || dependency >= totalCommits) {
+			errors.push(`${prefix}: dependency index out of range (${dependency})`);
+		}
+	}
+	return errors;
+}

package/src/commit/agentic/topo-sort.ts

@@ -0,0 +1,44 @@
+import type { SplitCommitGroup } from "./state";
+
+export function computeDependencyOrder(groups: SplitCommitGroup[]): number[] | { error: string } {
+	const total = groups.length;
+	const inDegree = new Array<number>(total).fill(0);
+	const edges = Array.from({ length: total }, () => new Set<number>());
+
+	for (let index = 0; index < total; index += 1) {
+		const dependencies = groups[index]?.dependencies ?? [];
+		for (const dependency of dependencies) {
+			if (dependency < 0 || dependency >= total) {
+				return { error: `Invalid dependency index: ${dependency}` };
+			}
+			if (!edges[dependency]?.has(index)) {
+				edges[dependency]?.add(index);
+				inDegree[index] += 1;
+			}
+		}
+	}
+
+	const queue: number[] = [];
+	for (let index = 0; index < total; index += 1) {
+		if (inDegree[index] === 0) queue.push(index);
+	}
+
+	const order: number[] = [];
+	while (queue.length > 0) {
+		const current = queue.shift();
+		if (current === undefined) break;
+		order.push(current);
+		for (const next of edges[current] ?? []) {
+			inDegree[next] -= 1;
+			if (inDegree[next] === 0) {
+				queue.push(next);
+			}
+		}
+	}
+
+	if (order.length !== total) {
+		return { error: "Circular dependency detected in split commit plan." };
+	}
+
+	return order;
+}

package/src/commit/agentic/trivial.ts

@@ -0,0 +1,51 @@
+import type { CommitType } from "../../commit/types";
+
+export interface TrivialChangeResult {
+	isTrivial: true;
+	type: CommitType;
+	summary: string;
+}
+
+const WHITESPACE_ONLY_PATTERN = /^[-+][\t ]*$/;
+const IMPORT_LINE_PATTERN = /^[-+]\s*(import\s|from\s|export\s.*from|require\(|module\.exports)/;
+const EMPTY_LINE_PATTERN = /^[-+]\s*$/;
+
+export function detectTrivialChange(diff: string): TrivialChangeResult | null {
+	const lines = diff.split("\n");
+	const changeLines = lines.filter(line => line.startsWith("+") || line.startsWith("-"));
+	const contentLines = changeLines.filter(
+		line => !line.startsWith("+++") && !line.startsWith("---") && !line.startsWith("@@"),
+	);
+
+	if (contentLines.length === 0) return null;
+
+	if (isOnlyWhitespace(contentLines)) {
+		return { isTrivial: true, type: "style", summary: "formatted code" };
+	}
+
+	if (isOnlyImports(contentLines)) {
+		return { isTrivial: true, type: "style", summary: "reorganized imports" };
+	}
+
+	return null;
+}
+
+function isOnlyWhitespace(lines: string[]): boolean {
+	for (const line of lines) {
+		const content = line.slice(1);
+		if (content.trim().length > 0 && !WHITESPACE_ONLY_PATTERN.test(line)) {
+			return false;
+		}
+	}
+	return true;
+}
+
+function isOnlyImports(lines: string[]): boolean {
+	for (const line of lines) {
+		if (EMPTY_LINE_PATTERN.test(line)) continue;
+		if (!IMPORT_LINE_PATTERN.test(line)) {
+			return false;
+		}
+	}
+	return true;
+}

package/src/commit/agentic/validation.ts

@@ -0,0 +1,200 @@
+import { stripTypePrefix } from "../../commit/analysis/summary";
+import { validateSummary } from "../../commit/analysis/validation";
+import type { CommitType, ConventionalDetail } from "../../commit/types";
+
+export const SUMMARY_MAX_CHARS = 72;
+export const MAX_DETAIL_ITEMS = 6;
+
+const fillerWords = ["comprehensive", "various", "several", "improved", "enhanced", "better"];
+const metaPhrases = ["this commit", "this change", "updated code", "modified files"];
+const pastTenseVerbs = new Set([
+	"added",
+	"adjusted",
+	"aligned",
+	"bumped",
+	"changed",
+	"cleaned",
+	"clarified",
+	"consolidated",
+	"converted",
+	"corrected",
+	"created",
+	"deployed",
+	"deprecated",
+	"disabled",
+	"documented",
+	"dropped",
+	"enabled",
+	"expanded",
+	"extracted",
+	"fixed",
+	"hardened",
+	"implemented",
+	"improved",
+	"integrated",
+	"introduced",
+	"migrated",
+	"moved",
+	"optimized",
+	"patched",
+	"prevented",
+	"reduced",
+	"refactored",
+	"removed",
+	"renamed",
+	"reorganized",
+	"replaced",
+	"resolved",
+	"restored",
+	"restructured",
+	"reworked",
+	"secured",
+	"simplified",
+	"stabilized",
+	"standardized",
+	"streamlined",
+	"tightened",
+	"tuned",
+	"updated",
+	"upgraded",
+	"validated",
+]);
+const pastTenseEdExceptions = new Set(["hundred", "red", "bed"]);
+
+const unicodeReplacements: Array<[RegExp, string]> = [
+	[/[\u2018\u2019]/g, "'"],
+	[/[\u201C\u201D]/g, '"'],
+	[/[\u2013\u2014\u2212]/g, "-"],
+	[/\u2260/g, "!="],
+	[/\u00BD/g, "1/2"],
+	[/\u03BB/g, "lambda"],
+	[/[\u200B-\u200D\uFEFF]/g, ""],
+];
+
+export function normalizeSummary(summary: string, type: CommitType, scope: string | null): string {
+	const stripped = stripTypePrefix(summary, type, scope);
+	return normalizeUnicode(stripped).replace(/\s+/g, " ").trim();
+}
+
+export function normalizeUnicode(text: string): string {
+	let result = text;
+	for (const [pattern, replacement] of unicodeReplacements) {
+		result = result.replace(pattern, replacement);
+	}
+	return result.normalize("NFC");
+}
+
+export function validateSummaryRules(summary: string): { errors: string[]; warnings: string[] } {
+	const errors: string[] = [];
+	const warnings: string[] = [];
+	const basic = validateSummary(summary, SUMMARY_MAX_CHARS);
+	if (!basic.valid) {
+		errors.push(...basic.errors);
+	}
+
+	const words = summary.trim().split(/\s+/);
+	const firstWord = words[0]?.toLowerCase() ?? "";
+	const normalizedFirst = firstWord.replace(/[^a-z]/g, "");
+	const hasPastTense =
+		pastTenseVerbs.has(normalizedFirst) ||
+		(normalizedFirst.endsWith("ed") && !pastTenseEdExceptions.has(normalizedFirst));
+	if (!hasPastTense) {
+		errors.push("Summary must start with a past-tense verb");
+	}
+
+	const lowerSummary = summary.toLowerCase();
+	for (const word of fillerWords) {
+		if (lowerSummary.includes(word)) {
+			warnings.push(`Avoid filler word: ${word}`);
+		}
+	}
+	for (const phrase of metaPhrases) {
+		if (lowerSummary.includes(phrase)) {
+			warnings.push(`Avoid meta phrase: ${phrase}`);
+		}
+	}
+
+	return { errors, warnings };
+}
+
+export function capDetails(details: ConventionalDetail[]): { details: ConventionalDetail[]; warnings: string[] } {
+	if (details.length <= MAX_DETAIL_ITEMS) {
+		return { details, warnings: [] };
+	}
+
+	const scored = details.map((detail, index) => ({
+		detail,
+		index,
+		score: scoreDetail(detail.text),
+	}));
+
+	scored.sort((a, b) => b.score - a.score || a.index - b.index);
+	const keep = new Set(scored.slice(0, MAX_DETAIL_ITEMS).map(entry => entry.index));
+	const kept = details.filter((_detail, index) => keep.has(index));
+	const warnings = [`Capped detail list to ${MAX_DETAIL_ITEMS} items based on priority scoring.`];
+	return { details: kept, warnings };
+}
+
+function scoreDetail(text: string): number {
+	const lower = text.toLowerCase();
+	let score = 0;
+	if (/(security|vulnerability|exploit|cve)/.test(lower)) score += 100;
+	if (/(breaking|incompatible)/.test(lower)) score += 90;
+	if (/(performance|optimization|optimiz|latency|throughput)/.test(lower)) score += 80;
+	if (/(bug|fix|crash|panic|regression|failure)/.test(lower)) score += 70;
+	if (/(api|interface|public|export)/.test(lower)) score += 50;
+	if (/(user|client|customer)/.test(lower)) score += 40;
+	if (/(deprecated|removed|delete)/.test(lower)) score += 35;
+	return score;
+}
+
+export function validateTypeConsistency(
+	type: CommitType,
+	files: string[],
+	options: { diffText?: string; summary?: string; details?: ConventionalDetail[] } = {},
+): { errors: string[]; warnings: string[] } {
+	const errors: string[] = [];
+	const warnings: string[] = [];
+	const lowerFiles = files.map(file => file.toLowerCase());
+	const hasDocs = lowerFiles.some(file => /\.(md|mdx|adoc|rst)$/.test(file));
+	const hasTests = lowerFiles.some(
+		file => /(^|\/)(test|tests|__tests__)(\/|$)/.test(file) || /(^|\/).*(_test|\.test|\.spec)\./.test(file),
+	);
+	const hasCI = lowerFiles.some(file => file.startsWith(".github/workflows/") || file.startsWith(".gitlab-ci"));
+	const hasBuild = lowerFiles.some(file =>
+		["cargo.toml", "package.json", "makefile"].some(candidate => file.endsWith(candidate)),
+	);
+	const hasPerfEvidence = lowerFiles.some(file => /(bench|benchmark|perf)/.test(file));
+	const summary = options.summary?.toLowerCase() ?? "";
+	const detailText = options.details?.map(detail => detail.text.toLowerCase()).join(" ") ?? "";
+	const hasPerfKeywords = /(performance|optimiz|latency|throughput|benchmark)/.test(`${summary} ${detailText}`);
+
+	switch (type) {
+		case "docs":
+			if (!hasDocs) errors.push("Docs commit should include documentation file changes");
+			break;
+		case "test":
+			if (!hasTests) errors.push("Test commit should include test file changes");
+			break;
+		case "ci":
+			if (!hasCI) errors.push("CI commit should include CI configuration changes");
+			break;
+		case "build":
+			if (!hasBuild) errors.push("Build commit should include build-related files");
+			break;
+		case "refactor": {
+			const hasNewFiles = options.diffText ? /\nnew file mode\s/m.test(options.diffText) : false;
+			if (hasNewFiles) warnings.push("Refactor commit adds new files; consider feat if new functionality");
+			break;
+		}
+		case "perf":
+			if (!hasPerfEvidence && !hasPerfKeywords) {
+				warnings.push("Perf commit lacks benchmark or performance keywords");
+			}
+			break;
+		default:
+			break;
+	}
+
+	return { errors, warnings };
+}