@lzehrung/codegraph 3.0.1 → 3.1.1

package/dist/indexer/navigation-goto.js

@@ -1,16 +1,20 @@
 import { CSHARP_SUPPORT, supportForFileWithoutHeaderSample } from "../languages.js";
+import { pythonPropertyDecorator } from "./python-property-decorator.js";
 import { isJsTsLanguage } from "../languages/js-family.js";
 import { isPythonReceiverAttributeAssignmentName } from "../languages/definitions/python.js";
 import { sliceText } from "../util/ast.js";
 import { foldPhpIdentifierCase } from "../util/identifiers.js";
+import { csharpNamespaceAtIndex, csharpNamespaceRegionAtIndex, } from "../util/csharp-tree.js";
 import { fileIdentityKey } from "../util/paths.js";
 import { collectMemberAccessChain, getMemberAccessParts, getNavigationExpressionProperty, isMemberAccessNode, isReceiverNameNode, memberAccessTraversalTypes, } from "../util/member-access.js";
+import { definitionIdentityKey } from "./reference-context.js";
+import { toTreeSitterPosition } from "./shared.js";
 import { MEMBER_ACCESS_ROWS, supportsReceiverMemberNavigation } from "../util/member-access-tables.js";
 import { typescriptCallableContainerKey, typescriptMergedNamespaceContainers } from "./ts-callables.js";
 import { effectiveExplicitBinding, isExpandedStarBinding, resolveStarImportedName, resolveStarImportedNamespace, starImportPrecedence, } from "./star-import-precedence.js";
 import { classifyReceiver, cppOutOfLineOwnerPath, cppQualifiedNameSegments, declarationIsStaticEquivalent, declarationNodeIsStatic, declaredTypeNameNode, declaresMembers, hasStaticMemberDistinction, memberContainerDef, nearestMemberContainer, isUnprovenHeritageExpression, kotlinExtensionReceiverTypeNode, csharpDottedNameRoot, nodeInStaticMemberContext, importTypeQuerySpecifier, rustImplSelfTypeNode, supportsStaticMemberScope, TRANSPARENT_MEMBER_CONTAINER_TYPES, unwrapNamedType, } from "../graphs/symbol-graph-detailed/receiver-calls.js";
 import { getCallArgumentCount, memberLookupBinding } from "../languages/callable-arity.js";
-import { getCompilationUnitPeers, getPackageDeclarationName } from "./compilation-units.js";
+import { csharpNamespaceChainDeclares, csharpProjectDeclarationsUnknown, csharpUsingTargetShadowed, getCompilationUnitPeers, getPackageDeclarationName, } from "./compilation-units.js";
 import { isExportedDeclaration, isJvmPackageSymbolVisible, isPrivateDeclaration, isGoExportedMemberName, isSwiftCrossFileHiddenSharedOwnerMember, } from "./declaration-visibility.js";
 import { ensureParsedContext } from "./parse-context.js";
 import { csharpLookupName, csharpQualifiedNameNode, findClosestScopeBinding, getOrBuildScopeIndex, resolveNamedDefinition, } from "./navigation-local.js";
@@ -18,7 +22,7 @@ import { resolveCppQualifiedMemberContainer, cppFunctionHasImplicitThis } from "
 import { okGoToResult } from "./navigation-provenance.js";
 import { comparePhpReferenceNames, findPhpImportAlias } from "./navigation-php.js";
 import { resolveIndexedPhpClassReference, resolvePhpNamespaceSymbol } from "./php-namespace-symbols.js";
-import { cjsRequireValueBinding, memberContainerForDefinition, resolveCsharpQualifiedName, resolveExport, resolveImported, resolvePhpExportByImportType, resolveImportTypeMember, } from "./navigation-resolve.js";
+import { cjsRequireValueBinding, csharpShadowedStarsMayHold, memberContainerForDefinition, resolveCsharpQualifiedName, resolveExport, resolveImported, resolvePhpExportByImportType, resolveImportTypeMember, } from "./navigation-resolve.js";
 import { CSHARP_PARTIAL_CONTAINER_TYPES, getSharedOwnerIdentity, isSwiftExtensionContainer, sharedOwnerCanUseMembers, } from "./shared-owner-identity.js";
 import { hasSeparateMemberScopes, inheritsMemberOverloads, selectMember, } from "./member-selection.js";
 import { SymbolKind, } from "./types.js";
