opencode-codegraph 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.1.5 - 2026-03-20
+
+- add unified next-action summary to review-trace status output
+- surface next-action guidance in post-commit OpenCode plugin metadata and review-trace summaries
+- document the next-action workflow in plugin and integration docs
+
+## 0.1.4 - 2026-03-20
+
+- add conversational pre-edit guidance when a chat message suggests code modification
+- append durable review-trace summary after `git commit` when trace artifacts are available
+- add unified `/status` workflow for freshness plus latest review-trace inspection in the surrounding OpenCode setup
+
+## 0.1.3 - 2026-03-20
+
+- surface durable review-trace summary back into OpenCode after commit
+- add machine-readable `review_trace_status.py --json`
+
+## 0.1.2 - 2026-03-20
+
+- fix `pattern-results` API path handling in the plugin client
+- align local OpenCode workspace installation with the published plugin flow

package/README.md

@@ -23,7 +23,7 @@ Automatically enriches AI conversations with Code Property Graph data -- securit
 
 ### Auto-Enrichment
 
-When you mention a file in chat, the plugin adds CPG context automatically:
+When you mention a file in chat, the plugin adds CPG context automatically:
 
 ```
 You: "Refactor src/api/routers/webhook.py"
@@ -32,18 +32,20 @@ Plugin injects:
   ### CPG context: src/api/routers/webhook.py
   **12 methods** in file:
   - `receive_github_webhook` CC=5 fan_in=0 fan_out=3 [entry]
-  - `_handle_push` CC=2 fan_in=4 fan_out=2
-  **2 security findings:**
-  - CWE-89 L42: SQL injection in query parameter
-```
+  - `_handle_push` CC=2 fan_in=4 fan_out=2
+  **2 security findings:**
+  - CWE-89 L42: SQL injection in query parameter
+```
+
+If the message also suggests an edit intent (`refactor`, `fix`, `modify`, `update`, etc.), the plugin appends a pre-edit warning block with complexity, fan-out, dead-code, and security hints for the referenced file.
 
 ### System Prompt
 
 Every conversation includes a project summary with file count, top complexity hotspots, and open security findings.
 
-### Post-Commit Updates
-
-After `git commit`, the plugin triggers incremental CPG re-parsing via GoCPG and syncs the ChromaDB vector store.
+### Post-Commit Updates
+
+After `git commit`, the plugin triggers incremental CPG re-parsing via GoCPG and syncs the ChromaDB vector store. If durable review-trace artifacts exist for the new `HEAD`, the plugin also appends a short review-trace summary with findings, recommendations, and a single next action to take.
 
 ### Custom Tools
 
@@ -62,10 +64,12 @@ Place in `.opencode/commands/`:
 
 | Command | Description |
 |---------|-------------|
-| `/review` | CPG-powered code review |
-| `/audit` | Full codebase audit (12 dimensions) |
-| `/explain` | Function analysis with call graph |
-| `/onboard` | Codebase understanding |
+| `/review` | CPG-powered code review |
+| `/audit` | Full codebase audit (12 dimensions) |
+| `/explain` | Function analysis with call graph |
+| `/onboard` | Codebase understanding |
+| `/update` | Freshness check and incremental CPG update |
+| `/status` | Unified freshness + latest review-trace status |
 
 ## Custom Agent
 
@@ -80,12 +84,13 @@ Place in `.opencode/commands/`:
 
 ## Hooks
 
-| Hook | Purpose |
-|------|---------|
-| `experimental.chat.system.transform` | Inject project summary into system prompt |
-| `chat.message` | Add CPG context for mentioned files |
-| `tool.execute.after` | Trigger CPG update after git commit |
-| `permission.ask` | Auto-allow `codegraph_*` tools |
+| Hook | Purpose |
+|------|---------|
+| `experimental.chat.system.transform` | Inject project summary into system prompt |
+| `chat.message` | Add CPG context for mentioned files |
+| `chat.message` (edit intent) | Add pre-edit warnings for files likely to be modified |
+| `tool.execute.after` | Trigger CPG update after git commit and append review-trace summary with next action |
+| `permission.ask` | Auto-allow `codegraph_*` tools |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-codegraph",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "OpenCode plugin for CodeGraph CPG-powered code analysis",
   "type": "module",
   "main": "src/index.ts",
@@ -8,7 +8,8 @@
     ".": "./src/index.ts"
   },
   "files": [
-    "src"
+    "src",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/api.ts

@@ -72,7 +72,7 @@ export class CodeGraphAPI {
    * Get CPG context for a specific file.
    * Returns markdown with methods, callers, complexity, and security findings.
    */
-  async getFileCPGContext(projectId: string, filePath: string): Promise<string | null> {
+  async getFileCPGContext(projectId: string, filePath: string): Promise<string | null> {
     const params = new URLSearchParams()
     if (projectId) params.set("project_id", projectId)
     params.set("filename", filePath)
@@ -117,8 +117,80 @@ export class CodeGraphAPI {
       }
     }
 
-    return lines.join("\n")
-  }
+    return lines.join("\n")
+  }
+
+  /**
+   * Get pre-edit guidance for a specific file when the user is likely to modify it.
+   */
+  async getPreEditGuidance(projectId: string, filePath: string): Promise<string | null> {
+    const params = new URLSearchParams()
+    if (projectId) params.set("project_id", projectId)
+    params.set("filename", filePath)
+    const findingsParams = new URLSearchParams(params)
+    findingsParams.set("category", "security")
+
+    const [methodsRes, findingsRes] = await Promise.allSettled([
+      this.fetch(`/api/v1/cpg/methods?${params}`),
+      this.fetch(`/api/v1/cpg/pattern-results?${findingsParams.toString()}`),
+    ])
+
+    const methods = methodsRes.status === "fulfilled" ? methodsRes.value?.results || [] : []
+    const findings = findingsRes.status === "fulfilled" ? findingsRes.value?.results || [] : []
+
+    const highComplexity = methods.filter((m: any) => (m.cyclomatic_complexity ?? 0) >= 15)
+    const highFanOut = methods.filter((m: any) => (m.fan_out ?? 0) >= 30)
+    const deadMethods = methods.filter(
+      (m: any) => (m.fan_in ?? 0) === 0 && !m.is_entry_point && !m.is_external && !m.is_test,
+    )
+
+    if (!highComplexity.length && !highFanOut.length && !deadMethods.length && !findings.length) {
+      return null
+    }
+
+    const lines: string[] = [`### CodeGraph Pre-Edit Warnings: \`${filePath}\``, ""]
+
+    if (highComplexity.length) {
+      lines.push("**High complexity methods:**")
+      for (const method of highComplexity.slice(0, 5)) {
+        lines.push(
+          `- \`${method.name}\` CC=${method.cyclomatic_complexity} fan_in=${method.fan_in} fan_out=${method.fan_out}`,
+        )
+      }
+      lines.push("")
+    }
+
+    if (highFanOut.length) {
+      lines.push("**High fan-out methods:**")
+      for (const method of highFanOut.slice(0, 5)) {
+        lines.push(`- \`${method.name}\` fan_out=${method.fan_out}`)
+      }
+      lines.push("")
+    }
+
+    if (deadMethods.length) {
+      lines.push("**Potential dead methods in file:**")
+      for (const method of deadMethods.slice(0, 5)) {
+        lines.push(`- \`${method.name}\` has fan_in=0`)
+      }
+      lines.push("")
+    }
+
+    if (findings.length) {
+      lines.push(`**Security findings present:** ${findings.length}`)
+      for (const finding of findings.slice(0, 5)) {
+        lines.push(`- **${finding.rule_id}** L${finding.line}: ${finding.message}`)
+      }
+      lines.push("")
+    }
+
+    lines.push("**Before editing:**")
+    lines.push("- Re-check callers before refactoring methods with high fan-in or high complexity.")
+    lines.push("- Update or add tests for the risky paths you touch in this file.")
+    lines.push("- If this file defines handlers/services, verify interface registration after the change.")
+
+    return lines.join("\n")
+  }
 
   /**
    * Trigger incremental CPG update after a git commit.

package/src/index.ts

@@ -16,9 +16,12 @@ import { tool } from "@opencode-ai/plugin/tool"
 import { CodeGraphAPI } from "./api"
 import {
   extractFileRefs,
+  fileNeedsRegistrationCheck,
   formatReviewTraceSummary,
   getHeadCommit,
   isGitCommit,
+  messageSuggestsEditing,
+  recommendedNextActionFromReviewTrace,
   readReviewTraceSnapshot,
 } from "./util"
 
@@ -50,10 +53,11 @@ const codegraphPlugin: Plugin = async (input) => {
     // -----------------------------------------------------------------
     // 2. Chat message: auto-enrich with CPG context for mentioned files
     // -----------------------------------------------------------------
-    "chat.message": async (_inp, output) => {
-      const files = extractFileRefs(output.parts)
-      if (files.length === 0) return
-
+    "chat.message": async (_inp, output) => {
+      const files = extractFileRefs(output.parts)
+      if (files.length === 0) return
+      const editIntent = messageSuggestsEditing(output.parts)
+
       try {
         for (const file of files.slice(0, 5)) {
           const context = await api.getFileCPGContext(projectId, file)
@@ -63,6 +67,23 @@ const codegraphPlugin: Plugin = async (input) => {
               text: context,
             } as any)
           }
+
+          if (editIntent) {
+            const guidance = await api.getPreEditGuidance(projectId, file)
+            if (guidance) {
+              output.parts.push({
+                type: "text",
+                text: guidance,
+              } as any)
+            } else if (fileNeedsRegistrationCheck(file)) {
+              output.parts.push({
+                type: "text",
+                text:
+                  `### CodeGraph Pre-Edit Reminder: \`${file}\`\n\n` +
+                  "- This looks like a handler/service file. After editing, verify that CLI/API/MCP/ACP registration still matches the intended entry points.",
+              } as any)
+            }
+          }
         }
       } catch {
         // CodeGraph API not available — skip silently
@@ -92,6 +113,7 @@ const codegraphPlugin: Plugin = async (input) => {
               codegraph_review_trace_findings: traceSnapshot.review_findings_count ?? null,
               codegraph_review_trace_recommendations:
                 traceSnapshot.review_recommendations?.slice(0, 3) || [],
+              codegraph_review_trace_next_action: recommendedNextActionFromReviewTrace(traceSnapshot),
             }
           }
         }

package/src/util.ts

@@ -20,7 +20,7 @@ export type ReviewTraceSnapshot = {
  * Extract file references from message parts.
  * Looks for file paths in text parts (e.g., `src/api/main.py`, @filename patterns).
  */
