@nghyane/arcane 0.1.0

package/src/commit/agentic/tools/git-file-diff.ts

@@ -0,0 +1,194 @@
+import { Type } from "@sinclair/typebox";
+import type { CommitAgentState } from "../../../commit/agentic/state";
+import type { ControlledGit } from "../../../commit/git";
+import type { CustomTool } from "../../../extensibility/custom-tools/types";
+
+const TARGET_TOKENS = 30000;
+const CHARS_PER_TOKEN = 4;
+const MAX_CHARS = TARGET_TOKENS * CHARS_PER_TOKEN;
+const TRUNCATE_THRESHOLD_LINES = 30;
+const KEEP_HEAD_LINES = 15;
+const KEEP_TAIL_LINES = 10;
+
+const HIGH_PRIORITY_EXTENSIONS = new Set([
+	".rs",
+	".go",
+	".py",
+	".js",
+	".ts",
+	".tsx",
+	".jsx",
+	".java",
+	".c",
+	".cpp",
+	".h",
+	".hpp",
+]);
+const SHELL_SQL_EXTENSIONS = new Set([".sh", ".bash", ".zsh", ".sql"]);
+const MANIFEST_FILES = new Set([
+	"Cargo.toml",
+	"package.json",
+	"go.mod",
+	"pyproject.toml",
+	"requirements.txt",
+	"Gemfile",
+	"build.gradle",
+	"pom.xml",
+]);
+const LOW_PRIORITY_EXTENSIONS = new Set([".md", ".txt", ".json", ".yaml", ".yml", ".toml", ".xml", ".csv"]);
+const BINARY_EXTENSIONS = new Set([
+	".png",
+	".jpg",
+	".jpeg",
+	".gif",
+	".ico",
+	".woff",
+	".woff2",
+	".ttf",
+	".eot",
+	".pdf",
+	".zip",
+	".tar",
+	".gz",
+	".exe",
+	".dll",
+	".so",
+	".dylib",
+]);
+const TEST_PATTERNS = ["/test/", "/tests/", "/__tests__/", "_test.", ".test.", ".spec.", "_spec."];
+
+export function getFilePriority(filename: string): number {
+	const basename = filename.split("/").pop() ?? filename;
+	const ext = basename.includes(".") ? `.${basename.split(".").pop()}` : "";
+
+	if (BINARY_EXTENSIONS.has(ext)) return -100;
+
+	const lowerPath = filename.toLowerCase();
+	for (const pattern of TEST_PATTERNS) {
+		if (lowerPath.includes(pattern)) return 10;
+	}
+
+	if (LOW_PRIORITY_EXTENSIONS.has(ext) && !MANIFEST_FILES.has(basename)) return 20;
+	if (MANIFEST_FILES.has(basename)) return 70;
+	if (SHELL_SQL_EXTENSIONS.has(ext)) return 80;
+	if (HIGH_PRIORITY_EXTENSIONS.has(ext)) return 100;
+
+	return 50;
+}
+
+function truncateDiffContent(diff: string): { content: string; truncated: boolean } {
+	const lines = diff.split("\n");
+	if (lines.length <= TRUNCATE_THRESHOLD_LINES) {
+		return { content: diff, truncated: false };
+	}
+
+	const head = lines.slice(0, KEEP_HEAD_LINES);
+	const tail = lines.slice(-KEEP_TAIL_LINES);
+	const truncatedCount = lines.length - KEEP_HEAD_LINES - KEEP_TAIL_LINES;
+
+	return {
+		content: [...head, `\n... (truncated ${truncatedCount} lines) ...\n`, ...tail].join("\n"),
+		truncated: true,
+	};
+}
+
+function processDiffs(files: string[], diffs: Map<string, string>): { result: string; truncatedFiles: string[] } {
+	const sortedFiles = [...files].sort((a, b) => getFilePriority(b) - getFilePriority(a));
+
+	const truncatedFiles: string[] = [];
+	const parts: string[] = [];
+	let totalChars = 0;
+
+	for (const file of sortedFiles) {
+		const diff = diffs.get(file);
+		if (!diff) continue;
+
+		const remaining = MAX_CHARS - totalChars;
+		if (remaining <= 0) {
+			truncatedFiles.push(file);
+			continue;
+		}
+
+		let content = diff;
+		if (content.length > remaining || content.split("\n").length > TRUNCATE_THRESHOLD_LINES) {
+			const { content: truncated, truncated: wasTruncated } = truncateDiffContent(content);
+			if (wasTruncated) {
+				truncatedFiles.push(file);
+			}
+			content = truncated;
+			if (content.length > remaining) {
+				content = `${content.slice(0, remaining)}\n... (diff truncated due to size) ...`;
+				if (!truncatedFiles.includes(file)) {
+					truncatedFiles.push(file);
+				}
+			}
+		}
+
+		parts.push(`=== ${file} ===\n${content}`);
+		totalChars += content.length;
+	}
+
+	return { result: parts.join("\n\n"), truncatedFiles };
+}
+
+const gitFileDiffSchema = Type.Object({
+	files: Type.Array(Type.String({ description: "Files to diff" }), { minItems: 1, maxItems: 10 }),
+	staged: Type.Optional(Type.Boolean({ description: "Use staged changes (default: true)" })),
+});
+
+export function createGitFileDiffTool(
+	git: ControlledGit,
+	state: CommitAgentState,
+): CustomTool<typeof gitFileDiffSchema> {
+	return {
+		name: "git_file_diff",
+		label: "Git File Diff",
+		description: "Return the diff for specific files.",
+		parameters: gitFileDiffSchema,
+		async execute(_toolCallId, params) {
+			const staged = params.staged ?? true;
+			const cacheKey = (file: string) => `${file}:${staged}`;
+
+			if (!state.diffCache) {
+				state.diffCache = new Map();
+			}
+
+			const diffs = new Map<string, string>();
+			const uncachedFiles: string[] = [];
+
+			for (const file of params.files) {
+				const cached = state.diffCache.get(cacheKey(file));
+				if (cached !== undefined) {
+					diffs.set(file, cached);
+				} else {
+					uncachedFiles.push(file);
+				}
+			}
+
+			if (uncachedFiles.length > 0) {
+				for (const file of uncachedFiles) {
+					const diff = await git.getDiffForFiles([file], staged);
+					if (diff) {
+						diffs.set(file, diff);
+						state.diffCache.set(cacheKey(file), diff);
+					} else {
+						state.diffCache.set(cacheKey(file), "");
+					}
+				}
+			}
+
+			const { result, truncatedFiles } = processDiffs(params.files, diffs);
+			const output = result || "(no diff)";
+
+			return {
+				content: [{ type: "text", text: output }],
+				details: {
+					files: params.files,
+					staged,
+					truncatedFiles: truncatedFiles.length > 0 ? truncatedFiles : undefined,
+					cacheHits: params.files.length - uncachedFiles.length,
+				},
+			};
+		},
+	};
+}

