codecaliper 0.1.0__py3-none-any.whl

codecaliper/cli.py

@@ -0,0 +1,231 @@
+"""The codecaliper CLI (stdlib argparse — zero extra dependencies).
+
+    codecaliper FILE... [--lang auto|python|java] [--json|--csv] ...
+    codecaliper spec version | list | show RULING-ID
+    codecaliper env                  # the calibration plate
+    codecaliper cite [--format ...]  # methods-section template
+
+Diagnostics go to stderr, data to stdout — pipeline-safe. Exit codes:
+0 success, 1 usage/internal error, 2 completed with error-severity diagnostics.
+"""
+
+from __future__ import annotations
+
+import argparse
+import platform
+import sys
+
+from codecaliper._version import __version__
+from codecaliper.errors import CodecaliperError
+
+
+class _Parser(argparse.ArgumentParser):
+    """argparse exits 2 on usage errors; our contract reserves 2 for
+    'completed with error-severity diagnostics', so usage errors exit 1."""
+
+    def error(self, message: str) -> None:  # type: ignore[override]
+        self.print_usage(sys.stderr)
+        print(f"{self.prog}: error: {message}", file=sys.stderr)
+        raise SystemExit(1)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = argv if argv is not None else sys.argv[1:]
+    if args and args[0] in ("spec", "env", "cite"):
+        return _dispatch_subcommand(args)
+    return _cmd_measure(args)
+
+
+def _measure_parser() -> argparse.ArgumentParser:
+    p = _Parser(
+        prog="codecaliper",
+        description="A cross-language code readability + complexity measurement instrument.",
+    )
+    p.add_argument("files", nargs="+", metavar="FILE")
+    p.add_argument("--lang", default="auto", choices=["auto", "python", "java"])
+    fmt = p.add_mutually_exclusive_group()
+    fmt.add_argument("--json", action="store_true", help="JSON output (default)")
+    fmt.add_argument("--csv", action="store_true", help="wide-format CSV output")
+    p.add_argument("--metrics", default=",".join(
+        ("cyclomatic", "cognitive", "halstead", "maintainability_index", "loc")))
+    p.add_argument("--no-readability", action="store_true")
+    p.add_argument("--bw-granularity", default="file",
+                   choices=["snippet", "function", "file"])
+    p.add_argument("--sonar-compat", action="store_true",
+                   help="cognitive complexity in sonar-compat mode (default: whitepaper)")
+    p.add_argument("--explain", action="store_true",
+                   help="attach per-increment ruling traces (RulingTrace)")
+    p.add_argument("--strict", action="store_true",
+                   help="error exit on parse errors instead of measure-and-label")
+    p.add_argument("-o", "--output", default=None)
+    p.add_argument("--version", action="version", version=f"codecaliper {__version__}")
+    return p
+
+
+def _cmd_measure(argv: list[str]) -> int:
+    from codecaliper import canonical
+    from codecaliper.api import Session
+    from codecaliper.errors import StrictParseError
+    from codecaliper.languages import detect_language
+
+    opts = _measure_parser().parse_args(argv)
+    try:
+        session = Session(
+            metrics=tuple(m for m in opts.metrics.split(",") if m),
+            readability=() if opts.no_readability else ("bw2010",),
+            granularity=opts.bw_granularity,
+            cognitive_mode="sonar-compat" if opts.sonar_compat else "whitepaper",
+            explain=opts.explain,
+            strict=opts.strict,
+        )
+    except CodecaliperError as exc:
+        print(f"codecaliper: error: {exc}", file=sys.stderr)
+        return 1
+    reports = []
+    had_error_diag = False
+    try:
+        for path in opts.files:
+            lang = detect_language(path) if opts.lang == "auto" else opts.lang
+            rep = session.measure_file(path, language=lang)
+            reports.append(rep)
+            for d in rep.diagnostics:
+                print(f"{path}: {d.severity}: {d.code}: {d.message}", file=sys.stderr)
+                if d.severity == "error":
+                    had_error_diag = True
+    except StrictParseError as exc:
+        # --strict: an error-severity condition, per the documented exit contract
+        print(f"codecaliper: error: {exc}", file=sys.stderr)
+        return 2
+    except (CodecaliperError, OSError) as exc:
+        print(f"codecaliper: error: {exc}", file=sys.stderr)
+        return 1
+
+    if opts.csv:
+        out = canonical.to_csv(reports)
+    else:
+        out = "".join(canonical.to_json(r) for r in reports)
+    if opts.output:
+        try:
+            with open(opts.output, "w", encoding="utf-8") as f:
+                f.write(out)
+        except OSError as exc:
+            print(f"codecaliper: error: {exc}", file=sys.stderr)
+            return 1
+    else:
+        sys.stdout.write(out)
+    return 2 if had_error_diag else 0
+
+
+def _dispatch_subcommand(argv: list[str]) -> int:
+    cmd, rest = argv[0], argv[1:]
+    if cmd == "spec":
+        return _cmd_spec(rest)
+    if cmd == "env":
+        return _cmd_env()
+    if cmd == "cite":
+        return _cmd_cite(rest)
+    return 1  # pragma: no cover
+
+
+def _cmd_spec(argv: list[str]) -> int:
+    from codecaliper.spec import iter_rulings, ruling, spec_version
+
+    p = _Parser(prog="codecaliper spec")
+    sub = p.add_subparsers(dest="action", required=True)
+    sub.add_parser("version")
+    lst = sub.add_parser("list")
+    lst.add_argument("--metric", default=None)
+    lst.add_argument("--lang", default=None)
+    show = sub.add_parser("show")
+    show.add_argument("ruling_id")
+    opts = p.parse_args(argv)
+
+    if opts.action == "version":
+        print(spec_version())
+    elif opts.action == "list":
+        for r in iter_rulings(metric=opts.metric, language=opts.lang):
+            mode = f" [{r.mode}]" if r.mode else ""
+            print(f"{r.id}  {r.status:<10} {r.title}{mode}")
+    elif opts.action == "show":
+        try:
+            r = ruling(opts.ruling_id)
+        except CodecaliperError as exc:
+            print(f"codecaliper: error: {exc}", file=sys.stderr)
+            return 1
+        print(f"{r.id} — {r.title}")
+        print(f"metric: {r.metric}   language: {r.language}   status: {r.status}"
+              + (f"   mode: {r.mode}" if r.mode else ""))
+        if r.superseded_by:
+            print(f"superseded by: {r.superseded_by}")
+        print(f"since spec: {r.since_spec}")
+        if r.node_types:
+            print(f"node types: {', '.join(r.node_types)}")
+        if r.examples:
+            print(f"normative cases: {', '.join(r.examples)}")
+        print()
+        print(r.statement)
+    return 0
+
+
+def _cmd_env() -> int:
+    """The calibration plate — what bug reports and papers should quote."""
+    from codecaliper.languages import available_languages, get_adapter
+    from codecaliper.spec import spec_version
+
+    print(f"codecaliper {__version__}")
+    print(f"spec {spec_version()}")
+    print(f"python {platform.python_version()} ({platform.system()} {platform.machine()})")
+    try:
+        import importlib.metadata
+
+        print(f"tree-sitter {importlib.metadata.version('tree-sitter')} (binding)")
+    except Exception:  # noqa: BLE001 - env report must never crash
+        print("tree-sitter binding: not installed")
+    for lang in available_languages():
+        try:
+            info = get_adapter(lang).grammar_info()
+            flag = "calibrated" if info.validated else "UNVALIDATED"
+            print(f"{info.package} {info.version} (ABI {info.abi_version}, {flag})")
+        except CodecaliperError as exc:
+            print(f"{lang}: grammar unavailable: {exc}")
+    return 0
+
+
+def _cmd_cite(argv: list[str]) -> int:
+    from codecaliper.languages import available_languages, get_adapter
+    from codecaliper.spec import spec_version
+
+    p = _Parser(prog="codecaliper cite")
+    p.add_argument("--format", default="text", choices=["text", "bibtex"])
+    opts = p.parse_args(argv)
+    grammars = []
+    for lang in available_languages():
+        try:
+            info = get_adapter(lang).grammar_info()
+            grammars.append(f"{info.package} {info.version}")
+        except CodecaliperError:
+            pass
+    if opts.format == "bibtex":
+        print(
+            "@software{codecaliper,\n"
+            "  author  = {Ji, Yuxiang},\n"
+            "  title   = {codecaliper: a cross-language code readability and "
+            "complexity measurement instrument},\n"
+            f"  version = {{{__version__}}},\n"
+            f"  note    = {{spec {spec_version()}; grammars: {', '.join(grammars)}}},\n"
+            "  url     = {https://github.com/KurathSec/codecaliper}\n"
+            "}"
+        )
+    else:
+        print(
+            f"Metrics were computed with codecaliper {__version__} under mapping "
+            f"specification {spec_version()} (grammars: {', '.join(grammars)}); "
+            "cognitive complexity in whitepaper mode unless stated; readability "
+            "vectors are the raw Buse-Weimer 2010 feature set, with granularity "
+            "and extrapolation as labelled in the output."
+        )
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

