codecaliper 0.1.0__py3-none-any.whl

codecaliper/model.py

@@ -0,0 +1,132 @@
+"""Result data model.
+
+All result types are frozen, slotted dataclasses: immutable, clock-free (no
+timestamps anywhere — outputs are byte-reproducible per platform, CORE-ALL-0004),
+with a stable field order that canonical.py serializes deterministically.
+
+Honesty is encoded in types, not docs: MI carries a typed ``derived_from`` and a
+standing ``mi-contains-cc`` diagnostic; every Halstead value carries
+``halstead-approximation``; readability results carry ``extrapolated`` as a field;
+there is deliberately no score field anywhere (ARCHITECTURE.md §13).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+Granularity = Literal["snippet", "function", "file"]
+Severity = Literal["info", "warning", "error"]
+
+#: Closed set of diagnostic codes (ARCHITECTURE.md §2).
+DIAGNOSTIC_CODES = frozenset(
+    {
+        "parse-error-recovered",
+        "unvalidated-grammar",
+        "granularity-extrapolated",
+        "snippet-out-of-calibrated-range",
+        "snippet-scaffolded",
+        "bw-lexical-fallback",
+        "mi-contains-cc",
+        "halstead-approximation",
+        "encoding-replaced",
+        "bom-stripped",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Span:
+    """1-based line numbers, 0-based columns (editor convention)."""
+
+    start_line: int
+    start_col: int
+    end_line: int
+    end_col: int
+
+
+@dataclass(frozen=True, slots=True)
+class GrammarInfo:
+    language: str  # "python"
+    package: str  # "tree-sitter-python"
+    version: str  # actually-installed version (importlib.metadata)
+    abi_version: int  # tree-sitter Language ABI
+    validated: bool  # matches spec/validated_grammars.toml? Run and label, never refuse.
+
+
+@dataclass(frozen=True, slots=True)
+class Provenance:
+    tool_version: str
+    spec_version: str  # on EVERY report — the instrument's calibration stamp
+    language: str
+    grammar: GrammarInfo
+    modes: tuple[tuple[str, str], ...]  # (("cognitive", "whitepaper"),) — sorted, hashable
+    rulings_applied: tuple[str, ...]  # sorted, deduped IDs governing the emitted values
+
+
+@dataclass(frozen=True, slots=True)
+class Diagnostic:
+    severity: Severity
+    code: str  # member of DIAGNOSTIC_CODES
+    message: str
+    span: Span | None = None
+    ruling: str | None = None  # the ruling governing this behaviour, if any
+
+
+@dataclass(frozen=True, slots=True)
+class RulingTrace:
+    """Per-increment attribution, populated only with explain=True (zero default cost)."""
+
+    ruling_id: str
+    span: Span
+    delta: float
+
+
+@dataclass(frozen=True, slots=True)
+class MetricValue:
+    metric: str  # "cyclomatic", "halstead.volume", ...
+    value: int | float
+    rulings: tuple[str, ...] = ()  # ruling IDs governing this metric for this language
+    derived_from: tuple[str, ...] = ()  # MI: ("halstead.volume", "cyclomatic", "sloc")
+    trace: tuple[RulingTrace, ...] = ()
+    diagnostics: tuple[Diagnostic, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class FeatureVectorResult:
+    """A raw feature vector — never a score (ARCHITECTURE.md §7/§13)."""
+
+    feature_set: str  # "bw2010"
+    granularity: Granularity
+    native_granularity: Granularity  # "snippet" for bw2010
+    extrapolated: bool  # granularity != native_granularity
+    names: tuple[str, ...]  # canonical order (bw2010: Fig. 6 order from the reference)
+    values: tuple[float, ...]
+    rulings: tuple[str, ...] = ()
+    diagnostics: tuple[Diagnostic, ...] = ()
+    unit_name: str | None = None  # function name when granularity == "function"
+    span: Span | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class FunctionReport:
+    name: str
+    qualified_name: str
+    span: Span
+    metrics: tuple[MetricValue, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class FileReport:
+    path: str | None  # None for in-memory measure()
+    parse_ok: bool  # False if the tree contains ERROR/MISSING nodes (CORE-ALL-0002)
+    file_metrics: tuple[MetricValue, ...] = ()
+    functions: tuple[FunctionReport, ...] = ()
+    readability: tuple[FeatureVectorResult, ...] = ()  # plural: feature SETS, not scores
+    diagnostics: tuple[Diagnostic, ...] = ()
+    provenance: Provenance | None = None
+
+
+def metric_map(values: tuple[MetricValue, ...]) -> dict[str, MetricValue]:
+    """Convenience view keyed by metric name (stable insertion order preserved)."""
+    return {v.metric: v for v in values}

codecaliper/readability/__init__.py

@@ -0,0 +1,13 @@
+from codecaliper.readability.base import available_feature_sets
+from codecaliper.readability.bw2010 import (
+    BW_FEATURE_NAMES,
+    BW_FEATURE_ORDER_SHA,
+    bw_features,
+)
+
+__all__ = [
+    "BW_FEATURE_NAMES",
+    "BW_FEATURE_ORDER_SHA",
+    "available_feature_sets",
+    "bw_features",
+]

codecaliper/readability/base.py

@@ -0,0 +1,11 @@
+"""FeatureSet registry — bw2010 now; scalabrino2018/dorn2012 slot in at 1.x
+without model changes (FileReport.readability is already plural)."""
+
+from __future__ import annotations
+
+#: name -> native granularity; extraction dispatch lives in api.py for the MVP.
+FEATURE_SETS: dict[str, str] = {"bw2010": "snippet"}
+
+
+def available_feature_sets() -> tuple[str, ...]:
+    return tuple(FEATURE_SETS)

codecaliper/readability/bw2010.py

@@ -0,0 +1,156 @@
+"""The 25 Buse-Weimer (2010, Fig. 6) readability features on tree-sitter.
+
+Canonical feature names and order are inherited verbatim from the reference
+implementation (Spaghetti Architect bench/anchor.py::_BW_FEATURE_NAMES,
+NOTICE-credited); tests/test_bw_port_fidelity.py holds this port to the stdlib
+reference per feature. Output is always the raw vector — there is no score
+(BW-ALL-0001).
+
+Two feature families (BW-ALL-0004):
+- raw-line facts (length, indentation, spaces, blanks, char frequency) from the
+  normalized text of every line, strings included;
+- token facts (identifiers, keywords, numbers, comments, operator classes,
+  punctuation) from the unified LexicalToken stream, so string/comment contents
+  are invisible to them.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+from codecaliper.languages.base import LanguageAdapter
+from codecaliper.spec import require
+from codecaliper.syntax.tokens import LexicalToken, TokenKind
+
+R_FEATURES = require("BW-ALL-0001")
+R_GRANULARITY = require("BW-ALL-0002")
+R_COMMENT_ONCE = require("BW-ALL-0003")
+R_TOKEN_LEVEL = require("BW-ALL-0004")
+R_ID_LENGTH = require("BW-ALL-0005")
+R_OP_CLASSES = require("BW-ALL-0006")
+
+#: Fig. 6 order — verbatim from the reference implementation.
+BW_FEATURE_NAMES: tuple[str, ...] = (
+    "avg_line_length", "max_line_length",
+    "avg_identifiers", "max_identifiers",
+    "avg_identifier_length", "max_identifier_length",
+    "avg_indentation", "max_indentation",
+    "avg_keywords", "max_keywords",
+    "avg_numbers", "max_numbers",
+    "avg_comments", "avg_periods", "avg_commas", "avg_spaces",
+    "avg_parentheses", "avg_arithmetic_ops", "avg_comparison_ops",
+    "avg_assignments", "avg_branches", "avg_loops", "avg_blank_lines",
+    "max_char_occurrences", "max_identifier_occurrences",
+)
+
+#: Feature-order integrity stamp for trained-model artifacts (ARCHITECTURE.md §7.2).
+BW_FEATURE_ORDER_SHA: str = hashlib.sha256(",".join(BW_FEATURE_NAMES).encode()).hexdigest()
+
+#: The rulings in force for every bw2010 vector.
+BW_RULINGS: tuple[str, ...] = (
+    R_FEATURES, R_GRANULARITY, R_COMMENT_ONCE, R_TOKEN_LEVEL, R_ID_LENGTH, R_OP_CLASSES,
+)
+
+#: The paper's calibrated snippet regime (BW-ALL-0002).
+CALIBRATED_LINE_RANGE = (4, 11)
+
+
+def bw_features(
+    lines: list[str], tokens: list[LexicalToken], adapter: LanguageAdapter
+) -> dict[str, float]:
+    """Compute the 25 features. ``tokens`` line numbers must be 1-based relative
+    to ``lines`` (granularity slicing rebases them)."""
+    n_lines = max(1, len(lines))
+
+    line_len: list[int] = []
+    indent: list[int] = []
+    spaces = 0
+    blank = 0
+    char_freq: dict[str, int] = {}
+    for line in lines:
+        line_len.append(len(line))
+        stripped = line.lstrip()
+        # TOK-ALL-0006 (supersedes TOK-ALL-0004): a tab counts as 8 indentation
+        # characters, arbitrated by the BW faithfulness experiment. Line length
+        # above stays a raw character count.
+        leading = line[: len(line) - len(stripped)]
+        indent.append(sum(8 if ch == "\t" else 1 for ch in leading))
+        spaces += line.count(" ")
+        if stripped == "":
+            blank += 1
+        for ch in line:
+            char_freq[ch] = char_freq.get(ch, 0) + 1
+
+    ident_per_line = [0] * len(lines)
+    ident_len_per_line = [0] * len(lines)  # per-line max identifier length (BW-ALL-0005)
+    kw_per_line = [0] * len(lines)
+    num_per_line = [0] * len(lines)
+    comments = periods = commas = parens = 0
+    arith = compare = assign = branch = loop = 0
+    ident_freq: dict[str, int] = {}
+
+    for tok in tokens:
+        i = tok.line - 1
+        if not (0 <= i < len(lines)):
+            continue
+        if tok.kind is TokenKind.IDENTIFIER:
+            ident_per_line[i] += 1
+            ident_len_per_line[i] = max(ident_len_per_line[i], len(tok.text))
+            ident_freq[tok.text] = ident_freq.get(tok.text, 0) + 1
+        elif tok.kind is TokenKind.KEYWORD:
+            kw_per_line[i] += 1
+            if tok.text in adapter.branch_keywords:
+                branch += 1
+            elif tok.text in adapter.loop_keywords:
+                loop += 1
+        elif tok.kind is TokenKind.NUMBER:
+            num_per_line[i] += 1
+        elif tok.kind is TokenKind.COMMENT:
+            comments += 1  # once per token (BW-ALL-0003, provisional)
+        elif tok.kind in (TokenKind.OPERATOR, TokenKind.PUNCT):
+            if tok.text == ",":
+                commas += 1
+            elif tok.text == ".":
+                periods += 1
+            elif tok.text in ("(", ")"):
+                parens += 1
+            if tok.text in adapter.assignment_ops:
+                assign += 1
+            elif tok.text in adapter.comparison_ops:
+                compare += 1
+            elif tok.text in adapter.arithmetic_ops:
+                arith += 1
+
+    def _avg(xs: list[int]) -> float:
+        return sum(xs) / len(xs) if xs else 0.0
+
+    def _max(xs: list[int]) -> float:
+        return float(max(xs)) if xs else 0.0
+
+    return {
+        "avg_line_length": _avg(line_len),
+        "max_line_length": _max(line_len),
+        "avg_identifiers": _avg(ident_per_line),
+        "max_identifiers": _max(ident_per_line),
+        "avg_identifier_length": _avg(ident_len_per_line),
+        "max_identifier_length": _max(ident_len_per_line),
+        "avg_indentation": _avg(indent),
+        "max_indentation": _max(indent),
+        "avg_keywords": _avg(kw_per_line),
+        "max_keywords": _max(kw_per_line),
+        "avg_numbers": _avg(num_per_line),
+        "max_numbers": _max(num_per_line),
+        "avg_comments": comments / n_lines,
+        "avg_periods": periods / n_lines,
+        "avg_commas": commas / n_lines,
+        "avg_spaces": spaces / n_lines,
+        "avg_parentheses": parens / n_lines,
+        "avg_arithmetic_ops": arith / n_lines,
+        "avg_comparison_ops": compare / n_lines,
+        "avg_assignments": assign / n_lines,
+        "avg_branches": branch / n_lines,
+        "avg_loops": loop / n_lines,
+        "avg_blank_lines": blank / n_lines,
+        "max_char_occurrences": float(max(char_freq.values(), default=0)),
+        "max_identifier_occurrences": float(max(ident_freq.values(), default=0)),
+    }

