| 1 |
--- |
| 2 |
name: knowledge-graph |
| 3 |
description: Use this skill to understand repository structure, trace class dependencies, find a symbol's file, or explore module relationships — without re-scanning the codebase from scratch. |
| 4 |
--- |
| 5 |
|
| 6 |
# Knowledge Graph |
| 7 |
|
| 8 |
A pre-built dependency graph lives at `.aiassistant/graph/dependency-graph.json`. |
| 9 |
|
| 10 |
**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. |
| 11 |
|
| 12 |
--- |
| 13 |
|
| 14 |
## Graph shape |
| 15 |
|
| 16 |
```json |
| 17 |
{ |
| 18 |
"generated_at": "<ISO timestamp>", |
| 19 |
"base_commit": "<git SHA>", |
| 20 |
"node_count": 350, |
| 21 |
"nodes": { |
| 22 |
"classes/Optimization/Process/AbstractProcess.php": { |
| 23 |
"language": "php", |
| 24 |
"namespace": "Imagify\\Optimization\\Process", |
| 25 |
"symbols": [ |
| 26 |
{ "kind": "class", "name": "AbstractProcess", "extends": [], "implements": ["ProcessInterface"] } |
| 27 |
], |
| 28 |
"imports": [ |
| 29 |
"Imagify\\Optimization\\Data\\DataInterface", |
| 30 |
"Imagify\\Media\\MediaInterface" |
| 31 |
] |
| 32 |
} |
| 33 |
}, |
| 34 |
"symbol_index": { |
| 35 |
"Imagify\\Optimization\\Process\\AbstractProcess": "classes/Optimization/Process/AbstractProcess.php" |
| 36 |
} |
| 37 |
} |
| 38 |
``` |
| 39 |
|
| 40 |
- **`nodes`** — keyed by relative file path. Each node has the language (`php` or `js`), declared symbols (PHP only), and all import/use statements. |
| 41 |
- **`symbol_index`** — maps every fully-qualified PHP class / interface / trait / enum to its file path. Use this for instant "where is this class?" lookups. |
| 42 |
|
| 43 |
--- |
| 44 |
|
| 45 |
## How to use it |
| 46 |
|
| 47 |
### Find a class file |
| 48 |
``` |
| 49 |
symbol_index["Imagify\\Optimization\\Process\\AbstractProcess"] |
| 50 |
→ "classes/Optimization/Process/AbstractProcess.php" |
| 51 |
``` |
| 52 |
|
| 53 |
### List all classes in a namespace |
| 54 |
Filter `nodes` where `node.namespace` starts with `Imagify\Media`. |
| 55 |
|
| 56 |
### Trace what a file depends on |
| 57 |
Read `nodes["classes/Media/WP.php"].imports`. |
| 58 |
|
| 59 |
### Find all files that import a given class |
| 60 |
Search `nodes[*].imports` for the target FQN. |
| 61 |
|
| 62 |
--- |
| 63 |
|
| 64 |
## Keeping the graph fresh |
| 65 |
|
| 66 |
The graph records the git commit it was built from (`base_commit`). If that SHA differs from `HEAD`, run: |
| 67 |
|
| 68 |
```bash |
| 69 |
node bin/build-knowledge-graph.js |
| 70 |
``` |
| 71 |
|
| 72 |
The script is incremental — it only re-parses files changed since `base_commit`. Use `--full` to force a complete rebuild. |
| 73 |
|
| 74 |
**When to refresh:** |
| 75 |
- After merging a branch with structural changes (new classes, namespace moves). |
| 76 |
- Before a grooming or architecture review session. |
| 77 |
- Automatically in CI (optional — add as a pre-commit hook or workflow step). |
| 78 |
|
| 79 |
--- |
| 80 |
|
| 81 |
## Supported languages |
| 82 |
|
| 83 |
| Language | What is extracted | |
| 84 |
|---|---| |
| 85 |
| PHP | `namespace`, `class`/`interface`/`trait`/`enum` declarations (with `extends`/`implements`), `use` imports (including grouped `\{A, B}` forms) | |
| 86 |
| TypeScript / JavaScript | `import` (static + dynamic) and `require()` sources | |
| 87 |
|
