Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

feat(engine): closed relation vocabulary for synthesized links

Shrish Dwivedidc0a118d865b
diff --git a/README.md b/README.md
index a8fad42e..11b1c42d 100644
--- a/README.md
+++ b/README.md
@@ -135,8 +135,6 @@ See [`.env.example`](.env.example) for the full list of settings (model names, b
## CLI
-Two commands. That is the whole surface.
-
```bash
graft init [dir] # build .context/ from the code at [dir] (default: .)
graft init --extensions .ts .py # only include these code extensions
@@ -145,10 +143,42 @@ graft init --local # force local Ollama even if OPENROUTER_API
graft check [dir] # fail (exit 1) if .context/ has drifted from the code
graft check --json # print the drift report as JSON
+graft viz [dir] # see the graph: serves an interactive viewer on localhost
+graft viz --port 5000 --no-open # pick a port; don't auto-open the browser
+
# global
graft --dir <path> # use a context dir other than <repo>/.context
```
+## Visualize it (`graft viz`)
+
+`graft viz` opens a local, interactive view of both graphs — no install, no dev
+server; the viewer ships prebuilt inside the package.
+
+- **Context** tab — the architecture graph from `.context/*.md`. Nodes colored by
+ type, sized by connectedness.
+- **Code** tab — the per-symbol graph from `graph.json` (run `graft graph` first).
+- **Outline** tab — the file → class → method hierarchy as a collapsible tree.
+
+Edges speak the code's language. Every link is one of a closed set of verbs, each
+answering a question someone building or reviewing code actually asks:
+
+| Verb | The question it answers |
+|---|---|
+| `part_of` / `contains` | where does this live? |
+| `uses` / `calls` / `imports` / `depends_on` | what breaks if I change this? |
+| `produces` | where does this output come from? |
+| `configures` | what changes its behavior without a code change? |
+| `validates` | what checks or judges this? (tests, drift checks, scoring) |
+| `extends` / `implements` | what contract must this honor? |
+
+Select a node and its edges take on direction: **amber = what it depends on,
+teal = what depends on it**, with the verb written on each highlighted edge.
+Chips above the canvas filter by verb; tree-sitter-extracted edges draw solid
+while LLM-inferred ones draw dashed. The viewer live-reloads when `.context/`
+changes on disk. Older graphs with vague verbs (`influences`, `supports`) are
+normalized on load — no regeneration needed.
+
---
## Benchmark
@@ -178,7 +208,7 @@ See [`bench/README.md`](bench/README.md) for the method and how to add your own
## Development
```bash
-git clone https://github.com/nanonets/graft.git && cd graft
+git clone https://github.com/NanoNets/context-graph-engine.git && cd context-graph-engine
npm install
npm run build
npm test
@@ -186,8 +216,6 @@ npm test
npm run cli -- init . # run the CLI from source
```
-<!-- placeholder: confirm repo URL once published -->
-
---
## License
diff --git a/src/ai/synthesize.ts b/src/ai/synthesize.ts
index 75d7f736..d6e4287a 100644
--- a/src/ai/synthesize.ts
+++ b/src/ai/synthesize.ts
@@ -46,7 +46,8 @@ Produce a CURATED set of nodes of mixed granularity:
Rules:
- Strongly prefer FEWER, larger, meaningful nodes. For a repo of N files, aim for well under N nodes. Do NOT emit one node per file, and never a node per incidental identifier (a local interface, helper, or third-party symbol).
- Merge duplicates and surface-form variants into one node.
-- For each node give: a canonical human-readable name; a type ("system" | "file" | "concept"); a 1-3 sentence summary of its ROLE in the system; "sources" = the exact file paths (from the input) it is grounded in (a system lists all its files; a concept lists the files that motivate it); and "links" to other nodes you define, each with a snake_case relation (depends_on, part_of, uses, implements, produces) and a short description.
+- For each node give: a canonical human-readable name; a type ("system" | "file" | "concept"); a 1-3 sentence summary of its ROLE in the system; "sources" = the exact file paths (from the input) it is grounded in (a system lists all its files; a concept lists the files that motivate it); and "links" to other nodes you define, each with a relation and a short description of what concretely happens in the code.
+- The relation MUST be one of exactly these verbs (each answers a question a code reviewer asks): "part_of" (where does this live?), "uses" (what breaks if the target changes?), "depends_on" (same, for non-call dependencies), "produces" (where does this output come from?), "configures" (what changes its behavior without a code change?), "validates" (what checks or judges this? tests, drift checks, scoring), "implements" (what contract must this honor?). Never invent vague relations like "influences", "supports", or "relates_to" — if none of the verbs fit, drop the link.
- Only link to nodes you actually define in this response.
Respond only via the record_graph tool / JSON schema.`;
@@ -68,7 +69,10 @@ const NODES_SCHEMA = {
type: "object",
properties: {
to: { type: "string" },
- relation: { type: "string" },
+ relation: {
+ type: "string",
+ enum: ["part_of", "uses", "depends_on", "produces", "configures", "validates", "implements"],
+ },
description: { type: "string" },
},
required: ["to", "relation"],