How Wiki Generation from Community Structure Works in code-review-graph

The wiki generation system converts detected code communities into a navigable Markdown documentation set using the Leiden clustering algorithm, with each community receiving its own page containing member details, execution flows, and cross-community dependencies.

The code-review-graph project analyzes repository structure through knowledge graphs and automatically produces human-readable documentation. Its wiki generation feature transforms abstract community clusters into concrete Markdown pages that developers can browse and search. This process bridges the gap between automated code analysis and practical documentation maintenance.

The Four-Stage Wiki Generation Pipeline

The system processes community data through four distinct phases to produce static Markdown files.

Step 1: Detecting Communities with Leiden Clustering

Community detection begins in [code_review_graph/communities.py](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/communities.py) where get_communities() executes the Leiden clustering algorithm against the SQLite-backed graph. Each returned community dictionary contains essential metadata including name, size, members, cohesion, and optional fields like description and dominant_language. The algorithm identifies tightly coupled code elements that form logical architectural boundaries.

Step 2: Building Community Pages

For every detected community, the private helper _generate_community_page() in [code_review_graph/wiki.py](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/wiki.py#L32-L71) constructs a comprehensive Markdown document. The generated page includes:

• A header with the community name
• An "Overview" section displaying size, cohesion metrics, and dominant language
• A "Members" table listing up to 50 top members with their kind, file path, and line ranges
• "Execution Flows" retrieved via flows.get_flows() and store.get_flow_qualified_names showing critical paths traversing the community
• "Dependencies" aggregating outgoing and incoming cross-community edges using Counter

Step 3: Writing Files and Collision Handling

The generate_wiki() function orchestrates file output in [code_review_graph/wiki.py](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/wiki.py#L174-L78). It first creates the target directory, then iterates over all communities to write individual pages. Each filename derives from _slugify(), which converts community names into ASCII-only, hyphen-separated strings truncated to 80 characters.

A slug collision guard (addressing the bug fixed in PR #222) automatically renames duplicate slugs by appending incrementing numbers, producing filenames like data-processing-2.md. Finally, the system generates an index.md containing links to all communities with their respective sizes and returns a dictionary summarizing generated, updated, and unchanged pages.

Step 4: Retrieving Generated Pages

The get_wiki_page() function provides safe, programmatic access to generated documentation. Located in [code_review_graph/wiki.py](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/wiki.py#L80-L106), it accepts a directory path and community name, slugifies the input, and reads the matching Markdown file. The implementation includes path-traversal protection and supports fallback matching strategies, including exact filename matches and fuzzy containment searches.

Practical Usage and Integration

Python API Integration

Developers can trigger wiki generation programmatically using the GraphStore and wiki utilities:

from code_review_graph.main import GraphStore
from code_review_graph.wiki import generate_wiki, get_wiki_page

# Initialize or open existing graph store

store = GraphStore.open("my_graph.sqlite")

# Generate wiki pages to local directory

stats = generate_wiki(store, "./my_wiki")
print(stats)

# Output: {'pages_generated': 12, 'pages_updated': 0, 'pages_unchanged': 0}

# Retrieve specific community documentation

md_content = get_wiki_page("./my_wiki", "Data Processing")
print(md_content[:200])

Command-Line Interface

The same pipeline runs via the CLI without writing code:

# Generate wiki in default .code-review-graph/wiki directory

code-review-graph wiki

# Force regeneration regardless of existing files

code-review-graph wiki --force

Summary

• Community Detection: Uses Leiden algorithm via get_communities() to partition the codebase into logical groups stored as dictionaries with metadata.
• Content Generation: _generate_community_page() assembles Markdown with overview statistics, member tables, execution flows, and dependency graphs pulled from GraphStore.
• File Management: generate_wiki() handles directory creation, slug generation with collision detection (PR #222 fix), and index page generation.
• Safe Retrieval: get_wiki_page() provides path-traversal-safe access with slug-based and fuzzy matching capabilities.
• Async Architecture: The entire pipeline is coroutine-based and integrates with the CLI as an asynchronous operation requiring no external services unless the optional [wiki] extra is installed.

Frequently Asked Questions

What algorithm does code-review-graph use for community detection?

The system implements the Leiden clustering algorithm through code_review_graph.communities.get_communities(). This algorithm optimizes modularity to find densely connected subgraphs that represent logical architectural boundaries in the codebase, with fallback support for file-based grouping when graph data is sparse.

How does the system handle communities with identical names?

The _slugify() function converts names to ASCII-only, hyphen-separated strings, while generate_wiki() implements a collision guard that appends incrementing numbers to duplicate slugs (e.g., auth-service.md and auth-service-2.md). This resolves potential filename conflicts automatically, as implemented in the fix for PR #222.

Can I customize the content of generated wiki pages?

Currently, page structure is determined by _generate_community_page() in wiki.py, which pulls data from GraphStore and flows modules. While the core layout—containing overview sections, member tables, and execution flows—is standardized, the optional [wiki] extra package enables LLM-generated prose summaries for additional narrative content.

Is the wiki generation process safe for automated CI/CD pipelines?

Yes. The generate_wiki() function returns deterministic statistics and handles filesystem operations safely, while get_wiki_page() includes path-traversal protection against malicious inputs. The async-ready design allows non-blocking execution in automated environments, and the system requires no external services unless specifically configured for LLM-enhanced summaries.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}