crapkit 0.2.0__py3-none-any.whl

crapkit/lizardcognitive.py

@@ -0,0 +1,238 @@
+"""Cognitive complexity (Sonar spec) as a lizard token-stream extension.
+
+Rides lizard's language-aware tokenizers, so TS/TSX/JS/Python all pay the same
+rules with no second parse and no new dependency:
+  +1 and +nesting for if / ternary / switch / loops / catch-except
+  +1 flat for else / elif (an else-if chain costs one per link, no deepening)
+  +1 per boolean-operator run, +1 each time the operator alternates
+  +1 for a labeled break/continue or goto, +1 once for direct recursion
+  try / finally / case labels / with are free; nesting rises inside the
+  block structures listed above.
+
+Attribution follows lizard's function splitting (a nested arrow's tokens are
+the arrow's), exactly as ccn is attributed today. Ternary branches do not
+deepen nesting (a structure inside a ternary arm is rare enough to accept).
+
+The whitepaper's worked examples in tests/unit/test_cognitive.py are the spec.
+"""
+from __future__ import annotations
+
+_COUNTING = frozenset({"if", "for", "foreach", "while", "do", "catch", "except", "switch"})
+_BOOL_OPS = frozenset({"&&", "||", "??", "and", "or"})
+_RUN_RESETS = frozenset({";", ",", "{", "}"})
+
+
+class _FnState:
+    __slots__ = ("total", "stack", "brace_depth", "line_indent", "at_line_start",
+                 "pending", "else_pending", "question_pending", "bool_op", "name",
+                 "recursed", "body_started", "prev", "label_check")
+
+    def __init__(self, name: str):
+        self.total = 0
+        self.stack = []          # (entry_brace_depth) or python header indents
+        self.brace_depth = 0
+        self.line_indent = 0
+        self.at_line_start = True
+        self.pending = False     # a counting structure awaits its '{'
+        self.else_pending = False
+        self.question_pending = False
+        self.bool_op = None
+        self.name = name
+        self.recursed = False
+        self.body_started = False
+        self.prev = ""
+        self.label_check = False  # just saw break/continue
+
+
+class LizardExtension:
+    """One instance per analysis pass; state is per lizard FunctionInfo."""
+
+    FUNCTION_INFO = {"cognitive_complexity": {"caption": " Cog "}}
+
+    def __call__(self, tokens, reader):
+        # Keyed on the FunctionInfo itself, never on id(fn): the map would hold no
+        # reference, a finished function's address would be recycled under a later
+        # one, and that one would inherit a stranger's running total. Measured on
+        # the consumer repo: 377-379 rows moved between two runs of the same commit.
+        states: dict[object, _FnState] = {}
+        is_python = type(reader).__name__.lower().startswith("python")
+        for token in tokens:
+            fn = reader.context.current_function
+            state = states.get(fn)
+            if state is None:
+                state = states[fn] = _FnState(getattr(fn, "name", ""))
+            _step(state, token, is_python)
+            fn.cognitive_complexity = state.total
+            yield token
+
+
+def _step(state: _FnState, token: str, is_python: bool) -> None:
+    if not token.strip():
+        _line_event(state, token, is_python)
+        return
+    if token.startswith(("#", "//", "/*")):
+        return  # a comment token must never read as code, whatever it contains
+    if is_python and state.at_line_start:
+        _python_dedent(state)
+    if _resolve_lookbehinds(state, token, is_python):
+        state.prev = token
+        state.at_line_start = False
+        return
+    _consume(state, token, is_python)
+    state.prev = token
+    state.at_line_start = False
+
+
+def _line_event(state: _FnState, token: str, is_python: bool) -> None:
+    """Whitespace arrives split ('\\n' then '    '): the newline opens the line,
+    later whitespace extends its indent, and the dedent settles only when the
+    first real token of the line arrives."""
+    if "\n" in token:
+        state.at_line_start = True
+        state.bool_op = None
+        state.line_indent = len(token) - token.rfind("\n") - 1
+        state.body_started = state.body_started or is_python
+    elif state.at_line_start:
+        state.line_indent += len(token)
+
+
+def _python_dedent(state: _FnState) -> None:
+    while state.stack and state.line_indent <= state.stack[-1]:
+        state.stack.pop()
+
+
+def _resolve_lookbehinds(state: _FnState, token: str, is_python: bool) -> bool:
+    """Signals needing one token of hindsight. True = this token is consumed."""
+    if state.question_pending:
+        _resolve_question(state, token, is_python)
+    if state.label_check:
+        _resolve_label(state, token)
+    if state.else_pending:
+        state.else_pending = False
+        state.pending = True
+        # else-if: the else already paid the flat +1; this if only opens the block
+        return token == "if"
+    return False
+
+
+def _resolve_question(state: _FnState, token: str, is_python: bool) -> None:
+    state.question_pending = False
+    if token not in (".", ":", ")"):  # optional chaining / optional type / trailing
+        state.total += 1 + _nesting(state, is_python)
+
+
+def _resolve_label(state: _FnState, token: str) -> None:
+    state.label_check = False
+    if token not in (";", "}", ")") and token.strip():
+        state.total += 1  # break/continue TO A LABEL
+
+
+def _nesting(state: _FnState, is_python: bool) -> int:
+    return len(state.stack)
+
+
+def _consume(state: _FnState, token: str, is_python: bool) -> None:
+    if token in _RUN_RESETS:
+        state.bool_op = None
+    if token in ("{", "}"):
+        _brace(state, token)
+        return
+    if is_python and not state.body_started:
+        return  # tokens of the def header line never count
+    if token in _BOOL_OPS:
+        _bool_op(state, token)
+        return
+    _keywords(state, token, is_python)
+
+
+def _brace(state: _FnState, token: str) -> None:
+    if token == "{":
+        _open_brace(state)
+    else:
+        _close_brace(state)
+
+
+def _open_brace(state: _FnState) -> None:
+    if state.pending:
+        state.stack.append(state.brace_depth)
+        state.pending = False
+    state.brace_depth += 1
+
+
+def _close_brace(state: _FnState) -> None:
+    state.brace_depth -= 1
+    if state.stack and state.stack[-1] == state.brace_depth:
+        state.stack.pop()
+
+
+def _bool_op(state: _FnState, token: str) -> None:
+    op = {"and": "&&", "or": "||"}.get(token, token)
+    if op != state.bool_op:
+        state.total += 1
+        state.bool_op = op
+
+
+def _keywords(state: _FnState, token: str, is_python: bool) -> None:
+    if token == "if":
+        _if_token(state, is_python)
+    elif token in ("else", "elif"):
+        _else_token(state, token, is_python)
+    elif token in _COUNTING:
+        _structure_token(state, token, is_python)
+    else:
+        _jumps_and_recursion(state, token, is_python)
+
+
+def _structure_token(state: _FnState, token: str, is_python: bool) -> None:
+    if token == "while" and state.prev == "}":
+        return  # the closing half of do-while; the do already paid
+    _structure(state, token, is_python)
+
+
+def _jumps_and_recursion(state: _FnState, token: str, is_python: bool) -> None:
+    if token == "?":
+        state.question_pending = True
+    elif token in ("break", "continue"):
+        state.label_check = not is_python
+    elif token == "goto":
+        state.total += 1
+    elif _is_recursion(state, token):
+        state.recursed = True
+        state.total += 1
+
+
+def _is_recursion(state: _FnState, token: str) -> bool:
+    return (token == state.name and bool(state.name) and not state.recursed
+            and (state.body_started or state.brace_depth > 0))
+
+
+def _if_token(state: _FnState, is_python: bool) -> None:
+    if is_python and not state.at_line_start:
+        state.total += 1 + _nesting(state, is_python)  # ternary expression form
+        return
+    state.total += 1 + _nesting(state, is_python)
+    _push_structure(state, is_python)
+
+
+def _else_token(state: _FnState, token: str, is_python: bool) -> None:
+    if is_python and not state.at_line_start:
+        return  # the else arm of a ternary expression is part of its +1
+    state.total += 1
+    if token == "elif":
+        _push_structure(state, is_python)
+    else:
+        state.else_pending = not is_python
+        if is_python:
+            _push_structure(state, is_python)
+
+
+def _structure(state: _FnState, token: str, is_python: bool) -> None:
+    state.total += 1 + _nesting(state, is_python)
+    _push_structure(state, is_python)
+
+
+def _push_structure(state: _FnState, is_python: bool) -> None:
+    if is_python:
+        state.stack.append(state.line_indent)
+    else:
+        state.pending = True

