@orangepro/orangepro-mcp 0.2.42 → 0.2.43

package/dist/local/analyze/analyzer.js

@@ -842,10 +842,18 @@ export function analyzeRepo(root, opts = {}) {
             }
             const content = readSafe(file.absPath);
             const isGenerated = content ? isGeneratedCode(content) : false;
+            const treeStructure = content && isTreeSitterLanguage(language) && treeSitterReady(language)
+                ? extractTreeSitterStructure(content, language, file.relPath)
+                : undefined;
             if (isGenerated)
                 generatedCodeFiles.add(file.relPath);
-            if (content && (language === "typescript" || language === "javascript") && !isGenerated && !isNonProductPath(file.relPath)) {
-                for (const contract of extractBehaviorContracts(content, file.relPath)) {
+            if (content && !isGenerated && !isNonProductPath(file.relPath)) {
+                const behaviorContracts = language === "typescript" || language === "javascript"
+                    ? extractBehaviorContracts(content, file.relPath)
+                    : language === "python"
+                        ? (treeStructure?.pythonBehaviorContracts ?? [])
+                        : [];
+                for (const contract of behaviorContracts) {
                     if (behaviorSurfaceExclusionReason(file.relPath, contract.handler ?? contract.title))
                         continue;
                     behaviorContractsTotal++;
@@ -868,7 +876,9 @@ export function analyzeRepo(root, opts = {}) {
                             file: contract.file,
                             source: contract.source,
                             ...(contract.handler ? { handler: contract.handler } : {}),
-                            ...(contract.controller ? { controller: contract.controller } : {})
+                            ...(contract.controller ? { controller: contract.controller } : {}),
+                            ...(contract.route_prefix_status ? { route_prefix_status: contract.route_prefix_status } : {}),
+                            ...(contract.route_prefix ? { route_prefix: contract.route_prefix } : {})
                         },
                         evidence_strength: "hard",
                         review_status: "auto_detected",
@@ -924,7 +934,8 @@ export function analyzeRepo(root, opts = {}) {
                     // Trivial accessors (Java getId/toString, Python __repr__) are real
                     // symbols but carry no testable behavior — kept in the graph, dropped
                     // from the denominator with disclosure so coverage is not under-claimed.
-                    const isBoilerplate = !isDts && !isInfra && !isGeneratedSymbol && callableKind && isBoilerplateSymbol(sym.name, language, sym.symbol_kind, sym.trivial_accessor);
+                    const boilerplateName = language === "python" ? (sym.name.split(".").pop() ?? sym.name) : sym.name;
+                    const isBoilerplate = !isDts && !isInfra && !isGeneratedSymbol && callableKind && isBoilerplateSymbol(boilerplateName, language, sym.symbol_kind, sym.trivial_accessor);
                     const callableBehaviorCandidate = !isDts && !isInfra && !isGeneratedSymbol && !isBoilerplate && behaviorCallableKind;
                     const surfaceExclusionReason = callableBehaviorCandidate
                         ? behaviorSurfaceExclusionReason(file.relPath, sym.name, sym.member_of)
@@ -1069,9 +1080,8 @@ export function analyzeRepo(root, opts = {}) {
                     if (generatedServices.length > 0)
                         medusaGeneratedServicesByFile.set(file.relPath, generatedServices);
                 }
-                else if (isTreeSitterLanguage(language) && treeSitterReady(language) && !isNonProductFile(file.relPath)) {
-                    const structure = extractTreeSitterStructure(content, language);
-                    nonTsStructureByFile.set(file.relPath, { language, structure });
+                else if (treeStructure && !isNonProductFile(file.relPath)) {
+                    nonTsStructureByFile.set(file.relPath, { language, structure: treeStructure });
                 }
             }
         }
@@ -1516,6 +1526,9 @@ export function analyzeRepo(root, opts = {}) {
     let javaProofAttempted = 0;
     let pythonProofConfirmedPairs = 0;
     let pythonProofAttempted = 0;
+    let pythonDependencyEdges = 0;
+    let pythonEndpointReachablePromoted = 0;
+    let pythonStructuralContainersExcluded = 0;
     if (nonTsStructureByFile.size > 0) {
         const nodeByExternalId = new Map(nodes.map((n) => [n.external_id, n]));
         const codeFilesByLanguage = new Map();
@@ -1661,12 +1674,12 @@ export function analyzeRepo(root, opts = {}) {
                 }
             }));
         };
-        const addImportBinding = (fromRel, local, target, imported, kind) => {
+        const addImportBinding = (fromRel, local, target, imported, kind, module) => {
             let map = importBindingsByFile.get(fromRel);
             if (!map)
                 importBindingsByFile.set(fromRel, (map = new Map()));
             if (!map.has(local))
-                map.set(local, { ...target, imported, kind });
+                map.set(local, { ...target, imported, kind, module });
         };
         const uniquePythonModule = (mod) => {
             const set = pythonModuleToFiles.get(mod);
@@ -1721,6 +1734,39 @@ export function analyzeRepo(root, opts = {}) {
                 return null;
             return symbolKind(targetRel, methodName) === "method" ? targetRel : null;
         };
+        const pythonQualifiedMemberId = (targetRel, className, methodName) => {
+            if (!targetRel)
+                return null;
+            const member = `${className}.${methodName}`;
+            return symbolsByFile.get(targetRel)?.has(member) && symbolKind(targetRel, member) === "method"
+                ? `sym:${targetRel}#${member}`
+                : null;
+        };
+        const shouldRetainPythonImportedSink = (binding, callee) => {
+            if (!/^(?:delete|destroy|purge|drop|erase|wipe|truncate|terminate|revoke|remove|replace|overwrite)/i.test(callee))
+                return false;
+            const topModule = (binding.module ?? "").replace(/^\.+/, "").split(".")[0]?.toLowerCase();
+            if (new Set(["os", "pathlib", "shutil", "tempfile"]).has(topModule ?? ""))
+                return false;
+            const moduleName = (binding.module ?? "").toLowerCase();
+            const owner = binding.imported ?? "";
+            return /(?:^|[._])(db|database|model|orm|prisma|repo|repository|record|redis|mongo|sql|store|storage|table)(?:$|[._])/.test(moduleName)
+                || /(?:Model|Repository|Repo|Store|Client|Table|Database|DB)$/.test(owner);
+        };
+        const shouldRetainPythonReceiverFieldSink = (qualifier, callee) => {
+            if (!/^(?:delete|destroy|purge|drop|erase|wipe|truncate|terminate|revoke|remove|replace|overwrite)/i.test(callee))
+                return false;
+            const tokens = qualifier
+                .replace(/\([^)]*\)/g, "")
+                .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+                .toLowerCase()
+                .split(/[^a-z0-9]+/)
+                .filter(Boolean);
+            return tokens.some((token) => new Set([
+                "db", "database", "model", "orm", "prisma", "repo", "repository", "record", "redis",
+                "mongo", "sql", "session", "store", "storage", "table"
+            ]).has(token));
+        };
         const guardedCsharpMemberTarget = (fromRel, className, methodName) => {
             const ownNamespace = nonTsStructureByFile.get(fromRel)?.structure.moduleName;
             const namespaces = new Set([...(ownNamespace ? [ownNamespace] : []), ...(csharpUsingNamespacesByFile.get(fromRel) ?? [])]);
@@ -1924,7 +1970,7 @@ export function analyzeRepo(root, opts = {}) {
                 return null;
             if (!classTargetRel || symbolKind(classTargetRel, rootQualifier) !== "class")
                 return null;
-            return eligiblePythonSymbol(classTargetRel, callee);
+            return eligiblePythonSymbol(classTargetRel, `${rootQualifier}.${callee}`);
         };
         for (const [rel, { language, structure }] of nonTsStructureByFile) {
             for (const i of structure.imports) {
@@ -1953,11 +1999,19 @@ export function analyzeRepo(root, opts = {}) {
                 }
                 else if (language === "c" || language === "cpp")
                     targetRel = resolveRelativeModule(rel, i.module, [".h", ".hpp", ".hh", ".hxx", ".c", ".cc", ".cpp", ".cxx"]);
-                if (!targetRel && !targetDir)
+                if (!targetRel && !targetDir) {
+                    // Python external runtime imports do not produce graph edges, but the
+                    // binding still anchors `Model.delete()`/`client.replace()` as an
+                    // imported external call. TYPE_CHECKING imports were removed by the
+                    // AST extractor, so they cannot become sink provenance here.
+                    if (language === "python") {
+                        addImportBinding(rel, i.local, {}, i.imported, i.kind, i.module);
+                    }
                     continue;
+                }
                 if (targetRel)
                     emitImport(rel, targetRel);
-                addImportBinding(rel, i.local, { ...(targetRel ? { targetRel } : {}), ...(targetDir ? { targetDir } : {}) }, i.imported, i.kind);
+                addImportBinding(rel, i.local, { ...(targetRel ? { targetRel } : {}), ...(targetDir ? { targetDir } : {}) }, i.imported, i.kind, i.module);
             }
         }
         // Go package-level method index (dir → "Recv.M" → file) for receiver calls that
@@ -2000,8 +2054,10 @@ export function analyzeRepo(root, opts = {}) {
                         emitCall(callerId, `sym:${rel}#${c.callee}`, rel);
                         continue;
                     }
-                    if (language === "python" && localSyms.has(c.callee))
+                    if (language === "python" && localSyms.has(c.callee)) {
+                        emitCall(callerId, `sym:${rel}#${c.callee}`, rel);
                         continue;
+                    }
                     const b = imports?.get(c.callee);
                     if (language === "php" && b?.targetRel && b.imported && symbolKind(b.targetRel, b.imported) !== "function")
                         continue;
@@ -2010,11 +2066,38 @@ export function analyzeRepo(root, opts = {}) {
                     }
                 }
                 else if (c.qualifier) {
-                    const rootQualifier = c.qualifier.split(".")[0];
-                    if (shadowed.has(rootQualifier))
+                    const rootQualifier = language === "python" ? pythonQualifierRoot(c.qualifier) : c.qualifier.split(".")[0];
+                    if (shadowed.has(rootQualifier) && !(language === "python" && (rootQualifier === "self" || rootQualifier === "cls")))
                         continue;
                     const b = imports?.get(rootQualifier);
-                    if (language === "go" && c.receiverVar && c.receiverType && c.qualifier === c.receiverVar) {
+                    if (language === "python") {
+                        const callerNode = nodeByExternalId.get(callerId);
+                        const callerOwner = typeof callerNode?.properties.member_of === "string" ? callerNode.properties.member_of : undefined;
+                        const selfMember = (rootQualifier === "self" || rootQualifier === "cls") && callerOwner
+                            ? pythonQualifiedMemberId(rel, callerOwner, c.callee)
+                            : null;
+                        const localClassMember = pythonQualifiedMemberId(rel, rootQualifier.replace(/\(.*$/, ""), c.callee);
+                        const importedClassMember = b?.kind === "named" && b.imported
+                            ? pythonQualifiedMemberId(b.targetRel, b.imported, c.callee)
+                            : null;
+                        if (selfMember || localClassMember || importedClassMember) {
+                            emitCall(callerId, selfMember ?? localClassMember ?? importedClassMember, rel);
+                        }
+                        else if (b?.kind === "module" && b.targetRel && symbolsByFile.get(b.targetRel)?.has(c.callee)) {
+                            emitCall(callerId, `sym:${b.targetRel}#${c.callee}`, rel);
+                        }
+                        else if (b && !b.targetRel && shouldRetainPythonImportedSink(b, c.callee)) {
+                            const qualifier = b.kind === "named" ? c.qualifier.replace(/\([^)]*\)/g, "") : c.qualifier;
+                            recordImportedStaticCallee(callerId, `${qualifier}.${c.callee}`);
+                        }
+                        else if (!b && c.qualifier.includes(".") && shouldRetainPythonReceiverFieldSink(c.qualifier, c.callee)) {
+                            // Attribute-chain receiver (`self.repo.delete`, `store.client.replace`):
+                            // retain a name fact only. Scoring applies its own persistence + verb
+                            // policy; no graph edge or evidence claim is created here.
+                            recordExternalCallee(callerId, `${c.qualifier}.${c.callee}`);
+                        }
+                    }
+                    else if (language === "go" && c.receiverVar && c.receiverType && c.qualifier === c.receiverVar) {
                         // Go receiver-method call: inside `func (t *task) Run()`, `t.validate()` calls
                         // `task.validate`. The receiver's type is DECLARED in the method signature, so
                         // this is exact resolution: same file first, then the same package (methods of
@@ -2064,6 +2147,153 @@ export function analyzeRepo(root, opts = {}) {
                 }
             }
         }
+        const resolvePythonReferenceId = (fromRel, reference) => {
+            const parts = reference.split(".").filter(Boolean);
+            if (parts.length === 0)
+                return null;
+            const local = parts[0];
+            if (parts.length === 1 && symbolsByFile.get(fromRel)?.has(local))
+                return `sym:${fromRel}#${local}`;
+            const localMember = parts.length > 1 ? parts.join(".") : "";
+            if (localMember && symbolsByFile.get(fromRel)?.has(localMember))
+                return `sym:${fromRel}#${localMember}`;
+            const binding = importBindingsByFile.get(fromRel)?.get(local);
+            if (!binding?.targetRel || isNonProductFile(binding.targetRel))
+                return null;
+            const targetName = binding.kind === "module"
+                ? parts.slice(1).join(".")
+                : [binding.imported, ...parts.slice(1)].filter(Boolean).join(".");
+            return targetName && symbolsByFile.get(binding.targetRel)?.has(targetName)
+                ? `sym:${binding.targetRel}#${targetName}`
+                : null;
+        };
+        const seenPythonDependencyEdges = new Set();
+        for (const [rel, { language, structure }] of nonTsStructureByFile) {
+            if (language !== "python")
+                continue;
+            for (const dependency of structure.pythonDependencies ?? []) {
+                const handlerId = `sym:${rel}#${dependency.handler}`;
+                const dependencyId = resolvePythonReferenceId(rel, dependency.dependency);
+                if (!codeSymbolIds.has(handlerId) || !dependencyId || !codeSymbolIds.has(dependencyId))
+                    continue;
+                const callKey = `${handlerId}|${dependencyId}`;
+                if (!seenCalls.has(callKey)) {
+                    seenCalls.add(callKey);
+                    edges.push(makeEdge({
+                        from_external_id: handlerId,
+                        to_external_id: dependencyId,
+                        relationship_type: "CALLS",
+                        evidence_strength: "framework-derived",
+                        review_status: "auto_detected",
+                        provenance: prov(rel),
+                        properties: { call_via: "fastapi_dependency", resolution: "tree_sitter_exact" }
+                    }));
+                }
+                for (const contract of behaviorContractsByFile.get(rel) ?? []) {
+                    if (contract.framework !== "fastapi" || contract.handler !== dependency.handler)
+                        continue;
+                    const key = `${contract.id}|${dependencyId}`;
+                    if (seenPythonDependencyEdges.has(key))
+                        continue;
+                    seenPythonDependencyEdges.add(key);
+                    pythonDependencyEdges++;
+                    edges.push(makeEdge({
+                        from_external_id: contract.id,
+                        to_external_id: dependencyId,
+                        relationship_type: "DEPENDS_ON",
+                        evidence_strength: "framework-derived",
+                        review_status: "auto_detected",
+                        provenance: prov(rel),
+                        properties: { framework: "fastapi", dependency: dependency.dependency }
+                    }));
+                }
+            }
+        }
+        // Python's first-pass denominator is intentionally conservative. Promote only
+        // concrete production methods/functions reached from a framework handler by
+        // exact hard/framework CALLS edges. This repairs denominator visibility without
+        // admitting every class or utility into the score population.
+        const pythonNodeIds = new Set(nodes
+            .filter((n) => n.kind === "CodeSymbol" && typeof n.properties.file === "string" && n.properties.file.endsWith(".py"))
+            .map((n) => n.external_id));
+        const pythonAdjacency = new Map();
+        for (const edge of edges) {
+            if (edge.relationship_type !== "CALLS" || !pythonNodeIds.has(edge.from_external_id) || !pythonNodeIds.has(edge.to_external_id))
+                continue;
+            const list = pythonAdjacency.get(edge.from_external_id);
+            const step = { target: edge.to_external_id, edgeKind: edge.relationship_type };
+            if (list)
+                list.push(step);
+            else
+                pythonAdjacency.set(edge.from_external_id, [step]);
+        }
+        const pythonEntrypoints = [...new Set(edges
+                .filter((e) => e.relationship_type === "IMPLEMENTED_IN" && pythonNodeIds.has(e.to_external_id))
+                .map((e) => e.to_external_id))].sort();
+        const reachablePython = new Set(pythonEntrypoints);
+        const pythonWitness = new Map(pythonEntrypoints.map((seed) => [seed, { seed, edgeKinds: [], hopCount: 0 }]));
+        let frontier = [...pythonEntrypoints];
+        for (let depth = 0; depth < 3 && frontier.length > 0; depth++) {
+            const next = [];
+            for (const current of frontier) {
+                const currentWitness = pythonWitness.get(current);
+                if (!currentWitness)
+                    continue;
+                for (const step of pythonAdjacency.get(current) ?? []) {
+                    if (reachablePython.has(step.target))
+                        continue;
+                    reachablePython.add(step.target);
+                    pythonWitness.set(step.target, {
+                        seed: currentWitness.seed,
+                        edgeKinds: [...currentWitness.edgeKinds, step.edgeKind],
+                        hopCount: currentWitness.hopCount + 1
+                    });
+                    next.push(step.target);
+                }
+            }
+            frontier = next;
+        }
+        for (const id of reachablePython) {
+            const node = nodeByExternalId.get(id);
+            if (!node || node.properties.symbol_kind === "class")
+                continue;
+            const witness = pythonWitness.get(id);
+            node.properties.endpoint_reachable = true;
+            if (witness) {
+                node.properties.denominator_witness = {
+                    seed: witness.seed,
+                    edge_kinds: witness.edgeKinds,
+                    hop_count: witness.hopCount
+                };
+            }
+            if (node.denominator_eligible === true)
+                continue;
+            const callableName = (node.title ?? "").split(".").pop() ?? node.title ?? "";
+            if (callableName.startsWith("_") || node.properties.denominator_reason_code !== "not_entry_point_adjacent")
+                continue;
+            node.denominator_eligible = true;
+            node.denominator_reason = "Transitively reachable from a Python framework entrypoint through exact static calls.";
+            node.properties.denominator_promotion = "python_entrypoint_reachable";
+            pythonEndpointReachablePromoted++;
+        }
+        const pythonOwnersWithMethods = new Set(nodes
+            .filter((n) => n.kind === "CodeSymbol" &&
+            n.properties.symbol_kind === "method" &&
+            n.denominator_eligible === true &&
+            typeof n.properties.file === "string" &&
+            n.properties.file.endsWith(".py") &&
+            typeof n.properties.member_of === "string")
+            .map((n) => `${n.properties.file}#${n.properties.member_of}`));
+        for (const node of nodes) {
+            if (node.kind === "CodeSymbol" &&
+                node.properties.symbol_kind === "class" &&
+                node.denominator_eligible === true &&
+                typeof node.properties.file === "string" &&
+                pythonOwnersWithMethods.has(`${node.properties.file}#${node.title ?? ""}`)) {
+                node.properties.ranking_exclusion_reason = "python_structural_container";
+                pythonStructuralContainersExcluded++;
+            }
+        }
         const seenGoProof = new Set();
         const proofVerifiedAt = scanStartMs;
         for (const [testRel, structure] of goTestStructureByFile) {
@@ -2566,6 +2796,15 @@ export function analyzeRepo(root, opts = {}) {
                 }
             }
             : {}),
+        ...(pythonDependencyEdges || pythonEndpointReachablePromoted || pythonStructuralContainersExcluded
+            ? {
+                python_structural_recalibration: {
+                    dependency_edges: pythonDependencyEdges,
+                    endpoint_reachable_promoted: pythonEndpointReachablePromoted,
+                    structural_containers_rank_excluded: pythonStructuralContainersExcluded
+                }
+            }
+            : {}),
         flows,
         structural_clusters: structuralClusters,
         ...(tsStatus.loaded.length || tsStatus.failed.length

package/dist/local/analyze/treeSitter/engine.js

@@ -8,6 +8,8 @@ import { createRequire } from "node:module";
 import { Parser, Language } from "web-tree-sitter";
 import { MAX_SYMBOLS_PER_FILE } from "../symbols.js";
 import { TS_LANG_CONFIGS } from "./languages.js";
+import { slugify } from "../../util/ids.js";
+import { shortHash } from "../../util/hash.js";
 const require = createRequire(import.meta.url);
 let initPromise = null;
 const loaded = new Map();
@@ -212,6 +214,39 @@ function symbolName(node, cfg) {
 function nodeLines(node) {
     return { start_line: node.startPosition.row + 1, end_line: node.endPosition.row + 1 };
 }
+/**
+ * Nearest lexical Python class for a function. A function boundary reached first
+ * means this is a nested local function, not a class method.
+ */
+function pythonOwnerClass(node) {
+    const owners = [];
+    let parent = node.parent;
+    while (parent) {
+        if (parent.type === "function_definition" || parent.type === "lambda")
+            return undefined;
+        if (parent.type === "class_definition") {
+            const name = parent.childForFieldName("name")?.text;
+            if (name)
+                owners.unshift(name);
+        }
+        parent = parent.parent;
+    }
+    return owners.length > 0 ? owners.join(".") : undefined;
+}
+function hasPythonFunctionAncestor(node) {
+    let parent = node.parent;
+    while (parent) {
+        if (parent.type === "function_definition" || parent.type === "lambda")
+            return true;
+        parent = parent.parent;
+    }
+    return false;
+}
+function pythonQualifiedFunctionName(node) {
+    const name = functionName(node, "python");
+    const owner = pythonOwnerClass(node);
+    return name && owner ? `${owner}.${name}` : name;
+}
 /**
  * Extract class/function/method symbol metadata (names + a trivial-accessor flag —
  * never source bodies) from a tree-sitter-supported language. Sync; returns [] when
@@ -249,16 +284,22 @@ export function extractTreeSitterSymbols(content, language) {
             kind = "method";
         else if (cfg.functionTypes.has(node.type))
             kind = "function";
-        if (kind && shouldEmitSymbol(node, language)) {
+        const pythonOwner = language === "python" && node.type === "function_definition" ? pythonOwnerClass(node) : undefined;
+        if (pythonOwner && kind === "function")
+            kind = "method";
+        const localPythonDeclaration = language === "python" && (node.type === "function_definition" || node.type === "class_definition") && hasPythonFunctionAncestor(node);
+        if (kind && !localPythonDeclaration && shouldEmitSymbol(node, language)) {
             const name = symbolName(node, cfg);
             if (name && !RESERVED_SYMBOL_NAMES.has(name)) {
                 // Go methods mint receiver-qualified names (`Recv.M`, mirroring TS/JS
                 // `Class.method` + member_of) so same-named methods on different receivers
                 // stay distinct symbols; an underivable receiver falls back to the bare name.
-                const recv = kind === "method" && language === "go" ? goReceiverBaseName(node) : undefined;
+                const recv = kind === "method" && language === "go" ? goReceiverBaseName(node) : language === "python" ? pythonOwner : undefined;
+                const pythonClassOwner = kind === "class" && language === "python" ? pythonOwnerClass(node) : undefined;
+                const emittedName = pythonClassOwner ? `${pythonClassOwner}.${name}` : name;
                 add(kind === "method"
                     ? { name: recv ? `${recv}.${name}` : name, ...(recv ? { member_of: recv } : {}), symbol_kind: kind, trivial_accessor: isTrivialAccessorBody(node, language), ...nodeLines(node) }
-                    : { name, symbol_kind: kind, ...nodeLines(node) });
+                    : { name: emittedName, symbol_kind: kind, ...nodeLines(node) });
             }
         }
         for (let i = 0; i < node.childCount; i++) {
@@ -464,6 +505,21 @@ function kotlinTopLevelSymbols(root) {
     }
     return [...out].sort();
 }
+function underPythonTypeCheckingGuard(node) {
+    let parent = node.parent;
+    while (parent) {
+        if (parent.type === "if_statement") {
+            const condition = parent.childForFieldName("condition");
+            const text = condition?.text.trim() ?? "";
+            if (text === "TYPE_CHECKING" || /^[A-Za-z_]\w*\.TYPE_CHECKING$/.test(text))
+                return true;
+        }
+        if (parent.type === "function_definition" || parent.type === "class_definition")
+            break;
+        parent = parent.parent;
+    }
+    return false;
+}
 function extractImports(root, language) {
     const imports = [];
     const add = (binding) => {
@@ -472,6 +528,9 @@ function extractImports(root, language) {
         imports.push(binding);
     };
     const walk = (node) => {
+        if (language === "python" && (node.type === "import_statement" || node.type === "import_from_statement") && underPythonTypeCheckingGuard(node)) {
+            return;
+        }
         if (language === "java" && node.type === "import_declaration") {
             const spec = namedChildren(node).find((n) => n.type.endsWith("identifier"))?.text;
             if (spec && !spec.endsWith(".*"))
@@ -1430,6 +1489,360 @@ function extractJavaProofCalls(root, imports) {
     }
     return out;
 }
+const FASTAPI_HTTP_METHODS = new Set(["get", "post", "put", "patch", "delete", "options", "head", "trace"]);
+function pythonStaticString(node) {
+    if (!node || node.type !== "string")
+        return null;
+    const contents = node.descendantsOfType("string_content").filter((n) => Boolean(n));
+    if (contents.length !== 1)
+        return null;
+    return contents[0]?.text ?? null;
+}
+function pythonDottedName(node) {
+    if (!node)
+        return null;
+    if (node.type === "identifier" || node.type === "dotted_name")
+        return node.text;
+    if (node.type !== "attribute")
+        return null;
+    const object = pythonDottedName(node.childForFieldName("object"));
+    const attribute = node.childForFieldName("attribute")?.text;
+    return object && attribute ? `${object}.${attribute}` : null;
+}
+function pythonCallArguments(call) {
+    const args = call.childForFieldName("arguments");
+    return args ? namedChildren(args).filter((n) => n.type !== "comment") : [];
+}
+function pythonKeywordArgument(call, name) {
+    for (const arg of pythonCallArguments(call)) {
+        if (arg.type !== "keyword_argument" || arg.childForFieldName("name")?.text !== name)
+            continue;
+        return arg.childForFieldName("value") ?? namedChildren(arg)[1] ?? null;
+    }
+    return null;
+}
+function pythonPositionalArguments(call) {
+    return pythonCallArguments(call).filter((n) => n.type !== "keyword_argument" && n.type !== "list_splat" && n.type !== "dictionary_splat");
+}
+function pythonStaticHttpMethods(node, fallback = ["GET"]) {
+    if (!node)
+        return fallback;
+    if (!new Set(["list", "tuple", "set"]).has(node.type))
+        return null;
+    const elements = namedChildren(node).filter((child) => child.type !== "comment");
+    if (elements.length === 0)
+        return null;
+    const methods = elements.map((element) => pythonStaticString(element));
+    if (methods.some((method) => method === null))
+        return null;
+    const normalized = methods.map((method) => method.toLowerCase());
+    return normalized.every((method) => FASTAPI_HTTP_METHODS.has(method)) ? normalized.map((method) => method.toUpperCase()) : null;
+}
+function normalizePythonRoutePath(...parts) {
+    const joined = parts.map((p) => p.trim().replace(/^\/+|\/+$/g, "")).filter(Boolean).join("/");
+    return joined ? `/${joined}` : "/";
+}
+function pythonImportedFromFastapi(imports, local, imported) {
+    return imports.some((b) => b.local === local && b.module === "fastapi" && b.kind === "named" && b.imported === imported);
+}
+function pythonCallIsFastapiConstructor(call, imports, imported) {
+    const parts = callParts(call, "python");
+    if (!parts)
+        return false;
+    if (!parts.qualifier)
+        return pythonImportedFromFastapi(imports, parts.callee, imported);
+    if (parts.callee !== imported)
+        return false;
+    const root = parts.qualifier.split(".")[0] ?? "";
+    return imports.some((b) => b.local === root && b.kind === "module" && b.module === "fastapi");
+}
+function pythonBindingTargetNames(target) {
+    if (!target)
+        return [];
+    if (target.type === "identifier")
+        return [target.text];
+    if (!new Set(["pattern_list", "tuple_pattern", "list_pattern", "tuple", "list"]).has(target.type))
+        return [];
+    return namedChildren(target).flatMap((child) => pythonBindingTargetNames(child));
+}
+function pythonFastapiReceivers(root, imports) {
+    const mutationCount = new Map();
+    const candidates = new Map();
+    const mutations = [];
+    for (const type of ["assignment", "annotated_assignment", "augmented_assignment", "delete_statement"]) {
+        mutations.push(...root.descendantsOfType(type).filter((node) => Boolean(node)));
+    }
+    mutations.sort((a, b) => a.startIndex - b.startIndex);
+    for (const assignment of mutations) {
+        if (!pythonDirectModuleExecution(assignment))
+            continue;
+        const left = assignment.childForFieldName("left");
+        const targets = assignment.type === "delete_statement"
+            ? namedChildren(assignment).flatMap((child) => pythonBindingTargetNames(child))
+            : pythonBindingTargetNames(left);
+        for (const target of targets)
+            mutationCount.set(target, (mutationCount.get(target) ?? 0) + 1);
+        const right = assignment.childForFieldName("right");
+        if (left?.type !== "identifier")
+            continue;
+        const kind = right?.type === "call" && pythonCallIsFastapiConstructor(right, imports, "APIRouter")
+            ? "router"
+            : right?.type === "call" && pythonCallIsFastapiConstructor(right, imports, "FastAPI")
+                ? "app"
+                : null;
+        if (!kind || right?.type !== "call")
+            continue;
+        const prefixNode = kind === "router" ? pythonKeywordArgument(right, "prefix") : null;
+        const staticPrefix = pythonStaticString(prefixNode);
+        candidates.set(left.text, {
+            kind,
+            prefix: staticPrefix ?? "",
+            prefixResolved: !prefixNode || staticPrefix !== null,
+            boundAt: assignment.startIndex
+        });
+    }
+    const out = new Map();
+    for (const [name, receiver] of candidates)
+        if (mutationCount.get(name) === 1)
+            out.set(name, receiver);
+    return out;
+}
+const PYTHON_NONDETERMINISTIC_SCOPES = new Set([
+    "function_definition", "class_definition", "if_statement", "for_statement", "while_statement",
+    "try_statement", "with_statement", "match_statement", "lambda", "list_comprehension",
+    "dictionary_comprehension", "set_comprehension", "generator_expression"
+]);
+function pythonDirectModuleExecution(node) {
+    let parent = node.parent;
+    while (parent) {
+        if (PYTHON_NONDETERMINISTIC_SCOPES.has(parent.type))
+            return false;
+        if (parent.type === "module")
+            return true;
+        parent = parent.parent;
+    }
+    return false;
+}
+function pythonRouterIncludePrefixes(root, receivers) {
+    const out = new Map();
+    for (const call of root.descendantsOfType("call")) {
+        if (!call || !pythonDirectModuleExecution(call))
+            continue;
+        const parts = callParts(call, "python");
+        const app = parts?.qualifier?.split(".")[0];
+        if (!parts || parts.callee !== "include_router" || !app || receivers.get(app)?.kind !== "app")
+            continue;
+        const router = pythonDottedName(pythonPositionalArguments(call)[0] ?? null);
+        if (!router || !receivers.has(router) || receivers.get(app).boundAt >= call.startIndex || receivers.get(router).boundAt >= call.startIndex)
+            continue;
+        const includePrefix = pythonStaticString(pythonKeywordArgument(call, "prefix"));
+        if (includePrefix === null && pythonKeywordArgument(call, "prefix"))
+            continue;
+        let prefixes = out.get(router);
+        if (!prefixes)
+            out.set(router, (prefixes = new Set()));
+        prefixes.add(includePrefix ?? "");
+    }
+    return out;
+}
+function makePythonBehaviorContract(input) {
+    const identityInput = `${input.method}|${input.path}|${input.file}|${input.handler ?? ""}`;
+    return {
+        id: `endpoint:${slugify(`${input.method}-${input.path}-${input.file}-${input.handler ?? ""}`)}-${shortHash(identityInput)}`,
+        title: `${input.method} ${input.path}`,
+        kind: "http_endpoint",
+        framework: "fastapi",
+        method: input.method,
+        path: input.path,
+        file: input.file,
+        handler: input.handler,
+        route_prefix_status: input.prefixStatus,
+        ...(input.prefix ? { route_prefix: input.prefix } : {}),
+        source: "framework"
+    };
+}
+function dedupePythonContracts(contracts) {
+    const seen = new Set();
+    return contracts.filter((contract) => {
+        const key = `${contract.method}|${contract.path}|${contract.handler ?? ""}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function pythonDirectModuleHandlers(root) {
+    const counts = new Map();
+    for (const fn of root.descendantsOfType("function_definition")) {
+        if (!fn || hasPythonFunctionAncestor(fn))
+            continue;
+        const declaration = fn.parent?.type === "decorated_definition" ? fn.parent : fn;
+        if (declaration.parent?.type !== "module")
+            continue;
+        const name = pythonQualifiedFunctionName(fn);
+        if (name)
+            counts.set(name, (counts.get(name) ?? 0) + 1);
+    }
+    for (const type of ["assignment", "annotated_assignment", "augmented_assignment", "delete_statement"]) {
+        for (const mutation of root.descendantsOfType(type)) {
+            if (!mutation || !pythonDirectModuleExecution(mutation))
+                continue;
+            const left = mutation.childForFieldName("left");
+            const targets = mutation.type === "delete_statement"
+                ? namedChildren(mutation).flatMap((child) => pythonBindingTargetNames(child))
+                : pythonBindingTargetNames(left);
+            for (const target of targets)
+                if (counts.has(target))
+                    counts.set(target, counts.get(target) + 1);
+        }
+    }
+    return new Set([...counts].filter(([, count]) => count === 1).map(([name]) => name));
+}
+function extractPythonBehaviorContracts(root, imports, file) {
+    const receivers = pythonFastapiReceivers(root, imports);
+    if (receivers.size === 0)
+        return [];
+    const directHandlers = pythonDirectModuleHandlers(root);
+    const includes = pythonRouterIncludePrefixes(root, receivers);
+    const out = [];
+    const add = (receiverName, method, routePath, registrationAt, handler) => {
+        const receiver = receivers.get(receiverName);
+        if (!receiver || receiver.boundAt >= registrationAt)
+            return;
+        const includePrefixes = receiver.kind === "app" ? new Set([""]) : includes.get(receiverName);
+        const prefixes = includePrefixes && includePrefixes.size > 0 ? [...includePrefixes] : [""];
+        const status = receiver.prefixResolved && (receiver.kind === "app" || Boolean(includePrefixes?.size)) ? "resolved" : "unresolved";
+        for (const includePrefix of prefixes) {
+            const prefix = normalizePythonRoutePath(includePrefix, receiver.prefix);
+            const normalizedPrefix = prefix === "/" ? "" : prefix;
+            out.push(makePythonBehaviorContract({
+                file,
+                method: method.toUpperCase(),
+                path: normalizePythonRoutePath(normalizedPrefix, routePath),
+                handler,
+                prefixStatus: status,
+                prefix: normalizedPrefix
+            }));
+        }
+    };
+    for (const fn of root.descendantsOfType("function_definition")) {
+        if (!fn || hasPythonFunctionAncestor(fn))
+            continue;
+        const handler = pythonQualifiedFunctionName(fn);
+        const decorated = fn.parent?.type === "decorated_definition" ? fn.parent : null;
+        if (!handler || !directHandlers.has(handler) || !decorated || decorated.parent?.type !== "module")
+            continue;
+        for (const decorator of namedChildren(decorated).filter((n) => n.type === "decorator")) {
+            const call = namedChildren(decorator).find((n) => n.type === "call");
+            const parts = call ? callParts(call, "python") : null;
+            const receiver = parts?.qualifier?.split(".")[0];
+            const route = call ? pythonStaticString(pythonPositionalArguments(call)[0] ?? null) : null;
+            if (!call || !parts || !receiver || route === null)
+                continue;
+            if (FASTAPI_HTTP_METHODS.has(parts.callee)) {
+                add(receiver, parts.callee, route, call.startIndex, handler);
+            }
+            else if (parts.callee === "api_route") {
+                const methods = pythonStaticHttpMethods(pythonKeywordArgument(call, "methods"));
+                if (!methods)
+                    continue;
+                for (const method of methods)
+                    add(receiver, method, route, call.startIndex, handler);
+            }
+        }
+    }
+    for (const call of root.descendantsOfType("call")) {
+        if (!call || !pythonDirectModuleExecution(call))
+            continue;
+        const parts = callParts(call, "python");
+        const receiver = parts?.qualifier?.split(".")[0];
+        if (!parts || parts.callee !== "add_api_route" || !receiver || !receivers.has(receiver))
+            continue;
+        const positional = pythonPositionalArguments(call);
+        const route = pythonStaticString(positional[0] ?? null);
+        const handler = pythonDottedName(positional[1] ?? null);
+        if (route === null || !handler || !directHandlers.has(handler))
+            continue;
+        const methods = pythonStaticHttpMethods(pythonKeywordArgument(call, "methods"));
+        if (!methods)
+            continue;
+        for (const method of methods)
+            add(receiver, method, route, call.startIndex, handler);
+    }
+    return dedupePythonContracts(out);
+}
+function isFastapiDependsCall(call, imports) {
+    const parts = callParts(call, "python");
+    if (!parts)
+        return false;
+    if (!parts.qualifier) {
+        return pythonImportedFromFastapi(imports, parts.callee, "Depends") || pythonImportedFromFastapi(imports, parts.callee, "Security");
+    }
+    if (parts.callee !== "Depends" && parts.callee !== "Security")
+        return false;
+    const root = parts.qualifier.split(".")[0] ?? "";
+    return imports.some((b) => b.local === root && b.kind === "module" && b.module === "fastapi");
+}
+function extractPythonDependencies(root, imports, acceptedHandlers) {
+    const out = [];
+    const seen = new Set();
+    const receivers = pythonFastapiReceivers(root, imports);
+    const directHandlers = pythonDirectModuleHandlers(root);
+    const addFromNode = (handler, node) => {
+        if (!node)
+            return;
+        const calls = [...(node.type === "call" ? [node] : []), ...node.descendantsOfType("call").filter((n) => Boolean(n))];
+        for (const call of calls) {
+            if (!isFastapiDependsCall(call, imports))
+                continue;
+            const dependency = pythonDottedName(pythonPositionalArguments(call)[0] ?? null);
+            if (!dependency)
+                continue;
+            const key = `${handler}|${dependency}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({ handler, dependency });
+        }
+    };
+    for (const fn of root.descendantsOfType("function_definition")) {
+        if (!fn || hasPythonFunctionAncestor(fn))
+            continue;
+        const handler = pythonQualifiedFunctionName(fn);
+        const params = fn.childForFieldName("parameters");
+        const declaration = fn.parent?.type === "decorated_definition" ? fn.parent : fn;
+        if (!handler || !params || !directHandlers.has(handler) || declaration.parent?.type !== "module" || !acceptedHandlers.has(handler))
+            continue;
+        addFromNode(handler, params);
+        const decorated = fn.parent?.type === "decorated_definition" ? fn.parent : null;
+        for (const decorator of decorated ? namedChildren(decorated).filter((n) => n.type === "decorator") : []) {
+            const routeCall = namedChildren(decorator).find((n) => n.type === "call");
+            const parts = routeCall ? callParts(routeCall, "python") : null;
+            const receiver = parts?.qualifier?.split(".")[0];
+            if (!routeCall || !parts || !receiver || !receivers.has(receiver) || receivers.get(receiver).boundAt >= routeCall.startIndex)
+                continue;
+            if (!FASTAPI_HTTP_METHODS.has(parts.callee) && (parts.callee !== "api_route" || !pythonStaticHttpMethods(pythonKeywordArgument(routeCall, "methods"))))
+                continue;
+            addFromNode(handler, pythonKeywordArgument(routeCall, "dependencies"));
+        }
+    }
+    for (const call of root.descendantsOfType("call")) {
+        if (!call || !pythonDirectModuleExecution(call))
+            continue;
+        const parts = callParts(call, "python");
+        const receiver = parts?.qualifier?.split(".")[0];
+        if (!parts || parts.callee !== "add_api_route" || !receiver || !receivers.has(receiver) || receivers.get(receiver).boundAt >= call.startIndex)
+            continue;
+        const positional = pythonPositionalArguments(call);
+        const route = pythonStaticString(positional[0] ?? null);
+        const handler = pythonDottedName(positional[1] ?? null);
+        const methods = pythonStaticHttpMethods(pythonKeywordArgument(call, "methods"));
+        if (route !== null && handler && methods && directHandlers.has(handler) && acceptedHandlers.has(handler)) {
+            addFromNode(handler, pythonKeywordArgument(call, "dependencies"));
+        }
+    }
+    return out;
+}
 function directPythonAssertCall(assertion) {
     const subject = namedChildren(assertion)[0];
     if (!subject)
@@ -1490,7 +1903,7 @@ function extractPythonProofCalls(root) {
     walk(root, false, null);
     return out;
 }
-export function extractTreeSitterStructure(content, language) {
+export function extractTreeSitterStructure(content, language, relPath = "") {
     const parser = parserFor(language);
     if (!parser)
         return { imports: [], calls: [] };
@@ -1530,6 +1943,9 @@ export function extractTreeSitterStructure(content, language) {
                             callerReceivers.set(name, { receiverVar: rv, receiverType: recv });
                     }
                 }
+                if (name && language === "python" && node.type === "function_definition") {
+                    name = pythonQualifiedFunctionName(node) ?? name;
+                }
                 if (name) {
                     nextCaller = name;
                     nextShadowed = localBindings(node, language);
@@ -1546,6 +1962,10 @@ export function extractTreeSitterStructure(content, language) {
     };
     visit(root, null, new Set(), false);
     const imports = extractImports(root, language);
+    const pythonBehaviorContracts = language === "python" ? extractPythonBehaviorContracts(root, imports, relPath) : undefined;
+    const pythonDependencies = language === "python"
+        ? extractPythonDependencies(root, imports, new Set((pythonBehaviorContracts ?? []).map((contract) => contract.handler).filter((handler) => Boolean(handler))))
+        : undefined;
     const result = {
         ...(language === "java" ? { packageName: javaPackage(root), javaClasses: javaClassInfos(root), javaProofCalls: extractJavaProofCalls(root, imports) } : {}),
         ...(language === "go" ? { packageName: goPackage(root), goCtorResults: extractGoCtorResults(root) } : {}),
@@ -1555,7 +1975,7 @@ export function extractTreeSitterStructure(content, language) {
         imports,
         calls,
         ...(language === "go" ? { goProofCalls: extractGoProofCalls(root, imports) } : {}),
-        ...(language === "python" ? { pythonProofCalls: extractPythonProofCalls(root) } : {})
+        ...(language === "python" ? { pythonProofCalls: extractPythonProofCalls(root), pythonBehaviorContracts, pythonDependencies } : {})
     };
     tree.delete();
     return result;

package/dist/local/graph/ontology.js

@@ -9,9 +9,9 @@
  * The graph is built directly by OrangePro; it does not depend on any
  * third-party graph product or format.
  */
-// v2: Go method symbol ids are receiver-qualified (`sym:file.go#Recv.M`) — old
-// graphs hold bare-name method ids and must force-rebuild (loadGraph hard-fails).
-export const LOCAL_GRAPH_SCHEMA_VERSION = "orangepro.local_graph.v2";
+// v3: Python method symbol ids are owner-qualified (`sym:file.py#Class.method`) —
+// old graphs hold collision-prone bare method ids and must force-rebuild.
+export const LOCAL_GRAPH_SCHEMA_VERSION = "orangepro.local_graph.v3";
 /** Node kinds that map to behaviors/requirements for scoring + gaps + generation. */
 export const BEHAVIOR_KINDS = new Set([
     "Requirement",

package/dist/local/provenance.js

@@ -3,7 +3,7 @@ import { ORS_VERSION } from "./score/risk.js";
 import { ORANGEPRO_VERSION } from "./version.js";
 import { hashString } from "./util/hash.js";
 export const ARTIFACT_IDENTITY_VERSION = "orangepro.artifact_identity.v1";
-export const ANALYZER_VERSION = "orangepro.analyzer.v1";
+export const ANALYZER_VERSION = "orangepro.analyzer.v2";
 export const PROOF_ORACLE_VERSION = "orangepro.targeted_mutation_oracle.v1";
 function stable(value) {
     if (value === null || typeof value !== "object")

package/dist/local/score/risk.js

@@ -446,6 +446,7 @@ export function rankRiskGaps(graph, opts = {}) {
     // worklist but do not rescale an unchanged peer.
     const normalizationSymbols = graph.nodes.filter((n) => n.kind === "CodeSymbol" && n.denominator_eligible === true && !n.stale && rankEligible(n) && !isSuppressed(n.external_id));
     const symbols = normalizationSymbols.filter((n) => !confirmed.has(n.external_id));
+    const worklistSymbols = symbols.filter((n) => n.properties.ranking_exclusion_reason !== "python_structural_container");
     const symbolIds = new Set(normalizationSymbols.map((s) => s.external_id));
     const symbolsByFile = new Map();
     for (const s of normalizationSymbols) {
@@ -603,7 +604,7 @@ export function rankRiskGaps(graph, opts = {}) {
             for (const s of syms)
                 legacyIncoming.set(s.external_id, (legacyIncoming.get(s.external_id) ?? 0) + share);
         }
-        return symbols
+        return worklistSymbols
             .map((s) => {
             const file = symbolFile(s);
             const incoming_refs = legacyIncoming.get(s.external_id) ?? 0;
@@ -649,7 +650,7 @@ export function rankRiskGaps(graph, opts = {}) {
     const rawById = new Map(normalizationSymbols.map((s, idx) => [s.external_id, rawScores[idx]]));
     const pById = new Map(normalizationSymbols.map((s, idx) => [s.external_id, pScores[idx]]));
     const iById = new Map(normalizationSymbols.map((s, idx) => [s.external_id, iScores[idx]]));
-    const ranked = symbols
+    const ranked = worklistSymbols
         .map((s) => {
         const file = symbolFile(s);
         const incoming_refs = Math.round((incoming.get(s.external_id) ?? 0) * 10) / 10;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orangepro/orangepro-mcp",
-  "version": "0.2.42",
+  "version": "0.2.43",
   "private": false,
   "description": "OrangePro (`opro`) — a local-first, BYOK CLI + MCP server that builds an evidence graph from a local checkout, ingests runtime coverage, and generates grounded tests. Metadata-only exports; no source upload; generated tests stay local.",
   "license": "MIT",
@@ -101,7 +101,7 @@
     "smoke:generate-prove-v5": "npm run build && node scripts/smoke-generate-prove-v5.mjs",
     "smoke:db-sqljs": "npm run build && node scripts/smoke-db-sqljs-prove.mjs",
     "release": "node scripts/release.mjs",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "npm run typecheck && npm run build && npm test"
   },
   "engines": {
     "node": ">=20"