zzet--gortex/CONTRIBUTING.md

Contributing to Gortex

Thank you for considering contributing to Gortex! This guide will help you get started.

Licensing of contributions

Gortex is released under the Apache License, Version 2.0. By submitting a contribution (a pull request, patch, or other work) you agree that it is licensed to the project under the same Apache 2.0 terms, as described in section 5 of the License. You retain copyright in your contribution; the project retains a perpetual, worldwide, royalty-free license to use, modify, and redistribute it as part of Gortex.

Contributors are listed in CONTRIBUTORS.md. Add yourself to that file in the same PR if you'd like to be credited.

Getting Started

Prerequisites

• Go 1.21+
• CGO enabled (required for tree-sitter C bindings)
• Git

Building

git clone https://github.com/zzet/gortex.git
cd gortex
go build -o gortex ./cmd/gortex/

Running Tests

go test -race ./...

Running Benchmarks

go test -bench=. -benchmem ./internal/parser/languages/
go test -bench=. -benchmem ./internal/query/
go test -bench=. -benchmem ./internal/indexer/

How to Contribute

Reporting Bugs

• Open an issue with a clear description
• Include the output of gortex version and go version
• Provide a minimal reproduction if possible

Suggesting Features

• Open an issue describing the feature and its use case
• For language support requests, mention if the tree-sitter grammar is available in github.com/smacker/go-tree-sitter

Submitting Code

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Write tests for your changes
4. Ensure all tests pass (go test -race ./...)
5. Commit with a clear message
6. Open a pull request

Adding a New Language Extractor

This is one of the most impactful contributions. Follow these steps:

1. Check if the tree-sitter grammar exists in github.com/smacker/go-tree-sitter
2. Create internal/parser/languages/<language>.go implementing the parser.Extractor interface
3. Create internal/parser/languages/<language>_test.go with at least 3 tests
4. Register it in internal/parser/languages/register.go
5. Debug the AST first — tree-sitter node types vary between grammars

What to extract (in priority order):

• Functions/methods with EdgeMemberOf to their class/type
• Classes/types/interfaces
• Interface method specs in Meta["methods"] (enables IMPLEMENTS inference)
• Imports
• Call sites
• Variables/constants

Reference implementations:

• golang.go — the most complete extractor
• python.go — simple OOP language
• rust.go — systems language with impl blocks
• yaml.go — simple config extractor

Code Style

• Follow standard Go conventions (gofmt, go vet)
• No unnecessary abstractions — three similar lines is better than a premature helper
• Tests should be self-contained with inline source snippets
• Extractor test helpers (nodesOfKind, edgesOfKind) are shared across test files

Project Structure

cmd/gortex/          CLI entry point and commands
internal/
  analysis/          Community detection, process discovery, impact analysis
  claudemd/          CLAUDE.md generator
  config/            Configuration loading
  graph/             Core graph data structure (Node, Edge, Graph)
  indexer/           Directory walker, file watcher
  mcp/               MCP server and tool handlers
  parser/            Extractor interface, tree-sitter helpers
    languages/       Per-language extractors (one file each)
  query/             Query engine (BFS traversal, SubGraph)
  resolver/          Cross-file reference resolution, IMPLEMENTS inference
  web/               Web visualization server (Sigma.js)
pkg/gortex/          Public API for embedding

Questions?

Open an issue or start a discussion. We're happy to help!