crapkit/mcp_server.py

@@ -0,0 +1,167 @@
+"""Minimal MCP stdio server. JSON-RPC 2.0, newline-delimited, no SDK dependency.
+
+Read-side only: every tool shells to the CLI's own --json surface, so the MCP
+view can never drift from what the CLI reports, and nothing here writes a
+baseline, a ratchet, or a mutant. Runs that mutate state stay in the CLI.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+PROTOCOL_VERSION = "2024-11-05"
+
+_REPO = {"repo": {"type": "string", "description": "repo root (default: the server's)"}}
+
+TOOLS: tuple[dict, ...] = (
+    {"name": "next_item", "argv": ["next-item"], "json_flag": False, "positional": (),
+     "flags": {"top": "--top", "exclude": "--exclude"},
+     "description": "The highest-risk function(s) to refactor next, with scores and effort estimates",
+     "properties": {"top": {"type": "integer"}, "exclude": {"type": "array", "items": {"type": "string"}}}},
+    {"name": "worklist", "argv": ["worklist"], "json_flag": True, "positional": (),
+     "flags": {"top": "--top"},
+     "description": "Risk-ranked decomposition queue (ccn x recency-weighted churn)",
+     "properties": {"top": {"type": "integer"}}},
+    {"name": "runs", "argv": ["runs"], "json_flag": True, "positional": (), "flags": {},
+     "description": "Run history: id, kind, verdict, commit, lane set", "properties": {}},
+    {"name": "brief", "argv": ["brief"], "json_flag": True, "positional": ("path", "name"),
+     "flags": {},
+     "description": "One function's whole context: scored row, ratchet mark, uncovered lines, "
+                    "duplication twins, churn and change-coupling partners",
+     "properties": {"path": {"type": "string", "description": "repo-relative source file"},
+                    "name": {"type": "string",
+                             "description": "the bare identifier (classify) or the whole "
+                                            "long_name next_item printed "
+                                            "(classify( score , late )); both resolve"}}},
+    {"name": "explain", "argv": ["explain"], "json_flag": False, "positional": ("path", "name"),
+     "flags": {},
+     "description": "One function's score trajectory across runs plus its ratchet mark",
+     "properties": {"path": {"type": "string"}, "name": {"type": "string"}}},
+    {"name": "doctor", "argv": ["doctor"], "json_flag": False, "positional": (), "flags": {},
+     "description": "Config/repo agreement check: typo keys, empty scopes, missing lane cwds",
+     "properties": {}},
+    {"name": "coupling", "argv": ["coupling"], "json_flag": True, "positional": (),
+     "flags": {"min_support": "--min-support", "min_confidence": "--min-confidence"},
+     "description": "File pairs that keep landing in the same commits (hidden dependencies)",
+     "properties": {"min_support": {"type": "integer"}, "min_confidence": {"type": "number"}}},
+    {"name": "duplication", "argv": ["duplication"], "json_flag": True, "positional": (),
+     "flags": {"similarity": "--similarity"},
+     "description": "Near-duplicate functions by normalized line shingles",
+     "properties": {"similarity": {"type": "number"}}},
+    {"name": "ratchet_report", "argv": ["ratchet", "report"], "json_flag": True, "positional": (),
+     "flags": {},
+     "description": "Debt burn-down: open mark ages and repayment velocity from git history",
+     "properties": {}},
+)
+
+
+def tool_listing() -> list[dict]:
+    return [{"name": t["name"], "description": t["description"],
+             "inputSchema": {"type": "object", "properties": {**_REPO, **t["properties"]}}}
+            for t in TOOLS]
+
+
+def _flag_args(flags: dict, arguments: dict) -> list[str]:
+    out: list[str] = []
+    for key, flag in flags.items():
+        value = arguments.get(key)
+        if value is None:
+            continue
+        for v in (value if isinstance(value, list) else [value]):
+            out += [flag, str(v)]
+    return out
+
+
+def build_argv(tool: dict, arguments: dict) -> list[str]:
+    argv = list(tool["argv"])
+    argv += [str(arguments[p]) for p in tool["positional"]]
+    argv += _flag_args(tool["flags"], arguments)
+    if tool["json_flag"]:
+        argv.append("--json")
+    return argv
+
+
+def _result(text: str, *, is_error: bool) -> dict:
+    return {"content": [{"type": "text", "text": text}], "isError": is_error}
+
+
+def _no_config_result(repo: str) -> dict:
+    """What every tool answers in a directory crapkit has never measured.
+
+    A tool result, never a JSON-RPC error: the client keeps the session, and the
+    caller reads one sentence that says what to run instead of a transport
+    failure. isError stays true so nothing reads an unmeasured directory as a
+    repo with nothing to report.
+    """
+    return _result(f"no crapkit.toml in {repo} — nothing measured here. "
+                   "Run `crapkit init` in the repo you want scored, or pass this tool a "
+                   "`repo` argument (or start the server with --repo) pointing at one.",
+                   is_error=True)
+
+
+def _run_cli(tool: dict, arguments: dict, repo: str) -> dict:
+    """One tool, run as the CLI command it maps to. A command that printed
+    nothing answers with its stderr, so a refusal reaches the caller as text."""
+    argv = build_argv(tool, arguments) + ["--repo", repo]
+    proc = subprocess.run([sys.executable, "-m", "crapkit", *argv],
+                          capture_output=True, text=True, timeout=600)
+    text = proc.stdout if proc.stdout.strip() else proc.stderr
+    return _result(text, is_error=proc.returncode != 0)
+
+
+def _call_tool(root: Path, name: str, arguments: dict) -> dict:
+    """Name lookup, then the repo the call names, then the run."""
+    tool = next((t for t in TOOLS if t["name"] == name), None)
+    if tool is None:
+        return _result(f"unknown tool {name!r}", is_error=True)
+    repo = arguments.get("repo") or str(root)
+    if not (Path(repo) / "crapkit.toml").is_file():
+        return _no_config_result(repo)
+    return _run_cli(tool, arguments, repo)
+
+
+def _respond(msg_id, result=None, error=None) -> dict:
+    resp = {"jsonrpc": "2.0", "id": msg_id}
+    resp["error" if error else "result"] = error if error else result
+    return resp
+
+
+def _handle(root: Path, msg: dict) -> dict | None:
+    method = msg.get("method", "")
+    if "id" not in msg:
+        return None  # a notification (e.g. notifications/initialized) needs no reply
+    if method == "initialize":
+        return _respond(msg["id"], {
+            "protocolVersion": PROTOCOL_VERSION,
+            "capabilities": {"tools": {}},
+            "serverInfo": {"name": "crapkit", "version": _version()}})
+    if method == "tools/list":
+        return _respond(msg["id"], {"tools": tool_listing()})
+    if method == "tools/call":
+        params = msg.get("params", {})
+        return _respond(msg["id"], _call_tool(root, params.get("name", ""),
+                                              params.get("arguments", {})))
+    return _respond(msg["id"], error={"code": -32601, "message": f"unknown method {method!r}"})
+
+
+def _version() -> str:
+    from . import __version__
+    return __version__
+
+
+def serve(root: Path) -> int:
+    """Newline-delimited JSON-RPC over stdio until EOF."""
+    for line in sys.stdin:
+        if not line.strip():
+            continue
+        try:
+            msg = json.loads(line)
+        except ValueError:
+            continue
+        resp = _handle(root, msg)
+        if resp is not None:
+            sys.stdout.write(json.dumps(resp) + "\n")
+            sys.stdout.flush()
+    return 0

crapkit/merge.py

@@ -0,0 +1,77 @@
+"""Merge the standard and modified lizard passes into one record per function.
+
+Pure. Join key is (path, start, end, long_name) — spans, never bare names,
+because anonymous and nested functions collide on names within a file.
+"""
+from __future__ import annotations
+
+from typing import NamedTuple
+
+
+class RawFn(NamedTuple):
+    path: str
+    long_name: str
+    start: int
+    end: int
+    ccn: int
+    nloc: int
+    params: int
+    nesting: int
+    cognitive: int = 0
+
+
+class FunctionRecord(NamedTuple):
+    path: str
+    long_name: str
+    start: int
+    end: int
+    ccn_std: int
+    ccn_mod: int
+    ccn: int
+    nloc: int
+    params: int
+    nesting: int
+    cognitive: int = 0  # Sonar-spec, from the standard pass; reporting only
+
+
+def _key(fn: RawFn) -> tuple[str, int, int, str]:
+    return (fn.path, fn.start, fn.end, fn.long_name)
+
+
+def _group_by_key(fns: list[RawFn]) -> dict[tuple, list[RawFn]]:
+    # Ordered lists, not one entry per key: two anonymous callbacks on one line
+    # share a key, and a plain dict would keep only the last twin.
+    grouped: dict[tuple, list[RawFn]] = {}
+    for f in fns:
+        grouped.setdefault(_key(f), []).append(f)
+    return grouped
+
+
+def _key_disagreements(std_by_key: dict[tuple, list[RawFn]],
+                       mod_by_key: dict[tuple, list[RawFn]]) -> list[tuple]:
+    # Keys one pass has and the other lacks; failing that, keys both have at
+    # differing multiplicity. Empty means the two passes line up exactly.
+    return sorted(set(std_by_key) ^ set(mod_by_key)) or sorted(
+        k for k, v in std_by_key.items() if len(v) != len(mod_by_key.get(k, ()))
+    )
+
+
+def merge_passes(standard: list[RawFn], modified: list[RawFn]) -> list[FunctionRecord]:
+    mod_by_key = _group_by_key(modified)
+    diff = _key_disagreements(_group_by_key(standard), mod_by_key)
+    if diff:
+        raise ValueError(f"lizard pass mismatch: {len(diff)} function key(s) differ between passes: {diff[:5]}")
+    # Both passes emit twins in the same parse order, so pairing within a key
+    # is by position.
+    taken: dict[tuple, int] = {}
+    records = []
+    for fn in standard:
+        key = _key(fn)
+        mod = mod_by_key[key][taken.get(key, 0)]
+        taken[key] = taken.get(key, 0) + 1
+        records.append(FunctionRecord(
+            path=fn.path, long_name=fn.long_name, start=fn.start, end=fn.end,
+            ccn_std=fn.ccn, ccn_mod=mod.ccn, ccn=min(fn.ccn, mod.ccn),
+            nloc=fn.nloc, params=fn.params, nesting=fn.nesting, cognitive=fn.cognitive,
+        ))
+    return records

crapkit/mutate.py

@@ -0,0 +1,96 @@
+"""Line-based mutant generation. Pure: text + changed lines in, mutants out.
+
+Diff-scoped by design: mutating a whole repo is a research project, mutating
+the lines a change touched is a review step. Operators flip comparisons,
+boolean connectives, and boolean literals — the mutants that catch a test
+suite asserting nothing. String literals are masked and comment lines skipped:
+a survivor in dead text would erode trust in the survivor list.
+"""
+from __future__ import annotations
+
+import re
+from typing import NamedTuple
+
+
+class Mutant(NamedTuple):
+    path: str
+    line: int          # 1-indexed
+    original: str      # the whole original line
+    mutated: str       # the whole mutated line
+    op: str            # "a -> b"
+
+
+# source token -> mutation targets. Negation flips plus boundary shifts —
+# the boundary mutant (> vs >=) is the one an off-by-one test hole misses.
+# Word-ish operators bind on spaces to dodge identifiers like Sand/oreo.
+_OPS = {
+    "python": {"==": ("!=",), "!=": ("==",), "<=": ("<", ">"), ">=": (">", "<"),
+               "<": ("<=", ">="), ">": (">=", "<="),
+               " and ": (" or ",), " or ": (" and ",), "True": ("False",), "False": ("True",)},
+    "typescript": {"===": ("!==",), "!==": ("===",), "==": ("!=",), "!=": ("==",),
+                   "<=": ("<", ">"), ">=": (">", "<"), "<": ("<=", ">="), ">": (">=", "<="),
+                   "&&": ("||",), "||": ("&&",), "true": ("false",), "false": ("true",)},
+}
+# a short token matching INSIDE one of these is not that operator (== in ===,
+# > in => arrows, < in <=): skip the occurrence entirely
+_PROTECT = ("===", "!==", "==", "!=", "<=", ">=", "=>", "->")
+_COMMENT_PREFIXES = ("#", "//", "/*", "*")
+_STRING_RE = re.compile(r"'[^']*'|\"[^\"]*\"|`[^`]*`")
+
+
+def _masked(line: str) -> str:
+    """String literal contents blanked, length preserved, so operator offsets
+    found on the mask apply to the real line."""
+    return _STRING_RE.sub(lambda m: " " * len(m.group()), line)
+
+
+def _occurrences(mask: str, needle: str) -> list[int]:
+    out, at = [], mask.find(needle)
+    while at != -1:
+        out.append(at)
+        at = mask.find(needle, at + 1)
+    return out
+
+
+def _covered_by_longer(mask: str, at: int, token: str) -> bool:
+    for p in _PROTECT:
+        if len(p) <= len(token):
+            continue
+        for start in range(max(0, at - len(p) + 1), at + 1):
+            if mask.startswith(p, start):
+                return True
+    return False
+
+
+def _line_mutations(line: str, ops: dict) -> list[tuple[str, str]]:
+    """(mutated_line, op_label) for every operator occurrence outside strings."""
+    mask = _masked(line)
+    out = []
+    for source, targets in ops.items():
+        for at in _occurrences(mask, source):
+            if _covered_by_longer(mask, at, source):
+                continue
+            for target in targets:
+                out.append((line[:at] + target + line[at + len(source):],
+                            f"{source.strip()} -> {target.strip()}"))
+    return out
+
+
+def file_mutants(text: str, changed_lines: set[int] | None, language: str) -> list[Mutant]:
+    ops = _OPS.get(language, _OPS["typescript"])
+    mutants = []
+    for line_no, line in enumerate(text.splitlines(), start=1):
+        if changed_lines is not None and line_no not in changed_lines:
+            continue
+        if line.strip().startswith(_COMMENT_PREFIXES):
+            continue
+        for mutated, op in _line_mutations(line, ops):
+            mutants.append(Mutant("", line_no, line, mutated, op))
+    return mutants
+
+
+def apply_mutant(text: str, mutant: Mutant) -> str:
+    lines = text.splitlines(keepends=True)
+    eol = "\n" if lines[mutant.line - 1].endswith("\n") else ""
+    lines[mutant.line - 1] = mutant.mutated + eol
+    return "".join(lines)