chore: release v3.1.2

[carlos-alm]

Summary

• Bump version to 3.1.2
• Add CHANGELOG entry for all commits since v3.1.1
• Update ROADMAP progress (Phase 3 status, current version header)
• Update BACKLOG last-updated date
• Fix commit-msg and pre-push hooks against sh -e failure when diff-impact is unavailable (same bug fixed for pre-push on feat/unified-ast-analysis-framework — main never received the fix)

Merge order: The feature branch (feat/unified-ast-analysis-framework) should land on main first. This PR can be merged immediately after.

Test plan

• npm install succeeds with updated package.json
• CHANGELOG renders correctly on GitHub
• git commit no longer fails when diff-impact is unavailable

[greptile-apps]

Greptile Summary

This release PR bumps @optave/codegraph from v3.1.1 to v3.1.2, adds the corresponding CHANGELOG entry (summarising the unified AST analysis framework, CFG rewrite, command/query separation, dynamic-import tracking, and associated bug fixes landed on the feature branch), and refreshes the ROADMAP/BACKLOG docs. The most substantive code change is a two-part bug fix in the Husky git hooks that prevents hook failure under sh -e when diff-impact is unavailable.

Key changes:

• .husky/commit-msg — adds || true to the SUMMARY inline node command so a non-zero exit from the script cannot abort the hook under sh -e strict mode.
• .husky/pre-push — adds 2>/dev/null || true to the AFFECTED assignment (same sh -e guard), and adds [ -n "$AFFECTED" ] before the arithmetic [ "$AFFECTED" -gt 50 ] comparison to prevent an "integer expression expected" error when $AFFECTED is an empty string.
• package.json — main version bumped 3.1.1 → 3.1.2; optional native binary packages jump from 3.1.0 → 3.1.2 (skipping 3.1.1, which intentionally did not republish native binaries).
• CHANGELOG.md / ROADMAP.md / BACKLOG.md — documentation updates aligned to the new release.

Confidence Score: 5/5

• This PR is safe to merge immediately after the prerequisite feature branch lands on main.
• All changes are either documentation/version-number updates or well-targeted defensive fixes to git hooks. The hook fixes correctly handle the sh -e edge case: || true prevents non-zero exits from aborting the hook, and the [ -n "$AFFECTED" ] guard prevents an arithmetic comparison on an empty string. The native binary version jump from 3.1.0 to 3.1.2 (skipping 3.1.1) is intentional and consistent with the stated merge order. No logic regressions are introduced.
• No files require special attention.

Important Files Changed

Filename	Overview
.husky/commit-msg	Adds `
.husky/pre-push	Two-part fix: adds `2>/dev/null
CHANGELOG.md	Well-structured v3.1.2 entry covering features (unified AST framework, CFG rewrite, commands extraction, dynamic imports), bug fixes, performance, and refactors; references all associated PRs.
package.json	Main package bumped 3.1.1 → 3.1.2; optional platform-specific native binaries jump 3.1.0 → 3.1.2 (skipping 3.1.1, which is intentional — native binaries were not republished for 3.1.1).
docs/roadmap/ROADMAP.md	Current version header and Phase 3 in-progress marker both updated from 3.1.1 to 3.1.2; no other changes.
docs/roadmap/BACKLOG.md	Trivial date update from 2026-03-03 to 2026-03-11; no content changes.

Sequence Diagram

