Add documentation

Author: code-with-auto

CONTRIBUTORS.md

@@ -0,0 +1,210 @@
+# Contributing to loq
+
+Thank you for your interest in contributing to loq! This document provides guidelines and instructions for contributing.
+
+## Code of Conduct
+
+Be kind, respectful, and constructive. We're all here to build something useful together.
+
+## How to Contribute
+
+### Reporting Bugs
+
+1. Check existing issues to avoid duplicates
+2. Use the bug report template
+3. Include:
+   - loq version (`loq --version`)
+   - OS and version
+   - Steps to reproduce
+   - Expected vs actual behavior
+   - Sample log line(s) if relevant
+
+### Suggesting Features
+
+1. Check existing issues/discussions
+2. Describe the use case
+3. Propose a solution if you have one
+
+### Pull Requests
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make your changes
+4. Add/update tests
+5. Ensure all tests pass: `bun test`
+6. Ensure coverage stays above 95%: `bun test --coverage`
+7. Submit a PR
+
+## Development Setup
+
+```bash
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/loq.git
+cd loq
+
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Run in dev mode
+bun run dev
+```
+
+## Project Structure
+
+```
+src/
+├── cli/           # Command-line interface
+├── config/        # Configuration loading
+├── parser/        # Log parsing
+│   └── formats/   # Individual format parsers
+├── query/         # Query language
+├── output/        # Output formatting
+└── utils/         # Utilities
+
+tests/             # Mirror of src/ structure
+```
+
+## Adding a New Log Format
+
+### 1. Create the parser
+
+```typescript
+// src/parser/formats/myformat.ts
+import type { LogEntry, LogParser } from '../types';
+
+export const myFormatParser: LogParser = {
+  name: 'myformat',
+
+  detect(line: string): boolean {
+    // Fast check - is this line in my format?
+    return /^MYFORMAT:/.test(line);
+  },
+
+  parse(line: string): LogEntry | null {
+    const match = line.match(/^MYFORMAT: \[(.+?)\] (\w+) - (.+)$/);
+    if (!match) return null;
+
+    return {
+      raw: line,
+      timestamp: match[1],
+      level: match[2].toLowerCase(),
+      message: match[3],
+      fields: {
+        // Include all parsed fields for querying
+        timestamp: match[1],
+        level: match[2],
+        message: match[3],
+      },
+    };
+  },
+};
+```
+
+### 2. Register the parser
+
+```typescript
+// src/parser/auto-detect.ts
+import { myFormatParser } from './formats/myformat';
+
+const builtinParsers: LogParser[] = [
+  jsonParser,
+  myFormatParser,  // Add here - order matters for detection
+  apacheParser,
+  // ...
+];
+```
+
+### 3. Add tests
+
+```typescript
+// tests/parsers/myformat.test.ts
+import { describe, expect, test } from 'bun:test';
+import { myFormatParser } from '../../src/parser/formats/myformat';
+
+describe('MyFormat Parser', () => {
+  describe('detect', () => {
+    test('detects valid format', () => {
+      expect(myFormatParser.detect('MYFORMAT: [2024-01-01] INFO - test')).toBe(true);
+    });
+
+    test('rejects other formats', () => {
+      expect(myFormatParser.detect('{"level":"info"}')).toBe(false);
+    });
+  });
+
+  describe('parse', () => {
+    test('parses correctly', () => {
+      const result = myFormatParser.parse('MYFORMAT: [2024-01-01] ERROR - Something failed');
+      expect(result).not.toBeNull();
+      expect(result!.timestamp).toBe('2024-01-01');
+      expect(result!.level).toBe('error');
+      expect(result!.message).toBe('Something failed');
+    });
+
+    test('returns null for invalid line', () => {
+      expect(myFormatParser.parse('invalid')).toBeNull();
+    });
+  });
+});
+```
+
+## Coding Guidelines
+
+### TypeScript
+
+- Use strict mode
+- Prefer explicit types for public APIs
+- Use `type` imports where possible
+
+### Testing
+
+- Aim for 95%+ coverage
+- Test both success and failure cases
+- Use descriptive test names
+- Group related tests with `describe()`
+
+### Performance
+
+- Parser `detect()` should be fast (regex test, not full parse)
+- Stream large files, don't load into memory
+- Avoid unnecessary allocations in hot paths
+
+### Error Handling
+
+- Don't crash on invalid input
+- Return `null` from parsers for non-matching lines
+- Log warnings for config issues, don't fail
+
+## Commit Messages
+
+Use conventional commits:
+
+```
+feat: add support for Docker log format
+fix: handle missing timestamp in syslog
+docs: update README with new examples
+test: add coverage for edge cases
+refactor: simplify query executor
+```
+
+## Release Process
+
+Releases are automated via GitHub Actions when a tag is pushed:
+
+```bash
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+## Contributors
+
+Thanks to everyone who has contributed to loq!
+
+<!-- Add your name here when you contribute -->
+
+---
+
+Questions? Open an issue or discussion!