codecaliper 0.1.0__py3-none-any.whl

codecaliper/languages/python.py

@@ -0,0 +1,179 @@
+"""Python adapter: tables + contextual hooks, every row citing a ruling.
+
+Verified against tree-sitter-python 0.25.0 node kinds (test_grammar_integrity
+holds these tables to the compiled grammar).
+"""
+
+from __future__ import annotations
+
+import keyword
+from typing import TYPE_CHECKING
+
+from codecaliper.languages.base import Classified, LanguageAdapter, NodeClass
+from codecaliper.spec import require
+
+if TYPE_CHECKING:  # pragma: no cover
+    from codecaliper.syntax._treesitter import Node
+
+R_CC_IF = require("CC-PY-0001")
+R_CC_ELIF = require("CC-PY-0002")
+R_CC_BOOLOP = require("CC-PY-0003")
+R_CC_COMP_GUARD = require("CC-PY-0004")
+R_CC_LOOP = require("CC-PY-0005")
+R_CC_EXCEPT = require("CC-PY-0006")
+R_CC_TERNARY = require("CC-PY-0007")
+R_CC_CASE = require("CC-PY-0008")
+R_COG_STRUCT = require("COG-ALL-0001")
+R_COG_HYBRID = require("COG-ALL-0002")
+R_COG_BOOLSEQ = require("COG-ALL-0003")
+R_COG_NESTING = require("COG-ALL-0004")
+R_COG_COMPREHENSION = require("COG-PY-0001")
+R_NESTED_UNITS = require("CORE-ALL-0003")
+R_TOK_ELLIPSIS = require("TOK-PY-0003")
+
+# BW-PY-0001's enumerated soft-keyword set (match/case/type/_), pinned so
+# classification is identical across the supported interpreters; asserted at
+# import time to be a superset of the running interpreter's softkwlist so a
+# future CPython addition can't drift silently past this table.
+_SOFT_KEYWORDS = frozenset({"_", "case", "match", "type"})
+assert _SOFT_KEYWORDS >= frozenset(keyword.softkwlist), (
+    f"host softkwlist {keyword.softkwlist} exceeds the pinned BW-PY-0001 set "
+    f"{sorted(_SOFT_KEYWORDS)} — reconcile the ruling before shipping"
+)
+
+_NODE_CLASS_MAP: dict[str, tuple[NodeClass, tuple[str, ...]]] = {
+    "if_statement": (NodeClass.BRANCH, (R_CC_IF, R_COG_STRUCT)),
+    "elif_clause": (NodeClass.ELIF_CONTINUATION, (R_CC_ELIF, R_COG_HYBRID)),
+    "conditional_expression": (NodeClass.TERNARY, (R_CC_TERNARY, R_COG_STRUCT)),
+    "for_statement": (NodeClass.LOOP, (R_CC_LOOP, R_COG_STRUCT)),
+    "while_statement": (NodeClass.LOOP, (R_CC_LOOP, R_COG_STRUCT)),
+    "except_clause": (NodeClass.CATCH, (R_CC_EXCEPT, R_COG_STRUCT)),
+    "match_statement": (NodeClass.SWITCH, (R_COG_STRUCT,)),
+    "case_clause": (NodeClass.CASE_LABEL, (R_CC_CASE,)),
+    "if_clause": (NodeClass.COMPREHENSION_GUARD, (R_CC_COMP_GUARD, R_COG_COMPREHENSION)),
+    "lambda": (NodeClass.LAMBDA, (R_COG_NESTING,)),
+    "function_definition": (NodeClass.FUNCTION_DEF, (R_NESTED_UNITS, R_COG_NESTING)),
+    "class_definition": (NodeClass.CLASS_DEF, (R_NESTED_UNITS,)),
+    "try_statement": (NodeClass.NESTING_ONLY, ()),
+    "with_statement": (NodeClass.NESTING_ONLY, ()),
+}
+
+
+class PythonAdapter(LanguageAdapter):
+    def __init__(self) -> None:
+        super().__init__(
+            name="python",
+            file_extensions=(".py", ".pyi"),
+            # BW-PY-0001: kwlist (True/False/None included; soft keywords are identifiers)
+            keywords=frozenset(keyword.kwlist),
+            # BW-PY-0001: soft keywords are identifiers, matching tokenize NAME.
+            # PINNED to the spec's enumerated set rather than the running
+            # interpreter's keyword.softkwlist — `type` (PEP 695) is absent from
+            # softkwlist before 3.12, which would make provenance for a `type`
+            # alias differ across the supported 3.10-3.14 interpreters.
+            soft_keywords=_SOFT_KEYWORDS,
+            keyword_leaf_types=frozenset({"true", "false", "none"}),
+            identifier_types=frozenset({"identifier"}),
+            # TOK-PY-0003: `...` (named `ellipsis` leaf) is an OPERATOR token,
+            # matching CPython tokenize's OP and Java's varargs `...`; otherwise
+            # it falls through to OTHER and vanishes from Halstead
+            operator_leaf_types=frozenset({"ellipsis"}),
+            number_types=frozenset({"integer", "float"}),
+            string_types=frozenset({"string"}),
+            comment_types=frozenset({"comment"}),
+            # TOK-PY-0002: `string` is atomic; `concatenated_string` is
+            # descended so interleaved comments lex as COMMENT tokens
+            atomic_types=frozenset({"string"}),
+            # BW-ALL-0006 operator classes (spellings mirror the reference extractor)
+            arithmetic_ops=frozenset({"+", "-", "*", "/", "//", "%", "**", "@"}),
+            comparison_ops=frozenset({"==", "!=", "<", ">", "<=", ">=", "<>"}),
+            assignment_ops=frozenset(
+                {"=", "+=", "-=", "*=", "/=", "//=", "%=", "**=",
+                 "&=", "|=", "^=", ">>=", "<<=", "@=", ":="}
+            ),
+            branch_keywords=frozenset({"if", "elif"}),  # BW-PY-0002
+            loop_keywords=frozenset({"for", "while"}),  # BW-PY-0002
+            node_class_map=dict(_NODE_CLASS_MAP),
+            statement_types=frozenset(
+                {
+                    "expression_statement", "return_statement", "pass_statement",
+                    "break_statement", "continue_statement", "import_statement",
+                    "import_from_statement", "future_import_statement",
+                    "raise_statement", "assert_statement",
+                    "delete_statement", "global_statement", "nonlocal_statement",
+                    "if_statement", "for_statement", "while_statement", "try_statement",
+                    "with_statement", "function_definition", "class_definition",
+                    "match_statement", "type_alias_statement",
+                    # legacy py2 syntax the grammar still recognizes
+                    "print_statement", "exec_statement",
+                }
+            ),
+            function_def_types=frozenset({"function_definition"}),
+            class_def_types=frozenset({"class_definition"}),
+            # TOK-PY-0003 governs only when an `...` actually lexes; cited
+            # per-occurrence, not statically
+            conditional_token_rulings={"ellipsis": R_TOK_ELLIPSIS},
+        )
+
+    def classify(self, node: Node) -> Classified | None:
+        t = node.type
+        if t == "if_clause":
+            # CC-PY-0004 scopes to comprehension guards. A case-clause guard is
+            # not separately counted: the guarded case_clause already counts
+            # (CC-PY-0008), and counting the guard too would double-count.
+            parent = node.parent
+            if parent is not None and parent.type == "case_clause":
+                return None
+            return super().classify(node)
+        if t == "case_clause":
+            # CC-PY-0008: a bare-wildcard `case _:` with no guard is the
+            # fall-through path, mirroring Java `default:` (CC-JAVA-0006).
+            patterns = [c for c in node.children if c.type == "case_pattern"]
+            has_guard = node.child_by_field_name("guard") is not None
+            if (
+                len(patterns) == 1
+                and (patterns[0].text or b"") == b"_"
+                and not has_guard
+            ):
+                return None
+            return super().classify(node)
+        if t == "else_clause":
+            # COG-ALL-0002: hybrid +1 only for an if-attached else; for/while/try
+            # else clauses are not branch arms.
+            parent = node.parent
+            if parent is not None and parent.type == "if_statement":
+                return Classified(NodeClass.ELSE_CLAUSE, (R_COG_HYBRID,))
+            return None
+        if t == "boolean_operator":
+            op = node.child_by_field_name("operator")
+            op_type = op.type if op is not None else ""
+            parent = node.parent
+            same_as_parent = False
+            if parent is not None and parent.type == "boolean_operator":
+                pop = parent.child_by_field_name("operator")
+                same_as_parent = pop is not None and pop.type == op_type
+            return Classified(
+                NodeClass.BOOL_OP, (R_CC_BOOLOP, R_COG_BOOLSEQ), new_sequence=not same_as_parent
+            )
+        return super().classify(node)
+
+    def call_name(self, node: Node) -> str | None:
+        """COG-ALL-0005 receiver rule: bare calls plus self./cls. method calls."""
+        if node.type != "call":
+            return None
+        fn = node.child_by_field_name("function")
+        if fn is None:
+            return None
+        if fn.type == "identifier":
+            return (fn.text or b"").decode("utf-8", errors="replace")
+        if fn.type == "attribute":
+            obj = fn.child_by_field_name("object")
+            attr = fn.child_by_field_name("attribute")
+            if (
+                obj is not None
+                and obj.type == "identifier"
+                and (obj.text or b"") in (b"self", b"cls")
+                and attr is not None
+            ):
+                return (attr.text or b"").decode("utf-8", errors="replace")
+        return None

