jotbot

README

JotBot - AI-powered code documentation

JotBot auto-generates missing documentation for your Go and TypeScript codebase. The documentation of this repository was entirely generated by JotBot using gpt-4, so I encourage you to explore the source code to see the quality of the generated documentation.

You can find generated TypeScript documentation in packages/jotbot.

Quick Start

Install

go install github.com/modernice/jotbot/cmd/jotbot@latest

Add TypeScript Support

npm i -g jotbot-ts@latest
pnpm i -g jotbot-ts@latest

Use

Within your Go and/or TypeScript codebase, run:

jotbot generate --key OPENAI_API_KEY

---

Features

• Generate documentation for Go and TypeScript codebases
• Customize glob patterns for included and excluded files
• Filter code symbols by matching regular expressions
• Limit the number of files to generate documentation for
• Run in dry mode to preview changes without applying them
• Control the AI model and token limits used for generating documentation
• Optionally commit changes to a Git branch

Models

JotBot utilizes OpenAI's GPT models to generate documentation. By default, JotBot uses the gpt-3.5-turbo model which provides good results at a cost-effective rate. However, the best results are produced by gpt-4 and text-davinci-003, which are 10-30x more expensive than gpt-3.5-turbo.

You are free to choose any model from the OpenAI Docs and pass it via the --model|-m flag:

jotbot generate -m text-davinci-003

Installation

Via go install

If you have Go installed, you can simply install JotBot using go install:

go install github.com/modernice/jotbot/cmd/jotbot@latest

Standalone Binary

You can download the latest binary from the Releases page.

TypeScript Support

To enable TypeScript (and JavaScript) support, you also need to install the jotbot-ts npm package.

npm install -g jotbot-ts
pnpm install -g jotbot-ts

Usage

To generate missing documentation for your codebase, run the following command:

jotbot generate [options]

By default, this command will find all Go and TypeScript (and JavaScript) files in the current and nested directories and generate documentation for them. Excluded from the search are by default:

• **/.*/**
• **/dist/**
• **/node_modules/**
• **/vendor/**
• **/testdata/**
• **/test/**
• **/tests/**
• **/*.pb.go

To-Do

• Configurable OpenAI settings (temperature, top_p etc.)
• Any ideas? open an issue or start a discussion

CLI options

jotbot --help

Option	Description	Default
--root	Root directory of the repository	"."
--include, -i	Glob pattern(s) to include files
--include-tests, -T	Include TestXXX() functions (Go-specific)
--exclude, -e	Glob pattern(s) to exclude files
--exclude-internal, -E	Exclude 'internal' directories (Go-specific)	true
--match	Regular expression(s) to match identifiers
--symbol, -s	Symbol(s) to search for in code (TS/JS-specific)
--clear, -c	Force-clear comments in generation prompt (Go-specific)
--branch	Branch name to commit changes to (leave empty to not commit)
--limit	Limit the number of files to generate documentation for	0
--dry	Print the changes without applying them	false
--model, -m	OpenAI model used to generate documentation	"gpt-3.5-turbo"
--maxTokens	Maximum number of tokens to generate for a single documentation	512
--parallel, -p	Number of files to handle concurrently	4
--workers	Number of workers to use per file	2
--override, -o	Override existing documentation (Go-specific)
--key	OpenAI API key
--verbose, -v	Enable verbose logging	false

Screenshots

License

MIT

Documentation

Index

• type Finding
  • func (f Finding) String() string
• type JotBot
  • func New(root string, opts ...Option) *JotBot
  • func (bot *JotBot) ConfigureLanguage(name string, lang Language)
  • func (bot *JotBot) Extensions() []string
  • func (bot *JotBot) Find(ctx context.Context, opts ...find.Option) ([]Finding, error)
  • func (bot *JotBot) Generate(ctx context.Context, findings []Finding, svc generate.Service, ...) (*Patch, error)
• type Language
• type Option
  • func Match(filters ...*regexp.Regexp) Option
  • func WithLanguage(name string, lang Language) Option
  • func WithLogger(h slog.Handler) Option
