Viper_VSCode/architecture/generated/pyright-engineering-map.md

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
• Constraint solving and type variables
• Flow narrowing and type guards
• Import resolution and packaging
• Parser, binder, and symbols
• Diagnostics and configuration
• Language service providers
• 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
• packages/pyright/packages/pyright-internal/src/analyzer/checker.ts
• packages/pyright/packages/pyright-internal/src/analyzer/types.ts

Test starting points:

• packages/pyright/packages/pyright-internal/src/tests/samples
• packages/pyright/packages/pyright-internal/src/tests/typeEvaluator*.test.ts

Related semantic areas:

• Type Evaluation

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
• packages/pyright/packages/pyright-internal/src/analyzer/constraintTracker.ts
• packages/pyright/packages/pyright-internal/src/analyzer/typeEvaluator.ts

Test starting points:

• packages/pyright/packages/pyright-internal/src/tests/samples/typeVar*.py
• packages/pyright/packages/pyright-internal/src/tests/samples/generic*.py

Related semantic areas:

• Constraint Solving and Type Variables
• Type Evaluation

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
• packages/pyright/packages/pyright-internal/src/analyzer/typeGuards.ts
• packages/pyright/packages/pyright-internal/src/analyzer/checker.ts

Test starting points:

• packages/pyright/packages/pyright-internal/src/tests/samples/typeNarrowing*.py
• packages/pyright/packages/pyright-internal/src/tests/samples/typeGuard*.py

Related semantic areas:

• Flow Narrowing and Type Guards
• Type Evaluation

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
• packages/pyright/packages/pyright-internal/src/analyzer/importResult.ts
• packages/pyright/packages/pyright-internal/src/languageService/autoImporter.ts

Test starting points:

• packages/pyright/packages/pyright-internal/src/tests/importResolver.test.ts
• packages/pyright/packages/pyright-internal/src/tests/samples/import*.py

Related semantic areas:

• Import Resolution and Packaging
• Language Service Providers

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
• packages/pyright/packages/pyright-internal/src/analyzer/binder.ts
• packages/pyright/packages/pyright-internal/src/analyzer/symbol.ts

Test starting points:

• packages/pyright/packages/pyright-internal/src/tests/parser.test.ts
• packages/pyright/packages/pyright-internal/src/tests/parseTreeUtils.test.ts
• packages/pyright/packages/pyright-internal/src/tests/samples

Related semantic areas:

• Parser, Binder, and Symbols

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
• packages/pyright/packages/pyright-internal/src/analyzer/checker.ts
• packages/pyright/packages/pyright-internal/src/commands

Test starting points:

• packages/pyright/packages/pyright-internal/src/tests/config.test.ts
• packages/pyright/packages/pyright-internal/src/tests/samples

Related semantic areas:

• Diagnostics and Configuration
• Type Evaluation

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
• packages/pyright/packages/pyright-internal/src/languageServerBase.ts

Test starting points:

• packages/pyright/packages/pyright-internal/src/tests/languageServer.test.ts
• packages/pyright/packages/pyright-internal/src/tests/harness/fourslash

Related semantic areas:

• Language Service Providers

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
• packages/pyright/packages/vscode-pyright/src
• packages/pyright/packages/pyright-internal/src/server.ts

Test starting points:

• packages/pyright/packages/pyright-internal/src/tests/languageServer.test.ts
• packages/pyright/packages/pyright-internal/src/tests/service.test.ts

Related semantic areas:

• CLI and VS Code Extension

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.