codecaliper/metrics/base.py

@@ -0,0 +1,55 @@
+"""MetricContext — the trace/audit seam every increment routes through.
+
+``ctx.count(ruling, node, delta)`` records which rulings actually fired (for
+``Provenance.rulings_applied``) and, only when ``explain=True``, a per-increment
+:class:`RulingTrace` — zero cost on the default path (ARCHITECTURE.md §3.3).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from codecaliper.model import RulingTrace, Span
+
+if TYPE_CHECKING:  # pragma: no cover
+    from codecaliper.syntax._treesitter import Node
+
+
+@dataclass
+class MetricContext:
+    cognitive_mode: str = "whitepaper"  # "whitepaper" | "sonar-compat"
+    explain: bool = False
+    line_range: tuple[int, int] | None = None  # CORE-JAVA-0001 scaffold restriction
+    line_offset: int = 0  # scaffold lines to subtract so trace spans stay in
+    # original snippet coordinates (CORE-JAVA-0001)
+    domain: tuple[int, int] | None = None  # 1-based line domain of the MEASURED
+    # text; trace spans are clamped into it so a root-node trace can neither
+    # leak scaffold coordinates (CORE-JAVA-0001) nor point past the last
+    # physical line
+    fired: set[str] = field(default_factory=set)
+    traces: dict[str, list[RulingTrace]] = field(default_factory=dict)
+
+    def in_range(self, node: Node) -> bool:
+        if self.line_range is None:
+            return True
+        lo, hi = self.line_range
+        return lo <= node.start_point[0] + 1 <= hi
+
+    def count(self, ruling_id: str, node: Node, delta: float = 1.0, metric: str = "") -> float:
+        self.fired.add(ruling_id)
+        if self.explain:
+            start_line = node.start_point[0] + 1 - self.line_offset
+            end_line = node.end_point[0] + 1 - self.line_offset
+            if self.domain is not None:
+                lo, hi = self.domain
+                start_line = min(max(start_line, lo), hi)
+                end_line = min(max(end_line, lo), hi)
+            span = Span(
+                start_line, node.start_point[1], end_line, node.end_point[1],
+            )
+            self.traces.setdefault(metric, []).append(RulingTrace(ruling_id, span, delta))
+        return delta
+
+    def trace_for(self, metric: str) -> tuple[RulingTrace, ...]:
+        return tuple(self.traces.get(metric, ()))

codecaliper/metrics/cognitive.py

@@ -0,0 +1,111 @@
+"""Cognitive complexity — ONE walker, dual mode (COG-* rulings).
+
+Default mode is whitepaper-faithful; sonar-compat matches the deployed
+Sonar-lineage implementations where they diverge from the paper text. The only
+seed divergence is the recursion increment (COG-ALL-0005 whitepaper /
+COG-ALL-0006 sonar-compat); every future divergence must arrive as a new
+mode-tagged ruling pair, keeping the spec table the authoritative mode diff.
+
+The chain-flattening walk generalizes the proven ``_traverse`` walker from
+Spaghetti Architect's eval/metrics.py onto tree-sitter (NOTICE-credited).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from codecaliper.languages.base import LanguageAdapter, NodeClass
+from codecaliper.metrics.base import MetricContext
+from codecaliper.spec import require
+
+if TYPE_CHECKING:  # pragma: no cover
+    from codecaliper.syntax._treesitter import Node
+
+R_STRUCT = require("COG-ALL-0001")
+R_HYBRID = require("COG-ALL-0002")
+R_BOOLSEQ = require("COG-ALL-0003")
+R_NESTING = require("COG-ALL-0004")
+R_RECURSION_WP = require("COG-ALL-0005")
+R_NO_RECURSION_SONAR = require("COG-ALL-0006")
+
+_STRUCTURAL = frozenset(
+    {NodeClass.BRANCH, NodeClass.LOOP, NodeClass.CATCH, NodeClass.SWITCH, NodeClass.TERNARY}
+)
+_HYBRID = frozenset({NodeClass.ELIF_CONTINUATION, NodeClass.ELSE_CLAUSE})
+
+
+def cognitive(
+    root: Node,
+    adapter: LanguageAdapter,
+    ctx: MetricContext,
+    *,
+    exclude_nested_units: bool = False,
+    initial_function_names: tuple[str, ...] = (),
+) -> int:
+    """Cognitive complexity of ``root``'s subtree.
+
+    ``initial_function_names`` seeds the enclosing-function name stack when the
+    root itself is a function unit (recursion heuristic, COG-ALL-0005).
+    """
+    total = 0
+    whitepaper = ctx.cognitive_mode == "whitepaper"
+    fdepth0 = 1 if initial_function_names else 0
+    # stack entries: (node, nesting, function_depth, enclosing_function_names)
+    stack: list[tuple[Node, int, int, tuple[str, ...]]] = [
+        (child, 0, fdepth0, initial_function_names) for child in reversed(root.children)
+    ]
+    from codecaliper.syntax._treesitter import is_opaque
+
+    while stack:
+        node, nesting, fdepth, names = stack.pop()
+        if is_opaque(node):
+            continue  # CORE-ALL-0002: ERROR/MISSING subtrees are opaque
+        child_nesting, child_fdepth, child_names = nesting, fdepth, names
+        c = adapter.classify(node)
+        if c is not None:
+            k = c.node_class
+            if k in _STRUCTURAL:
+                if ctx.in_range(node):
+                    total += int(ctx.count(R_STRUCT, node, 1 + nesting, metric="cognitive"))
+                    if nesting > 0:
+                        ctx.fired.add(R_NESTING)  # the nesting penalty rule applied
+                child_nesting += 1  # COG-ALL-0004
+            elif k in _HYBRID:
+                if ctx.in_range(node):
+                    total += int(ctx.count(R_HYBRID, node, 1, metric="cognitive"))
+                # chain flattening: no extra nesting beyond the chain head's
+            elif k is NodeClass.BOOL_OP:
+                if c.new_sequence and ctx.in_range(node):
+                    total += int(ctx.count(R_BOOLSEQ, node, 1, metric="cognitive"))
+            elif k is NodeClass.JUMP_LABEL:
+                # labeled jumps: flat +1, both modes, no nesting effect
+                # (whitepaper B1 fundamental increment; sonar-java implements it)
+                if ctx.in_range(node):
+                    for r in c.rulings:
+                        if r.startswith("COG-"):
+                            total += int(ctx.count(r, node, 1, metric="cognitive"))
+                            break
+            elif k in (NodeClass.FUNCTION_DEF, NodeClass.LAMBDA):
+                if exclude_nested_units and k is NodeClass.FUNCTION_DEF:
+                    continue  # CORE-ALL-0003: nested units get their own reports
+                if fdepth > 0:
+                    child_nesting += 1  # COG-ALL-0004: only NESTED units deepen
+                    ctx.fired.add(R_NESTING)
+                child_fdepth += 1
+                if k is NodeClass.FUNCTION_DEF:
+                    child_names = names + (adapter.function_name(node),)
+            elif k is NodeClass.CLASS_DEF:
+                if exclude_nested_units:
+                    continue
+                # class bodies do not deepen cognitive nesting (COG-ALL-0004)
+        if whitepaper and names:
+            callee = adapter.call_name(node)
+            if callee is not None and callee == names[-1] and ctx.in_range(node):
+                total += int(ctx.count(R_RECURSION_WP, node, 1, metric="cognitive"))
+        elif not whitepaper:
+            ctx.fired.add(R_NO_RECURSION_SONAR)
+        stack.extend(
+            (child, child_nesting, child_fdepth, child_names)
+            for child in reversed(node.children)
+        )
+    return total

