matimo 0.1.0-alpha.1

package/docs/user-guide/DEVELOPMENT_STANDARDS.md

@@ -0,0 +1,698 @@
+# Development Standards — Code Quality Rules
+
+Code quality standards and best practices for Matimo.
+
+## Table of Contents
+
+- [TypeScript Standards](#typescript-standards)
+- [Naming Conventions](#naming-conventions)
+- [Error Handling](#error-handling)
+- [Testing Standards](#testing-standards)
+- [Documentation Standards](#documentation-standards)
+- [Security Standards](#security-standards)
+- [Logging Standards](#logging-standards)
+- [Performance Standards](#performance-standards)
+- [Quality Metrics](#quality-metrics)
+
+---
+
+## TypeScript Standards
+
+### Strict Mode (Required)
+
+All code must compile in TypeScript strict mode.
+
+```typescript
+// tsconfig.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "noImplicitThis": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitReturns": true
+  }
+}
+```
+
+### Type Safety
+
+**DO:**
+```typescript
+// Explicit types everywhere
+function loadTool(path: string): ToolDefinition {
+  // implementation
+}
+
+// Use interface for contracts
+interface ToolDefinition {
+  name: string;
+  execute(params: Record<string, unknown>): Promise<Result>;
+}
+
+// Use union types for variants
+type ExecutionType = 'command' | 'http' | 'script';
+
+// Use const assertions for immutable data
+const EXECUTION_TYPES = ['command', 'http', 'script'] as const;
+```
+
+**DON'T:**
+```typescript
+// No implicit any
+function loadTool(path) { }
+
+// No any types
+function execute(tool: any, params: any): any { }
+
+// No untyped variables
+let result;
+```
+
+### Export Types
+
+Export types alongside implementations:
+
+```typescript
+// ✅ DO: Export types with implementation
+export interface ToolDefinition {
+  name: string;
+  // ...
+}
+
+export class ToolLoader {
+  loadToolFromFile(path: string): ToolDefinition { }
+}
+
+// ❌ DON'T: Types only in comments
+// ToolDefinition = { name: string, ... }
+class ToolLoader { }
+```
+
+---
+
+## Naming Conventions
+
+### Files
+
+```typescript
+// kebab-case for files
+tool-loader.ts
+command-executor.ts
+error-codes.ts
+matimo-error.ts
+
+// Descriptive names
+// ✓ command-executor.ts
+// ✗ executor.ts
+// ✗ cmd-exec.ts
+```
+
+### Classes & Types
+
+```typescript
+// PascalCase for classes
+class ToolLoader { }
+class CommandExecutor { }
+class MatimoError extends Error { }
+
+// PascalCase for types/interfaces
+interface ToolDefinition { }
+interface ExecutionConfig { }
+type ExecutionType = 'command' | 'http' | 'script';
+```
+
+### Functions & Variables
+
+```typescript
+// camelCase for functions and variables
+function loadTool() { }
+const toolRegistry = new Map();
+let executionCount = 0;
+
+// Descriptive names
+// ✓ loadToolFromFile()
+// ✓ validateToolParameters()
+// ✗ load()
+// ✗ validate()
+```
+
+### Constants
+
+```typescript
+// UPPER_SNAKE_CASE for constants
+const MAX_RETRIES = 3;
+const DEFAULT_TIMEOUT = 5000;
+const SUPPORTED_TYPES = ['command', 'http', 'script'];
+
+// Constants should be immutable
+const readonly EXECUTION_TYPES = ['command', 'http'] as const;
+```
+
+---
+
+## Error Handling
+
+### Use Structured Errors
+
+```typescript
+// Define standard error codes
+export enum ErrorCode {
+  INVALID_SCHEMA = 'INVALID_SCHEMA',
+  EXECUTION_FAILED = 'EXECUTION_FAILED',
+  AUTH_FAILED = 'AUTH_FAILED',
+  TOOL_NOT_FOUND = 'TOOL_NOT_FOUND',
+  FILE_NOT_FOUND = 'FILE_NOT_FOUND',
+  VALIDATION_FAILED = 'VALIDATION_FAILED'
+}
+
+// Use structured error class
+export class MatimoError extends Error {
+  constructor(
+    message: string,
+    public code: ErrorCode,
+    public context?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = 'MatimoError';
+  }
+}
+
+// Throw with context
+throw new MatimoError(
+  'Tool execution failed',
+  ErrorCode.EXECUTION_FAILED,
+  {
+    toolName: tool.name,
+    reason: 'timeout',
+    duration: 30000
+  }
+);
+```
+
+### Error Message Guidelines
+
+```typescript
+// ✅ DO: Clear, actionable messages
+throw new MatimoError(
+  'Tool validation failed: missing required parameter "repo"',
+  ErrorCode.VALIDATION_FAILED
+);
+
+// ✅ DO: Include context
+throw new MatimoError(
+  'HTTP request failed',
+  ErrorCode.EXECUTION_FAILED,
+  { status: 500, endpoint: '/api/issues' }
+);
+
+// ❌ DON'T: Generic errors
+throw new Error('Something went wrong');
+
+// ❌ DON'T: Include sensitive data
+throw new Error(`Failed with token: ${apiKey}`);
+```
+
+### Error Handling Pattern
+
+```typescript
+try {
+  const result = await executor.execute(tool, params);
+  return result;
+} catch (error) {
+  if (error instanceof MatimoError) {
+    logger.error('Execution failed', {
+      code: error.code,
+      message: error.message,
+      context: error.context
+    });
+    throw error;
+  }
+  
+  // Convert unknown errors
+  throw new MatimoError(
+    'Unknown error during execution',
+    ErrorCode.EXECUTION_FAILED,
+    { originalError: error.message }
+  );
+}
+```
+
+---
+
+## Testing Standards
+
+### Test File Organization
+
+```typescript
+// test/unit/tool-loader.test.ts
+describe('ToolLoader', () => {
+  describe('loadToolFromFile', () => {
+    it('should load valid YAML tool definition', () => {
+      // Arrange
+      const filePath = './fixtures/calculator.yaml';
+
+      // Act
+      const tool = loader.loadToolFromFile(filePath);
+
+      // Assert
+      expect(tool.name).toBe('calculator');
+      expect(tool.parameters).toBeDefined();
+    });
+
+    it('should throw FileNotFoundError when file does not exist', () => {
+      // Arrange
+      const filePath = './fixtures/nonexistent.yaml';
+
+      // Act & Assert
+      expect(() => {
+        loader.loadToolFromFile(filePath);
+      }).toThrow(FileNotFoundError);
+    });
+  });
+});
+```
+
+### Test Naming
+
+```typescript
+// ✅ DO: Descriptive test names
+it('should load valid YAML tool definition');
+it('should throw FileNotFoundError when file does not exist');
+it('should validate parameters against schema');
+it('should handle missing required parameters');
+it('should retry on temporary failure');
+
+// ❌ DON'T: Vague test names
+it('should work');
+it('tests loading');
+it('handles errors');
+```
+
+### Test Coverage
+
+**Minimum targets:**
+- Overall: **80%+**
+- Critical paths: **90%+**
+- Branch coverage: All if/else paths tested
+- Edge cases: Empty inputs, null values, max values
+
+```bash
+# Check coverage
+pnpm test:coverage
+
+# Expected:
+# Statements   : 80%+
+# Branches     : 75%+
+# Functions    : 80%+
+# Lines        : 80%+
+```
+
+### Mocking & Fixtures
+
+```typescript
+// ✅ DO: Use fixtures for test data
+const validTool = loadYaml('./fixtures/calculator.yaml');
+
+// ✅ DO: Mock external dependencies
+const mockAPI = jest.spyOn(axios, 'get')
+  .mockResolvedValue({ data: { id: 1 } });
+
+// ✅ DO: Clean up mocks
+afterEach(() => {
+  jest.clearAllMocks();
+});
+
+// ✅ DO: Use AAA pattern
+it('should execute tool', () => {
+  // Arrange
+  const tool = loadTool('calculator');
+  
+  // Act
+  const result = executor.execute(tool, { a: 1, b: 2 });
+  
+  // Assert
+  expect(result.output.result).toBe(3);
+});
+```
+
+---
+
+## Documentation Standards
+
+### JSDoc Comments
+
+```typescript
+// ✅ DO: JSDoc for all public APIs
+/**
+ * Load a tool definition from a YAML/JSON file.
+ * 
+ * @param path - Path to tool definition file
+ * @returns Loaded and validated tool definition
+ * @throws {FileNotFoundError} If file doesn't exist
+ * @throws {SchemaValidationError} If tool schema invalid
+ * 
+ * @example
+ * const tool = loader.loadToolFromFile('./tools/calculator.yaml');
+ */
+export function loadToolFromFile(path: string): ToolDefinition {
+  // implementation
+}
+
+// ❌ DON'T: Missing or vague documentation
+function load(p) { }
+
+// ❌ DON'T: Obvious comments
+// Increment i
+i++;
+```
+
+### Code Comments
+
+Comments should explain **WHY**, not **WHAT**.
+
+```typescript
+// ✅ DO: Explain why
+// We retry exponentially because the API has rate limits
+// and temporary network issues are common
+const delay = initialDelay * Math.pow(2, retries);
+
+// ✅ DO: Document non-obvious logic
+// Skip first item because it's always metadata
+for (let i = 1; i < items.length; i++) {
+  // process item
+}
+
+// ❌ DON'T: Describe what the code does
+// Calculate exponential backoff
+const delay = initialDelay * Math.pow(2, retries);
+
+// ❌ DON'T: Obvious comments
+// Get the first item
+const first = items[0];
+```
+
+### README Structure
+
+```markdown
+# Tool Name
+
+Brief description (1 sentence)
+
+## Features
+- Feature 1
+- Feature 2
+
+## Installation
+```
+
+## Installation
+
+Step-by-step setup instructions
+
+## Usage
+
+Code examples
+
+## API Reference
+
+Methods and options
+
+## Troubleshooting
+
+Common issues and solutions
+```
+
+---
+
+## Security Standards
+
+### Input Validation
+
+```typescript
+// ✅ DO: Validate all inputs
+const validated = toolSchema.parameters.parse(params);
+const result = await executor.execute(tool, validated);
+
+// ✅ DO: Use Zod for schema validation
+import { z } from 'zod';
+
+const paramSchema = z.object({
+  repo: z.string().regex(/^[^/]+\/[^/]+$/),
+  issue: z.number().min(1)
+});
+
+const validated = paramSchema.parse(params);
+
+// ❌ DON'T: Trust user input
+const command = `git clone ${userUrl}`;  // Dangerous!
+```
+
+### Secret Management
+
+```typescript
+// ✅ DO: Use environment variables with MATIMO_ prefix
+const apiKey = process.env.MATIMO_SLACK_API_KEY;
+if (!apiKey) {
+  throw new MatimoError('Missing Slack API key', ErrorCode.AUTH_FAILED);
+}
+
+// ✅ DO: Validate secrets exist before use
+const token = process.env.MATIMO_GITHUB_TOKEN;
+if (!token || token.length === 0) {
+  throw new MatimoError('Invalid GitHub token', ErrorCode.AUTH_FAILED);
+}
+
+// ❌ DON'T: Hardcode secrets
+const API_KEY = 'sk_live_abc123xyz789';  // NEVER!
+
+// ❌ DON'T: Log secrets
+logger.info('Token retrieved:', apiKey);  // WRONG!
+logger.info('Token retrieved');  // OK
+```
+
+### Output Escaping
+
+```typescript
+// ✅ DO: Escape shell commands
+import { shellEscape } from 'shell-escape';
+const escaped = shellEscape([command, ...args]);
+
+// ✅ DO: Sanitize error messages
+const sanitized = error.message.replace(apiKey, '[REDACTED]');
+
+// ❌ DON'T: Include secrets in error messages
+throw new Error(`Failed with key: ${apiKey}`);
+```
+
+---
+
+## Logging Standards
+
+### Structured Logging
+
+```typescript
+// ✅ DO: Use structured logging
+logger.info('tool_execution', {
+  traceId: context.traceId,
+  toolName: tool.name,
+  parameters: sanitized(params),
+  duration: executionTime,
+  status: 'success' | 'failed'
+});
+
+// ✅ DO: Include trace IDs
+logger.error('execution_failed', {
+  traceId: context.traceId,
+  toolName: tool.name,
+  error: error.message
+});
+
+// ❌ DON'T: Unstructured logging
+console.log('Tool loaded');
+logger.info('tool loaded: ' + toolName);
+
+// ❌ DON'T: Log secrets
+logger.info('Token: ' + apiKey);
+```
+
+### Log Levels
+
+```typescript
+logger.debug('Parsing tool definition');           // Detailed info
+logger.info('Tool loaded successfully');          // Informational
+logger.warn('Tool schema drift detected');        // Warning
+logger.error('Tool execution failed', error);     // Error
+
+// ❌ DON'T: Use console.log in production
+console.log('Debug info');
+```
+
+---
+
+## Performance Standards
+
+### Execution Time Targets
+
+```
+Simple tools (echo, time): <100ms
+API tools (GitHub, Slack): <2 seconds
+Data processing (CSV, JSON): <1 second
+Heavy computation: <10 seconds
+```
+
+### Memory Targets
+
+```
+Tool loading: <10MB
+Tool execution: <50MB
+Registry loading: <20MB
+```
+
+### Throughput Targets
+
+```
+Tools loaded: 1000+ in <1 second
+Concurrent executions: 100+
+Requests/second: 1000+
+```
+
+---
+
+## Quality Metrics
+
+### Code Quality Checklist
+
+```typescript
+// ✅ Types
+- Strict TypeScript mode enabled
+- No `any` types used
+- All functions have type signatures
+- Return types explicitly declared
+
+// ✅ Testing
+- 80%+ test coverage
+- Unit tests for all modules
+- Integration tests for critical paths
+- Edge cases tested
+
+// ✅ Documentation
+- JSDoc comments on all public APIs
+- README with examples
+- Code comments explaining WHY
+- Type definitions exported
+
+// ✅ Error Handling
+- All errors use MatimoError
+- Errors include codes and context
+- No generic Error throws
+- Error messages are clear
+
+// ✅ Security
+- No hardcoded secrets
+- All inputs validated
+- Sensitive data never logged
+- Shell commands properly escaped
+
+// ✅ Performance
+- Tool loading <10MB
+- Execution meets time targets
+- No memory leaks
+- Concurrent operations supported
+```
+
+### Build Verification
+
+```bash
+# Check TypeScript
+pnpm build
+# Expected: No errors
+
+# Check linting
+pnpm lint
+# Expected: 0 errors, 0 warnings
+
+# Check tests
+pnpm test
+# Expected: All tests passing
+
+# Check coverage
+pnpm test:coverage
+# Expected: 80%+ coverage
+```
+
+---
+
+## Development Workflow
+
+### Before Committing
+
+1. **Format code:** `pnpm format`
+2. **Check types:** `pnpm build`
+3. **Lint:** `pnpm lint`
+4. **Test:** `pnpm test`
+5. **Coverage:** `pnpm test:coverage` (verify 80%+)
+
+### Pre-Merge Checklist
+
+- [ ] All tests passing
+- [ ] Coverage 80%+ 
+- [ ] No TypeScript errors
+- [ ] No ESLint warnings
+- [ ] Code formatted with Prettier
+- [ ] Commit messages follow guidelines
+- [ ] Documentation updated
+- [ ] PR reviewed and approved
+
+---
+
+## Common Anti-Patterns
+
+```typescript
+// ❌ DON'T: Use any types
+function execute(tool: any, params: any): any { }
+
+// ✅ DO: Use proper types
+function execute(
+  tool: ToolDefinition,
+  params: Record<string, unknown>
+): Promise<ExecutionResult> { }
+
+// ❌ DON'T: Generic error handling
+catch (error) {
+  throw new Error('Failed');
+}
+
+// ✅ DO: Structured error handling
+catch (error) {
+  throw new MatimoError(
+    'Tool execution failed',
+    ErrorCode.EXECUTION_FAILED,
+    { toolName, reason: error.message }
+  );
+}
+
+// ❌ DON'T: Log secrets
+logger.info('Authenticated with key:', apiKey);
+
+// ✅ DO: Redact sensitive data
+logger.info('Authentication successful', { hasKey: !!apiKey });
+
+// ❌ DON'T: Skip validation
+const result = userInput.trim();
+
+// ✅ DO: Validate all inputs
+const validated = schema.parse(userInput);
+```
+
+---
+
+## See Also
+
+- [CONTRIBUTING.md](../CONTRIBUTING.md) — Contribution guide
+- [COMMIT_GUIDELINES.md](../community/COMMIT_GUIDELINES.md) — Commit standards
+- [QUICK_START.md](../getting-started/QUICK_START.md) — Get started
+- [API_REFERENCE.md](../api-reference/SDK.md) — SDK documentation