@nghyane/arcane 0.1.0

package/src/commit/agentic/index.ts

@@ -0,0 +1,359 @@
+import * as path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { $env } from "@nghyane/arcane-utils";
+import { getProjectDir } from "@nghyane/arcane-utils/dirs";
+import { applyChangelogProposals } from "../../commit/changelog";
+import { detectChangelogBoundaries } from "../../commit/changelog/detect";
+import { parseUnreleasedSection } from "../../commit/changelog/parse";
+import { ControlledGit } from "../../commit/git";
+import { formatCommitMessage } from "../../commit/message";
+import { resolveFastModel, resolvePrimaryModel } from "../../commit/model-selection";
+import type { CommitCommandArgs, ConventionalAnalysis } from "../../commit/types";
+import { ModelRegistry } from "../../config/model-registry";
+import { renderPromptTemplate } from "../../config/prompt-templates";
+import { Settings } from "../../config/settings";
+import { discoverAuthStorage, discoverContextFiles } from "../../sdk";
+import { type ExistingChangelogEntries, runCommitAgentSession } from "./agent";
+import { generateFallbackProposal } from "./fallback";
+import splitConfirmPrompt from "./prompts/split-confirm.md" with { type: "text" };
+import type { CommitAgentState, CommitProposal, HunkSelector, SplitCommitPlan } from "./state";
+import { computeDependencyOrder } from "./topo-sort";
+import { detectTrivialChange } from "./trivial";
+
+interface CommitExecutionContext {
+	git: ControlledGit;
+	dryRun: boolean;
+	push: boolean;
+}
+
+export async function runAgenticCommit(args: CommitCommandArgs): Promise<void> {
+	const cwd = getProjectDir();
+	const git = new ControlledGit(cwd);
+	const [settings, authStorage] = await Promise.all([Settings.init({ cwd }), discoverAuthStorage()]);
+
+	writeStdout("● Resolving model...");
+	const modelRegistry = new ModelRegistry(authStorage);
+	await modelRegistry.refresh();
+	const stagedFilesPromise = (async () => {
+		let stagedFiles = await git.getStagedFiles();
+		if (stagedFiles.length === 0) {
+			writeStdout("No staged changes detected, staging all changes...");
+			await git.stageAll();
+			stagedFiles = await git.getStagedFiles();
+		}
+		return stagedFiles;
+	})();
+
+	const primaryModelPromise = resolvePrimaryModel(args.model, settings, modelRegistry);
+	const [primaryModelResult, stagedFiles] = await Promise.all([primaryModelPromise, stagedFilesPromise]);
+	const { model: primaryModel, apiKey: primaryApiKey } = primaryModelResult;
+	writeStdout(`  └─ ${primaryModel.name}`);
+
+	const { model: agentModel } = await resolveFastModel(settings, modelRegistry, primaryModel, primaryApiKey);
+
+	if (stagedFiles.length === 0) {
+		writeStderr("No changes to commit.");
+		return;
+	}
+
+	if (!args.noChangelog) {
+		writeStdout("● Detecting changelog targets...");
+	}
+	const [changelogBoundaries, contextFiles, numstat, diff] = await Promise.all([
+		args.noChangelog ? [] : detectChangelogBoundaries(cwd, stagedFiles),
+		discoverContextFiles(cwd),
+		git.getNumstat(true),
+		git.getDiff(true),
+	]);
+	const changelogTargets = changelogBoundaries.map(boundary => boundary.changelogPath);
+	if (!args.noChangelog) {
+		if (changelogTargets.length > 0) {
+			for (const path of changelogTargets) {
+				writeStdout(`  └─ ${path}`);
+			}
+		} else {
+			writeStdout("  └─ (none found)");
+		}
+	}
+
+	writeStdout("● Discovering context files...");
+	const agentsMdFiles = contextFiles.filter(file => file.path.endsWith("AGENTS.md"));
+	if (agentsMdFiles.length > 0) {
+		for (const file of agentsMdFiles) {
+			writeStdout(`  └─ ${file.path}`);
+		}
+	} else {
+		writeStdout("  └─ (none found)");
+	}
+	const forceFallback = $env.ARCANE_COMMIT_TEST_FALLBACK?.toLowerCase() === "true";
+	if (forceFallback) {
+		writeStdout("● Forcing fallback commit generation...");
+		const fallbackProposal = generateFallbackProposal(numstat);
+		await runSingleCommit(fallbackProposal, { git, dryRun: args.dryRun, push: args.push });
+		return;
+	}
+
+	const trivialChange = detectTrivialChange(diff);
+	if (trivialChange) {
+		writeStdout(`● Detected trivial change: ${trivialChange.summary}`);
+		const trivialProposal: CommitProposal = {
+			analysis: {
+				type: trivialChange.type,
+				scope: null,
+				details: [],
+				issueRefs: [],
+			},
+			summary: trivialChange.summary,
+			warnings: [],
+		};
+		await runSingleCommit(trivialProposal, { git, dryRun: args.dryRun, push: args.push });
+		return;
+	}
+
+	let existingChangelogEntries: ExistingChangelogEntries[] | undefined;
+	if (!args.noChangelog && changelogTargets.length > 0) {
+		existingChangelogEntries = await loadExistingChangelogEntries(changelogTargets);
+		if (existingChangelogEntries.length === 0) {
+			existingChangelogEntries = undefined;
+		}
+	}
+
+	writeStdout("● Starting commit agent...");
+	let commitState: CommitAgentState;
+	let usedFallback = false;
+
+	try {
+		commitState = await runCommitAgentSession({
+			cwd,
+			git,
+			model: agentModel,
+			settings,
+			modelRegistry,
+			authStorage,
+			userContext: args.context,
+			contextFiles,
+			changelogTargets,
+			requireChangelog: !args.noChangelog && changelogTargets.length > 0,
+			diffText: diff,
+			existingChangelogEntries,
+		});
+	} catch (error) {
+		const errorMessage = error instanceof Error ? error.message : String(error);
+		writeStderr(`Agent error: ${errorMessage}`);
+		if (error instanceof Error && error.stack && $env.DEBUG) {
+			writeStderr(error.stack);
+		}
+		writeStdout("● Using fallback commit generation...");
+		commitState = { proposal: generateFallbackProposal(numstat) };
+		usedFallback = true;
+	}
+
+	if (!usedFallback && !commitState.proposal && !commitState.splitProposal) {
+		if ($env.ARCANE_COMMIT_NO_FALLBACK?.toLowerCase() !== "true") {
+			writeStdout("● Agent did not provide proposal, using fallback...");
+			commitState.proposal = generateFallbackProposal(numstat);
+			usedFallback = true;
+		}
+	}
+
+	let updatedChangelogFiles: string[] = [];
+	if (!args.noChangelog && changelogTargets.length > 0 && !usedFallback) {
+		if (!commitState.changelogProposal) {
+			writeStderr("Commit agent did not provide changelog entries.");
+			return;
+		}
+		writeStdout("● Applying changelog entries...");
+		const updated = await applyChangelogProposals({
+			git,
+			cwd,
+			proposals: commitState.changelogProposal.entries,
+			dryRun: args.dryRun,
+			onProgress: message => {
+				writeStdout(`  ├─ ${message}`);
+			},
+		});
+		updatedChangelogFiles = updated.map(filePath => path.relative(cwd, filePath));
+		if (updated.length > 0) {
+			for (const filePath of updated) {
+				writeStdout(`  └─ ${filePath}`);
+			}
+		} else {
+			writeStdout("  └─ (no changes)");
+		}
+	}
+
+	if (commitState.proposal) {
+		await runSingleCommit(commitState.proposal, { git, dryRun: args.dryRun, push: args.push });
+		return;
+	}
+
+	if (commitState.splitProposal) {
+		await runSplitCommit(commitState.splitProposal, {
+			git,
+			dryRun: args.dryRun,
+			push: args.push,
+			additionalFiles: updatedChangelogFiles,
+		});
+		return;
+	}
+
+	writeStderr("Commit agent did not provide a proposal.");
+}
+
+async function runSingleCommit(proposal: CommitProposal, ctx: CommitExecutionContext): Promise<void> {
+	if (proposal.warnings.length > 0) {
+		writeStdout(formatWarnings(proposal.warnings));
+	}
+	const commitMessage = formatCommitMessage(proposal.analysis, proposal.summary);
+	if (ctx.dryRun) {
+		writeStdout("\nGenerated commit message:\n");
+		writeStdout(commitMessage);
+		return;
+	}
+	await ctx.git.commit(commitMessage);
+	writeStdout("Commit created.");
+	if (ctx.push) {
+		await ctx.git.push();
+		writeStdout("Pushed to remote.");
+	}
+}
+
+async function runSplitCommit(
+	plan: SplitCommitPlan,
+	ctx: CommitExecutionContext & { additionalFiles?: string[] },
+): Promise<void> {
+	if (plan.warnings.length > 0) {
+		writeStdout(formatWarnings(plan.warnings));
+	}
+	if (ctx.additionalFiles && ctx.additionalFiles.length > 0) {
+		appendFilesToLastCommit(plan, ctx.additionalFiles);
+	}
+	const stagedFiles = await ctx.git.getStagedFiles();
+	const plannedFiles = new Set(plan.commits.flatMap(commit => commit.changes.map(change => change.path)));
+	const missingFiles = stagedFiles.filter(file => !plannedFiles.has(file));
+	if (missingFiles.length > 0) {
+		writeStderr(`Split commit plan missing staged files: ${missingFiles.join(", ")}`);
+		return;
+	}
+
+	if (ctx.dryRun) {
+		writeStdout("\nSplit commit plan (dry run):\n");
+		for (const [index, commit] of plan.commits.entries()) {
+			const analysis: ConventionalAnalysis = {
+				type: commit.type,
+				scope: commit.scope,
+				details: commit.details,
+				issueRefs: commit.issueRefs,
+			};
+			const message = formatCommitMessage(analysis, commit.summary);
+			writeStdout(`Commit ${index + 1}:\n${message}\n`);
+			const changeSummary = commit.changes
+				.map(change => formatFileChangeSummary(change.path, change.hunks))
+				.join(", ");
+			writeStdout(`Changes: ${changeSummary}\n`);
+		}
+		return;
+	}
+
+	if (!(await confirmSplitCommitPlan(plan))) {
+		writeStdout("Split commit aborted by user.");
+		return;
+	}
+
+	const order = computeDependencyOrder(plan.commits);
+	if ("error" in order) {
+		throw new Error(order.error);
+	}
+
+	await ctx.git.resetStaging();
+	for (const commitIndex of order) {
+		const commit = plan.commits[commitIndex];
+		await ctx.git.stageHunks(commit.changes);
+		const analysis: ConventionalAnalysis = {
+			type: commit.type,
+			scope: commit.scope,
+			details: commit.details,
+			issueRefs: commit.issueRefs,
+		};
+		const message = formatCommitMessage(analysis, commit.summary);
+		await ctx.git.commit(message);
+		await ctx.git.resetStaging();
+	}
+	writeStdout("Split commits created.");
+	if (ctx.push) {
+		await ctx.git.push();
+		writeStdout("Pushed to remote.");
+	}
+}
+
+function appendFilesToLastCommit(plan: SplitCommitPlan, files: string[]): void {
+	if (plan.commits.length === 0) return;
+	const planned = new Set(plan.commits.flatMap(commit => commit.changes.map(change => change.path)));
+	const targetCommit = plan.commits[plan.commits.length - 1];
+	for (const file of files) {
+		if (planned.has(file)) continue;
+		targetCommit.changes.push({ path: file, hunks: { type: "all" } });
+		planned.add(file);
+	}
+}
+
+async function confirmSplitCommitPlan(plan: SplitCommitPlan): Promise<boolean> {
+	if (!process.stdin.isTTY || !process.stdout.isTTY) {
+		return true;
+	}
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	try {
+		const prompt = renderPromptTemplate(splitConfirmPrompt, { count: plan.commits.length });
+		const answer = await rl.question(prompt);
+		return ["y", "yes"].includes(answer.trim().toLowerCase());
+	} finally {
+		rl.close();
+	}
+}
+
+function formatWarnings(warnings: string[]): string {
+	return `Warnings:\n${warnings.map(warning => `- ${warning}`).join("\n")}`;
+}
+
+function writeStdout(message: string): void {
+	process.stdout.write(`${message}\n`);
+}
+
+function writeStderr(message: string): void {
+	process.stderr.write(`${message}\n`);
+}
+
+function formatFileChangeSummary(path: string, hunks: HunkSelector): string {
+	if (hunks.type === "all") {
+		return `${path} (all)`;
+	}
+	if (hunks.type === "indices") {
+		return `${path} (hunks ${hunks.indices.join(", ")})`;
+	}
+	return `${path} (lines ${hunks.start}-${hunks.end})`;
+}
+
+async function loadExistingChangelogEntries(paths: string[]): Promise<ExistingChangelogEntries[]> {
+	const entries = await Promise.all(
+		paths.map(async path => {
+			const file = Bun.file(path);
+			if (!(await file.exists())) {
+				return null;
+			}
+			const content = await file.text();
+			try {
+				const unreleased = parseUnreleasedSection(content);
+				const sections = Object.entries(unreleased.entries)
+					.filter(([, items]) => items.length > 0)
+					.map(([name, items]) => ({ name, items }));
+				if (sections.length > 0) {
+					return { path, sections };
+				}
+			} catch {
+				return null;
+			}
+			return null;
+		}),
+	);
+	return entries.filter((entry): entry is ExistingChangelogEntries => entry !== null);
+}