codecaliper/metrics/cyclomatic.py

@@ -0,0 +1,62 @@
+"""Cyclomatic complexity: 1 + decision points over NodeClass (CC-* rulings)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from codecaliper.languages.base import LanguageAdapter, NodeClass
+from codecaliper.metrics.base import MetricContext
+from codecaliper.spec import require
+
+if TYPE_CHECKING:  # pragma: no cover
+    from codecaliper.syntax._treesitter import Node
+
+R_BASE = require("CC-ALL-0001")
+
+_DECISION_CLASSES = frozenset(
+    {
+        NodeClass.BRANCH,
+        NodeClass.ELIF_CONTINUATION,
+        NodeClass.LOOP,
+        NodeClass.CATCH,
+        NodeClass.CASE_LABEL,
+        NodeClass.TERNARY,
+        NodeClass.COMPREHENSION_GUARD,
+        NodeClass.BOOL_OP,
+    }
+)
+
+
+def cyclomatic(
+    root: Node,
+    adapter: LanguageAdapter,
+    ctx: MetricContext,
+    *,
+    exclude_nested_units: bool = False,
+) -> int:
+    """Decision points in ``root``'s subtree (root itself excluded from unit
+    exclusion so a function node can be measured as a unit, CORE-ALL-0003)."""
+    from codecaliper.syntax._treesitter import is_opaque
+
+    # the base path is itself a counted increment: CC-ALL-0001 fires for every
+    # emitted cyclomatic value, so provenance and --explain carry it
+    total = int(ctx.count(R_BASE, root, 1, metric="cyclomatic"))
+    stack = list(reversed(root.children))
+    while stack:
+        node = stack.pop()
+        if is_opaque(node):
+            continue  # CORE-ALL-0002: ERROR/MISSING subtrees are opaque
+        c = adapter.classify(node)
+        if c is not None:
+            if exclude_nested_units and c.node_class in (
+                NodeClass.FUNCTION_DEF,
+                NodeClass.CLASS_DEF,
+            ):
+                continue  # nested units get their own reports (CORE-ALL-0003)
+            if c.node_class in _DECISION_CLASSES and ctx.in_range(node):
+                for r in c.rulings:
+                    if r.startswith("CC-"):
+                        total += int(ctx.count(r, node, 1, metric="cyclomatic"))
+                        break
+        stack.extend(reversed(node.children))
+    return total

codecaliper/metrics/halstead.py

@@ -0,0 +1,55 @@
+"""Lexical Halstead over the unified token stream (HAL-ALL-0001).
+
+Deliberately uniform cross-language: operators are OPERATOR/KEYWORD/PUNCT
+tokens, operands are IDENTIFIER/NUMBER/STRING tokens. Absolute values are
+implementation-defined (only trends/ratios are stable); every emitted value
+carries the halstead-approximation diagnostic. The divergence vs AST-harvest
+implementations (radon, the stdlib reference lane) is declared (no Halstead
+differential oracle runs; the label is the disclosure).
+"""
+
+from __future__ import annotations
+
+import math
+
+from codecaliper.model import Diagnostic
+from codecaliper.spec import require
+from codecaliper.syntax.tokens import LexicalToken, TokenKind
+
+R_LEXICAL = require("HAL-ALL-0001")
+
+APPROX_DIAGNOSTIC = Diagnostic(
+    severity="info",
+    code="halstead-approximation",
+    message="Halstead values are a lexical approximation; absolute values are "
+    "implementation-defined, only trends/ratios are stable (HAL-ALL-0001).",
+    ruling=R_LEXICAL,
+)
+
+_OPERATOR_KINDS = frozenset({TokenKind.OPERATOR, TokenKind.KEYWORD, TokenKind.PUNCT})
+_OPERAND_KINDS = frozenset({TokenKind.IDENTIFIER, TokenKind.NUMBER, TokenKind.STRING})
+
+
+def halstead(tokens: list[LexicalToken]) -> dict[str, float]:
+    operators: list[str] = []
+    operands: list[str] = []
+    for tok in tokens:
+        if tok.kind in _OPERATOR_KINDS:
+            operators.append(tok.text)
+        elif tok.kind in _OPERAND_KINDS:
+            operands.append(tok.text)
+    n1, big_n1 = len(set(operators)), len(operators)
+    n2, big_n2 = len(set(operands)), len(operands)
+    n, big_n = n1 + n2, big_n1 + big_n2
+    volume = big_n * math.log2(n) if n > 0 else 0.0
+    difficulty = (n1 / 2) * (big_n2 / n2) if n2 > 0 else 0.0
+    effort = difficulty * volume
+    return {
+        "halstead.n1": float(n1),
+        "halstead.N1": float(big_n1),
+        "halstead.n2": float(n2),
+        "halstead.N2": float(big_n2),
+        "halstead.volume": volume,
+        "halstead.difficulty": difficulty,
+        "halstead.effort": effort,
+    }

codecaliper/metrics/loc.py

@@ -0,0 +1,62 @@
+"""Line counting (LOC-* rulings) — coverage measures over the token stream.
+
+sloc counts lines covered by code-token spans, so multi-line strings count on
+every line they span; this is exactly where the demoted regex lane provably
+fails (ARCHITECTURE.md §6) and the corpus proves it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from codecaliper.languages.base import LanguageAdapter
+from codecaliper.metrics.base import MetricContext
+from codecaliper.spec import require
+from codecaliper.syntax.tokens import LexicalToken, TokenKind
+
+if TYPE_CHECKING:  # pragma: no cover
+    from codecaliper.syntax._treesitter import Node
+
+R_PHYSICAL = require("LOC-ALL-0001")
+R_SLOC = require("LOC-ALL-0002")
+R_CLOC = require("LOC-ALL-0003")
+R_LLOC = require("LOC-ALL-0004")
+R_TOK_LINES = require("TOK-ALL-0005")  # line attribution for sloc/comment coverage
+
+
+def loc_metrics(
+    lines: list[str],
+    tokens: list[LexicalToken],
+    root: Node,
+    adapter: LanguageAdapter,
+    ctx: MetricContext,
+) -> dict[str, int]:
+    physical = len(lines)
+    blank = sum(1 for ln in lines if not ln.strip())
+
+    code_lines: set[int] = set()
+    comment_lines: set[int] = set()
+    for tok in tokens:
+        target = comment_lines if tok.kind is TokenKind.COMMENT else code_lines
+        for line in range(tok.line, tok.end_line + 1):
+            target.add(line)
+
+    from codecaliper.syntax._treesitter import is_opaque
+
+    lloc = 0
+    stack = [root]
+    while stack:
+        node = stack.pop()
+        if is_opaque(node):
+            continue  # CORE-ALL-0002: ERROR/MISSING subtrees are opaque
+        if node.type in adapter.statement_types and ctx.in_range(node):
+            lloc += int(ctx.count(R_LLOC, node, 1, metric="lloc"))
+        stack.extend(reversed(node.children))
+
+    return {
+        "physical_lines": physical,
+        "blank_lines": blank,
+        "sloc": len(code_lines),
+        "comment_lines": len(comment_lines),
+        "lloc": lloc,
+    }

