Skip to content

TASKS.md

Latest commit

 

History

History
602 lines (484 loc) · 24.7 KB

TASKS.md

File metadata and controls

602 lines (484 loc) · 24.7 KB
Raw

Graphize Tasks

LLM-powered tool to turn Go codebases into queryable knowledge graphs.

Feature Parity Reference

Reviewed against safishamsi/graphify:

  • Branch: v3
  • Commit: 699e9960ce7b88076db33a4da3adbd53fb410c7c
  • Version: v0.3.28+5 (2026-04-10)
  • Review Date: 2026-04-11

Architecture Overview

┌─────────────────────────────────────────────────────────────────────────┐
│                         GRAPHIZE PIPELINE                                │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Step 1: Detect        Step 2: Extract           Step 3: Build          │
│  ┌──────────┐          ┌─────────────────┐       ┌──────────────┐       │
│  │ Scan     │          │ Part A: AST     │       │ Merge AST +  │       │
│  │ sources  │─────────▶│ (deterministic) │──┬───▶│ Semantic     │       │
│  │          │          ├─────────────────┤  │    │ results      │       │
│  └──────────┘          │ Part B: LLM     │  │    └──────────────┘       │
│                        │ (optional)      │──┘           │               │
│                        └─────────────────┘              ▼               │
│                                                  ┌──────────────┐       │
│  Step 4: Analyze       Step 5: Export           │ GraphFS      │       │
│  ┌──────────┐          ┌─────────────────┐      │ Store        │       │
│  │ Cluster  │◀─────────│ God nodes       │◀─────└──────────────┘       │
│  │ Detect   │          │ Surprises       │                              │
│  └──────────┘          │ Questions       │                              │
│       │                └─────────────────┘                              │
│       ▼                                                                  │
│  Step 6: Output                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ HTML │ TOON │ JSON │ GRAPH_REPORT.md │ Neo4j │ Obsidian        │    │
│  └─────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘

Feature Comparison: Graphize vs Graphify

Core Features

Feature Graphify Graphize Status
Source Tracking Single directory Multi-repo with commit hashes ✅ Better
Git Currency None Tracks commit/branch per repo ✅ Better
Storage Single graph.json One file per entity (GraphFS) ✅ Better
AST Extraction tree-sitter (20 langs) Go only (go/ast) ✅ Done
Per-file Caching ✅ SHA256 + MD5 ✅ SHA256 ✅ Done
Edge Confidence ✅ ✅ EXTRACTED/INFERRED/AMBIGUOUS ✅ Done
LLM Semantic Extraction ✅ Subagents ✅ Skill + merge workflow ✅ Done
Multi-agent-spec ❌ ✅ agents/specs/ ✅ Better

Analysis Features

Feature Graphify Graphize Status
Community Detection ✅ Leiden/Louvain ✅ Louvain (gonum) ✅ Done
God Nodes Analysis ✅ Full ✅ Full (report cmd) ✅ Done
Surprising Connections ✅ Betweenness centrality ✅ Cross-file, cross-community ✅ Done
Cohesion Scores ✅ ✅ ✅ Done
Isolated Nodes ✅ ✅ ✅ Done
Package Statistics ❌ ✅ ✅ Better
Suggested Questions ✅ ✅ ✅ Done
Hyperedges ✅ 3+ node groups ❌ ⬜ Phase 7
Betweenness Centrality ✅ For bridges ✅ Bridges in report ✅ Done
Corpus Health Check ✅ Word count, verdict ✅ report --health ✅ Done

Export Formats

Feature Graphify Graphize Status
HTML Visualization ✅ vis.js ✅ cytoscape.js ✅ Done
TOON Export ❌ ✅ (with confidence) ✅ Better
JSON Export ✅ NetworkX ✅ Cytoscape format ✅ Done
GRAPH_REPORT.md ✅ ✅ (report cmd) ✅ Done
GraphML Export ✅ ✅ ✅ Done
Obsidian Export ✅ Wiki-style vault ✅ ✅ Done
Neo4j Cypher Export ✅ cypher.txt ✅ ✅ Done
Neo4j Push ✅ Direct bolt connection ❌ ⬜ Phase 5
SVG Export ✅ ❌ ⬜ Phase 5

CLI Features

Feature Graphify Graphize Status
MCP Server ✅ ✅ ✅ Done
Watch Mode ✅ fsnotify ✅ ✅ Done
Git Hooks ✅ post-commit/checkout ✅ ✅ Done
Directed Graphs ✅ --directed flag ✅ ✅ Done
Path Command ✅ path "A" "B" ✅ ✅ Done
Explain Command ✅ explain "Node" ✅ ✅ Done
Token Benchmark ✅ benchmark ✅ ✅ Done
URL Ingestion ✅ add <url> ❌ ⬜ Phase 7

