pyscn Documentation

CBO (Coupling Between Objects) is an object-oriented design metric that measures the number of distinct classes a given class depends on. It provides a quantitative assessment of inter-class coupling.

A higher CBO value indicates greater dependency on external classes, which increases risks such as:

• Change propagation: Changes to dependent classes may ripple into this class.
• Testing difficulty: More mocks and stubs are required for unit testing.
• Reduced reusability: The class becomes harder to reuse in different contexts.
• Comprehension overhead: Understanding the class requires knowledge of many other classes.

pyscn-mcp is a Model Context Protocol (MCP) server that exposes pyscn's static analysis capabilities as tools for AI agents and MCP clients (such as Claude Code, Cursor, or ChatGPT desktop).

All tools accept path arguments and optional threshold overrides, returning results in structured JSON format.

Available Tools:

• analyze_code: Equivalent to pyscn analyze.
• check_complexity: Complexity analyzer.
• detect_clones: Clone detector.
• check_coupling: CBO analyzer.
• find_dead_code: Dead code analyzer.
• get_health_score: Summary score.

| Tool | Equivalent CLI |
| --- | --- |
| `analyze_code` | `pyscn analyze` |
| `check_complexity` | Complexity analyzer |
| `detect_clones` | Clone detector |
| `check_coupling` | CBO analyzer |
| `find_dead_code` | Dead code analyzer |
| `get_health_score` | Summary score |

Type-1 detection identifies code fragments that are textually identical after normalization. This analysis is opt-in via the EnableTextualAnalysis flag because it requires storing raw source content, which increases memory usage.

Algorithm Steps:

1. Normalization: Removes Python comments (single-line # and multi-line '''/""") and collapses whitespace, maintaining a single separator between word-token boundaries.
2. FNV-64a Hash Comparison: Computes a 64-bit FNV hash of the normalized string. If hashes match, similarity is 1.0.
3. Levenshtein Fallback: If hashes differ, it calculates the Levenshtein edit distance using a space-optimized O(min(m,n)) implementation. Similarity is calculated as: 1.0 - distance / max(len(s1), len(s2)).

pyscn detects four distinct types of code duplication, ranging from literal copy-pasting to semantic equivalence:

1. Type-1 (Identical): Literal copy-paste where only whitespace or comments differ.
2. Type-2 (Renamed Identifiers): The structure is identical, but variable or function names have changed.
3. Type-3 (Modified Copies): A copy of a function that has had statements added or removed (detected via tree edit distance).
4. Type-4 (Same Behavior, Different Implementation): The code is written differently but performs the same logic (detected via control-flow comparison).

While tools like pylint or jscpd typically only catch Type-1 or Type-2, pyscn is designed to detect all four types.

The layer-violation rule flags import statements that violate your defined architectural boundaries. It ensures that modules in one layer do not depend on modules in a forbidden layer, preventing hidden coupling and maintaining testability.

To use this rule, you must define your layers using [[architecture.layers]] (mapping package name fragments to layer names) and then define dependency constraints using [[architecture.rules]].

This rule is triggered by running:

• pyscn analyze
• pyscn check --select deps

The placeholder-comment rule (categorized under mockdata) flags comments containing unfinished-work markers such as TODO, FIXME, XXX, HACK, BUG, or NOTE. This rule helps surface hidden scope and unmanaged technical debt within a codebase.

You can trigger this specific rule using the pyscn check command with the --select mockdata flag.

pyscn check --select mockdata

Dependency depth measures the length of the longest chain of load-time dependencies.

Calculation Logic

1. The analyzer condenses all strongly connected components (SCCs) into single nodes to create a Directed Acyclic Graph (DAG).
2. It calculates the longest path through this DAG using a topological pass.
3. Note: Lazy function and method imports are excluded from depth/topology calculations to avoid including non-load-time dependencies.

Benchmarking Depth

For a project with $N$ modules, the expected maximum depth for a well-structured project is:

expected = max(3, ceil(log2(N + 1)) + 1)

Exceeding this threshold suggests poor layering or excessive transitive coupling.

pyscn represents a Python project as a directed graph where Nodes are Python modules (one per .py file) and Edges are import relationships.

ModuleNode Fields

Each module in the graph tracks the following metadata:

• Name: Dotted module name (e.g., mypackage.submodule)
• FilePath: Absolute path to the .py file
• Package: Top-level package extracted from the name
• IsPackage: true if the file is __init__.py
• InDegree: Fan-in (number of modules importing this module)
• OutDegree: Fan-out (number of modules this module imports)
• Dependencies: Set of outgoing module names
• Dependents: Set of incoming module names

DependencyEdgeTypes

Edges are categorized by the Python syntax used:

• import: import module
• from_import: from module import name
• relative: from .module import name
• implicit: Indirect dependencies

The placeholder-phone-number rule flags phone numbers in string literals that follow obviously fake patterns, such as all zeros (000-0000-0000), sequential digits (123-456-7890, 012-345-6789), or long runs of repeated digits. This rule is part of the mockdata category and is triggered using the pyscn check command.

To avoid this warning, instead of using a fake string, you should leave the field empty, require it from the caller, or pull it from configuration.

# Bad: uses a placeholder pattern
default_phone = "000-0000-0000"

# Good: uses None instead of a fake value
default_phone: str | None = None