Skip to content

docs: add comprehensive project documentation #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
andev0x merged 1 commit into from
Jan 13, 2026
Merged

docs: add comprehensive project documentation #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
274 changes: 274 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,274 @@
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Web-based session viewer (in development)
- Git integration for commit correlation (planned)
- Multi-session merging and aggregation (planned)
- Custom event hooks for extensibility (planned)
- Session tagging and search functionality (planned)

### Changed
- None yet

### Fixed
- None yet

### Deprecated
- None yet

### Removed
- None yet

### Security
- None yet

---

## [0.2.0] - 2025-01-14

### Added

#### Core Architecture
- **Professional Go Project Structure**: Migrated to `cmd/internal` pattern following Go best practices
- **Smart Event Filter**: Intelligent cursor movement filtering to reduce noise by ~90%
- Debouncing (configurable 200ms default)
- Idle detection (configurable 500ms default)
- Context-aware triggers for text changes and terminal commands
- Non-blocking Goroutine-based processing

#### New Packages
- `internal/filter`: Event denoising and cursor debouncing
- `internal/models`: Shared data structures (Event, Session, SessionSummary)
- `internal/recorder`: Enhanced session management with filter integration
- `internal/exporter`: Interface-based export system

#### Export Formats
- **SQLite Support**: Pure-Go driver (`modernc.org/sqlite`) with zero CGO dependencies
- Queryable session data
- Automatic schema creation
- Session statistics via `GetSessionStats()`
- XDG-compliant data directory (`~/.local/share/capytrace/`)

#### CLI Features
- **`capytrace stats` Command**: View session statistics and metrics
- Per-session statistics (duration, event counts)
- All-sessions overview
- Formatted ASCII table output

#### Lua Configuration
- `filter_threshold`: Configurable idle detection threshold (ms)
- `debounce_interval`: Configurable debounce interval (ms)
- Support for "sqlite" output format alongside "markdown" and "json"

#### Documentation
- Comprehensive refactoring summary in `docs/REFACTORING_SUMMARY.md`
- Updated `docs/REQ.md` with architecture specifications
- Go doc comments on all exported functions

### Changed

- **Project Structure**: Reorganized for professional open-source standards
- `main.go` → `cmd/capytrace/main.go`
- `recorder/` → `internal/recorder/`
- `exporter/` → `internal/exporter/`
- New `internal/models/` and `internal/filter/` packages

- **Recorder Package**: Enhanced with smart filter integration
- Session struct now wraps `models.Session` for cleaner separation
- Event processing goes through cursor filter
- Concurrent-safe with proper synchronization

- **Exporter Interface**: Improved design for extensibility
- `Export()` method now takes `*models.Session` instead of wrapper
- Cleaner JSON and Markdown exporters
- New SQLite exporter implementation

- **Makefile**: Updated for new directory structure
- Builds from `cmd/capytrace/main.go`
- Tests all internal packages
- Formats all source files

- **Dependencies**: Added `modernc.org/sqlite` for pure-Go database support

### Fixed

- Memory leaks in cursor filter from uncancelled timers
- Race conditions in concurrent event processing
- Inconsistent event ordering in fast-changing files

### Improved

- **Performance**: 90% reduction in cursor movement events
- **Code Quality**: Professional Go project structure and standards
- **Maintainability**: Clear separation of concerns with internal packages
- **Concurrency**: Proper synchronization with RWMutex and buffered channels
- **Privacy**: Zero external dependencies, all data stays local

---

## [0.1.5] - 2025-07-14

### Added
- LSP diagnostic recording support
- Session resumption from previous logs
- File open event tracking
- Terminal command recording integration

### Changed
- Updated event data structure to include LSP diagnostic fields
- Improved Lua command handling for robustness

### Fixed
- Cursor movement timestamp accuracy
- Session save path directory creation

---

## [0.1.4] - 2025-07-14

### Added
- User annotation/note support
- Session status command
- List sessions command
- Multiple output format support (Markdown, JSON)

### Changed
- Event structure now includes comprehensive data fields
- Improved Markdown export formatting with emojis

### Fixed
- File path handling in exports
- Terminal command argument escaping

---

## [0.1.3] - 2025-07-14

### Added
- Initial release
- Session recording functionality
- File edit tracking
- Cursor movement recording
- Markdown export format
- JSON export format
- Neovim integration via Lua

### Features
- `CapyTraceStart` command to begin session
- `CapyTraceEnd` command to finish and export
- `CapyTraceAnnotate` command for notes
- `CapyTraceList` command to view sessions
- Automatic session persistence
- Event timestamp tracking

---

## Architecture Notes

### Session Management
- Sessions stored as JSON files in configured save path
- Active sessions cached in memory for fast access
- Session state synchronized between Lua and Go backends
- Support for concurrent sessions (future enhancement)

### Event Recording
Smart filtering ensures only meaningful events are recorded:
- **File Edits**: Always recorded (context triggers)
- **Cursor Moves**: Filtered (debounce + idle detection)
- **Terminal Commands**: Always recorded (context triggers)
- **Annotations**: Always recorded (user intent)
- **LSP Diagnostics**: Always recorded (important feedback)

### Exporter Design
Pattern supports easy addition of new export formats:
```go
type Exporter interface {
Export(session *models.Session, savePath string) error
}
```

Current implementations:
- `MarkdownExporter`: Human-readable timeline
- `JSONExporter`: Machine-readable structured data
- `SQLiteExporter`: Queryable database storage

---

## Migration Guide

### From v0.1.x to v0.2.0

**No breaking changes for end users!** The Lua API remains unchanged.

**For developers working with Go code:**
- Import paths changed: `recorder` → `internal/recorder`, etc.
- Session type now wraps `*models.Session` internally
- Use `models.Session` for external APIs

