# How GitNexus Traces Execution Flows from Entry Points Through Call Chains

> Discover how GitNexus traces execution flows from entry points through call chains using function scoring, weighted call graphs, and BFS traversals for high-level process insights.

- Repository: [Abhigyan Patwari/GitNexus](https://github.com/abhigyanpatwari/GitNexus)
- Tags: how-to-guide
- Published: 2026-03-08

---

**GitNexus traces execution flows by scoring functions to identify entry points, building a confidence-weighted call graph, and performing bounded BFS traversals to discover high-level process nodes.**

GitNexus is an open-source code analysis tool that maps high-level execution flows—called "processes"—by analyzing call relationships in source code. Understanding how execution flows are traced from entry points through call chains is essential for navigating complex codebases and identifying business-logic boundaries. The implementation spans the ingestion pipeline in `gitnexus/src/core/ingestion/`.

## Scoring Functions to Identify Entry Points

The first phase of tracing execution flows involves identifying candidate entry points using heuristics that distinguish high-level orchestrators from utility functions.

### Heuristic Scoring Algorithm

The `calculateEntryPointScore` function in [`gitnexus/src/core/ingestion/entry-point-scoring.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/entry-point-scoring.ts) evaluates every function and method across four dimensions (lines [190-226](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/entry-point-scoring.ts#L190-L226)):

- **Call ratio**: Calculated as `calleeCount / (callerCount + 1)`, giving high base scores to functions that call many others but are called by few.
- **Export status**: Public or exported symbols receive a 2.0× multiplier versus 1.0× for internal functions.
- **Name patterns**: Positive patterns like `handle*`, `on*`, or `*Controller` boost scores, while utility patterns like `get*` or `_private` penalize them (lines [152-172](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/entry-point-scoring.ts#L152-L172)).
- **Framework hints**: The `detectFrameworkFromPath(filePath)` utility adds framework-specific multipliers based on file location.

### Filtering Test Files

Before scoring, the pipeline excludes test files via `isTestFile` to prevent scaffolding code from becoming entry points. The matcher patterns are defined in [`gitnexus/src/core/ingestion/entry-point-scoring.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/entry-point-scoring.ts) (lines [72-107](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/entry-point-scoring.ts#L72-L107)).

## Building the Confidence-Weighted Call Graph

Once entry candidates are identified, [`gitnexus/src/core/ingestion/process-processor.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/process-processor.ts) constructs adjacency lists for traversal. The `buildCallsGraph` function creates forward edges for CALLS relationships with confidence ≥ 0.5, while `buildReverseCallsGraph` creates reverse edges to count callers (lines [221-249](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/process-processor.ts#L221-L249)).

```typescript
const buildCallsGraph = (graph: KnowledgeGraph): AdjacencyList => { … }
const buildReverseCallsGraph = (graph: KnowledgeGraph): AdjacencyList => { … }

```

## Bounded BFS Traversal from Entry Points

The `findEntryPoints` function iterates over all `Function` and `Method` nodes, filters out test files, requires at least one outgoing CALL, and runs `calculateEntryPointScore`. It returns the top-scoring IDs (up to 200) as entry points (lines [51-76](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/process-processor.ts#L51-L76) and [88-95](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/process-processor.ts#L88-L95)).

### Trace Generation and Limits

`traceFromEntryPoint` performs a breadth-first search that tracks the full path (`[nodeId, …]`). It stops when `maxTraceDepth` is reached, when a node has no further CALLS, or when the `maxBranching` limit is exceeded for a node. A trace is emitted only if it meets the `minSteps` threshold (lines [337-384](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/process-processor.ts#L337-L384)).

### Trace Deduplication

Two passes prune redundant paths:

1. **`deduplicateTraces`** removes any trace that is a subset of a longer one (lines [395-415](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/process-processor.ts#L395-L415)).
2. **`deduplicateByEndpoints`** keeps only the longest trace per *entry → terminal* pair (lines [426-440](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/process-processor.ts#L426-L440)).

## Materializing Process Nodes and Steps

For each final trace, the processor creates a `ProcessNode` object containing:

- A deterministic ID (`proc_<idx>_<sanitizedName>`).
- A heuristic label `"Entry → Terminal"` (capitalized).
- The list of communities touched, step count, and the raw node ID trace.

The node creation logic resides in [`gitnexus/src/core/ingestion/process-processor.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/process-processor.ts) (lines [141-176](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/process-processor.ts#L141-L176)). Corresponding `ProcessStep` records are emitted for every node in the trace.

## Public API and Configuration

The entire pipeline is exposed via `processProcesses` in [`gitnexus/src/core/ingestion/process-processor.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/process-processor.ts) (lines [74-87](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/process-processor.ts#L74-L87)):

```typescript
export const processProcesses = async (
  knowledgeGraph: KnowledgeGraph,
  memberships: CommunityMembership[],
  onProgress?: (msg: string, pct: number) => void,
  config: Partial<ProcessDetectionConfig> = {}
): Promise<ProcessDetectionResult> => { … }

```

Call this function after community detection to obtain a `ProcessDetectionResult` containing all discovered processes, per-step data, and statistics.

### Customizing Trace Boundaries

You can control the traversal behavior via the `config` parameter:

```typescript
await processProcesses(kg, memberships, undefined, {
  maxTraceDepth: 5,   // Stop after 5 hops
  maxBranching: 2,    // Explore at most two outgoing calls per node
  minSteps: 3,        // Ignore trivial A→B traces
});

```

### Inspecting Individual Traces

To examine specific execution flows:

```typescript
const { processes } = await processProcesses(kg, memberships);
const first = processes[0];
console.log('Full node‑ID trace:', first.trace);
// Translate IDs back to source locations:
first.trace.forEach(id => console.log(kg.getNode(id).properties.filePath));

```

## Summary

- **Heuristic scoring** in [`entry-point-scoring.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/entry-point-scoring.ts) identifies high-level entry points using call ratios, export status, and naming patterns while filtering out test files.
- **Graph construction** in [`process-processor.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/process-processor.ts) builds forward and reverse CALLS adjacency lists with confidence thresholds ≥ 0.5.
- **Bounded BFS** traces execution from entry points, respecting `maxTraceDepth`, `maxBranching`, and `minSteps` constraints to avoid explosion.
- **Deduplication** removes subset traces and collapses paths by endpoints to produce minimal, representative execution flows.
- **Materialization** converts traces into `ProcessNode` and `ProcessStep` records with deterministic IDs and heuristic labels.

## Frequently Asked Questions

### How does GitNexus prevent utility functions from being marked as entry points?

GitNexus applies naming-pattern penalties in `calculateEntryPointScore` (lines [152-172](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/entry-point-scoring.ts#L152-L172)) that reduce scores for prefixes like `get*`, `set*`, or `_private`. Additionally, the call-ratio heuristic favors functions that call many others but are rarely called themselves, which typically excludes low-level utilities.

### What is the confidence threshold for including a call in the execution graph?

The `buildCallsGraph` function only includes edges where the CALLS relationship confidence is ≥ 0.5. This filtering occurs in [`gitnexus/src/core/ingestion/process-processor.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/process-processor.ts) around lines [221-249](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/process-processor.ts#L221-L249), ensuring that low-confidence or speculative calls do not pollute execution traces.

### How can I limit the depth of execution flow tracing?

Pass a custom `ProcessDetectionConfig` to `processProcesses` with the `maxTraceDepth` parameter. For example, setting `maxTraceDepth: 5` stops the BFS after five hops from the entry point. You can also constrain branching via `maxBranching` to limit how many outgoing calls are followed per node, as shown in the configuration examples in [`process-processor.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/process-processor.ts).

### Why are some execution traces removed after the initial BFS?

GitNexus runs two deduplication passes to eliminate redundant traces. First, `deduplicateTraces` removes any trace that is a complete subset of a longer trace (lines [395-415](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/process-processor.ts#L395-L415)). Second, `deduplicateByEndpoints` keeps only the longest trace for each unique entry-to-terminal pair (lines [426-440](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/process-processor.ts#L426-L440)), ensuring the final set contains minimal, representative execution flows.