[Bulk index][Python] Wrap Pyright and scip-python with truthful dynamic limits

[samchon]

Outcome

Replace the stale batch scip-python core with a pinned current Pyright semantic
exporter that shares one Program/type-evaluator state, walks each source once,
and publishes exact facts plus Any/Unknown coverage. Keep scip-python as a
navigation compatibility fallback only.

Current master baseline

Current master registers scip-python with semantic-index authority and only
references. Its bundled Pyright core is historically pinned far behind
current Pyright, omits kinds/enclosing symbols/diagnostics, conflates
implementation relations, and cannot expose call-receiver typing coverage.

PR #147 measured Flask at 10.629 s through scip-python and 0.748 s
through the static fallback. The faster static cell does not have semantic
resolution. The strict cell is a useful cold navigation baseline; no resident
no-op/edit result exists.

Why Pyright is the semantic owner

Pyright is designed as a high-performance
type checker for large Python codebases. Its open-source service already owns:

• configuration and execution environments;
• import resolution and typeshed/custom stubs;
• a Program of source files;
• parse trees, symbol tables, declarations and scopes;
• cached type evaluation and diagnostics; and
• incremental source updates.

scip-python contains a modified historical Pyright tree. Updating and enriching
that batch artifact creates a permanent lag. A custom exporter in a pinned
current Pyright service can reuse the same program and evaluator used by the
language service and avoid one references request per symbol.

Decision: pinned Pyright command/service

Add an upstreamable samchon/graphSnapshot command or narrow maintained fork:

1. load the same configuration/execution environments as Pyright;
2. wait for analysis completion and capture one program generation;
3. enumerate program source files and walk parse trees once;
4. resolve declarations, symbols, calls and types through the existing evaluator;
5. emit changed file/environment shards using [Bulk index] Replace symbol-by-symbol LSP scans with compiler-owned snapshots #63's protocol; and
6. verify program/config/source generation before commit.

Use the resident language service for edit/no-op mode. A batch command may serve
CI, but it must use the same exporter and schema rather than generating SCIP
and reparsing it.

Pin the Pyright release and commit, record its Python language support and
typeshed revision, and reject an unknown internal API handshake.

Facts and dynamic limits

Export:

• modules, classes, functions, methods, parameters, variables, properties,
  type aliases and nested/local declarations;
• imports/aliases, syntactic exports and __all__ only where statically
  evaluable;
• resolved function/method/constructor calls;
• read/write accesses and type references;
• direct base classes/protocol information and overrides where Pyright proves
  them;
• syntactic decorators with resolved decorator expression and decorated target;
• diagnostics from the same program; and
• framework tests through a named pytest/unittest enricher.

Python's dynamic surface is not a provider failure. Emit unresolved records for:

