topos.graphs.mdg.object

Module Dependency Graph (MDG) Representation

Consumes the knowledge graph produced by GitNexus and lifts it into a Representation. This is the inter-module view of the program — it captures the import/call/inheritance structure across files, packages, and classes. Compare this with the academic intra-procedural Program Dependence Graph at topos.graphs.pdg.object, which records control- and data-dependence edges within a single procedure.

GitNexus runs gitnexus analyze on a repository and writes a .gitnexus/ directory containing a LadybugDB graph store. This module parses that output into an in-memory graph of typed nodes and relationships, then computes dependency-level metrics that the AST alone cannot provide.

Node labels and relationship types mirror GitNexus’s shared schema:

Nodes:  File, Module, Function, Class, Method, Import, ...
Edges:  CALLS, IMPORTS, INHERITS, CONTAINS, USES, ...

Metrics produced (feed the COMPOSABLE generator of H(G_qual)):

• mdg.coupling – afferent + efferent coupling for a file

• mdg.instability – Ce / (Ca + Ce) (Martin’s metric)

• mdg.fan_in – incoming CALLS edges

• mdg.fan_out – outgoing CALLS edges

• mdg.dep_depth – longest IMPORTS chain from the file

exception topos.graphs.mdg.object.LadybugSchemaMismatchError(message, *, original=None)

Bases: RuntimeError

Raised when .gitnexus/lbug storage version exceeds embedded ladybug.

class topos.graphs.mdg.object.GraphNode(id, label, properties=<factory>)

Bases: object

A node in the GitNexus knowledge graph.

id

label

properties

class topos.graphs.mdg.object.GraphRelationship(id, source_id, target_id, type, confidence=1.0, reason='')

Bases: object

An edge in the GitNexus knowledge graph.

id

source_id

target_id

type

confidence = 1.0

reason = ''

class topos.graphs.mdg.object.ModuleDependencyGraph(target_file, nodes=<factory>, relationships=<factory>, _outgoing=<factory>, _incoming=<factory>)

Bases: object

Inter-module dependency-graph representation parsed from GitNexus output.

Provides graph lookup methods and computes dependency-level metrics for a target file path within the graph.

This is the module-level dependency view (imports, calls, inheritance across files). It is distinct from the academic intra-procedural Program Dependence Graph at topos.graphs.pdg.object.

target_file

The file path to compute metrics for.

Type:

str

nodes

All nodes in the graph, keyed by ID.

Type:

dict[str, topos.graphs.mdg.object.GraphNode]

relationships

All relationships in the graph, keyed by ID.

Type:

dict[str, topos.graphs.mdg.object.GraphRelationship]

target_file

nodes

relationships

property name

property dimension

classmethod from_gitnexus_dir(gitnexus_dir, target_file)

Build a ModuleDependencyGraph from a .gitnexus/ directory.

Supports both the current LadybugDB binary format (lbug file, produced by GitNexus ≥ 1.5) and the legacy JSON directory format.

Parameters:

• gitnexus_dir – Path to the .gitnexus/ directory.

• target_file – The file path to compute metrics for.

Raises:

• FileNotFoundError – If the graph store cannot be found.

• ImportError – If ladybug is not installed for binary format.

• LadybugSchemaMismatchError – If the store version exceeds embedded ladybug.

add_node(node)

add_relationship(rel)

get_node(node_id)

nodes_of_label(label)

relationships_of_type(rel_type)

outgoing(node_id, rel_type=None)

incoming(node_id, rel_type=None)

file_node_id()

Find the File node ID matching target_file.

contained_symbols(file_node_id)

Return IDs of all symbols directly contained in a file node.

all_contained_symbols(node_id)

Return IDs of all symbols transitively reachable via CONTAINS edges.

Performs a BFS down the CONTAINS tree starting from node_id. Cycles are handled safely via a visited set.

metrics()