Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
56 lines (35 loc) · 4.45 KB

CONTRIBUTING.md

File metadata and controls

56 lines (35 loc) · 4.45 KB
Raw

Contributing to ArchGuard

First off, thank you for taking the time to contribute! ArchGuard is built on the idea that architectural integrity should be automated, not just documented. Whether you are fixing a bug, improving the LLM prompts, or optimizing the vector search, your help is appreciated.

Getting Started

To begin contributing, you will need Go 1.26 or later and a local instance of Ollama to run the default models. Once your environment is ready, fork the repository and clone it to your local machine.

Run go mod download to pull the necessary dependencies, including the tokenizer and YAML parser. You can build the project locally using go build -o archguard ./cmd/archguard. Before submitting any changes, ensure that the binary compiles and that you have tested your logic against a local ADR directory.

Project Architecture

The codebase is organized into several internal packages to maintain a strict separation of concerns.

  • cmd/archguard: This is the entry point. It manages CLI flags and environment variables like ARCHGUARD_API_KEY. Keep this layer thin.
  • internal/analysis: This is the core engine. It coordinates the analysis pipeline, manages the worker pool, and handles file truncation for LLM context windows.
  • internal/index: This package manages the vector store and ADR parsing. It is responsible for calculating hashes, executing Delta Indexing (to skip redundant API calls), managing concurrent provider fetching, and maintaining PostgreSQL upsert logic and HNSW index structures.
  • internal/llm: This contains the provider interfaces. If you want to add a new provider (like Anthropic), this is where you would implement the Provider interface.

Technical Standards

We follow a minimalist approach to code documentation. Avoid adding conversational or obvious comments to your code. Instead, prioritize clean variable naming and modular design.

For public-facing functions and complex logic, use Structured Block Commenting combined with Explicit Type Documentation. This ensures that the intent of the logic is clear for future contributors.

Analysis Pipeline & Performance

  • Vector Search: ArchGuard relies on cosine similarity to find relevant ADRs. Ensure search logic adheres to the formal definition: $\text{similarity} = \frac{\mathbf{A} \cdot \mathbf{B}}{|\mathbf{A}| |\mathbf{B}|}$.
  • Index Optimization: Vector indexing operations should utilize Delta Indexing to bypass LLM calls for unchanged assets. Remote stores (like Postgres) must handle structural drift correctly (e.g., executing conditional REINDEX maintenance and safe ON CONFLICT block upserts).
  • Parallelism: The analysis engine uses a worker pool to process files concurrently. The default concurrency is 5, adjustable via max_concurrency in the config. Vector store embedding logic uses a separate pool (embedding_concurrency).
  • Smart Truncation: To fit within LLM context limits, the engine truncates large files by rolling back to the nearest preceding newline character to avoid breaking code mid-line.
  • Caching: Analysis results are cached in .archguard/cache using a SHA-256 hash of the model name, ADR content, file content, and prompts. This is critical for maintaining performance in local environments.

Testing and Pull Requests

We maintain a robust testing suite that includes unit tests for internal logic and E2E tests for the CLI. Run go test ./... to execute the full suite. Our E2E tests utilize a mock provider to verify logic without incurring API costs or requiring a running Ollama instance.

When you are ready to submit your changes, please use Conventional Commits for your messages. For example, use feat: add support for local vector caching or fix: handle malformed JSON from LLM. Pull requests will be reviewed for idiomatic Go patterns and architectural alignment.

CI and Exit Codes

When contributing to the CLI, ensure that behavioral changes respect standard exit codes:

  • 0: Success (no violations found).
  • 1: General error (e.g. not run inside a git repository, baseline file I/O failure).
  • 2: Usage error (missing/unknown command, bad flags).
  • 3: Config error (failed to load or validate archguard.yaml).
  • 4: Architectural drift detected.
  • 5: Index error (failed to build, load, or fetch ADRs for the vector store).
  • --ci flag: Changes that result in truncated context should only trigger warnings in CI mode to maintain pipeline stability.