feat: add support for cognitive complexity analysis in Python

[askpt]

Summary

Add support for analyzing and displaying Cognitive Complexity metrics for Python files using the Visual Studio Code extension.

Motivation

Python is a widely used language in many codebases. Supporting Python will extend the practicality of this extension and address a key user need, as many teams want to measure cognitive complexity across multi-language projects.

Acceptance Criteria

• Cognitive Complexity analysis is available for Python files (.py).
• Accurate analysis based on SonarSource's Cognitive Complexity specification for Python syntax.
• CodeLens overlays show complexity scores above each function/method in Python files, with proper color coding (green/yellow/red) based on user-configurable thresholds.
• Configuration options (thresholds, enabling/disabling CodeLens, etc.) are updated to allow/disable analysis for Python, as is currently supported for C# and Go.
• Tests are implemented for Python analysis logic.

Out of Scope

• Refactoring or expanding other language support (non-Python-specific changes).

Additional Notes

• Implementation should use Tree-sitter or equivalent robust parsing to ensure accurate metric calculation for Python code, similar to existing support for C# and Go.
• Consider potential edge cases in Python (e.g., nested functions, comprehensions).

[github-actions]

🎯 Agentic Issue Triage

Type: Feature Request — New Language Support
Summary: Add cognitive complexity analysis for Python (.py) files using Tree-sitter, following the same pattern already established for C#, Go, JavaScript, and TypeScript.

The codebase is well-structured for this extension — adding Python support is a well-contained change following an existing, clear pattern.

---

📐 Architecture & Implementation Pattern

The extension uses a factory pattern with lazy-loaded, language-specific Tree-sitter analyzers. Here's the full map of what needs to change:

File	Change
src/metricsAnalyzer/languages/pythonAnalyzer.ts	New file — Mirror goAnalyzer.ts or csharpAnalyzer.ts
src/metricsAnalyzer/metricsAnalyzerFactory.ts	Add python: createAnalyzer("./languages/pythonAnalyzer", "PythonMetricsAnalyzer") to languageAnalyzers
package.json	Add onLanguage:python to activationEvents and add python to any language-scoped configuration
src/test/ or src/unit/	Add unit tests for Python complexity analysis
samples/	Add a Test.py sample file for manual testing

📦 Dependency

Install the Tree-sitter Python grammar:

npm install tree-sitter-python

The tree-sitter-python package is the official grammar and is already available on npm — consistent with how tree-sitter-c-sharp and tree-sitter-go are used.

🐍 Python-Specific Complexity Constructs

When implementing pythonAnalyzer.ts, the following Python AST node types (from tree-sitter-python) map to cognitive complexity increments:

+1 structural increments (also increase nesting):

• if_statement / elif_clause
• for_statement / while_statement
• try_statement / except_clause
• with_statement
• match_statement / case_clause (Python 3.10+)

+1 flat increments:

• binary_operator with and / or
• break_statement / continue_statement (when nested)

Edge cases to handle carefully:

• Nested functions (function_definition inside another function_definition) — should be analyzed as separate top-level entries (not counted in parent), same as Go closures
• Lambda expressions — count as +1 if nested inside another function/lambda
• List/set/dict comprehensions (list_comprehension, set_comprehension, dictionary_comprehension, generator_expression) — each for clause within a comprehension should add complexity; comprehensions are nesting structures
• Decorators — do not contribute to complexity
• Class methods — each function_definition inside a class_definition is analyzed independently; use ClassName.method_name format for display (similar to Go's Receiver.MethodName)

🔨 Implementation Checklist

• Install tree-sitter-python npm dependency
• Create src/metricsAnalyzer/languages/pythonAnalyzer.ts implementing PythonMetricsAnalyzer class with a static analyzeFile(sourceText: string) method
• Register python in languageAnalyzers in metricsAnalyzerFactory.ts
• Add "onLanguage:python" to activationEvents in package.json
• Update configuration schema in package.json if per-language enable/disable is supported
• Add samples/Test.py with representative complex Python code
• Add unit tests covering: simple function, nested control flow, comprehension, nested function, class methods, lambda, try/except, with statement
• Run npm run compile && npm run lint to verify no regressions

🔗 Helpful Resources

• [tree-sitter-python npm package]((www.npmjs.com/redacted)
• Tree-sitter Python grammar node types
• [SonarSource Cognitive Complexity whitepaper]((www.sonarsource.com/redacted) — the specification this extension implements
• Existing Go analyzer for reference
• Related: feat: add support for cognitive complexity analysis in Java #238 (Java support request follows the same implementation pattern)

💡 Implementation Nudges

• The createAnalyzer() helper in metricsAnalyzerFactory.ts handles the 0-based → 1-based line/column normalization automatically — your analyzer just needs to return 0-based positions.
• The module-level singleton pattern (const _parser = new Parser(); _parser.setLanguage(Python)) used in goAnalyzer.ts should be replicated to avoid expensive repeated parser initialization.
• Python's elif is a separate elif_clause node in the tree-sitter AST — treat it the same as if_statement for complexity purposes (it's an else if structural element).
• Unlike Go, Python uses indentation rather than braces — Tree-sitter handles this transparently; the AST structure will look similar to other languages.

Generated by Agentic Triage for issue #237 · ● 369.8K · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/issue-triage.md@7c7feb61a52b662eb2089aa2945588b7a200d404