Content Types

Feature Graphify Graphize Status
Go Code ✅ tree-sitter ✅ go/ast ✅ Done
Multi-language ✅ 20 langs ❌ Go only ⬜ Phase 7
Markdown/Text ✅ Claude extraction ✅ extractor ✅ Done
PDF Papers ✅ Citation mining ❌ ⬜ Phase 7
Images ✅ Claude vision ❌ ⬜ Phase 7
Video/Audio ✅ Whisper transcription ❌ ⬜ Phase 7
Office Docs ✅ DOCX/XLSX conversion ❌ ⬜ Phase 7

Platform Integration

Feature Graphify Graphize Status
Claude Code ✅ PreToolUse hook ✅ MCP server ✅ Done
Codex ✅ hooks.json ✅ install codex ✅ Done
Cursor ✅ .cursor/rules ✅ install cursor ✅ Done
Gemini CLI ✅ BeforeTool hook ✅ install gemini ✅ Done
GitHub Copilot ✅ skills/ folder ✅ install copilot ✅ Done
Aider/OpenClaw ✅ AGENTS.md ✅ install aider ✅ Done

Graphize Advantages

  • Multi-repo support: Track multiple repositories with independent git commit tracking
  • GraphFS storage: Git-friendly one-file-per-entity storage
  • TOON format: Token-efficient output for AI agents (98% smaller than JSON)
  • multi-agent-spec: Portable subagent definitions for Claude, Kiro, Codex, Gemini
  • Edge confidence metadata: Full support for EXTRACTED/INFERRED/AMBIGUOUS with scores

Graphify Advantages

  • 20 language support: tree-sitter parsers for many languages
  • Multimodal extraction: Code, docs, papers, images, video, audio, office docs
  • Platform hooks: 10 AI assistant integrations with always-on hooks
  • URL ingestion: Fetch and extract papers, tweets, videos

Phase 1 - MVP ✅ COMPLETE

Core Infrastructure ✅

  • Project structure with pkg/ layout
  • Source tracking types: Source, Manifest, SourceStatus
  • Git commit/branch reading (NewSourceFromPath, CheckStatus)
  • Output formatters: JSON, YAML working
  • Manifest persistence (save/load to .graphize/manifest.json)
  • TOON output: integrate toon-go library when released

CLI Commands ✅

  • graphize init - creates graph database directory structure
  • graphize add <repo> - tracks repo with commit hash (persisted)
  • graphize status - shows all sources with staleness detection
  • graphize analyze - extract graph from sources
  • graphize query - query the graph with filters

Go AST Extraction ✅

  • Parse Go files with go/ast
  • Extract packages, files, functions, methods, types, imports
  • Extract function calls, type references as edges
  • Mark all AST-derived edges as EXTRACTED confidence

Query Command ✅

  • graphize query - show graph summary
  • graphize query <node-id> - show edges for a node
  • BFS/DFS traversal with --depth and --dfs flags
  • Direction filter (--dir out/in/both)
  • Edge type filter (--edge-type)

Export Commands ✅

  • graphize export html - Cytoscape.js visualization
  • graphize export json - Cytoscape JSON format
  • graphize export toon - TOON format (agent-optimized)
  • graphize summary - Markdown summary for AGENTS folder

Phase 2 - LLM Semantic Extraction ✅ COMPLETE

Per-file Caching ✅

  • Create pkg/cache/cache.go
  • SHA256-based file hashing
  • Store extraction results per file hash
  • Cache hit/miss detection
  • Cache invalidation on file change
  • Integrate with pkg/extract/extract.go
  • Add --no-cache flag to analyze command
  • Report cache hit/miss statistics

LLM Extraction Skill

  • Create skills/enhance.md skill file
  • Create agents/specs/semantic-extractor.yaml (multi-agent-spec)
  • Define subagent prompt for semantic extraction
  • Define edge types (inferred_depends, rationale_for, similar_to, etc.)
  • Parse and validate subagent JSON output (pkg/extract/merge.go)
  • Merge with AST extraction results (graphize merge command)
  • Create agents/plugins/ via assistantkit (when available)
  • Chunk files (20-25 per chunk) - extract.ChunkFiles() + graphize enhance --json
  • graphize enhance --prompt - Output prompts for each chunk
  • graphize enhance --json - JSON output for automation
  • skills/semantic-extract.md - Orchestration skill for parallel dispatch

