fix: break circular dependency cycle and remove dead queryName export

.claude/hooks/check-cycles.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# check-cycles.sh — PreToolUse hook for Bash (git commit)
+# Blocks commits if circular dependencies involve files edited in this session.
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+# Extract the command from tool_input JSON
+COMMAND=$(echo "$INPUT" | node -e "
+  let d='';
+  process.stdin.on('data',c=>d+=c);
+  process.stdin.on('end',()=>{
+    const p=JSON.parse(d).tool_input?.command||'';
+    if(p)process.stdout.write(p);
+  });
+" 2>/dev/null) || true
+
+if [ -z "$COMMAND" ]; then
+  exit 0
+fi
+
+# Only trigger on git commit commands
+if ! echo "$COMMAND" | grep -qE '(^|\s|&&\s*)git\s+commit\b'; then
+  exit 0
+fi
+
+# Guard: codegraph DB must exist
+WORK_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || WORK_ROOT="${CLAUDE_PROJECT_DIR:-.}"
+if [ ! -f "$WORK_ROOT/.codegraph/graph.db" ]; then
+  exit 0
+fi
+
+# Guard: must have staged changes
+STAGED=$(git diff --cached --name-only 2>/dev/null) || true
+if [ -z "$STAGED" ]; then
+  exit 0
+fi
+
+# Load session edit log
+LOG_FILE="$WORK_ROOT/.claude/session-edits.log"
+if [ ! -f "$LOG_FILE" ] || [ ! -s "$LOG_FILE" ]; then
+  exit 0
+fi
+EDITED_FILES=$(awk '{print $2}' "$LOG_FILE" | sort -u)
+
+# Run check with cycles predicate on staged changes
+RESULT=$(node "$WORK_ROOT/src/cli.js" check --staged --json -T 2>/dev/null) || true
+
+if [ -z "$RESULT" ]; then
+  exit 0
+fi
+
+# Check if cycles predicate failed — but only block if a cycle involves
+# a file that was edited in this session
+CYCLES_FAILED=$(echo "$RESULT" | EDITED="$EDITED_FILES" node -e "
+  let d='';
+  process.stdin.on('data',c=>d+=c);
+  process.stdin.on('end',()=>{
+    try {
+      const data=JSON.parse(d);
+      const cyclesPred=(data.predicates||[]).find(p=>p.name==='cycles');
+      if(!cyclesPred || cyclesPred.passed) return;
+      const edited=new Set(process.env.EDITED.split('\\n').filter(Boolean));
+      // Filter to cycles that involve at least one file we edited
+      const relevant=(cyclesPred.cycles||[]).filter(
+        cycle=>cycle.some(f=>edited.has(f))
+      );
+      if(relevant.length===0) return;
+      const summary=relevant.slice(0,5).map(c=>c.join(' -> ')).join('\\n  ');
+      const extra=relevant.length>5?'\\n  ... and '+(relevant.length-5)+' more':'';
+      process.stdout.write(summary+extra);
+    }catch{}
+  });
+" 2>/dev/null) || true
+
+if [ -n "$CYCLES_FAILED" ]; then
+  REASON="BLOCKED: Circular dependencies detected involving files you edited:
+  $CYCLES_FAILED
+Fix the cycles before committing."
+
+  node -e "
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: process.argv[1]
+      }
+    }));
+  " "$REASON"
+  exit 0
+fi
+
+exit 0

