Comprehensive repository analysis

1{
2  "task": "comprehensive_repository_analysis",
3  "objective": "Conduct exhaustive analysis of entire codebase to identify, prioritize, fix, and document ALL verifiable bugs, security vulnerabilities, and critical issues across any technology stack",
4  "analysis_phases": [
5    {
6      "phase": 1,
7      "name": "Repository Discovery & Mapping",
8      "steps": [
9        {
10          "step": "1.1",
11          "title": "Architecture & Structure Analysis",
12          "actions": [
13            "Map complete directory structure (src/, lib/, tests/, docs/, config/, scripts/, build/, deploy/)",
14            "Identify all technology stacks and frameworks in use",
15            "Parse dependency manifests (package.json, requirements.txt, go.mod, pom.xml, Gemfile, Cargo.toml, composer.json)",
16            "Document entry points, main execution paths, and module boundaries",
17            "Analyze build systems (Webpack, Gradle, Maven, Make, CMake)",
18            "Review CI/CD configurations (GitHub Actions, GitLab CI, Jenkins, CircleCI)",
19            "Examine existing documentation (README, CONTRIBUTING, API specs, architecture diagrams)"
20          ]
21        },
22        {
23          "step": "1.2",
24          "title": "Development Environment Inventory",
25          "actions": [
26            "Identify testing frameworks (Jest, Mocha, pytest, PHPUnit, Go test, JUnit, RSpec, xUnit)",
27            "Review linter/formatter configs (ESLint, Prettier, Black, Flake8, RuboCop, golangci-lint, Checkstyle)",
28            "Scan for inline issue markers (TODO, FIXME, HACK, XXX, BUG, NOTE)",
29            "Analyze git history for problematic patterns and recent hotfixes",
30            "Extract existing test coverage reports and metrics",
31            "Identify code analysis tools already in use (SonarQube, CodeClimate, etc.)"
32          ]
33        }
34      ]
35    },
36    {
37      "phase": 2,
38      "name": "Systematic Bug Discovery",
39      "bug_categories": [
40        {
41          "category": "CRITICAL",
42          "severity": "P0",
43          "types": [
44            "SQL Injection vulnerabilities",
45            "Cross-Site Scripting (XSS) flaws",
46            "Cross-Site Request Forgery (CSRF) vulnerabilities",
47            "Authentication/Authorization bypass",
48            "Remote Code Execution (RCE) risks",
49            "Data corruption or permanent data loss",
50            "System crashes, deadlocks, or infinite loops",
51            "Memory leaks and resource exhaustion",
52            "Insecure cryptographic implementations",
53            "Hardcoded secrets or credentials"
54          ]
55        },
56        {
57          "category": "FUNCTIONAL",
58          "severity": "P1-P2",
59          "types": [
60            "Logic errors (incorrect conditionals, wrong calculations, off-by-one errors)",
61            "State management issues (race conditions, stale state, improper mutations)",
62            "Incorrect API contracts or request/response mappings",
63            "Missing or insufficient input validation",
64            "Broken business logic or workflow violations",
65            "Incorrect data transformations or serialization",
66            "Type mismatches or unsafe type coercions",
67            "Incorrect exception handling or error propagation"
68          ]
69        },
70        {
71          "category": "INTEGRATION",
72          "severity": "P2",
73          "types": [
74            "Incorrect external API usage or outdated endpoints",
75            "Database query errors, SQL syntax issues, or N+1 problems",
76            "Message queue handling failures (RabbitMQ, Kafka, SQS)",
77            "File system operation errors (permissions, path traversal)",
78            "Network communication issues (timeouts, retries, connection pooling)",
79            "Cache inconsistency or invalidation problems",
80            "Third-party library misuse or version incompatibilities"
81          ]
82        },
83        {
84          "category": "EDGE_CASES",
85          "severity": "P2-P3",
86          "types": [
87            "Null/undefined/nil/None pointer dereferences",
88            "Empty array/list/collection handling",
89            "Zero or negative value edge cases",
90            "Boundary conditions (max/min integers, string length limits)",
91            "Missing error handling or swallowed exceptions",
92            "Timeout and retry logic failures",
93            "Concurrent access issues without proper locking",
94            "Overflow/underflow in numeric operations"
95          ]
96        },
97        {
98          "category": "CODE_QUALITY",
99          "severity": "P3-P4",
100          "types": [
101            "Deprecated API usage",
102            "Dead code or unreachable code paths",
103            "Circular dependencies",
104            "Performance bottlenecks (inefficient algorithms, redundant operations)",
105            "Missing or incorrect type annotations",
106            "Inconsistent error handling patterns",
107            "Resource leaks (file handles, database connections, network sockets)",
108            "Improper logging (sensitive data exposure, insufficient context)"
109          ]
110        }
111      ],
112      "discovery_methods": [
113        "Static code analysis using language-specific tools",
114        "Pattern matching for common anti-patterns and code smells",
115        "Dependency vulnerability scanning (npm audit, pip-audit, bundle-audit, cargo audit)",
116        "Control flow and data flow analysis",
117        "Dead code detection",
118        "Configuration validation against best practices",
119        "Documentation-to-implementation cross-verification",
120        "Security-focused code review"
121      ]
122    },
123    {
124      "phase": 3,
125      "name": "Bug Documentation & Prioritization",
126      "bug_report_schema": {
127        "bug_id": "Sequential identifier (BUG-001, BUG-002, etc.)",
128        "severity": {
129          "type": "enum",
130          "values": [
131            "CRITICAL",
132            "HIGH",
133            "MEDIUM",
134            "LOW"
135          ],
136          "description": "Bug severity level"
137        },
138        "category": {
139          "type": "enum",
140          "values": [
141            "SECURITY",
142            "FUNCTIONAL",
143            "PERFORMANCE",
144            "INTEGRATION",
145            "CODE_QUALITY"
146          ],
147          "description": "Bug classification"
148        },
149        "location": {
150          "files": [
151            "Array of affected file paths with line numbers"
152          ],
153          "component": "Module/Service/Feature name",
154          "function": "Specific function or method name"
155        },
156        "description": {
157          "current_behavior": "What's broken or wrong",
158          "expected_behavior": "What should happen instead",
159          "root_cause": "Technical explanation of why it's broken"
160        },
161        "impact_assessment": {
162          "user_impact": "Effect on end users (data loss, security exposure, UX degradation)",
163          "system_impact": "Effect on system (performance, stability, scalability)",
164          "business_impact": "Effect on business (compliance, revenue, reputation, legal)"
165        },
166        "reproduction": {
167          "steps": [
168            "Step-by-step instructions to reproduce"
169          ],
170          "test_data": "Sample data or conditions needed",
171          "actual_result": "What happens when reproduced",
172          "expected_result": "What should happen"
173        },
174        "verification": {
175          "code_snippet": "Demonstrative code showing the bug",
176          "test_case": "Test that would fail due to this bug",
177          "logs_or_metrics": "Evidence from logs or monitoring"
178        },
179        "dependencies": {
180          "related_bugs": [
181            "Array of related BUG-IDs"
182          ],
183          "blocking_issues": [
184            "Array of bugs that must be fixed first"
185          ],
186          "blocked_by": [
187            "External factors preventing fix"
188          ]
189        },
190        "metadata": {
191          "discovered_date": "ISO 8601 timestamp",
192          "discovered_by": "Tool or method used",
193          "cve_id": "If applicable, CVE identifier",
194          "cwe_id": "If applicable, CWE identifier"
195        }
196      },
197      "prioritization_matrix": {
198        "criteria": [
199          {
200            "factor": "severity",
201            "weight": 0.4,
202            "scale": "CRITICAL=100, HIGH=70, MEDIUM=40, LOW=10"
203          },
204          {
205            "factor": "user_impact",
206            "weight": 0.3,
207            "scale": "All users=100, Many=70, Some=40, Few=10"
208          },
209          {
210            "factor": "fix_complexity",
211            "weight": 0.15,
212            "scale": "Simple=100, Medium=60, Complex=20"
213          },
214          {
215            "factor": "regression_risk",
216            "weight": 0.15,
217            "scale": "Low=100, Medium=60, High=20"
218          }
219        ],
220        "formula": "priority_score = Σ(factor_value × weight)"
221      }
222    },
223    {
224      "phase": 4,
225      "name": "Fix Implementation",
226      "fix_workflow": [
227        {
228          "step": 1,
229          "action": "Create isolated fix branch",
230          "naming": "fix/BUG-{id}-{short-description}"
231        },
232        {
233          "step": 2,
234          "action": "Write failing test FIRST",
235          "rationale": "Test-Driven Development ensures fix is verifiable"
236        },
237        {
238          "step": 3,
239          "action": "Implement minimal, focused fix",
240          "principle": "Smallest change that correctly resolves the issue"
241        },
242        {
243          "step": 4,
244          "action": "Verify test now passes",
245          "validation": "Run specific test and related test suite"
246        },
247        {
248          "step": 5,
249          "action": "Run full regression test suite",
250          "validation": "Ensure no existing functionality breaks"
251        },
252        {
253          "step": 6,
254          "action": "Update documentation",
255          "scope": "API docs, inline comments, changelog"
256        }
257      ],
258      "fix_principles": [
259        "MINIMAL_CHANGE: Make the smallest change that correctly fixes the issue",
260        "NO_SCOPE_CREEP: Avoid unrelated refactoring or feature additions",
261        "BACKWARDS_COMPATIBLE: Preserve existing API contracts unless bug itself is breaking",
262        "FOLLOW_CONVENTIONS: Adhere to project's existing code style and patterns",
263        "DEFENSIVE_PROGRAMMING: Add guards to prevent similar bugs in the future",
264        "EXPLICIT_OVER_IMPLICIT: Make intent clear through code structure and comments",
265        "FAIL_FAST: Validate inputs early and fail with clear error messages"
266      ],
267      "code_review_checklist": [
268        "Fix addresses root cause, not just symptoms",
269        "All edge cases are properly handled",
270        "Error messages are clear, actionable, and don't expose sensitive info",
271        "Performance impact is acceptable (no O(n²) where O(n) suffices)",
272        "Security implications thoroughly considered",
273        "No new compiler warnings or linting errors",
274        "Changes are covered by tests",
275        "Documentation is updated and accurate",
276        "Breaking changes are clearly marked and justified",
277        "Dependencies are up-to-date and secure"
278      ]
279    },
280    {
281      "phase": 5,
282      "name": "Testing & Validation",
283      "test_requirements": {
284        "mandatory_tests_per_fix": [
285          {
286            "type": "unit_test",
287            "description": "Isolated test for the specific bug fix",
288            "coverage": "Must cover the exact code path that was broken"
289          },
290          {
291            "type": "integration_test",
292            "description": "Test if bug involves multiple components",
293            "coverage": "End-to-end flow through affected systems"
294          },
295          {
296            "type": "regression_test",
297            "description": "Ensure fix doesn't break existing functionality",
298            "coverage": "All related features and code paths"
299          },
300          {
301            "type": "edge_case_tests",
302            "description": "Cover boundary conditions and corner cases",
303            "coverage": "Null values, empty inputs, limits, error conditions"
304          }
305        ]
306      },
307      "test_structure_template": {
308        "description": "Language-agnostic test structure",
309        "template": [
310          "describe('BUG-{ID}: {description}', () => {",
311          "  test('reproduces original bug', () => {",
312          "    // This test demonstrates the bug existed",
313          "    // Should fail before fix, pass after",
314          "  });",
315          "",
316          "  test('verifies fix resolves issue', () => {",
317          "    // This test proves correct behavior after fix",
318          "  });",
319          "",
320          "  test('handles edge case: {case}', () => {",
321          "    // Additional coverage for related scenarios",
322          "  });",
323          "});"
324        ]
325      },
326      "validation_steps": [
327        {
328          "step": "Run full test suite",
329          "commands": {
330            "javascript": "npm test",
331            "python": "pytest",
332            "go": "go test ./...",
333            "java": "mvn test",
334            "ruby": "bundle exec rspec",
335            "rust": "cargo test",
336            "php": "phpunit"
337          }
338        },
339        {
340          "step": "Measure code coverage",
341          "tools": [
342            "Istanbul/NYC",
343            "Coverage.py",
344            "JaCoCo",
345            "SimpleCov",
346            "Tarpaulin"
347          ]
348        },
349        {
350          "step": "Run static analysis",
351          "tools": [
352            "ESLint",
353            "Pylint",
354            "golangci-lint",
355            "SpotBugs",
356            "Clippy"
357          ]
358        },
359        {
360          "step": "Performance benchmarking",
361          "condition": "If fix affects hot paths or critical operations"
362        },
363        {
364          "step": "Security scanning",
365          "tools": [
366            "Snyk",
367            "OWASP Dependency-Check",
368            "Trivy",
369            "Bandit"
370          ]
371        }
372      ]
373    },
374    {
375      "phase": 6,
376      "name": "Documentation & Reporting",
377      "fix_documentation_requirements": [
378        "Update inline code comments explaining the fix and why it was necessary",
379        "Revise API documentation if behavior changed",
380        "Update CHANGELOG.md with bug fix entry",
381        "Create or update troubleshooting guides",
382        "Document any workarounds for deferred/unfixed issues",
383        "Add migration notes if fix requires user action"
384      ],
385      "executive_summary_template": {
386        "title": "Bug Fix Report - {repository_name}",
387        "metadata": {
388          "date": "ISO 8601 date",
389          "analyzer": "Tool/Person name",
390          "repository": "Full repository path",
391          "commit_hash": "Git commit SHA",
392          "duration": "Analysis duration in hours"
393        },
394        "overview": {
395          "total_bugs_found": "integer",
396          "total_bugs_fixed": "integer",
397          "bugs_deferred": "integer",
398          "test_coverage_before": "percentage",
399          "test_coverage_after": "percentage",
400          "files_analyzed": "integer",
401          "lines_of_code": "integer"
402        },
403        "critical_findings": [
404          "Top 3-5 most critical bugs found and their fixes"
405        ],
406        "fix_summary_by_category": {
407          "security": "count",
408          "functional": "count",
409          "performance": "count",
410          "integration": "count",
411          "code_quality": "count"
412        },
413        "detailed_fix_table": {
414          "columns": [
415            "BUG-ID",
416            "File",
417            "Line",
418            "Category",
419            "Severity",
420            "Description",
421            "Status",
422            "Test Added"
423          ],
424          "format": "Markdown table or CSV"
425        },
426        "risk_assessment": {
427          "remaining_high_priority": [
428            "List of unfixed critical issues"
429          ],
430          "recommended_next_steps": [
431            "Prioritized action items"
432          ],
433          "technical_debt": [
434            "Summary of identified tech debt"
435          ],
436          "breaking_changes": [
437            "Any backwards-incompatible fixes"
438          ]
439        },
440        "testing_results": {
441          "test_command": "Exact command used to run tests",
442          "tests_passed": "X out of Y",
443          "tests_failed": "count with reasons",
444          "tests_added": "count",
445          "coverage_delta": "+X% or -X%"
446        }
447      },
448      "deliverables_checklist": [
449        "All bugs documented in standardized format",
450        "Fixes implemented with minimal scope",
451        "Test suite updated and passing",
452        "Documentation updated (code, API, user guides)",
453        "Code review completed and approved",
454        "Performance impact assessed and acceptable",
455        "Security review conducted for security-related fixes",
456        "Deployment notes and rollback plan prepared",
457        "Changelog updated with user-facing changes",
458        "Stakeholders notified of critical fixes"
459      ]
460    },
461    {
462      "phase": 7,
463      "name": "Continuous Improvement",
464      "pattern_analysis": {
465        "objectives": [
466          "Identify recurring bug patterns across codebase",
467          "Detect architectural issues enabling bugs",
468          "Find gaps in testing strategy",
469          "Highlight areas with technical debt"
470        ],
471        "outputs": [
472          "Common bug pattern report",
473          "Preventive measure recommendations",
474          "Tooling improvement suggestions",
475          "Architectural refactoring proposals"
476        ]
477      },
478      "monitoring_recommendations": {
479        "metrics_to_track": [
480          "Bug discovery rate over time",
481          "Time to resolution by severity",
482          "Regression rate (bugs reintroduced)",
483          "Test coverage percentage",
484          "Code churn in bug-prone areas",
485          "Dependency vulnerability count"
486        ],
487        "alerting_rules": [
488          "Critical security vulnerabilities in dependencies",
489          "Test suite failures",
490          "Code coverage drops below threshold",
491          "Performance degradation in key operations"
492        ],
493        "logging_improvements": [
494          "Add structured logging where missing",
495          "Include correlation IDs for request tracing",
496          "Log security-relevant events",
497          "Ensure error logs include stack traces and context"
498        ]
499      }
500    }
501  ],
502  "constraints_and_best_practices": [
503    "NEVER compromise security for simplicity or convenience",
504    "MAINTAIN complete audit trail of all changes",
505    "FOLLOW semantic versioning if fixes change public API",
506    "RESPECT rate limits when testing external services",
507    "USE feature flags for high-risk or gradual rollout fixes",
508    "DOCUMENT all assumptions made during analysis",
509    "CONSIDER rollback strategy for every fix",
510    "PREFER backwards-compatible fixes when possible",
511    "AVOID introducing new dependencies without justification",
512    "TEST in multiple environments when applicable"
513  ],
514  "output_formats": [
515    {
516      "format": "markdown",
517      "purpose": "Human-readable documentation and reports",
518      "filename_pattern": "bug_report_{date}.md"
519    },
520    {
521      "format": "json",
522      "purpose": "Machine-readable for automated processing",
523      "filename_pattern": "bug_data_{date}.json",
524      "schema": "Follow bug_report_schema defined in Phase 3"
525    },
526    {
527      "format": "csv",
528      "purpose": "Import into bug tracking systems (Jira, GitHub Issues)",
529      "filename_pattern": "bugs_{date}.csv",
530      "columns": [
531        "BUG-ID",
532        "Severity",
533        "Category",
534        "File",
535        "Line",
536        "Description",
537        "Status"
538      ]
539    },
540    {
541      "format": "yaml",
542      "purpose": "Configuration-friendly format for CI/CD integration",
543      "filename_pattern": "bug_config_{date}.yaml"
544    }
545  ],
546  "special_considerations": {
547    "monorepos": "Analyze each package/workspace separately with cross-package dependency tracking",
548    "microservices": "Consider inter-service contracts, API compatibility, and distributed tracing",
549    "legacy_code": "Balance fix risk vs benefit; prioritize high-impact, low-risk fixes",
550    "third_party_dependencies": "Report vulnerabilities upstream; consider alternatives if unmaintained",
551    "high_traffic_systems": "Consider deployment strategies (blue-green, canary) for fixes",
552    "regulated_industries": "Ensure compliance requirements met (HIPAA, PCI-DSS, SOC2, GDPR)",
553    "open_source_projects": "Follow contribution guidelines; engage with maintainers before large changes"
554  },
555  "success_criteria": {
556    "quantitative": [
557      "All CRITICAL and HIGH severity bugs addressed",
558      "Test coverage increased by at least X%",
559      "Zero security vulnerabilities in dependencies",
560      "All tests passing",
561      "Code quality metrics improved (cyclomatic complexity, maintainability index)"
562    ],
563    "qualitative": [
564      "Codebase is more maintainable",
565      "Documentation is clear and comprehensive",
566      "Team can confidently deploy fixes",
567      "Future bug prevention mechanisms in place",
568      "Development velocity improved"
569    ]
570  }
571}