codecaliper/readability/granularity.py

@@ -0,0 +1,210 @@
+"""Granularity segmentation and extrapolation labelling (BW-ALL-0002), plus the
+Java bare-snippet scaffold (CORE-JAVA-0001)."""
+
+from __future__ import annotations
+
+from codecaliper.languages.base import FunctionUnit, LanguageAdapter
+from codecaliper.model import Diagnostic, FeatureVectorResult, Granularity, Span
+from codecaliper.readability.bw2010 import (
+    BW_FEATURE_NAMES,
+    BW_RULINGS,
+    CALIBRATED_LINE_RANGE,
+    bw_features,
+)
+from codecaliper.spec import require
+from codecaliper.syntax.tokens import LexicalToken, lang_tokenization_rulings
+
+R_TOK_LINE = require("TOK-ALL-0005")  # token line attribution
+R_TOK_TAB = require("TOK-ALL-0006")   # tab = 8 indentation characters
+
+JAVA_SNIPPET_PREFIX = "class __CC__ {\nvoid __cc__() {\n"
+JAVA_SNIPPET_SUFFIX = "\n}\n}\n"
+JAVA_SNIPPET_LINE_OFFSET = 2  # lines prepended by the class+method scaffold
+
+# Class-body-only scaffold: rescues member-level snippets (constructors,
+# modifier-bearing methods) that a method body cannot contain (CORE-JAVA-0001).
+JAVA_CLASS_PREFIX = "class __CC__ {\n"
+JAVA_CLASS_SUFFIX = "\n}\n"
+JAVA_CLASS_LINE_OFFSET = 1
+
+
+def rebase_unit(unit: FunctionUnit, line_offset: int, n_lines: int) -> FunctionUnit:
+    """Shift a FunctionUnit's span from scaffold to original snippet coordinates,
+    and strip the synthetic scaffold qualifiers from qualified_name — scaffold
+    artifacts must never leak into emitted output (CORE-JAVA-0001). Longest
+    prefix first: the class+method scaffold nests units under __CC__.__cc__."""
+    qualified = unit.qualified_name
+    for scaffold_prefix in ("__CC__.__cc__.", "__CC__."):
+        if qualified.startswith(scaffold_prefix):
+            qualified = qualified[len(scaffold_prefix):]
+            break
+    s = unit.span
+    return FunctionUnit(
+        unit.name,
+        qualified,
+        unit.node,
+        Span(
+            start_line=s.start_line - line_offset,
+            start_col=s.start_col,
+            end_line=min(s.end_line - line_offset, n_lines),
+            end_col=s.end_col,
+        ),
+    )
+
+
+def rebase_tokens(
+    tokens: list[LexicalToken], start_line: int, end_line: int
+) -> list[LexicalToken]:
+    """Tokens whose start lies in [start_line, end_line], rebased to 1-based."""
+    offset = start_line - 1
+    return [
+        LexicalToken(t.kind, t.text, t.line - offset, min(t.end_line, end_line) - offset)
+        for t in tokens
+        if start_line <= t.line <= end_line
+    ]
+
+
+def _bw_vector_rulings(
+    adapter: LanguageAdapter, lexical_fallback: bool, cond_rulings: tuple[str, ...]
+) -> tuple[str, ...]:
+    """The governing set for an emitted BW vector: the six BW-ALL requires,
+    the language-specific bw2010 rulings (keyword/branch-keyword delimitation),
+    and the tokenization rulings that shape the features (TOK-ALL-0005 line
+    attribution, TOK-ALL-0006 tab=8 indentation, the language's static
+    atomic-string rulings). ``cond_rulings`` are the construct-specific
+    tokenization rulings (TOK-ALL-0007 anonymous words, TOK-JAVA-0002 `_`) that
+    actually engaged inside THIS vector's line span; BW-ALL-0007 stays strictly
+    conditional on the lexical fallback actually engaging."""
+    from codecaliper.spec import iter_rulings
+
+    lang_specific = tuple(sorted(
+        r.id
+        for r in iter_rulings(metric="bw2010", language=adapter.name)
+        if r.id not in BW_RULINGS and r.id != "BW-ALL-0007"
+    ))
+    return (
+        BW_RULINGS
+        + lang_specific
+        + (R_TOK_LINE, R_TOK_TAB)
+        + lang_tokenization_rulings(adapter)
+        + tuple(sorted(cond_rulings))
+        + (("BW-ALL-0007",) if lexical_fallback else ())
+    )
+
+
+def vector(
+    lines: list[str],
+    tokens: list[LexicalToken],
+    adapter: LanguageAdapter,
+    granularity: Granularity,
+    *,
+    unit_name: str | None = None,
+    span: Span | None = None,
+    scaffolded: bool = False,
+    lexical_fallback: bool = False,
+    cond_rulings: tuple[str, ...] = (),
+) -> FeatureVectorResult:
+    features = bw_features(lines, tokens, adapter)
+    diags: list[Diagnostic] = []
+    if lexical_fallback:
+        diags.append(
+            Diagnostic(
+                "info", "bw-lexical-fallback",
+                "parse errors present; token-family features computed over the "
+                "full lexical stream, ERROR regions included — the BW construct "
+                "is lexical (BW-ALL-0007). CORE-ALL-0002 still governs every "
+                "metric.",
+                ruling="BW-ALL-0007",
+            )
+        )
+    extrapolated = granularity != "snippet"
+    if extrapolated:
+        diags.append(
+            Diagnostic(
+                "warning", "granularity-extrapolated",
+                f"bw2010 is calibrated on snippets; {granularity}-level vectors are "
+                "extrapolation beyond the model's native unit (BW-ALL-0002)",
+                ruling="BW-ALL-0002",
+            )
+        )
+    lo, hi = CALIBRATED_LINE_RANGE
+    if granularity == "snippet" and not (lo <= len(lines) <= hi):
+        diags.append(
+            Diagnostic(
+                "info", "snippet-out-of-calibrated-range",
+                f"snippet is {len(lines)} lines; the bw2010 calibrated regime is "
+                f"{lo}-{hi} lines (BW-ALL-0002)",
+                ruling="BW-ALL-0002",
+            )
+        )
+    if scaffolded:
+        diags.append(
+            Diagnostic(
+                "info", "snippet-scaffolded",
+                "bare Java snippet was parsed inside a synthetic class/method "
+                "scaffold; features computed over the original lines only "
+                "(CORE-JAVA-0001)",
+                ruling="CORE-JAVA-0001",
+            )
+        )
+    return FeatureVectorResult(
+        feature_set="bw2010",
+        granularity=granularity,
+        native_granularity="snippet",
+        extrapolated=extrapolated,
+        names=BW_FEATURE_NAMES,
+        values=tuple(features[n] for n in BW_FEATURE_NAMES),
+        rulings=_bw_vector_rulings(adapter, lexical_fallback, cond_rulings),
+        diagnostics=tuple(diags),
+        unit_name=unit_name,
+        span=span,
+    )
+
+
+def cond_in_range(cond_lines: dict[str, set[int]], lo: int, hi: int) -> tuple[str, ...]:
+    """Conditional tokenization rulings that engaged on a line within [lo, hi]."""
+    return tuple(sorted(
+        rid for rid, lns in cond_lines.items() if any(lo <= ln <= hi for ln in lns)
+    ))
+
+
+def function_vectors(
+    lines: list[str],
+    tokens: list[LexicalToken],
+    adapter: LanguageAdapter,
+    units: list[FunctionUnit],
+    opaque_tokens: list[LexicalToken] | None = None,
+    cond_opaque: dict[str, set[int]] | None = None,
+    cond_full: dict[str, set[int]] | None = None,
+) -> list[FeatureVectorResult]:
+    """Per-unit vectors. ``opaque_tokens`` is the error-opaque stream, passed
+    only when the file-level BW lexical fallback engaged (BW-ALL-0007): a
+    unit's vector is flagged only when its OWN span gained ERROR-region tokens
+    — the opaque stream is a subsequence of the full one, so equal slice
+    lengths imply identical slices. ``cond_opaque``/``cond_full`` map each
+    conditional tokenization ruling to the lines it engaged on in the
+    respective stream; a unit cites one only when it engaged inside the unit's
+    OWN span (in the stream that unit actually used)."""
+    out = []
+    for unit in units:
+        s, e = unit.span.start_line, unit.span.end_line
+        unit_tokens = rebase_tokens(tokens, s, e)
+        unit_fallback = (
+            opaque_tokens is not None
+            and len(unit_tokens) != len(rebase_tokens(opaque_tokens, s, e))
+        )
+        cond_src = cond_full if unit_fallback else cond_opaque
+        cond_rulings = cond_in_range(cond_src, s, e) if cond_src is not None else ()
+        out.append(
+            vector(
+                lines[s - 1 : e],
+                unit_tokens,
+                adapter,
+                "function",
+                unit_name=unit.qualified_name,
+                span=unit.span,
+                lexical_fallback=unit_fallback,
+                cond_rulings=cond_rulings,
+            )
+        )
+    return out