Edge Confidence System ✅

  • Add Confidence field to Edge type (EXTRACTED/INFERRED/AMBIGUOUS) - Already in graphfs
  • Add ConfidenceScore field (0.0-1.0) - Already in graphfs
  • AST extraction sets Confidence: EXTRACTED on all edges
  • TOON export includes confidence for non-EXTRACTED edges
  • HTML export includes confidence data for edge coloring
  • HTML template edge color-coding (in cytoscape-go) - Future enhancement

New CLI Commands

  • graphize enhance - Prepare files for LLM semantic extraction
  • graphize enhance --force - Ignore cache, list all files
  • graphize enhance --chunk-size N - Control chunk size
  • graphize enhance --prompt - Output subagent prompts for each chunk
  • graphize enhance --json - JSON output for automation scripts
  • Show cache hit/miss statistics
  • graphize merge -i <json> - Merge semantic edges from LLM extraction
  • graphize merge --validate - Validate semantic JSON without merging
  • /semantic-extract skill - Orchestrated parallel subagent dispatch

Test Coverage ✅

  • pkg/extract/merge_test.go - 6 test functions, 31 test cases
    • ChunkFiles, ParseSemanticJSON, ValidateSemanticExtraction
    • MergeExtractions, IsValidSemanticEdgeType, BuildSubagentPrompt
  • cmd/graphize/cmd/enhance_test.go - 7 test functions
    • EnhanceOutput JSON serialization, ChunkOutput structure
    • Prompt generation, field validation
  • pkg/cache/cache_test.go - existing cache tests

Workflow Validation ✅

  • End-to-end test on yaml.v2 codebase
  • Discovered 18 semantic edges (similar_to, shared_concern, inferred_depends, implements_pattern)
  • Merged into graph, verified in report output
  • Suggested questions reference INFERRED edges for human review

Clone & Rebuild Workflow ✅

  • graphize rebuild - Analyze + merge semantic edges in one command
  • graphize rebuild --html - Also generate HTML visualization
  • graphize rebuild --report - Also generate analysis report
  • graphize rebuild --semantics <path> - Custom semantic edges path
  • Automatic detection of agents/graph/semantic-edges.json

Phase 3 - Analysis & Reports ✅ COMPLETE

Community Detection ✅

  • Implement simple community detection (pkg/analyze/cluster.go)
  • Group by package (natural code communities)
  • Connected components fallback
  • Calculate cohesion scores
  • Split oversized communities
  • Community labels inference
  • Louvain algorithm via gonum (pkg/analyze/louvain.go)

Graph Analysis ✅

  • God nodes detection (most connected) - pkg/analyze/gods.go
  • Surprising connections (cross-community, cross-file) - pkg/analyze/surprise.go
  • Isolated nodes detection
  • Cross-file edges analysis
  • Package statistics
  • Edge confidence grouping
  • Suggested questions generation (pkg/analyze/questions.go)

Report Generation ✅

  • graphize report command
  • Generate report with:
    • Corpus summary (nodes, edges, types)
    • God nodes listing (most connected)
    • Surprising connections (cross-file, cross-community)
    • Community breakdown with cohesion scores
    • Isolated nodes (potential gaps)
    • Package statistics
    • Edge confidence breakdown
    • INFERRED/AMBIGUOUS edges flagged in Surprising Connections
    • Suggested questions in report (5 question types)

Phase 4 - Agent Integration ✅ COMPLETE

MCP Server ✅

  • graphize serve - Start MCP server (using official Go SDK)
  • Tool: query_graph (BFS/DFS traversal)
  • Tool: get_node (lookup by ID or label)
  • Tool: get_neighbors (in/out/both directions)
  • Tool: get_community (list members)
  • Tool: graph_summary (stats + god nodes + suggested questions)

AGENTS Folder Convention ✅

  • graphize init-agents - Create agents/ folder structure
  • Generate agents/graph/GRAPH_SUMMARY.md (checkable)
  • Generate agents/graph/GRAPH.toon.gz (checkable)
  • Add .gitignore for local-only files

Phase 5 - Export & Automation ✅ COMPLETE

Implementation Order: Quick wins first, then multi-language (Phase 7). See PLAN.md for detailed schedule.

Quick Wins ✅

  • graphize path "A" "B" - Trace exact path between nodes ✅
    • Use graphfs query.FindPath
    • Show intermediate nodes and edge types
  • graphize benchmark - Print token reduction stats ✅
    • Compare raw corpus size vs TOON output
    • Show compression ratio
  • --directed flag for graphize analyze ✅
    • Preserve edge direction in graph (stored in manifest)
    • Affects traversal and analysis