codecaliper/errors.py

@@ -0,0 +1,27 @@
+"""Typed error taxonomy. Nothing else escapes the public facade."""
+
+from __future__ import annotations
+
+
+class CodecaliperError(Exception):
+    """Base class for all codecaliper errors."""
+
+
+class UnsupportedLanguageError(CodecaliperError):
+    """The requested language has no registered adapter."""
+
+
+class LanguageDetectionError(CodecaliperError):
+    """--lang auto could not map the file extension; never guess (spec CORE-ALL-0005)."""
+
+
+class GrammarLoadError(CodecaliperError):
+    """A tree-sitter grammar wheel could not be imported or wrapped."""
+
+
+class SpecError(CodecaliperError):
+    """The ruling registry is unreadable, or code cited a phantom ruling ID."""
+
+
+class StrictParseError(CodecaliperError):
+    """--strict was set and the parse tree contains ERROR/MISSING nodes (CORE-ALL-0002)."""

codecaliper/languages/__init__.py

@@ -0,0 +1,44 @@
+"""Language adapter registry — a plain dict, deliberately (ARCHITECTURE.md §14:
+entry-point plugin discovery is deferred until a third-party adapter exists)."""
+
+from __future__ import annotations
+
+from functools import cache
+
+from codecaliper.errors import LanguageDetectionError, UnsupportedLanguageError
+from codecaliper.languages.base import LanguageAdapter
+from codecaliper.spec import require
+
+_BUILTIN = ("python", "java")
+
+R_LANG_AUTO = require("CORE-ALL-0005")  # extension map, never a guess
+
+
+@cache
+def get_adapter(name: str) -> LanguageAdapter:
+    if name == "python":
+        from codecaliper.languages.python import PythonAdapter
+
+        return PythonAdapter()
+    if name == "java":
+        from codecaliper.languages.java import JavaAdapter
+
+        return JavaAdapter()
+    raise UnsupportedLanguageError(
+        f"no adapter for language {name!r}; available: {', '.join(_BUILTIN)}"
+    )
+
+
+def available_languages() -> tuple[str, ...]:
+    return _BUILTIN
+
+
+def detect_language(path: str) -> str:
+    """--lang auto: extension map with an explicit error — never a guess."""
+    lower = path.lower()
+    for name in _BUILTIN:
+        if any(lower.endswith(ext) for ext in get_adapter(name).file_extensions):
+            return name
+    raise LanguageDetectionError(
+        f"cannot detect language of {path!r} from its extension; pass --lang explicitly"
+    )