sequenceDiagram
    participant Dev as Developer
    participant Hook as Git Hook (sh -e)
    participant CG as codegraph diff-impact
    participant Node as node -e (inline script)

    Dev->>Hook: git commit / git push
    Hook->>CG: codegraph diff-impact ... 2>/dev/null
    alt diff-impact available
        CG-->>Hook: JSON impact data (IMPACT)
    else diff-impact unavailable
        CG-->>Hook: exit non-zero → fallback: node src/cli.js
        Note over Hook,CG: || true ensures IMPACT="" instead of hook abort
    end

    alt IMPACT is non-empty
        Hook->>Node: echo $IMPACT | node -e "..." 2>/dev/null || true
        alt node succeeds
            Node-->>Hook: SUMMARY / AFFECTED value
        else node fails (sh -e risk)
            Note over Node,Hook: || true → empty string, no abort
        end
        alt commit-msg: SUMMARY non-empty
            Hook->>Dev: Appends impact summary to commit message
        end
        alt pre-push: AFFECTED non-empty AND > 50
            Note over Hook: [ -n "$AFFECTED" ] guard prevents<br/>arithmetic error on empty string
            Hook->>Dev: Warning: $AFFECTED functions affected
        end
    end

Loading

_{Last reviewed commit: 3f791fb}

[claude]

Claude finished @carlos-alm's task —— View job

---

PR Review Analysis

Todo List

• Phase 1: Root Cause Analysis
• Phase 2: Configuration Change Detection
• Phase 3: Test Integrity Assessment
• Phase 4: Code Quality Review
• Read and analyze changed files
• Provide final rating and recommendation

Phase 1: Root Cause Analysis ✅

Problem Being Solved: This PR fixes a legitimate bug where git hooks fail when diff-impact command is unavailable (e.g., when codegraph binary is missing or corrupted). The hooks run with sh -e (exit on error), so any command failure aborts the hook entirely.

Why This Approach: The fix adds || true guards to prevent sh -e from aborting hooks when diff-impact fails. This is the correct defensive approach - hooks should gracefully degrade when optional analysis tools are unavailable rather than blocking commits/pushes entirely.

Risk Assessment: Low risk - this is a bug fix that improves reliability without changing core functionality.

Phase 2: Configuration Change Detection ✅

No High-Risk Changes Detected: This is a release PR with routine version bumps and documentation updates. The hook fixes are defensive improvements, not configuration relaxation. No linting rules disabled, test timeouts increased, or build configuration modified.

Phase 3: Test Integrity Assessment ✅

No Test Weakening: No test files modified. No assertions removed. This PR contains only version bumps, changelog entries, and defensive hook improvements.

Phase 4: Code Quality Review ✅

Hook Fixes (.husky/commit-msg, .husky/pre-push)

Excellent fixes addressing the core issue:

• commit-msg: Adds || true to line 5 IMPACT command substitution
• pre-push: Adds comprehensive guards to both IMPACT (line 2) and AFFECTED (line 10) pipelines, plus -n "$AFFECTED" check before integer comparison (line 11)

One minor gap: Greptile correctly identified that the SUMMARY pipeline in .husky/commit-msg:16 lacks the same || true guard. This is an edge case but worth addressing for consistency.

Native Dependency Version Mismatch (Critical Finding)

Major issue in package.json: Native optional dependencies are stuck at 3.1.0 while the main package is 3.1.2. As noted in CLAUDE.md, commit-and-tag-version doesn't trigger the npm version lifecycle hook that runs sync-native-versions.js.

This means:

• Users with native platforms get 3.1.0 binaries + 3.1.2 JS layer
• Potential compatibility issues if native/JS interfaces changed
• This has been accumulating across releases (3.1.1 also had this gap)

Documentation Updates

• CHANGELOG.md: Comprehensive v3.1.2 entry covering all major features
• ROADMAP.md: Routine version header update (3.1.1 → 3.1.2)
• BACKLOG.md: Date update (2026-03-03 → 2026-03-11)

All documentation changes are accurate and well-structured.

Critical Concerns

1. Native dependency version drift: package.json shows @optave/codegraph-* packages at 3.1.0 vs main package 3.1.2. This needs resolution before npm publish.

2. Incomplete hook fix: .husky/commit-msg:16 SUMMARY pipeline lacks || true guard for consistency with the IMPACT fix.

Final Recommendation

• Rating: ⭐⭐⭐☆☆ (3/5)
• Action: REQUEST CHANGES
• Reasoning: While the hook fixes and documentation are excellent, the native dependency version mismatch is a critical issue that must be resolved before publishing. The fix should either: (a) run node scripts/sync-native-versions.js manually, (b) document why native packages remain at 3.1.0, or (c) skip native binary publication for this release.

