building-java-knowledge-graph

Prerequisites

Step 1 — Verify JVM project:

find "$PROJECT_ROOT" -maxdepth 5 -type f \( -name "*.java" -o -name "*.kt" -o -name "*.scala" -o -name "*.groovy" \) | head -1

If no JVM files found: skip this skill. Set knowledge_graph_dir to null in setup_artifacts. Non-fatal — downstream agents fall back to direct source analysis.

Step 2 — Verify Python:

python3 --version 2>/dev/null || python --version 2>/dev/null

If unavailable: skip this skill with same fallback as above.

Quick Start

# First-time setup (~1 minute)
pip3 install --user 'tree-sitter<0.21'
python3 scripts/install_grammars.py

# Optional: SVG generation
brew install graphviz  # macOS

# Analyze project
python3 scripts/build_knowledge_graph.py /path/to/project output-dir

⚠️ DESTRUCTIVE OUTPUT: The script wipes ALL files in output-dir before writing. NEVER point it at a shared directory like {{BASE_PATH}}/ or {{BASE_PATH}}/artifacts/. Use a dedicated subdirectory:

# ✅ SAFE — dedicated subdirectory
python3 scripts/build_knowledge_graph.py /path/to/project {{BASE_PATH}}/artifacts/kg_output

# ❌ DANGER — will delete constitution.md, board.md, other artifacts!
python3 scripts/build_knowledge_graph.py /path/to/project {{BASE_PATH}}

After the script finishes, copy knowledge-graph.json to {{BASE_PATH}}/ for other agents to consume.

What It Detects

• Build systems: Maven (pom.xml), Gradle (build.gradle*), Ant (build.xml), Ivy (ivy.xml)
• Languages: Java, Kotlin, Scala, Groovy via tree-sitter AST
• Structure: Modules, packages, classes, interfaces, enums, annotations
• Relationships: Inheritance, implementations, module dependencies
• Patterns: Architecture layers (controller/service/repository/model/config/util)
• Config: application*.properties, application*.yaml/yml
• Gradle subprojects: settings.gradle parsing

Output

All outputs are written under the provided artifact path (pass as 2nd argument to the script).

knowledge-graph.json           ← complete graph (nodes + edges)
module-dependencies.{dot,svg}  ← module dependency diagram
module-{name}.{dot,svg}        ← per-module class diagrams
project-{name}.{dot,svg}       ← complete project diagram

Resources

• references/schema.md — node/edge types, ID patterns, fields, visualization colors
• references/querying.md — jq and Python query examples
• scripts/build_knowledge_graph.py — main analyzer
• scripts/install_grammars.py — grammar installer