jotbot

package module
v0.1.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 14, 2024 License: MIT Imports: 15 Imported by: 0

README

JotBot - AI-powered code documentation

Go Reference Test jotbot-ts

JotBot seamlessly auto-generates code documentation for your Go and TypeScript projects, bridging the gap between comprehensive code and insightful documentation.

The documentation of this repository was entirely generated by JotBot using gpt-4 but currently (2023/07/18) I get the best results using gpt-3.5-turbo.

OpenAI's gpt-3.5 and gpt-4 models demonstrate fluctuations in quality over time. Determining which model excels at any given instance can be challenging, but gpt-4 often yields more consistent results.

For general applications, I recommend using gpt-3.5-turbo-16k as a default, and temporarliy switching to gpt-4 in scenarios where gpt-3.5 might fall short.

gpt-4-1106-preview is the best model for generating documentation so far. The default model of JotBot is gpt-3.5-turbo which is gives the best value for money.

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

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

JotBot JotBot

License

MIT

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Finding added in v0.0.4 

type Finding struct {
	Identifier string
	File       string
	Language   string
}

Finding represents a discovered identifier within a particular file and programming language. It holds the unique identifier found, the file in which it was found, and the language of that file. The Finding type provides a way to reference specific code elements that have been identified during analysis or processing across various files and languages.

func (Finding) String added in v0.0.4 

func (f Finding) String() string

String provides a human-readable representation of a Finding, combining its File and Identifier properties in a formatted string.

type JotBot added in v0.0.4 

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

JotBot orchestrates the process of searching, analyzing, and transforming code across multiple programming languages within a specified directory structure. It leverages configurable language-specific behaviors to locate identifiers, generate updates, and apply patches based on findings. JotBot allows for flexible extension by registering different languages and can be customized through various options to match specific project needs. It provides methods to configure languages, find code patterns, generate code changes, and apply those changes as patches. Additionally, it supports logging for traceability of operations.

func New 

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

New initializes and returns a new instance of JotBot configured with the provided root directory and options.

func (*JotBot) ConfigureLanguage added in v0.0.4 

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

ConfigureLanguage associates a given language with its name and file extensions within the JotBot instance. It enables the JotBot to recognize files of this language by their extensions when performing operations such as finding identifiers or generating patches.

func (*JotBot) Extensions added in v0.0.4 

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

Extensions returns a slice of all file extensions that are associated with configured languages within the JotBot instance. These extensions can be used to filter files for processing based on the languages that the JotBot is capable of handling.

func (*JotBot) Find added in v0.0.4 

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

Find performs a search for identifiers within the files of a repository based on the configured languages and file extensions. It accepts a context and variadic find options to customize the search behavior. The function returns a slice of Findings, which contain the identifier, file, and language of each found item, or an error if the search could not be completed. The Findings are sorted by file and then by identifier. If filters are configured, only findings matching those filters are included in the results.

func (*JotBot) Generate added in v0.0.4 

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

Generate creates a patch based on the provided findings and generation service, applying additional options if specified. It processes each finding to prepare the input for the generator, then invokes the generator to create file patches. On success, it returns a *Patch that encapsulates the generated patches along with any errors that occurred during generation. If an error is encountered during the preparation of inputs or generation process, it returns an error detailing the failure.

type Language added in v0.0.4 

type Language interface {
	patch.Language
	generate.Language

	// Extensions reports the file extensions associated with a language. These
	// extensions typically do not include the leading dot.
	Extensions() []string

	// Find locates and returns all identifiers within a given byte slice according
	// to the rules of the implementing language, or an error if the search cannot
	// be completed. It returns a slice of strings representing the found
	// identifiers and an error, if any occurred during the search process.
	Find([]byte) ([]string, error)
}

Language represents a programming language with the ability to describe itself, such as providing its file extensions and identifying code patterns within its syntax. It integrates with patching and code generation systems, allowing for modifications and enhancements of code written in the language it represents. It also offers methods to locate identifiers within a body of text, aiding in various analysis and automation tasks.

type Option 

type Option func(*JotBot)

Option configures a *JotBot instance with custom settings, such as specifying languages to recognize, logging behavior, or file matching patterns. It is used when creating a new *JotBot or adjusting its configuration at runtime. Each Option is a function that applies a specific configuration to the *JotBot.

func Match added in v0.0.4 

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

Match configures a JotBot with custom filters for identifying relevant findings. It accepts a variable number of regular expressions that are used to filter the search results when finding identifiers within files. The provided filters are appended to any existing filters the JotBot may have.

func WithLanguage added in v0.0.4 

func WithLanguage(name string, lang Language) Option

WithLanguage configures a JotBot instance to use a specified language with an associated name. It allows the JotBot to recognize and handle files that pertain to the given language during its operations. This configuration is done through an option that can be passed to the JotBot constructor.

func WithLogger 

func WithLogger(h slog.Handler) Option

WithLogger configures a JotBot instance to use the provided slog.Handler for logging operations. It returns an Option which, when applied, sets up the internal logger of the JotBot with the specified handler.

type Patch added in v0.0.4 

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

Patch applies modifications across a collection of files within a specified root directory. It leverages a provided callback to determine the language-specific behaviors required for each file based on its extension, ensuring that patches are applied correctly according to language rules and syntax. Patch also supports a dry run mode that simulates the patch application, returning a map of the proposed changes without altering the original files, allowing for pre-application review and validation.

func (*Patch) Apply added in v0.0.4 

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

Apply applies the patch to the files within the specified root directory. It takes a context and a string representing the root directory path as arguments and returns an error if the patch cannot be applied. The operation respects the context cancellation and will abort if the context is canceled.

func (*Patch) DryRun added in v0.0.4 

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

DryRun simulates the application of the patch to the given root directory without making actual changes, and returns a map of file paths to their new content as it would appear after applying the patch. It accepts a context for cancellation and deadline control, and requires the root directory as an argument. The function returns an error if any issues occur during the dry run process.

Source Files

View all Source files

Directories

Path Synopsis
cmd
jotbot
mockgenerate
generate
git
git/gittest
nodes
patch
slice
tests
langs
golang
ts
services
openai
tools
reset

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.