fix: repair impact workflow that never posted PR comments (#821)

* fix: repair impact analysis workflow that never posted PR comments

The workflow had three bugs preventing it from ever working:
- Used non-existent --ref flag (should be positional arg)
- Used non-existent --json flag (diff-impact uses -f json)
- Missing pull-requests: write permission for commenting

Also adds -j/--json shorthand to diff-impact for consistency with
all other commands, switches npx to node dist/cli.js to eliminate
~5min startup overhead per invocation, removes silent error
swallowing, and updates comments in-place on force-push.

* docs: fix broken --ref and --json flags in diff-impact examples

All docs examples used non-existent --ref flag (should be positional)
and --json flag (should be -f json) for diff-impact commands.

* fix: add contents:read permission and paginate comment listing (#821)

Author: carlos-alm

.github/workflows/codegraph-impact.yml

@@ -1,8 +1,12 @@
 name: Codegraph Impact Analysis
 on: [pull_request]
 
+permissions:
+  contents: read
+  pull-requests: write
+
 concurrency:
-  group: codegraph-impact-${{ github.ref }}
+  group: codegraph-impact-${{ github.event.pull_request.number }}
   cancel-in-progress: true
 
 jobs:
@@ -33,31 +37,47 @@ jobs:
           path: .codegraph/
           key: codegraph-${{ hashFiles('src/**', 'package.json') }}
           restore-keys: codegraph-
-      - name: Build codegraph
-        run: npx codegraph build || (rm -rf .codegraph && npx codegraph build --no-incremental)
+      - name: Build graph
+        run: node dist/cli.js build || (rm -rf .codegraph && node dist/cli.js build --no-incremental)
       - name: Run impact analysis
-        run: |
-          npx codegraph diff-impact --ref origin/${{ github.base_ref }} --json -T > impact.json || echo '{"affectedFiles":[],"summary":null}' > impact.json
+        run: node dist/cli.js diff-impact origin/${{ github.base_ref }} --json -T > impact.json
       - name: Comment on PR
+        if: success()
         uses: actions/github-script@v8
         with:
           script: |
             const fs = require('fs');
             const impact = JSON.parse(fs.readFileSync('impact.json', 'utf-8'));
-            if (!impact.summary) {
+            if (!impact.summary || (impact.summary.functionsChanged === 0 && impact.summary.callersAffected === 0)) {
               console.log('No impact data to report.');
               return;
             }
             const body = `## Codegraph Impact Analysis\n\n` +
-              `**${impact.summary.functionsChanged} functions changed** -> ` +
+              `**${impact.summary.functionsChanged} functions changed** → ` +
               `**${impact.summary.callersAffected} callers affected** across ` +
-              `**${impact.summary.filesAffected} files**.\n\n` +
+              `**${impact.summary.filesAffected} files**\n\n` +
               (impact.affectedFunctions || []).slice(0, 20).map(f =>
                 `- \`${f.name}\` in \`${f.file}:${f.line}\` (${f.transitiveCallers} transitive callers)`
               ).join('\n');
-            github.rest.issues.createComment({
+            // Update existing comment or create new one
+            const comments = await github.paginate(github.rest.issues.listComments, {
               owner: context.repo.owner,
               repo: context.repo.repo,
               issue_number: context.issue.number,
-              body
             });
+            const existing = comments.find(c => c.body.startsWith('## Codegraph Impact Analysis'));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }

docs/guides/ai-agent-guide.md

@@ -960,7 +960,7 @@ Add a GitHub Actions workflow that posts `diff-impact` results on every PR:
 
 - name: Analyze PR impact
   run: |
-    npx @optave/codegraph diff-impact origin/${{ github.base_ref }} --json -T > impact.json
+    npx @optave/codegraph diff-impact origin/${{ github.base_ref }} -f json -T > impact.json
 
 - name: Comment on PR
   uses: actions/github-script@v7

docs/guides/recommended-practices.md

@@ -33,7 +33,7 @@ See what your branch will affect before pushing:
 ```bash
 # .husky/pre-push
 codegraph build
-codegraph diff-impact --ref origin/main --no-tests
+codegraph diff-impact origin/main --no-tests
 ```
 
 This prints a summary like:
@@ -47,7 +47,7 @@ If you want to **block pushes** that exceed a threshold, add a check:
 ```bash
 # .husky/pre-push
 codegraph build
-IMPACT=$(codegraph diff-impact --ref origin/main --no-tests --json)
+IMPACT=$(codegraph diff-impact origin/main --no-tests -f json)
 AFFECTED=$(echo "$IMPACT" | node -e "
   const d = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
   console.log(d.summary?.callersAffected || 0)
@@ -98,7 +98,7 @@ Add a threshold check to your CI pipeline:
 - name: Check impact threshold
   run: |
     npx codegraph build
-    IMPACT=$(npx codegraph diff-impact --ref origin/${{ github.base_ref }} --json)
+    IMPACT=$(npx codegraph diff-impact origin/${{ github.base_ref }} -f json)
     AFFECTED=$(echo "$IMPACT" | node -e "
       const d = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
       console.log(d.summary?.callersAffected || 0)

docs/use-cases/harness-engineering.md

@@ -198,7 +198,7 @@ All of the above works in CI pipelines, not just locally:
 
 - name: Impact comment on PR
   run: |
-    IMPACT=$(npx codegraph diff-impact --ref origin/${{ github.base_ref }} -T)
+    IMPACT=$(npx codegraph diff-impact origin/${{ github.base_ref }} -T)
     gh pr comment ${{ github.event.number }} --body "$IMPACT"
 ```
 

src/cli/commands/diff-impact.ts

@@ -13,6 +13,7 @@ export const command: CommandDefinition = {
     ['--ndjson', 'Newline-delimited JSON output'],
     ['--staged', 'Analyze staged changes instead of unstaged'],
     ['--depth <n>', 'Max transitive caller depth', '3'],
+    ['-j, --json', 'Output as JSON (shorthand for -f json)'],
     ['-f, --format <format>', 'Output format: text, mermaid, json', 'text'],
     ['--no-implementations', 'Exclude interface/trait implementors from blast radius'],
   ],
@@ -21,7 +22,7 @@ export const command: CommandDefinition = {
       ref,
       staged: opts.staged,
       depth: parseInt(opts.depth as string, 10),
-      format: opts.format,
+      format: opts.json ? 'json' : opts.format,
       includeImplementors: opts.implementations !== false,
       ...ctx.resolveQueryOpts(opts),
     });