<!--
Generated by the pyrx RPG docs pipeline from ../../.rpg/rpg_encoder.json.
Do not edit directly — changes will be overwritten by the next refresh.
Graph repo_sha: 784698179a5627072df39bbe0fcadb55bb7dd408
Graph generated_at: 2026-06-10T00:19:36.841Z
-->
# Pyright Engineering Map

A maintainer map from Pyright concepts to implementation roots, tests, and graph pages. It uses LSP terminology where Pyright implements a protocol-facing language feature, and stays within packages/pyright-owned paths.

## Quick Index

- [Type evaluation](#type-evaluation)
- [Constraint solving and type variables](#constraint-solving-and-type-variables)
- [Flow narrowing and type guards](#flow-narrowing-and-type-guards)
- [Import resolution and packaging](#import-resolution-and-packaging)
- [Parser, binder, and symbols](#parser-binder-and-symbols)
- [Diagnostics and configuration](#diagnostics-and-configuration)
- [Language service providers](#language-service-providers)
- [CLI and VS Code extension](#cli-and-vs-code-extension)

## Type evaluation

**User surface:** Type inference, call analysis, overload selection, operator semantics, class and function type computation

**LSP surface:** `textDocument/hover`<br>`textDocument/completion`<br>`textDocument/signatureHelp`

**Start in code:**

- [packages/pyright/packages/pyright-internal/src/analyzer/typeEvaluator.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/analyzer/typeEvaluator.ts)
- [packages/pyright/packages/pyright-internal/src/analyzer/checker.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/analyzer/checker.ts)
- [packages/pyright/packages/pyright-internal/src/analyzer/types.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/analyzer/types.ts)

**Test starting points:**

- [packages/pyright/packages/pyright-internal/src/tests/samples](https://github.com/microsoft/pyrx/tree/main/packages/pyright/packages/pyright-internal/src/tests/samples)
- [packages/pyright/packages/pyright-internal/src/tests/typeEvaluator*.test.ts](https://github.com/microsoft/pyrx/tree/main/packages/pyright/packages/pyright-internal/src/tests)

**Related semantic areas:**

- [Type Evaluation](features/feat-type-evaluation.md)

## Constraint solving and type variables

**User surface:** TypeVar solving, generic specialization, constrained types, variance, inference scoring

**LSP surface:** `textDocument/hover`<br>`textDocument/signatureHelp`<br>`textDocument/completion`

**Start in code:**

- [packages/pyright/packages/pyright-internal/src/analyzer/constraintSolver.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/analyzer/constraintSolver.ts)
- [packages/pyright/packages/pyright-internal/src/analyzer/constraintTracker.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/analyzer/constraintTracker.ts)
- [packages/pyright/packages/pyright-internal/src/analyzer/typeEvaluator.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/analyzer/typeEvaluator.ts)

**Test starting points:**

- [packages/pyright/packages/pyright-internal/src/tests/samples/typeVar*.py](https://github.com/microsoft/pyrx/tree/main/packages/pyright/packages/pyright-internal/src/tests/samples)
- [packages/pyright/packages/pyright-internal/src/tests/samples/generic*.py](https://github.com/microsoft/pyrx/tree/main/packages/pyright/packages/pyright-internal/src/tests/samples)

**Related semantic areas:**

- [Constraint Solving and Type Variables](features/feat-constraint-solving-and-type-variables.md)
- [Type Evaluation](features/feat-type-evaluation.md)

## Flow narrowing and type guards

**User surface:** Control-flow graph, narrowing expressions, TypeGuard and TypeIs behavior, pattern narrowing

**LSP surface:** `textDocument/hover`<br>`textDocument/publishDiagnostics`

**Start in code:**

- [packages/pyright/packages/pyright-internal/src/analyzer/codeFlowEngine.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/analyzer/codeFlowEngine.ts)
- [packages/pyright/packages/pyright-internal/src/analyzer/typeGuards.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/analyzer/typeGuards.ts)
- [packages/pyright/packages/pyright-internal/src/analyzer/checker.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/analyzer/checker.ts)

**Test starting points:**

- [packages/pyright/packages/pyright-internal/src/tests/samples/typeNarrowing*.py](https://github.com/microsoft/pyrx/tree/main/packages/pyright/packages/pyright-internal/src/tests/samples)
- [packages/pyright/packages/pyright-internal/src/tests/samples/typeGuard*.py](https://github.com/microsoft/pyrx/tree/main/packages/pyright/packages/pyright-internal/src/tests/samples)

**Related semantic areas:**

- [Flow Narrowing and Type Guards](features/feat-flow-narrowing-and-type-guards.md)
- [Type Evaluation](features/feat-type-evaluation.md)

## Import resolution and packaging

**User surface:** Module resolution, execution environments, editable installs, stub discovery, auto-import search

**LSP surface:** `textDocument/completion`<br>`textDocument/definition`<br>`workspace/symbol`

**Start in code:**

- [packages/pyright/packages/pyright-internal/src/analyzer/importResolver.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/analyzer/importResolver.ts)
- [packages/pyright/packages/pyright-internal/src/analyzer/importResult.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/analyzer/importResult.ts)
- [packages/pyright/packages/pyright-internal/src/languageService/autoImporter.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/languageService/autoImporter.ts)

**Test starting points:**

- [packages/pyright/packages/pyright-internal/src/tests/importResolver.test.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/tests/importResolver.test.ts)
- [packages/pyright/packages/pyright-internal/src/tests/samples/import*.py](https://github.com/microsoft/pyrx/tree/main/packages/pyright/packages/pyright-internal/src/tests/samples)

**Related semantic areas:**

- [Import Resolution and Packaging](features/feat-import-resolution-and-packaging.md)
- [Language Service Providers](features/feat-language-service-providers.md)

## Parser, binder, and symbols

**User surface:** Python syntax tree parsing, binding, scopes, symbol tables, declaration discovery

**LSP surface:** `textDocument/documentSymbol`<br>`textDocument/definition`<br>`textDocument/references`

**Start in code:**

- [packages/pyright/packages/pyright-internal/src/parser](https://github.com/microsoft/pyrx/tree/main/packages/pyright/packages/pyright-internal/src/parser)
- [packages/pyright/packages/pyright-internal/src/analyzer/binder.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/analyzer/binder.ts)
- [packages/pyright/packages/pyright-internal/src/analyzer/symbol.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/analyzer/symbol.ts)

**Test starting points:**

- [packages/pyright/packages/pyright-internal/src/tests/parser.test.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/tests/parser.test.ts)
- [packages/pyright/packages/pyright-internal/src/tests/parseTreeUtils.test.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/tests/parseTreeUtils.test.ts)
- [packages/pyright/packages/pyright-internal/src/tests/samples](https://github.com/microsoft/pyrx/tree/main/packages/pyright/packages/pyright-internal/src/tests/samples)

**Related semantic areas:**

- [Parser, Binder, and Symbols](features/feat-parser-binder-and-symbols.md)

## Diagnostics and configuration

**User surface:** Diagnostic rules, config files, execution environments, severity mapping, command-line analysis

**LSP surface:** `textDocument/publishDiagnostics`<br>`workspace/didChangeConfiguration`

**Start in code:**

- [packages/pyright/packages/pyright-internal/src/common/configOptions.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/common/configOptions.ts)
- [packages/pyright/packages/pyright-internal/src/analyzer/checker.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/analyzer/checker.ts)
- [packages/pyright/packages/pyright-internal/src/commands](https://github.com/microsoft/pyrx/tree/main/packages/pyright/packages/pyright-internal/src/commands)

**Test starting points:**

- [packages/pyright/packages/pyright-internal/src/tests/config.test.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/tests/config.test.ts)
- [packages/pyright/packages/pyright-internal/src/tests/samples](https://github.com/microsoft/pyrx/tree/main/packages/pyright/packages/pyright-internal/src/tests/samples)

**Related semantic areas:**

- [Diagnostics and Configuration](features/feat-diagnostics-and-configuration.md)
- [Type Evaluation](features/feat-type-evaluation.md)

## Language service providers

**User surface:** Hover, completion, definition, references, rename, document symbols, semantic tokens

**LSP surface:** `textDocument/hover`<br>`textDocument/completion`<br>`textDocument/definition`<br>`textDocument/references`<br>`textDocument/rename`<br>`textDocument/documentSymbol`<br>`textDocument/semanticTokens`

**Start in code:**

- [packages/pyright/packages/pyright-internal/src/languageService](https://github.com/microsoft/pyrx/tree/main/packages/pyright/packages/pyright-internal/src/languageService)
- [packages/pyright/packages/pyright-internal/src/languageServerBase.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/languageServerBase.ts)

**Test starting points:**

- [packages/pyright/packages/pyright-internal/src/tests/languageServer.test.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/tests/languageServer.test.ts)
- [packages/pyright/packages/pyright-internal/src/tests/harness/fourslash](https://github.com/microsoft/pyrx/tree/main/packages/pyright/packages/pyright-internal/src/tests/harness/fourslash)

**Related semantic areas:**

- [Language Service Providers](features/feat-language-service-providers.md)

## CLI and VS Code extension

**User surface:** Pyright command-line entry point, VS Code extension integration, server startup, client configuration

**LSP surface:** `initialize`<br>`shutdown`<br>`workspace/configuration`

**Start in code:**

- [packages/pyright/packages/pyright/src](https://github.com/microsoft/pyrx/tree/main/packages/pyright/packages/pyright/src)
- [packages/pyright/packages/vscode-pyright/src](https://github.com/microsoft/pyrx/tree/main/packages/pyright/packages/vscode-pyright/src)
- [packages/pyright/packages/pyright-internal/src/server.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/server.ts)

**Test starting points:**

- [packages/pyright/packages/pyright-internal/src/tests/languageServer.test.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/tests/languageServer.test.ts)
- [packages/pyright/packages/pyright-internal/src/tests/service.test.ts](https://github.com/microsoft/pyrx/blob/main/packages/pyright/packages/pyright-internal/src/tests/service.test.ts)

**Related semantic areas:**

- [CLI and VS Code Extension](features/feat-cli-and-vs-code-extension.md)

## How to use this map

- Start with the area that matches the behavior the user or protocol request exercises.
- Follow the code links for implementation entry points, then use the test links to find the matching test shape.
