README

vis-graphify

Code knowledge graphs for Vis, built with the Blockether fork of graphify. The fork adds full Clojure support over Blockether/tree-sitter-clojure: namespaces, vars, :require aliases, cross-file calls, protocols, records and Clojure 1.12/1.13 syntax.

When to use

• You want to know who calls a function, across files: use graphify.explain.
• You plan a change and want to see what it can break: use graphify.affected.
• You want to rename a function, method, class or Clojure var everywhere without touching locals, fields, strings or other symbols with the same name: use graphify.rename. See Rename a symbol.
• You want to add a parameter to a function and pass a value at every call: use graphify.add_parameter. See Add a parameter.
• You want to see how two parts of the code connect: use graphify.shortest_path.
• You join an unknown codebase and want its central code first: use graphify.hubs.
• You want to see how commands, queries and events flow between your services, or find calls to commands that no service registers: use graphify.domain. See Domain flows.

The graph comes from tree-sitter syntax trees. A build makes no LLM call and sends no code anywhere.

Install

vis-agent extension install Blockether/vis-graphify --trust

Vis prepares a private environment with graphify and the Clojure grammar. Run /reload in a session.

Use

In a Vis session, ask for the graph work in chat, for example "who calls run-tests in this project?". The agent uses these tools in its Python sandbox:

You can name a node by its id, its label (run()), its bare name (run) or a qualified name (my.ns/run, orders.Order, Ledger.post or crate::util::sum), or by its file and name (src/util.rs::checksum). If a name matches more than one node, the error lists each candidate id with its file and line.

print(result) shows a short summary with file:line locations. Read a field, such as diff, for the details. The graph build writes graphify-out/.gitignore, so git and grep skip the graph files.

Rename a symbol

Ask in chat, for example "rename parse_config to load_config". The agent calls graphify.rename("parse_config()", "load_config", apply=True). When the rename has a conflict, the call writes nothing. The result has these fields:

• diff: the change in each file;
• conflicts: why the rename is unsafe, if it is. Examples are a file that already uses the new name, a method that overrides a base class or implements a trait, or a common method name such as get on receivers of unknown type;
• mentions: other code symbols that spell the old name. They stay unchanged; check them.
• text_mentions: the count of strings, comments and keywords that spell the old name. They stay unchanged.

Without apply=True, the call is a preview and writes nothing. A file that changed after the plan stops the write.

The rename works in every language with a tree-sitter grammar in graphify: Python, JavaScript, TypeScript, Go, Rust, Java, C#, Kotlin, Ruby, PHP, Clojure and more. It follows imports, aliases, re-exports and declared receiver types, and it skips parameters, locals and fields with the same name. For Clojure, it follows :as, :refer, :refer :all and :rename, and changes declare, defmethod, protocol implementations, #'var, resolve, syntax-quote and ->Rec factories. graphify.references() lists the same sites without a change.

Add a parameter

Ask in chat, for example "add a currency string parameter to pricing.Total and pass "EUR"". The agent calls graphify.add_parameter("pricing/pricing.go::Total", "currency string", '"EUR"', apply=True). The call finds the calls with the same exact resolution as graphify.references(). A method or a function in another package with the same name stays unchanged.

• Write the parameter as the language writes it: currency string (Go), currency: str (Python), currency: string (TypeScript) or currency (Clojure).
• The parameter goes last in the definition, and the argument goes last in each call.
• A multi-line call with a trailing comma gets the argument on its own line.

The call writes nothing when a site blocks the change. Examples are a function that is passed as a value, not called, or a Python list that ends with *args, **kwargs or a default. In Python, pass name=value after a default. Then change the blocked sites by hand.

Domain flows

graphify.domain() reads the framework registrations of your Clojure services and connects them. The built-in edd-core plugin reads edd-core commands, queries, events, effects and Malli schemas. The call writes these files to <root>/graphify-out/domain/:

• DOMAIN.md: a summary, findings, Mermaid flowcharts for the system and each service, a sequence diagram for each entry point, and the schemas;
• domain.json: the full model;
• schemas/: one JSON Schema for each Malli schema.

The result lists the findings, errors first. For example, missing-command means that code calls a command that the target service does not register. payload-invalid means that a call sends data that the full :consumes schema of its target rejects. Codes that start with schema- mark a broken Malli schema, such as an unknown type, :min above :max or a regex that cannot compile. DOMAIN.md lists these problems under each schema. graphify.build() also adds the domain elements to the graph, so graphify.explain("domain:command:orders-svc:place-order") shows the handler.

To read another framework, write a domain plugin: a Python file with a plugin object that has a name and an extract(corpus, model) method. The plugin guide describes the contract. Make the plugin available in one of these ways:

• Put the file in <root>/.graphify/plugins/. graphify finds it for that project.
• Pass its path or name in plugins, for example graphify.domain(plugins=["tools/jobs.py"]).
• Add it to src/vis_graphify/domain_plugins/ in this repository. Every Vis user of the extension then gets it.

Development

uv sync
uvx ruff format --check . && uvx ruff check .
uv run --with pytest pytest tests -q

Benchmark

bench/ measures extraction, queries and change tracking on real Clojure projects against clj-kondo. On the Vis sources (235 files), definitions have a recall of 0.999, references a recall of 0.996, and explain() finds 99.8 percent of the callers in a few milliseconds. A full build takes about 4 s, and an update after a one-file change about 5 s.

License

Apache-2.0. graphify is MIT-licensed; see NOTICE.