package/src/commit/agentic/tools/git-hunk.ts

@@ -0,0 +1,50 @@
+import { Type } from "@sinclair/typebox";
+import type { ControlledGit } from "../../../commit/git";
+import type { DiffHunk, FileHunks } from "../../../commit/types";
+import type { CustomTool } from "../../../extensibility/custom-tools/types";
+
+const gitHunkSchema = Type.Object({
+	file: Type.String({ description: "File path" }),
+	hunks: Type.Optional(Type.Array(Type.Number({ description: "1-based hunk indices" }), { minItems: 1 })),
+	staged: Type.Optional(Type.Boolean({ description: "Use staged changes (default: true)" })),
+});
+
+function selectHunks(fileHunks: FileHunks, requested?: number[]): DiffHunk[] {
+	if (!requested || requested.length === 0) return fileHunks.hunks;
+	const wanted = new Set(requested.map(value => Math.max(1, Math.floor(value))));
+	return fileHunks.hunks.filter(hunk => wanted.has(hunk.index + 1));
+}
+
+export function createGitHunkTool(git: ControlledGit): CustomTool<typeof gitHunkSchema> {
+	return {
+		name: "git_hunk",
+		label: "Git Hunk",
+		description: "Return specific hunks from a file diff.",
+		parameters: gitHunkSchema,
+		async execute(_toolCallId, params) {
+			const staged = params.staged ?? true;
+			const hunks = await git.getHunks([params.file], staged);
+			const fileHunks = hunks.find(entry => entry.filename === params.file) ?? {
+				filename: params.file,
+				isBinary: false,
+				hunks: [],
+			};
+			if (fileHunks.isBinary) {
+				return {
+					content: [{ type: "text", text: "Binary file diff; no hunks available." }],
+					details: { file: params.file, staged, hunks: [] },
+				};
+			}
+			const selected = selectHunks(fileHunks, params.hunks);
+			const text = selected.length ? selected.map(hunk => hunk.content).join("\n\n") : "(no matching hunks)";
+			return {
+				content: [{ type: "text", text }],
+				details: {
+					file: params.file,
+					staged,
+					hunks: selected,
+				},
+			};
+		},
+	};
+}