codecaliper/readability/retrain.py

@@ -0,0 +1,67 @@
+"""Retraining scaffold (ARCHITECTURE.md §7.4): feature extraction is decoupled from any
+trained model; codecaliper ships NO weights. Model artifacts are JSON (never
+pickle) and carry honesty metadata — applying a Java-snippet model elsewhere is
+a construct-validity decision the user makes with eyes open.
+
+The heavy lifting (logistic regression) needs the [retrain] extra
+(scikit-learn); this module only defines the artifact contract so the §6.3
+faithfulness pipeline and user retraining share one format.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+
+from codecaliper.errors import SpecError
+from codecaliper.readability.bw2010 import BW_FEATURE_ORDER_SHA
+from codecaliper.spec import spec_version
+
+
+@dataclass(frozen=True, slots=True)
+class ModelArtifact:
+    feature_set: str  # "bw2010"
+    feature_order_sha: str  # must equal BW_FEATURE_ORDER_SHA at predict time
+    spec_version: str
+    trained_granularity: str
+    trained_language: str
+    dataset_id: str  # e.g. "bw2010-original-100java" — an ID, never bundled data
+    protocol: str  # e.g. "bw2010-logistic-10fold"
+    seed: int
+    coefficients: tuple[float, ...]
+    intercept: float
+
+    def save(self, path: str) -> None:
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(asdict(self), f, indent=2, sort_keys=True)
+            f.write("\n")
+
+    @classmethod
+    def load(cls, path: str) -> ModelArtifact:
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+        data["coefficients"] = tuple(data["coefficients"])
+        art = cls(**data)
+        if art.feature_set == "bw2010" and art.feature_order_sha != BW_FEATURE_ORDER_SHA:
+            raise SpecError(
+                "model artifact feature order does not match this codecaliper's "
+                "canonical bw2010 order — refusing to predict with misaligned features"
+            )
+        return art
+
+
+def new_artifact_metadata(
+    *, trained_granularity: str, trained_language: str, dataset_id: str,
+    protocol: str, seed: int,
+) -> dict[str, object]:
+    """Metadata stamp for a fresh training run (used by validation/bw_faithfulness)."""
+    return {
+        "feature_set": "bw2010",
+        "feature_order_sha": BW_FEATURE_ORDER_SHA,
+        "spec_version": spec_version(),
+        "trained_granularity": trained_granularity,
+        "trained_language": trained_language,
+        "dataset_id": dataset_id,
+        "protocol": protocol,
+        "seed": seed,
+    }

codecaliper/spec/__init__.py

@@ -0,0 +1,3 @@
+from codecaliper.spec.registry import Ruling, iter_rulings, require, ruling, spec_version
+
+__all__ = ["Ruling", "iter_rulings", "require", "ruling", "spec_version"]