• Any/Unknown call receivers;
• getattr/setattr, __getattr__, __getattribute__;
• monkey-patching and metaclass-synthesized members;
• importlib, __import__, dynamic __all__;
• eval/exec;
• dynamic *args/**kwargs forwarding;
• C-extension/opaque stub boundaries; and
• decorators whose runtime transformation changes identity/signature beyond
  static proof.

Publish both counts and denominators for call receivers typed concrete,
union/protocol, explicit Any, implicit Unknown, and unresolved. Do not merge
Any and Unknown: one is an explicit escape, the other missing information.

Potential override/duck-typing candidates are not executed dispatches.
Only a statically closed exact target may emit that edge.

Identity and environment

Use distribution/module identity, qualified owner path, declaration kind and
canonical signature/type-parameter structure. Include:

• execution environment/root and --project-namespace equivalent;
• source module versus stub module and stub-to-implementation relation;
• decorated function's source identity distinct from the runtime wrapper;
• document/owner-scoped locals;
• nested definitions and comprehensions; and
• generation-scoped identity for dynamic/synthetic entities that cannot be
  stable.

Python has no source-level overload definitions in the Java sense, but
@overload declarations, implementation bodies and stub/source pairs require
one canonical callable with all declaration spans and signatures.

The universe includes Pyright config/pyproject, execution environment,
interpreter version/platform, import paths, venv, installed distributions,
typeshed/custom stubs, Python version, define constants, strictness settings and
all imported source/stub digests.

Incremental and performance behavior

• no-op: reuse the resident Program generation and graph manifest;
• body edit: Pyright invalidates affected files/types; export their shards;
• public type/import/stub/config change: re-export the reported dependent
  closure;
• environment/package/typeshed change: select a new universe;
• create/delete/rename: explicit shard update/removal; and
• analysis error/cancel/process crash/generation movement: retain prior commit.

No call to find references per declaration is allowed. Cold overhead is
measured against the same Pyright analysis without graph export. Target no-op
p95 below 250 ms and ordinary body edit below 2 s on the pinned fixture.

Implementation map

1. Add [Bulk index] Replace symbol-by-symbol LSP scans with compiler-owned snapshots #63's shard/coverage schema.
2. Build a pinned Pyright exporter package/fork with a version handshake.
3. Add a provider ahead of scip-python only after configuration parity passes.
4. Add exact dynamic/stub/execution-environment fixtures and deterministic
   fake-protocol tests.
5. Retain scip-python/static as separately identified fallbacks.
6. Phase-separate Pyright load/analyze/export/merge in the real Flask benchmark.

Acceptance

• Exact fixtures cover packages, multiple execution environments, namespace
  packages, stubs/source, overloads, decorators, protocols, generics,
  properties, async, comprehensions, dynamic imports, monkey-patching and
  tests.
• Calls/accesses/types are extracted from the resident evaluator, not text
  or SCIP markdown.
• Any/Unknown receiver coverage and every unresolved dynamic class are
  machine-readable.
• All 15 fact families have explicit coverage/unresolved rows.
• No-op, body/API edit, create/delete/rename, config/interpreter/package/
  stub change, error, cancel, crash and retry are atomic.
• Cold overhead is compared with native Pyright; no-op/edit phases are
  measured separately.
• Linux/macOS/Windows interpreter and path selection are proven.
• scip-python and static remain truthful fallbacks.
• Focused tests, Python experiment, pnpm build, pnpm test, and
  pnpm coverage pass.

Primary references

• Pyright repository
• Pyright configuration and execution environments
• current scip-python

[samchon]

Provider recon at graph 71e35af. The pin this issue requires is trivially satisfiable — and that is the problem. Plus the concrete meaning of "truthful dynamic limits".

The pin is real, and three years stale

packages/pyright/package.json and packages/pyright-internal/package.json both read "version": "1.1.301".

• Pyright 1.1.301 published 2023-03-29.
• Pyright current is 1.1.411 (2026-06-25).

scip-python's analyzer core is ~3 years and 110 releases behind. It predates PEP 695 type-parameter syntax (3.12), type statements, and 3.13 typing. The README's "supports Python 3.10+" describes the runtime floor, not modern syntax coverage.

This issue's pinning requirement is therefore satisfied trivially — but the pin is to a 2023 type system, and that is the fact that should drive the acceptance matrix. The repo is still active (pushed 2026-07-14), but packages/pyright* are not being rebased.

Requested amendment: record the Pyright version explicitly in provenance and in the acceptance rows, and decide whether fixtures may use post-3.11 syntax at all. A repo using PEP 695 generics will index, quietly, with worse results.

What "truthful dynamic limits" means concretely

Provable from a bound Pyright program: module/class/function/parameter declarations, import statements, syntactic decorators, statically-resolved base classes, and call targets whose receiver type Pyright inferred to a concrete class.

Never provable: getattr/setattr dispatch, monkey-patching, __getattr__/__getattribute__, metaclass-synthesized members, importlib/__import__, eval/exec, *args/**kwargs forwarding, C-extension boundaries, and any receiver typed Any/Unknown.

The honest coverage metric is the Any/Unknown rate at call receivers. Pyright distinguishes Unknown (implicit Any) from explicit Any internally — the right signal — but scip-python does not emit it, so a sidecar over the Pyright program must compute and publish it. A call edge whose receiver is Unknown must be emitted as conservative/degraded or as a warning, never as an exact target.

(Compare Ruby, which has a first-class upstream coverage metric — the Sorbet sigil histogram plus types.input.untyped.usages. Python has no equivalent and must synthesize one. See the #81 comment.)

What the artifact actually proves

SymbolInformation is constructed in exactly 12 places in treeVisitor.ts and populates only symbol, documentation, relationships.

• No kind, no display_name, no signature_documentation, no enclosing_symbol, no diagnostics. Signatures exist only as markdown-fenced generated stub text inside documentation (```python … ```) — recovering one means parsing markdown, which is not a strict fact. GraphNodeKind must come from descriptor suffixes; see the [Bulk index] Add strict SCIP navigation-skeleton ingestion and enrichment gates #69 comment.
• Occurrences carry Definition and ReadAccess; pushNewOccurrence defaults to role = scip.SymbolRole.ReadAccess (treeVisitor.ts:1396). No WriteAccess → the read/write split is impossible. No Import role, no Test role.
• Relationships are is_implementation: true only, in two places: class base classes (type.details.baseClasses, :735-782) and superclass method declarations (getFunctionRelationships, :390). extends, implements, and overrides are all collapsed into that one flag and are indistinguishable in the output. Protocols are unimplemented — the source carries // TODO: Add Protocol support with: base.compatibleProtocols, so structural typing produces no relationship at all.

Silent truncation risk

Base-class relationships are filtered by guessPackage(...); if the package cannot be guessed, the relationship is dropped without a warning. A missing extends edge is indistinguishable from "no base class". The adapter must treat absent relationships as unknown, never as proven-absent. (#69 now carries this as a general rule; Python is the witness.)

Proven: contains (derived), references. calls, instantiates, imports, type_ref, tests need enrichment; dispatches is unprovable and must be reported as degraded authority; exports is unprovable in principle (Python has no export construct — __all__ is a runtime list); decorates is provable for syntactic decorators from the Pyright AST but not for runtime-applied ones.

Invocation and prep

@sourcegraph/scip-python 0.6.6 (2025-09-05). npm install -g @sourcegraph/scip-python; scip-python index . --project-name=$MY_PROJECT → index.scip. Flags --target-only=src/subdir, --project-namespace=implicit.namespace, --environment=path/to/env.json.

Activate the virtualenv first — scip-python shells out to pip for installed package names/versions. --environment supplies a JSON list of PythonPackage{name, version, files} and "will skip any calls out to pip", which is the deterministic path a fixture should take. Requires Python 3.10+, Node 16+. OOM is common: NODE_OPTIONS="--max-old-space-size=8192". Repo default branch is scip, not main.

Identity (feeds #65)

scip-python python <package> <version> <descriptors>, from packageDescriptor, typeDescriptor, methodDescriptor, termDescriptor, parameterDescriptor, metaDescriptor('__init__'). Python has no overloads, so the ordinal-disambiguator problem that afflicts Java/C#/Kotlin does not arise here.

• Same-named locals: safe — locals become local N, document-scoped (must still be path-prefixed).
• Decorators: the decorated function keeps its own symbol, but the decorator's transformation — signature rewrite, wrapping, registration — is not modeled. A @property-turned-attribute or a registry decorator is invisible. This bears on this issue's decorator acceptance row.
• Monkey-patching: not represented at all.
• --project-namespace rewrites symbol prefixes — it must be recorded in provenance, or cross-generation identity silently changes.

Incremental

Cold-only. The shipped CLI is batch: index → write → exit. No daemon, no resident mode. This issue's resident plan requires a custom sidecar over pyright-internal's program APIs — feasible (the fork keeps pyright-internal intact, "no substantial changes"), but it is a build against a 2023 Pyright API.

Provenance

Metadata.tool_info{name, version, arguments} free; PythonPackage{name, version, files} from pip or --environment is a good environment fingerprint. Missing: interpreter version, Pyright config, stub set, and the Any rate — all must be synthesized by the provider.

Verdict

Wrapper for a navigation skeleton; sidecar or fork for anything semantic. Ceiling to record: "Pyright-1.1.301-resolved static facts, no read/write split, no import roles, extends/implements/overrides conflated, Protocols unsupported, dispatch unprovable."

Full recon: .wiki/bulk-index-providers/recon-python-ruby-php.md.

[samchon]

The body now chooses a pinned current Pyright Program/type-evaluator exporter
as the final provider. The historical Pyright core embedded in scip-python
remains a navigation fallback rather than the foundation to keep rebasing and
enriching.

The new provider must publish explicit concrete/union/protocol/Any/Unknown
receiver coverage and dynamic unresolved sites. This is the minimum contract
that lets MCP distinguish “no call” from “Pyright could not determine the
receiver,” while reusing the resident program instead of asking for references
per symbol.