BranchPy
Log in

Docs-Builder

# Analysis Architecture

Version: 1.1.1
Last Updated: January 23, 2026

Pipeline Overview

Source (.rpy) → AST Parser → Semantic Mapper → CFG Builder → Propagation Engine →
SAE (state changes) → PFI (functions/stats) → Exports (JSON/trace/call graph)

Core Modules

  • AST Parsing: PythonASTParser builds ParseResult trees (variables, functions, imports, complexity) for each file.
  • Cross-File Tracking: CrossFileTracker merges parse trees, resolves label graphs, detects unreachable/duplicate labels, and builds label graph edges.
  • Semantic Mapping: SemanticAction + SemanticNode annotate CFG nodes with canonical actions (jump/call/guard/set/io, etc.) using function providers and semantics YAML.
  • CFG Builder: Label-level CFG (CFG scaffold) and statement-level SAE CFG with edge kinds (SEQ, JUMP, JUMP_DYNAMIC, BRANCH_TRUE/False, CALL). Supports dynamic jump resolution via semantics and dataflow.
  • Propagation Engine: Computes flow metrics (path count, cyclomatic complexity, branching factor), variable lifetimes, and warnings (dead code, undefined label, dynamic flow, dead branches).
  • SAE: Tracks state changes along paths, infers types/operations, classifies cosmetic vs. mechanical branches, and surfaces mutation summaries per label/path.
  • PFI: Indexes functions, analyzes stat effects, builds call graphs, runs consistency checks, and exports JSON/DOT formats.
  • AI Integration (analysis-facing): Provider protocol + request/response models used when analysis features call AI providers (code review, docgen, summaries) respecting safe/local flags.

Data Flows & Outputs

  • Semantic Trace Exporter: JSONL trace of semantic actions and CFG metadata for governance and analytics.
  • Flow Exports: Propagation engine emits metrics/warnings; SAE produces mutation timelines; PFI exports function index, stat modifiers, call graph, and governance events.
  • UI/CLI Integration:
    • CLI: branchpy analyze, branchpy semantics2 flow, branchpy pfi, SAE/propagation helpers.
    • VS Code panels: Semantics, PFI panels consume the same CLI/JSON outputs.

Reliability & Performance

  • Propagation engine caches results (239x speedup for repeat analyses); clearing cache is supported.
  • Statement-level CFG avoids SEQ edges after terminal nodes; menu branching is explicit with choice nodes.
  • Dynamic jumps resolved via semantics catalog + dataflow; unresolved jumps emitted as warnings, not failures.
  • PFI scales to 10k functions (<20s) with governance logging optional.

Governance & Boundaries

  • Analysis artifacts are deterministic and local; no telemetry or network writes required.
  • Governance events: function discovery/analysis/warnings (PFI), flow warnings (propagation), semantic trace exports.
  • UI decisions (panels, flowchart rendering) live in User-Guide; analysis docs focus on compute and data contracts.