• type Patch
  • func (p *Patch) Apply(ctx context.Context, root string) error
  • func (p *Patch) DryRun(ctx context.Context, root string) (map[string][]byte, error)

Types

type Finding

type Finding struct {
	Identifier string
	File       string
	Language   string
}

Finding represents an identifier found within a file and its associated language.

func (Finding) String

func (f Finding) String() string

String returns a formatted string representation of the Finding, containing the file name and identifier separated by an '@' symbol.

type JotBot

type JotBot struct {
	// contains filtered or unexported fields
}

JotBot is a tool for finding, generating, and patching code snippets in multiple programming languages. It supports customizable language configurations and can be extended with additional languages. JotBot can filter findings based on regular expressions, generate new code snippets using a provided generate.Service, and apply or dry-run patches to modify the source code.

func New

func New(root string, opts ...Option) *JotBot

New creates a new JotBot instance with the specified root directory and optional configurations. The returned JotBot can be used to find and generate code snippets based on configured languages and filters.

func (*JotBot) ConfigureLanguage

func (bot *JotBot) ConfigureLanguage(name string, lang Language)

ConfigureLanguage configures a Language for the given name and adds the language's file extensions to the mapping of extensions to languages.

func (*JotBot) Extensions

func (bot *JotBot) Extensions() []string

Extensions returns a slice of file extensions for which a language is configured in the JotBot instance.

func (*JotBot) Find

func (bot *JotBot) Find(ctx context.Context, opts ...find.Option) ([]Finding, error)

Find searches for files in the root directory of a JotBot instance, filters them by configured languages, and returns a slice of findings. Each finding includes the identifier, file path, and language name associated with the matched file. The search can be further customized using context and find options.

func (*JotBot) Generate

func (bot *JotBot) Generate(ctx context.Context, findings []Finding, svc generate.Service, opts ...generate.Option) (*Patch, error)

Generate creates a Patch by generating code for the given Findings using the provided generate.Service and options. It returns an error if there is any issue during code generation.

type Language

type Language interface {
	patch.Language
	generate.Language

	// Extensions returns a slice of file extensions supported by the configured
	// languages in the Language interface.
	Extensions() []string

	// Find searches the provided byte slice for language-specific identifiers and
	// returns a slice of found identifiers and an error if any occurs.
	Find([]byte) ([]string, error)
}

Language is an interface that combines the functionality of patch.Language and generate.Language, providing methods for file extension handling and finding identifiers in source code. It extends the capabilities of patching and generating code by allowing customization for different programming languages.

type Option

type Option func(*JotBot)

Option is a function that configures a JotBot instance. It takes a JotBot pointer as an argument and modifies its properties according to the desired configuration. Common options include WithLanguage, which associates a language with JotBot, and WithLogger, which sets up a logger for the JotBot instance.

func Match

func Match(filters ...*regexp.Regexp) Option

Match adds the provided regular expression filters to the JotBot instance, which are then used to filter identifiers found in files during the Find operation.

func WithLanguage

func WithLanguage(name string, lang Language) Option

WithLanguage configures a JotBot instance to use the specified Language implementation with the given name. The Language implementation is used for finding identifiers, generating code, and patching files with the corresponding file extension.

func WithLogger

func WithLogger(h slog.Handler) Option

WithLogger configures a JotBot to use the provided slog.Handler for logging.

type Patch

type Patch struct {
	*patch.Patch
	// contains filtered or unexported fields
}

Patch represents a set of changes to be applied to source code files. It provides methods for applying the changes directly or performing a dry run to preview the resulting files without modifying them. A Patch is created by generating code from a list of findings using a generate.Service and various generate.Option values.

func (*Patch) Apply

func (p *Patch) Apply(ctx context.Context, root string) error

Apply applies the patch to the files in the provided root directory. It returns an error if there is an issue applying the patch or accessing the file system.

func (*Patch) DryRun

func (p *Patch) DryRun(ctx context.Context, root string) (map[string][]byte, error)

DryRun applies the patch in a simulated environment without making actual changes to the files in the specified root directory, returning a map of filenames to their updated contents after applying the patch. It is useful for previewing changes before applying them.