package/src/commit/agentic/tools/git-overview.ts

@@ -0,0 +1,84 @@
+import { Type } from "@sinclair/typebox";
+import type { CommitAgentState, GitOverviewSnapshot } from "../../../commit/agentic/state";
+import { extractScopeCandidates } from "../../../commit/analysis/scope";
+import type { ControlledGit } from "../../../commit/git";
+import type { CustomTool } from "../../../extensibility/custom-tools/types";
+
+const EXCLUDED_LOCK_FILES = new Set([
+	"Cargo.lock",
+	"package-lock.json",
+	"yarn.lock",
+	"pnpm-lock.yaml",
+	"bun.lock",
+	"bun.lockb",
+	"go.sum",
+	"poetry.lock",
+	"Pipfile.lock",
+	"uv.lock",
+	"composer.lock",
+	"Gemfile.lock",
+	"flake.lock",
+	"pubspec.lock",
+	"Podfile.lock",
+	"mix.lock",
+	"gradle.lockfile",
+]);
+
+function isExcludedFile(path: string): boolean {
+	const basename = path.split("/").pop() ?? path;
+	return EXCLUDED_LOCK_FILES.has(basename);
+}
+
+function filterExcludedFiles(files: string[]): { filtered: string[]; excluded: string[] } {
+	const filtered: string[] = [];
+	const excluded: string[] = [];
+	for (const file of files) {
+		if (isExcludedFile(file)) {
+			excluded.push(file);
+		} else {
+			filtered.push(file);
+		}
+	}
+	return { filtered, excluded };
+}
+
+const gitOverviewSchema = Type.Object({
+	staged: Type.Optional(Type.Boolean({ description: "Use staged changes (default: true)" })),
+	include_untracked: Type.Optional(Type.Boolean({ description: "Include untracked files when staged=false" })),
+});
+
+export function createGitOverviewTool(
+	git: ControlledGit,
+	state: CommitAgentState,
+): CustomTool<typeof gitOverviewSchema> {
+	return {
+		name: "git_overview",
+		label: "Git Overview",
+		description: "Return staged files, diff stat summary, and numstat entries.",
+		parameters: gitOverviewSchema,
+		async execute(_toolCallId, params) {
+			const staged = params.staged ?? true;
+			const allFiles = staged ? await git.getStagedFiles() : await git.getChangedFiles(false);
+			const { filtered: files, excluded } = filterExcludedFiles(allFiles);
+			const stat = await git.getStat(staged);
+			const allNumstat = await git.getNumstat(staged);
+			const numstat = allNumstat.filter(entry => !isExcludedFile(entry.path));
+			const scopeResult = extractScopeCandidates(numstat);
+			const untrackedFiles = !staged && params.include_untracked ? await git.getUntrackedFiles() : undefined;
+			const snapshot: GitOverviewSnapshot = {
+				files,
+				stat,
+				numstat,
+				scopeCandidates: scopeResult.scopeCandidates,
+				isWideScope: scopeResult.isWide,
+				untrackedFiles,
+				excludedFiles: excluded.length > 0 ? excluded : undefined,
+			};
+			state.overview = snapshot;
+			return {
+				content: [{ type: "text", text: JSON.stringify(snapshot, null, 2) }],
+				details: snapshot,
+			};
+		},
+	};
+}

package/src/commit/agentic/tools/index.ts