.claude/hooks/check-dead-exports.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# check-dead-exports.sh — PreToolUse hook for Bash (git commit)
+# Blocks commits if any src/ file edited in THIS SESSION has exports with zero consumers.
+# Uses the session edit log to scope checks to files you actually touched.
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+# Extract the command from tool_input JSON
+COMMAND=$(echo "$INPUT" | node -e "
+  let d='';
+  process.stdin.on('data',c=>d+=c);
+  process.stdin.on('end',()=>{
+    const p=JSON.parse(d).tool_input?.command||'';
+    if(p)process.stdout.write(p);
+  });
+" 2>/dev/null) || true
+
+if [ -z "$COMMAND" ]; then
+  exit 0
+fi
+
+# Only trigger on git commit commands
+if ! echo "$COMMAND" | grep -qE '(^|\s|&&\s*)git\s+commit\b'; then
+  exit 0
+fi
+
+# Guard: codegraph DB must exist
+WORK_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || WORK_ROOT="${CLAUDE_PROJECT_DIR:-.}"
+if [ ! -f "$WORK_ROOT/.codegraph/graph.db" ]; then
+  exit 0
+fi
+
+# Guard: must have staged changes
+STAGED=$(git diff --cached --name-only 2>/dev/null) || true
+if [ -z "$STAGED" ]; then
+  exit 0
+fi
+
+# Load session edit log to scope checks to files we actually edited
+LOG_FILE="$WORK_ROOT/.claude/session-edits.log"
+if [ ! -f "$LOG_FILE" ] || [ ! -s "$LOG_FILE" ]; then
+  exit 0
+fi
+EDITED_FILES=$(awk '{print $2}' "$LOG_FILE" | sort -u)
+
+# Check each staged source file that was edited in this session
+DEAD_EXPORTS=""
+
+while IFS= read -r file; do
+  # Only check source files
+  case "$file" in
+    src/*.js|src/*.ts|src/*.tsx) ;;
+    *) continue ;;
+  esac
+
+  # Only check files edited in this session
+  if ! echo "$EDITED_FILES" | grep -qxF "$file"; then
+    continue
+  fi
+
+  RESULT=$(node "$WORK_ROOT/src/cli.js" exports "$file" --unused --json 2>/dev/null) || true
+  if [ -z "$RESULT" ]; then
+    continue
+  fi
+
+  # Extract unused export names
+  UNUSED=$(echo "$RESULT" | node -e "
+    let d='';
+    process.stdin.on('data',c=>d+=c);
+    process.stdin.on('end',()=>{
+      try {
+        const data=JSON.parse(d);
+        const unused=(data.results||[]).filter(r=>r.consumerCount===0);
+        if(unused.length>0){
+          process.stdout.write(unused.map(u=>u.name+' ('+data.file+':'+u.line+')').join(', '));
+        }
+      }catch{}
+    });
+  " 2>/dev/null) || true
+
+  if [ -n "$UNUSED" ]; then
+    DEAD_EXPORTS="${DEAD_EXPORTS:+$DEAD_EXPORTS; }$UNUSED"
+  fi
+done <<< "$STAGED"
+
+if [ -n "$DEAD_EXPORTS" ]; then
+  REASON="BLOCKED: Dead exports (zero consumers) detected in files you edited: $DEAD_EXPORTS. Either add consumers, remove the exports, or verify these are intentionally public API."
+
+  node -e "
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: process.argv[1]
+      }
+    }));
+  " "$REASON"
+  exit 0
+fi
+
+exit 0

.claude/hooks/guard-pr-body.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Block PR creation if the body contains "generated with" (case-insensitive)
+
+input="$CLAUDE_TOOL_INPUT"
+
+# Only check gh pr create commands
+echo "$input" | grep -qi 'gh pr create' || exit 0
+
+# Block if body contains "generated with"
+if echo "$input" | grep -qi 'generated with'; then
+  echo "BLOCK: Remove any 'Generated with ...' line from the PR body." >&2
+  exit 2
+fi

.claude/hooks/warn-signature-changes.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# warn-signature-changes.sh — PreToolUse hook for Bash (git commit)
+# Warns when staged changes modify function signatures, highlighting risk
+# level based on the symbol's role (core > utility > others).
+# Informational only — never blocks.
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+# Extract the command from tool_input JSON
+COMMAND=$(echo "$INPUT" | node -e "
+  let d='';
+  process.stdin.on('data',c=>d+=c);
+  process.stdin.on('end',()=>{
+    const p=JSON.parse(d).tool_input?.command||'';
+    if(p)process.stdout.write(p);
+  });
+" 2>/dev/null) || true
+
+if [ -z "$COMMAND" ]; then
+  exit 0
+fi
+
+# Only trigger on git commit commands
+if ! echo "$COMMAND" | grep -qE '(^|\s|&&\s*)git\s+commit\b'; then
+  exit 0
+fi
+
+# Guard: codegraph DB must exist
+WORK_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || WORK_ROOT="${CLAUDE_PROJECT_DIR:-.}"
+if [ ! -f "$WORK_ROOT/.codegraph/graph.db" ]; then
+  exit 0
+fi
+
+# Guard: must have staged changes
+STAGED=$(git diff --cached --name-only 2>/dev/null) || true
+if [ -z "$STAGED" ]; then
+  exit 0
+fi
+
+# Run check --staged to get signature violations, then enrich with role + caller count
+WARNING=$(node -e "
+  const path = require('path');
+  const { checkData } = require(path.join(process.argv[1], 'src/check.js'));
+  const { openReadonlyOrFail } = require(path.join(process.argv[1], 'src/db.js'));
+
+  const result = checkData(undefined, { staged: true, noTests: true });
+  if (!result || result.error) process.exit(0);
+
+  const sigPred = (result.predicates || []).find(p => p.name === 'signatures');
+  if (!sigPred || sigPred.passed || !sigPred.violations.length) process.exit(0);
+
+  const db = openReadonlyOrFail();
+  const lines = [];
+
+  for (const v of sigPred.violations) {
+    // Get role from DB
+    const node = db.prepare(
+      'SELECT role FROM nodes WHERE name = ? AND file = ? AND line = ?'
+    ).get(v.name, v.file, v.line);
+    const role = node?.role || 'unknown';
+
+    // Count transitive callers (BFS, depth 3)
+    const defNode = db.prepare(
+      'SELECT id FROM nodes WHERE name = ? AND file = ? AND line = ?'
+    ).get(v.name, v.file, v.line);
+
+    let callerCount = 0;
+    if (defNode) {
+      const visited = new Set([defNode.id]);
+      let frontier = [defNode.id];
+      for (let d = 0; d < 3; d++) {
+        const next = [];
+        for (const fid of frontier) {
+          const callers = db.prepare(
+            'SELECT DISTINCT n.id FROM edges e JOIN nodes n ON e.source_id = n.id WHERE e.target_id = ? AND e.kind = \\'calls\\''
+          ).all(fid);
+          for (const c of callers) {
+            if (!visited.has(c.id)) {
+              visited.add(c.id);
+              next.push(c.id);
+              callerCount++;
+            }
+          }
+        }
+        frontier = next;
+        if (!frontier.length) break;
+      }
+    }
+
+    const risk = role === 'core' ? 'HIGH' : role === 'utility' ? 'MEDIUM' : 'low';
+    lines.push(risk + ': ' + v.name + ' (' + v.kind + ') [' + role + '] at ' + v.file + ':' + v.line + ' — ' + callerCount + ' transitive callers');
+  }
+
+  db.close();
+
+  if (lines.length > 0) {
+    process.stdout.write(lines.join('\\n'));
+  }
+" "$WORK_ROOT" 2>/dev/null) || true
+
+if [ -z "$WARNING" ]; then
+  exit 0
+fi
+
+# Escape for JSON
+ESCAPED=$(printf '%s' "$WARNING" | node -e "
+  let d='';
+  process.stdin.on('data',c=>d+=c);
+  process.stdin.on('end',()=>process.stdout.write(JSON.stringify(d)));
+" 2>/dev/null) || true
+
+if [ -z "$ESCAPED" ]; then
+  exit 0
+fi
+
+# Inject as additionalContext — informational, never blocks
+node -e "
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+      additionalContext: '[codegraph] Signature changes detected in staged files:\\n' + JSON.parse(process.argv[1])
+    }
+  }));
+" "$ESCAPED" 2>/dev/null || true
+
+exit 0

.claude/settings.json

@@ -14,10 +14,30 @@
             "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-git.sh\"",
             "timeout": 10
           },
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-pr-body.sh\"",
+            "timeout": 10
+          },
           {
             "type": "command",
             "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/show-diff-impact.sh\"",
             "timeout": 15
+          },
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/check-cycles.sh\"",
+            "timeout": 15
+          },
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/check-dead-exports.sh\"",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/warn-signature-changes.sh\"",
+            "timeout": 15
           }
         ]
       },

CHANGELOG.md

@@ -15,7 +15,6 @@ All notable changes to this project will be documented in this file. See [commit
 
 * **native:** fix function-scoped `const` declarations being incorrectly extracted as top-level constants ([#344](https://github.com/optave/codegraph/pull/344))
 
-
 ## [3.0.2](https://github.com/optave/codegraph/compare/v3.0.1...v3.0.2) (2026-03-04)
 
 **Dataflow goes multi-language, build performance recovery, and native engine parity fixes.** This patch extends dataflow analysis from JS/TS-only to all 11 supported languages, recovers build performance lost after CFG/dataflow became default-on, fixes language-aware identifier collection in dataflow, and closes a native engine scoping bug for constants.

CLAUDE.md

@@ -66,6 +66,7 @@ JS source is plain JavaScript (ES modules) in `src/`. No transpilation step. The
 | `boundaries.js` | Architecture boundary rules with onion architecture preset |
 | `owners.js` | CODEOWNERS integration for ownership queries |
 | `snapshot.js` | SQLite DB backup and restore |
+| `sequence.js` | Mermaid sequence diagram generation from call graph edges |
 | `paginate.js` | Pagination helpers for bounded query results |
 | `logger.js` | Structured logging (`warn`, `debug`, `info`, `error`) |
 
@@ -132,6 +133,7 @@ node src/cli.js deps src/<file>.js   # File-level imports and importers
 node src/cli.js diff-impact main     # Impact of current branch vs main
 node src/cli.js complexity -T         # Per-function complexity metrics
 node src/cli.js communities -T       # Community detection & drift analysis
+node src/cli.js sequence <name> -T   # Mermaid sequence diagram from call edges
 node src/cli.js check -T             # Rule engine pass/fail check
 node src/cli.js audit <target> -T    # Combined structural summary + impact + health report
 node src/cli.js triage -T            # Ranked audit priority queue