codecaliper 0.1.0__py3-none-any.whl

codecaliper/spec/registry.py

@@ -0,0 +1,112 @@
+"""The ruling registry: loads the versioned metric-to-syntax mapping spec.
+
+Rulings are machine-readable TOML package data with immutable IDs
+(``{METRIC}-{LANG}-{NNNN}``). ``require()`` raises :class:`SpecError` the moment
+code cites a phantom ID, so the code and the spec cannot drift apart silently
+(ARCHITECTURE.md §3.3).
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from functools import lru_cache
+from importlib import resources
+from typing import Any
+
+from codecaliper.errors import SpecError
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - py3.10 fallback
+    import tomli as tomllib
+
+_RULING_FILES = (
+    "core.toml",
+    "tokenization.toml",
+    "cyclomatic.toml",
+    "cognitive.toml",
+    "halstead.toml",
+    "mi.toml",
+    "loc.toml",
+    "bw.toml",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Ruling:
+    id: str
+    metric: str
+    language: str  # "all" | "python" | "java" | ...
+    title: str
+    statement: str
+    status: str = "active"  # active | draft | superseded
+    since_spec: str = "0.1.0"
+    mode: str = ""  # cognitive only: "whitepaper" | "sonar-compat" | "" (both)
+    node_types: tuple[str, ...] = ()  # tree-sitter node types this ruling binds to
+    examples: tuple[str, ...] = ()  # normative consistency-corpus case IDs
+    superseded_by: str = ""
+
+
+def _load_toml(name: str) -> dict[str, Any]:
+    ref = resources.files("codecaliper.spec") / "rulings" / name
+    with ref.open("rb") as f:
+        data: dict[str, Any] = tomllib.load(f)
+    return data
+
+
+@lru_cache(maxsize=1)
+def spec_version() -> str:
+    return str(_load_toml("index.toml")["spec"]["version"])
+
+
+@lru_cache(maxsize=1)
+def _registry() -> dict[str, Ruling]:
+    rulings: dict[str, Ruling] = {}
+    for fname in _RULING_FILES:
+        data = _load_toml(fname)
+        for raw in data.get("ruling", []):
+            r = Ruling(
+                id=raw["id"],
+                metric=raw["metric"],
+                language=raw["language"],
+                title=raw["title"],
+                statement=raw["statement"].strip(),
+                status=raw.get("status", "active"),
+                since_spec=raw.get("since_spec", "0.1.0"),
+                mode=raw.get("mode", ""),
+                node_types=tuple(raw.get("node_types", [])),
+                examples=tuple(raw.get("examples", [])),
+                superseded_by=raw.get("superseded_by", ""),
+            )
+            if r.id in rulings:
+                raise SpecError(f"duplicate ruling id {r.id!r} in {fname}")
+            rulings[r.id] = r
+    return rulings
+
+
+def require(ruling_id: str) -> str:
+    """Assert the ruling exists and return its ID (call at module import time)."""
+    if ruling_id not in _registry():
+        raise SpecError(
+            f"code cites phantom ruling {ruling_id!r}; add it to the spec or fix the citation"
+        )
+    return ruling_id
+
+
+def ruling(ruling_id: str) -> Ruling:
+    try:
+        return _registry()[ruling_id]
+    except KeyError:
+        raise SpecError(f"unknown ruling {ruling_id!r}") from None
+
+
+def iter_rulings(metric: str | None = None, language: str | None = None) -> tuple[Ruling, ...]:
+    out = []
+    for r in _registry().values():
+        if metric is not None and r.metric != metric:
+            continue
+        if language is not None and r.language not in (language, "all"):
+            continue
+        out.append(r)
+    return tuple(out)

codecaliper/spec/rulings/bw.toml

@@ -0,0 +1,156 @@
+# BW-*: Buse-Weimer (2010) Fig. 6 feature delimitation rulings.
+# The paper is ambiguous about token delimitation, comment counting and
+# normalization (ARCHITECTURE.md §7); every ambiguity is pinned here. Rulings marked
+# PROVISIONAL will be arbitrated empirically by the ARCHITECTURE.md §8.3 faithfulness pipeline
+# and superseded if the arbitration disagrees — with the experiment recorded.
+
+[[ruling]]
+id = "BW-ALL-0001"
+metric = "bw2010"
+language = "all"
+title = "The 25 features, canonical order, raw vector only"
+statement = """
+The feature set is the 25 features of Buse & Weimer 2010 Fig. 6, emitted in the
+canonical order inherited from the reference implementation
+(avg_line_length ... max_identifier_occurrences). Output is always the raw
+feature vector; no scalar readability score exists anywhere in this tool
+(ARCHITECTURE.md §13). Average features divide by the number of lines; max features
+take the maximum.
+"""
+examples = ["py-cc-boolop-001"]
+
+[[ruling]]
+id = "BW-ALL-0002"
+metric = "bw2010"
+language = "all"
+title = "Granularity labelling and the calibrated regime"
+statement = """
+granularity is one of snippet | function | file; anything other than snippet is
+extrapolation beyond the model's native unit and is labelled with
+extrapolated=true plus a diagnostic. Even at snippet granularity, a diagnostic
+warns when the unit falls outside the paper's 4-11 line calibrated regime.
+"""
+examples = ["java-snippet-constructor-001"]
+
+[[ruling]]
+id = "BW-ALL-0003"
+metric = "bw2010"
+language = "all"
+title = "A comment token counts once (PROVISIONAL)"
+statement = """
+avg_comments counts comment TOKENS divided by lines; a multi-line block comment
+counts once (on its start line), mirroring the stdlib-tokenize reference
+behaviour for line comments. PROVISIONAL: per-spanned-line counting is the
+alternative; the faithfulness pipeline will arbitrate.
+"""
+examples = ["java-block-comment-001"]
+
+[[ruling]]
+id = "BW-ALL-0004"
+metric = "bw2010"
+language = "all"
+title = "Token-level features exclude string contents; character features use raw text"
+statement = """
+Punctuation/operator features (periods, commas, parentheses, arithmetic,
+comparisons, assignments) count TOKENS, so punctuation inside string literals
+and comments is invisible to them. Character-level features (line length,
+indentation, spaces, max_char_occurrences) always use the raw normalized text
+of every line, strings included.
+"""
+examples = ["py-multiline-string-001"]
+
+[[ruling]]
+id = "BW-ALL-0005"
+metric = "bw2010"
+language = "all"
+title = "Identifier-length feature is the mean of per-line maxima"
+statement = """
+avg_identifier_length = mean over all lines of (the longest identifier on that
+line, 0 for lines without identifiers); max_identifier_length is the global
+maximum. Faithful to the reference implementation's reading of Fig. 6
+('average/maximum value per line').
+"""
+examples = ["py-try-except-001"]
+
+[[ruling]]
+id = "BW-ALL-0006"
+metric = "bw2010"
+language = "all"
+title = "Operator classes are adapter tables"
+statement = """
+Which operator spellings count as arithmetic / comparison / assignment is a
+per-language adapter table, part of the spec surface. Short-circuit operators
+(and/or, &&/||) are NOT in these classes: Python's are keywords (counted by
+avg_keywords), Java's are uncategorized operators.
+"""
+examples = ["py-comprehension-001"]
+
+[[ruling]]
+id = "BW-PY-0001"
+metric = "bw2010"
+language = "python"
+title = "Python keyword set"
+statement = """
+Keywords are keyword.kwlist of the reference CPython (True/False/None
+included). Soft keywords (match/case/type/_) count as identifiers, matching the
+stdlib tokenize reference.
+"""
+examples = ["py-try-except-001"]
+
+[[ruling]]
+id = "BW-PY-0002"
+metric = "bw2010"
+language = "python"
+title = "Python branch/loop keyword features"
+statement = """
+avg_branches counts if/elif keyword tokens; avg_loops counts for/while keyword
+tokens (including comprehension for/if keywords, which are lexically identical
+- faithful to the reference's lexical reading).
+"""
+examples = ["py-elif-chain-001"]
+
+[[ruling]]
+id = "BW-JAVA-0001"
+metric = "bw2010"
+language = "java"
+title = "Java keyword set"
+statement = """
+Keywords are the JLS reserved words plus the literals true/false/null —
+procedurally consistent with Python, whose kwlist includes True/False/None.
+(Editorial clarification in spec 1.1.0: the table deliberately omits the
+reserved word `_` — JLS §3.9 lists it since SE 9 — because `_` is ruled an
+identifier token in every position (TOK-JAVA-0002), mirroring BW-PY-0001's
+treatment of Python's `_`. The normative table is unchanged.)
+"""
+
+[[ruling]]
+id = "BW-JAVA-0002"
+metric = "bw2010"
+language = "java"
+title = "Java branch/loop keyword features"
+statement = """
+avg_branches counts `if` keyword tokens (an else-if contributes via its `if`);
+avg_loops counts for/while/do keyword tokens.
+"""
+examples = ["java-elseif-001"]
+
+[[ruling]]
+id = "BW-ALL-0007"
+metric = "bw2010"
+language = "all"
+title = "Token-family features use the full lexical stream, ERROR regions included"
+since_spec = "1.0.0"
+statement = """
+The BW construct is lexical: the original instrument was grammar-less and saw
+every token of every (frequently non-compilable) snippet. When the parse tree
+contains errors, token-family BW features are therefore computed over the FULL
+leaf stream, descending into ERROR subtrees (MISSING nodes are zero-width
+fabrications and still yield nothing), and the vector carries a
+bw-lexical-fallback diagnostic. This deliberately scopes CORE-ALL-0002, which
+continues to govern every metric (cyclomatic, cognitive, Halstead, LOC):
+zeroing lexical features on fragments silently changes the construct — a
+parser-based reimplementation degraded on 71/100 original BW snippets before
+this ruling. Arbitrated by the BW faithfulness experiment
+(validation/bw_faithfulness/derived/arbitration_report.md).
+"""
+examples = ["py-bw-fallback-001"]

codecaliper/spec/rulings/cognitive.toml

@@ -0,0 +1,124 @@
+# COG-*: cognitive complexity (SonarSource whitepaper, dual-mode).
+# Default mode is whitepaper-faithful; --sonar-compat matches the behaviour of
+# the widely-deployed implementations where they diverge from the paper text.
+# Every inter-mode difference is a mode-tagged ruling: the spec table IS the
+# whitepaper-vs-Sonar diff (ARCHITECTURE.md §0).
+
+[[ruling]]
+id = "COG-ALL-0001"
+metric = "cognitive"
+language = "all"
+title = "Structural increments: +1 plus the current nesting level"
+statement = """
+if / loops / catch / switch / ternary each contribute (1 + nesting level at
+their position). Both modes.
+"""
+examples = ["py-cc-boolop-001", "java-boolop-catch-001", "py-nested-function-001"]
+
+[[ruling]]
+id = "COG-ALL-0002"
+metric = "cognitive"
+language = "all"
+title = "elif/else-if and else are hybrid increments: +1, no nesting penalty"
+statement = """
+An elif/else-if continuation and an if-attached else clause each contribute a
+flat +1 regardless of nesting depth, and an elif does not deepen nesting
+relative to its chain head (chain flattening — Sonar's own rule). Both modes.
+In Java an `else` directly followed by an if_statement is the chain
+continuation and is not additionally counted as an else. ONLY an else attached
+to an if/elif chain is a hybrid increment: Python's for/while/try `else`
+clauses contribute nothing (they are completion handlers, not branch arms).
+"""
+examples = ["py-elif-chain-001", "java-elseif-001"]
+
+[[ruling]]
+id = "COG-ALL-0003"
+metric = "cognitive"
+language = "all"
+title = "Boolean operator sequences: +1 per sequence of like operators"
+statement = """
+A run of the same short-circuit operator contributes +1 total; each operator
+change starts a new sequence (`a and b or c` = 2; `a && b && c` = 1).
+Parentheses delimit sequences. Both modes.
+"""
+examples = ["py-cc-boolop-001", "java-boolop-catch-001"]
+
+[[ruling]]
+id = "COG-ALL-0004"
+metric = "cognitive"
+language = "all"
+title = "What deepens nesting"
+statement = """
+Nesting increases inside: if (and its else/elif bodies), loops, catch, switch,
+ternary, and function-like units that are themselves nested inside another
+function (nested functions, lambdas). Nesting does NOT increase inside: try
+bodies, with/synchronized blocks, class bodies, or top-level function bodies.
+Both modes.
+"""
+examples = ["py-nested-function-001"]
+
+[[ruling]]
+id = "COG-ALL-0005"
+metric = "cognitive"
+language = "all"
+title = "Direct recursion counts +1 per recursive call (whitepaper mode)"
+mode = "whitepaper"
+statement = """
+Each call whose callee name equals the enclosing function's name contributes +1
+(the whitepaper lists recursion as a fundamental increment). Receiver rule,
+applied symmetrically across languages: bare calls count (`f(...)`), and
+self-receiver calls count (Python `self.f(...)`/`cls.f(...)`, Java
+`this.f(...)`); a same-named call on any other receiver does NOT count. Name
+matching is a declared syntactic heuristic: it does not resolve overloads or
+mutual recursion.
+"""
+examples = ["py-recursion-001"]
+
+[[ruling]]
+id = "COG-ALL-0006"
+metric = "cognitive"
+language = "all"
+title = "No recursion increment (sonar-compat mode)"
+mode = "sonar-compat"
+statement = """
+SonarQube's own analyzers (sonar-python, sonar-java) do not implement the
+whitepaper's recursion increment; sonar-compat mode therefore omits it.
+(Editorial correction in spec 1.1.0: the original justification also named
+the cognitive_complexity Python package as omitting recursion — false; that
+package DOES implement the +1-per-recursive-call increment, as this repo's
+own differential lane classifies. The normative content of this ruling —
+sonar-compat omits the recursion increment — is unchanged.)
+"""
+examples = ["py-recursion-001"]
+
+[[ruling]]
+id = "COG-JAVA-0001"
+metric = "cognitive"
+language = "java"
+title = "Labeled jumps are a fundamental increment: flat +1, both modes"
+since_spec = "1.1.0"
+statement = """
+A `break LABEL` or `continue LABEL` contributes a flat +1 regardless of
+nesting depth and does not deepen nesting (the whitepaper's fundamental
+increment list names goto LABEL / break LABEL / continue LABEL; sonar-java
+implements it identically, so both modes agree). A bare break/continue
+contributes nothing, and the label declaration itself (`LABEL: for ...`) is
+not separately counted. Cyclomatic is unaffected: a jump is not a decision
+point.
+"""
+node_types = ["break_statement", "continue_statement"]
+examples = ["java-labeled-jump-001"]
+
+[[ruling]]
+id = "COG-PY-0001"
+metric = "cognitive"
+language = "python"
+title = "Comprehension clauses contribute no cognitive increment"
+statement = """
+Comprehension `for_in_clause` and `if_clause` (guard) contribute no cognitive
+increment and do not deepen nesting: a comprehension reads as a single
+declarative expression (consistent with SonarPython's treatment). Contrast
+with cyclomatic, where the guard IS a decision point (CC-PY-0004).
+"""
+node_types = ["if_clause", "for_in_clause"]
+examples = ["py-comprehension-001"]

codecaliper/spec/rulings/core.toml

@@ -0,0 +1,87 @@
+# CORE-*: cross-cutting measurement policies.
+
+[[ruling]]
+id = "CORE-ALL-0001"
+metric = "core"
+language = "all"
+title = "Metrics operate on pre-preprocessing source text"
+statement = """
+All measurements are functions of the source text as written, before any
+preprocessing (relevant to C-family languages later; declared now, ARCHITECTURE.md §0).
+A purely syntactic tool is an approximation for preprocessed languages, and this
+instrument says so instead of hiding it.
+"""
+
+[[ruling]]
+id = "CORE-ALL-0002"
+metric = "core"
+language = "all"
+title = "Parse-error recovery: measure, label, never fabricate"
+statement = """
+tree-sitter always returns a tree. ERROR and MISSING subtrees are classified as
+opaque (not descended into for metric counting), the report carries
+parse_ok=false and a parse-error-recovered diagnostic. --strict upgrades this
+to an error exit. No number is silently fabricated from broken syntax.
+"""
+examples = ["py-error-opacity-001"]
+
+[[ruling]]
+id = "CORE-ALL-0003"
+metric = "core"
+language = "all"
+title = "Nested-unit attribution"
+statement = """
+Per-function values are computed on the function's own subtree EXCLUDING nested
+named function/method/constructor definitions and nested class declarations,
+which receive their own FunctionReports (lambdas remain part of the enclosing
+unit). File-level values are ONE whole-file walk (top-level code plus all
+units), not the sum of per-function values. This is a classic radon-vs-lizard
+divergence axis, ruled explicitly.
+"""
+examples = ["py-nested-function-001"]
+
+[[ruling]]
+id = "CORE-ALL-0004"
+metric = "core"
+language = "all"
+title = "Float emission and determinism scope"
+statement = """
+Canonical JSON/CSV output rounds floating-point values to 12 significant digits
+(round-half-even). Outputs contain no timestamps and no hash-order dependence;
+byte-identical output is guaranteed PER PLATFORM (libm differences across
+OS/arch may flip the last ULP of ln(); this is documented, not hidden).
+Consistency-corpus float assertions always carry explicit tolerances.
+"""
+
+[[ruling]]
+id = "CORE-ALL-0005"
+metric = "core"
+language = "all"
+title = "Language detection is an extension map — never a guess"
+statement = """
+--lang auto maps file extensions to adapters; an unmapped or ambiguous
+extension is an explicit error. Content sniffing is out of scope for 1.0.
+"""
+
+[[ruling]]
+id = "CORE-JAVA-0001"
+metric = "core"
+language = "java"
+title = "Bare-snippet scaffolding at snippet granularity"
+statement = """
+The Buse-Weimer dataset snippets are mostly statement sequences or bare
+methods, not compilation units. VERIFIED (tree-sitter-java 0.23.5): the
+grammar's `program` rule accepts both bare statement sequences and bare method
+declarations, so BW-shaped snippets parse cleanly WITHOUT scaffolding. As a
+fallback, at granularity="snippet", if the bare parse yields an error-bearing
+tree, the text is re-parsed inside TWO candidate scaffolds — class-body-only
+`class __CC__ { ... }` (rescues constructors and modifier-bearing members) and
+`class __CC__ { void __cc__() { ... } }` — and the strict error-count
+minimizer is adopted only when it beats the bare parse. All features are
+computed ONLY over the original snippet's line range (scaffold lines excluded,
+original indentation unshifted), scaffold-line function units are dropped, all
+emitted spans and traces are rebased to original snippet coordinates, and a
+snippet-scaffolded diagnostic is attached.
+"""
+examples = ["java-snippet-constructor-001"]
+

codecaliper/spec/rulings/cyclomatic.toml

@@ -0,0 +1,172 @@
+# CC-*: cyclomatic complexity — decision-point counting rulings.
+# McCabe is defined on the control-flow graph; in practice every tool counts
+# decision points. These rulings pin OUR counting rules per language.
+
+[[ruling]]
+id = "CC-ALL-0001"
+metric = "cyclomatic"
+language = "all"
+title = "Base value and decision-point summation"
+statement = """
+cyclomatic = 1 + the number of decision points in the measured unit. What
+counts as a decision point is pinned by the per-language rulings below.
+"""
+examples = ["py-cc-boolop-001", "java-elseif-001"]
+
+[[ruling]]
+id = "CC-PY-0001"
+metric = "cyclomatic"
+language = "python"
+title = "if statements count +1"
+statement = "Each `if_statement` contributes one decision point."
+node_types = ["if_statement"]
+examples = ["py-cc-boolop-001", "py-elif-chain-001"]
+
+[[ruling]]
+id = "CC-PY-0002"
+metric = "cyclomatic"
+language = "python"
+title = "elif clauses count +1 each"
+statement = "Each `elif_clause` contributes one decision point (each arm is a branch)."
+node_types = ["elif_clause"]
+examples = ["py-elif-chain-001"]
+
+[[ruling]]
+id = "CC-PY-0003"
+metric = "cyclomatic"
+language = "python"
+title = "Boolean short-circuit operators count per operator"
+statement = """
+Each `boolean_operator` node contributes one decision point. An N-operand chain
+is (N-1) nested nodes, so `a and b or c` contributes 2 — each short-circuit is a
+distinct execution path. Agrees with radon; diverges from tools that count a
+whole chain as one.
+"""
+node_types = ["boolean_operator"]
+examples = ["py-cc-boolop-001"]
+
+[[ruling]]
+id = "CC-PY-0004"
+metric = "cyclomatic"
+language = "python"
+title = "Comprehension guards count +1; comprehension for-clauses do not"
+statement = """
+Each `if_clause` inside a comprehension/generator contributes one decision
+point (a guard is a branch). The `for_in_clause` itself does not (it is
+iteration syntax, not a decision). A case-clause guard `if_clause` is NOT
+separately counted — the guarded case_clause already counts under CC-PY-0008,
+and counting both would double-count one branch. Diverges from lizard, which
+also counts the comprehension `for` clause as a loop (see divergences.toml,
+lizard/snippet:diff-comp-guard) — lizard counts the guard AND the for-clause;
+ours counts only the guard.
+"""
+node_types = ["if_clause"]
+examples = ["py-comprehension-001"]
+
+[[ruling]]
+id = "CC-PY-0005"
+metric = "cyclomatic"
+language = "python"
+title = "Loops count +1"
+statement = "Each `for_statement` / `while_statement` contributes one decision point (async included: the async modifier does not change counting)."
+node_types = ["for_statement", "while_statement"]
+examples = ["py-nested-function-001"]
+
+[[ruling]]
+id = "CC-PY-0006"
+metric = "cyclomatic"
+language = "python"
+title = "except clauses count +1 each"
+statement = "Each `except_clause` contributes one decision point."
+node_types = ["except_clause"]
+examples = ["py-try-except-001"]
+
+[[ruling]]
+id = "CC-PY-0007"
+metric = "cyclomatic"
+language = "python"
+title = "Conditional expressions (ternaries) count +1"
+statement = """
+Each `conditional_expression` contributes one decision point. Diverges from the
+stdlib-ast reference lane (which does not count IfExp); the divergence is
+classified.
+"""
+node_types = ["conditional_expression"]
+examples = ["py-ternary-001"]
+
+[[ruling]]
+id = "CC-PY-0008"
+metric = "cyclomatic"
+language = "python"
+title = "match case clauses count +1 each; the match statement and bare wildcard do not"
+statement = """
+Each `case_clause` contributes one decision point, EXCEPT a bare-wildcard
+`case _:` with no guard, which is the fall-through path and does not count —
+the exact mirror of Java `default:` (CC-JAVA-0006).
+"""
+node_types = ["case_clause"]
+examples = ["py-match-001"]
+
+[[ruling]]
+id = "CC-JAVA-0001"
+metric = "cyclomatic"
+language = "java"
+title = "if statements count +1 (else-if chains count each if)"
+statement = """
+Each `if_statement` contributes one decision point, including an if_statement
+that is the `alternative` of another (an else-if arm is a branch).
+"""
+node_types = ["if_statement"]
+examples = ["java-elseif-001"]
+
+[[ruling]]
+id = "CC-JAVA-0002"
+metric = "cyclomatic"
+language = "java"
+title = "Ternary expressions count +1"
+statement = "Each `ternary_expression` contributes one decision point."
+node_types = ["ternary_expression"]
+examples = ["java-ternary-001"]
+
+[[ruling]]
+id = "CC-JAVA-0003"
+metric = "cyclomatic"
+language = "java"
+title = "Short-circuit operators count per operator"
+statement = """
+Each `binary_expression` whose operator is `&&` or `||` contributes one
+decision point; `a && b && c` contributes 2.
+"""
+node_types = ["binary_expression"]
+examples = ["java-boolop-catch-001"]
+
+[[ruling]]
+id = "CC-JAVA-0004"
+metric = "cyclomatic"
+language = "java"
+title = "Loops count +1"
+statement = "Each `for_statement` / `enhanced_for_statement` / `while_statement` / `do_statement` contributes one decision point."
+node_types = ["for_statement", "enhanced_for_statement", "while_statement", "do_statement"]
+examples = ["java-loops-001"]
+
+[[ruling]]
+id = "CC-JAVA-0005"
+metric = "cyclomatic"
+language = "java"
+title = "catch clauses count +1 each"
+statement = "Each `catch_clause` contributes one decision point."
+node_types = ["catch_clause"]
+examples = ["java-boolop-catch-001"]
+
+[[ruling]]
+id = "CC-JAVA-0006"
+metric = "cyclomatic"
+language = "java"
+title = "case labels count +1 each; default does not"
+statement = """
+Each `switch_label` beginning with `case` contributes one decision point; a
+`default` label does not (it is the fall-through path, like an else).
+"""
+node_types = ["switch_label"]
+examples = ["java-switch-001"]
+

codecaliper/spec/rulings/halstead.toml

@@ -0,0 +1,20 @@
+# HAL-*: Halstead metrics.
+
+[[ruling]]
+id = "HAL-ALL-0001"
+metric = "halstead"
+language = "all"
+title = "Lexical Halstead: token-class harvesting (a declared approximation)"
+statement = """
+Operators are OPERATOR, KEYWORD, and PUNCT tokens; operands are IDENTIFIER,
+NUMBER, and STRING tokens, from the unified lexical stream. n1/n2 are distinct
+counts, N1/N2 total counts; V = N*log2(n); D = (n1/2)*(N2/n2); E = D*V.
+Absolute Halstead values are implementation-defined across all tools — only
+trends and ratios are stable — and every emitted value carries the
+halstead-approximation diagnostic (ARCHITECTURE.md §13). This lexical convention is
+deliberately uniform cross-language; its divergence from AST-harvest
+implementations (radon, the stdlib reference lane) is declared, not classified
+against a differential oracle: every value carries the halstead-approximation
+diagnostic (there is no Halstead differential lane, unlike cyclomatic/cognitive).
+"""
+examples = ["py-cc-boolop-001"]