@@ -0,0 +1,56 @@
+import type { CommitAgentState } from "../../../commit/agentic/state";
+import type { ControlledGit } from "../../../commit/git";
+import type { ModelRegistry } from "../../../config/model-registry";
+import type { Settings } from "../../../config/settings";
+import type { CustomTool } from "../../../extensibility/custom-tools/types";
+import type { AuthStorage } from "../../../session/auth-storage";
+import { createAnalyzeFileTool } from "./analyze-file";
+import { createGitFileDiffTool } from "./git-file-diff";
+import { createGitHunkTool } from "./git-hunk";
+import { createGitOverviewTool } from "./git-overview";
+import { createProposeChangelogTool } from "./propose-changelog";
+import { createProposeCommitTool } from "./propose-commit";
+import { createRecentCommitsTool } from "./recent-commits";
+import { createSplitCommitTool } from "./split-commit";
+
+export interface CommitToolOptions {
+	cwd: string;
+	git: ControlledGit;
+	authStorage: AuthStorage;
+	modelRegistry: ModelRegistry;
+	settings: Settings;
+	spawns: string;
+	state: CommitAgentState;
+	changelogTargets: string[];
+	enableAnalyzeFiles?: boolean;
+}
+
+export function createCommitTools(options: CommitToolOptions): Array<CustomTool<any, any>> {
+	const tools: Array<CustomTool<any, any>> = [
+		createGitOverviewTool(options.git, options.state),
+		createGitFileDiffTool(options.git, options.state),
+		createGitHunkTool(options.git),
+		createRecentCommitsTool(options.git),
+	];
+
+	if (options.enableAnalyzeFiles ?? true) {
+		tools.push(
+			createAnalyzeFileTool({
+				cwd: options.cwd,
+				authStorage: options.authStorage,
+				modelRegistry: options.modelRegistry,
+				settings: options.settings,
+				spawns: options.spawns,
+				state: options.state,
+			}),
+		);
+	}
+
+	tools.push(
+		createProposeChangelogTool(options.state, options.changelogTargets),
+		createProposeCommitTool(options.git, options.state),
+		createSplitCommitTool(options.git, options.state, options.changelogTargets),
+	);
+
+	return tools;
+}

package/src/commit/agentic/tools/propose-changelog.ts

@@ -0,0 +1,128 @@
+import { Type } from "@sinclair/typebox";
+import type { CommitAgentState } from "../../../commit/agentic/state";
+import type { ChangelogCategory } from "../../../commit/types";
+import type { CustomTool } from "../../../extensibility/custom-tools/types";
+
+const changelogEntrySchema = Type.Object({
+	path: Type.String(),
+	entries: Type.Record(Type.String(), Type.Array(Type.String())),
+	deletions: Type.Optional(
+		Type.Record(Type.String(), Type.Array(Type.String()), {
+			description: "Entries to remove from existing changelog sections (case-insensitive match)",
+		}),
+	),
+});
+
+const proposeChangelogSchema = Type.Object({
+	entries: Type.Array(changelogEntrySchema),
+});
+
+interface ChangelogResponse {
+	valid: boolean;
+	errors: string[];
+	warnings: string[];
+}
+
+const allowedCategories = new Set<ChangelogCategory>([
+	"Breaking Changes",
+	"Added",
+	"Changed",
+	"Deprecated",
+	"Removed",
+	"Fixed",
+	"Security",
+]);
+
+export function createProposeChangelogTool(
+	state: CommitAgentState,
+	changelogTargets: string[],
+): CustomTool<typeof proposeChangelogSchema> {
+	return {
+		name: "propose_changelog",
+		label: "Propose Changelog",
+		description: "Provide changelog entries for targeted CHANGELOG.md files.",
+		parameters: proposeChangelogSchema,
+		async execute(_toolCallId, params) {
+			const errors: string[] = [];
+			const warnings: string[] = [];
+			const targets = new Set(changelogTargets);
+			const seen = new Set<string>();
+
+			const normalized = params.entries.map(entry => {
+				const cleaned: Record<string, string[]> = {};
+				for (const [category, values] of Object.entries(entry.entries ?? {})) {
+					if (!allowedCategories.has(category as ChangelogCategory)) {
+						errors.push(`Unknown changelog category for ${entry.path}: ${category}`);
+						continue;
+					}
+					const items = values.map(value => value.trim().replace(/\.$/, "")).filter(value => value.length > 0);
+					if (items.length > 0) {
+						cleaned[category] = Array.from(new Set(items));
+					}
+				}
+
+				let cleanedDeletions: Record<string, string[]> | undefined;
+				if (entry.deletions) {
+					cleanedDeletions = {};
+					for (const [category, values] of Object.entries(entry.deletions)) {
+						if (!allowedCategories.has(category as ChangelogCategory)) {
+							errors.push(`Unknown deletion category for ${entry.path}: ${category}`);
+							continue;
+						}
+						const items = values.map(value => value.trim()).filter(value => value.length > 0);
+						if (items.length > 0) {
+							cleanedDeletions[category] = Array.from(new Set(items));
+						}
+					}
+					if (Object.keys(cleanedDeletions).length === 0) {
+						cleanedDeletions = undefined;
+					}
+				}
+
+				if (Object.keys(cleaned).length === 0 && !cleanedDeletions) {
+					warnings.push(`No changelog entries provided for ${entry.path}.`);
+				}
+				return {
+					path: entry.path,
+					entries: cleaned,
+					deletions: cleanedDeletions,
+				};
+			});
+
+			for (const entry of normalized) {
+				if (targets.size > 0 && !targets.has(entry.path)) {
+					errors.push(`Changelog not expected: ${entry.path}`);
+					continue;
+				}
+				if (seen.has(entry.path)) {
+					errors.push(`Duplicate changelog entry for ${entry.path}`);
+					continue;
+				}
+				seen.add(entry.path);
+			}
+
+			if (targets.size > 0) {
+				for (const target of targets) {
+					if (!seen.has(target)) {
+						errors.push(`Missing changelog entries for ${target}`);
+					}
+				}
+			}
+
+			const response: ChangelogResponse = {
+				valid: errors.length === 0,
+				errors,
+				warnings,
+			};
+
+			if (response.valid) {
+				state.changelogProposal = { entries: normalized };
+			}
+
+			return {
+				content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+				details: response,
+			};
+		},
+	};
+}

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

