Feat: Add advanced SurrealDB graph analysis functions to NAPI bindings

Exposes 6 advanced graph analysis functions from the Rust SDK to TypeScript/JavaScript
via N-API bindings, enabling sophisticated code analysis in Node.js applications.

## New Files

### crates/codegraph-napi/src/graph.rs (NEW - 450+ lines)
Complete NAPI wrapper module with:
- 11 type converter functions (Rust SDK → NAPI types)
- 6 exported async functions with proper error handling
- Feature-gated behind `cloud-surrealdb` feature
- Tokio async runtime integration

### crates/codegraph-napi/GRAPH_FUNCTIONS_GUIDE.md (NEW - 600+ lines)
Comprehensive guide including:
- Overview and use cases
- SurrealDB setup instructions (local + cloud)
- Complete function reference with examples
- Real-world integration patterns (CI/CD, code review, dashboards)
- Troubleshooting guide

### crates/codegraph-napi/example-graph.ts (NEW - 450+ lines)
Runnable TypeScript example demonstrating:
- All 6 graph functions with realistic scenarios
- Environment variable setup
- Error handling patterns
- Practical workflows (architectural analysis, impact assessment)

## Modified Files

### crates/codegraph-napi/src/types.rs
Added 11 #[napi(object)] types:
- NodeLocation, NodeInfo, DependencyNode
- CircularDependency, CallerInfo, CallChainNode
- CouplingMetrics, CouplingMetricsResult
- NodeReference, EdgeTypeCount, HubNode

### crates/codegraph-napi/src/state.rs
- Added GraphFunctions initialization from SURREALDB_CONNECTION env var
- Added `graph_functions: Option<Arc<GraphFunctions>>` field
- Implemented `init_graph_functions()` helper for SurrealDB setup

### crates/codegraph-napi/src/lib.rs
- Added graph module declaration with feature gate
- Exported all 11 graph types
- Exported all 6 graph functions

### crates/codegraph-napi/README.md
- Added "Graph Analysis Functions" section (150+ lines)
- Complete TypeScript usage examples for all 6 functions
- Full TypeScript interface definitions

### crates/codegraph-napi/Cargo.toml
- Updated cloud-surrealdb feature to enable codegraph-graph/surrealdb

### crates/codegraph-napi/package.json
- Added `example:graph` script

## Exported Functions

All 6 functions are async and return Promises:

1. **getTransitiveDependencies**(nodeId, edgeType, depth)
   - Find all downstream dependencies up to specified depth

2. **getReverseDependencies**(nodeId, edgeType, depth)
   - Find all upstream dependents (what depends on this node)

3. **detectCircularDependencies**(edgeType)
   - Identify circular dependency cycles in the graph

4. **traceCallChain**(fromNode, maxDepth)
   - Map function call hierarchies and execution paths

5. **calculateCouplingMetrics**(nodeId)
   - Measure afferent/efferent coupling, instability, stability

6. **getHubNodes**(minDegree)
   - Find highly connected nodes (architectural hubs)

## Environment Setup

```bash
export SURREALDB_CONNECTION=ws://localhost:8000
# Or use SurrealDB Cloud (1GB free): wss://your-instance.surrealdb.cloud
```

## Usage Example

```typescript
import { getHubNodes, calculateCouplingMetrics } from 'codegraph-napi';

// Find architectural hubs
const hubs = await getHubNodes(10);
console.log(`Found ${hubs.length} hub nodes`);

// Analyze coupling for a module
const metrics = await calculateCouplingMetrics('node:module-uuid');
console.log(`Instability: ${metrics.metrics.instability}`);
```

## Build Verification

Code compiles successfully with cloud-surrealdb feature:
```bash
cargo check -p codegraph-napi --no-default-features --features cloud-surrealdb
```

## Documentation

- Complete API reference in README.md
- Comprehensive guide in GRAPH_FUNCTIONS_GUIDE.md
- Working example in example-graph.ts
- TypeScript type definitions auto-generated via napi-rs

This implementation brings the full power of SurrealDB graph analysis to the Node.js ecosystem!

Author: jruokola

crates/codegraph-napi/Cargo.toml

@@ -12,7 +12,7 @@ crate-type = ["cdylib"]
 default = ["local"]
 local = ["codegraph-vector/faiss"]
 cloud-jina = ["codegraph-vector/jina"]
-cloud-surrealdb = ["surrealdb"]
+cloud-surrealdb = ["surrealdb", "codegraph-graph/surrealdb"]
 cloud = ["cloud-jina", "cloud-surrealdb"]
 full = ["local", "cloud"]
 
@@ -33,7 +33,7 @@ tracing = { workspace = true }
 # Local crates
 codegraph-core = { path = "../codegraph-core" }
 codegraph-api = { path = "../codegraph-api" }
-codegraph-graph = { path = "../codegraph-graph" }
+codegraph-graph = { path = "../codegraph-graph", features = [] }
 codegraph-vector = { path = "../codegraph-vector" }
 codegraph-ai = { path = "../codegraph-ai" }