---
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

```json
{
  "generated_at": "<ISO timestamp>",
  "base_commit":  "<git SHA>",
  "node_count":   913,
  "nodes": {
    "classes/Engine/Cache/Subscriber.php": {
      "language":  "php",
      "namespace": "Imagify\\Engine\\Cache",
      "symbols": [
        { "kind": "class", "name": "Subscriber", "extends": [], "implements": ["SubscriberInterface"] }
      ],
      "imports": [
        "Imagify\\Event_Management\\SubscriberInterface",
        "Imagify\\Engine\\Cache\\Purge"
      ]
    }
  },
  "symbol_index": {
    "Imagify\\Engine\\Cache\\Subscriber": "classes/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["Imagify\\Engine\\Cache\\Purge"]
→ "classes/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 "Imagify\\Engine\\Cache\\Purge" ∈ node.imports
→ "classes/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. `Imagify\Engine\Cache`)
- `symbols[*].implements` contains `SubscriberInterface`

### 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["Imagify\\...\\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.

### Distinguish modern vs legacy classes
- Nodes with namespace starting `Imagify\` in `classes/` = modern PSR-4 (`declare(strict_types=1)`). New code goes here.
- Nodes in `inc/classes/` with classmap prefix `Imagify_` = legacy. Do not add new classes here; migrate out instead.
- Strauss-prefixed vendor deps appear under `Imagify\Dependencies\` — do not modify.

---

## Keeping the graph fresh

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

```bash
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. Check `config/providers.php` to confirm the ServiceProvider is registered.
7. Only then open the actual PHP files (now you know exactly which ones to read).