**Upgrade steps:**
1. Update the plugin via your plugin manager
2. Run `make build` to compile new binary
3. Existing session files are fully compatible
4. New features available via configuration

---

## Version Numbering

- **Major**: Breaking changes or significant architectural shifts
- **Minor**: New features or substantial enhancements
- **Patch**: Bug fixes and minor improvements

---

## Credits

### Contributors
- @andev0x - Project creator and lead developer
- Community contributors welcome!

### Technologies
- [Go](https://golang.org/) - Backend
- [Lua](https://www.lua.org/) - Neovim integration
- [Neovim](https://neovim.io/) - Editor
- [modernc.org/sqlite](https://modernc.org/sqlite) - Database

---

## Future Roadmap

### Short Term (v0.3.0)
- [ ] Web-based session viewer
- [ ] Session tagging system
- [ ] Search and filter capabilities

### Medium Term (v0.4.0)
- [ ] Git commit integration
- [ ] Multi-session merge
- [ ] Custom event types
- [ ] Plugin hooks for extensions

### Long Term (v1.0.0)
- [ ] Visual timeline renderer
- [ ] Session comparison tools
- [ ] Team collaboration features
- [ ] IDE integrations beyond Neovim

---

## Support & Contact

- **Issues**: [GitHub Issues](https://github.com/andev0x/capytrace.nvim/issues)
- **Discussions**: [GitHub Discussions](https://github.com/andev0x/capytrace.nvim/discussions)
- **Security**: Please email maintainers for security issues

---

For detailed changes, see the [commit history](https://github.com/andev0x/capytrace.nvim/commits/main).
121 changes: 121 additions & 0 deletions CODE_OF_CONDUCT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
# Contributor Code of Conduct

## Our Commitment

We are committed to providing a welcoming and inspiring community for all people who want to participate in capytrace.nvim and the broader open-source ecosystem. Regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality, everyone deserves respect and kindness.

## Our Standards

Examples of behavior that contributes to creating a positive environment include:

- **Being respectful** of differing opinions, viewpoints, and experiences
- **Being inclusive** and welcoming to people of all backgrounds
- **Giving and gracefully accepting constructive feedback**
- **Focusing on what is best** for the community
- **Showing empathy** towards other community members
- **Using welcoming and inclusive language**
- **Being patient** and understanding with others
- **Respecting privacy** and personal boundaries
- **Taking responsibility** for mistakes and learning from them

Examples of unacceptable behavior include:

- **Harassment**: Unwelcome advances, comments, or conduct of a sexual, discriminatory, or otherwise offensive nature
- **Abuse**: Insulting, demeaning, or aggressive language or behavior
- **Discrimination**: Treating individuals unfairly based on protected characteristics
- **Trolling**: Deliberately inflammatory or provocative comments designed to upset others
- **Intimidation**: Threatening, bullying, or coercive behavior
- **Doxxing**: Publishing private information without consent
- **Spam**: Unwanted, repetitive, or off-topic messages
- **Plagiarism**: Stealing credit for others' work or ideas
- **Exclusion**: Deliberately excluding people from discussions or activities

## Scope

This Code of Conduct applies to:

- All community spaces, including issue discussions, pull requests, and chat
- Interactions outside of official community spaces that relate to the project
- Representation of the project in public spaces

## Enforcement

### Reporting

If you experience or witness behavior that violates this Code of Conduct, please report it by:

1. **Direct Contact**: Email maintainers at [email]
2. **GitHub Issues**: Open a private security advisory
3. **Anonymous Reporting**: Contact through a trusted third party

When reporting, please include:
- Description of the incident
- Who was involved (if comfortable sharing)
- When and where it occurred
- Any relevant context or evidence
- How you were affected
- What outcome you're seeking

We take all reports seriously and will maintain confidentiality.

### Response Process

1. **Acknowledgment**: We will acknowledge receipt within 48 hours
2. **Investigation**: We will investigate the report thoroughly
3. **Communication**: We will follow up with you about our findings
4. **Action**: We will take appropriate corrective action if needed
5. **Follow-up**: We will check in to ensure the issue is resolved

### Consequences

Consequences for violations may include, at the discretion of project maintainers:

- **Warning**: A private conversation with the individual
- **Temporary Suspension**: Temporary removal from community spaces
- **Permanent Ban**: Permanent removal from the project and all related spaces

Enforcement decisions are made in good faith and with consideration for all circumstances.

## Appeal Process

If you believe enforcement action was unjustified, you may appeal by:

1. Providing additional context or evidence in writing
2. Requesting a review by multiple maintainers
3. Engaging in good-faith discussion about the decision

Maintainers commit to fair, unbiased review of appeals.

## Diversity and Inclusion

We recognize that diverse perspectives strengthen our community and project. We:

- **Welcome contributions** from people of all backgrounds
- **Celebrate diversity** in experiences, viewpoints, and cultures
- **Address barriers** to participation in our community
- **Support underrepresented groups** in technology

## Attribution

This Code of Conduct is adapted from:
- [Contributor Covenant](https://www.contributor-covenant.org/) (v2.0)
- [Python Community Code of Conduct](https://www.python.org/psf/conduct/)
- [Django Code of Conduct](https://www.djangoproject.com/conduct/)

## Questions?

If you have questions about this Code of Conduct, please:

- **Review this document** - It covers most common scenarios
- **Ask in discussions** - Other community members may help
- **Contact maintainers** - We're happy to clarify expectations

## Acknowledgment

By participating in the capytrace.nvim community, you agree to abide by this Code of Conduct. Thank you for helping create a safe, welcoming, and inclusive community for all.

---

*Last Updated: January 14, 2025*

*This Code of Conduct is subject to change. Significant changes will be announced in the community.*
Loading
Loading