Fix: unify AST and semantic graphs with entity resolution and worked example

[karthick1005]

Graph Unification: AST + Semantic Alignment with Worked Example

Status: Ready for review
Target: safishamsi/graphify
Fork: karthick1005/graphify

---

Summary

This contribution fixes a structural issue where AST and semantic extraction produced largely disconnected subgraphs and relied on brittle exact ID matching.

It introduces canonical identity, entity resolution, and entity-level semantic ↔ code linking, along with a worked example to validate the changes on a real-world backend system.

---

Problem

Currently:

• AST and semantic extraction run independently
• Nodes are merged only on exact ID equality
• Semantic nodes often fail to align with AST nodes

Result:

• Separate code graph and semantic graph
• Minimal code ↔ concept connections
• Semantic layer behaves as a detached subgraph

---

Solution

1. Canonical Identity

• Added normalization for node IDs
• Prevents duplication (e.g., SentenceTransformer vs sentence transformer)

2. Entity Resolution

• Implemented post-build merging using:

  • string similarity
  • token overlap

3. Fine-Grained Code Extraction

• Extract functions, classes, and methods
• Enables entity-level alignment

4. Semantic ↔ Code Linking

• Added:

  • link_code_to_concepts()
  • link_semantic_to_code()
  • link_concepts()

• Establishes connections between:

  • functions/classes ↔ concepts

5. Alignment Pipeline

• Introduced structured flow:

  canonicalize → resolve_entities → semantic linking → align_nodes
  

---

Worked Example

Added:

worked/leetcode-backend/

Includes:

• graph.json — generated graph
• README.md — corpus + usage
• review.md — evaluation of graph quality

This example demonstrates:

• Distributed system graph construction
• Fine-grained entity extraction
• Semantic ↔ code alignment
• Improved graph connectivity

---

Result

• Unified graph instead of parallel subgraphs
• Code ↔ concept relationships established
• Reduced reliance on exact ID matching
• Semantic layer now enriches the AST graph

---

Files Changed

• graphify/build.py — canonical ID + merge logic
• graphify/align.py — entity resolution + linking
• graphify/extract.py — fine-grained extraction
• worked/leetcode-backend/* — validation example

---

Backwards Compatibility

• No breaking changes
• Existing pipelines continue to work
• Improvements are additive

---

Motivation

The issue was observed while analyzing generated graphs, where semantic and AST layers remained disconnected.

This change ensures proper integration and improves the usefulness of the generated knowledge graph.

---

Closes

Fixes #198