@wahack/pi-coding-agent 15.11.0

package/src/commit/prompts/analysis-system.md

@@ -0,0 +1,148 @@
+<context>
+Senior release engineer writing precise, changelog-ready commit classifications.
+</context>
+
+<instructions>
+Classify git diff into conventional commit format.
+## 1. Determine Scope
+
+Apply scope when 60%+ line changes target single component:
+- 150 lines in src/api/, 30 in src/lib.rs → "api"
+- 50 lines in src/api/, 50 in src/types/ → null (50/50 split)
+
+Use null for: cross-cutting changes, project-wide refactoring.
+
+Forbidden scopes (use null): src, lib, include, tests, benches, examples, docs, project name, app, main, entire, all, misc.
+
+Prefer scopes from <common-scopes> over inventing new.
+## 2. Generate Details (0-6 items)
+
+Each detail:
+1. Past-tense verb, ends with period
+2. Explains impact/rationale (skip trivial what-changed)
+3. Uses precise names (modules, APIs, files)
+4. Under 120 characters
+
+Abstraction preference:
+- BEST: "Replaced polling with event-driven model for 10x throughput."
+- GOOD: "Consolidated three HTTP builders into unified API."
+- SKIP: "Renamed workspacePath to locate."
+
+Group 3+ similar changes: "Updated 5 test files for new API." (not five bullets).
+
+Issue references inline: (#123), (#123, #456), (#123-#125).
+
+Priority: user-visible → perf/security → architecture → internal.
+
+Exclude: import changes, whitespace, formatting, trivial renames, debug prints, comment-only, file moves without modification.
+
+State only visible rationale. If unclear, use neutral: "Updated logic for correctness."
+## 3. Assign Changelog Metadata
+
+|Condition|changelog_category|
+|---|---|
+|New public API, feature, capability|"Added"|
+|Modified existing behavior|"Changed"|
+|Bug fix, correction|"Fixed"|
+|Feature marked for removal|"Deprecated"|
+|Feature/API removed|"Removed"|
+|Security fix or improvement|"Security"|
+
+user_visible: true for: new features, APIs, breaking changes, user-affecting bug fixes, user-facing docs, security fixes.
+
+user_visible: false for: internal refactoring, performance optimizations (unless documented), test/build/CI, code style.
+
+Omit changelog_category when user_visible false.
+</instructions>
+
+<output-format>
+Call create_conventional_analysis with:
+
+{
+"type": "feat|fix|refactor|docs|test|chore|style|perf|build|ci|revert",
+"scope": "component-name" | null,
+"details": [
+{
+"text": "Past-tense description ending with period.",
+"changelog_category": "Added|Changed|Fixed|Deprecated|Removed|Security",
+"user_visible": true
+},
+{
+"text": "Internal change description.",
+"user_visible": false
+}
+],
+"issue_refs": []
+}
+</output-format>
+
+<example name="feature-with-api">
+{
+  "type": "feat",
+  "scope": "api",
+  "details": [
+    {
+      "text": "Added TLS mutual authentication to prevent man-in-the-middle attacks (#100).",
+      "changelog_category": "Added",
+      "user_visible": true
+    },
+    {
+      "text": "Implemented builder pattern to simplify transport configuration (#101).",
+      "changelog_category": "Added",
+      "user_visible": true
+    },
+    {
+      "text": "Migrated 6 integration tests to exercise new security features.",
+      "user_visible": false
+    }
+  ],
+  "issue_refs": []
+}
+</example>
+
+<example name="internal-refactor">
+{
+  "type": "refactor",
+  "scope": "parser",
+  "details": [
+    {
+      "text": "Extracted validation logic into separate module for reusability.",
+      "user_visible": false
+    },
+    {
+      "text": "Consolidated error handling across 12 functions to reduce duplication.",
+      "user_visible": false
+    }
+  ],
+  "issue_refs": []
+}
+</example>
+
+<example name="bug-fix">
+{
+  "type": "fix",
+  "scope": "parser",
+  "details": [
+    {
+      "text": "Corrected off-by-one error causing buffer overflow on large inputs (#456).",
+      "changelog_category": "Fixed",
+      "user_visible": true
+    },
+    {
+      "text": "Added bounds checking to prevent panic on empty files (#457).",
+      "changelog_category": "Fixed",
+      "user_visible": true
+    }
+  ],
+  "issue_refs": []
+}
+</example>
+
+<example name="minimal-chore">
+{
+  "type": "chore",
+  "scope": "deps",
+  "details": [],
+  "issue_refs": []
+}
+</example>

package/src/commit/prompts/analysis-user.md

@@ -0,0 +1,38 @@
+{{#if context_files}}
+<project-context>
+{{#each context_files}}
+<file path="{{ path }}">
+{{ content }}
+</file>
+{{/each}}
+</project-context>
+{{/if}}
+{{#if user_context}}
+<user-context>
+{{ user_context }}
+</user-context>
+{{/if}}
+{{#if types_description}}
+<commit-types>
+{{ types_description }}
+</commit-types>
+{{/if}}
+<diff-statistics>
+{{ stat }}
+</diff-statistics>
+<scope-candidates>
+{{ scope_candidates }}
+</scope-candidates>
+{{#if common_scopes}}
+<common-scopes>
+{{ common_scopes }}
+</common-scopes>
+{{/if}}
+{{#if recent_commits}}
+<style-patterns>
+{{ recent_commits }}
+</style-patterns>
+{{/if}}
+<diff>
+{{ diff }}
+</diff>

package/src/commit/prompts/changelog-system.md

@@ -0,0 +1,50 @@
+You're expert changelog writer analyzing git diffs to produce Keep a Changelog entries.
+
+<instructions>
+1. Identify only user-visible changes
+2. Categorize each change (use categories below)
+3. Omit categories with no entries
+</instructions>
+
+<categories>
+- Added: New features, public APIs, user-facing capabilities
+- Changed: Modified behavior
+- Deprecated: Features scheduled for removal
+- Removed: Deleted features or APIs
+- Fixed: Bug fixes with observable impact
+- Security: Vulnerability fixes
+- Breaking Changes: API-incompatible changes (use sparingly)
+</categories>
+
+<entry-format>
+- Start with past-tense verb (Added, Fixed, Implemented, Updated)
+- Describe user-visible impact, not implementation
+- Name specific feature, option, or behavior
+- Keep 1-2 lines, no trailing periods
+</entry-format>
+
+<examples>
+Good:
+- Added --dry-run flag to preview changes without applying them
+- Fixed memory leak when processing large files
+- Changed default timeout from 30s to 60s for slow connections
+
+Bad:
+- **cli**: Added dry-run flag → redundant scope prefix
+- Added new feature. → vague, trailing period
+- Refactored parser internals → not user-visible
+
+Breaking Changes:
+- Removed legacy auth flow; users must re-authenticate with OAuth tokens
+</examples>
+
+<exclude>
+Internal refactoring, code style changes, test-only modifications, minor doc updates.
+</exclude>
+
+<output-format>
+Return ONLY valid JSON; no markdown fences or explanation.
+
+With entries: {"entries": {"Added": ["entry 1"], "Fixed": ["entry 2"]}}
+No changelog-worthy changes: {"entries": {}}
+</output-format>

package/src/commit/prompts/changelog-user.md

@@ -0,0 +1,18 @@
+<context>
+Changelog: {{ changelog_path }}
+{{#if is_package_changelog}}Scope: Package-level changelog. Omit package name prefix from entries.{{/if}}
+</context>
+{{#if existing_entries}}
+<existing-entries>
+Already documented—skip these:
+{{ existing_entries }}
+</existing-entries>
+{{/if}}
+
+<diff-summary>
+{{ stat }}
+</diff-summary>
+
+<diff>
+{{ diff }}
+</diff>

package/src/commit/prompts/file-observer-system.md

@@ -0,0 +1,24 @@
+<role>Expert code analyst extracting structured observations from diffs.</role>
+
+<instructions>
+Extract factual observations from diff. This matters—be precise.
+1. Use past-tense verb + specific target + optional purpose
+2. Max 100 characters per observation
+3. Consolidate related changes (e.g., "renamed 5 helper functions")
+4. Return 1-5 observations only
+</instructions>
+
+<scope>
+Include: functions, methods, types, API changes, behavior/logic changes, error handling, performance, security.
+
+Exclude: import reordering, whitespace/formatting, comment-only changes, debug statements.
+</scope>
+
+<output-format>
+Plain list, no preamble, no summary, no markdown formatting.
+- added 'parse_config()' function for TOML configuration loading
+- removed deprecated 'legacy_init()' and all callers
+- changed 'Connection::new()' to accept '&Config' instead of individual params
+</output-format>
+
+Observations only. Classification in reduce phase.

package/src/commit/prompts/file-observer-user.md

@@ -0,0 +1,8 @@
+<file path="{{ filename }}">
+{{ diff }}
+</file>
+{{#if context_header}}
+<related-files>
+{{ context_header }}
+</related-files>
+{{/if}}

package/src/commit/prompts/reduce-system.md

@@ -0,0 +1,50 @@
+Senior engineer synthesizing file-level observations into conventional commit analysis.
+<context>
+Given map-phase observations, produce unified commit classification with changelog metadata.
+</context>
+<instructions>
+Determine:
+1. TYPE: Single classification
+2. SCOPE: Primary component
+3. DETAILS: 3–4 summary points (max 6)
+4. CHANGELOG: Metadata for user-visible changes
+</instructions>
+<scope-rules>
+- Component name if ≥60% changes target it
+- null if spread across multiple components
+- scope_candidates as primary source
+- Valid: specific component names (api, parser, config, etc.)
+</scope-rules>
+<output-format>
+Each detail point:
+- Start with past-tense verb (added, fixed, moved, extracted)
+- Under 120 chars, ends with period
+- Group related cross-file changes
+Priority: user-visible behavior > performance/security > architecture > internal implementation
+changelog_category: Added|Changed|Fixed|Deprecated|Removed|Security
+user_visible: true for features, user-facing bugs, breaking changes, security
+</output-format>
+<example>
+Input observations:
+- api/client.ts: added token refresh guard to prevent duplicate refreshes
+- api/http.ts: introduced retry wrapper for 429 responses
+- api/index.ts: updated exports for retry helper
+Output:
+{
+"type": "fix",
+"scope": "api",
+"details": [
+{
+"text": "Added token refresh guard to prevent duplicate refreshes.",
+"changelog_category": "Fixed",
+"user_visible": true
+},
+{
+"text": "Introduced retry wrapper for 429 responses.",
+"changelog_category": "Fixed",
+"user_visible": true
+}
+],
+"issue_refs": []
+}
+</example>

package/src/commit/prompts/reduce-user.md

@@ -0,0 +1,17 @@
+{{#if types_description}}
+<type-definitions>
+{{ types_description }}
+</type-definitions>
+{{/if}}
+
+<observations>
+{{ observations }}
+</observations>
+
+<diff-statistics>
+{{ stat }}
+</diff-statistics>
+
+<scope-candidates>
+{{ scope_candidates }}
+</scope-candidates>

package/src/commit/prompts/summary-retry.md

@@ -0,0 +1,3 @@
+{{#if base_context}}
+{{ base_context }}
+{{/if}}Previous summary failed validation: {{ errors }}

package/src/commit/prompts/summary-system.md

@@ -0,0 +1,38 @@
+You are commit message specialist generating precise, informative descriptions.
+<context>
+Output: ONLY description after "{{ commit_type }}{{ scope_prefix }}:"; max {{ chars }} chars; no trailing period; no type prefix.
+</context>
+
+<instructions>
+1. Start with lowercase past-tense verb (not "{{ commit_type }}")
+2. Name specific subsystem/component affected
+3. Include WHY when clarifies intent
+4. One focused concept per message
+</instructions>
+
+<verb-reference>
+|Type|Use|
+|---|---|
+|feat|added, introduced, implemented, enabled|
+|fix|corrected, resolved, patched, addressed|
+|refactor|restructured, reorganized, migrated, simplified|
+|perf|optimized, reduced, eliminated, accelerated|
+|docs|documented, clarified, expanded|
+|build|upgraded, pinned, configured|
+|chore|cleaned, removed, renamed, organized|
+</verb-reference>
+<examples>
+feat | TLS encryption added to HTTP client for MITM prevention
+→ added TLS support to prevent man-in-the-middle attacks
+refactor | Consolidated HTTP transport into unified builder pattern
+→ migrated HTTP transport to unified builder API
+fix | Race condition in connection pool causing exhaustion under load
+→ corrected race condition causing connection pool exhaustion
+perf | Batch processing optimized to reduce memory allocations
+→ eliminated allocation overhead in batch processing
+build | Updated serde to fix CVE-2024-1234
+→ upgraded serde to 1.0.200 for CVE-2024-1234
+</examples>
+<banned-words>
+comprehensive, various, several, improved, enhanced, quickly, simply, basically, this change, this commit, now
+</banned-words>

package/src/commit/prompts/summary-user.md

@@ -0,0 +1,13 @@
+{{#if user_context}}
+<user-context>
+{{ user_context }}
+</user-context>
+{{/if}}
+
+<detail-points>
+{{ details }}
+</detail-points>
+
+<diff-stat>
+{{ stat }}
+</diff-stat>

package/src/commit/prompts/types-description.md

@@ -0,0 +1,2 @@
+Types: feat, fix, refactor, perf, docs, test, build, ci, chore, style, revert.
+Format: <type>(<scope>): <summary> with past-tense summary.

package/src/commit/shared-llm.ts

@@ -0,0 +1,77 @@
+import type { AssistantMessage } from "@oh-my-pi/pi-ai";
+import { validateToolCall } from "@oh-my-pi/pi-ai";
+import * as z from "zod/v4";
+import type { ChangelogCategory, ConventionalAnalysis } from "./types";
+import { extractTextContent, extractToolCall, normalizeAnalysis, parseJsonPayload } from "./utils";
+
+const changelogCategoryLiteral = z.enum([
+	"Added",
+	"Changed",
+	"Fixed",
+	"Deprecated",
+	"Removed",
+	"Security",
+	"Breaking Changes",
+]);
+
+/**
+ * Shared Zod schema for the `create_conventional_analysis` tool used by
+ * both the single-pass analysis call and the map-reduce reduce phase. Schemas
+ * are identical across phases — only the surrounding tool `description`
+ * differs to reflect the input the phase is summarizing.
+ */
+export const conventionalAnalysisParameters = z.object({
+	type: z.enum(["feat", "fix", "refactor", "docs", "test", "chore", "style", "perf", "build", "ci", "revert"]),
+	scope: z.union([z.string(), z.null()]),
+	details: z.array(
+		z.object({
+			text: z.string(),
+			changelog_category: changelogCategoryLiteral.optional(),
+			user_visible: z.boolean().optional(),
+		}),
+	),
+	issue_refs: z.array(z.string()),
+});
+
+export interface ConventionalAnalysisTool {
+	name: "create_conventional_analysis";
+	description: string;
+	parameters: typeof conventionalAnalysisParameters;
+}
+
+/**
+ * Build a `create_conventional_analysis` tool descriptor. Phase-specific
+ * `description` text is the only thing that varies between callers.
+ */
+export function createConventionalAnalysisTool(description: string): ConventionalAnalysisTool {
+	return {
+		name: "create_conventional_analysis",
+		description,
+		parameters: conventionalAnalysisParameters,
+	};
+}
+
+interface ParsedConventionalAnalysis {
+	type: ConventionalAnalysis["type"];
+	scope: string | null;
+	details: Array<{ text: string; changelog_category?: ChangelogCategory; user_visible?: boolean }>;
+	issue_refs: string[];
+}
+
+/**
+ * Extract a {@link ConventionalAnalysis} from an assistant response, preferring
+ * a structured tool call and falling back to JSON embedded in text content.
+ */
+export function parseConventionalAnalysisResponse(
+	message: AssistantMessage,
+	tool: ConventionalAnalysisTool,
+): ConventionalAnalysis {
+	const toolCall = extractToolCall(message, tool.name);
+	if (toolCall) {
+		const parsed = validateToolCall([tool], toolCall) as z.infer<typeof conventionalAnalysisParameters>;
+		return normalizeAnalysis(parsed);
+	}
+	const text = extractTextContent(message);
+	const parsed = parseJsonPayload(text) as ParsedConventionalAnalysis;
+	return normalizeAnalysis(parsed);
+}

package/src/commit/types.ts

@@ -0,0 +1,118 @@
+/**
+ * Types for the omp commit pipeline.
+ */
+export type CommitType =
+	| "feat"
+	| "fix"
+	| "refactor"
+	| "perf"
+	| "docs"
+	| "test"
+	| "build"
+	| "ci"
+	| "chore"
+	| "style"
+	| "revert";
+
+export type ChangelogCategory =
+	| "Breaking Changes"
+	| "Added"
+	| "Changed"
+	| "Deprecated"
+	| "Removed"
+	| "Fixed"
+	| "Security";
+
+export const CHANGELOG_CATEGORIES: ChangelogCategory[] = [
+	"Breaking Changes",
+	"Added",
+	"Changed",
+	"Deprecated",
+	"Removed",
+	"Fixed",
+	"Security",
+];
+
+export interface CommitCommandArgs {
+	/** Push after commit */
+	push: boolean;
+	/** Preview without committing */
+	dryRun: boolean;
+	/** Skip changelog updates */
+	noChangelog: boolean;
+	/** Use legacy deterministic pipeline */
+	legacy?: boolean;
+	/** Additional user context for the model */
+	context?: string;
+	/** Override the model selection */
+	model?: string;
+}
+
+export interface NumstatEntry {
+	path: string;
+	additions: number;
+	deletions: number;
+}
+
+export interface ConventionalDetail {
+	text: string;
+	changelogCategory?: ChangelogCategory;
+	userVisible: boolean;
+}
+
+export interface ConventionalAnalysis {
+	type: CommitType;
+	scope: string | null;
+	details: ConventionalDetail[];
+	issueRefs: string[];
+}
+
+export interface CommitSummary {
+	summary: string;
+}
+
+export interface FileObservation {
+	file: string;
+	observations: string[];
+	additions: number;
+	deletions: number;
+}
+
+export interface FileDiff {
+	filename: string;
+	content: string;
+	additions: number;
+	deletions: number;
+	isBinary: boolean;
+}
+
+export interface DiffHunk {
+	index: number;
+	header: string;
+	oldStart: number;
+	oldLines: number;
+	newStart: number;
+	newLines: number;
+	content: string;
+}
+
+export interface FileHunks {
+	filename: string;
+	isBinary: boolean;
+	hunks: DiffHunk[];
+}
+
+export interface ChangelogBoundary {
+	changelogPath: string;
+	files: string[];
+}
+
+export interface UnreleasedSection {
+	startLine: number;
+	endLine: number;
+	entries: Record<string, string[]>;
+}
+
+export interface ChangelogGenerationResult {
+	entries: Record<string, string[]>;
+}

package/src/commit/utils/exclusions.ts

@@ -0,0 +1,42 @@
+const EXCLUDED_FILES = [
+	"Cargo.lock",
+	"package-lock.json",
+	"npm-shrinkwrap.json",
+	"yarn.lock",
+	"pnpm-lock.yaml",
+	"shrinkwrap.yaml",
+	"bun.lock",
+	"bun.lockb",
+	"deno.lock",
+	"composer.lock",
+	"Gemfile.lock",
+	"poetry.lock",
+	"Pipfile.lock",
+	"pdm.lock",
+	"uv.lock",
+	"go.sum",
+	"flake.lock",
+	"pubspec.lock",
+	"Podfile.lock",
+	"Packages.resolved",
+	"mix.lock",
+	"packages.lock.json",
+	"config.yml.lock",
+	"config.yaml.lock",
+	"settings.yml.lock",
+	"settings.yaml.lock",
+];
+
+const EXCLUDED_SUFFIXES = [".lock.yml", ".lock.yaml", "-lock.yml", "-lock.yaml"];
+
+export function isExcludedFile(path: string): boolean {
+	const lower = path.toLowerCase();
+	if (EXCLUDED_FILES.some(name => lower.endsWith(name.toLowerCase()))) {
+		return true;
+	}
+	return EXCLUDED_SUFFIXES.some(suffix => lower.endsWith(suffix));
+}
+
+export function filterExcludedFiles<T extends { filename: string }>(files: T[]): T[] {
+	return files.filter(file => !isExcludedFile(file.filename));
+}