-export function extractFileRefs(parts: Array<{ type: string; text?: string }>): string[] {
+export function extractFileRefs(parts: Array<{ type: string; text?: string }>): string[] {
   const files: string[] = []
   const seen = new Set<string>()
 
@@ -68,6 +68,37 @@ export function isGitCommit(output: string): boolean {
   )
 }
 
+/**
+ * Heuristic: detect whether the user is likely asking to modify code.
+ */
+export function messageSuggestsEditing(parts: Array<{ type: string; text?: string }>): boolean {
+  const patterns = [
+    /\b(edit|change|modify|update|refactor|rewrite|implement|fix|patch|remove)\b/i,
+    /\b(add|improve|cleanup|clean up|rename|split|extract)\b/i,
+  ]
+
+  for (const part of parts) {
+    if (part.type !== "text" || !part.text) continue
+    const text = part.text
+    if (patterns.some((pattern) => pattern.test(text))) {
+      return true
+    }
+  }
+
+  return false
+}
+
+export function fileNeedsRegistrationCheck(filePath: string): boolean {
+  const normalized = filePath.replace(/\\/g, "/")
+  const isHandlerLike = ["scenarios/", "services/", "analysis/", "security/"].some((segment) =>
+    normalized.includes(segment),
+  )
+  const isInterfaceLayer = ["src/cli/", "src/api/routers/", "src/tui/commands/", "src/mcp/", "src/acp/"].some(
+    (segment) => normalized.includes(segment),
+  )
+  return isHandlerLike && !isInterfaceLayer
+}
+
 export async function getHeadCommit($: any): Promise<string | null> {
   try {
     const sha = (await $`git rev-parse HEAD`.quiet().text()).trim()
@@ -132,9 +163,39 @@ export function formatReviewTraceSummary(snapshot: ReviewTraceSnapshot): string
     }
   }
 
+  const nextAction = recommendedNextActionFromReviewTrace(snapshot)
+  if (nextAction) {
+    lines.push("", `**Next action:** ${nextAction}`)
+  }
+
   return lines.length > 2 ? lines.join("\n") : null
 }
 
+export function recommendedNextActionFromReviewTrace(snapshot: ReviewTraceSnapshot): string {
+  const status = (snapshot.status || "").toLowerCase()
+  const findingsCount = snapshot.review_findings_count
+  const recommendations = Array.isArray(snapshot.review_recommendations)
+    ? snapshot.review_recommendations.filter(Boolean)
+    : []
+
+  if (snapshot.error) {
+    return "Investigate the review-trace error, then run /review once the pipeline is healthy."
+  }
+  if (status === "running") {
+    return "Wait for review trace completion, then inspect findings and recommendations."
+  }
+  if (status && status !== "completed") {
+    return "Check the latest review trace status again and rerun /review if the result is incomplete."
+  }
+  if (typeof findingsCount === "number" && findingsCount > 0) {
+    if (recommendations.length) {
+      return "Apply the top CodeGraph recommendations, then run /review to confirm the fixes."
+    }
+    return "Inspect the reported findings, fix the highest-risk issues, then run /review again."
+  }
+  return "No review findings recorded; continue with /review or push once the rest of your checks are green."
+}
+
 // File extensions recognized as source code
 const SOURCE_EXTENSIONS = new Set([
   "py",