{
"execution_tool": "graph_query",
"groups": [
{
"goal": "Check graph coverage and establish the indexed codebase shape.",
"name": "overview",
"queries": [
{
"description": "Count all materialized graph nodes as a quick coverage check.",
"name": "graph_coverage",
"parameters": [],
"returns": [
"total_nodes"
],
"statement": "MATCH (n) RETURN count(n) AS total_nodes LIMIT 1"
},
{
"description": "List materialized modules with source paths and spans.",
"name": "source_unit_inventory",
"parameters": [],
"returns": [
"id",
"label",
"qualified_name",
"path",
"line_start",
"line_end"
],
"statement": "MATCH (m:Module) RETURN m.id, m.label, m.qualified_name, m.path, m.line_start, m.line_end ORDER BY m.path LIMIT 200"
},
{
"description": "List source files with path and content metadata.",
"name": "package_directory_shape",
"parameters": [],
"returns": [
"path",
"label",
"size_bytes",
"content_hash"
],
"statement": "MATCH (f:File) RETURN f.path, f.label, f.size_bytes, f.content_hash ORDER BY f.path LIMIT 300"
}
]
},
{
"goal": "Find how the library exposes behavior through modules, definitions, or runtime entrypoints.",
"name": "public_surface",
"queries": [
{
"description": "Find exposed module surfaces and fallback definition-level public candidates.",
"name": "public_surface_candidates",
"parameters": [],
"returns": [
"surface_source",
"module_label",
"module_path",
"surface_id",
"surface_label",
"surface_qualified_name",
"surface_path",
"line_start"
],
"statement": "MATCH (m:Module)-[:FROM_Exposes]->(:Exposes)-[:TO_Exposes]->(surface) RETURN 'exposed' AS surface_source, m.label AS module_label, m.path AS module_path, surface.id AS surface_id, surface.label AS surface_label, surface.qualified_name AS surface_qualified_name, surface.path AS surface_path, surface.line_start AS line_start UNION ALL MATCH (m:Module)-[:FROM_Defines]->(:Defines)-[:TO_Defines]->(surface:Class) RETURN 'defined' AS surface_source, m.label AS module_label, m.path AS module_path, surface.id AS surface_id, surface.label AS surface_label, surface.qualified_name AS surface_qualified_name, surface.path AS surface_path, surface.line_start AS line_start UNION ALL MATCH (m:Module)-[:FROM_Defines]->(:Defines)-[:TO_Defines]->(surface:Function) RETURN 'defined' AS surface_source, m.label AS module_label, m.path AS module_path, surface.id AS surface_id, surface.label AS surface_label, surface.qualified_name AS surface_qualified_name, surface.path AS surface_path, surface.line_start AS line_start UNION ALL MATCH (m:Module)-[:FROM_Defines]->(:Defines)-[:TO_Defines]->(surface:Method) RETURN 'defined' AS surface_source, m.label AS module_label, m.path AS module_path, surface.id AS surface_id, surface.label AS surface_label, surface.qualified_name AS surface_qualified_name, surface.path AS surface_path, surface.line_start AS line_start LIMIT 200"
},
{
"description": "Find function-level name/path candidates for runtime or CLI entrypoints.",
"name": "entrypoint_runtime_surface",
"parameters": [],
"returns": [
"entrypoint_kind",
"entrypoint_id",
"entrypoint_label",
"entrypoint_path",
"target_id",
"target_label",
"target_qualified_name",
"target_path",
"line_start"
],
"statement": "MATCH (d:Function) WHERE d.label = 'main' OR d.label = 'cli' OR d.label CONTAINS 'server' OR d.path CONTAINS 'cli' RETURN 'name_candidate' AS entrypoint_kind, d.id AS entrypoint_id, d.label AS entrypoint_label, d.path AS entrypoint_path, d.id AS target_id, d.label AS target_label, d.qualified_name AS target_qualified_name, d.path AS target_path, d.line_start AS line_start LIMIT 100"
}
]
},
{
"goal": "Map internal and external dependencies so agents can infer layers and adapters.",
"name": "dependency_topology",
"queries": [
{
"description": "Map import declarations to external dependency nodes.",
"name": "external_dependency_map",
"parameters": [],
"returns": [
"path",
"import_label",
"dependency"
],
"statement": "MATCH (i:ImportDeclaration)-[:FROM_DependsOn]->(:DependsOn)-[:TO_DependsOn]->(d:Dependency) RETURN i.path, i.label AS import_label, d.label AS dependency ORDER BY d.label, i.path LIMIT 300"
},
{
"description": "List modules and their import declarations as a coupling inventory.",
"name": "module_import_coupling",
"parameters": [],
"returns": [
"module_label",
"module_path",
"import_label",
"line_start"
],
"statement": "MATCH (m:Module)-[:FROM_Imports]->(:Imports)-[:TO_Imports]->(i:ImportDeclaration) RETURN m.label, m.path, i.label, i.line_start ORDER BY m.path, i.line_start LIMIT 300"
}
]
},
{
"goal": "Identify important call paths, orchestration nodes, and central implementation flows.",
"name": "execution_flow",
"queries": [
{
"description": "Find definitions with many resolved incoming references.",
"name": "high_fan_in_definitions",
"parameters": [],
"returns": [
"id",
"label",
"qualified_name",
"path",
"inbound_refs"
],
"statement": "MATCH (ref)-[:FROM_ResolvesTo]->(:ResolvesTo)-[:TO_ResolvesTo]->(target:Class) RETURN target.id, target.label, target.qualified_name, target.path, count(ref) AS inbound_refs UNION ALL MATCH (ref)-[:FROM_ResolvesTo]->(:ResolvesTo)-[:TO_ResolvesTo]->(target:Function) RETURN target.id, target.label, target.qualified_name, target.path, count(ref) AS inbound_refs UNION ALL MATCH (ref)-[:FROM_ResolvesTo]->(:ResolvesTo)-[:TO_ResolvesTo]->(target:Method) RETURN target.id, target.label, target.qualified_name, target.path, count(ref) AS inbound_refs UNION ALL MATCH (ref)-[:FROM_ResolvesTo]->(:ResolvesTo)-[:TO_ResolvesTo]->(target:Module) RETURN target.id, target.label, target.qualified_name, target.path, count(ref) AS inbound_refs ORDER BY inbound_refs DESC LIMIT 50"
},
{
"description": "Find functions or methods that call many downstream nodes.",
"name": "high_fan_out_callers",
"parameters": [],
"returns": [
"id",
"label",
"qualified_name",
"path",
"outgoing_calls"
],
"statement": "MATCH (caller:Function)-[:FROM_Calls]->(:Calls)-[:TO_Calls]->(callee) RETURN caller.id, caller.label, caller.qualified_name, caller.path, count(callee) AS outgoing_calls UNION ALL MATCH (caller:Method)-[:FROM_Calls]->(:Calls)-[:TO_Calls]->(callee) RETURN caller.id, caller.label, caller.qualified_name, caller.path, count(callee) AS outgoing_calls ORDER BY outgoing_calls DESC LIMIT 50"
},
{
"description": "Inspect direct callees for a named callable.",
"name": "callable_neighborhood",
"parameters": [
"name"
],
"returns": [
"caller_id",
"caller_label",
"caller_qualified_name",
"callee_id",
"callee_label",
"callee_qualified_name",
"callee_path"
],
"statement": "MATCH (caller)-[:FROM_Calls]->(:Calls)-[:TO_Calls]->(callee) WHERE caller.label = $name OR caller.qualified_name = $name RETURN caller.id, caller.label, caller.qualified_name, callee.id, callee.label, callee.qualified_name, callee.path LIMIT 100"
}
]
},
{
"goal": "Expose data access, query execution, secrets, and configuration-sensitive paths.",
"name": "runtime_data_security",
"queries": [
{
"description": "Find actors that execute or construct query nodes.",
"name": "data_query_touchpoints",
"parameters": [],
"returns": [
"actor_id",
"actor_label",
"actor_qualified_name",
"actor_path",
"query_label",
"query_path",
"query_line_start"
],
"statement": "MATCH (actor)-[:FROM_ExecutesQuery]->(:ExecutesQuery)-[:TO_ExecutesQuery]->(q:Query) RETURN actor.id, actor.label, actor.qualified_name, actor.path, q.label, q.path, q.line_start LIMIT 100"
},
{
"description": "Find actors linked to secret or sensitive configuration references.",
"name": "secret_configuration_touchpoints",
"parameters": [],
"returns": [
"actor_id",
"actor_label",
"actor_qualified_name",
"actor_path",
"secret_label",
"secret_path",
"secret_line_start"
],
"statement": "MATCH (actor)-[:FROM_UsesSecret]->(:UsesSecret)-[:TO_UsesSecret]->(s:SecretRef) RETURN actor.id, actor.label, actor.qualified_name, actor.path, s.label, s.path, s.line_start LIMIT 100"
}
]
},
{
"goal": "Link architecture claims to documentation and parser evidence.",
"name": "documentation_context",
"queries": [
{
"description": "Find documentation chunks connected to code nodes.",
"name": "documentation_to_code_links",
"parameters": [],
"returns": [
"doc_id",
"doc_label",
"doc_path",
"node_id",
"node_label",
"node_qualified_name",
"node_path"
],
"statement": "MATCH (d:DocumentationChunk)-[:FROM_Documents]->(:Documents)-[:TO_Documents]->(n) RETURN d.id, d.label, d.path, n.id, n.label, n.qualified_name, n.path LIMIT 100"
},
{
"description": "Return evidence nodes for a named symbol or qualified name.",
"name": "evidence_for_symbol",
"parameters": [
"name"
],
"returns": [
"node_id",
"node_label",
"node_qualified_name",
"node_path",
"evidence_id",
"evidence_label",
"evidence_path",
"evidence_line_start",
"evidence_line_end"
],
"statement": "MATCH (n)-[:FROM_EvidencedBy]->(:EvidencedBy)-[:TO_EvidencedBy]->(e) WHERE n.label = $name OR n.qualified_name = $name RETURN n.id, n.label, n.qualified_name, n.path, e.id, e.label, e.path, e.line_start, e.line_end LIMIT 100"
}
]
},
{
"goal": "Detect graph gaps that reduce confidence in architecture claims.",
"name": "graph_quality_gaps",
"queries": [
{
"description": "Find references without resolved semantic targets.",
"name": "unresolved_reference_risk",
"parameters": [],
"returns": [
"id",
"label",
"path",
"line_start"
],
"statement": "MATCH (r:Reference) WHERE NOT EXISTS { MATCH (r)-[:FROM_ResolvesTo]->(:ResolvesTo)-[:TO_ResolvesTo]->() } RETURN r.id, r.label, r.path, r.line_start ORDER BY r.path, r.line_start LIMIT 200"
}
]
}
],
"recommended_order": [
"overview",
"public_surface",
"dependency_topology",
"execution_flow",
"runtime_data_security",
"documentation_context",
"graph_quality_gaps"
],
"workflow": "coding_task_architecture_discovery"
}