[claude]

Claude finished @carlos-alm's task —— View job

---

Claude finished @carlos-alm's task —— View job

---

PR Review Analysis

Todo List

• Phase 1: Root Cause Analysis
• Phase 2: Configuration Change Detection
• Phase 3: Test Integrity Assessment
• Phase 4: Code Quality Review
• Read and analyze changed files
• Provide final rating and recommendation

Phase 1: Root Cause Analysis ✅

Problem Being Solved: This PR fixes a legitimate bug where git hooks fail when diff-impact command is unavailable (e.g., when codegraph binary is missing or corrupted). The hooks run with sh -e (exit on error), so any command failure aborts the hook entirely.

Why This Approach: The fix adds || true guards to prevent sh -e from aborting hooks when diff-impact fails. This is the correct defensive approach - hooks should gracefully degrade when optional analysis tools are unavailable rather than blocking commits/pushes entirely.

Risk Assessment: Low risk - this is a bug fix that improves reliability without changing core functionality.

Phase 2: Configuration Change Detection ✅

No High-Risk Changes Detected: This is a release PR with routine version bumps and documentation updates. The hook fixes are defensive improvements, not configuration relaxation. No linting rules disabled, test timeouts increased, or build configuration modified.

Phase 3: Test Integrity Assessment ✅

No Test Weakening: No test files modified. No assertions removed. This PR contains only version bumps, changelog entries, and defensive hook improvements.

Phase 4: Code Quality Review ✅

Hook Fixes (.husky/commit-msg, .husky/pre-push)

Excellent fixes addressing the core issue:

• commit-msg: Adds || true to line 5 IMPACT command substitution
• pre-push: Adds comprehensive guards to both IMPACT (line 2) and AFFECTED (line 10) pipelines, plus -n "$AFFECTED" check before integer comparison (line 11)

One minor gap: The SUMMARY pipeline in .husky/commit-msg:16 lacks the same || true guard. This is an edge case but worth addressing for consistency.

Native Dependency Versions (Corrected Assessment)

Good news: Upon direct inspection, the native optional dependencies in package.json are correctly set to 3.1.2, matching the main package version. The Greptile review may have been based on an earlier state of the PR.

Documentation Updates

Well-executed updates:

• CHANGELOG.md: Comprehensive v3.1.2 entry covering unified AST framework, CFG rewrite, CLI command separation, dynamic imports, hook fixes, complexity improvements, DB caching, and repository pattern migration
• ROADMAP.md: Version header updated from 3.1.1 → 3.1.2, Phase 3 status reflects current progress
• BACKLOG.md: Last-updated date updated from 2026-03-03 → 2026-03-11

All documentation changes are accurate and consistent.

Critical Concerns

1. Minor hook consistency gap: .husky/commit-msg:16 SUMMARY pipeline lacks || true guard for complete consistency with the IMPACT fix.

Final Recommendation

• Rating: ⭐⭐⭐⭐☆ (4/5)
• Action: APPROVE WITH CONDITIONS
• Reasoning: This is a solid release PR that properly fixes legitimate hook failures, updates versions correctly (including native dependencies), and provides comprehensive documentation. The hook fixes are well-implemented defensive programming. The only minor issue is the incomplete consistency in the commit-msg hook, which doesn't affect functionality but could be improved for completeness. This is a quality release that should be safe to merge and publish.

[carlos-alm]

Both issues from the Greptile review have been addressed:

1. Native dependency version drift (package.json lines 74-79): Fixed in 3f791fb — all @optave/codegraph-* optional deps now pinned to 3.1.2, matching the root package version.

2. SUMMARY pipeline missing || true guard (.husky/commit-msg:16): Already fixed in a7a2bcc — the SUMMARY assignment now has || true for consistency with the IMPACT guard.

@greptileai