Export Formats ✅

  • GraphML export (for Gephi/yEd) - graphize export graphml
  • Neo4j Cypher export - graphize export cypher ✅
    • Generate CREATE statements for nodes
    • Generate CREATE statements for edges
    • Include all node/edge attributes
  • Neo4j Push - graphize export cypher --push bolt://localhost:7687
    • Direct bolt connection to Neo4j instance
    • Authentication support (user/password)
  • SVG export - graphize export svg
    • Use gonum/plot or similar for layout
    • Static vector graph output
  • Obsidian vault export - graphize export obsidian ✅
    • Generate index.md entry point
    • One article per community with wikilinks
    • One article per god node
    • Cohesion scores and navigation footers

Watch Mode ✅

  • graphize watch - Monitor files, rebuild on change ✅
    • Use fsnotify for file system events
    • Debounce rapid changes (500ms)
    • Incremental rebuild (only changed files)
    • Optional: auto-regenerate HTML/report

Git Hooks ✅

  • graphize hook install - Install git hooks ✅
    • post-commit hook: auto-analyze on commit
    • post-checkout hook: check if graph is stale
  • graphize hook uninstall - Remove hooks ✅
  • graphize hook status - Check hook installation ✅

Phase 6 - Enhanced Analysis ✅ COMPLETE

See docs/plans/v0.2.0-tasks.md for detailed task tracking.

Analysis Improvements

  • Betweenness centrality for bridge detection ✅
  • Composite surprise scoring ✅
    • Weight cross-file > cross-community (2.5x)
    • Weight code-doc edges higher (+1.5 bonus)
  • Corpus health check ✅
    • graphize report --health flag
    • Verdict on whether graph adds value

New Commands

  • graphize explain "NodeName" - Explain a node in context ✅
    • Show node attributes, neighbors, community, centrality
    • --depth and --json flags
  • graphize install <platform> - Platform installer command ✅

Documentation Extraction

  • Markdown/text extraction ✅
    • graphize enhance --include-docs flag
    • graphize enhance --docs-only flag
    • Extract concepts and link to code nodes

Platform Installers

  • graphize install claude - Claude Desktop MCP ✅
  • graphize install codex - Codex hooks.json ✅
  • graphize install cursor - .cursor/rules/graphize.mdc ✅
  • graphize install gemini - Gemini CLI context ✅
  • graphize install copilot - GitHub Copilot skills ✅
  • graphize install aider - AGENTS.md section ✅

Phase 7 - Multimodal & Multi-language ⬜ FUTURE

Multi-language Support

  • Tree-sitter integration via go-tree-sitter
    • Python extraction
    • TypeScript/JavaScript extraction
    • Rust extraction
    • Java extraction
  • Language detection heuristics
  • Unified node ID scheme across languages

Hyperedges

  • Support for 3+ node group relationships
    • "All classes implementing interface X"
    • "All functions in auth flow"
  • Hyperedge visualization in HTML export
  • Hyperedge queries

URL Ingestion

  • graphize add <url> - Fetch and extract external content
    • Papers (PDF): citation mining + concept extraction
    • Web pages: content extraction
    • Videos (YouTube): transcript extraction
  • --author and --contributor tags
  • URL caching by hash

Multimodal Extraction

  • PDF extraction
    • Text extraction via pdftotext or similar
    • LLM concept extraction
    • Citation relationship mining
  • Image extraction
    • Claude vision for diagrams, screenshots, charts
    • Node creation for visual concepts
  • Video/Audio transcription
    • Whisper integration for local transcription
    • God-node-aware prompts for domain vocabulary
    • Transcript caching

Office Documents

  • DOCX extraction
    • Convert to markdown
    • LLM concept extraction
  • XLSX extraction
    • Convert to markdown tables
    • Extract data relationships

Current Stats

Large Codebase (coreforge)

  • 21,369 nodes extracted (AST)
  • 72,351 edges extracted (AST)
  • ~20 seconds extraction time
  • 477 KB TOON export (gzipped)
  • 23 MB HTML visualization

Semantic Extraction Test (yaml.v2)

  • 506 nodes, 1,738 edges total
  • 1,720 EXTRACTED edges (AST)
  • 18 INFERRED edges (LLM semantic)
  • Edge types discovered: similar_to (5), shared_concern (5), inferred_depends (6), implements_pattern (2)

Node Types

packages, files, functions, methods, structs, interfaces, constants, variables

Edge Types

  • AST: calls, contains, imports, method_of, references, extends
  • Semantic: inferred_depends, rationale_for, similar_to, implements_pattern, shared_concern

