|
| 1 | +"""Contextual next-step suggestions for MCP tool responses. |
| 2 | +
|
| 3 | +Computes follow-up tool suggestions based on what a tool returned, |
| 4 | +so LLM agents know what to invoke next. Only used by MCP servers |
| 5 | +(HTTP and stdio), not the CLI. |
| 6 | +""" |
| 7 | + |
| 8 | + |
| 9 | +def compute_next_steps(tool_name, result): |
| 10 | + """Return a list of next-step suggestion strings for a tool result. |
| 11 | +
|
| 12 | + Args: |
| 13 | + tool_name: Name of the tool that produced the result. |
| 14 | + result: The tool's return value (dict or list). |
| 15 | +
|
| 16 | + Returns: |
| 17 | + List of strings, each a brief actionable suggestion. Empty list |
| 18 | + if no suggestions apply. |
| 19 | + """ |
| 20 | + fn = _TOOL_HINTS.get(tool_name) |
| 21 | + if fn is None: |
| 22 | + return [] |
| 23 | + return fn(result) |
| 24 | + |
| 25 | + |
| 26 | +# ------------------------------------------------------------------ # |
| 27 | +# Per-tool hint functions |
| 28 | +# ------------------------------------------------------------------ # |
| 29 | + |
| 30 | +def _hints_analyze(result): |
| 31 | + if isinstance(result, dict) and "code_files_scanned" in result: |
| 32 | + return [ |
| 33 | + "Run 'risk_map' to identify high-risk files.", |
| 34 | + "Run 'test_gaps' to find untested code.", |
| 35 | + "Run 'triage' for a combined risk + gap + stale overview.", |
| 36 | + ] |
| 37 | + return [] |
| 38 | + |
| 39 | + |
| 40 | +def _hints_update(result): |
| 41 | + if isinstance(result, dict) and result.get("files_updated", 0) > 0: |
| 42 | + return [ |
| 43 | + "Run 'diff_impact' to see which tests are affected by the changes.", |
| 44 | + "Run 'risk_map' to check updated risk scores.", |
| 45 | + ] |
| 46 | + return [] |
| 47 | + |
| 48 | + |
| 49 | +def _hints_risk_map(result): |
| 50 | + if isinstance(result, list) and result: |
| 51 | + top = result[:3] |
| 52 | + files = [r["file_path"] for r in top] |
| 53 | + steps = [ |
| 54 | + "Run 'test_gaps' to find missing test coverage for high-risk files.", |
| 55 | + ] |
| 56 | + # Suggest coupling drilldown for files with high coupling scores |
| 57 | + high_coupling = [ |
| 58 | + r["file_path"] for r in top |
| 59 | + if r.get("breakdown", {}).get("coupling", 0) > 0.3 |
| 60 | + ] |
| 61 | + if high_coupling: |
| 62 | + steps.append( |
| 63 | + f"Run 'coupling {high_coupling[0]}' to see co-change partners." |
| 64 | + ) |
| 65 | + # Suggest churn drilldown for high-churn files |
| 66 | + high_churn = [ |
| 67 | + r["file_path"] for r in top |
| 68 | + if r.get("breakdown", {}).get("churn", 0) > 0.5 |
| 69 | + ] |
| 70 | + if high_churn: |
| 71 | + steps.append( |
| 72 | + f"Run 'churn {high_churn[0]}' for detailed change history." |
| 73 | + ) |
| 74 | + steps.append( |
| 75 | + f"Run 'suggest_tests {files[0]}' for test recommendations on the riskiest file." |
| 76 | + ) |
| 77 | + return steps |
| 78 | + if isinstance(result, list): |
| 79 | + return ["Run 'analyze' to populate risk data."] |
| 80 | + return [] |
| 81 | + |
| 82 | + |
| 83 | +def _hints_diff_impact(result): |
| 84 | + if isinstance(result, list) and result: |
| 85 | + return [ |
| 86 | + "Run the listed tests to verify your changes.", |
| 87 | + "Use 'record_result' to log outcomes for future prioritization.", |
| 88 | + "Run 'coupling' on changed files to check for hidden dependents.", |
| 89 | + ] |
| 90 | + if isinstance(result, list): |
| 91 | + return [ |
| 92 | + "Run 'test_gaps' to check if new code needs tests.", |
| 93 | + "Run 'update' if you've made changes since last analysis.", |
| 94 | + ] |
| 95 | + return [] |
| 96 | + |
| 97 | + |
| 98 | +def _hints_test_gaps(result): |
| 99 | + if isinstance(result, list) and result: |
| 100 | + top_file = result[0]["file_path"] |
| 101 | + return [ |
| 102 | + "Write tests for the highest-churn untested units first.", |
| 103 | + f"Run 'churn {top_file}' to see change frequency.", |
| 104 | + f"Run 'ownership {top_file}' to find who can help write tests.", |
| 105 | + ] |
| 106 | + if isinstance(result, list): |
| 107 | + return ["All code units have test coverage."] |
| 108 | + return [] |
| 109 | + |
| 110 | + |
| 111 | +def _hints_stale_tests(result): |
| 112 | + if isinstance(result, list) and result: |
| 113 | + return [ |
| 114 | + "Update or remove the stale tests listed above.", |
| 115 | + "Run 'update' to re-analyze after fixing test files.", |
| 116 | + ] |
| 117 | + if isinstance(result, list): |
| 118 | + return ["All tests reference current code."] |
| 119 | + return [] |
| 120 | + |
| 121 | + |
| 122 | +def _hints_impact(result): |
| 123 | + if isinstance(result, list) and result: |
| 124 | + return [ |
| 125 | + "Run the impacted tests to verify correctness.", |
| 126 | + "Use 'record_result' to log outcomes for future prioritization.", |
| 127 | + ] |
| 128 | + return [] |
| 129 | + |
| 130 | + |
| 131 | +def _hints_suggest_tests(result): |
| 132 | + if isinstance(result, list) and result: |
| 133 | + return [ |
| 134 | + "Run the suggested tests in order of relevance.", |
| 135 | + "Use 'record_result' to log outcomes for future prioritization.", |
| 136 | + ] |
| 137 | + return [] |
| 138 | + |
| 139 | + |
| 140 | +def _hints_triage(result): |
| 141 | + if isinstance(result, dict) and "summary" in result: |
| 142 | + steps = [] |
| 143 | + if result["summary"].get("total_test_gaps", 0) > 0: |
| 144 | + steps.append( |
| 145 | + "Focus on files appearing in both risk and gap sections." |
| 146 | + ) |
| 147 | + if result["top_risk_files"]: |
| 148 | + top = result["top_risk_files"][0]["file_path"] |
| 149 | + steps.append(f"Run 'suggest_tests {top}' on the highest-risk file.") |
| 150 | + steps.append(f"Run 'ownership {top}' to find who owns the riskiest code.") |
| 151 | + return steps |
| 152 | + return [] |
| 153 | + |
| 154 | + |
| 155 | +# ------------------------------------------------------------------ # |
| 156 | +# Dispatch table |
| 157 | +# ------------------------------------------------------------------ # |
| 158 | + |
| 159 | +_TOOL_HINTS = { |
| 160 | + "analyze": _hints_analyze, |
| 161 | + "update": _hints_update, |
| 162 | + "risk_map": _hints_risk_map, |
| 163 | + "diff_impact": _hints_diff_impact, |
| 164 | + "test_gaps": _hints_test_gaps, |
| 165 | + "stale_tests": _hints_stale_tests, |
| 166 | + "impact": _hints_impact, |
| 167 | + "suggest_tests": _hints_suggest_tests, |
| 168 | + "triage": _hints_triage, |
| 169 | +} |
0 commit comments