knowledge-graph

name	knowledge-graph
description	Read and refresh the project's dependency graph to trace classes, services, and modules.

Knowledge Graph

A pre-built dependency graph lives at .claude/graph/dependency-graph.json. The builder is node bin/build-knowledge-graph.js (incremental by default, --full to force rebuild).

This skill has two responsibilities:

1. Refresh the graph at session start if it is stale (base_commit ≠ git rev-parse HEAD).
2. Read the graph to answer dependency, namespace, and structure questions instantly.

Read it before running grep/glob searches for class relationships, namespace exploration, or dependency tracing. It eliminates redundant file scans and speeds up the first useful response in any session.

---

Graph shape

{
  "generated_at": "<ISO timestamp>",
  "base_commit":  "<git SHA>",
  "node_count":   913,
  "nodes": {
    "src/Engine/Cache/Subscriber.php": {
      "language":  "php",
      "namespace": "Plugin\\Engine\\Cache",
      "symbols": [
        { "kind": "class", "name": "Subscriber", "extends": [], "implements": ["Subscriber_Interface"] }
      ],
      "imports": [
        "Plugin\\Event_Management\\Subscriber_Interface",
        "Plugin\\Engine\\Cache\\Purge"
      ]
    }
  },
  "symbol_index": {
    "Plugin\\Engine\\Cache\\Subscriber": "src/Engine/Cache/Subscriber.php"
  }
}

• nodes — keyed by relative file path. Each node has the language (php or js), declared symbols (PHP only), and all import/use statements.
• symbol_index — maps every fully-qualified PHP class / interface / trait / enum to its file path. Use this for instant "where is this class?" lookups.

---

Query patterns

Find a class file (zero grep)

symbol_index["Plugin\\Engine\\Cache\\Purge"]
→ "src/Engine/Cache/Purge.php"

Find the ServiceProvider that wires a class

The ServiceProvider that registers a class imports it. Search for files whose imports contain the target FQN:

filter nodes where "Plugin\\Engine\\Cache\\Purge" ∈ node.imports
→ "src/Engine/Cache/ServiceProvider.php"

Then read that ServiceProvider to see how the class is registered in register().

Find all Subscribers in a module

Filter nodes where:

• namespace starts with the module prefix (e.g. Plugin\Engine\Cache)
• symbols[*].implements contains Subscriber_Interface

Find all ServiceProviders in the codebase

Filter nodes where symbols[*].extends contains AbstractServiceProvider.

Trace a class's full dependency chain

1. Start at symbol_index["Plugin\\...\\ClassName"] → get file path
2. Read nodes[file].imports → these are its direct dependencies
3. For each dependency, repeat → you get the full constructor injection tree without reading any PHP

Verify no unexpected cross-module dependencies

Check nodes[file].imports for any FQN that shouldn't be there. For example, a Frontend Subscriber importing an Admin class is a red flag.

---

Keeping the graph fresh

The graph records the git commit it was built from (base_commit). If that SHA differs from HEAD, run:

node bin/build-knowledge-graph.js

The script is incremental — it only re-parses files changed since base_commit. Use --full to force a complete rebuild.

When to refresh:

• At the start of every issue workflow session.
• After merging a branch with structural changes (new classes, namespace moves).
• Before an architecture review session.

---

Supported languages

Language	What is extracted
PHP	namespace, class/interface/trait/enum declarations (with extends/implements), use imports (including grouped \{A, B} forms)
TypeScript / JavaScript	import (static + dynamic) and require() sources

---

Practical workflow (issue implementation)

Before writing a single line of code for an issue:

1. Check base_commit vs HEAD — refresh if stale.
2. Use symbol_index to locate all classes involved in the fix.
3. For each class, read nodes[file].imports — know the dependency chain before touching the constructor.
4. Find the ServiceProvider via the import search above — know where to add/modify the binding.
5. List all Subscribers in the module — know which ones may need new hook entries.
6. Only then open the actual PHP files (now you know exactly which ones to read).