Recommended Workflow

For Repo Maintainers (Initial Setup)

# 1. Initialize and extract
graphize init
graphize add .
graphize analyze

# 2. Run LLM semantic extraction (expensive, one-time)
/semantic-extract

# 3. Check in the portable artifacts
git add .graphize/manifest.json
git add agents/graph/semantic-edges.json
git commit -m "feat: add graphize knowledge graph"

For Repo Consumers (After Clone)

# Single command rebuilds everything
graphize rebuild --html --report

# View the results
open graph.html

What Gets Checked In

Path Purpose Size
.graphize/manifest.json Source tracking <1 KB
agents/graph/semantic-edges.json LLM-extracted edges ~10 KB
agents/specs/ Subagent definitions ~5 KB

What Gets Generated Locally

Path Purpose Regenerate With
.graphize/nodes/ Graph database graphize rebuild
.graphize/edges/ Graph edges graphize rebuild
.graphize/cache/ Extraction cache graphize rebuild
graph.html Visualization graphize export html
GRAPH_REPORT.md Analysis graphize report

Code Quality & Refactoring 🔧 IN PROGRESS

Move business logic from cmd/ to library packages for better unit testability.

DRY Fixes (Quick Wins)

  • Extract formatBytes() to pkg/metrics/formatter.go
    • Duplicated in: benchmark.go, export_cypher.go, export_graphml.go
    • Added: FormatBytes(), FormatNumber() with tests
  • Extract edge grouping helpers to pkg/analyze/group.go
    • groupEdgesByType() duplicated in: export_obsidian.go, report.go
    • Added: GroupEdgesByType(), CountEdgesByType(), GroupEdgesByConfidence(), CountEdgesByConfidence() with tests
  • Extract directory walking to pkg/metrics/walker.go
    • File collection duplicated in: benchmark.go, enhance.go
    • Added: WalkSourceFiles(), WalkSourceFilesWithContent(), WalkOptions with tests

High Priority Extractions

  • pkg/exporters/cypher/ - Cypher generation from export_cypher.go
    • Generator type with Generate(), NodeToCreate(), EdgeToCreate()
    • EscapeString(), EscapeKey(), ToNeoLabel(), ToNeoRelType()
    • Comprehensive unit tests (8 test functions)
  • pkg/metrics/tokens.go - Token estimation from benchmark.go
    • EstimateTokens(), EstimateTokensInFile()
    • Word counting + punctuation heuristics for LLM token estimation
  • pkg/exporters/obsidian/ - Vault generation from export_obsidian.go
    • Generator type with Generate(), VaultContent result type
    • GenerateIndex(), GenerateCommunity(), GenerateNode()
    • SanitizeName() for safe filenames
    • Comprehensive unit tests (6 test functions)
  • pkg/query/ - Query formatting from query.go ✅
    • summary.go - ComputeSummary, SummaryOptions, GodNode detection
    • format.go - FormatTraversal, FormatPath for output formatting
    • filter.go - EdgeFilter, FilterEdges, FindPartialMatches
    • Unit tests for all functions

Medium Priority Extractions

  • pkg/analyze/report.go - Report orchestration from report.go ✅
    • Report struct with all analysis sections
    • GenerateReport() function
    • FormatMarkdown() method
    • Unit tests for report generation
  • pkg/exporters/graphml/ - GraphML generation from export_graphml.go ✅
    • Generator type with Generate(), WriteTo()
    • Result type with NodeCount, EdgeCount, SkippedEdges
    • Configurable: Directed, GraphID, Description
    • Unit tests (9 test functions)

Provider Integrations 🔶 IN PROGRESS

system-spec Provider ✅

  • Register system-spec provider in graphize
    • Import github.com/plexusone/system-spec/graphize package
    • Add to provider registry in pkg/extract/systemspec/extractor.go
    • Auto-detect system-spec JSON files (has name + services fields)
    • Extract infrastructure topology nodes alongside code graph
    • Link service nodes to repo paths via links_to edges

Service-Based Filtering

  • Add --service flag to query command
    • Map service name → repo URL via links_to edges
    • Resolve repo URL → local path via manifest
    • Filter query results to nodes from that repo
    • Example: graphize query --service payments returns all code from payments repo
  • Add --service flag to export commands
    • Export subgraph for a specific service
    • Useful for service-specific documentation

Legend

  • Implemented
  • Not started
  • ✅ Complete / Better than graphify
  • 🎯 HIGH priority
  • 🔶 Medium priority (Phase 5-6)
  • ⬜ Low priority / Future (Phase 7)