@@ -0,0 +1,154 @@
+import { Type } from "@sinclair/typebox";
+import type { CommitAgentState } from "../../../commit/agentic/state";
+import {
+	capDetails,
+	MAX_DETAIL_ITEMS,
+	normalizeSummary,
+	SUMMARY_MAX_CHARS,
+	validateSummaryRules,
+	validateTypeConsistency,
+} from "../../../commit/agentic/validation";
+import { validateAnalysis } from "../../../commit/analysis/validation";
+import type { ControlledGit } from "../../../commit/git";
+import type { CommitType, ConventionalAnalysis, 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 proposeCommitSchema = Type.Object({
+	type: commitTypeSchema,
+	scope: Type.Union([Type.String(), Type.Null()]),
+	summary: Type.String(),
+	details: Type.Array(detailSchema),
+	issue_refs: Type.Array(Type.String()),
+});
+
+interface ProposalResponse {
+	valid: boolean;
+	errors: string[];
+	warnings: string[];
+	proposal?: {
+		type: CommitType;
+		scope: string | null;
+		summary: string;
+		details: ConventionalDetail[];
+		issue_refs: string[];
+	};
+}
+
+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 createProposeCommitTool(
+	git: ControlledGit,
+	state: CommitAgentState,
+): CustomTool<typeof proposeCommitSchema> {
+	return {
+		name: "propose_commit",
+		label: "Propose Commit",
+		description: "Submit the final conventional commit proposal.",
+		parameters: proposeCommitSchema,
+		async execute(_toolCallId, params) {
+			const scope = params.scope?.trim() || null;
+			const summary = normalizeSummary(params.summary, params.type, scope);
+			const details = normalizeDetails(params.details);
+			const { details: cappedDetails, warnings: detailWarnings } = capDetails(details);
+			const analysis: ConventionalAnalysis = {
+				type: params.type,
+				scope,
+				details: cappedDetails,
+				issueRefs: params.issue_refs ?? [],
+			};
+
+			const summaryValidation = validateSummaryRules(summary);
+			const analysisValidation = validateAnalysis(analysis);
+			const stagedFiles = state.overview?.files ?? (await git.getStagedFiles());
+			const diffText = state.diffText ?? (await git.getDiff(true));
+			const typeValidation = validateTypeConsistency(params.type, stagedFiles, {
+				diffText,
+				summary,
+				details: cappedDetails,
+			});
+
+			const errors = [...summaryValidation.errors, ...analysisValidation.errors, ...typeValidation.errors];
+			const warnings = [...summaryValidation.warnings, ...detailWarnings, ...typeValidation.warnings];
+
+			const response: ProposalResponse = {
+				valid: errors.length === 0,
+				errors,
+				warnings,
+			};
+
+			if (response.valid) {
+				response.proposal = {
+					type: analysis.type,
+					scope: analysis.scope,
+					summary,
+					details: analysis.details,
+					issue_refs: analysis.issueRefs,
+				};
+				state.proposal = {
+					analysis,
+					summary,
+					warnings,
+				};
+			}
+
+			const text = JSON.stringify(
+				{
+					...response,
+					constraints: {
+						maxSummaryChars: SUMMARY_MAX_CHARS,
+						maxDetailItems: MAX_DETAIL_ITEMS,
+					},
+				},
+				null,
+				2,
+			);
+
+			return {
+				content: [{ type: "text", text }],
+				details: response,
+			};
+		},
+	};
+}