codecaliper/languages/base.py

@@ -0,0 +1,162 @@
+"""The LanguageAdapter contract.
+
+Metric engines never see tree-sitter node-type strings — only :class:`NodeClass`
+and :class:`~codecaliper.syntax.tokens.TokenKind`. Per-language differences live
+entirely in the adapters' tables and a few named hook methods, every one citing
+a ruling ID; the grammar-integrity and spec-coverage tests hold the tables to
+the compiled grammar and the spec (ARCHITECTURE.md §5).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from codecaliper.model import GrammarInfo, Span
+
+if TYPE_CHECKING:  # pragma: no cover
+    from codecaliper.syntax._treesitter import Node, Parser, Tree
+
+
+class NodeClass(Enum):
+    BRANCH = "branch"                     # if heads
+    ELIF_CONTINUATION = "elif"            # elif / else-if arms (chain-flattened)
+    ELSE_CLAUSE = "else"                  # if-attached else
+    TERNARY = "ternary"
+    SWITCH = "switch"                     # match / switch head
+    CASE_LABEL = "case"
+    LOOP = "loop"
+    CATCH = "catch"
+    BOOL_OP = "boolop"
+    JUMP_LABEL = "labeled-jump"           # break/continue LABEL — flat +1 (COG-JAVA-0001)
+    COMPREHENSION_GUARD = "comp-guard"
+    LAMBDA = "lambda"
+    FUNCTION_DEF = "function"
+    CLASS_DEF = "class"
+    NESTING_ONLY = "nesting-only"         # try / with — no increment, no cognitive nesting
+
+
+@dataclass(frozen=True, slots=True)
+class Classified:
+    node_class: NodeClass
+    rulings: tuple[str, ...]
+    new_sequence: bool = True  # BOOL_OP only: starts a new like-operator sequence (COG-ALL-0003)
+
+
+@dataclass(frozen=True, slots=True)
+class FunctionUnit:
+    name: str
+    qualified_name: str
+    node: Node
+    span: Span
+
+
+def span_of(node: Node) -> Span:
+    return Span(
+        start_line=node.start_point[0] + 1,
+        start_col=node.start_point[1],
+        end_line=node.end_point[0] + 1,
+        end_col=node.end_point[1],
+    )
+
+
+@dataclass
+class LanguageAdapter:
+    """Base adapter: concrete adapters supply tables and small hooks."""
+
+    name: str = ""
+    file_extensions: tuple[str, ...] = ()
+
+    # --- token tables (BW + Halstead + LOC share them; BW-ALL-0006) ---
+    keywords: frozenset[str] = frozenset()
+    soft_keywords: frozenset[str] = frozenset()  # classify as IDENTIFIER (BW-PY-0001)
+    keyword_leaf_types: frozenset[str] = frozenset()
+    identifier_types: frozenset[str] = frozenset()
+    operator_leaf_types: frozenset[str] = frozenset()  # named leaves that are OPERATOR tokens
+    number_types: frozenset[str] = frozenset()
+    string_types: frozenset[str] = frozenset()
+    comment_types: frozenset[str] = frozenset()
+    atomic_types: frozenset[str] = frozenset()
+    arithmetic_ops: frozenset[str] = frozenset()
+    comparison_ops: frozenset[str] = frozenset()
+    assignment_ops: frozenset[str] = frozenset()
+    branch_keywords: frozenset[str] = frozenset()
+    loop_keywords: frozenset[str] = frozenset()
+
+    # Construct-specific tokenization rulings that only govern when their node
+    # type actually lexes (node_type -> ruling id) — cited per-occurrence, like
+    # TOK-ALL-0007, NOT statically the way the atomic-string rulings are.
+    conditional_token_rulings: dict[str, str] = field(default_factory=dict)
+
+    # --- structural tables ---
+    node_class_map: dict[str, tuple[NodeClass, tuple[str, ...]]] = field(default_factory=dict)
+    statement_types: frozenset[str] = frozenset()
+    function_def_types: frozenset[str] = frozenset()
+    class_def_types: frozenset[str] = frozenset()
+
+    _grammar: object = None
+    _parser: Parser | None = None
+    _grammar_info: GrammarInfo | None = None
+
+    # --- parsing ---
+    def _ensure_loaded(self) -> None:
+        if self._parser is None:
+            from codecaliper.syntax import grammars
+
+            self._grammar, self._parser, self._grammar_info = grammars.load(self.name)
+
+    def parse(self, source: bytes) -> Tree:
+        self._ensure_loaded()
+        assert self._parser is not None
+        return self._parser.parse(source)
+
+    def grammar_info(self) -> GrammarInfo:
+        self._ensure_loaded()
+        assert self._grammar_info is not None
+        return self._grammar_info
+
+    def grammar(self) -> object:
+        self._ensure_loaded()
+        return self._grammar
+
+    # --- classification (table lookup; hooks in subclasses for context cases) ---
+    def classify(self, node: Node) -> Classified | None:
+        entry = self.node_class_map.get(node.type)
+        if entry is None:
+            return None
+        return Classified(entry[0], entry[1])
+
+    # --- hooks ---
+    def function_name(self, node: Node) -> str:
+        name = node.child_by_field_name("name")
+        if name is None:
+            return ""
+        return (name.text or b"").decode("utf-8", errors="replace")
+
+    def call_name(self, node: Node) -> str | None:
+        """Simple callee name for the recursion heuristic (COG-ALL-0005), or None."""
+        return None
+
+    def function_units(self, tree: Tree) -> list[FunctionUnit]:
+        from codecaliper.syntax._treesitter import is_opaque, walk
+
+        units: list[FunctionUnit] = []
+        # enclosing-name stack for qualified names, driven by node spans
+        stack: list[tuple[int, str]] = []  # (end_byte, name)
+        opaque_until = -1  # skip everything inside an ERROR subtree (CORE-ALL-0002)
+        for node, _depth in walk(tree):
+            if node.start_byte < opaque_until:
+                continue
+            if is_opaque(node):
+                opaque_until = node.end_byte
+                continue
+            while stack and node.start_byte >= stack[-1][0]:
+                stack.pop()
+            if node.type in self.function_def_types or node.type in self.class_def_types:
+                name = self.function_name(node)
+                if node.type in self.function_def_types:
+                    qual = ".".join([n for _, n in stack] + [name])
+                    units.append(FunctionUnit(name, qual, node, span_of(node)))
+                stack.append((node.end_byte, name))
+        return units

codecaliper/languages/java.py

@@ -0,0 +1,192 @@
+"""Java adapter: tables + contextual hooks, every row citing a ruling.
+
+Verified against tree-sitter-java 0.23.5 node kinds. Java has no else_clause
+node — an `else` is an anonymous token and the else-if chain lives in the
+if_statement's `alternative` field, so both are handled by hooks here.
+"""
+
+from __future__ import annotations
+
+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-JAVA-0001")
+R_CC_TERNARY = require("CC-JAVA-0002")
+R_CC_BOOLOP = require("CC-JAVA-0003")
+R_CC_LOOP = require("CC-JAVA-0004")
+R_CC_CATCH = require("CC-JAVA-0005")
+R_CC_CASE = require("CC-JAVA-0006")
+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_JUMP = require("COG-JAVA-0001")
+R_NESTED_UNITS = require("CORE-ALL-0003")
+R_TOK_UNDERSCORE = require("TOK-JAVA-0002")
+
+# The JLS reserved words except `_`, which is ruled an identifier token
+# (TOK-JAVA-0002, mirroring Python's `_`); true/false/null arrive via
+# keyword_leaf_types (BW-JAVA-0001). Contextual keywords (record, sealed,
+# yield, ...) are identifiers, like every other non-reserved word token
+# (TOK-ALL-0007).
+_JAVA_KEYWORDS = frozenset(
+    """abstract assert boolean break byte case catch char class const continue
+    default do double else enum extends final finally float for goto if
+    implements import instanceof int interface long native new package private
+    protected public return short static strictfp super switch synchronized
+    this throw throws transient try void volatile while""".split()
+)
+
+_NODE_CLASS_MAP: dict[str, tuple[NodeClass, tuple[str, ...]]] = {
+    "ternary_expression": (NodeClass.TERNARY, (R_CC_TERNARY, R_COG_STRUCT)),
+    "for_statement": (NodeClass.LOOP, (R_CC_LOOP, R_COG_STRUCT)),
+    "enhanced_for_statement": (NodeClass.LOOP, (R_CC_LOOP, R_COG_STRUCT)),
+    "while_statement": (NodeClass.LOOP, (R_CC_LOOP, R_COG_STRUCT)),
+    "do_statement": (NodeClass.LOOP, (R_CC_LOOP, R_COG_STRUCT)),
+    "catch_clause": (NodeClass.CATCH, (R_CC_CATCH, R_COG_STRUCT)),
+    "switch_expression": (NodeClass.SWITCH, (R_COG_STRUCT,)),
+    "lambda_expression": (NodeClass.LAMBDA, (R_COG_NESTING,)),
+    "method_declaration": (NodeClass.FUNCTION_DEF, (R_NESTED_UNITS, R_COG_NESTING)),
+    "constructor_declaration": (NodeClass.FUNCTION_DEF, (R_NESTED_UNITS, R_COG_NESTING)),
+    "compact_constructor_declaration": (NodeClass.FUNCTION_DEF, (R_NESTED_UNITS, R_COG_NESTING)),
+    "class_declaration": (NodeClass.CLASS_DEF, (R_NESTED_UNITS,)),
+    "interface_declaration": (NodeClass.CLASS_DEF, (R_NESTED_UNITS,)),
+    "enum_declaration": (NodeClass.CLASS_DEF, (R_NESTED_UNITS,)),
+    "record_declaration": (NodeClass.CLASS_DEF, (R_NESTED_UNITS,)),
+    "try_statement": (NodeClass.NESTING_ONLY, ()),
+    "try_with_resources_statement": (NodeClass.NESTING_ONLY, ()),
+    "synchronized_statement": (NodeClass.NESTING_ONLY, ()),
+}
+
+
+class JavaAdapter(LanguageAdapter):
+    def __init__(self) -> None:
+        super().__init__(
+            name="java",
+            file_extensions=(".java",),
+            keywords=_JAVA_KEYWORDS,
+            keyword_leaf_types=frozenset({"true", "false", "null_literal"}),
+            # underscore_pattern: `_` as an unnamed variable declarator is the
+            # same identifier token as `_` in pattern/lambda positions
+            # (TOK-JAVA-0002)
+            identifier_types=frozenset(
+                {"identifier", "type_identifier", "underscore_pattern"}
+            ),
+            # TOK-JAVA-0002 governs only when an underscore_pattern actually
+            # lexes; cited per-occurrence, not statically (unlike TOK-JAVA-0001)
+            conditional_token_rulings={"underscore_pattern": R_TOK_UNDERSCORE},
+            number_types=frozenset(
+                {
+                    "decimal_integer_literal", "hex_integer_literal",
+                    "octal_integer_literal", "binary_integer_literal",
+                    "decimal_floating_point_literal", "hex_floating_point_literal",
+                }
+            ),
+            string_types=frozenset({"string_literal", "character_literal"}),
+            comment_types=frozenset({"line_comment", "block_comment"}),
+            atomic_types=frozenset({"string_literal", "character_literal"}),  # TOK-JAVA-0001
+            arithmetic_ops=frozenset({"+", "-", "*", "/", "%"}),
+            comparison_ops=frozenset({"==", "!=", "<", ">", "<=", ">="}),
+            assignment_ops=frozenset(
+                {"=", "+=", "-=", "*=", "/=", "%=", "&=", "|=", "^=", "<<=", ">>=", ">>>="}
+            ),
+            branch_keywords=frozenset({"if"}),  # BW-JAVA-0002
+            loop_keywords=frozenset({"for", "while", "do"}),  # BW-JAVA-0002
+            node_class_map=dict(_NODE_CLASS_MAP),
+            statement_types=frozenset(
+                {
+                    "local_variable_declaration", "expression_statement", "return_statement",
+                    "if_statement", "for_statement", "enhanced_for_statement",
+                    "while_statement", "do_statement", "try_statement",
+                    "try_with_resources_statement", "switch_expression", "break_statement",
+                    "continue_statement", "throw_statement", "method_declaration",
+                    "constructor_declaration", "class_declaration", "field_declaration",
+                    "assert_statement", "yield_statement", "labeled_statement",
+                    "synchronized_statement",
+                    # declarations (LOC-ALL-0004 covers declarations too)
+                    "package_declaration", "import_declaration", "interface_declaration",
+                    "enum_declaration", "record_declaration", "annotation_type_declaration",
+                    "annotation_type_element_declaration", "constant_declaration",
+                    "static_initializer", "compact_constructor_declaration",
+                    "explicit_constructor_invocation", "module_declaration",
+                    "requires_module_directive", "exports_module_directive",
+                    "opens_module_directive", "uses_module_directive",
+                    "provides_module_directive",
+                }
+            ),
+            function_def_types=frozenset(
+                {"method_declaration", "constructor_declaration",
+                 "compact_constructor_declaration"}
+            ),
+            class_def_types=frozenset(
+                {"class_declaration", "interface_declaration", "enum_declaration",
+                 "record_declaration"}
+            ),
+        )
+
+    def classify(self, node: Node) -> Classified | None:
+        t = node.type
+        if t == "if_statement":
+            # CC-JAVA-0001 + COG-ALL-0002: an if that is the `alternative` of
+            # another if is an else-if arm — chain-flattened for cognitive.
+            parent = node.parent
+            if (
+                parent is not None
+                and parent.type == "if_statement"
+                and parent.child_by_field_name("alternative") == node
+            ):
+                return Classified(NodeClass.ELIF_CONTINUATION, (R_CC_IF, R_COG_HYBRID))
+            return Classified(NodeClass.BRANCH, (R_CC_IF, R_COG_STRUCT))
+        if t == "else":
+            # Anonymous `else` token: hybrid +1 unless it introduces an else-if
+            # (then the nested if_statement counts instead — no double count).
+            parent = node.parent
+            if parent is not None and parent.type == "if_statement":
+                alt = parent.child_by_field_name("alternative")
+                if alt is not None and alt.type != "if_statement":
+                    return Classified(NodeClass.ELSE_CLAUSE, (R_COG_HYBRID,))
+            return None
+        if t == "binary_expression":
+            op = node.child_by_field_name("operator")
+            op_type = op.type if op is not None else ""
+            if op_type not in ("&&", "||"):
+                return None
+            parent = node.parent
+            same_as_parent = False
+            if parent is not None and parent.type == "binary_expression":
+                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
+            )
+        if t == "switch_label":
+            # CC-JAVA-0006: `case` labels count; `default` does not.
+            first = node.children[0] if node.children else None
+            if first is not None and first.type == "case":
+                return Classified(NodeClass.CASE_LABEL, (R_CC_CASE,))
+            return None
+        if t in ("break_statement", "continue_statement"):
+            # COG-JAVA-0001: only LABELED jumps increment (break LABEL /
+            # continue LABEL); a bare break/continue contributes nothing.
+            if any(child.type == "identifier" for child in node.children):
+                return Classified(NodeClass.JUMP_LABEL, (R_COG_JUMP,))
+            return None
+        return super().classify(node)
+
+    def call_name(self, node: Node) -> str | None:
+        """COG-ALL-0005 receiver rule: bare calls plus this-receiver calls only —
+        a same-named call on another receiver is not recursion."""
+        if node.type != "method_invocation":
+            return None
+        obj = node.child_by_field_name("object")
+        if obj is not None and obj.type != "this":
+            return None
+        name = node.child_by_field_name("name")
+        if name is not None:
+            return (name.text or b"").decode("utf-8", errors="replace")
+        return None