architecture

name	architecture
description	Use when you need to understand the Pyre or Pysa codebase architecture, find where specific functionality is implemented, or navigate the source directory structure. Use when working on OCaml code, debugging type checking or taint analysis issues, or exploring the codebase.
metadata	{"oncalls":["pysa"],"strict":true}

Pyre Architecture

Type Checking Pipeline

• Python CLI (client/): Reads .pyre_configuration, determines flags, shells out to pyre.bin
• Command dispatch (source/main.ml): Routes to Check, Analyze (Pysa), Infer, Server, CodeNavigation, or NoDaemonQuery
• Parsing (source/menhir_parser/, source/cpython_parser/): Python source -> AST (source/ast/)
• Environment building (source/analysis/): Populates global type environment in parallel. All sources added at once (not recursively following imports). Builds a layered environment chain: UnannotatedGlobalEnvironment -> ClassHierarchyEnvironment -> TypeAliasEnvironment -> AnnotatedGlobalEnvironment -> FunctionDefinitionEnvironment -> ErrorsEnvironment -> TypeEnvironment
• Type checking (source/analysis/typeCheck.ml): Each function checked in parallel via control flow graph. Propagates parameter types through function body, checks compatibility at each operation. Never goes beyond function call boundaries.
• Error reporting: Results collected and returned to CLI

Pysa (Taint Analysis) Pipeline

• Analysis orchestrator (source/interprocedural_analyses/taint/taintAnalysis.ml): Main entrypoint of the analysis, runs the different analysis steps
• PyrePysaApi (source/interprocedural/pyrePysaApi.ml): Provides an API to query a type checker (pyre or pyrefly)
• Class Hierarchy Graph (source/interprocedural/classHierarchyGraph.ml): Builds a class hierarchy graph
• Callables Shared Memory (source/interprocedural/callablesSharedMemory.ml): Builds a mapping from callables (functions and methods) to their AST and signature
• Call Graph (source/interprocedural/callGraph.ml): Defines call graph data structures
• Call Graph Builder (source/interprocedural/callGraphBuilder.ml): Builds call graphs for all callables
• Model parsing (source/interprocedural_analyses/taint/modelParser.ml): Parses .pysa model files
• Forward analysis (source/interprocedural_analyses/taint/forwardAnalysis.ml): Tracks taint from sources
• Backward analysis (source/interprocedural_analyses/taint/backwardAnalysis.ml): Tracks taint to sinks
• Configuration (source/interprocedural_analyses/taint/taintConfiguration.ml): Defines rules connecting sources to sinks
• Global Fixpoint (source/interprocedural/fixpointAnalysis.ml): Implements a global fixpoint over callables
• Model (source/interprocedural_analyses/taint/model.ml): Defines a summary of the taint behavior of a function, inferred during analysis

Key Source Directories

• source/ast/: Python AST representation (Expression, Statement, Source, Location, Reference)
• source/analysis/: Core type checker: type representation (type.ml), CFG, fixpoint, preprocessing, environments, type order, class hierarchy
• source/interprocedural/: Interprocedural framework: call graph, dependency graph, override graph, fixpoint
• source/interprocedural_analyses/taint/: Pysa taint analysis: sources, sinks, domains, models, rules, reporting
• source/interprocedural_analyses/type_inference/: Interprocedural type inference
• source/server/: Pyre daemon for incremental analysis
• source/code_navigation_server/: IDE code navigation server
• source/command/: OCaml CLI command implementations
• source/buck_command/: Buck-specific commands
• source/buck_integration/: Buck build system integration
• source/service/: Shared memory management, scheduling
• source/domains/: Abstract domain library (lattices for interprocedural analyses)
• source/hack_parallel/: Shared memory and multi-worker infrastructure (forked from Hack)
• source/saved_state/: Serialization for incremental analysis
• client/: Python CLI (pyre command)
• client/commands/: All user-facing commands (check, analyze, start, stop, infer, query, etc.)
• client/configuration/: .pyre_configuration file parsing
• client/language_server/: LSP protocol implementation
• api/: Programmatic Python API for Pyre server
• pyre_extensions/: Runtime Python helpers (none_throws, safe_cast, etc.)
• tools/generate_taint_models/: Auto-generation of Pysa taint models
• tools/typeshed_patcher/: Applies patches to bundled typeshed stubs
• stubs/: Bundled typeshed with patching mechanism
• facebook/: Meta-internal code (not open-sourced)

OCaml Conventions

• Most types derive show, eq, compare, to_yojson via PPX derivers. For a type Module.t, Module.show gives a debug string.
• Debug with Log.dump "format %s" value and run with pyre --noninteractive check
• In Python test files, use pyre_dump(), pyre_dump_cfg(), pyre_dump_locations(), and reveal_type(x) to inspect Pyre's state