ucn 5.2.1 → 5.3.0

package/languages/python.js

@@ -408,6 +408,24 @@ function pythonAliasBase(node) {
     return base ? (PY_ALIAS_RUNTIME_TYPES.get(base) || base) : null;
 }
 
+function pythonAliasMembers(node) {
+    const current = unwrapTypeNode(node);
+    if (!current) return [];
+    if (current.type === 'binary_operator' && current.text.includes('|')) {
+        return [...new Set([
+            ...pythonAliasMembers(current.namedChild(0)),
+            ...pythonAliasMembers(current.namedChild(1)),
+        ])];
+    }
+    if (current.type === 'subscript' || current.type === 'generic_type') {
+        const parts = genericTypeParts(current);
+        if (!parts || !['Union', 'Optional'].includes(parts.base)) return [];
+        return [...new Set(parts.args.flatMap(pythonAliasMembers))];
+    }
+    const name = typeNameFromExpr(current);
+    return name && name !== 'None' ? [name] : [];
+}
+
 /**
  * Python type aliases: PEP 695 `type X = int`, annotated
  * `X: TypeAlias = ...`, and module-scope static aliases such as
@@ -448,6 +466,7 @@ function _processTypeAlias(node, classes, processedRanges, lines) {
     processedRanges.add(rangeKey);
     const { startLine, endLine } = nodeToLocation(node, lines);
     const aliasOf = pythonAliasBase(valueNode);
+    const aliasMembers = pythonAliasMembers(valueNode);
     classes.push({
         name,
         type: 'type',
@@ -456,6 +475,7 @@ function _processTypeAlias(node, classes, processedRanges, lines) {
         methods: [],
         members: [],
         ...(aliasOf && { aliasOf }),
+        ...(aliasMembers.length > 1 && { aliasMembers }),
     });
     return true;
 }
@@ -969,8 +989,30 @@ function isinstanceTypes(condition, receiverName) {
 function narrowedReceiverType(refNode, receiverName, declaredUnion) {
     for (let current = refNode; current?.parent; current = current.parent) {
         const parent = current.parent;
-        if (parent.type === 'if_statement') {
+        if (parent.type === 'if_statement' || parent.type === 'elif_clause') {
             const condition = parent.childForFieldName('condition');
+            const noneIdentity = condition?.type === 'comparison_operator' &&
+                condition.namedChildCount === 2 &&
+                condition.children.find(child =>
+                    child.type === 'is' || child.type === 'is not');
+            const noneIndex = noneIdentity
+                ? [condition.namedChild(0), condition.namedChild(1)]
+                    .findIndex(child => child?.type === 'none')
+                : -1;
+            const compared = noneIndex >= 0
+                ? condition.namedChild(1 - noneIndex) : null;
+            if (compared?.type === 'identifier' &&
+                compared.text === receiverName && declaredUnion?.length) {
+                const remaining = declaredUnion.filter(type => type !== 'None');
+                const consequence = parent.childForFieldName('consequence');
+                const alternative = parent.childForFieldName('alternative');
+                const inNonNullBranch = noneIdentity.type === 'is not'
+                    ? nodeContains(consequence, refNode)
+                    : nodeContains(alternative, refNode);
+                if (inNonNullBranch && remaining.length === 1) {
+                    return remaining[0];
+                }
+            }
             const positive = isinstanceTypes(condition, receiverName);
             if (positive.length === 0) continue;
             const consequence = parent.childForFieldName('consequence');
@@ -1122,18 +1164,21 @@ function contextTargetOf(callNode) {
  * pkg.ClassName(...).  Preserve the qualifier: dropping `threading` from
  * `threading.Thread()` turns an external class into an unqualified project
  * type name and can falsely confirm `thread.join()` against Project.join.
- * Uppercase-first remains a Python class-naming heuristic, so callers use the
- * qualifier as routing/provenance evidence rather than a hidden hard claim.
+ * PascalCase after optional privacy underscores remains a Python class-naming
+ * heuristic, so callers use the qualifier as routing/provenance evidence
+ * rather than a hidden hard claim. Private classes such as `_ClassBuilder`
+ * are ordinary constructor values and must retain their type identity.
  */
 function constructorTypeInfo(funcNode) {
     if (!funcNode) return undefined;
     if (funcNode.type === 'identifier') {
-        return /^[A-Z]/.test(funcNode.text) ? { type: funcNode.text } : undefined;
+        return /^_*[A-Z]/.test(funcNode.text)
+            ? { type: funcNode.text } : undefined;
     }
     if (funcNode.type === 'attribute') {
         const attr = funcNode.childForFieldName('attribute');
         const object = funcNode.childForFieldName('object');
-        return attr && /^[A-Z]/.test(attr.text)
+        return attr && /^_*[A-Z]/.test(attr.text)
             ? { type: attr.text, qualifier: object?.text || undefined }
             : undefined;
     }
@@ -1307,11 +1352,73 @@ const PY_COMPREHENSIONS = new Set([
     'dictionary_comprehension',
 ]);
 
+// Whether this reference is evaluated with `name` bound by an enclosing
+// for/comprehension target. Keep the check lexical: a nested function has its
+// own scope, and the iterable expression of `for x in source(x)` sees the
+// outer x rather than the new loop binding.
+function isPythonIterationBindingAt(refNode, name) {
+    for (let parent = refNode?.parent; parent; parent = parent.parent) {
+        if (parent.type === 'for_statement' &&
+            pythonTargetBindsName(parent.childForFieldName('left'), name)) {
+            const body = parent.childForFieldName('body');
+            if (nodeContains(body, refNode)) return true;
+        }
+        if (PY_COMPREHENSIONS.has(parent.type)) {
+            for (let i = 0; i < parent.namedChildCount; i++) {
+                const clause = parent.namedChild(i);
+                if (clause.type !== 'for_in_clause' ||
+                    !pythonTargetBindsName(
+                        clause.childForFieldName('left'), name)) continue;
+                const iterable = clause.childForFieldName('right');
+                if (!nodeContains(iterable, refNode)) return true;
+            }
+        }
+        if (parent.type === 'function_definition' ||
+            parent.type === 'async_function_definition' ||
+            parent.type === 'lambda') break;
+    }
+    return false;
+}
+
+// Stronger subset used for dispatch tiering: an element drawn from an
+// identifier/attribute iterable has unknown provenance. Direct call
+// producers are handled separately by assignedIter flow: external calls
+// demote there, while a project-internal producer intentionally keeps the
+// measured single-owner rule (#294's counter-probe).
+function isPythonUnprovenIterationBindingAt(refNode, name) {
+    for (let parent = refNode?.parent; parent; parent = parent.parent) {
+        if (parent.type === 'for_statement' &&
+            pythonTargetBindsName(parent.childForFieldName('left'), name)) {
+            const body = parent.childForFieldName('body');
+            if (nodeContains(body, refNode)) {
+                return unwrapTypeNode(parent.childForFieldName('right'))?.type !== 'call';
+            }
+        }
+        if (PY_COMPREHENSIONS.has(parent.type)) {
+            for (let i = 0; i < parent.namedChildCount; i++) {
+                const clause = parent.namedChild(i);
+                if (clause.type !== 'for_in_clause' ||
+                    !pythonTargetBindsName(
+                        clause.childForFieldName('left'), name)) continue;
+                const iterable = clause.childForFieldName('right');
+                if (!nodeContains(iterable, refNode)) {
+                    return unwrapTypeNode(iterable)?.type !== 'call';
+                }
+            }
+        }
+        if (parent.type === 'function_definition' ||
+            parent.type === 'async_function_definition' ||
+            parent.type === 'lambda') break;
+    }
+    return false;
+}
+
 // Python locals are function-scoped: an assignment anywhere in the function
 // shadows an imported module for every reference in that function. Keep this
 // shared between call records and reference records so plan cannot promote a
 // receiver that callers would reject as locally rebound.
 function isPythonNameShadowedAt(refNode, name) {
+    if (isPythonIterationBindingAt(refNode, name)) return true;
     for (let parent = refNode.parent; parent; parent = parent.parent) {
         if (PY_COMPREHENSIONS.has(parent.type)) {
             for (let i = 0; i < parent.namedChildCount; i++) {
@@ -1526,14 +1633,20 @@ function findCallsInCode(code, parser) {
     });
     const functionStack = [];  // Stack of { name, startLine, endLine }
     const aliases = new Map();  // Track local aliases: aliasName -> originalName
+    const aliasesStack = [];
     const nonCallableNames = new Set();  // Track names assigned non-callable values
+    const nonCallableNamesStack = [];
     const localVarTypes = new Map();  // Track local variable types: varName -> typeName (for receiverType inference)
     const declaredVarTypes = new Map(); // Compiler-checked annotations survive later assignments
     const localVarTypeQualifiers = new Map(); // varName -> imported module alias that owns the inferred type
-    const localVarUnionTypes = new Map(); // varName -> concrete PEP 604 alternatives
+    // varName -> concrete union alternatives. `None` is retained only for a
+    // complete constructor/nullable branch join so a later identity guard can
+    // narrow it without typing unguarded calls.
+    const localVarUnionTypes = new Map();
     const localIterableTypes = new Map(); // iterable binding -> loop-variable types
     const localIterationSources = new Map(); // loop variable -> declared iterable path + tuple index
     const localDictValueTypes = new Map(); // local dict -> exact string-key value types
+    const localSubscriptSources = new Map(); // local value -> exact typed container selected by []
     const localVarStdlibContracts = new Map(); // variable -> stdlib module proving its type flow
     const assignmentRhsReceiverTypes = new Map(); // call-node id -> pre-assignment receiver type
     const constructedReceiverVars = new Set(); // exact constructor-result bindings
@@ -1547,7 +1660,14 @@ function findCallsInCode(code, parser) {
     // rewritten call is then receiver-blind and routes through dispatch tiering.
     const memberAliases = new Map();
     const memberAliasesStack = [];  // function-scoped save/restore, like localVarTypes
+    // Exact class-value aliases: `_Segment = Segment` makes later
+    // `_Segment.line()` dispatch through the imported/local class object.
+    // Keep this separate from callable aliases: receiver evidence must be
+    // scope-local, position-aware, and invalidated by every later write.
+    const classValueAliases = new Map();
+    const classValueAliasesStack = [];
     const moduleAliases = new Set();  // Names bound to MODULES (import httpx / import numpy as np)
+    const moduleImportSpecifiers = new Set(); // Exact dotted imports: import rich.repr
     const localVarTypesStack = [];  // Stack for function-scoped save/restore of localVarTypes
     const declaredVarTypesStack = [];
     const localVarTypeQualifiersStack = [];
@@ -1555,6 +1675,7 @@ function findCallsInCode(code, parser) {
     const localIterableTypesStack = [];
     const localIterationSourcesStack = [];
     const localDictValueTypesStack = [];
+    const localSubscriptSourcesStack = [];
     const localVarStdlibContractsStack = [];
     const constructedReceiverVarsStack = [];
     const withBindingVarsStack = [];
@@ -1644,6 +1765,33 @@ function findCallsInCode(code, parser) {
     };
 
     const isShadowedByLocal = isPythonNameShadowedAt;
+    const isDirectScopeAssignment = assignment => {
+        const statement = assignment?.parent?.type === 'expression_statement'
+            ? assignment.parent : assignment;
+        const parent = statement?.parent;
+        if (parent?.type === 'module') return true;
+        if (parent?.type !== 'block') return false;
+        return ['function_definition', 'async_function_definition']
+            .includes(parent.parent?.type);
+    };
+    const functionParameterBindsName = (functionNode, name) => {
+        const params = functionNode?.childForFieldName('parameters');
+        if (!params) return false;
+        for (let i = 0; i < params.namedChildCount; i++) {
+            const param = params.namedChild(i);
+            let paramName = param.type === 'identifier'
+                ? param
+                : (param.childForFieldName('name') || param.namedChild(0));
+            if (paramName && ['dictionary_splat_pattern', 'list_splat_pattern']
+                .includes(paramName.type)) {
+                paramName = paramName.namedChild(0);
+            }
+            if (paramName?.type === 'identifier' && paramName.text === name) {
+                return true;
+            }
+        }
+        return false;
+    };
     const exactConstructorInfo = funcNode => {
         const ctor = constructorTypeInfo(funcNode);
         if (!ctor) return undefined;
@@ -1660,6 +1808,194 @@ function findCallsInCode(code, parser) {
         return moduleAliases.has(root) && !isShadowedByLocal(funcNode, root)
             ? ctor : undefined;
     };
+    // Compiler-stable two-branch join (#330):
+    //   if value is not None and not isinstance(value, T): out = T(value)
+    //   else: out = value
+    // The result is T | None. Require one direct assignment per branch and
+    // exactly the two proving conjuncts; extra control flow must abstain.
+    const nullableBranchJoinType = (assignment, targetName, source) => {
+        if (!assignment || !source ||
+            !['identifier', 'attribute'].includes(source.type)) return null;
+        const block = assignment.parent?.parent;
+        const elseClause = block?.parent;
+        const statement = elseClause?.parent;
+        if (block?.type !== 'block' || block.namedChildCount !== 1 ||
+            elseClause?.type !== 'else_clause' ||
+            statement?.type !== 'if_statement') return null;
+
+        const directAssignment = branch => {
+            if (branch?.type !== 'block' || branch.namedChildCount !== 1) {
+                return null;
+            }
+            const expression = branch.namedChild(0);
+            const candidate = expression?.type === 'expression_statement'
+                ? expression.namedChild(0) : null;
+            return candidate?.type === 'assignment' &&
+                candidate.childForFieldName('left')?.type === 'identifier' &&
+                candidate.childForFieldName('left').text === targetName
+                ? candidate.childForFieldName('right') : null;
+        };
+        const alternative = elseClause.childForFieldName('body') ||
+            elseClause.namedChild(0);
+        const alternativeRhs = directAssignment(alternative);
+        if (alternativeRhs?.id !== source.id) return null;
+
+        const condition = statement.childForFieldName('condition');
+        const andTerms = node => {
+            const isAnd = node?.type === 'boolean_operator' &&
+                node.children.some(child => child.type === 'and');
+            return isAnd
+                ? node.namedChildren.flatMap(andTerms)
+                : (node ? [node] : []);
+        };
+        const terms = andTerms(condition);
+        if (terms.length !== 2) return null;
+        const sameSource = node => node?.type === source.type &&
+            node.text === source.text;
+        const nonNull = terms.find(term => {
+            if (term.type !== 'comparison_operator' ||
+                !term.children.some(child => child.type === 'is not') ||
+                term.namedChildCount !== 2) return false;
+            const parts = [term.namedChild(0), term.namedChild(1)];
+            return parts.some(part => part?.type === 'none') &&
+                parts.some(sameSource);
+        });
+        const negativeIsinstance = terms.find(term =>
+            term.type === 'not_operator' &&
+            term.namedChild(0)?.type === 'call');
+        if (!nonNull || !negativeIsinstance) return null;
+        const check = negativeIsinstance.namedChild(0);
+        if (check.childForFieldName('function')?.type !== 'identifier' ||
+            check.childForFieldName('function').text !== 'isinstance') return null;
+        const args = check.childForFieldName('arguments');
+        if (!args || args.namedChildCount !== 2 ||
+            !sameSource(args.namedChild(0))) return null;
+        const narrowedType = typeNameFromExpr(args.namedChild(1));
+        if (!narrowedType) return null;
+
+        const consequence = statement.childForFieldName('consequence');
+        const consequenceRhs = directAssignment(consequence);
+        if (consequenceRhs?.type !== 'call') return null;
+        const constructor = exactConstructorInfo(
+            consequenceRhs.childForFieldName('function'));
+        return constructor?.type === narrowedType
+            ? [narrowedType, 'None'] : null;
+    };
+
+    // A function may legally reference a module global declared later in the
+    // file. The source-order walk cannot see that binding yet, so collect the
+    // narrow compiler-stable subset up front: one direct module assignment to
+    // a bare constructor, with no other module-scope write to the name. Keep
+    // qualified constructors out of this forward pass because their module
+    // import must itself be proven at the assignment position.
+    const moduleBindingCounts = new Map();
+    const forwardModuleConstructorCandidates = new Map();
+    const moduleTargetNames = target => {
+        if (!target) return [];
+        if (target.type === 'identifier') return [target.text];
+        if (!['tuple', 'pattern_list', 'list', 'list_pattern',
+            'tuple_pattern', 'list_splat_pattern',
+            'dictionary_splat_pattern'].includes(target.type)) return [];
+        const names = [];
+        for (let i = 0; i < target.namedChildCount; i++) {
+            names.push(...moduleTargetNames(target.namedChild(i)));
+        }
+        return names;
+    };
+    const isModuleScopeNode = node => {
+        for (let parent = node?.parent; parent; parent = parent.parent) {
+            if (parent.type === 'function_definition' ||
+                parent.type === 'class_definition' ||
+                parent.type === 'lambda') return false;
+        }
+        return true;
+    };
+    const moduleBindingNodeTypes = new Set([
+        'assignment', 'augmented_assignment', 'named_expression',
+        'for_statement', 'function_definition', 'async_function_definition',
+        'class_definition', 'import_statement', 'import_from_statement',
+        'global_statement', 'delete_statement', 'as_pattern',
+    ]);
+    let hasModuleWildcardImport = false;
+    traverseTreeCached(tree.rootNode, node => {
+        if (!moduleBindingNodeTypes.has(node.type)) return true;
+        if (node.type === 'global_statement') {
+            for (let i = 0; i < node.namedChildCount; i++) {
+                const child = node.namedChild(i);
+                if (child.type !== 'identifier') continue;
+                moduleBindingCounts.set(child.text,
+                    (moduleBindingCounts.get(child.text) || 0) + 1);
+            }
+            return true;
+        }
+        if (!isModuleScopeNode(node)) return true;
+        let names = [];
+        if (node.type === 'assignment' ||
+            node.type === 'augmented_assignment' ||
+            node.type === 'named_expression') {
+            names = moduleTargetNames(
+                node.childForFieldName('left') ||
+                node.childForFieldName('name'));
+        } else if (node.type === 'for_statement') {
+            names = moduleTargetNames(node.childForFieldName('left'));
+        } else if (node.type === 'function_definition' ||
+            node.type === 'async_function_definition' ||
+            node.type === 'class_definition') {
+            names = moduleTargetNames(node.childForFieldName('name'));
+        } else if (node.type === 'import_statement') {
+            for (let i = 0; i < node.namedChildCount; i++) {
+                const child = node.namedChild(i);
+                if (child.type === 'aliased_import') {
+                    const alias = child.childForFieldName('alias');
+                    const imported = child.childForFieldName('name');
+                    if (alias) names.push(alias.text);
+                    else if (imported) names.push(imported.text.split('.')[0]);
+                } else if (child.type === 'dotted_name') {
+                    names.push(child.text.split('.')[0]);
+                }
+            }
+        } else if (node.type === 'import_from_statement') {
+            for (let i = 0; i < node.namedChildCount; i++) {
+                const child = node.namedChild(i);
+                if (child.type === 'wildcard_import') {
+                    hasModuleWildcardImport = true;
+                } else if (child.type === 'aliased_import') {
+                    const alias = child.childForFieldName('alias');
+                    const imported = child.childForFieldName('name');
+                    if (alias) names.push(alias.text);
+                    else if (imported) names.push(imported.text.split('.').pop());
+                } else if (i > 0 && child.type === 'dotted_name') {
+                    names.push(child.text.split('.').pop());
+                }
+            }
+        } else if (node.type === 'delete_statement') {
+            for (let i = 0; i < node.namedChildCount; i++) {
+                names.push(...moduleTargetNames(node.namedChild(i)));
+            }
+        } else if (node.type === 'as_pattern') {
+            names = moduleTargetNames(
+                node.childForFieldName('alias')?.namedChild(0));
+        }
+        for (const name of names) {
+            moduleBindingCounts.set(name,
+                (moduleBindingCounts.get(name) || 0) + 1);
+        }
+        if (node.type !== 'assignment' || names.length !== 1) return true;
+        const statement = node.parent?.type === 'expression_statement'
+            ? node.parent : node;
+        if (statement.parent?.type !== 'module') return true;
+        const right = node.childForFieldName('right');
+        if (right?.type !== 'call') return true;
+        const ctor = constructorTypeInfo(right.childForFieldName('function'));
+        if (!ctor || ctor.qualifier ||
+            isPythonConstructorValueShadowedAt(
+                right.childForFieldName('function'), ctor.type)) return true;
+        forwardModuleConstructorCandidates.set(names[0], ctor);
+        return true;
+    });
+    const stableForwardModuleConstructors = new Map(
+        [...forwardModuleConstructorCandidates].filter(([name]) =>
+            !hasModuleWildcardImport && moduleBindingCounts.get(name) === 1));
 
     traverseTree(tree.rootNode, (node) => {
         // Track module-alias bindings: `import httpx` binds 'httpx' (a module),
@@ -1672,6 +2008,7 @@ function findCallsInCode(code, parser) {
                 if (child.type === 'dotted_name') {
                     const first = child.namedChild(0);
                     if (first?.type === 'identifier') moduleAliases.add(first.text);
+                    moduleImportSpecifiers.add(child.text);
                 } else if (child.type === 'aliased_import') {
                     const alias = child.childForFieldName('alias');
                     if (alias?.type === 'identifier') moduleAliases.add(alias.text);
@@ -1708,10 +2045,47 @@ function findCallsInCode(code, parser) {
             localDictValueTypesStack.push(new Map(
                 [...localDictValueTypes].map(([name, values]) =>
                     [name, new Map(values)])));
+            localSubscriptSourcesStack.push(new Map(localSubscriptSources));
             localVarStdlibContractsStack.push(new Map(localVarStdlibContracts));
             constructedReceiverVarsStack.push(new Set(constructedReceiverVars));
             withBindingVarsStack.push(new Set(withBindingVars));
             memberAliasesStack.push(new Map(memberAliases));
+            classValueAliasesStack.push(new Map(classValueAliases));
+            aliasesStack.push(new Map(aliases));
+            nonCallableNamesStack.push(new Set(nonCallableNames));
+            const body = node.childForFieldName('body');
+            for (const [name, ctor] of stableForwardModuleConstructors) {
+                if (functionParameterBindsName(node, name) ||
+                    (body && pythonScopeBindsName(body, name))) continue;
+                if (!localVarTypes.has(name)) {
+                    localVarTypes.set(name, ctor.type);
+                    constructedReceiverVars.add(name);
+                }
+            }
+            for (const name of aliases.keys()) {
+                if ((body && pythonScopeBindsName(body, name)) ||
+                    functionParameterBindsName(node, name)) {
+                    aliases.delete(name);
+                }
+            }
+            for (const name of nonCallableNames) {
+                if ((body && pythonScopeBindsName(body, name)) ||
+                    functionParameterBindsName(node, name)) {
+                    nonCallableNames.delete(name);
+                }
+            }
+            for (const name of localSubscriptSources.keys()) {
+                if ((body && pythonScopeBindsName(body, name)) ||
+                    functionParameterBindsName(node, name)) {
+                    localSubscriptSources.delete(name);
+                }
+            }
+            for (const name of classValueAliases.keys()) {
+                if ((body && pythonScopeBindsName(body, name)) ||
+                    functionParameterBindsName(node, name)) {
+                    classValueAliases.delete(name);
+                }
+            }
         }
 
         // Track parameter type annotations: def foo(x: Foo) → x is Foo
@@ -1826,6 +2200,8 @@ function findCallsInCode(code, parser) {
             const left = node.childForFieldName('left');
             const right = node.childForFieldName('right');
             if (left?.type === 'identifier') {
+                classValueAliases.delete(left.text);
+                localSubscriptSources.delete(left.text);
                 const previousType = localVarTypes.get(left.text);
                 if (previousType && right?.type === 'call') {
                     const rightFunction = right.childForFieldName('function');
@@ -1837,6 +2213,8 @@ function findCallsInCode(code, parser) {
                 }
                 // Track type annotation: x: Foo = ... → x is Foo
                 const typeNode = node.childForFieldName('type');
+                const branchJoinUnion = !typeNode
+                    ? nullableBranchJoinType(node, left.text, right) : null;
                 if (typeNode) {
                     const typeName = typeNameFromAnnotation(typeNode);
                     const unionTypes = typeNamesFromAnnotation(typeNode);
@@ -1865,6 +2243,9 @@ function findCallsInCode(code, parser) {
                     localIterationSources.delete(left.text);
                     localDictValueTypes.delete(left.text);
                     localVarStdlibContracts.delete(left.text);
+                    if (branchJoinUnion) {
+                        localVarUnionTypes.set(left.text, branchJoinUnion);
+                    }
                     // Python assignments remain constrained by a variable or
                     // parameter annotation. Constructor/literal inference is
                     // nearest-assignment only, but a declared contract is
@@ -1944,6 +2325,20 @@ function findCallsInCode(code, parser) {
                         localDictValueTypes.set(left.text, valueTypes);
                     }
                 }
+                if (!typeNode && right?.type === 'subscript') {
+                    const base = right.childForFieldName('value');
+                    if (base?.type === 'identifier' && base.text !== left.text) {
+                        const rootType = localVarTypes.get(base.text);
+                        if (rootType) {
+                            localSubscriptSources.set(left.text, {
+                                root: base.text,
+                                rootType,
+                                rootTypeQualifier:
+                                    localVarTypeQualifiers.get(base.text),
+                            });
+                        }
+                    }
+                }
                 const roundTripSource = pickleRoundTripSource(right);
                 const roundTripType = roundTripSource
                     ? localVarTypes.get(roundTripSource) : null;
@@ -1953,6 +2348,11 @@ function findCallsInCode(code, parser) {
                 }
                 if (right?.type === 'identifier') {
                     aliases.set(left.text, right.text);
+                    const classValue = !typeNode && isDirectScopeAssignment(node)
+                        ? exactConstructorInfo(right) : null;
+                    if (classValue) {
+                        classValueAliases.set(left.text, classValue.type);
+                    }
                 }
                 // Member-access alias (fix #218): append = output.append
                 else if (right?.type === 'attribute') {
@@ -2197,13 +2597,31 @@ function findCallsInCode(code, parser) {
                     // Literal receivers carry their builtin type: {}.get() can
                     // never be a project class method
                     let subscriptReceiverType;
+                    let receiverSubscriptRoot;
+                    let receiverSubscriptRootType;
+                    let receiverSubscriptRootTypeQualifier;
                     if (objNode?.type === 'subscript') {
                         const base = objNode.childForFieldName('value');
                         const key = literalStringValue(
                             objNode.childForFieldName('subscript'));
-                        if (base?.type === 'identifier' && key != null) {
-                            subscriptReceiverType =
-                                localDictValueTypes.get(base.text)?.get(key);
+                        if (base?.type === 'identifier') {
+                            receiverSubscriptRoot = base.text;
+                            receiverSubscriptRootType = localVarTypes.get(base.text);
+                            receiverSubscriptRootTypeQualifier =
+                                localVarTypeQualifiers.get(base.text);
+                            if (key != null) {
+                                subscriptReceiverType =
+                                    localDictValueTypes.get(base.text)?.get(key);
+                            }
+                        }
+                    }
+                    if (!receiverSubscriptRoot && receiver) {
+                        const source = localSubscriptSources.get(receiver);
+                        if (source) {
+                            receiverSubscriptRoot = source.root;
+                            receiverSubscriptRootType = source.rootType;
+                            receiverSubscriptRootTypeQualifier =
+                                source.rootTypeQualifier;
                         }
                     }
                     const receiverType = receiver
@@ -2212,7 +2630,8 @@ function findCallsInCode(code, parser) {
                             comprehensionReceiverType(
                                 objNode, receiver, localIterableTypes,
                                 callableIterableTypes, instanceFieldContracts) ||
-                            localVarTypes.get(receiver))
+                            localVarTypes.get(receiver) ||
+                            classValueAliases.get(receiver))
                             || assignmentRhsReceiverTypes.get(node.id)
                         : (subscriptReceiverType ||
                             (objNode ? PY_LITERAL_RECEIVER_TYPES[objNode.type] : undefined));
@@ -2246,6 +2665,13 @@ function findCallsInCode(code, parser) {
                         : undefined;
                     const receiverRootType = receiverPath
                         ? localVarTypes.get(receiverPath.root) : undefined;
+                    const dottedReceiver = receiverPath
+                        ? [receiverPath.root, ...receiverPath.fields].join('.')
+                        : null;
+                    const receiverModuleSpecifier = dottedReceiver &&
+                        moduleImportSpecifiers.has(dottedReceiver) &&
+                        !isShadowedByLocal(objNode, receiverPath.root)
+                        ? dottedReceiver : undefined;
                     // Module receiver (httpx.get()) — unless locally shadowed
                     // by a typed instance binding
                     const receiverIsModule = !!receiver && moduleAliases.has(receiver) &&
@@ -2270,8 +2696,20 @@ function findCallsInCode(code, parser) {
                         ...(receiver && constructedReceiverVars.has(receiver) && { receiverConstructed: true }),
                         ...(receiver && withBindingVars.has(receiver) && { receiverWithBinding: true }),
                         ...(receiverIsModule && { receiverIsModule: true }),
+                        ...(receiverModuleSpecifier && { receiverModuleSpecifier }),
+                        ...(receiverSubscriptRoot && { receiverSubscriptRoot }),
+                        ...(receiverSubscriptRootType && {
+                            receiverSubscriptRootType,
+                        }),
+                        ...(receiverSubscriptRootTypeQualifier && {
+                            receiverSubscriptRootTypeQualifier,
+                        }),
                         ...(receiver && objNode?.type === 'identifier' &&
                             isShadowedByLocal(objNode, receiver) && { receiverLocalBinding: true }),
+                        ...(receiver && !receiverType && objNode?.type === 'identifier' &&
+                            isPythonUnprovenIterationBindingAt(objNode, receiver) && {
+                                receiverUntypedIteration: true,
+                            }),
                         ...(receiverPath && {
                             receiverRoot: receiverPath.root,
                             receiverField: receiverPath.fields[receiverPath.fields.length - 1],
@@ -2432,6 +2870,13 @@ function findCallsInCode(code, parser) {
                         localDictValueTypes.set(name, values);
                     }
                 }
+                const savedSubscriptSources = localSubscriptSourcesStack.pop();
+                if (savedSubscriptSources) {
+                    localSubscriptSources.clear();
+                    for (const [name, source] of savedSubscriptSources) {
+                        localSubscriptSources.set(name, source);
+                    }
+                }
                 const savedStdlibContracts = localVarStdlibContractsStack.pop();
                 if (savedStdlibContracts) {
                     localVarStdlibContracts.clear();
@@ -2450,6 +2895,25 @@ function findCallsInCode(code, parser) {
                     memberAliases.clear();
                     for (const [k, v] of savedAliases) memberAliases.set(k, v);
                 }
+                const savedClassValueAliases = classValueAliasesStack.pop();
+                if (savedClassValueAliases) {
+                    classValueAliases.clear();
+                    for (const [k, v] of savedClassValueAliases) {
+                        classValueAliases.set(k, v);
+                    }
+                }
+                const savedCallableAliases = aliasesStack.pop();
+                if (savedCallableAliases) {
+                    aliases.clear();
+                    for (const [k, v] of savedCallableAliases) aliases.set(k, v);
+                }
+                const savedNonCallableNames = nonCallableNamesStack.pop();
+                if (savedNonCallableNames) {
+                    nonCallableNames.clear();
+                    for (const name of savedNonCallableNames) {
+                        nonCallableNames.add(name);
+                    }
+                }
             }
         }
     });
@@ -2472,20 +2936,123 @@ function findImportsInCode(code, parser) {
     // module initialization. Preserve that AST fact so dependency-cycle
     // reporting can distinguish an eager import loop from a deliberate lazy
     // edge without deleting either edge from the graph.
-    const isDeferredImport = (node) => {
+    // fix #338: `if TYPE_CHECKING:` (bare, `t.TYPE_CHECKING`,
+    // `typing.TYPE_CHECKING`) consequence blocks never execute at runtime —
+    // the import exists for the type checker only. Only the consequence
+    // branch is guarded: `else:` and `if not TYPE_CHECKING:` bodies DO run.
+    let typingBindings = null;
+    let typingWildcard = false;
+    const isNestedScope = node => {
+        for (let p = node.parent; p; p = p.parent) {
+            if (p.type === 'function_definition' || p.type === 'class_definition' || p.type === 'lambda') return true;
+        }
+        return false;
+    };
+    // Which local names prove a runtime-false guard, and where. A guard at
+    // module level reads the module binding: only module-level rebindings
+    // (assignments, loops, def/class names, walrus, `as` targets) and a
+    // second import of the same name can disturb it — a function parameter
+    // or a nested import lives in its own scope. A guard INSIDE a function
+    // can additionally be shadowed by that function's locals, so nested
+    // rebindings poison nested guards (conservative: any nested scope, not
+    // just the enclosing one). Same-spelled user flags/attributes can be
+    // true; only a unique `typing` binding proves the guard false.
+    const typingBindingKind = (name, guardNested) => {
+        if (!typingBindings) {
+            typingBindings = new Map();
+            const entry = local => {
+                let e = typingBindings.get(local);
+                if (!e) { e = { kind: null, imports: 0, moduleShadow: false, nestedShadow: false }; typingBindings.set(local, e); }
+                return e;
+            };
+            const shadow = (pattern, nested) => {
+                if (!pattern) return;
+                traverseTree(pattern, child => {
+                    if (child.type === 'identifier') {
+                        const e = entry(child.text);
+                        if (nested) e.nestedShadow = true; else e.moduleShadow = true;
+                    }
+                    return true;
+                });
+            };
+            traverseTree(tree.rootNode, n => {
+                const nested = isNestedScope(n);
+                if (n.type === 'import_statement' || n.type === 'import_from_statement') {
+                    if (n.namedChildren.some(item => item.type === 'wildcard_import')) typingWildcard = true;
+                    const moduleNode = n.childForFieldName('module_name');
+                    for (const item of n.namedChildren) {
+                        if (moduleNode && sameNode(moduleNode, item)) continue;
+                        const imported = item.type === 'aliased_import' ? item.childForFieldName('name')?.text : item.text;
+                        const local = item.type === 'aliased_import' ? item.childForFieldName('alias')?.text : imported?.split('.')[0];
+                        if (!local) continue;
+                        const e = entry(local);
+                        if (nested) { e.nestedShadow = true; continue; }
+                        const kind = n.type === 'import_statement'
+                            ? (imported === 'typing' ? 'module' : null)
+                            : (moduleNode?.text === 'typing' && imported === 'TYPE_CHECKING' ? 'flag' : null);
+                        e.imports++;
+                        e.kind = e.imports === 1 ? kind : null;
+                    }
+                } else if (n.type === 'assignment' || n.type === 'augmented_assignment' || n.type === 'for_statement' || n.type === 'for_in_clause') {
+                    shadow(n.childForFieldName('left'), nested);
+                } else if (n.type === 'parameters' || n.type === 'lambda_parameters') {
+                    // Parameter NAMES rebind; annotations (`x: t.Any`) and
+                    // default values are expressions that READ the outer
+                    // binding. Walking the whole subtree treated every
+                    // `t.`-annotated parameter as a rebinding of `t` and
+                    // reverted click's TYPE_CHECKING guards to eager.
+                    for (const param of n.namedChildren) {
+                        if (param.type === 'default_parameter' || param.type === 'typed_default_parameter') {
+                            shadow(param.childForFieldName('name'), true);
+                        } else if (param.type === 'typed_parameter') {
+                            shadow(param.namedChild(0), true);
+                        } else if (param.type !== 'keyword_separator' && param.type !== 'positional_separator') {
+                            shadow(param, true);
+                        }
+                    }
+                } else if (n.type === 'named_expression') shadow(n.childForFieldName('name'), nested);
+                else if (n.type === 'function_definition' || n.type === 'class_definition') shadow(n.childForFieldName('name'), nested);
+                else if (n.type === 'as_pattern') shadow(n.childForFieldName('alias'), nested);
+                return true;
+            });
+        }
+        if (typingWildcard) return null;
+        const e = typingBindings.get(name);
+        if (!e || e.imports !== 1 || e.moduleShadow) return null;
+        if (guardNested && e.nestedShadow) return null;
+        return e.kind;
+    };
+    const isTypeCheckingGuard = (condition, guardNested = true) => {
+        if (!condition) return false;
+        if (condition.type === 'parenthesized_expression') return isTypeCheckingGuard(condition.namedChild(0), guardNested);
+        if (condition.type === 'identifier') return typingBindingKind(condition.text, guardNested) === 'flag';
+        if (condition.type === 'attribute') {
+            const object = condition.childForFieldName('object');
+            return condition.childForFieldName('attribute')?.text === 'TYPE_CHECKING' &&
+                object?.type === 'identifier' && typingBindingKind(object.text, guardNested) === 'module';
+        }
+        return false;
+    };
+    const importDeferral = (node) => {
         for (let parent = node.parent; parent; parent = parent.parent) {
             if (parent.type === 'function_definition' || parent.type === 'lambda') {
-                return true;
+                return 'function-local';
+            }
+            if (parent.type === 'block' && parent.parent &&
+                (parent.parent.type === 'if_statement' || parent.parent.type === 'elif_clause') &&
+                sameNode(parent.parent.childForFieldName('consequence'), parent) &&
+                isTypeCheckingGuard(parent.parent.childForFieldName('condition'), isNestedScope(parent.parent))) {
+                return 'type-checking';
             }
         }
-        return false;
+        return null;
     };
 
     traverseTreeCached(tree.rootNode, (node) => {
         // import statement: import os, import sys as system
         if (node.type === 'import_statement') {
             const line = node.startPosition.row + 1;
-            const deferred = isDeferredImport(node);
+            const deferral = importDeferral(node);
 
             for (let i = 0; i < node.namedChildCount; i++) {
                 const child = node.namedChild(i);
@@ -2502,14 +3069,14 @@ function findImportsInCode(code, parser) {
                             names: [parts[0]],
                             type: 'import',
                             line,
-                            ...(deferred && { deferred: true })
+                            ...(deferral && { deferred: true, deferredReason: deferral })
                         });
                         imports.push({
                             module: child.text,
                             names: [],
                             type: 'import-submodule',
                             line,
-                            ...(deferred && { deferred: true })
+                            ...(deferral && { deferred: true, deferredReason: deferral })
                         });
                     } else {
                         imports.push({
@@ -2517,7 +3084,7 @@ function findImportsInCode(code, parser) {
                             names: [child.text],
                             type: 'import',
                             line,
-                            ...(deferred && { deferred: true })
+                            ...(deferral && { deferred: true, deferredReason: deferral })
                         });
                     }
                 } else if (child.type === 'aliased_import') {
@@ -2530,7 +3097,7 @@ function findImportsInCode(code, parser) {
                             names: [aliasNode ? aliasNode.text : nameNode.text.split('.').pop()],
                             type: 'import',
                             line,
-                            ...(deferred && { deferred: true })
+                            ...(deferral && { deferred: true, deferredReason: deferral })
                         });
                         if (aliasNode && aliasNode.text !== nameNode.text) {
                             if (!importAliases) importAliases = [];
@@ -2545,7 +3112,7 @@ function findImportsInCode(code, parser) {
         // from ... import statement
         if (node.type === 'import_from_statement') {
             const line = node.startPosition.row + 1;
-            const deferred = isDeferredImport(node);
+            const deferral = importDeferral(node);
             let modulePath = '';
             const names = [];
 
@@ -2579,7 +3146,7 @@ function findImportsInCode(code, parser) {
                     names,
                     type: isRelative ? 'relative' : 'from',
                     line,
-                    ...(deferred && { deferred: true })
+                    ...(deferral && { deferred: true, deferredReason: deferral })
                 });
             }
             return true;
@@ -2594,7 +3161,7 @@ function findImportsInCode(code, parser) {
                 const firstArg = argsNode.namedChild(0);
                 if ((funcName === 'importlib.import_module' || funcName === '__import__') && firstArg) {
                     const line = node.startPosition.row + 1;
-                    const deferred = isDeferredImport(node);
+                    const deferral = importDeferral(node);
                     const isLiteral = firstArg.type === 'string';
                     imports.push({
                         module: isLiteral ? firstArg.text.replace(/^['"]|['"]$/g, '') : firstArg.text,
@@ -2602,7 +3169,7 @@ function findImportsInCode(code, parser) {
                         type: 'dynamic',
                         line,
                         dynamic: !isLiteral,
-                        ...(deferred && { deferred: true })
+                        ...(deferral && { deferred: true, deferredReason: deferral })
                     });
                 }
             }
@@ -2834,6 +3401,50 @@ function findInstanceAttributeTypes(code, parser, options = {}) {
     const explicitContracts = explicitInstanceFieldContracts(tree, parser);
 
     const PRIMITIVE_TYPES = new Set(['int', 'float', 'str', 'bool', 'bytes', 'list', 'dict', 'set', 'tuple', 'None', 'Any', 'object']);
+    const conditionalFieldType = (node, parameterAlternatives) => {
+        let current = node;
+        while (current?.type === 'parenthesized_expression' &&
+            current.namedChildCount === 1) {
+            current = current.namedChild(0);
+        }
+        if (current?.type !== 'conditional_expression' ||
+            current.namedChildCount < 3) return null;
+        const consequence = current.namedChild(0);
+        const condition = current.namedChild(1);
+        const alternative = current.namedChild(2);
+        const parameterBranches = [consequence, alternative]
+            .map((branch, index) => branch?.type === 'identifier' &&
+                parameterAlternatives.has(branch.text)
+                ? { index, name: branch.text } : null)
+            .filter(Boolean);
+        if (parameterBranches.length !== 1) return null;
+        const parameterBranch = parameterBranches[0];
+        const positiveTypes = isinstanceTypes(condition, parameterBranch.name);
+        if (positiveTypes.length === 0) return null;
+        const declaredTypes = parameterAlternatives.get(parameterBranch.name);
+        const narrowedTypes = parameterBranch.index === 0
+            ? declaredTypes.filter(type => positiveTypes.includes(type))
+            : declaredTypes.filter(type => !positiveTypes.includes(type));
+        if (narrowedTypes.length !== 1) return null;
+
+        const valueBranch = parameterBranch.index === 0
+            ? alternative : consequence;
+        if (valueBranch?.type !== 'call') return null;
+        const callable = valueBranch.childForFieldName('function');
+        let valueType = null;
+        if (callable?.type === 'identifier' && /^[A-Z]/.test(callable.text) &&
+            !isPythonConstructorValueShadowedAt(callable, callable.text)) {
+            valueType = callable.text;
+        } else if (callable?.type === 'attribute') {
+            const owner = callable.childForFieldName('object');
+            const method = callable.childForFieldName('attribute');
+            if (owner?.type === 'identifier' && method?.type === 'identifier' &&
+                !isPythonNameShadowedAt(callable, owner.text)) {
+                valueType = options.resolveCallType?.(owner.text, method.text);
+            }
+        }
+        return valueType === narrowedTypes[0] ? valueType : null;
+    };
 
     traverseTreeCached(tree.rootNode, (node) => {
         if (node.type !== 'class_definition') return true;
@@ -2888,10 +3499,14 @@ function findInstanceAttributeTypes(code, parser, options = {}) {
             if (!typeNode) continue;
             if (!isDataclass && assign.childForFieldName('right')) continue;
 
-            // Extract type name from annotation
-            const typeIdent = typeNode.type === 'type' ? typeNode.firstChild : typeNode;
-            if (!typeIdent || typeIdent.type !== 'identifier') continue;
-            const typeName = typeIdent.text;
+            // Use the same single-type annotation parser as parameters and
+            // explicit instance fields. This admits compiler-equivalent bare
+            // contracts such as `color: Optional[Color]` and `Color | None`,
+            // while unions with several value types still abstain. Qualified
+            // names need origin metadata that this compact attr map does not
+            // retain, so leave those to declared field symbols.
+            const typeName = typeNameFromAnnotation(typeNode);
+            if (!typeName || typeQualifierFromAnnotation(typeNode)) continue;
 
             // Skip primitives and lowercase types
             if (PRIMITIVE_TYPES.has(typeName)) continue;
@@ -2927,6 +3542,7 @@ function findInstanceAttributeTypes(code, parser, options = {}) {
             // Build parameter type map from __init__ annotations
             // e.g. def __init__(self, market: MarketDataFetcher = None) → {market: MarketDataFetcher}
             const paramTypes = new Map();
+            const paramAlternatives = new Map();
             const params = child.childForFieldName('parameters');
             if (params) {
                 for (let p = 0; p < params.childCount; p++) {
@@ -2936,12 +3552,25 @@ function findInstanceAttributeTypes(code, parser, options = {}) {
                         const pName = param.childForFieldName('name') || param.child(0);
                         const pType = param.childForFieldName('type');
                         if (pName && pType) {
-                            const typeIdent = pType.type === 'type' ? pType.firstChild : pType;
-                            if (typeIdent?.type === 'identifier') {
-                                const tn = typeIdent.text;
-                                if (!PRIMITIVE_TYPES.has(tn) && tn[0] >= 'A' && tn[0] <= 'Z') {
-                                    paramTypes.set(pName.text, tn);
-                                }
+                            // Use the shared annotation parser so forward
+                            // references (`"Environment"`), dotted names,
+                            // and Optional/union wrappers participate in the
+                            // same conservative receiver-type contract as
+                            // ordinary parameter calls.
+                            const tn = typeNameFromAnnotation(pType);
+                            const directAlternatives = typeNamesFromAnnotation(pType);
+                            const aliasAlternatives = directAlternatives.length === 1
+                                ? options.resolveTypeAliasMembers?.(
+                                    directAlternatives[0])
+                                : null;
+                            const alternatives = aliasAlternatives?.length > 1
+                                ? aliasAlternatives : directAlternatives;
+                            if (alternatives.length > 1) {
+                                paramAlternatives.set(pName.text, alternatives);
+                            }
+                            if (tn && !PRIMITIVE_TYPES.has(tn) &&
+                                tn[0] >= 'A' && tn[0] <= 'Z') {
+                                paramTypes.set(pName.text, tn);
                             }
                         }
                     }
@@ -2967,7 +3596,8 @@ function findInstanceAttributeTypes(code, parser, options = {}) {
                 const rhs = assign.childForFieldName('right');
                 if (!rhs) return true;
 
-                const typeName = extractConstructorName(rhs);
+                const typeName = conditionalFieldType(rhs, paramAlternatives) ||
+                    extractConstructorName(rhs);
                 if (typeName) {
                     attrTypes.set(attrName, typeName);
                 } else if (rhs.type === 'call') {
@@ -3022,13 +3652,23 @@ function findInstanceAttributeTypes(code, parser, options = {}) {
                 const right = assignment.childForFieldName('right');
                 const callable = right?.type === 'call'
                     ? right.childForFieldName('function') : null;
-                const moduleName = callable?.type === 'attribute'
-                    ? callable.childForFieldName('object')?.text : null;
+                const callableReceiver = callable?.type === 'attribute'
+                    ? callable.childForFieldName('object') : null;
+                const directConstructor = callable?.type === 'identifier' &&
+                    /^[A-Z]/.test(callable.text) &&
+                    !isPythonConstructorValueShadowedAt(callable, callable.text)
+                    ? callable.text : null;
+                const moduleName = callableReceiver?.type === 'identifier'
+                    ? callableReceiver.text : null;
                 const functionName = callable?.type === 'attribute'
                     ? callable.childForFieldName('attribute')?.text : null;
-                const runtimeType = moduleName && functionName
-                    ? options.resolveBuiltinCallType?.(moduleName, functionName)
-                    : null;
+                const resolveCallType = options.resolveCallType ||
+                    options.resolveBuiltinCallType;
+                const runtimeType = directConstructor ||
+                    (moduleName && functionName &&
+                        !isPythonNameShadowedAt(callable, moduleName)
+                        ? resolveCallType?.(moduleName, functionName)
+                        : null);
                 if (!runtimeType) {
                     // None is a harmless uninitialized state; any other
                     // unknown write could replace the field with a project