package/src/commit/agentic/prompts/analyze-file.md

@@ -0,0 +1,22 @@
+Analyze file at {{file}}.
+
+Goal:
+{{#if goal}}
+{{goal}}
+{{else}}
+Summarize purpose and commit-relevant changes.
+{{/if}}
+
+Return concise JSON object with:
+- summary: one-sentence description of file's role
+- highlights: 2-5 bullet points about notable behaviors or changes
+- risks: edge cases or risks worth noting (empty array if none)
+
+{{#if related_files}}
+## Other Files in This Change
+{{related_files}}
+
+Consider how file's changes relate to above files.
+{{/if}}
+
+Output only valid JSON. No markdown fences, no prose before/after JSON.

package/src/commit/agentic/prompts/session-user.md

@@ -0,0 +1,25 @@
+Generate conventional commit proposal for current staged changes.
+
+{{#if user_context}}
+User context:
+{{user_context}}
+{{/if}}
+
+{{#if changelog_targets}}
+Changelog targets (must call propose_changelog for these files):
+{{changelog_targets}}
+{{/if}}
+
+{{#if existing_changelog_entries}}
+## Existing Unreleased Changelog Entries
+May include entries from list in propose_changelog `deletions` field for removal.
+{{#each existing_changelog_entries}}
+### {{path}}
+{{#each sections}}
+{{name}}:
+{{#list items prefix="- " join="\n"}}{{this}}{{/list}}
+{{/each}}
+{{/each}}
+{{/if}}
+
+Use git_* tools to inspect changes. Call analyze_files for deeper per-file summaries. Finish with propose_commit or split_commit.

package/src/commit/agentic/prompts/split-confirm.md

@@ -0,0 +1 @@
+Split commit plan has {{count}} commits. Proceed? (y/N):

package/src/commit/agentic/prompts/system.md

@@ -0,0 +1,38 @@
+You are arcane commit workflow's conventional commit expert.
+
+Your job: decide needed git info, gather via tools, then call exactly one:
+- propose_commit (single commit)
+- split_commit (multiple commits when changes are unrelated)
+
+Workflow rules:
+1. Always call git_overview first.
+2. Keep tool calls minimal: prefer 1-2 git_file_diff calls for key files (hard limit 2).
+3. Use git_hunk only for large diffs.
+4. Use recent_commits only if you need style context.
+5. Use analyze_files only when diffs too large or unclear.
+6. Do not use read.
+
+Commit requirements:
+- Summary line: past-tense verb, <= 72 chars, no trailing period.
+- Avoid filler words: comprehensive, various, several, improved, enhanced, better.
+- Avoid meta phrases: "this commit", "this change", "updated code", "modified files".
+- Scope: lowercase, max two segments; only letters, digits, hyphens, underscores.
+- Detail lines optional (0-6). Each sentence ending in period, <= 120 chars.
+
+Conventional commit types:
+{{types_description}}
+
+Tool guidance:
+- git_overview: staged files, stat summary, numstat, scope candidates
+- git_file_diff: diff for specific files
+- git_hunk: specific hunks for large diffs
+- recent_commits: recent commit subjects + style stats
+- analyze_files: spawn quick_task subagents in parallel for analysis
+- propose_changelog: provide changelog entries for each changelog target
+- propose_commit: submit final commit proposal and run validation
+- split_commit: propose multiple commit groups (no overlapping files; all staged files covered)
+
+## Changelog Requirements
+
+If changelog targets provided, you MUST call `propose_changelog` before finishing.
+If you propose split commit plan, include changelog target files in relevant commit changes.

package/src/commit/agentic/state.ts

@@ -0,0 +1,69 @@
+import type { CommitType, ConventionalAnalysis, ConventionalDetail, NumstatEntry } from "../../commit/types";
+
+export interface GitOverviewSnapshot {
+	files: string[];
+	stat: string;
+	numstat: NumstatEntry[];
+	scopeCandidates: string;
+	isWideScope: boolean;
+	untrackedFiles?: string[];
+	excludedFiles?: string[];
+}
+
+export interface CommitProposal {
+	analysis: ConventionalAnalysis;
+	summary: string;
+	warnings: string[];
+}
+
+export interface FileObservation {
+	file: string;
+	summary: string;
+	highlights: string[];
+	risks: string[];
+	additions: number;
+	deletions: number;
+}
+
+export type HunkSelector =
+	| { type: "all" }
+	| { type: "indices"; indices: number[] }
+	| { type: "lines"; start: number; end: number };
+
+export interface FileChange {
+	path: string;
+	hunks: HunkSelector;
+}
+
+export interface SplitCommitGroup {
+	changes: FileChange[];
+	type: CommitType;
+	scope: string | null;
+	summary: string;
+	details: ConventionalDetail[];
+	issueRefs: string[];
+	rationale?: string;
+	dependencies: number[];
+}
+
+export interface SplitCommitPlan {
+	commits: SplitCommitGroup[];
+	warnings: string[];
+}
+
+export interface ChangelogProposal {
+	entries: Array<{
+		path: string;
+		entries: Record<string, string[]>;
+		deletions?: Record<string, string[]>;
+	}>;
+}
+
+export interface CommitAgentState {
+	overview?: GitOverviewSnapshot;
+	proposal?: CommitProposal;
+	splitProposal?: SplitCommitPlan;
+	changelogProposal?: ChangelogProposal;
+	diffCache?: Map<string, string>;
+	diffText?: string;
+}

package/src/commit/agentic/tools/analyze-file.ts

@@ -0,0 +1,118 @@
+import { Type } from "@sinclair/typebox";
+import analyzeFilePrompt from "../../../commit/agentic/prompts/analyze-file.md" with { type: "text" };
+import type { CommitAgentState } from "../../../commit/agentic/state";
+import type { NumstatEntry } from "../../../commit/types";
+import type { ModelRegistry } from "../../../config/model-registry";
+import { renderPromptTemplate } from "../../../config/prompt-templates";
+import type { Settings } from "../../../config/settings";
+import type { CustomTool } from "../../../extensibility/custom-tools/types";
+import type { AuthStorage } from "../../../session/auth-storage";
+import { runTaskBatch } from "../../../task/batch";
+import { getFilePriority } from "./git-file-diff";
+
+const analyzeFileSchema = Type.Object({
+	files: Type.Array(Type.String({ description: "File path" }), { minItems: 1 }),
+	goal: Type.Optional(Type.String({ description: "Optional analysis focus" })),
+});
+
+export function createAnalyzeFileTool(options: {
+	cwd: string;
+	authStorage: AuthStorage;
+	modelRegistry: ModelRegistry;
+	settings: Settings;
+	spawns: string;
+	state: CommitAgentState;
+}): CustomTool<typeof analyzeFileSchema> {
+	return {
+		name: "analyze_files",
+		label: "Analyze Files",
+		description: "Spawn quick_task agents to analyze files.",
+		parameters: analyzeFileSchema,
+		async execute(_toolCallId, params, _onUpdate, ctx, signal) {
+			const numstat = options.state.overview?.numstat ?? [];
+			const tasks = params.files.map((file, index) => {
+				const relatedFiles = formatRelatedFiles(params.files, file, numstat);
+				const prompt = renderPromptTemplate(analyzeFilePrompt, {
+					file,
+					goal: params.goal,
+					related_files: relatedFiles,
+				});
+				return {
+					id: `AnalyzeFile${index + 1}`,
+					description: `Analyze ${file}`,
+					task: prompt,
+				};
+			});
+
+			try {
+				const { results } = await runTaskBatch({
+					cwd: options.cwd,
+					agentName: "quick_task",
+					tasks,
+					sessionFile: ctx.sessionManager.getSessionFile() ?? null,
+					signal,
+					authStorage: options.authStorage,
+					modelRegistry: options.modelRegistry,
+					settings: options.settings,
+				});
+
+				const output = results
+					.filter(Boolean)
+					.map(r => r!.output.trim())
+					.filter(Boolean)
+					.join("\n\n---\n\n");
+
+				return {
+					content: [{ type: "text", text: output || "(no output)" }],
+					details: {},
+				};
+			} catch (err) {
+				const message = err instanceof Error ? err.message : "Task batch failed";
+				return {
+					content: [{ type: "text", text: message }],
+					details: {},
+				};
+			}
+		},
+	};
+}
+
+function inferFileType(path: string): string {
+	const priority = getFilePriority(path);
+	const lowerPath = path.toLowerCase();
+
+	if (priority === -100) return "binary file";
+	if (priority === 10) return "test file";
+	if (lowerPath.endsWith(".md") || lowerPath.endsWith(".txt")) return "documentation";
+	if (
+		lowerPath.endsWith(".json") ||
+		lowerPath.endsWith(".yaml") ||
+		lowerPath.endsWith(".yml") ||
+		lowerPath.endsWith(".toml")
+	)
+		return "configuration";
+	if (priority === 70) return "dependency manifest";
+	if (priority === 80) return "script";
+	if (priority === 100) return "implementation";
+
+	return "source file";
+}
+
+function formatRelatedFiles(files: string[], currentFile: string, numstat: NumstatEntry[]): string | undefined {
+	const others = files.filter(file => file !== currentFile);
+	if (others.length === 0) return undefined;
+
+	const numstatMap = new Map(numstat.map(entry => [entry.path, entry]));
+
+	const lines = others.map(file => {
+		const entry = numstatMap.get(file);
+		const fileType = inferFileType(file);
+		if (entry) {
+			const lineCount = entry.additions + entry.deletions;
+			return `- ${file} (${lineCount} lines): ${fileType}`;
+		}
+		return `- ${file}: ${fileType}`;
+	});
+
+	return `OTHER FILES IN THIS CHANGE:\n${lines.join("\n")}`;
+}