gaunt-sloth-assistant 0.1.5 → 0.3.0

package/src/consoleUtils.ts

@@ -0,0 +1,33 @@
+import chalk from 'chalk';
+import { debug as systemDebug, error as systemError, log } from '#src/systemUtils.js';
+
+// TODO it seems like commander supports coloured output, maybe dependency to chalk can be removed
+
+export function displayError(message: string): void {
+  systemError(chalk.red(message));
+}
+
+export function displayWarning(message: string): void {
+  systemError(chalk.yellow(message));
+}
+
+export function displaySuccess(message: string): void {
+  systemError(chalk.green(message));
+}
+
+export function displayInfo(message: string): void {
+  systemError(chalk.blue(message));
+}
+
+export function display(message: string): void {
+  log(message);
+}
+
+export function displayDebug(message: string | Error | undefined): void {
+  // TODO make it controlled by config
+  if (message instanceof Error) {
+    systemDebug(message.stack || '');
+  } else if (message !== undefined) {
+    systemDebug(message);
+  }
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+import { Command } from 'commander';
+import { askCommand } from '#src/commands/askCommand.js';
+import { initCommand } from '#src/commands/initCommand.js';
+import { reviewCommand } from '#src/commands/reviewCommand.js';
+import { slothContext } from '#src/config.js';
+import { getSlothVersion } from '#src/utils.js';
+import { argv, readStdin } from '#src/systemUtils.js';
+import { setVerbose } from '#src/llmUtils.js';
+
+const program = new Command();
+
+program
+  .name('gsloth')
+  .description('Gaunt Sloth Assistant reviewing your PRs')
+  .version(getSlothVersion())
+  .option('--verbose', 'Print entire prompt sent to LLM.');
+
+// Parse global options before binding any commands
+program.parseOptions(argv);
+if (program.getOptionValue('verbose')) {
+  // Set global prompt debug
+  setVerbose(true);
+}
+
+initCommand(program);
+reviewCommand(program, slothContext);
+askCommand(program);
+// TODO add general interactive chat command
+
+await readStdin(program);

package/src/llmUtils.ts

@@ -0,0 +1,54 @@
+import type { Message, State } from '#src/modules/types.js';
+import { AIMessageChunk, HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import { END, MemorySaver, MessagesAnnotation, START, StateGraph } from '@langchain/langgraph';
+import { BaseLanguageModelCallOptions } from '@langchain/core/language_models/base';
+
+const llmGlobalSettings = {
+  verbose: false,
+};
+
+export async function invoke(
+  llm: BaseChatModel,
+  options: Partial<BaseLanguageModelCallOptions>,
+  systemMessage: string,
+  prompt: string
+): Promise<string> {
+  if (llmGlobalSettings.verbose) {
+    llm.verbose = true;
+  }
+  // This node receives the current state (messages) and invokes the LLM
+  const callModel = async (state: State): Promise<{ messages: AIMessageChunk }> => {
+    // state.messages will contain the list including the system systemMessage and user diff
+    const response = await (llm as BaseChatModel).invoke(state.messages);
+    // MessagesAnnotation expects the node to return the new message(s) to be added to the state.
+    // Wrap the response in an array if it's a single message object.
+    return { messages: response };
+  };
+
+  // Define the graph structure with MessagesAnnotation state
+  const workflow = new StateGraph(MessagesAnnotation)
+    // Define the node and edge
+    .addNode('model', callModel)
+    .addEdge(START, 'model') // Start at the 'model' node
+    .addEdge('model', END); // End after the 'model' node completes
+
+  // Set up memory (optional but good practice for potential future multi-turn interactions)
+  const memory = new MemorySaver();
+
+  // Compile the workflow into a runnable app
+  const app = workflow.compile({ checkpointer: memory });
+
+  // Construct the initial the messages including the systemMessage as a system message
+  const messages: Message[] = [new SystemMessage(systemMessage), new HumanMessage(prompt)];
+
+  const output = await app.invoke({ messages }, options);
+  const lastMessage = output.messages[output.messages.length - 1];
+  return typeof lastMessage.content === 'string'
+    ? lastMessage.content
+    : JSON.stringify(lastMessage.content);
+}
+
+export function setVerbose(debug: boolean) {
+  llmGlobalSettings.verbose = debug;
+}

package/src/modules/questionAnsweringModule.ts

@@ -0,0 +1,44 @@
+import { slothContext } from '#src/config.js';
+import { display, displayError, displaySuccess } from '#src/consoleUtils.js';
+import { getCurrentDir } from '#src/systemUtils.js';
+import { fileSafeLocalDate, ProgressIndicator, toFileSafeString } from '#src/utils.js';
+import { writeFileSync } from 'node:fs';
+import * as path from 'node:path';
+import { invoke } from '#src/llmUtils.js';
+
+/**
+ * Ask a question and get an answer from the LLM
+ * @param source - The source of the question (used for file naming)
+ * @param preamble - The preamble to send to the LLM
+ * @param content - The content of the question
+ */
+export async function askQuestion(
+  source: string,
+  preamble: string,
+  content: string
+): Promise<void> {
+  const progressIndicator = new ProgressIndicator('Thinking.');
+  const outputContent = await invoke(
+    slothContext.config.llm,
+    slothContext.session,
+    preamble,
+    content
+  );
+  progressIndicator.stop();
+  const filePath = path.resolve(
+    getCurrentDir(),
+    toFileSafeString(source) + '-' + fileSafeLocalDate() + '.md'
+  );
+  display(`\nwriting ${filePath}`);
+  // TODO highlight LLM output with something like Prism.JS (maybe system emoj are enough ✅⚠️❌)
+  display('\n' + outputContent);
+  try {
+    writeFileSync(filePath, outputContent);
+    displaySuccess(`This report can be found in ${filePath}`);
+  } catch (error) {
+    displayError(`Failed to write answer to file: ${filePath}`);
+    displayError(error instanceof Error ? error.message : String(error));
+    // TODO Consider if we want to exit or just log the error
+    // exit(1);
+  }
+}

package/src/modules/reviewModule.ts

@@ -0,0 +1,31 @@
+import { slothContext } from '#src/config.js';
+import { display, displayDebug, displayError, displaySuccess } from '#src/consoleUtils.js';
+import { getCurrentDir, stdout } from '#src/systemUtils.js';
+import { fileSafeLocalDate, ProgressIndicator, toFileSafeString } from '#src/utils.js';
+import { writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { invoke } from '#src/llmUtils.js';
+
+export async function review(source: string, preamble: string, diff: string): Promise<void> {
+  const progressIndicator = new ProgressIndicator('Reviewing.');
+  const outputContent = await invoke(slothContext.config.llm, slothContext.session, preamble, diff);
+  progressIndicator.stop();
+  const filePath = path.resolve(
+    getCurrentDir(),
+    toFileSafeString(source) + '-' + fileSafeLocalDate() + '.md'
+  );
+  stdout.write('\n');
+  display(`writing ${filePath}`);
+  stdout.write('\n');
+  // TODO highlight LLM output with something like Prism.JS (maybe system emoj are enough ✅⚠️❌)
+  display(outputContent);
+  try {
+    writeFileSync(filePath, outputContent);
+    displaySuccess(`This report can be found in ${filePath}`);
+  } catch (error) {
+    displayDebug(error instanceof Error ? error : String(error));
+    displayError(`Failed to write review to file: ${filePath}`);
+    // Consider if you want to exit or just log the error
+    // exit(1);
+  }
+}

package/src/modules/types.ts

@@ -0,0 +1,23 @@
+import type { BaseMessage } from '@langchain/core/messages';
+
+export type Message = BaseMessage;
+
+export interface State {
+  messages: Message[];
+}
+
+export interface ProgressCallback {
+  (): void;
+}
+
+export interface ReviewOptions {
+  source: string;
+  preamble: string;
+  diff: string;
+}
+
+export interface QuestionOptions {
+  source: string;
+  preamble: string;
+  content: string;
+}

package/src/prompt.ts

@@ -0,0 +1,54 @@
+import {
+  readFileFromCurrentDir,
+  readFileFromCurrentOrInstallDir,
+  spawnCommand,
+} from '#src/utils.js';
+import { displayError } from '#src/consoleUtils.js';
+import { exit } from '#src/systemUtils.js';
+import { GSLOTH_BACKSTORY } from '#src/config.js';
+
+export function readBackstory(): string {
+  return readFileFromCurrentOrInstallDir(GSLOTH_BACKSTORY, true);
+}
+
+export function readGuidelines(guidelinesFilename: string): string {
+  try {
+    return readFileFromCurrentDir(guidelinesFilename);
+  } catch (error) {
+    displayError(
+      'Consider running `gsloth init` to set up your project. Check `gsloth init --help` to see options.'
+    );
+    throw error;
+  }
+}
+
+export function readReviewInstructions(reviewInstructions: string): string {
+  return readConfigPromptFile(reviewInstructions);
+}
+
+function readConfigPromptFile(guidelinesFilename: string): string {
+  try {
+    return readFileFromCurrentOrInstallDir(guidelinesFilename);
+  } catch (error) {
+    displayError(
+      'Consider running `gsloth init` to set up your project. Check `gsloth init --help` to see options.'
+    );
+    throw error;
+  }
+}
+
+/**
+ * This function expects https://cli.github.com/ to be installed and authenticated.
+ * It does something like `gh pr diff 42`
+ */
+export async function getPrDiff(pr: string): Promise<string> {
+  // TODO makes sense to check if gh is available and authenticated
+  try {
+    return await spawnCommand('gh', ['pr', 'diff', pr], 'Loading PR diff...', 'Loaded PR diff.');
+  } catch (e) {
+    displayError(e instanceof Error ? e.toString() : String(e));
+    displayError(`Failed to call "gh pr diff ${pr}", see message above for details.`);
+    exit();
+    return ''; // This line will never be reached due to exit()
+  }
+}

package/src/providers/file.ts

@@ -0,0 +1,24 @@
+import { resolve } from 'node:path';
+import { display } from '#src/consoleUtils.js';
+import { readFileSyncWithMessages } from '#src/utils.js';
+import { getCurrentDir } from '#src/systemUtils.js';
+import type { ProviderConfig } from './types.js';
+
+/**
+ * Reads the text file from current dir
+ * @param _ config (unused in this provider)
+ * @param fileName
+ * @returns file contents
+ */
+export async function get(
+  _: ProviderConfig | null,
+  fileName: string | undefined
+): Promise<string | null> {
+  if (!fileName) {
+    return null;
+  }
+  const currentDir = getCurrentDir();
+  const filePath = resolve(currentDir, fileName);
+  display(`Reading file ${fileName}...`);
+  return readFileSyncWithMessages(filePath);
+}

package/src/providers/ghPrDiffProvider.ts

@@ -0,0 +1,20 @@
+import { displayWarning } from '#src/consoleUtils.js';
+import { execAsync } from '#src/utils.js';
+import type { ProviderConfig } from './types.js';
+
+/**
+ * Gets PR diff using gh command line tool
+ * @param _ config (unused in this provider)
+ * @param pr PR number
+ * @returns PR diff
+ */
+export async function get(
+  _: ProviderConfig | null,
+  pr: string | undefined
+): Promise<string | null> {
+  if (!pr) {
+    displayWarning('No PR provided');
+    return null;
+  }
+  return execAsync(`gh pr diff ${pr}`);
+}

package/src/providers/jiraIssueLegacyProvider.ts

@@ -0,0 +1,103 @@
+import { display, displayError, displayWarning } from '#src/consoleUtils.js';
+import { env } from '#src/systemUtils.js';
+import type { JiraLegacyConfig } from '#src/providers/types.js';
+
+interface JiraIssueResponse {
+  fields: {
+    summary: string;
+    description: string;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+/**
+ * Gets Jira issue using Atlassian REST API v2 with unscoped API token (aka Legacy Token)
+ * @param config Jira configuration
+ * @param issueId Jira issue ID
+ * @returns Jira issue content
+ */
+export async function get(
+  config: Partial<JiraLegacyConfig>,
+  issueId: string | undefined
+): Promise<string | null> {
+  if (!config) {
+    displayWarning('No Jira config provided');
+    return null;
+  }
+  if (!issueId) {
+    displayWarning('No issue ID provided');
+    return null;
+  }
+  if (!config.baseUrl) {
+    displayWarning('No Jira base URL provided');
+    return null;
+  }
+
+  // Get username from environment variable or config
+  const username = env.JIRA_USERNAME || config.username;
+  if (!username) {
+    throw new Error(
+      'Missing JIRA username. The username can be defined as JIRA_USERNAME environment variable or as "username" in config.'
+    );
+  }
+
+  // Get token from environment variable or config
+  const token = env.JIRA_LEGACY_API_TOKEN || config.token;
+  if (!token) {
+    throw new Error(
+      'Missing JIRA Legacy API token. The legacy token can be defined as JIRA_LEGACY_API_TOKEN environment variable or as "token" in config.'
+    );
+  }
+
+  try {
+    const issue = await getJiraIssue(
+      {
+        ...(config as JiraLegacyConfig),
+        username,
+        token,
+      },
+      issueId
+    );
+    if (!issue) {
+      return null;
+    }
+
+    const summary = issue.fields.summary;
+    const description = issue.fields.description;
+
+    return `Jira Issue: ${issueId}\nSummary: ${summary}\n\nDescription:\n${description}`;
+  } catch (error) {
+    displayError(
+      `Failed to get Jira issue: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return null;
+  }
+}
+
+/**
+ * Helper function to get Jira issue details
+ * @param config Jira configuration
+ * @param issueId Jira issue ID
+ * @returns Jira issue response
+ */
+async function getJiraIssue(config: JiraLegacyConfig, issueId: string): Promise<JiraIssueResponse> {
+  const auth = Buffer.from(`${config.username}:${config.token}`).toString('base64');
+  const url = `${config.baseUrl}${issueId}`;
+  if (config.displayUrl) {
+    display(`Loading Jira issue ${config.displayUrl}${issueId}`);
+  }
+  display(`Retrieving jira from api ${url.replace(/^https?:\/\//, '')}`);
+  const response = await fetch(url, {
+    headers: {
+      Authorization: `Basic ${auth}`,
+      Accept: 'application/json',
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch Jira issue from ${url} with status: ${response.statusText}`);
+  }
+
+  return response.json();
+}

package/src/providers/jiraIssueProvider.ts

@@ -0,0 +1,133 @@
+import { display, displayError, displayWarning } from '#src/consoleUtils.js';
+import { env } from '#src/systemUtils.js';
+import type { JiraConfig } from './types.js';
+
+interface JiraIssueResponse {
+  fields: {
+    summary: string;
+    description: string;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+/**
+ * Gets Jira issue using Atlassian REST API v3 with Personal Access Token
+ *
+ * TODO we need to figure out how would this work with public jira.
+ *
+ * @param config Jira configuration
+ * @param issueId Jira issue ID
+ * @returns Jira issue content
+ */
+export async function get(
+  config: Partial<JiraConfig> | null,
+  issueId: string | undefined
+): Promise<string | null> {
+  if (!config) {
+    displayWarning('No Jira config provided');
+    return null;
+  }
+  if (!issueId) {
+    displayWarning('No issue ID provided');
+    return null;
+  }
+
+  // Get username from environment variable or config
+  const username = env.JIRA_USERNAME || config.username;
+  if (!username) {
+    throw new Error(
+      'Missing JIRA username. The username can be defined as JIRA_USERNAME environment variable or as "username" in config.'
+    );
+  }
+
+  // Get token from environment variable or config
+  const token = env.JIRA_API_PAT_TOKEN || config.token;
+  if (!token) {
+    throw new Error(
+      'Missing JIRA PAT token. The token can be defined as JIRA_API_PAT_TOKEN environment variable or as "token" in config.'
+    );
+  }
+
+  // Get cloud ID from environment variable or config
+  const cloudId = env.JIRA_CLOUD_ID || config.cloudId;
+  if (!cloudId) {
+    throw new Error(
+      'Missing JIRA Cloud ID. The Cloud ID can be defined as JIRA_CLOUD_ID environment variable or as "cloudId" in config.'
+    );
+  }
+
+  try {
+    const issue = await getJiraIssue(
+      {
+        ...config,
+        username,
+        token,
+        cloudId,
+      },
+      issueId
+    );
+    if (!issue) {
+      return null;
+    }
+
+    const summary = issue.fields.summary;
+    const description = issue.fields.description;
+
+    return `Jira Issue: ${issueId}\nSummary: ${summary}\n\nDescription:\n${description}`;
+  } catch (error) {
+    displayError(
+      `Failed to get Jira issue: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return null;
+  }
+}
+
+/**
+ * Helper function to get Jira issue details using Atlassian REST API v3
+ * @param config Jira configuration
+ * @param jiraKey Jira issue ID
+ * @returns Jira issue response
+ */
+async function getJiraIssue(config: JiraConfig, jiraKey: string): Promise<JiraIssueResponse> {
+  // Jira Cloud ID can be found by authenticated user at https://company.atlassian.net/_edge/tenant_info
+
+  // According to doc https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-get permissions to read this resource:
+  // either Classic (RECOMMENDED) read:jira-work
+  // or Granular read:issue-meta:jira, read:issue-security-level:jira, read:issue.vote:jira, read:issue.changelog:jira, read:avatar:jira, read:issue:jira, read:status:jira, read:user:jira, read:field-configuration:jira
+  const apiUrl = `https://api.atlassian.com/ex/jira/${config.cloudId}/rest/api/3/issue/${jiraKey}`;
+  if (config.displayUrl) {
+    display(`Loading Jira issue ${config.displayUrl}${jiraKey}`);
+  }
+  display(`Retrieving jira from api ${apiUrl.replace(/^https?:\/\//, '')}`);
+
+  // Encode credentials for Basic Authentication header
+  const credentials = `${config.username}:${config.token}`;
+  const encodedCredentials = Buffer.from(credentials).toString('base64');
+  const authHeader = `Basic ${encodedCredentials}`;
+
+  // Define request headers
+  const headers = {
+    Authorization: authHeader,
+    Accept: 'application/json; charset=utf-8',
+    'Accept-Language': 'en-US,en;q=0.9', // Prevents errors in other languages
+  };
+
+  const response = await fetch(apiUrl, {
+    method: 'GET',
+    headers: headers,
+  });
+
+  if (!response?.ok) {
+    try {
+      const errorData = await response.json();
+      throw new Error(
+        `Failed to fetch Jira issue: ${response.statusText} - ${JSON.stringify(errorData)}`
+      );
+    } catch (_e) {
+      throw new Error(`Failed to fetch Jira issue: ${response?.statusText}`);
+    }
+  }
+
+  return response.json();
+}

package/src/providers/text.ts

@@ -0,0 +1,14 @@
+import type { ProviderConfig } from './types.js';
+
+/**
+ * Returns the provided text as is
+ * @param _ config (unused in this provider)
+ * @param text Text to return
+ * @returns The provided text
+ */
+export async function get(
+  _: ProviderConfig | null,
+  text: string | undefined
+): Promise<string | null> {
+  return text ?? null;
+}

package/src/providers/types.ts

@@ -0,0 +1,24 @@
+export interface ProviderConfig {
+  username?: string;
+  token?: string;
+  baseUrl?: string;
+  [key: string]: unknown;
+}
+
+export interface JiraLegacyConfig extends ProviderConfig {
+  username: string;
+  baseUrl: string;
+  displayUrl?: string;
+  token: string;
+}
+
+export interface JiraConfig extends ProviderConfig {
+  cloudId: string;
+  username: string;
+  displayUrl?: string;
+  token: string;
+}
+
+export interface Provider {
+  get: (config: ProviderConfig | null, id: string | undefined) => Promise<string | null>;
+}

package/src/systemUtils.ts

@@ -0,0 +1,90 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'url';
+import { Command } from 'commander';
+import { ProgressIndicator } from '#src/utils.js';
+
+/**
+ * This file contains all system functions and objects that are globally available
+ * but not imported directly, such as process.stdin, process.stdout, process.argv,
+ * process.env, process.cwd(), process.exit(), etc.
+ *
+ * By centralizing these in one file, we improve testability and make it easier
+ * to mock these dependencies in tests.
+ */
+
+interface InnerState {
+  installDir: string | null | undefined;
+  stringFromStdin: string;
+}
+
+const innerState: InnerState = {
+  installDir: undefined,
+  stringFromStdin: '',
+};
+
+// Process-related functions and objects
+export const getCurrentDir = (): string => process.cwd();
+export const getInstallDir = (): string => {
+  if (innerState.installDir) {
+    return innerState.installDir;
+  }
+  throw new Error('Install directory not set');
+};
+/**
+ * Cached string from stdin. Should only be called after readStdin completes execution.
+ */
+export const getStringFromStdin = (): string => {
+  return innerState.stringFromStdin;
+};
+export const exit = (code?: number): never => process.exit(code || 0);
+export const stdin = process.stdin;
+export const stdout = process.stdout;
+export const argv = process.argv;
+export const env = process.env;
+
+// noinspection JSUnusedGlobalSymbols
+/**
+ * Provide the path to the entry point of the application.
+ * This is used to set the install directory.
+ * This is called from index.js root entry point.
+ */
+export const setEntryPoint = (indexJs: string): void => {
+  const filePath = fileURLToPath(indexJs);
+  const dirPath = dirname(filePath);
+  innerState.installDir = resolve(dirPath);
+};
+
+/**
+ * Asynchronously reads the stdin and stores it as a string,
+ * it can later be retrieved with getStringFromStdin.
+ */
+export function readStdin(program: Command): Promise<void> {
+  return new Promise((resolvePromise) => {
+    if (stdin.isTTY) {
+      program.parseAsync().then(() => resolvePromise());
+    } else {
+      // Support piping diff into gsloth
+      const progressIndicator = new ProgressIndicator('reading STDIN', true);
+
+      stdin.on('readable', function (this: NodeJS.ReadStream) {
+        const chunk = this.read();
+        progressIndicator.indicate();
+        if (chunk !== null) {
+          const chunkStr = chunk.toString('utf8');
+          innerState.stringFromStdin = innerState.stringFromStdin + chunkStr;
+        }
+      });
+
+      stdin.on('end', function () {
+        program.parseAsync(argv).then(() => resolvePromise());
+      });
+    }
+  });
+}
+
+// Console-related functions
+export const log = (message: string): void => console.log(message);
+export const error = (message: string): void => console.error(message);
+export const warn = (message: string): void => console.warn(message);
+export const info = (message: string): void => console.info(message);
+export const debug = (message: string): void => console.debug(message);