# 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`
`textDocument/completion`
`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`
`textDocument/signatureHelp`
`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`
`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`
`textDocument/definition`
`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`
`textDocument/definition`
`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`
`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`
`textDocument/completion`
`textDocument/definition`
`textDocument/references`
`textDocument/rename`
`textDocument/documentSymbol`
`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`
`shutdown`
`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.