codetyper.nvim/CONTRIBUTING.md

Contributing to Codetyper.nvim

Thank you for considering contributing to Codetyper.nvim!

Table of Contents

• Code of Conduct
• Getting Started
• Development Setup
• Project Structure
• Making Changes
• Submitting Changes
• Style Guide
• Testing
• Questions

Code of Conduct

This project and everyone participating in it is governed by our commitment to creating a welcoming and inclusive environment. Please be respectful and constructive in all interactions.

Getting Started

1. Fork the repository
2. Clone your fork locally
3. Set up the development environment
4. Create a branch for your changes
5. Make your changes
6. Submit a pull request

Development Setup

Prerequisites

• Neovim >= 0.8.0
• Lua 5.1+ or LuaJIT
• Git
• One of: GitHub Copilot (via copilot.lua/copilot.vim) or Ollama

Local Development

1. Clone the repository:

   git clone https://github.com/CarGDev/codetyper.nvim.git
   cd codetyper.nvim
   

2. Create a minimal test configuration:

   -- tests/minimal_init.lua
   vim.opt.runtimepath:append(".")
   require("codetyper").setup({
     llm = {
       provider = "ollama",
     },
   })
   

3. Test your changes:

   nvim --clean -u tests/minimal_init.lua
   

4. Run the full test suite:

   make test
   

Project Structure

codetyper.nvim/
├── lua/codetyper/
│   ├── init.lua                         # Entry point, setup()
│   ├── inject.lua                       # Code injection into buffers
│   ├── parser.lua                       # /@ @/ tag parser
│   ├── types.lua                        # Lua type annotations
│   │
│   ├── config/
│   │   ├── defaults.lua                 # Default configuration values
│   │   ├── credentials.lua              # Credential & model storage
│   │   └── preferences.lua              # User preference persistence
│   │
│   ├── adapters/nvim/
│   │   ├── autocmds.lua                 # Autocommands (prompt processing)
│   │   ├── commands.lua                 # All :Coder* user commands
│   │   ├── cmp/init.lua                 # nvim-cmp source integration
│   │   └── ui/
│   │       ├── thinking.lua             # Status window ("Thinking...")
│   │       ├── throbber.lua             # Animated spinner
│   │       ├── logs.lua                 # Internal log viewer
│   │       ├── logs_panel.lua           # Standalone logs panel
│   │       ├── context_modal.lua        # File-context picker
│   │       └── diff_review.lua          # Side-by-side diff review
│   │
│   ├── core/
│   │   ├── transform.lua                # Visual selection -> prompt -> apply
│   │   ├── marks.lua                    # Extmark tracking for injection
│   │   ├── thinking_placeholder.lua     # Inline virtual text status
│   │   ├── scope/init.lua              # Tree-sitter + indent scope
│   │   ├── intent/init.lua             # Prompt intent classifier
│   │   ├── llm/
│   │   │   ├── init.lua                 # Provider dispatcher
│   │   │   ├── copilot.lua              # GitHub Copilot client
│   │   │   ├── ollama.lua               # Ollama client (local)
│   │   │   ├── confidence.lua           # Response confidence scoring
│   │   │   └── selector.lua             # Provider selection logic
│   │   ├── diff/
│   │   │   ├── diff.lua                 # Diff utilities
│   │   │   ├── patch.lua                # Patch generation + staleness
│   │   │   ├── conflict.lua             # Git-style conflict resolution
│   │   │   └── search_replace.lua       # SEARCH/REPLACE block parser
│   │   ├── events/queue.lua             # Priority event queue
│   │   ├── scheduler/
│   │   │   ├── scheduler.lua            # Event dispatch orchestrator
│   │   │   ├── worker.lua               # Async LLM worker
│   │   │   ├── executor.lua             # Tool execution
│   │   │   ├── loop.lua                 # Processing loop
│   │   │   └── resume.lua               # Session resume
│   │   ├── cost/init.lua               # Token usage + cost estimation
│   │   └── memory/                      # Knowledge graph & pattern learning
│   │
│   ├── features/
│   │   ├── completion/                  # Inline completion & suggestions
│   │   └── indexer/                     # Project indexing & analysis
│   │
│   ├── support/
│   │   ├── utils.lua                    # General utilities
│   │   ├── logger.lua                   # Logging system
│   │   ├── tree.lua                     # Project tree generator
│   │   ├── health.lua                   # :checkhealth provider
│   │   ├── gitignore.lua                # .gitignore management
│   │   └── langmap.lua                  # Language detection
│   │
│   ├── params/agents/                   # Config tables for subsystems
│   └── prompts/                         # System & agent prompts
│
├── plugin/codetyper.lua                 # Plugin loader
├── doc/codetyper.txt                    # Vim help documentation
├── doc/tags                             # Help tags
├── tests/                               # Test suite
├── Makefile                             # Build/test/lint targets
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
└── llms.txt                             # LLM context documentation

Making Changes

Branch Naming

Use descriptive branch names:

• feature/description — New features
• fix/description — Bug fixes
• docs/description — Documentation updates
• refactor/description — Code refactoring

Commit Messages

Follow conventional commits:

type(scope): description

[optional body]

[optional footer]

Types:

• feat — New feature
• fix — Bug fix
• docs — Documentation
• style — Formatting, no code change
• refactor — Code restructuring
• test — Adding tests
• chore — Maintenance

Examples:

feat(scope): add indentation-based fallback for scope resolution
fix(patch): handle missing if-wrapper in SEARCH/REPLACE block
docs(readme): update commands reference for current state

Submitting Changes

1. Ensure your code follows the style guide
2. Update documentation if needed
3. Update CHANGELOG.md for notable changes
4. Test your changes thoroughly
5. Create a pull request with:
   • Clear title describing the change
   • Description of what and why
   • Reference to any related issues

Pull Request Template

## Description
[Describe your changes]

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Refactoring

## Testing
[Describe how you tested your changes]

## Checklist
- [ ] Code follows style guide
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
- [ ] All tests pass

Style Guide

Lua Style

• Use tabs for indentation
• Use snake_case for variables and functions
• Use PascalCase for module names
• Add type annotations with ---@param, ---@return, etc.
• Document public functions with LuaDoc comments
• Avoid obvious/redundant comments

---@mod module_name Module description

local M = {}

--- Description of the function
---@param name string The parameter description
---@return boolean
function M.example_function(name)
  return true
end

return M

Documentation

• Keep README.md up to date
• Update doc/codetyper.txt for new features
• Regenerate doc/tags after help file changes
• Use clear, concise language
• Include examples where helpful

Testing

Running Tests

make test              # Run all tests
make test-file F=x     # Run a specific test file
make test-verbose      # Verbose output
make lint              # Run luacheck
make format            # Format with stylua

Manual Testing

1. Test all commands work correctly
2. Test with different file types
3. Test LLM integration (Copilot and Ollama)
4. Test edge cases (empty files, large files, no Tree-sitter, etc.)
5. Run :checkhealth codetyper

Questions?

Feel free to:

• Open an issue for bugs or feature requests
• Start a discussion for questions
• Reach out to the maintainer

Contact

• Maintainer: cargdev
• Email: carlos.gutierrez@carg.dev
• Website: cargdev.io

---

Thank you for contributing!