Python CLI that reports SCBench verbosity and erosion composites for supported source codebases.
-
Verbosity: fraction of SLOC flagged by clone detection, ast-grep slop rules, or structural rules. Non-Python languages currently contribute clone lines only.
-
Erosion: share of function "mass" (
complexity * sqrt(sloc)) concentrated in high-complexity functions (cyclomatic complexity > 10). -
Cognitive erosion: same mass-share calculation using cognitive complexity > 10.
Requires Python 3.12+.
Run without installing (recommended):
uvx scb-check check PATH
uvx --from git+https://github.com/gabeorlanski/scb-check scb-check check PATHOr install into the current project:
uv sync # for development in this repo
uv add scb-check # as a dependency elsewhereFor hash-checked dependency installs from this repository, use the exported lock files:
python -m pip install --require-hashes -r requirements.lock
python -m pip install --require-hashes -r requirements-dev.lockRegenerate them after dependency changes with:
uv export --format requirements.txt --no-dev --no-emit-project --frozen --output-file requirements.lock
uv export --format requirements.txt --all-groups --no-emit-project --frozen --output-file requirements-dev.lockscb-check runs bundled ast-grep rules by trying a global sg executable first. If global sg is missing or fails, it falls back to the ast-grep-cli executable installed with scb-check.
scb-check check PATH # human-readable flags
scb-check check PATH --output-format json # JSON report with verbosity/erosion scores
scb-check check PATH --report # shortcut for --output-format json
scb-check check PATH -v / --verbosity # add info logging
scb-check check PATH -vv # add debug logging
scb-check check PATH --config FILE # explicit config path
scb-check check PATH --include-all # include gitignored files plus ignored, lower-severity, and boundary-suppressed findings
scb-check check PATH --disable-sg # skip ast-grep subprocess findings
scb-check check PATH --min-duplicate-lines N # show duplicate groups with at least N SLOC lines
scb-check rule RULE_ID # print YAML or metadata for a specific rulePATH may be a file or directory. Directories are walked for supported source files: Python (.py, .pyw), Rust (.rs), JavaScript (.js, .mjs, .cjs), TypeScript (.ts), Zig (.zig), Haskell (.hs), and C++ (.cpp, .cc, .cxx, .c++, .hpp, .hh, .hxx). Directory discovery respects .gitignore globs by default; use --include-all to scan gitignored supported files too.
verbosity, erosion, cog_erosion, files_scanned, total_loc, verbosity_flagged_loc, clone_loc, ast_grep_flagged_loc, structural_rule_loc, structural_rule_findings, total_functions, high_cc_functions, high_cog_functions, total_mass, high_cc_mass, total_cog_mass, high_cog_mass, syntax_tree_count, syntax_node_count, and syntax_by_language.
syntax_by_language is keyed by language value and reports tree_count plus total Tree-sitter node_count for parsed files in that language.
scb-check check exits 0 when no findings are reported, 1 when any finding is present (clones, ast-grep hits, structural findings, or high-complexity functions), and 2 for usage errors (bad path, missing config, invalid directives).
Clone detection only emits duplicated syntax blocks with at least two executable body statements. Function signatures, comments, blanks, and Python docstrings do not satisfy that threshold; displayed clone line counts and --min-duplicate-lines still use duplicated SLOC in the clone span.
scb-check looks for scb-check.toml or a pyproject.toml containing [tool.scb-check], [tool.ruff], or [tool.ty.src], walking upward from the current directory until it hits a .git root.
# scb-check.toml
exclude = ["tests/fixtures/*", "vendor/**"]
context = 1
[low-use-short-function]
enabled = true
max-call-sites = 2
max-function-sloc = 5
max-inline-caller-sloc = 50
max-inline-caller-complexity = 10
max-inline-caller-cognitive-complexity = 10
max-inline-call-nesting = 3# pyproject.toml
[tool.scb-check]
exclude = ["tests/fixtures/*"]
context = 2
[tool.scb-check.low-use-short-function]
enabled = trueexclude: list of glob patterns to skip while discovering supported source files.context: number of surrounding source lines to show around human-readable ast-grep, structural rule, and erosion findings.low-use-short-function: opt-in budgets for the short low-use helper rule. Setenabled = trueto enable it, then tunemax-call-sites,max-function-sloc,max-inline-caller-sloc,max-inline-caller-complexity,max-inline-caller-cognitive-complexity, andmax-inline-call-nesting.
Configured exclude patterns still apply when --include-all is used; only .gitignore file discovery is extended.
Ast-grep slop rules, structural rules, and source directives are currently Python-only. Rust, JavaScript, TypeScript, Zig, Haskell, and C++ still participate in SLOC totals, clone detection, cyclomatic erosion, and cognitive erosion.
When using pyproject.toml, scb-check also includes excludes from:
[tool.ruff].exclude[tool.ruff].extend-exclude[tool.ty.src].exclude
In Python files, you can suppress specific ast-grep or structural rule findings at the source line level with:
# scbc ignore[rule-id]
# scbc ignore[trivial-wrapper]Same-line form:
value = cfg.get("a", {}).get("b", {}) # scbc ignore[chained-dict-get] Boundary normalization for legacy webhook payloads.Standalone block form:
# scbc ignore[chained-dict-get]
# Boundary normalization for legacy webhook payloads.
value = cfg.get("a", {}).get("b", {})Multiple rule IDs:
# scbc ignore[chained-dict-get,dict-get-empty-dict-default]
# Legacy webhook payloads are partially populated and normalized downstream.
value = cfg.get("a", {}).get("b", {})Function-level boundary suppression is available for code that intentionally validates or normalizes external input:
def _load_toml(path: Path) -> dict[str, Any]:
# scbc boundary: reads and validates user config
...Boundary directives must be inside the function body, after the def line. By default, ast-grep findings inside that function are hidden, and informational ast-grep rules are omitted. Use --include-all to show ignored, informational, and boundary-suppressed ast-grep findings.
Rules:
- Rule IDs inside
ignore[...]are required. - Reason text is optional.
- Same-line ignore directives apply to that same physical line.
- Standalone ignore directives apply to the next non-blank, non-comment code line.
- Boundary directives apply to the containing function body.
- Ast-grep and structural rule findings are suppressible; clone and erosion findings are not.
- Invalid directives fail the run with exit code
2unless--include-allis used.
- Tree walking: language dispatch backed by tree-sitter grammars emits language-agnostic
ModuleIRand semantic project context. - Clone detection: hashed AST blocks across the scanned set; two or more matching instances become a
CloneBlock. - Slop patterns: Python ast-grep rules in
src/scb_check/resources/slop_rules/split by category (e.g.range(len(x)),dict.get(k, None),isinstanceladders, manual min/max, defensive guards). - Structural rules: typed Python classes in
src/scb_check/rules/run over tree-walking IR.trivial-wrapperflags removable single-return pass-through functions (identity returns and calls that only forward parameters to another scanned function), while semantic keep reasons skip constant returns, default-backed value providers, external calls, decorated functions, dunder methods, and inherited API implementations.low-use-short-functionflags short helpers with few resolved call sites only when inlining them would stay within configured caller SLOC, complexity, cognitive complexity, and nesting budgets. - Extra local slop patterns: set
SCB_CHECK_EXTRA_SLOP_RULESto a:-separated list of YAML paths to layer additional rules on top of the bundled set. - Complexity: per-function cyclomatic and cognitive complexity plus SLOC, combined into mass scores for erosion metrics.
uv run pytest
uv run ruff check
uv run ty check src/