@@ -237,7 +241,7 @@ export async function findCsharpPartialTypeEquivalents(index, def) {
     if (context.sup.id !== "csharp")
         return [];
     const start = def.range.start;
-    const nameNode = context.tree.rootNode.descendantForPosition({ row: start.line - 1, column: start.column - 1 }, { row: start.line - 1, column: start.column - 1 });
+    const nameNode = context.tree.rootNode.descendantForPosition(toTreeSitterPosition(start), toTreeSitterPosition(start));
     const container = nearestMemberContainer(nameNode);
     if (!container)
         return [];
@@ -286,7 +290,7 @@ function nameNodeForDef(context, def) {
     const index = start.index;
     if (index !== undefined)
         return context.tree.rootNode.descendantForIndex(index, index);
-    const position = { row: start.line - 1, column: start.column - 1 };
+    const position = toTreeSitterPosition(start);
     return context.tree.rootNode.descendantForPosition(position, position);
 }
 function enclosingImportScope(declarationName) {
@@ -296,41 +300,181 @@ function enclosingImportScope(declarationName) {
     }
     return current?.parent ?? null;
 }
+/** The scope of the import whose local name token starts at `start`, found by descending from `root`. */
+function importScopeAt(root, start) {
+    let nameNode = root;
+    for (;;) {
+        const child = nameNode.namedChildren.find((candidate) => candidate.startIndex <= start && start < candidate.endIndex);
+        if (!child)
+            break;
+        nameNode = child;
+    }
+    return enclosingImportScope(nameNode);
+}
+const CSHARP_SHADOWED_ALIAS_REASON = "C# alias is shadowed by an enclosing namespace member";
+const CSHARP_SHADOWED_TARGET_REASON = "C# alias target is shadowed by a member of an enclosing namespace";
+const CSHARP_INCOMPLETE_ALIAS_REASON = "C# namespace alias may name a type in a project file that could not be read";
+const CSHARP_SHADOWED_USING_REASON = "C# using directive is shadowed by an enclosing namespace that may declare the name";
+/** The leading name `X` of a C# dotted or alias-qualified name (`X.Y.Z`, `X::Y`) and the names it qualifies. */
+export function csharpChainQualifier(chainNode, source) {
+    const chain = collectMemberAccessChain({ sup: CSHARP_SUPPORT, source, chainNode });
+    if (!chain || !isReceiverNameNode(CSHARP_SUPPORT, chain.base.type))
+        return null;
+    return { qualifier: chain.base, names: chain.names };
+}
+/**
+ * Whether a nearer namespace shadows the namespace alias that `qualifier` (the `X` of `X.Type`) names. C# searches
+ * each enclosing namespace together with its own aliases before the next one out, so a namespace or type `X` in a
+ * namespace deeper than the alias's own comes before the alias. The answer comes from the index's own C# declarations
+ * when the lookup runs, never from the alias binding a cached module holds. An alias under `#if`, `#elif`, or
+ * `#else` belongs to the namespace that contains the conditional block. `X::Type` binds only aliases.
+ */
+function csharpAliasShadowedAt(index, mod, qualifier, source) {
+    if (qualifier.parent?.type === "alias_qualified_name")
+        return false;
+    const name = sliceText(qualifier, source);
+    const alias = innermostNamespaceImport(mod.imports, name, qualifier, CSHARP_SUPPORT.normalizeIdentifier);
+    const aliasStart = alias?.kind === "namespace" ? alias.localRange?.start.index : undefined;
+    const regions = mod.csharpNamespaceFacts?.regions;
+    if (aliasStart === undefined || !regions)
+        return false;
+    const enclosing = csharpNamespaceAtIndex(regions, qualifier.startIndex);
+    return (!!enclosing &&
+        csharpNamespaceChainDeclares(index, mod, enclosing, CSHARP_SUPPORT.normalizeIdentifier(name), csharpNamespaceAtIndex(regions, aliasStart)));
+}
+/**
+ * Why a use led by the namespace alias `qualifier` names (`X.Type`, `X::Type`) is unproven, or `null` when the alias
+ * stands. A nearer namespace can shadow the alias, and an enclosing namespace of the alias's own directive can shadow
+ * the first segment of its target. A project file whose declarations are unknown (no syntax tree) may declare the
+ * same type name as one the alias reaches, so no type found through a namespace alias is proven to be the only one.
+ * All three answers come from the index's own C# declarations when the lookup runs, never from a flag a cached
+ * module holds.
+ */
+export function csharpAliasUnprovenReason(index, mod, qualifier, source) {
+    if (csharpAliasShadowedAt(index, mod, qualifier, source))
+        return CSHARP_SHADOWED_ALIAS_REASON;
+    const alias = innermostNamespaceImport(mod.imports, sliceText(qualifier, source), qualifier, CSHARP_SUPPORT.normalizeIdentifier);
+    if (alias?.kind !== "namespace")
+        return null;
+    // An incomplete scan is the reason when it is the only one, and a declaration that was read names the shadowing one.
+    if (csharpProjectDeclarationsUnknown(index, mod))
+        return CSHARP_INCOMPLETE_ALIAS_REASON;
+    return csharpUsingTargetShadowed(index, mod, alias.localRange?.start.index, alias.from)
+        ? CSHARP_SHADOWED_TARGET_REASON
+        : null;
+}
+/**
+ * Why a dotted name led by `qualifier` (`B` of `B.Type`) is unproven because a `using N;` may bring `B` in, or `null`.
+ * An enclosing namespace shadows such a directive, so no lookup resolves it, and a namespace named `B` that the project
+ * declares must not stand in for what `B` may name there. An alias in scope binds the name first, and `B::Type` reaches
+ * aliases only, so neither is this reason.
+ */
+export function csharpShadowedUsingReason(index, mod, qualifier, source) {
+    if (qualifier.parent?.type === "alias_qualified_name")
+        return null;
+    const name = sliceText(qualifier, source);
+    if (!csharpShadowedStarsMayHold(index, mod, name) || csharpAliasAt(mod, name, qualifier))
+        return null;
+    return CSHARP_SHADOWED_USING_REASON;
+}
+/**
+ * The namespace block whose directives include the alias `binding`, read from the file's own namespace regions, so an
+ * alias under `#if` keeps the scope of the block around it. `undefined` for the compilation unit, and for a binding or
+ * file with no recorded position.
+ */
+function csharpAliasRegion(mod, binding) {
+    const aliasStart = binding.kind === "named" || binding.kind === "namespace" ? binding.localRange?.start.index : undefined;
+    const regions = mod.csharpNamespaceFacts?.regions;
+    return regions ? csharpNamespaceRegionAtIndex(regions, aliasStart) : undefined;
+}
+/**
+ * The alias of `candidates` that C# finds first for a use at `useIndex`. An alias binds only inside the block of the
+ * namespace its directive sits in (a directive before every namespace belongs to the whole file), and the aliases of a
+ * block come before those of the blocks around it, so of the aliases in scope the one in the smallest block wins. A
+ * binding or file with no recorded position counts as in scope and as outermost. Aliases of one block can only differ
+ * under conditional compilation, and the first stays.
+ */
+function nearestCsharpAlias(mod, candidates, useIndex) {
+    let nearest;
+    let nearestSpan = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        const region = csharpAliasRegion(mod, candidate);
+        if (region && (useIndex < region.start || useIndex >= region.end))
+            continue;
+        const span = region ? region.end - region.start : Number.POSITIVE_INFINITY;
+        if (!nearest || span < nearestSpan) {
+            nearest = candidate;
+            nearestSpan = span;
+        }
+    }
+    return nearest;
+}
+const csharpAliasTables = new WeakMap();
+/** The explicit aliases of a C# file by name, read from its import list once. A star import's expanded copies are no aliases. */
+function csharpAliasTable(mod) {
+    const cached = csharpAliasTables.get(mod.imports);
+    if (cached?.size === mod.imports.length)
+        return cached;
+    const table = { size: mod.imports.length, types: new Map(), namespaces: new Map() };
+    const add = (aliases, name, binding) => {
+        const named = aliases.get(name);
+        if (named)
+            named.push(binding);
+        else
+            aliases.set(name, [binding]);
+    };
+    for (const imp of mod.imports) {
+        if (imp.kind === "namespace") {
+            add(table.namespaces, CSHARP_SUPPORT.normalizeIdentifier(imp.localNS), imp);
+        }
+        else if ((imp.kind === "named" || imp.kind === "default") && !isExpandedStarBinding(imp, mod.imports)) {
+            add(table.types, imp.local, imp);
+        }
+    }
+    csharpAliasTables.set(mod.imports, table);
+    return table;
+}
 /**
- * Rewrites a valid C# `using X = Namespace; X::Target` lookup into the dotted form
- * export resolution already understands. `global::` and ordinary dotted names keep
- * their source spelling; an unknown alias stays `X::Target` instead of a bare name.
+ * The alias, namespace or type, that C# binds the name `name` to at `useNode`: the one declared in the nearest namespace
+ * block that contains the use. `undefined` when no alias is in scope there.
+ */
+export function csharpAliasAt(mod, name, useNode) {
+    const namespaceAlias = innermostNamespaceImport(mod.imports, name, useNode, CSHARP_SUPPORT.normalizeIdentifier);
+    const typeAliases = csharpAliasTable(mod).types.get(name) ?? [];
+    return nearestCsharpAlias(mod, namespaceAlias ? [namespaceAlias, ...typeAliases] : typeAliases, useNode.startIndex);
+}
+/**
+ * Whether a table of the file's imports keyed by name, built once for the whole file, answers for `name` at `useNode`.
+ * C# aliases bind only inside the block of their directive, so the table is right only for a name that no alias
+ * declares, or whose single alias is the one in scope at the use. A name that two aliases share, or whose alias sits in
+ * another block, has no answer a whole-file table can give.
+ */
+export function csharpAliasTableAnswers(mod, name, useNode) {
+    const table = csharpAliasTable(mod);
+    const types = table.types.get(name);
+    const namespaces = table.namespaces.get(CSHARP_SUPPORT.normalizeIdentifier(name));
+    const declared = (types?.length ?? 0) + (namespaces?.length ?? 0);
+    if (!declared)
+        return true;
+    return declared === 1 && csharpAliasAt(mod, name, useNode) === (types?.[0] ?? namespaces?.[0]);
+}
+/**
+ * Rewrites a valid C# `using X = Namespace;` lookup (`X.Target` or `X::Target`) into the
+ * dotted form export resolution understands. `global::` and unknown aliases keep their source spelling.
  */
 export function csharpAliasQualifiedLookupName(node, source, fallback, imports) {
     const raw = csharpLookupName(node, source, fallback);
     if (raw.startsWith("global::"))
         return raw;
     const chainNode = csharpQualifiedNameNode(node);
-    if (!chainNode || !raw.includes("::"))
+    const lead = chainNode && csharpChainQualifier(chainNode, source);
+    if (!lead)
         return raw;
-    const names = [];
-    let current = chainNode;
-    let base = null;
-    while (current && (current.type === "qualified_name" || current.type === "alias_qualified_name")) {
-        const parts = getMemberAccessParts(CSHARP_SUPPORT, current);
-        base = parts.object ?? base;
-        let property = parts.property;
-        if (property?.type === "generic_name") {
-            property = property.childForFieldName("name") ?? property.namedChildren[0] ?? property;
-        }
-        if (property?.type === "identifier")
-            names.push(sliceText(property, source));
-        current = base;
-    }
-    if (!base || !isReceiverNameNode(CSHARP_SUPPORT, base.type) || !names.length)
-        return raw;
-    const alias = sliceText(base, source);
+    const alias = sliceText(lead.qualifier, source);
     if (alias === "global")
         return raw;
-    const imported = innermostNamespaceImport(imports, alias, base, CSHARP_SUPPORT.normalizeIdentifier);
-    if (!imported)
-        return raw;
-    return `${imported.from}.${[...names].reverse().join(".")}`;
+    const imported = innermostNamespaceImport(imports, alias, lead.qualifier, CSHARP_SUPPORT.normalizeIdentifier);
+    return imported ? `${imported.from}.${lead.names.toReversed().join(".")}` : raw;
 }
 /**
  * Innermost in-scope namespace import bound to `alias`. `normalize` applies the language's
@@ -351,14 +495,7 @@ export function innermostNamespaceImport(imports, alias, useNode, normalize = (n
         const start = match.localRange?.start.index;
         if (start === undefined)
             continue;
-        let nameNode = root;
-        for (;;) {
-            const child = nameNode.namedChildren.find((candidate) => candidate.startIndex <= start && start < candidate.endIndex);
-            if (!child)
-                break;
-            nameNode = child;
-        }
-        const scope = enclosingImportScope(nameNode);
+        const scope = importScopeAt(root, start);
         if (!scope)
             continue;
         if (start > useNode.startIndex && scope.parent)
@@ -506,7 +643,7 @@ function resolveJvmPackageExpression(index, sup, source, expr, resolveLexicalBin
     return target ? { kind: "resolved", def: target } : null;
 }
 export async function resolveMemberAccessDefinition(params) {
-    const { index, mod, node, source, tree, sup, resolveLexicalBinding } = params;
+    const { index, mod, node, source, tree, sup, resolveLexicalBinding, loadParsedFile, pythonReceiverResolutionCache } = params;
     if (sup.id === "ruby") {
         const qualified = resolveRubyQualifiedConstantDefinition(index, mod, node, source);
         if (qualified)
@@ -525,6 +662,19 @@ export async function resolveMemberAccessDefinition(params) {
     }
     if (!memberNode)
         return null;
+    if (sup.id === "csharp") {
+        const lead = csharpChainQualifier(memberNode, source);
+        const reason = lead ? csharpAliasUnprovenReason(index, mod, lead.qualifier, source) : null;
+        if (lead && reason) {
+            // A parameter, local, or member named like the alias is a value that C# binds before any alias,
+            // except after `::`, which reaches aliases only.
+            const scopeIndex = getOrBuildScopeIndex(index, mod.file, source, sup, mod, tree);
+            const closest = findClosestScopeBinding(scopeIndex, sliceText(lead.qualifier, source), lead.qualifier, sup);
+            const aliasQualified = lead.qualifier.parent?.type === "alias_qualified_name";
+            if (aliasQualified || !closest || closest.import)
+                return { status: "not_found", reason };
+        }
+    }
     const { object: obj, property: prop } = getMemberAccessParts(sup, memberNode);
     const optionalMemberTypes = memberAccessTraversalTypes(sup);
     // Only the outermost access is the callee; an inner hop (`A.B` in `A.B.C()`) is not called.
@@ -561,12 +711,7 @@ export async function resolveMemberAccessDefinition(params) {
                         return null;
                 }
                 else {
-                    imp = innermostNamespaceImport(mod.imports, exprName, expr, sup.normalizeIdentifier);
-                    if (!imp) {
-                        imp = mod.imports.find((candidate) => (candidate.kind === "named" || candidate.kind === "default") &&
-                            candidate.local === exprName &&
-                            !isExpandedStarBinding(candidate, mod.imports));
-                    }
+                    imp = csharpAliasAt(mod, exprName, expr);
                 }
             }
             else {
@@ -615,6 +760,10 @@ export async function resolveMemberAccessDefinition(params) {
                 const local = resolveExport(index, mod.file, exprName, { referenceIndex: expr.startIndex });
                 if (local)
                     return local;
+                // An explicit alias in scope binds before any type a `using N;` imports, so one that names no indexed type stays
+                // unresolved. An alias in another namespace block is not selected above and leaves the imported type to answer.
+                if (imp)
+                    return null;
             }
             else {
                 const local = mod.locals.find((candidate) => {
@@ -685,9 +834,13 @@ export async function resolveMemberAccessDefinition(params) {
                 const memberName = sliceText(subProp, source);
                 // `P.Mix` in `P.Mix.M()`: when the leftmost name binds nothing, a C# dotted name is a
                 // namespace-qualified type, which qualified export lookup resolves across every file that
-                // declares the namespace.
+                // declares the namespace. An alias in scope binds the name, resolved or not, and so may a
+                // `using N;` that an enclosing namespace shadows, so neither falls back to a namespace of that name.
                 const dottedRoot = !base && sup.id === "csharp" ? csharpDottedNameRoot(expr) : null;
-                if (dottedRoot && !resolveLexicalBinding?.(dottedRoot)) {
+                if (dottedRoot &&
+                    !resolveLexicalBinding?.(dottedRoot) &&
+                    !csharpAliasAt(mod, sliceText(dottedRoot, source), dottedRoot) &&
+                    !csharpShadowedUsingReason(index, mod, dottedRoot, source)) {
                     return resolveCsharpQualifiedName(index, mod, sliceText(expr, source).replace(/\s+/gu, ""), expr.startIndex);
                 }
                 if (base?.kind === "namespace") {
@@ -768,9 +921,12 @@ export async function resolveMemberAccessDefinition(params) {
             return null;
         })
         : null;
+    const pythonInstanceReceiver = sup.id === "python" &&
+        ((receiverProof?.kind === "own-type" && obj?.type === "identifier" && sliceText(obj, source) === "self") ||
+            (receiverProof?.kind === "named-type" && receiverProof.proof !== "static-type"));
     const chain = await resolveExpression(memberNode);
     if (chain && prop && node.id === prop.id) {
-        if (chain.kind === "resolved") {
+        if (chain.kind === "resolved" && !pythonInstanceReceiver) {
             return okGoToResult(index, chain.def, {
                 via: { exportedName: sliceText(prop, source) },
                 resolution: "member-access",
@@ -792,7 +948,7 @@ export async function resolveMemberAccessDefinition(params) {
     if (obj && prop && node.id === prop.id && supportsReceiverMemberNavigation(sup.id)) {
         const member = sliceText(prop, source);
         if (sup.id === "python") {
-            const memberDef = await resolvePythonReceiverMember(index, mod, node, obj, member, source, sup, resolveExpression, receiverProof);
+            const memberDef = await resolvePythonReceiverMember(index, mod, node, obj, member, source, sup, resolveExpression, receiverProof, loadParsedFile, pythonReceiverResolutionCache);
             if (!memberDef)
                 return null;
             return okGoToResult(index, memberDef, {
@@ -962,10 +1118,6 @@ export async function resolveMemberAccessDefinition(params) {
 function findEnclosingClassContainer(node) {
     return nearestMemberContainer(node);
 }
-function keywordClassKey(def) {
-    const start = def.range.start;
-    return `${fileIdentityKey(def.file)}:${start.index ?? `${start.line}:${start.column}`}`;
-}
 function keywordContainerKey(file, container) {
     return `${fileIdentityKey(file)}:${container.startIndex}:${container.endIndex}`;
 }
@@ -1378,7 +1530,7 @@ function crossFilePeerMemberHidden(useFile, memberDef, targetContext) {
     if (languageId !== "java" && languageId !== "kotlin" && languageId !== "swift")
         return false;
     const start = memberDef.range.start;
-    const position = { row: Math.max(0, start.line - 1), column: Math.max(0, start.column - 1) };
+    const position = toTreeSitterPosition(start);
     const nameNode = targetContext.tree.rootNode.descendantForPosition(position, position);
     if (!nameNode)
         return false;
@@ -1428,7 +1580,7 @@ async function baseRefsFromContainer(index, mod, container, source, sup, supercl
         // unresolved, while an own receiver can inherit their default members.
         if (superclassOnly && sup.id === "kotlin" && !base.invoked)
             continue;
-        const key = keywordClassKey(def);
+        const key = definitionIdentityKey(def);
         if (seen.has(key))
             continue;
         seen.add(key);
@@ -2340,11 +2492,11 @@ function receiverMemberAcceptsArgumentCount(index, def, argumentCount) {
 /** Indexed owner membership and callable facts for direct and merged-owner lookup. */
 function indexedMemberModel(index, members, languageId) {
     return {
-        ownerKey: keywordClassKey,
+        ownerKey: definitionIdentityKey,
         members: () => members,
         supertypes: () => [],
         name: (def) => def.localName,
-        key: (def) => def.callable?.key ?? keywordClassKey(def),
+        key: (def) => def.callable?.key ?? definitionIdentityKey(def),
         callable: (def) => {
             const facts = def.callable ??
                 index.byFile
@@ -2600,7 +2752,7 @@ async function selectRustReceiverMember(index, receiverDef, member, context, loc
         const ref = await keywordClassRefFromDef(index, traitDef);
         if (!ref || ref.container.type !== "trait_item")
             continue;
-        const key = keywordClassKey(traitDef);
+        const key = definitionIdentityKey(traitDef);
         if (traitMembers.has(key))
             continue;
         const matches = [];
@@ -2625,7 +2777,7 @@ async function selectRustReceiverMember(index, receiverDef, member, context, loc
             return owner === "implemented" ? traitOwners : [];
         },
         name: (def) => context.sup.normalizeIdentifier(def.localName),
-        key: (def) => def.callable?.key ?? keywordClassKey(def),
+        key: (def) => def.callable?.key ?? definitionIdentityKey(def),
         callable: (def) => def.callable,
         scope: () => "any",
         visible: () => true,
@@ -2785,7 +2937,7 @@ async function selectGoReceiverMember(index, receiverDef, member, normalizeIdent
         members: (owner) => members.get(owner) ?? [],
         supertypes: (owner) => embedded.get(owner) ?? [],
         name: (def) => normalizeIdentifier(def.localName),
-        key: (def) => def.callable?.key ?? keywordClassKey(def),
+        key: (def) => def.callable?.key ?? definitionIdentityKey(def),
         callable: (def) => def.callable,
         scope: () => "any",
         visible: () => true,
@@ -2799,17 +2951,16 @@ async function selectGoReceiverMember(index, receiverDef, member, normalizeIdent
     });
     return selected.status === "unique" ? selected.member : undefined;
 }
-function pythonClassKey(def) {
-    const start = def.range.start;
-    return `${fileIdentityKey(def.file)}:${start.index ?? `${start.line}:${start.column}`}`;
+export function createPythonReceiverResolutionCache() {
+    return { classRefs: new Map(), members: new Map() };
 }
-async function resolvePythonReceiverMember(index, mod, node, obj, member, source, sup, resolveExpression, proof) {
-    const classRef = await pythonReceiverClassRef(index, mod, node, obj, source, sup, resolveExpression, proof);
+async function resolvePythonReceiverMember(index, mod, node, obj, member, source, sup, resolveExpression, proof, loadParsedFile, cache) {
+    const classRef = await pythonReceiverClassRef(index, mod, node, obj, source, sup, resolveExpression, proof, loadParsedFile, cache);
     if (!classRef)
         return undefined;
-    return lookupPythonClassMember(index, classRef.ref, member, classRef.startAtSupertype);
+    return lookupPythonClassMember(index, classRef.ref, member, classRef.startAtSupertype, classRef.preferInstanceAttributes, loadParsedFile, cache);
 }
-async function pythonReceiverClassRef(index, mod, node, obj, source, sup, resolveExpression, proof) {
+async function pythonReceiverClassRef(index, mod, node, obj, source, sup, resolveExpression, proof, loadParsedFile, cache) {
     const receiver = proof ?? classifyReceiver(sup, obj, source, null, 0, obj.parent ?? obj, noLexicalBinding);
     if (receiver.kind === "own-type" || receiver.kind === "supertype") {
         const container = findEnclosingClassContainer(node);
@@ -2831,11 +2982,13 @@ async function pythonReceiverClassRef(index, mod, node, obj, source, sup, resolv
         });
         if (!def)
             return null;
-        const ref = await pythonClassRefFromDef(index, def);
-        return ref ? { ref, startAtSupertype: receiver.kind === "supertype" } : null;
+        const ref = await pythonClassRefFromDef(index, def, loadParsedFile, cache);
+        const preferInstanceAttributes = receiver.kind === "own-type" && sliceText(obj, source) === "self";
+        return ref ? { ref, startAtSupertype: receiver.kind === "supertype", preferInstanceAttributes } : null;
     }
     let classDef;
     const constructor = receiver.kind === "named-type" && receiver.proof !== "static-type" ? receiver.typeNode : null;
+    const preferInstanceAttributes = receiver.kind === "named-type" && receiver.proof !== "static-type";
     if (constructor) {
         const result = await resolveExpression(constructor);
         if (result?.kind === "resolved" && result.def.kind === SymbolKind.Class) {
@@ -2850,35 +3003,140 @@ async function pythonReceiverClassRef(index, mod, node, obj, source, sup, resolv
     }
     if (!classDef)
         return null;
-    const ref = await pythonClassRefFromDef(index, classDef);
-    return ref ? { ref, startAtSupertype: false } : null;
+    const ref = await pythonClassRefFromDef(index, classDef, loadParsedFile, cache);
+    return ref ? { ref, startAtSupertype: false, preferInstanceAttributes } : null;
 }
-async function pythonClassRefFromDef(index, def) {
-    const module = index.byFile.get(fileIdentityKey(def.file));
-    if (!module)
-        return null;
-    const context = await ensureParsedContext(def.file, undefined, index.languageExtensions);
-    const start = def.range.start;
-    const position = {
-        row: start.line - 1,
-        column: start.column - 1,
-    };
-    let current = context.tree.rootNode.descendantForPosition(position, position);
-    while (current && current.type !== "class_definition") {
-        current = current.parent;
-    }
-    if (!current)
-        return null;
-    return { def, container: current, context, module };
+async function pythonClassRefFromDef(index, def, loadParsedFile, cache) {
+    const key = definitionIdentityKey(def);
+    const cached = cache?.classRefs.get(key);
+    if (cached)
+        return cached;
+    const pending = (async () => {
+        const module = index.byFile.get(fileIdentityKey(def.file));
+        if (!module)
+            return null;
+        const context = loadParsedFile
+            ? await loadParsedFile(def.file)
+            : await ensureParsedContext(def.file, undefined, index.languageExtensions);
+        if (!context || context.sup.id !== "python")
+            return null;
+        const start = def.range.start;
+        const position = {
+            row: start.line - 1,
+            column: start.column - 1,
+        };
+        let current = context.tree.rootNode.descendantForPosition(position, position);
+        while (current && current.type !== "class_definition") {
+            current = current.parent;
+        }
+        if (!current)
+            return null;
+        return { def, container: current, context, module };
+    })();
+    cache?.classRefs.set(key, pending);
+    return pending;
+}
+/** Whether `nameNode` names a class-level annotation without a value (`count: int`), which declares a type and binds nothing. */
+function isPythonValuelessAnnotation(nameNode) {
+    const assignment = nameNode.parent;
+    return (assignment?.type === "assignment" &&
+        assignment.childForFieldName("left")?.id === nameNode.id &&
+        !assignment.childForFieldName("right"));
+}
+/** The `locals` of `classRef` that bind their name in the class namespace: every one but an annotation without a value. */
+function pythonBindingLocals(classRef, locals) {
+    return locals.filter((local) => {
+        const nameNode = nameNodeForDef(classRef.context, local);
+        return !nameNode || !isPythonValuelessAnnotation(nameNode);
+    });
 }
-function pythonMembersOnClass(classRef, member) {
+/**
+ * The members of one class named `member`. `prefer` (`self` and constructed receivers) lets a property decide first and
+ * then an instance attribute beat a class attribute of the same class; `fallback` reaches instance attributes only
+ * when the class has no class-level member.
+ */
+function pythonMembersOnClass(classRef, member, instanceAttributes = "fallback") {
     const normalizeIdentifier = classRef.context.sup.normalizeIdentifier;
-    const direct = findDirectLocalsWithinNode(classRef.module.locals, member, classRef.container, classRef.context, normalizeIdentifier);
+    let direct;
+    if (instanceAttributes === "prefer") {
+        direct = findDirectLocalsWithinNode(classRef.module.locals, member, classRef.container, classRef.context, normalizeIdentifier);
+        const propertyMembers = pythonPropertyDescriptorMembers(classRef, member, direct);
+        if (propertyMembers)
+            return propertyMembers;
+        const instanceAttributeMembers = findPythonInstanceAttributesWithinClass(classRef.module.locals, member, classRef.container, classRef.context, normalizeIdentifier, "self");
+        const selectedInstanceAttribute = preferredPythonInstanceAttribute(instanceAttributeMembers, classRef.container, classRef.context);
+        if (selectedInstanceAttribute)
+            return [selectedInstanceAttribute];
+    }
+    direct ??= findDirectLocalsWithinNode(classRef.module.locals, member, classRef.container, classRef.context, normalizeIdentifier);
     if (direct.length)
         return direct;
     return findPythonInstanceAttributesWithinClass(classRef.module.locals, member, classRef.container, classRef.context, normalizeIdentifier);
 }
-function findPythonInstanceAttributesWithinClass(locals, member, container, targetContext, normalizeIdentifier) {
+/** What a function definition does to the property `member`: the role its decorators give it, `null` for a plain one. */
+function pythonPropertyRole(decorators, member) {
+    for (const decorator of decorators) {
+        if (decorator?.kind === "property")
+            return "getter";
+        if (decorator?.kind === "accessor" && decorator.propertyName === member)
+            return decorator.accessor;
+    }
+    return null;
+}
+/**
+ * What the class-level binding that `nameNode` names does to the property `member` holds: `property` makes a new one whose
+ * getter is the binding (`property(...)`, `@property`, a replacing `@member.getter`), `update` changes the one an
+ * earlier binding made (`@member.setter`, `@member.deleter`), `plain` replaces it with something else, and `annotation`
+ * (`member: int`) binds nothing.
+ */
+function pythonPropertyBinding(classRef, nameNode, member) {
+    if (isPythonValuelessAnnotation(nameNode))
+        return "annotation";
+    const assignment = nameNode.parent;
+    if (assignment?.type === "assignment" && assignment.childForFieldName("left")?.id === nameNode.id) {
+        const value = assignment.childForFieldName("right");
+        const callee = value?.type === "call" ? value.childForFieldName("function") : null;
+        const argumentsNode = value?.childForFieldName("arguments");
+        return callee?.text === "property" && (argumentsNode?.namedChildren.length ?? 0) >= 1 ? "property" : "plain";
+    }
+    let functionNode = nameNode;
+    while (functionNode && functionNode.id !== classRef.container.id && functionNode.type !== "function_definition") {
+        functionNode = functionNode.parent;
+    }
+    const decorated = functionNode?.type === "function_definition" ? functionNode.parent : null;
+    const decorators = decorated?.type === "decorated_definition"
+        ? decorated.namedChildren.filter((child) => child.type === "decorator")
+        : [];
+    const role = pythonPropertyRole(decorators.map(pythonPropertyDecorator), member);
+    if (role === "getter")
+        return "property";
+    return role ? "update" : "plain";
+}
+/**
+ * The property descriptor that `member` is in `classRef`, or `null` when it is not one. The class-level bindings of the
+ * name run in source order and the last one decides what the name holds: `property(...)`, `@property`, and a replacing
+ * `@member.getter` each make a new property whose getter is that definition, `@member.setter` and `@member.deleter` keep
+ * the property an earlier binding made, so its getter stays the target, and any other binding replaces the property
+ * (`count = 0` after `@property def count`). An annotation without a value binds nothing.
+ */
+function pythonPropertyDescriptorMembers(classRef, member, directMembers) {
+    let descriptor;
+    const inSourceOrder = [...directMembers].sort((left, right) => (left.range.start.index ?? 0) - (right.range.start.index ?? 0));
+    for (const local of inSourceOrder) {
+        const nameNode = nameNodeForDef(classRef.context, local);
+        if (!nameNode)
+            continue;
+        const binding = pythonPropertyBinding(classRef, nameNode, member);
+        if (binding === "property")
+            descriptor = local;
+        else if (binding === "update")
+            descriptor ??= local;
+        else if (binding === "plain")
+            descriptor = undefined;
+    }
+    return descriptor ? [descriptor] : null;
+}
+function findPythonInstanceAttributesWithinClass(locals, member, container, targetContext, normalizeIdentifier, receiver) {
     const matches = [];
     const containerStart = container.startIndex;
     const containerEnd = container.endIndex;
@@ -2899,11 +3157,61 @@ function findPythonInstanceAttributesWithinClass(locals, member, container, targ
             column: start.column - 1,
         };
         const nameNode = targetContext.tree.rootNode.descendantForPosition(position, position);
-        if (isPythonReceiverAttributeAssignmentName(nameNode))
-            matches.push(local);
+        if (!isPythonReceiverAttributeAssignmentName(nameNode))
+            continue;
+        const object = nameNode.parent?.childForFieldName("object");
+        if (receiver && object?.text !== receiver)
+            continue;
+        matches.push(local);
     }
     return matches;
 }
+function preferredPythonInstanceAttribute(attributes, container, context) {
+    let firstMethodAssignment;
+    let firstMethodStartIndex;
+    let initializerAssignment;
+    let initializerStartIndex;
+    for (const attribute of attributes) {
+        const startIndex = attribute.range.start.index;
+        if (startIndex === undefined)
+            continue;
+        const start = attribute.range.start;
+        const position = {
+            row: start.line - 1,
+            column: start.column - 1,
+        };
+        let current = context.tree.rootNode.descendantForPosition(position, position);
+        let method = null;
+        let invalidMethodScope = false;
+        while (current && current.id !== container.id) {
+            if (current.type === "class_definition") {
+                invalidMethodScope = true;
+                break;
+            }
+            if (current.type === "function_definition") {
+                if (method) {
+                    invalidMethodScope = true;
+                    break;
+                }
+                method = current;
+            }
+            current = current.parent;
+        }
+        if (invalidMethodScope || current?.id !== container.id || !method)
+            continue;
+        if (firstMethodStartIndex === undefined || startIndex < firstMethodStartIndex) {
+            firstMethodAssignment = attribute;
+            firstMethodStartIndex = startIndex;
+        }
+        if (method.childForFieldName("name")?.text !== "__init__")
+            continue;
+        if (initializerStartIndex === undefined || startIndex < initializerStartIndex) {
+            initializerAssignment = attribute;
+            initializerStartIndex = startIndex;
+        }
+    }
+    return initializerAssignment ?? firstMethodAssignment;
+}
 function pythonBaseIdentifierNodes(classNode) {
     const bases = classNode.childForFieldName("superclasses") ??
         (classNode.namedChildren ?? []).find((child) => child.type === "argument_list");
@@ -2953,7 +3261,7 @@ function resolvePythonNamedClass(index, mod, name) {
         return exported.def;
     return undefined;
 }
-async function pythonBaseClassRefs(index, classRef) {
+async function pythonBaseClassRefs(index, classRef, loadParsedFile, cache) {
     const names = pythonBaseIdentifierNodes(classRef.container);
     const refs = [];
     const seen = new Set();
@@ -2961,26 +3269,112 @@ async function pythonBaseClassRefs(index, classRef) {
         const def = resolvePythonNamedClass(index, classRef.module, sliceText(nameNode, classRef.context.source));
         if (!def)
             continue;
-        const key = pythonClassKey(def);
+        const key = definitionIdentityKey(def);
         if (seen.has(key))
             continue;
         seen.add(key);
-        const ref = await pythonClassRefFromDef(index, def);
+        const ref = await pythonClassRefFromDef(index, def, loadParsedFile, cache);
         if (ref)
             refs.push(ref);
     }
     return refs;
 }
-async function lookupPythonClassMember(index, start, member, startAtSupertype = false) {
+/**
+ * What decides `self.member` in `start`'s hierarchy: `property` when the first class that binds `member` at class level
+ * binds a property, `attribute` when it binds anything else or no class binds it, and `unproven` when the method
+ * resolution order would have to say. An annotation without a value (`member: int`) binds nothing. Python gives a
+ * property (a data descriptor) precedence over the instance dictionary, so `self.member = value` writes through it
+ * instead of declaring an attribute, while a plain class-level binding found first leaves the instance attribute in
+ * charge. Along one chain of single bases the nearest binding is first. With several bases the order is not rebuilt: a
+ * subclass always comes before its bases, so a binding class that no other binding class derives from comes first when
+ * it is the only one, and with several of them it is not proven which does. A property is first only as that one class,
+ * wherever it sits in the hierarchy, and it is the one whose getter answers.
+ */
+async function pythonPropertyPrecedence(index, start, member, loadParsedFile, cache) {
+    // The classes that bind `member`, each with the property its bindings make, or `null` when they make none.
+    const declarations = new Map();
+    const baseKeys = new Map();
+    const visited = new Set([definitionIdentityKey(start.def)]);
+    let level = [start];
+    let singleChain = true;
+    for (let depth = 0; depth < RECEIVER_HIERARCHY_DEPTH && level.length; depth += 1) {
+        if (level.length > 1)
+            singleChain = false;
+        const next = [];
+        for (const ref of level) {
+            const key = definitionIdentityKey(ref.def);
+            const bindings = pythonBindingLocals(ref, findDirectLocalsWithinNode(ref.module.locals, member, ref.container, ref.context, ref.context.sup.normalizeIdentifier));
+            if (bindings.length)
+                declarations.set(key, pythonPropertyDescriptorMembers(ref, member, bindings)?.[0] ?? null);
+            const bases = await pythonBaseClassRefs(index, ref, loadParsedFile, cache);
+            baseKeys.set(key, bases.map((base) => definitionIdentityKey(base.def)));
+            for (const base of bases) {
+                const baseKey = definitionIdentityKey(base.def);
+                if (visited.has(baseKey))
+                    continue;
+                visited.add(baseKey);
+                next.push(base);
+            }
+        }
+        // On one chain of single bases the nearest declaration is first, so the walk ends at it.
+        if (singleChain && declarations.size)
+            break;
+        level = next;
+    }
+    if (!declarations.size)
+        return { kind: "attribute" };
+    // A declaring class that another declaring class extends comes later in every order, so only the others can be first.
+    const dominated = new Set();
+    for (const declaring of declarations.keys()) {
+        const seen = new Set();
+        const pending = [...(baseKeys.get(declaring) ?? [])];
+        while (pending.length) {
+            const ancestor = pending.pop();
+            if (seen.has(ancestor))
+                continue;
+            seen.add(ancestor);
+            if (declarations.has(ancestor))
+                dominated.add(ancestor);
+            pending.push(...(baseKeys.get(ancestor) ?? []));
+        }
+    }
+    const nearest = [...declarations].filter(([key]) => !dominated.has(key)).map(([, getter]) => getter);
+    if (!nearest.length)
+        return { kind: "unproven" };
+    if (nearest.every((getter) => !getter))
+        return { kind: "attribute" };
+    const [getter] = nearest;
+    return nearest.length === 1 && getter ? { kind: "property", getter } : { kind: "unproven" };
+}
+async function lookupPythonClassMember(index, start, member, startAtSupertype = false, preferInstanceAttributes = false, loadParsedFile, cache) {
+    const key = `${definitionIdentityKey(start.def)}:${member}:${startAtSupertype}:${preferInstanceAttributes}`;
+    const cached = cache?.members.get(key);
+    if (cached)
+        return cached;
+    const pending = lookupPythonClassMemberUncached(index, start, member, startAtSupertype, preferInstanceAttributes, loadParsedFile, cache);
+    cache?.members.set(key, pending);
+    return pending;
+}
+async function lookupPythonClassMemberUncached(index, start, member, startAtSupertype, preferInstanceAttributes, loadParsedFile, cache) {
+    const instanceAttributes = preferInstanceAttributes ? "prefer" : "fallback";
+    if (preferInstanceAttributes) {
+        // An inherited property takes the write `self.x = value` and the read after it, so no instance attribute shadows it,
+        // and the class that binds it first answers, whichever level of the hierarchy it sits on.
+        const precedence = await pythonPropertyPrecedence(index, start, member, loadParsedFile, cache);
+        if (precedence.kind === "unproven")
+            return undefined;
+        if (precedence.kind === "property")
+            return precedence.getter;
+    }
     const membersByOwner = new Map();
     const parentsByOwner = new Map();
-    const visited = new Set([pythonClassKey(start.def)]);
+    const visited = new Set([definitionIdentityKey(start.def)]);
     let level = [start];
     for (let depth = 0; depth < RECEIVER_HIERARCHY_DEPTH && level.length; depth += 1) {
         let named = false;
         for (const ref of level) {
-            const members = startAtSupertype && !depth ? [] : pythonMembersOnClass(ref, member);
-            membersByOwner.set(pythonClassKey(ref.def), members);
+            const members = startAtSupertype && !depth ? [] : pythonMembersOnClass(ref, member, instanceAttributes);
+            membersByOwner.set(definitionIdentityKey(ref.def), members);
             if (members.length)
                 named = true;
         }
@@ -2988,10 +3382,10 @@ async function lookupPythonClassMember(index, start, member, startAtSupertype =
             break;
         const next = [];
         for (const ref of level) {
-            const parents = await pythonBaseClassRefs(index, ref);
-            parentsByOwner.set(pythonClassKey(ref.def), parents);
+            const parents = await pythonBaseClassRefs(index, ref, loadParsedFile, cache);
+            parentsByOwner.set(definitionIdentityKey(ref.def), parents);
             for (const parent of parents) {
-                const key = pythonClassKey(parent.def);
+                const key = definitionIdentityKey(parent.def);
                 if (visited.has(key))
                     continue;
                 visited.add(key);
@@ -3001,11 +3395,11 @@ async function lookupPythonClassMember(index, start, member, startAtSupertype =
         level = next;
     }
     const model = {
-        ownerKey: (ref) => pythonClassKey(ref.def),
-        members: (ref) => membersByOwner.get(pythonClassKey(ref.def)) ?? [],
-        supertypes: (ref) => parentsByOwner.get(pythonClassKey(ref.def)) ?? [],
+        ownerKey: (ref) => definitionIdentityKey(ref.def),
+        members: (ref) => membersByOwner.get(definitionIdentityKey(ref.def)) ?? [],
+        supertypes: (ref) => parentsByOwner.get(definitionIdentityKey(ref.def)) ?? [],
         name: (def) => def.localName,
-        key: (def) => def.callable?.key ?? pythonClassKey(def),
+        key: (def) => def.callable?.key ?? definitionIdentityKey(def),
         callable: (def) => def.callable,
         scope: () => "any",
         visible: () => true,