feat(pyscn): integrate pyscn code quality gate into CI

.github/workflows/tests.yml

@@ -47,6 +47,9 @@ jobs:
       - name: Lint with Sqlfluff
         run: make lint-sql
 
+      - name: Quality check with pyscn
+        run: make lint-quality
+
   type-check:
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -53,6 +53,7 @@ coverage.xml
 .hypothesis/
 .pytest_cache/
 cover/
+.pyscn/
 
 # Translations
 *.mo

.pre-commit-config.yaml

@@ -41,6 +41,15 @@ repos:
     - id: interrogate
       pass_filenames: false  # config (incl. exclude paths) lives in pyproject.toml
 
+# pyscn (code quality gate: complexity, dead code, clones, circular deps)
+- repo: local
+  hooks:
+    - id: pyscn
+      name: pyscn
+      entry: uv run pyscn check
+      language: system
+      pass_filenames: false
+
 # sqlfluff
 - repo: https://github.com/sqlfluff/sqlfluff
   rev: 3.5.0

Makefile

@@ -39,7 +39,7 @@ lock:
 format:
 	uv run ruff format --check .
 
-lint: lint-python lint-sql lint-docstrings
+lint: lint-python lint-sql lint-docstrings lint-quality
 
 lint-python:
 	uv run ruff check --output-format=github .
@@ -50,6 +50,9 @@ lint-sql:
 lint-docstrings:
 	uv run interrogate
 
+lint-quality:
+	uv run pyscn check .
+
 type:
 	uv run pyrefly check
 

README.md

@@ -100,6 +100,7 @@ The checks contained in this repo include (in the order in which they run):
 * `pyrefly` is used for static type checking
 * `sqlfluff` checks and fixes sql formatting and linting
 * `interrogate` checks docstring coverage
+* `pyscn` checks code quality (complexity, dead code, clones, circular deps)
 * `uv` checks on valid and aligned pyproject.toml and uv.lock files
 * `commitlint` enforces commit message conforms to [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) format
 

pyproject.toml

@@ -29,6 +29,7 @@ dev = [
     "nox >=2024.4.15,<2025",
     "prek >=0.1.0,<1",
     "pyrefly >=1.2.0,<2",
+    "pyscn >=1.31.2,<2",
     "pytest >=8.3.2,<9",
     "pytest-cov >=5.0.0,<6",
     "python-semantic-release >=10.0.0,<11",
@@ -52,6 +53,39 @@ verbose = 1
 exclude = ["tests", "docs", "noxfile.py"]
 
 
+#######
+# Pyscn
+#######
+# Code quality gate: complexity, dead code, clones, coupling, architecture.
+# This only sets what deviates from pyscn's own defaults (or is left as an
+# explicit toggle). Full option reference: https://docs.codescan.dev/configuration/reference/
+
+[tool.pyscn.output]
+format = "text"                 # Default output format: text, json, yaml, csv, html
+show_details = false             # Show detailed breakdown by default
+sort_by = "complexity"           # Default sort: name, complexity, risk
+min_complexity = 1               # Minimum complexity to report
+directory = ""                   # Output directory for reports (empty = default .pyscn/reports/, gitignored)
+
+[tool.pyscn.complexity]
+enabled = true                   # Enable complexity analysis
+low_threshold = 9                # Functions with complexity ≤ 9 are low risk
+medium_threshold = 19            # Functions with complexity 10-19 are medium risk
+                                  # Functions with complexity ≥ 20 are high risk
+max_complexity = 0               # Maximum allowed complexity (0 = no limit). Must be 0 or > medium_threshold;
+                                  # the CI gate's own limit (10) is set independently via `pyscn check --max-complexity`
+report_unchanged = true          # Report functions with complexity = 1
+
+[tool.pyscn.dead_code]
+enabled = true                   # Enable dead code detection; see reference link above for tunable options
+
+[tool.pyscn.cbo]
+enabled = true                   # Enable class coupling (CBO) analysis; see reference link above for tunable options
+
+[tool.pyscn.architecture]
+enabled = false                  # This project is a flat single-package library, not a layered app
+
+
 ##########
 # Coverage
 ##########