gennady 0.3.0 → 0.5.1-next.1

package/README.md

@@ -3,11 +3,103 @@
 **GEN**erate **N**ext-level **A**utomated **D**escription **Y**ntelligence.
 
 ```bash
+# Commit message
 npx gennady
+
+# Code review for critical issues
+npx gennady review
+
+# Quickly display the contents
+npx gennady cat <path1> <path2> ...
 ```
 
 ---
 
+### ✨ Features
+
+- 🤖 [**Commit Message**](#-commit-messages): Automatically generate clear, descriptive git commit messages from your staged changes.
+- 📝 [**review**](#-review): Instantly review your staged git changes for critical issues (logic, runtime, security).
+- 🐱 [**cat**](#-cat): Quickly display the contents of multiple files or directories at once, filtered by allowed extensions (default: .js, .ts, .tsx).
+- 🛠️ **TypeScript Support**: Full TypeScript type definitions for seamless integration into TypeScript projects.
+
+---
+
+## 🔖 Usage Overview
+
+Gennady provides several main CLI commands:
+- `npx gennady` — Generate commit messages from your staged git changes.
+- `npx gennady cat <path1> <path2> ...` — Display the contents of one or more files or directories, filtered by allowed extensions.
+- `npx gennady review` — Review your staged git changes for critical issues.
+
+---
+
+## 🤖 Commit Messages
+
+```sh
+# Basic usage
+npx gennady
+
+# Generate oneline commit message
+npx gennady --mode=oneline
+
+# Generate detailed commit message
+npx gennady --mode=detailed
+
+# Generate detailed commit message relative to the target branch
+npx gennady --branch=develop
+```
+
+### Options
+| Option            | Alias(es)        | Description                                  |
+|-------------------|------------------|----------------------------------------------|
+| `--mode`          | `-m`             | Set the mode (`auto`, `oneline`, `detailed`) |
+| `--oneline`       | `--short`, `-o`  | Generate a one-line commit message           |
+| `--model`         |                  | Specify the AI model                         |
+| `--branch`        | `-b`             | Target branch for diff                       |
+| `--apply`         |                  | Immediately apply the generated commit message to git |
+
+
+#### What Happens?
+- Gennady analyzes your staged changes.
+- It generates a commit message.
+- If your system language isn't English, it translates the message for you.
+
+---
+
+
+## 📝 review
+
+Review your staged git changes for critical issues.
+
+```sh
+npx gennady review
+
+# Review changes relative to a specific branch
+npx gennady review --branch=develop
+```
+
+#### What Happens?
+- Gennady analyzes your staged changes.
+- It checks only the lines added or modified in your diff for critical issues (logic, runtime, and security errors).
+- If no critical issues are found, it outputs `GOOD`.
+- If issues are found, they are listed in a clear, structured format.
+
+---
+
+## 🐱 cat
+
+Display the contents of files or directories (with filtering for allowed extensions).
+
+```sh
+npx gennady cat ./src/
+```
+
+#### Output
+- Shows file contents with headers per file.
+- Hints for copying output without color codes.
+
+---
+
 ## Setup LLM
 
 ### Local
@@ -22,32 +114,72 @@ ollama serve
 
 ### External
 
-Create `~/.gennadyrc` file:
+Create `~/.gennadyrc` configuration file:
 
 ```json
-[
-    {
-        "url": "https://api.openai.com/v1/chat/completions",
-        "key": "...",
-        "model": "gpt-4o"
-    }
-]
+{
+    "models": [
+        {
+            "model": "gpt-3.5-turbo-0125",
+            "url": "https://api.openai.com/v1/chat/completions",
+            "key": "...",
+        },
+        {
+            "model": "llama3:8b",
+            "url": "http://127.0.0.1:11434/api/generate",
+        }
+    ]
+}
 ```
 
 ---
 
-### Usage
+## 🔌 API
+
+Gennady provides a powerful JavaScript/TypeScript API for programmatic usage in your projects.
+
+### Installation
 
 ```bash
-# Basic usage
-npx gennady
+npm install gennady
+```
 
-# Generate oneline commit message
-npx gennady --mode=oneline
+### Basic Usage
 
-# Generate detailed commit message
-npx gennady --mode=detailed
+```typescript
+import { GennadyRc } from 'gennady/src/rc/rc-config';
+import { AiModel } from 'gennady/src/ai/ai-model';
 
-# Generate detailed commit message relative to the target branch
-npx gennady --branch=develop
-```
+// Load configuration
+const rc = new GennadyRc();
+
+// Get available AI models
+const models = rc.getModels();
+
+// Create AI model instance
+const aiModel = new AiModel(models[0]);
+
+// Generate text
+const [response, error] = await aiModel.generate('Hello, world!', {
+    temperature: 0.7,
+    timeout: 10000
+});
+
+if (error) {
+    console.error('Error:', error);
+} else {
+    console.log('Response:', response);
+}
+```
+
+### Available Modules
+
+- `AiModel`: Core AI model interaction
+- `GennadyRc`: Configuration management
+- `unguard`: Utility functions for error handling
+
+For complete API documentation, check the source code with detailed JSDoc comments.
+
+## 🎉 Happy Coding with Gennady!
+
+> Made with 🤖 by Konstantin Lebedev

package/cli/cmd/cat.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import path from 'path';
+import { catGen } from '../../src/cat-gen/cat-gen.js';
+import { style } from '../../src/utils/style.js';
+import { parseArgs } from '../../src/utils/parse-args.js';
+
+//
+// 🐱 CAT-GEN
+//
+const args = parseArgs(process.argv);
+
+if (args._.length === 0) {
+	console.error(style.yellow('Usage: npx gennady cat <path1> <path2> ...'));
+	process.exit(1);
+}
+
+catGen(args._).forEach(({ relativePath, content }) => {
+	console.log(style.blue(`#### ${relativePath}`));
+	console.log(content);
+	console.log('');
+});
+
+console.log(style.green(`^`.repeat(40)));
+console.log(style.italic.gray(`Hint: npx gennady cat ${process.argv.slice(3).join(' ')} --plain | pbcopy`));
+console.log('');

package/cli/cmd/commit.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { CommitGen } from '../../src/commit-gen/commit-gen.js';
+import { parseArgs } from '../../src/utils/parse-args.js';
+import { style } from '../../src/utils/style.js';
+import { getSysLang } from '../../src/utils/language.js';
+
+//
+// 🤖 COMMIT-GEN 💬
+//
+
+const CACHE_PATH = path.join(os.homedir(), '.gennady_commit_cache.json');
+const PROJECT_KEY = process.cwd();
+const COMMIT_CACHE = readCache();
+
+const params = parseArgs(process.argv, {
+	apply: ['apply'],
+	mode: ['mode', 'm'],
+	oneline: ['short', 'one', 'o'],
+	model: ['model'],
+	targetBranch: ['branch', 'b'],
+	apiUrl: ['api', 'apiUrl'],
+});
+
+const commitGen = new CommitGen(params);
+
+console.info(
+	'🤖',
+	style.whiteBright.bold('GENNADY'),
+	`(${style.cyan(commitGen.model)} → ${style.yellow(commitGen.mode)})`,
+	'🗯️',
+);
+
+console.info(style.gray('-'.repeat(40)));
+console.info(`- url: ${style.blue(commitGen.apiUrl)}`);
+console.info(style.gray('-'.repeat(40)));
+
+const commitMessage = params.apply && COMMIT_CACHE[PROJECT_KEY] || await commitGen.generate();
+if (!commitMessage) {
+	process.exit(0);
+}
+
+if (params.apply) {
+	// APPLY COMMIT
+	execSync(
+		`git commit -am "${commitMessage.replace(/"/g, '\"')}"`,
+		{stdio: 'inherit'},
+	);
+	saveCache({ [PROJECT_KEY]: undefined });
+} else {
+	// GENERATE COMMIT
+	console.info('-'.repeat(40), '\n');
+	console.info(style.whiteBright(commitMessage), '\n');
+	console.info('^'.repeat(40), '\n');
+
+	const lang = getSysLang();
+	if (lang !== 'en') {
+		console.info(await commitGen.translate(commitMessage, lang), '\n');
+		console.info('^'.repeat(40), '\n');
+	}
+
+	console.log(style.italic.gray(`Hint: npx gennady ${process.argv.slice(3).join(' ')} --apply`));
+	console.log('');
+
+	saveCache({ [PROJECT_KEY]: commitMessage });
+}
+
+function readCache() {
+	try {
+		return JSON.parse(fs.readFileSync(CACHE_PATH, 'utf8'));
+	} catch {
+		return {};
+	}
+}
+
+function saveCache(patch) {
+	const next = { ...COMMIT_CACHE, ...patch };
+	fs.writeFileSync(CACHE_PATH, JSON.stringify(next, null, 2));
+}

package/cli/cmd/review.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+import { getGitDiffInfo } from '../../src/git/git-core.js';
+import { ReviewGen } from '../../src/review-gen/review-gen.js';
+import { parseArgs } from '../../src/utils/parse-args.js';
+import { style } from '../../src/utils/style.js';
+
+//
+// 📝 REVIEW-GEN
+//
+
+const params = parseArgs(process.argv, {
+	branch: ['branch', 'b'],
+});
+
+const review = new ReviewGen();
+
+console.info(
+	`🤖`,
+	style.whiteBright.bold(`GENNADY`),
+	`(${style.cyan(review.ai.model)})`,
+	`📝`,
+);
+
+console.info(style.gray(`-`.repeat(40)));
+
+const {
+	parsedCodeDiff,
+	parsedCodeTokens,
+	programmingLanguages,
+	parsedCodeChunkMaxTokens,
+} = getGitDiffInfo(params.branch);
+
+console.info(`- Tokens: ${style.bold.cyanBright(parsedCodeTokens)} ${style.gray(`(max per file: ${parsedCodeChunkMaxTokens})`)}`);
+console.info(`- Languages: ${style.yellow(programmingLanguages)}`);
+
+if (parsedCodeDiff.length === 0) {
+	console.info(`No changes detected, skipping review.`);
+	console.info(style.italic.gray(`Hint: git add`));
+	process.exit(0);
+}
+
+const batches = review.ai.createPromptsBatchesByDiff(parsedCodeDiff);
+
+console.info(`- Queue: ${style.bold.cyan(batches.length)}`);
+console.info(style.gray(`-`.repeat(40)));
+
+const startGenTime = performance.now();
+const results = await Promise.all(batches.map(async (batch) => {
+	console.info(`- Task:`, batch.tokens, batch.languages);
+	return await review.generate(batch.diff, batch.languages);
+}));
+
+console.info(style.gray(`-`.repeat(40)));
+console.info(`- Generation time: ${style.blueBright(((performance.now() - startGenTime) / 1000).toFixed(2))}s`);
+console.info(style.gray(`-`.repeat(40)));
+
+console.info(results.join('\n\n'));

package/cli/gennady.js

@@ -1,48 +1,24 @@
 #!/usr/bin/env node
 
-import { readFileSync } from 'fs';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-import { CommitGen } from '../src/commit-gen/commit-gen.js';
-import { parseArgs } from '../src/utils/parse-args.js';
-import { style } from '../src/utils/style.js';
-import { getSysLang } from '../src/utils/language.js';
+switch(process.argv[2]) {	
+	//
+	// 🐱 CAT-GEN
+	//
+	case 'cat':
+		import('./cmd/cat.js');
+		break;
 
-const PROMPTS_DIR = join(
-	typeof __dirname !== 'string' ? dirname(fileURLToPath(import.meta.url)) : __dirname,
-	'../src/prompts',
-);
+	//
+	// 📝 REVIEW-GEN
+	//
+	case 'review':
+		import('./cmd/review.js');
+		break;
 
-const params = parseArgs(process.argv, {
-	mode: ['mode', 'm'],
-	oneline: ['short', 'one', 'o'],
-	model: ['model'],
-	targetBranch: ['branch', 'b'],
-	apiUrl: ['api', 'apiUrl'],
-});
-
-const commit = new CommitGen({
-	...params,
-	basePromptTemplate: readFileSync(join(PROMPTS_DIR, 'base-prompt.md')).toString(),
-	formatOnelinePromptTemplate: readFileSync(join(PROMPTS_DIR, 'format-oneline-prompt.md')).toString(),
-	formatDetailedPromptTemplate: readFileSync(join(PROMPTS_DIR, 'format-detailed-prompt.md')).toString(),
-	translatePromptTemplate: readFileSync(join(PROMPTS_DIR, 'translate-prompt.md')).toString(),
-});
-
-console.info(`🤖`, style.whiteBright.bold(`GENNADY`), `(${style.cyan(commit.model)} → ${style.yellow(commit.mode)})`, `🗯️`);
-console.info(style.gray(`-`.repeat(30)));
-console.info(`- url: ${style.blue(commit.apiUrl)}`);
-console.info(style.gray(`-`.repeat(30)));
-
-const msg = await commit.generate();
-if (msg) {
-	console.info(`-`.repeat(40), '\n');
-	console.info(style.whiteBright(msg), '\n');
-	console.info(`^`.repeat(40), '\n');
-
-	const lang = getSysLang();
-	if (lang !== 'en') {
-		console.info(await commit.translate(msg, lang), '\n');
-		console.info(`^`.repeat(40), '\n');
-	}
+	//
+	// 🤖 COMMIT-GEN 💬
+	//
+	default:
+		import('./cmd/commit.js');
+		break;
 }

package/index.d.ts

@@ -0,0 +1,3 @@
+export * from './src/ai/ai-model';
+export * from './src/rc/rc-config';
+export * from './src/utils/unguard';

package/index.js

@@ -1 +1,7 @@
+export * from './src/ai/ai-model.js';
+export * from './src/rc/rc-config.js';
+export * from './src/utils/unguard.js';
+
 export * from './src/commit-gen/commit-gen.js';
+export * from './src/git/git-diff.js';
+export * from './src/utils/language.js';

package/llm.md

@@ -0,0 +1,82 @@
+# Gennady API: Using AiModel.generate
+
+This guide demonstrates best practices for calling `AiModel.generate` and handling its results, particularly when using TypeScript.
+
+## 1. Basic Usage of `AiModel.generate`
+
+The `AiModel.generate` method returns a Promise that resolves to a tuple: `[result, error]`. You need to handle both potential outcomes.
+
+### ✅ GOOD: Handling the Result Tuple
+
+This example assumes `aiModel` is an initialized instance of `AiModel`.
+
+```typescript
+import { AiModel } from 'gennady/src/ai/ai-model';
+
+async function generateTextWithTupleHandling(aiModel: AiModel, prompt: string) {
+    const [response, error] = await aiModel.generate(prompt, {
+        temperature: 0.7,
+        timeout: 10000, // Optional: timeout in milliseconds
+    });
+    if (error) {
+        throw new Error(`[GENERATE_TEXT_WITH_TUPLE_ERROR] [${aiModel.name}] Generate failed`, {cause: error})
+    }
+
+    return response;
+}
+```
+**Reasoning:** This approach explicitly checks for an error before attempting to use the response. This is the fundamental way to interact with functions designed with this tuple-based error handling pattern.
+
+## 2. Using `AiModel.generate` with `unguardOrThrow` for Cleaner Code
+
+For scenarios where you want to simplify error handling and prefer exceptions for the error path, especially in a sequence of operations, `unguardOrThrow` is recommended.
+
+### ❌ BAD: Multiple Manual Error Checks in Sequential Operations
+
+```typescript
+// ... imports and aiModel initialization ...
+async function sequentialGenerationBad(aiModel: AiModel) {
+    const [response1, error1] = await aiModel.generate("First prompt");
+    if (error1) {
+        throw new Error(`[SEQUENTIAL_GENERATION_BAD_ERROR_1] [${aiModel.name}] Generate failed`, {cause: error1})
+    }
+    console.log("First response:", response1);
+
+    const [response2, error2] = await aiModel.generate("Second prompt using: " + response1.substring(0, 20));
+    if (error2) {
+        throw new Error(`[SEQUENTIAL_GENERATION_BAD_ERROR_2] [${aiModel.name}] Generate failed`, {cause: error2})
+    }
+    console.log("Second response:", response2);
+    // ... and so on
+}
+```
+**Reasoning:** This becomes verbose and repetitive. Each step requires its own error check and handling logic, making the main flow harder to read.
+
+### ✅ GOOD: Using `unguardOrThrow` for Concise Sequential Operations
+
+```typescript
+import { AiModel } from 'gennady/src/ai/ai-model';
+import { unguardOrThrow } from 'gennady/src/utils/unguard';
+
+async function sequentialGenerationGood(aiModel: AiModel) {
+    try {
+        console.log("Attempting first generation...");
+        const response1 = await unguardOrThrow(aiModel.generate("Write a short poem about coding."));
+        console.log("First response:\n", response1);
+
+        console.log("\nAttempting second generation based on the first...");
+        const response2 = await unguardOrThrow(aiModel.generate(`Write a haiku based on this line: "${response1.split('\n')[0]}"`));
+        console.log("Second response (haiku):\n", response2);
+
+        // You can continue the chain of operations here
+        // const response3 = await unguardOrThrow(aiModel.generate(...));
+
+    } catch (error) {
+        throw new Error(`[SEQUENTIAL_GENERATION_GOOD_ERROR] [${aiModel.name}] Generate failed`, {cause: error})
+    }
+}
+```
+**Reasoning:** `unguardOrThrow` unwraps the success value or throws the error if present. This allows you to write cleaner, more linear code for the success path and handle all errors in a single `catch` block. This is particularly useful for chained asynchronous operations where an error at any point should halt the entire chain.
+
+---
+Remember to always initialize `AiModel` with valid configuration, typically loaded via `GennadyRc`. The examples above focus on the `generate` call itself, assuming `aiModel` is ready.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gennady",
-  "version": "0.3.0",
+  "version": "0.5.1-next.1",
   "author": "Konstantin Lebedev <ibnrubaxa@gmail.com>",
   "description": "Gennady — Generate Next-level Automated Description Yntelligence",
   "keywords": [
@@ -10,14 +10,17 @@
     "local",
     "commit",
     "generator",
-    "gennady"
+    "gennady",
+    "review",
+    "code-review"
   ],
   "license": "MIT",
   "repository": "https://github.com/rubaxa/gennady",
   "type": "module",
   "bin": "./cli/gennady.js",
   "main": "index.js",
+  "types": "index.d.ts",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test"
   }
 }

