setup.md
1 --- 2 title: 'Setup' 3 category: 'getting-started' 4 last_verified: '2026-02-15' 5 related_files: 6 - 'src/module-name.test.js' 7 - 'src/capture.js' 8 - 'src/capture.test.js' 9 - 'scripts/quality-check.js' 10 tags: ['setup', 'testing', 'api', 'ai', 'llm'] 11 status: 'current' 12 --- 13 14 # Code Quality Setup & Workflow 15 16 Complete guide to the quality infrastructure for 333 Method Automation. 17 18 ## 🎯 Quality Stack Overview 19 20 ### Tools Installed 21 22 | Tool | Purpose | Integration | 23 | -------------------- | ------------------------------ | --------------------------- | 24 | **ESLint** | Code linting & error detection | ✅ Auto-fix, Cline-aware | 25 | **Prettier** | Code formatting | ✅ Auto-format | 26 | **Node Test Runner** | Unit testing (built-in) | ✅ Coverage tracking | 27 | **c8** | Code coverage | ✅ Reports to Cline | 28 | **Husky** | Git hooks | ✅ Pre-commit checks | 29 | **lint-staged** | Smart pre-commit | ✅ Only check changed files | 30 | **Sage** | AI code review (optional) | ✅ Cline feedback loop | 31 32 --- 33 34 ## 🚀 Quick Start (From nix-shell) 35 36 ```bash 37 # Enter development environment 38 nix-shell 39 40 # Everything auto-installs! 41 # Then run quality check: 42 npm run quality-check 43 ``` 44 45 --- 46 47 ## 📋 Available Commands 48 49 ### Linting 50 51 ```bash 52 # Check for issues 53 npm run lint 54 55 # Auto-fix issues 56 npm run lint:fix 57 ``` 58 59 ### Formatting 60 61 ```bash 62 # Format all code 63 npm run format 64 65 # Check if formatted 66 npm run format:check 67 ``` 68 69 ### Testing 70 71 ```bash 72 # Run all tests 73 npm test 74 75 # Watch mode (re-run on changes) 76 npm run test:watch 77 78 # Generate coverage report 79 npm run coverage 80 ``` 81 82 ### Full Quality Check 83 84 ```bash 85 # Run everything (ESLint + Prettier + Tests + Coverage + Sage) 86 npm run quality-check 87 ``` 88 89 **Output**: Creates `.quality-reports/` directory with JSON files Cline can read. 90 91 --- 92 93 ## 🔄 Cline Integration Workflow 94 95 ### Method 1: Automatic (Custom Instruction) 96 97 Add to `.vscode/cline_custom_instructions.md` (create if doesn't exist): 98 99 ```markdown 100 # Code Quality Instructions 101 102 After generating or modifying code: 103 104 1. Run: npm run quality-check 105 2. Read .quality-reports/summary.json 106 3. If issues exist: 107 - Auto-fix ESLint errors: npm run lint:fix 108 - Address Sage recommendations 109 - Generate missing tests if coverage < 80% 110 4. Update any outdated documentation, including --help in executables and shell.nix 111 5. Show me a summary of what was fixed 112 ``` 113 114 ### Method 2: Manual Workflow 115 116 1. **Cline generates code** 117 2. **You run**: `npm run quality-check` 118 3. **Tell Cline**: "Fix the issues in .quality-reports/" 119 4. **Cline** reads JSON files and auto-fixes 120 5. **Commit** clean code 121 122 ### Method 3: VSCodium Task (Keyboard) 123 124 Press `Ctrl+Shift+B` (or `Cmd+Shift+B` on Mac) 125 126 - Runs full quality check 127 - Results appear in terminal 128 - Cline can read the output 129 130 --- 131 132 ## 📂 Quality Reports Structure 133 134 After running `npm run quality-check`, you'll see: 135 136 ``` 137 .quality-reports/ 138 ├── summary.json # Overall status (Cline reads this first) 139 ├── eslint.json # Linting issues with auto-fix suggestions 140 ├── tests.txt # Test results 141 ├── coverage.txt # Coverage details 142 └── sage.json # AI review (if Sage installed) 143 ``` 144 145 ### Example summary.json 146 147 ```json 148 { 149 "timestamp": "2026-01-18T14:46:00.000Z", 150 "passed": false, 151 "checks": { 152 "eslint": { 153 "status": "failed", 154 "output": ".quality-reports/eslint.json" 155 }, 156 "tests": { 157 "status": "passed" 158 }, 159 "coverage": { 160 "status": "completed", 161 "percentage": 65.5, 162 "warning": "Coverage below 70% target" 163 } 164 } 165 } 166 ``` 167 168 --- 169 170 ## 🤖 Sage AI Integration (Optional) 171 172 ### Install Sage 173 174 ```bash 175 npm install -D @tigrisdata/sage 176 ``` 177 178 ### Configure 179 180 ```bash 181 # Initialize (creates .sage/config.json) 182 npx sage init 183 184 # Add your API key (.sage/config.json) 185 { 186 "apiKey": "your-openrouter-or-anthropic-key" 187 } 188 ``` 189 190 ### Run Reviews 191 192 ```bash 193 # Quick review 194 npx sage review 195 196 # Detailed review 197 npx sage review --verbose 198 199 # JSON output (for Cline) 200 npx sage review --format json > .quality-reports/sage.json 201 ``` 202 203 --- 204 205 ## 🔍 Pre-Commit Hooks (Coming Soon) 206 207 After we set up git: 208 209 ```bash 210 # Initialize Husky 211 npx husky install 212 213 # Add pre-commit hook 214 npx husky add .husky/pre-commit "npm run lint-staged" 215 ``` 216 217 This will: 218 219 - ✅ Lint only changed files 220 - ✅ Run relevant tests 221 - ✅ Block commits if critical issues found 222 - ✅ Show Sage recommendations 223 224 --- 225 226 ## 📊 Coverage Targets 227 228 | Module Type | Target | 229 | ----------------- | ------ | 230 | **Utilities** | 90%+ | 231 | **Core Modules** | 80%+ | 232 | **Orchestration** | 50%+ | 233 234 Run `npm run coverage` to see current status. 235 236 --- 237 238 ## 🐛 Troubleshooting 239 240 ### ESLint: "Cannot find module 'globals'" 241 242 ```bash 243 # From nix-shell: 244 npm install -D globals 245 ``` 246 247 ### Prettier: "Code is not formatted" 248 249 ```bash 250 npm run format 251 ``` 252 253 ### Tests: "No test files found" 254 255 Create test files: `src/module-name.test.js` 256 257 ### Coverage: Below target 258 259 Generate tests for uncovered files: 260 261 ```bash 262 # See which files need tests 263 npm run coverage 264 265 # Tell Cline: 266 "Generate tests for src/capture.js to reach 70% coverage" 267 ``` 268 269 ### Sage: "Command not found" 270 271 ```bash 272 npm install -D @tigrisdata/sage 273 npx sage init 274 ``` 275 276 --- 277 278 ## 💡 Best Practices 279 280 ### 1. Test-Driven Development 281 282 ```javascript 283 // Write test first (src/capture.test.js) 284 import { test } from 'node:test'; 285 import assert from 'node:assert'; 286 import { captureScreenshot } from './capture.js'; 287 288 test('captureScreenshot saves desktop screenshot', async () => { 289 const result = await captureScreenshot('https://example.com'); 290 assert.ok(result.desktop); 291 assert.ok(result.desktop.length > 0); 292 }); 293 294 // Then implement (src/capture.js) 295 export async function captureScreenshot(url) { 296 // Implementation 297 } 298 ``` 299 300 ### 2. Incremental Quality Checks 301 302 Don't wait until the end: 303 304 ```bash 305 # After each module: 306 npm run quality-check 307 308 # Fix issues immediately: 309 npm run lint:fix 310 ``` 311 312 ### 3. Cline Custom Commands 313 314 Create shortcuts in Cline context: 315 316 - "qc" = "npm run quality-check" 317 - "fix" = "Fix issues in .quality-reports/" 318 - "test module" = "Generate tests for [current file]" 319 320 --- 321 322 ## 📖 Configuration Files 323 324 | File | Purpose | 325 | -------------------------- | ------------------------ | 326 | `eslint.config.js` | ESLint rules | 327 | `.prettierrc` | Prettier settings | 328 | `.prettierignore` | Files to skip formatting | 329 | `scripts/quality-check.js` | Main quality script | 330 | `.vscode/tasks.json` | VSCodium shortcuts | 331 | `package.json` | npm scripts | 332 333 --- 334 335 ## 🎓 Learning Resources 336 337 ### ESLint 338 339 - Rules: https://eslint.org/docs/rules/ 340 - Cline can auto-fix most issues 341 342 ### Prettier 343 344 - Options: https://prettier.io/docs/en/options.html 345 - Auto-formats on save (if VSCodium plugin installed) 346 347 ### Node Test Runner 348 349 - Docs: https://nodejs.org/api/test.html 350 - Built-in to Node 18+, no external dependencies 351 352 ### c8 Coverage 353 354 - Docs: https://github.com/bcoe/c8 355 - HTML reports in `coverage/index.html` 356 357 ### Sage 358 359 - GitHub: https://github.com/usetig/sage 360 - CLI-based AI code review 361 362 --- 363 364 ## ✅ Quality Checklist 365 366 Before committing code: 367 368 - [ ] `npm run lint` passes 369 - [ ] `npm run format:check` passes 370 - [ ] `npm test` all passing 371 - [ ] Coverage ≥ 70% for new modules 372 - [ ] Sage review addressed (if using) 373 - [ ] `.quality-reports/summary.json` shows "passed": true 374 375 --- 376 377 ## 🔮 Future Enhancements 378 379 - [ ] GitHub Actions CI/CD (when repo ready) 380 - [ ] Automated Sage reviews on git push 381 - [ ] Coverage trends over time 382 - [ ] Performance benchmarks 383 - [ ] Mutation testing (Stryker) 384 385 --- 386 387 ## Need Help? 388 389 Check `.quality-reports/summary.json` for detailed issues, then ask Cline: 390 391 ``` 392 "Fix the issues found in .quality-reports/. 393 Show me what you fixed and why." 394 ```