Inter-Service Call Query API

[georgesafta]

Problem

The SDK has no API surface for querying cross-service call relationships. Individual applications can be analyzed in isolation today, but there is no way for a consumer to ask "which services call into payments-service?" or "what does orders-service call at runtime?" — regardless of what language those services are written in.

Inter-service HTTP/gRPC calls cross language boundaries (a TypeScript gateway calling a Java service calling a Python worker), so this feature cannot live on a single language facade — it needs a language-neutral, estate-level home. The facade needs to consume a Neo4J database that stores analysis from multiple applications.

Why the current architecture cannot host this

Today's analysis facades — JavaAnalysis (cldk/analysis/java/java_analysis.py), PythonAnalysis, TypeScriptAnalysis — are all language-scoped, and their Neo4j backends are hard-scoped to a single application:

• Neo4jConnectionConfig (cldk/analysis/commons/backend_config.py) carries an application_name, and each backend requires it — e.g. cldk/analysis/java/neo4j/neo4j_backend.py:110 raises application_name is required to scope queries to an application. if it is absent.
• Every Cypher query is anchored to that one app under a language-specific node label: MATCH (:JApplication {name: $app})-[:J_HAS_UNIT]->... (java/neo4j/neo4j_backend.py:137,172), and likewise (:PyApplication)-[:PY_HAS_MODULE]-> and :TSApplication for the other two.

Scope

• New: EstateAnalysis facade (or similar name) in cldk/analysis/commons/ (or a new cldk/analysis/estate/), backed by a single Cypher client.
• New: ServiceCall Pydantic model (language-neutral) in cldk/models/ or a new cldk/models/estate/.
• New: CLDK.estate(...) factory method on CLDK (cldk/core.py, alongside java()/python()/typescript()/c()) — takes a Neo4jConnectionConfig only (no project_path, no language).
• Reuse Neo4jConnectionConfig but ignore its application_name at the estate layer — estate queries are deliberately un-scoped. That field is meaningless for estate; the estate client must not thread it into any query. (Do not reuse the per-language *Neo4jBackend classes — they raise without an app anchor.)
• Not in scope: Changes to any per-language facade or analyzer; slice/taint/reachability queries.
• Read-only: the SDK only polls the graph; Codeanalyzer populates it.

Goals

• Data model — define a language-neutral ServiceCall Pydantic model. Schema TBD; at minimum: source_app, source_language, target_app, target_language, protocol (HTTP/gRPC), endpoint and http_method.
• EstateAnalysis facade with the following methods:

  get_incoming_service_calls(app_name: str) -> List[ServiceCall]
  get_outgoing_service_calls(app_name: str) -> List[ServiceCall]
  get_incoming_service_calls_from(app_name: str, from_app_name: str) -> List[ServiceCall]
  get_outgoing_service_calls_to(app_name: str, to_app_name: str) -> List[ServiceCall]
  get_service_calls_for_endpoint(app_name: str, endpoint: str) -> List[ServiceCall]

  These queries need to extract the exposed APIs and the invocations and match them based on their target URI, input/output schema. The exact edge type need to be decided.
• CLDK.estate(backend: Neo4jConnectionConfig) factory on cldk/core.py — parallels CLDK.java() / CLDK.python() / CLDK.typescript() but requires no project_path, and constructs an estate client (not a per-language *Neo4jBackend).
• Tests — mocked unit tests against the Cypher query layer; E2E smoke test against a multi-service fixture once available.

Caveats and Known Risks

• gRPC endpoint capture is TBD on the Codeanalyzer side; REST is partially tracked already.
• No Neo4J instance with multiple applications stored yet available (the schema is not yet known).

Definition of Done

• ServiceCall model defined.
• EstateAnalysis + CLDK.estate() implemented; five methods verified against a Neo4j instance with ≥ 2 services.
• Unit tests (mocked) green; docstrings and schema notes in place.