package/src/ai/ai-core.js

@@ -0,0 +1,116 @@
+import { AiModel } from './ai-model.js';
+import { GennadyRc } from '../rc/rc-config.js';
+import { unguardOrThrow } from '../utils/unguard.js';
+
+/** @deprecated */
+export class AiCore {
+	/**
+	 * List of AI Models
+	 * @type {AiModel[]} array of #AI_MODEL_CLASS
+	 */
+	#models = [];
+
+	/**
+	 * Active AI Model
+	 * @type {AiModel|null}
+	 */
+	#activeModel = null;
+
+	constructor(init) {
+		this.init = {
+			logger: console,
+			timeout: 120,
+			maxInputTokens: init.maxInputTokens || 4000,
+			...init,
+		};
+
+		GennadyRc.getDefaults().forEach((rc) => {
+			if (rc.isValid()) {
+				this.#models.push(...rc.getModels().map(model => new AiModel(model)));
+			}
+		});
+
+		if (!this.#models.length) {
+			this.#models.push(AiModel.getDefault());
+		}
+	}
+
+	get model() {
+		return this.#models[0]?.name;
+	}
+
+	get apiUrl() {
+		return this.#models[0]?.url
+	}
+
+	get maxInputTokens() {
+		return this.init.maxInputTokens;
+	}
+
+	get logger() {
+		return this.init.logger;
+	}
+
+	createPromptsBatchesByDiff(parseDiff) {
+		const maxChunkTokens = parseDiff.at(-1)?.tokens || 0
+
+		if (maxChunkTokens > this.maxInputTokens) {
+			this.logger.error(`TODO: Diff is too large`);
+			process.exit(1);
+		}
+
+		const batches = parseDiff.reduce((acc, file) => {
+			if (!acc[0] || acc[0].tokens + file.tokens > this.maxInputTokens) {
+				acc.unshift({tokens: 0, diff: '', languages: []});
+			}
+
+			const fileDiff = file.diff.hunks.flatMap(h => h.changes).join('\n');
+			if (fileDiff.trim()) {
+				acc[0].tokens += file.tokens;
+				acc[0].diff += `### File **${file.filename}**:\n${fileDiff}\n\n`;
+				
+				if (!acc[0].languages.includes(file.programmingLanguage)) {
+					acc[0].languages.push(file.programmingLanguage);
+				}
+			}
+
+			return acc;
+		}, []);
+
+		return batches;
+	}
+
+	async generate(prompt, context) {
+		try {
+			const model = await unguardOrThrow(this.#choiceModel());
+			const result = await unguardOrThrow(model.generate(prompt, context));
+			return result;
+		} catch (error) {
+			this.logger.error(`[AI_CORE_ERROR_GENERATE] Failed to generate LLM response:`, error);
+			return '';
+		}
+	}
+
+	/**
+	 * Choose active model
+	 * @anchor AI_CORE_CHOICE_MODEL
+	 * @returns {Promise<[AiModel, null] | [null, Error]>}
+	 */
+	async #choiceModel() {
+		if (this.#activeModel) {
+			return [this.#activeModel, null];
+		}
+
+		for (const model of this.#models) {
+			const [ok, error] = await model.ping();
+			if (ok) {
+				this.#activeModel = model;
+				return [model, null];
+			} else {
+				this.logger.warn(`[AI_CORE_ERROR_PING_MODEL_FAIL] [${model.name}] Ping failed:`, error);
+			}
+		}
+
+		return [null, new Error(`[AI_CORE_ERROR_PING_FAIL] No available models`)];
+	}
+}