codecaliper/metrics/mi.py

@@ -0,0 +1,31 @@
+"""Maintainability index (MI-ALL-0001) — derived, and it says so in the types.
+
+MI contains the CC term; it is NOT independent of cyclomatic complexity
+(ARCHITECTURE.md §13). Every value carries derived_from and mi-contains-cc.
+"""
+
+from __future__ import annotations
+
+import math
+
+from codecaliper.model import Diagnostic
+from codecaliper.spec import require
+
+R_MI = require("MI-ALL-0001")
+
+DERIVED_FROM = ("halstead.volume", "cyclomatic", "sloc")
+
+CONTAINS_CC_DIAGNOSTIC = Diagnostic(
+    severity="info",
+    code="mi-contains-cc",
+    message="MI is derived from Halstead volume, cyclomatic complexity and SLOC; "
+    "do not treat MI and CC as independent signals (MI-ALL-0001).",
+    ruling=R_MI,
+)
+
+
+def maintainability_index(volume: float, cc: int, sloc: int) -> float:
+    v = max(volume, 1e-9)
+    s = max(sloc, 1)
+    mi = (171.0 - 5.2 * math.log(v) - 0.23 * cc - 16.2 * math.log(s)) * 100.0 / 171.0
+    return max(0.0, min(100.0, mi))