Code graph and memory for your coding agents, in one Rust program. For Claude Code, Codex, Cursor and any MCP client.
Rust agent-memoryai-agentsclaude-codecode-analysiscode-graphcode-intelligencecode-searchcodexcoding-agentscontext-engineeringcursordeveloper-toolsgraphragknowledge-graphlocal-firstmcpmcp-servermodel-context-protocolrusttree-sitter
// Adapted from Graphify 0.9.95 (92741d16), Apache-2.0; see NOTICE.md.
// Upstream: graphify/exporters/html.py
//! Interactive graph view. Browser HTML/JS/CSS remains in its native format;
//! graph assembly, aggregation, annotation and output are implemented in Rust.
use super::{base::COMMUNITY_COLORS, common::*};
use crate::{
Result, analyze, build::Diagnostics, cluster::Communities, fsutil, graph::Graph, path_syntax,
paths, reflect, security,
};
use serde_json::{Value, json};
use std::{
collections::{BTreeMap, BTreeSet},
io::Write as _,
path::Path,
};
pub const MAX_NODES_FOR_VIZ: i64 = 5000;
pub const HTML_STALE_MARKER: &str = ".graph.html.stale";
pub fn viz_node_limit() -> i64 {
bounded_integer(&viz_node_limit_value())
}
fn bounded_integer(v: &Value) -> i64 {
v.as_i64().unwrap_or_else(|| {
if v.to_string().starts_with('-') {
i64::MIN
} else {
i64::MAX
}
})
}
fn viz_node_limit_value() -> Value {
let Some(raw) = std::env::var("GRAPHICLE_VIZ_NODE_LIMIT").ok() else {
return json!(MAX_NODES_FOR_VIZ);
};
let raw = raw.trim_matches(crate::dedup_strings::whitespace);
let (negative, body) = if let Some(s) = raw.strip_prefix('-') {
(true, s)
} else {
(false, raw.strip_prefix('+').unwrap_or(raw))
};
let mut ascii = String::new();
let mut digit = false;
for c in body.chars() {
if c == '_' && digit {
ascii.push(c);
digit = false;
continue;
}
let cp = c as u32;
let Some((start, _)) = crate::decimal_data::DECIMAL
.iter()
.find(|(a, b)| *a <= cp && cp <= *b)
else {
return json!(MAX_NODES_FOR_VIZ);
};
ascii.push(char::from(b'0' + ((cp - start) % 10) as u8));
digit = true;
}
if !digit {
return json!(MAX_NODES_FOR_VIZ);
}
let digits = ascii.replace('_', "");
let digits = digits.trim_start_matches('0');
let n = if digits.is_empty() {
"0".into()
} else if negative {
format!("-{digits}")
} else {
digits.to_owned()
};
serde_json::from_str(&n).unwrap_or(json!(MAX_NODES_FOR_VIZ))
}
pub fn html_styles() -> &'static str {
include_str!("../assets/export_html/styles.html")
}
pub fn hyperedge_script(json: &str) -> String {
include_str!("../assets/export_html/hyperedges.html.template").replace("{{HYPEREDGES}}", json)
}
const SCRIPT_TEMPLATE: &str = include_str!("../assets/export_html/script.html.template");
const SCRIPT_KEYS: [&str; 3] = ["{{NODES}}", "{{EDGES}}", "{{LEGEND}}"];
const DOCUMENT_TEMPLATE: &str = include_str!("../assets/export_html/document.html.template");
const DOCUMENT_KEYS: [&str; 5] = [
"{{TITLE}}",
"{{STATS}}",
"{{STYLES}}",
"{{SCRIPT}}",
"{{HYPEREDGE_SCRIPT}}",
];
pub fn html_script(nodes: &str, edges: &str, legend: &str) -> String {
// Single pass keeps placeholder-looking source strings literal.
render(
SCRIPT_TEMPLATE,
&[
(SCRIPT_KEYS[0], nodes),
(SCRIPT_KEYS[1], edges),
(SCRIPT_KEYS[2], legend),
],
)
}
/// [`render`] written to `out`: `write(out, i)` writes the value of
/// `keys[i]` wherever [`render`] would substitute it, so a value is never
/// held as a string of its own.
fn render_to<W: std::io::Write>(
out: &mut W,
template: &str,
keys: &[&str],
write: &mut dyn FnMut(&mut W, usize) -> std::io::Result<()>,
) -> std::io::Result<()> {
let mut rest = template;
loop {
let next = keys
.iter()
.enumerate()
.filter_map(|(i, key)| rest.find(key).map(|at| (at, i)))
.min_by_key(|(at, _)| *at);
let Some((at, i)) = next else {
out.write_all(rest.as_bytes())?;
return Ok(());
};
out.write_all(&rest.as_bytes()[..at])?;
write(out, i)?;
rest = &rest[at + keys[i].len()..];
}
}
/// [`js_safe`] of `value`, written to `out`: the JSON is escaped as it is
/// written instead of being built and copied as a string.
fn write_js_safe<W: std::io::Write>(out: &mut W, value: &Value) -> std::io::Result<()> {
crate::python_json::write(&mut ScriptSafe(out), value, None, true)
}
/// A writer that escapes every `<` as `\u003c` ([`js_safe`]): the JSON it
/// receives is ASCII (`ensure_ascii`), so escaping bytes escapes characters.
struct ScriptSafe<W>(W);
impl<W: std::io::Write> std::io::Write for ScriptSafe<W> {
fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
let mut rest = buf;
while let Some(at) = rest.iter().position(|b| *b == b'<') {
self.0.write_all(&rest[..at])?;
self.0.write_all(b"\\u003c")?;
rest = &rest[at + 1..];
}
self.0.write_all(rest)?;
Ok(buf.len())
}
fn flush(&mut self) -> std::io::Result<()> {
self.0.flush()
}
}
fn render(template: &str, values: &[(&str, &str)]) -> String {
let mut out = String::new();
let mut rest = template;
loop {
let next = values
.iter()
.filter_map(|(key, v)| rest.find(key).map(|at| (at, *key, *v)))
.min_by_key(|(at, _, _)| *at);
let Some((at, key, value)) = next else {
out.push_str(rest);
break;
};
out.push_str(&rest[..at]);
out.push_str(value);
rest = &rest[at + key.len()..];
}
out
}
pub fn html_document_title(output: &str) -> String {
let mut raw = output.replace('\\', "/");
if raw.as_bytes().get(1) == Some(&b':')
&& raw.as_bytes().get(2) == Some(&b'/')
&& raw.as_bytes()[0].is_ascii_alphabetic()
{
raw = raw[2..].into()
}
let parts = path_syntax::posix_parts(&raw);
// Upstream's prefix test ("graphify-out") cannot match its configuration
// folder; the configuration folder's name starts with the output folder's
// here, so that one name is excluded.
let output_folder = |part: &str| {
part == *paths::OUT_DIR_NAME
|| (part.starts_with(paths::DEFAULT_OUT_DIR) && part != paths::CONFIG_DIR)
};
for (i, part) in parts.iter().enumerate() {
if output_folder(part.as_str()) {
return parts[i..].join("/");
}
}
if let (Ok(target), Ok(cwd)) = (
fsutil::resolve_missing(Path::new(&raw)),
std::env::current_dir().and_then(|p| fsutil::resolve_missing(&p)),
) && let Ok(rel) = target.strip_prefix(cwd)
{
let s = rel.to_string_lossy().replace('\\', "/");
if !s.is_empty() && s != "." {
return s;
}
}
let name = path_syntax::posix_name(&parts);
if name.is_empty() {
"graph.html".into()
} else {
name.into()
}
}
#[derive(Default)]
pub struct HtmlOptions {
pub community_labels: BTreeMap<i64, Value>,
pub member_counts: BTreeMap<i64, f64>,
pub node_limit: Option<i64>,
pub learning_overlay: Option<Value>,
}
pub fn to_html(
graph: &Graph,
communities: &Communities,
output: &Path,
options: &HtmlOptions,
diagnostics: &mut Diagnostics,
) -> Result<bool> {
let limit = options.node_limit.unwrap_or_else(viz_node_limit);
let assign = assignments(graph, communities);
let labels = &options.community_labels;
if graph.nodes.len() as i64 > limit {
if options.node_limit.is_none() {
return Err(format!(
"Graph has {} nodes - too large for HTML viz (limit: {limit}). Use --no-viz, raise GRAPHICLE_VIZ_NODE_LIMIT, or reduce input size.",
graph.nodes.len()
).into());
}
diagnostics.stdout.push(format!(
"Graph has {} nodes (above {limit} limit). Building aggregated community view...",
graph.nodes.len()
));
let mut meta = Graph::new(false, false);
for (cid, _) in communities {
meta.add_node(
json!(cid.to_string()),
json!({"label":community_name(Some(*cid),labels)})
.as_object()
.unwrap()
.clone(),
)?;
}
// In the order each community pair first appears, as upstream's
// Counter keeps it (an index keeps the count lookup constant-time).
let mut counts: Vec<((i64, i64), usize)> = vec![];
let mut slots = rustc_hash::FxHashMap::<(i64, i64), usize>::default();
for (u, v, _) in graph.iter_edges() {
if let (Some(cu), Some(cv)) = (assign[u], assign[v])
&& cu != cv
{
let key = (cu.min(cv), cu.max(cv));
let slot = *slots.entry(key).or_insert_with(|| {
counts.push((key, 0));
counts.len() - 1
});
counts[slot].1 += 1;
}
}
for ((u, v), n) in counts {
meta.add_edge(json!(u.to_string()),json!(v.to_string()),None,json!({"weight":n,"relation":format!("{n} cross-community edges"),"confidence":"AGGREGATED"}).as_object().unwrap().clone())?;
}
if meta.nodes.len() <= 1 {
diagnostics
.stdout
.push("Single community - aggregated view not useful. Skipping graph.html.".into());
return Ok(false);
}
let meta_communities = communities
.iter()
.map(|(c, _)| (*c, vec![json!(c.to_string())]))
.collect::<Communities>();
if let Some(hypers) = graph.attributes["hyperedges"]
.as_array()
.filter(|v| !v.is_empty())
{
let pairs = analyze::node_community_map(communities);
// The first pair with each key, as the linear search it replaces
// found it.
let mut community_of = std::collections::BTreeMap::new();
for (n, c) in &pairs {
community_of
.entry(crate::python_compat::scalar_key(n))
.or_insert(*c);
}
let mut remapped = vec![];
for he in hypers {
let mut ids = vec![];
let mut seen = BTreeSet::new();
if let Some(members) = he["nodes"].as_array() {
for id in members {
if let Some(c) = community_of.get(&crate::python_compat::scalar_key(id)) {
let c = c.to_string();
if seen.insert(c.clone()) {
ids.push(c)
}
}
}
}
if ids.len() >= 2 {
let label = he
.get("label")
.filter(|v| truth(v))
.cloned()
.unwrap_or_else(|| {
json!(he["relation"].as_str().unwrap_or("").replace('_', " "))
});
remapped.push(
json!({"id":he.get("id").unwrap_or(&json!("")),"label":label,"nodes":ids}),
);
}
}
meta.attributes["hyperedges"] = json!(remapped);
}
let opts = HtmlOptions {
community_labels: labels.clone(),
member_counts: communities
.iter()
.map(|(c, m)| (*c, m.len() as f64))
.collect(),
..Default::default()
};
if !to_html(&meta, &meta_communities, output, &opts, diagnostics)? {
return Ok(false);
}
diagnostics.stdout.push(format!(
"graph.html written (aggregated: {} community nodes, {} cross-community edges)",
meta.nodes.len(),
meta.edge_count()
));
diagnostics
.stdout
.push("Tip: run with --obsidian for full node-level detail.".into());
return Ok(true);
}
let degree = (0..graph.nodes.len())
.map(|i| analyze::degree(graph, i))
.collect::<Vec<_>>();
let max_deg = degree.iter().copied().max().unwrap_or(1).max(1) as f64;
let mut max_mc = options
.member_counts
.values()
.copied()
.reduce(f64::max)
.unwrap_or(1.0);
if max_mc == 0.0 {
max_mc = 1.0
}
let overlay = options
.learning_overlay
.clone()
.unwrap_or_else(|| reflect::load_learning_overlay(output).unwrap_or_else(|_| json!({})));
let mut vis_nodes = vec![];
for (i, n) in graph.nodes.iter().enumerate() {
let cid = assign[i].unwrap_or(0);
let color = COMMUNITY_COLORS[cid.rem_euclid(COMMUNITY_COLORS.len() as i64) as usize];
let label = security::sanitize_label(n.attributes.get("label").unwrap_or(&n.id));
let deg = degree[i];
let (size, font_size) = if !options.member_counts.is_empty() {
(
10.0 + 30.0 * options.member_counts.get(&cid).unwrap_or(&1.0) / max_mc,
12,
)
} else {
(
10.0 + 30.0 * (deg as f64 / max_deg),
if deg as f64 >= max_deg * 0.15 { 12 } else { 0 },
)
};
let size = format!("{size:.1}")
.parse::<f64>()
.map_err(crate::Error::from)?;
let source = n
.attributes
.get("source_file")
.filter(|v| truth(v))
.map(string)
.unwrap_or_default();
let mut node = json!({"id":n.id,"label":label,"color":{"background":color,"border":color,"highlight":{"background":"#ffffff","border":color}},"size":size,"font":{"size":font_size,"color":"#ffffff"},"title":label,"community":cid,"community_name":security::sanitize_label(&community_name(Some(cid),labels)),"source_file":security::sanitize_label(&json!(source)),"file_type":n.attributes.get("file_type").unwrap_or(&json!("")),"degree":deg});
// Aggregated view: the Node Info panel shows a meta node's member count.
if !options.member_counts.is_empty() {
node["member_count"] = options
.member_counts
.get(&cid)
.map(|v| json!(*v as i64))
.unwrap_or_else(|| {
json!(
communities
.iter()
.find(|(c, _)| *c == cid)
.map_or(0, |(_, m)| m.len())
)
});
}
if let Some(entry) = overlay.get(string(&n.id)).filter(|v| truth(v)) {
let status =
security::sanitize_label(&json!(string(entry.get("status").unwrap_or(&json!("")))));
let stale = truth(&entry["stale"]);
node["learning_status"] = json!(status);
node["learning_stale"] = json!(stale);
let ring = match status.as_str() {
"preferred" => Some("#22c55e"),
"contested" => Some("#f59e0b"),
_ => None,
};
if let Some(mut ring) = ring {
if stale {
ring = "#9ca3af";
node["shapeProperties"] = json!({"borderDashes":[4,4]});
}
node["borderWidth"] = json!(3);
node["color"] = json!({"background":color,"border":ring,"highlight":{"background":"#ffffff","border":ring}});
}
let uses = string(entry.get("uses").unwrap_or(&json!(0)));
let mut lesson = match status.as_str() {
"contested" => format!(
"Lesson: contested (useful {uses} / dead-end {})",
string(entry.get("neg").unwrap_or(&json!(0)))
),
"preferred" => format!(
"Lesson: preferred source ({uses} useful, score={})",
string(entry.get("score").unwrap_or(&json!(0)))
),
_ => format!("Lesson: {status} ({uses} useful)"),
};
if stale {
lesson.push_str(" [code changed — re-verify]")
};
node["title"] = json!(format!(
"{label}\n{}",
security::sanitize_label(&json!(lesson))
));
}
vis_nodes.push(node)
}
let mut vis_edges = vec![];
for (u, v, e) in graph.iter_edges() {
let d = &e.attributes;
let confidence = d.get("confidence").cloned().unwrap_or(json!("EXTRACTED"));
let relation = d.get("relation").cloned().unwrap_or(json!(""));
let extracted = confidence == "EXTRACTED";
vis_edges.push(json!({"from":d.get("_src").unwrap_or(&graph.nodes[u].id),"to":d.get("_tgt").unwrap_or(&graph.nodes[v].id),"label":relation,"title":security::sanitize_label(&json!(format!("{} [{}]",string(&relation),string(&confidence)))),"dashes":!extracted,"width":if extracted{2}else{1},"color":{"opacity":if extracted{0.7}else{0.35}},"confidence":confidence}));
}
let legend=labels.keys().map(|cid|{
let count=communities.iter().find(|(c,_)|c==cid).map(|(_,m)|m.len()).unwrap_or(0);
let n=options.member_counts.get(cid).map(|v|json!(*v as i64)).unwrap_or(json!(count));
json!({"cid":cid,"color":COMMUNITY_COLORS[cid.rem_euclid(10) as usize],"label":escape(&security::sanitize_label(&community_name(Some(*cid),labels))),"count":n})
}).collect::<Vec<_>>();
// The lists move into their documents (`json!` would copy them).
let nodes = Value::Array(vis_nodes);
let edges = Value::Array(vis_edges);
let legends = Value::Array(legend);
let hypers = js_safe(graph.attributes.get("hyperedges").unwrap_or(&json!([])))?;
let title = escape(&security::sanitize_label(&json!(html_document_title(
&output.to_string_lossy()
))));
let stats = format!(
"{} nodes · {} edges · {} communities",
graph.nodes.len(),
graph.edge_count(),
communities.len()
);
let hyper_script = hyperedge_script(&hypers);
// The page `render` assembles from the document and script templates
// (`html_script`), streamed into the file: neither the node and edge JSON
// nor the page is held as a string.
paths::atomic_replace_with(
output,
|file| {
let mut out = std::io::BufWriter::with_capacity(1 << 16, file);
render_to(
&mut out,
DOCUMENT_TEMPLATE,
&DOCUMENT_KEYS,
&mut |out, key| match key {
0 => out.write_all(title.as_bytes()),
1 => out.write_all(stats.as_bytes()),
2 => out.write_all(html_styles().as_bytes()),
3 => render_to(out, SCRIPT_TEMPLATE, &SCRIPT_KEYS, &mut |out, key| {
write_js_safe(out, [&nodes, &edges, &legends][key])
}),
_ => out.write_all(hyper_script.as_bytes()),
},
)?;
std::io::Write::flush(&mut out)
},
&paths::SystemReplace,
)
.map_err(crate::Error::from)?;
Ok(true)
}
pub fn dispatch(r: &Value) -> Result<Value> {
let s = |k: &str| r[k].as_str().unwrap_or("");
let mut d = Diagnostics::default();
let value = match s("function") {
"_viz_node_limit" => viz_node_limit_value(),
"_html_styles" => json!(html_styles()),
"_html_document_title" => json!(html_document_title(s("output_path"))),
"_hyperedge_script" => json!(hyperedge_script(s("hyperedges_json"))),
"_html_script" => json!(html_script(
s("nodes_json"),
s("edges_json"),
s("legend_json")
)),
"to_html" => {
let graph = Graph::from_node_link(&r["G"], "edges")?;
let options = HtmlOptions {
community_labels: labels(&r["community_labels"])?,
member_counts: labels(&r["member_counts"])?
.into_iter()
.map(|(c, n)| (c, n.as_f64().unwrap_or(1.0)))
.collect(),
node_limit: r
.get("node_limit")
.filter(|v| !v.is_null())
.map(bounded_integer),
learning_overlay: r.get("learning_overlay").filter(|v| !v.is_null()).cloned(),
};
json!(to_html(
&graph,
&communities(r)?,
Path::new(s("output_path")),
&options,
&mut d
)?)
}
_ => return Err("Unknown HTML export operation".into()),
};
Ok(json!({"value":value,"stdout":d.stdout,"stderr":d.stderr}))
}
#[cfg(test)]
mod tests {
use super::html_document_title;
/// The page streamed into the file equals the page `render` assembled
/// from `js_safe` strings: placeholders found in order, a repeated one
/// written each time, values (even placeholder-looking ones) never
/// re-scanned, every `<` of the JSON escaped.
#[test]
fn streamed_page_matches_rendered_page() {
use super::*;
let nodes = json!([{"id": "a<b", "label": "x</script><!--", "size": 10.5,
"title": "{{EDGES}} \u{e9}\u{1f600}", "n": [1, 2.50, null]}]);
let edges = json!([{"from": "a<b", "to": "{{NODES}}", "dashes": false}]);
let legend = json!([]);
for (document, script) in [
(DOCUMENT_TEMPLATE, SCRIPT_TEMPLATE),
(
"<{{SCRIPT}}|{{TITLE}}{{STATS}}{{SCRIPT}}{{STYLES}}{{HYPEREDGE_SCRIPT}}{{X}}",
"{{LEGEND}}{{NODES}}-{{EDGES}}{{NODES}}{{",
),
] {
let values = [
super::js_safe(&nodes).unwrap(),
super::js_safe(&edges).unwrap(),
super::js_safe(&legend).unwrap(),
];
let rendered_script = render(
script,
&[
(SCRIPT_KEYS[0], &values[0]),
(SCRIPT_KEYS[1], &values[1]),
(SCRIPT_KEYS[2], &values[2]),
],
);
let expected = render(
document,
&[
("{{TITLE}}", "T{{STATS}}"),
("{{STATS}}", "S"),
("{{STYLES}}", html_styles()),
("{{SCRIPT}}", &rendered_script),
("{{HYPEREDGE_SCRIPT}}", "H"),
],
);
let mut out = Vec::new();
render_to(
&mut out,
document,
&DOCUMENT_KEYS,
&mut |out, key| match key {
0 => out.write_all(b"T{{STATS}}"),
1 => out.write_all(b"S"),
2 => out.write_all(html_styles().as_bytes()),
3 => render_to(out, script, &SCRIPT_KEYS, &mut |out, key| {
write_js_safe(out, [&nodes, &edges, &legend][key])
}),
_ => out.write_all(b"H"),
},
)
.unwrap();
assert_eq!(String::from_utf8(out).unwrap(), expected);
}
}
/// The title keeps the output folder and what follows it. The
/// configuration folder (`~/.graphicle-graph`) is not an output folder,
/// although its name starts with the default output folder's; another
/// folder named like the output folder still is, as upstream's prefix
/// test matches `graphify-out-old`.
#[test]
fn a_path_under_the_configuration_folder_keeps_its_title() {
assert_eq!(
html_document_title(
"/home/user/.graphicle-graph/repos/owner/repo/.graphicle/graph.html"
),
".graphicle/graph.html"
);
assert_eq!(
html_document_title("/home/user/.graphicle-graph/global/graph.html"),
"graph.html"
);
assert_eq!(
html_document_title("/home/user/project/.graphicle-old/graph.html"),
".graphicle-old/graph.html"
);
}
}