diff options
| author | Claude <noreply@anthropic.com> | 2026-11-06 00:54:48 +0000 |
|---|---|---|
| committer | Claude <noreply@anthropic.com> | 2026-11-06 00:54:48 +0000 |
| commit | 7aba3deae3ff17d032c37e07d2929d1426b34278 (patch) | |
| tree | 9c482f9acda1599bd2f9bed95a6a46b75e634e80 /plugins/code-modernization/scripts/telemetry.py | |
| parent | 5472f5f56e0070feeeb464318b316714fe3e9105 (diff) | |
| parent | b8331dd69ab3e132bbf8cd6e89b5d8c1747e21b1 (diff) | |
Merge remote-tracking branch 'origin/main' into add-plugin/xcodeadd-plugin/xcode
Diffstat (limited to 'plugins/code-modernization/scripts/telemetry.py')
| -rw-r--r-- | plugins/code-modernization/scripts/telemetry.py | 732 |
1 files changed, 732 insertions, 0 deletions
diff --git a/plugins/code-modernization/scripts/telemetry.py b/plugins/code-modernization/scripts/telemetry.py new file mode 100644 index 00000000..5079e684 --- /dev/null +++ b/plugins/code-modernization/scripts/telemetry.py @@ -0,0 +1,732 @@ +#!/usr/bin/env python3 +"""Usage counts for the code-modernization plugin. Whole numbers only, never text. + + telemetry.py command UserPromptSubmit hook: which of the plugin's commands was typed, and on what kind of machine + telemetry.py state Stop hook: how far the newest system under analysis/ has got + telemetry.py run Stop hook: how the last rule extraction went (agents started, lost, unverified) + telemetry.py failure hook after a python command, a failed tool call or a failed model call: what kind of failure + telemetry.py show [DIR] [--prompt TEXT] [--json] + print what the hooks would send for the workspace DIR (default: this folder) + +The two hooks read the hook's JSON from stdin and print at most one line, {"metrics": {...}}, which Claude Code +records as usage counts when its own telemetry is on. Every key is fixed below and every value is a whole number, +capped, and rounded to two significant figures from 100 up, so a count is not a fingerprint of one system. Nothing is +read except the plugin's own artifacts under analysis/ and modernized/, and no file name, path, system name, code or +prompt text leaves this script. Nothing is sent when the plugin has not been used in the folder. It never raises, +gives up after three seconds and always exits 0. + +Off switches: CODE_MODERNIZATION_TELEMETRY=0, the plugin's "Usage counts" option, or Claude Code's own +DISABLE_TELEMETRY / CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC. Anything but an explicit "on" in the first two +switches its off. To find out why nothing was sent, set CODE_MODERNIZATION_TELEMETRY_DEBUG=1: each hook run then +appends one line saying what it decided to telemetry-debug.log in the plugin's data folder. +""" +import collections +import hashlib +import itertools +import json +import os +import platform +import re +import signal +import stat +import sys +import tempfile +import threading +import time + +sys.dont_write_bytecode = True # a hook must not leave files in the plugin's own folder +HERE = os.path.dirname(os.path.abspath(__file__)) +sys.path.insert(0, HERE) +import build_report as br # noqa: E402 (reads the artifacts safely and counts them the way the report does) + +MAX_KEYS, CAP = 20, 10 ** 9 +TRUE = {"1", "true", "on", "yes"} +# The most a key can carry: a hostile artifact cannot make a count bigger than this. Counts from 100 up are rounded to two +# significant figures; enumerations and the step bitmask are exact. +LIMITS = {"pv": 999999, "cmd": 99, "perm": 6, "has_source": 1, "fresh": 1, "systems": 99, "goal": 4, "lang": 99, "done": 65535, "phases": 99, + "os": 9, "py": 9, "pyv": 999, "pathf": 7, "tool": 99, "kind": 99, "api": 99, "err": 99, "err_at": 99999} +COUNT_LIMIT = 10 ** 7 +EXACT = {"pv", "cmd", "perm", "has_source", "fresh", "goal", "lang", "done", "os", "py", "pyv", "pathf", "tool", "kind", "api", "err", "err_at"} +NAME = re.compile(r"[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}") +LINE_WIDTH = 600 # longer lines are cut before anything is parsed, so no artifact can make a pattern slow + +# One number per command: 1 is the front door, 20-22 are the pane's own commands (panel, review-pane, sign), typed without the plugin's name. +COMMANDS = {"": 1, "preflight": 2, "assess": 3, "map": 4, "extract-rules": 5, "review": 6, "brief": 7, "transform": 8, + "uplift": 9, "reimagine": 10, "verify": 11, "harden": 12, "status": 13} +PANE = {"panel": 20, "review-pane": 21, "sign": 22} +OTHER_COMMAND = 99 +PERMISSION_MODES = {"default": 1, "acceptEdits": 2, "plan": 3, "auto": 4, "bypassPermissions": 5, "dontAsk": 6} +TOOLS = {"Bash": 1, "Read": 2, "Edit": 3, "Write": 3, "MultiEdit": 3, "NotebookEdit": 3, "Glob": 4, "Grep": 4, "Agent": 5, "Task": 5, "Workflow": 6, + "AskUserQuestion": 7, "Skill": 8, "WebFetch": 9, "WebSearch": 9} +# What went wrong, decided here from the text of a failure and never sent: first match wins. 1-5 are about the interpreter and the plugin's own scripts. +FAILURE_KINDS = [ + (2, re.compile(r"python was not found|run without arguments to install from the microsoft store", re.I)), + (3, re.compile(r"xcode-select: note|no developer tools were found|command line developer tools", re.I)), + (1, re.compile(r"\b(?:python3?|py)(?:\.exe)?: (?:command )?not found|command not found: (?:python3?|py)\b|'(?:python3?|py)' is not recognized|python3?: no such file|env: .?python3?.?: no such file", re.I)), + (4, re.compile(r"syntaxerror|requires python 3|invalid syntax", re.I)), + (6, re.compile(r"permission to use|was denied|denied by|not allowed|blocked by|auto mode", re.I)), + (7, re.compile(r"eacces|permission denied|access is denied", re.I)), + (8, re.compile(r"timed out|timeout|etimedout", re.I)), + (11, re.compile(r"enospc|no space left|out of memory|cannot allocate memory|disk quota", re.I)), + (10, re.compile(r"econnrefused|enotfound|could not resolve host|certificate|\bssl\b|proxy|unauthori[sz]ed|\b401\b|\b403\b|\b429\b", re.I)), + (9, re.compile(r"no such file|cannot find the path|enoent|does not exist|not found", re.I)), + (12, re.compile(r"scriptpath|unknown tool|workflow|subagent", re.I)), +] +API_ERRORS = [ + (1, re.compile(r"rate.?limit|\b429\b", re.I)), + (2, re.compile(r"authenticat|unauthori[sz]ed|invalid.?api.?key|\b40[13]\b|oauth", re.I)), + (3, re.compile(r"billing|credit|payment|quota", re.I)), + (6, re.compile(r"max.?output|max_tokens|too long", re.I)), + (7, re.compile(r"timeout|timed out|network|econn|connection", re.I)), + (5, re.compile(r"server.?error|overloaded|\b5\d\d\b|internal", re.I)), + (4, re.compile(r"invalid.?request|\b400\b|unrecognized_model|not_found", re.I)), +] +ERROR_CODES = [(UnicodeError, 8), (KeyError, 1), (ValueError, 2), (OSError, 3), (TypeError, 4), (AttributeError, 5), (RecursionError, 6), (MemoryError, 7)] +COMMAND_RE = re.compile(r"^/(?P<ns>code-modernization:)?modernize(?:-(?P<verb>[a-z][a-z-]*))?(?=\s|$)") + +GOALS = {"understand": 1, "uplift": 2, "transform": 3, "reimagine": 4} +GOAL_LABEL = re.compile(r"(?i)^goal\b\s*[:\u2013\u2014]?\s*(.*)$") +GOAL_WORDS = re.compile(r"(?i)(understand|uplift|transform|reimagine|rewrite|rebuild)\b") +GOAL_ALIASES = {"rewrite": "transform", "rebuild": "reimagine"} +# the pop-up's own wording, when that is what was written down +GOAL_PHRASES = [(re.compile(r"(?i)newer version|same technology"), 2), (re.compile(r"(?i)different technology|one piece at a time"), 3), + (re.compile(r"(?i)from scratch|new architecture"), 4), (re.compile(r"(?i)understand it|map it"), 1)] + +# What the code is written in: the dominant language of the map, as one of these numbers (0 unknown, 99 other). +LANGS = {"cobol": 1, "jcl": 1, "java": 2, "jsp": 2, "c#": 3, "csharp": 3, "vb": 3, "vb.net": 3, "f#": 3, "python": 4, "php": 5, + "perl": 6, "c": 7, "c++": 8, "cpp": 8, "javascript": 9, "typescript": 9, "js": 9, "ts": 9, "node": 9, "angularjs": 9, + "ruby": 10, "go": 11, "golang": 11, "rust": 12, "kotlin": 13, "scala": 13, "groovy": 13, "sql": 14, "plsql": 14, + "pl/sql": 14, "tsql": 14, "fortran": 15, "rpg": 16, "rpgle": 16, "pascal": 17, "delphi": 17, "shell": 18, "bash": 18, + "assembler": 19, "assembly": 19, "hlasm": 19, "asp": 3, "vb6": 3, "nodejs": 9, "c/c++": 7} +# labels in a map that are not a language somebody modernizes +NOT_CODE = {"artifact", "make", "makefile", "cmake", "yaml", "yml", "json", "xml", "toml", "ini", "markdown", "md", "text", "txt", "html", "css", + "pkgconfig", "config", "properties", "docker", "dockerfile", "csv", "svg", "data", "binary", "license", "gradle", "maven", "unknown", "other"} + +# `done` adds up one of these for every step that has left its file: 15 = preflight, assess, map and rules. +STEPS = [("preflight", 1), ("assess", 2), ("map", 4), ("rules", 8), ("reviewed", 16), ("brief", 32), ("approved", 64), + ("built", 128), ("verified", 256), ("signed", 512), ("hardened", 1024), ("report", 2048), ("deltas", 4096), + ("baseline", 8192), ("playbook", 16384), ("spec", 32768)] +# Files that only this plugin writes: a folder with none of them is not something the plugin has worked on. +GATE = ("INTENT.md", "PREFLIGHT.md", "MODERNIZATION_BRIEF.md", "BUSINESS_RULES.md", "DELTA_CATALOG.md", "VERIFICATION.json", "RULE_REVIEWS.json", "AI_NATIVE_SPEC.md") +FILES = {"preflight": "PREFLIGHT.md", "assess": "ASSESSMENT.md", "map": "topology.json", "brief": "MODERNIZATION_BRIEF.md", + "verified": "VERIFICATION.json", "hardened": "SECURITY_FINDINGS.md", "report": "REPORT.html", + "deltas": "DELTA_CATALOG.md", "baseline": "BASELINE.md", "playbook": "PLAYBOOK.md", "spec": "AI_NATIVE_SPEC.md"} + +# Every key that can be sent, and what it counts. Order is send order; the version comes first so it always survives. +MEANING = collections.OrderedDict([ + ("pv", "plugin version as major*10000 + minor*100 + patch"), + ("cmd", "command typed: 1 front door, 2 preflight, 3 assess, 4 map, 5 extract-rules, 6 review, 7 brief, 8 transform, " + "9 uplift, 10 reimagine, 11 verify, 12 harden, 13 status, 20-22 pane commands, 99 other"), + ("perm", "permission mode the session ran in: 0 unknown, 1 default, 2 accept edits, 3 plan, 4 auto, 5 bypass, 6 don't ask"), + ("has_source", "1 when the command carried --source"), + ("fresh", "1 when the system has no artifacts yet"), + ("systems", "systems under analysis/"), + ("goal", "0 unknown, 1 understand, 2 uplift, 3 transform, 4 reimagine"), + ("lang", "dominant language of the map: 1 COBOL, 2 Java, 3 C#/.NET, 4 Python, 5 PHP, 6 Perl, 7 C, 8 C++, " + "9 JavaScript/TypeScript, 10 Ruby, 11 Go, 12 Rust, 13 Kotlin/Scala, 14 SQL, 15 Fortran, 16 RPG, 17 Pascal/Delphi, " + "18 shell, 19 assembler, 99 other, 0 unknown"), + ("done", "steps that have left their file, added up: " + ", ".join("%s=%d" % s for s in STEPS)), + ("map_kloc", "thousand lines of code in the map"), + ("rules", "business rules found"), + ("p0", "of those, the critical (P0) ones"), + ("rev_ok", "rules a person confirmed"), + ("rev_wrong", "rules a person marked wrong"), + ("phases", "phases in the plan"), + ("built", "modules or services built (an uplift's working copy counts as one once it exists)"), + ("eq_cases", "old-versus-new comparison cases run"), + ("eq_diff", "of those, differences or missing outputs nobody approved"), + ("eq_appr", "differences a person approved"), + ("v_proven", "modules judged PROVEN"), + ("v_partly", "modules judged PARTLY PROVEN"), + ("v_not", "modules judged NOT PROVEN"), + ("sec_crit", "critical security findings"), + ("sec_high", "high security findings"), + ("os", "system: 1 macOS, 2 Linux, 3 Windows, 4 Windows subsystem for Linux, 0 other"), + ("py", "how python worked: 0 python3 ran, 1 none found, 2 macOS developer-tools stub, 3 python3 present but broken (the Windows Store stub), " + "4 python3 unusable but python or py ran, 5 too old, 6 the script crashed"), + ("pyv", "python version as major*100 + minor (311 is 3.11)"), + ("pathf", "the folder's path: 1 has a space, 2 has non-ASCII characters, 4 is over 200 characters (added up)"), + ("tool", "the tool that failed: 1 Bash, 2 Read, 3 Edit or Write, 4 Glob or Grep, 5 agent, 6 Workflow, 7 asking the person, 8 skill, 9 web, 10 a connector, 99 other"), + ("kind", "what went wrong: 1 python or another interpreter missing, 2 the Windows Store python stub, 3 the macOS developer-tools stub, 4 python too old or a syntax error, " + "5 one of the plugin's scripts raised an error, 6 blocked by a permission rule or policy, 7 a file permission was denied, 8 timed out, 9 a file or folder was not found, " + "10 network, certificate or sign-in, 11 disk or memory, 12 workflow or agent trouble, 99 other"), + ("api", "a model call ended a turn: 1 rate limit, 2 sign-in failed, 3 billing, 4 invalid request, 5 server error or overloaded, 6 output too long, 7 network or timeout, 99 unknown"), + ("err", "the plugin's own script raised: 1 KeyError, 2 ValueError, 3 OSError, 4 TypeError, 5 AttributeError, 6 RecursionError, 7 MemoryError, 8 UnicodeError, 99 other"), + ("err_at", "the line of telemetry.py where it raised"), + ("agents", "agents the last rule extraction started"), + ("wf_failed", "modules or agents that extraction lost"), + ("wf_skip", "modules that extraction skipped"), + ("wf_unver", "rules that extraction could not verify"), +]) +COMMAND_KEYS = ("pv", "cmd", "perm", "has_source", "fresh", "systems", "goal", "done", "os", "py", "pyv", "pathf") +RUN_KEYS = ("pv", "agents", "wf_failed", "wf_skip", "wf_unver") +FAILURE_KEYS = ("pv", "os", "py", "pyv", "pathf", "tool", "kind", "api") +ERROR_KEYS = ("pv", "os", "py", "pyv", "err", "err_at") +STATE_KEYS = ("pv", "goal", "lang", "done", "map_kloc", "rules", "p0", "rev_ok", "rev_wrong", "phases", "built", "eq_cases", + "eq_diff", "eq_appr", "v_proven", "v_partly", "v_not", "sec_crit", "sec_high") + + +def off_reason(env=None): + """Why nothing is sent, or "" when counts may be sent. Sending needs the plugin's switches to be unset or an explicit + "on": any other word (off, no, 0, disabled) turns it off.""" + env = os.environ if env is None else env + val = lambda key: str(env.get(key, "")).strip().lower() # noqa: E731 + if val("CODE_MODERNIZATION_TELEMETRY") and val("CODE_MODERNIZATION_TELEMETRY") not in TRUE: + return "CODE_MODERNIZATION_TELEMETRY is off" + if val("CLAUDE_PLUGIN_OPTION_TELEMETRY") and val("CLAUDE_PLUGIN_OPTION_TELEMETRY") not in TRUE: + return "the plugin's Usage counts option is off" + for key in ("DISABLE_TELEMETRY", "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC"): + if val(key) in TRUE: + return "%s is set" % key + return "" + + +def whole(value): + """A whole number from 0 to CAP, whatever the artifact held.""" + if isinstance(value, bool): + return int(value) + try: + return max(0, min(CAP, int(value))) + except (TypeError, ValueError, OverflowError): + return 0 + + +def plugin_version(): + try: + with open(os.path.join(HERE, "..", ".claude-plugin", "plugin.json"), encoding="utf-8") as fh: + major, minor, patch = (int(x) for x in str(json.load(fh)["version"]).split(".")[:3]) + return major * 10000 + minor * 100 + patch + except (OSError, ValueError, KeyError, TypeError): + return 0 + + +def plain(path): + return os.path.isfile(path) and not os.path.islink(path) + + +def inside(cwd, path): + """True when path really lives under cwd (links that lead elsewhere are not followed).""" + try: + root = os.path.realpath(cwd) + return os.path.commonpath([root, os.path.realpath(path)]) == root + except ValueError: + return False + + +def systems_in(cwd): + """[(newest modification time, name)] of the folders under analysis/, newest first.""" + out, folder = [], os.path.join(cwd, "analysis") + if os.path.islink(folder) or not inside(cwd, folder): + return out + try: + entries = list(itertools.islice(os.scandir(folder), 200)) + except OSError: + return out + for e in entries: + if e.name.startswith(".") or e.is_symlink() or not e.is_dir(): + continue + try: + times = [e.stat().st_mtime] + kids = list(itertools.islice(os.scandir(e.path), 200)) + except OSError: + continue + for x in kids: + try: + times.append(x.stat().st_mtime) + except OSError: # a dangling link or a file that just went away + pass + out.append((max(times), e.name)) + return sorted(out, reverse=True) + + +def language_code(topo): + """The language with the most lines in the map, as its number.""" + weight, nodes = collections.Counter(), [] + + def walk(node, depth): + if isinstance(node, dict) and depth < 12: + nodes.append(node) + for child in node.get("children") or []: + walk(child, depth + 1) + + if isinstance(topo, dict): + walk(topo.get("root"), 0) + for n in nodes: + lang = n.get("language") + if not n.get("children") and isinstance(lang, str) and isinstance(n.get("loc"), int) and n["loc"] > 0: + low = lang.strip().lower()[:40] + first = re.match(r"[a-z0-9#+]+", low) + first = first.group(0) if first else "" + if low in NOT_CODE or first in NOT_CODE: + continue # build files, data and the like are not what is being modernized + weight[LANGS.get(low) or LANGS.get(first) or 99] += n["loc"] + return min(weight, key=lambda c: (-weight[c], c)) if weight else 0 + + +def goal_code(text, built): + """From the answer written after "Goal" in INTENT.md (its first words, not the sentences around it), else from what was built.""" + lines = [re.sub(r"[*`_#>\-]", " ", l).strip() for l in (text or "").split("\n")[:60]] + for i, line in enumerate(lines): + m = GOAL_LABEL.match(line) + if not m: + continue + rest = m.group(1) + if not rest: # a heading: the answer is on the next line that has words + rest = next((l for l in lines[i + 1:i + 4] if l), "") + rest = (GOAL_LABEL.match(rest) or GOAL_LABEL.match("goal " + rest)).group(1) + word = GOAL_WORDS.match(rest) + if word: + word = word.group(1).lower() + return GOALS[GOAL_ALIASES.get(word, word)] + for pattern, code in GOAL_PHRASES: + if pattern.search(rest[:100]): + return code + break + return {"": 3, "-uplifted": 2, "-reimagined": 4}.get(built, 0) + + +def built_kind_and_count(cwd, system): + """(which kind of build is newest: '' rewrite, '-uplifted' or '-reimagined'; how many modules or services).""" + total, kinds = 0, [] + for suffix in ("", "-uplifted", "-reimagined"): + root = os.path.join(cwd, "modernized", system + suffix) + if os.path.islink(root) or not inside(cwd, root): + continue + try: + kids = [e for e in os.scandir(root) if not e.name.startswith(".") and not e.is_symlink()] + newest = max(e.stat().st_mtime for e in kids) if kids else 0 + except OSError: + continue + if not kids: + continue + dirs = [e for e in kids if e.is_dir()] + total += 1 if suffix == "-uplifted" else (len(dirs) or 1) + kinds.append((newest, suffix)) + return (max(kinds)[1] if kinds else None), total + + +def snapshot(cwd, system): + """The counts for one system, or None when the plugin has left nothing there yet.""" + src = br.Source(cwd, system) + path = lambda name: os.path.join(src.adir, name) # noqa: E731 + + def text(name): + raw = src.read(path(name), name) + return None if raw is None else "\n".join(line[:LINE_WIDTH] for line in raw.split("\n")) + + if not any(plain(path(name)) for name in GATE): + return None + done, out = 0, collections.OrderedDict((k, 0) for k in STATE_KEYS) + present = {step: plain(path(FILES[step])) for step in FILES} + + rules_text = text("BUSINESS_RULES.md") + reviews, _ = src.json(path("RULE_REVIEWS.json"), "RULE_REVIEWS.json") + reviews = {k: v for k, v in reviews["reviews"].items() if isinstance(v, dict)} if isinstance(reviews, dict) and isinstance(reviews.get("reviews"), dict) else {} + cards = [b for b in br.parse_rules(rules_text) if b["k"] == "rule"] if rules_text else [] + if cards: + facts = br.rule_facts(rules_text, cards, reviews) + out["rules"], out["p0"] = whole(facts["total"]), whole(facts["byPriority"].get("P0", 0)) + present["rules"] = True + verdicts = collections.Counter(str(v.get("verdict", "")).lower() for v in reviews.values()) + out["rev_ok"], out["rev_wrong"] = whole(verdicts["confirmed"]), whole(verdicts["wrong"]) + present["reviewed"] = bool(reviews) + + topo, _ = src.json(path("topology.json"), "topology.json") + facts = br.topology_facts(topo) + out["map_kloc"] = whole(facts["loc"] // 1000) if facts else 0 + out["lang"] = language_code(topo) + + brief = text("MODERNIZATION_BRIEF.md") or "" + out["phases"] = len(re.findall(r"(?m)^#{2,4}[ \t]*Phase[ \t]+\d+", brief)) + for line in brief.split("\n"): + m = re.match(r"(?i)^\s*Approved by\s*:(.*?)(?:Date\s*:.*)?$", line) + if m: + present["approved"] = bool(re.search(r"[A-Za-z0-9]", m.group(1))) + break + + # counted from the case list and the modules' own checks, the way the report does, never from the file's own totals + eq, _ = src.json(path("EQUIVALENCE.json"), "EQUIVALENCE.json") + view = br.equivalence_view(eq) + if view: + tally = view["tally"] + out["eq_cases"] = whole(tally["executed"]) + out["eq_diff"] = whole(sum(tally.get(k, 0) for k in ("differs", "missing", "inconsistent", "unknown"))) + out["eq_appr"] = whole(tally.get("differs-approved", 0)) + + ver, _ = src.json(path("VERIFICATION.json"), "VERIFICATION.json") + proof = br.proof_view(ver) + if proof: + out["v_proven"], out["v_partly"], out["v_not"] = (whole(proof["counts"].get(k)) for k in ("PROVEN", "PARTLY PROVEN", "NOT PROVEN")) + present["signed"] = bool(proof["signoff"]["name"].strip() and proof["signoff"]["decision"].strip()) + + security = br.security_facts(text("SECURITY_FINDINGS.md") or "") or {} + out["sec_crit"], out["sec_high"] = whole(security.get("Critical")), whole(security.get("High")) + + kind, out["built"] = built_kind_and_count(cwd, system) + present["built"] = bool(out["built"]) + for step, bit in STEPS: + done |= bit if present.get(step) else 0 + out["done"] = done + out["goal"] = goal_code(text("INTENT.md"), kind) + out["pv"] = plugin_version() + return out + + +def os_code(): + """1 macOS, 2 Linux, 3 Windows, 4 WSL, 0 other. The shell wrapper knows best (uname); this is the fallback.""" + given = os.environ.get("CODE_MODERNIZATION_OS", "") + if given.isdigit(): + return min(int(given), 9) + system = platform.system().lower() + if system == "linux": + try: + with open("/proc/version", encoding="utf-8", errors="replace") as fh: + return 4 if "microsoft" in fh.read().lower() else 2 + except OSError: + return 2 + return {"darwin": 1, "windows": 3}.get(system, 0) + + +def python_status(): + """0 when python3 itself ran this; the shell wrapper says 4 when it had to fall back to python or py.""" + given = os.environ.get("CODE_MODERNIZATION_PY", "") + return min(int(given), 9) if given.isdigit() else 0 + + +def path_flags(cwd): + """The bits of a folder path that break scripts on Windows: 1 a space, 2 a non-ASCII character, 4 over 200 characters.""" + given = os.environ.get("CODE_MODERNIZATION_PATHF", "") + if given.isdigit(): + return min(int(given), 7) + return (1 if " " in cwd else 0) + (2 if any(ord(c) > 126 for c in cwd) else 0) + (4 if len(cwd) > 200 else 0) + + +def environment(cwd): + return [("os", os_code()), ("py", python_status()), ("pyv", sys.version_info[0] * 100 + sys.version_info[1]), ("pathf", path_flags(cwd))] + + +def system_word(words): + """The first plain word of a command's arguments, which is the system's name (a flag's value is not).""" + skip = False + for w in words: + if skip: + skip = False + elif w.startswith("-"): + skip = w == "--source" + elif NAME.fullmatch(w): + return w + return None + + +def command_metrics(prompt, cwd, permission_mode=None): + """The counts for one typed prompt, or None when it is not one of the plugin's commands.""" + m = COMMAND_RE.match(str(prompt or "").lstrip()) + if not m: + return None + verb = m.group("verb") or "" + if m.group("ns"): + cmd = COMMANDS.get(verb, OTHER_COMMAND) + elif verb in PANE: + cmd = PANE[verb] + elif verb in COMMANDS: + cmd = COMMANDS[verb] + else: + return None # another tool's /modernize-something + words = str(prompt).lstrip()[m.end():].split() + systems = systems_in(cwd) + named = system_word(words) + if named in {n for _, n in systems}: + system = named + else: # a name that does not exist yet is a new system; no name at all means the newest one + system = None if named else (systems[0][1] if systems else None) + snap = snapshot(cwd, system) if system else None + perm = PERMISSION_MODES.get(permission_mode, 0) if isinstance(permission_mode, str) else 0 + return collections.OrderedDict([("pv", plugin_version()), ("cmd", cmd), ("perm", perm), ("has_source", int("--source" in words)), + ("fresh", int(snap is None)), ("systems", min(len(systems), 99)), + ("goal", snap["goal"] if snap else 0), ("done", snap["done"] if snap else 0)] + environment(cwd)) + + +def health_metrics(cwd): + """Once per version and machine (the shell wrapper keeps count): what the plugin is running on.""" + return collections.OrderedDict([("pv", plugin_version())] + environment(cwd)) + + +def run_metrics(cwd): + """How the newest system's last rule extraction went, from the statistics the workflow wrote, or None.""" + for _, system in systems_in(cwd)[:5]: + src = br.Source(cwd, system) + result, _ = src.json(os.path.join(src.adir, "rules_result.json"), "rules_result.json") + stats = result.get("stats") if isinstance(result, dict) and isinstance(result.get("stats"), dict) else None + if stats is None: + continue + size = lambda key: len(stats[key]) if isinstance(stats.get(key), list) else 0 # noqa: E731 + return collections.OrderedDict([("pv", plugin_version()), ("agents", whole(stats.get("agents"))), ("wf_failed", size("failedModules") + size("droppedModules")), + ("wf_skip", size("skippedModules")), ("wf_unver", whole(stats.get("unverified")))]) + return None + + +def tool_code(name): + name = str(name or "") + return TOOLS.get(name) or (10 if name.startswith("mcp__") else 99) + + +def failure_kind(text): + """A code for what went wrong, decided from the failure's own text (which is never sent), or None when it says nothing useful.""" + text = str(text or "")[:8000] + if "Traceback" in text and ("code-modernization" in text or "scripts/" in text or "scripts\\" in text): + return 5 + for code, pattern in FAILURE_KINDS: + if pattern.search(text): + return code + return None + + +def failure_metrics(data, cwd): + """One failure as numbers: a failed tool call, or a model call that ended a turn. None when there is nothing to say.""" + event, session = str(data.get("hook_event_name") or ""), str(data.get("session_id") or "") + base = [("pv", plugin_version())] + environment(cwd) + if event == "StopFailure": + text = " ".join(str(data.get(k) or "") for k in ("error", "error_type", "error_details", "message"))[:2000] + api = next((code for code, pattern in API_ERRORS if pattern.search(text)), 99) + tag, extra = "api%d" % api, [("api", api)] + else: + if data.get("is_interrupt") is True: + return None + tool, error = tool_code(data.get("tool_name")), str(data.get("error") or "") + kind = failure_kind(error) + if kind is None: + if tool == 1 and re.fullmatch(r"\s*Exit code \d+\s*", error): + return None # a command that simply exited non-zero, often on purpose + kind = 99 + tag, extra = "t%dk%d" % (tool, kind), [("tool", tool), ("kind", kind)] + if remember("fail|%s|%s" % (session, tag), "1") != "new": # once per session and kind, so a loop of failures is one number + return None + return collections.OrderedDict(base + extra) + + +def state_metrics(cwd): + """The counts for the newest system under cwd that the plugin has worked on, or None.""" + for _, system in systems_in(cwd)[:5]: + snap = snapshot(cwd, system) + if snap is not None: + return snap + return None + + +def rounded(value): + """Two significant figures from 100 up (17727 becomes 18000), so a count says roughly how big, not exactly which system.""" + if value < 100: + return value + scale = 10 ** (len(str(value)) - 2) + return (value + scale // 2) // scale * scale + + +def ok(metrics): + """Only keys this script defines, only whole numbers within their limit, counts rounded, at most MAX_KEYS of them.""" + out = collections.OrderedDict() + for k, v in list(metrics.items())[:MAX_KEYS]: + if k in MEANING: + v = min(whole(v), LIMITS.get(k, COUNT_LIMIT)) + out[k] = v if k in EXACT else rounded(v) + return out + + +def data_dir(): + """The plugin's own data folder, or a private folder in the temp directory; None when neither can be used safely.""" + uid = getattr(os, "getuid", lambda: 0)() + base = os.environ.get("CLAUDE_PLUGIN_DATA") or "" + base = os.path.realpath(base) if os.path.isdir(base) else os.path.join(tempfile.gettempdir(), "code-modernization-%s" % uid) + try: + os.makedirs(base, mode=0o700, exist_ok=True) + st = os.lstat(base) + except OSError: + return None + if os.path.islink(base) or not stat.S_ISDIR(st.st_mode) or (hasattr(st, "st_uid") and st.st_uid != uid): + return None + return base + + +def note(text): + """With CODE_MODERNIZATION_TELEMETRY_DEBUG=1, one line saying what a hook run decided, in telemetry-debug.log in the data + folder (a link is never followed, and the file is cut down when it grows past 200 KB). Never raises.""" + if str(os.environ.get("CODE_MODERNIZATION_TELEMETRY_DEBUG", "")).strip().lower() not in TRUE: + return + base = data_dir() + if not base: + return + file = os.path.join(base, "telemetry-debug.log") + try: + if os.path.getsize(file) > 200000: + os.remove(file) + except OSError: + pass + try: + fd = os.open(file, os.O_WRONLY | os.O_APPEND | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0), 0o600) + with os.fdopen(fd, "a", encoding="utf-8") as fh: + fh.write("%s %s\n" % (time.strftime("%H:%M:%S"), text)) + except OSError: + pass + + +def remember(key, digest): + """"new" when this workspace's counts changed since they were last sent and the new state is stored, "same" when + they did not, "cannot" when the state cannot be stored: nothing is sent then, it would repeat at the end of every turn.""" + base = data_dir() + if not base: + return "cannot" + try: + file = os.path.join(base, "telemetry-state.json") + try: + with open(file, encoding="utf-8") as fh: + seen = json.load(fh) + except (OSError, ValueError): + seen = {} + seen = seen if isinstance(seen, dict) else {} + if seen.get(key) == digest: + return "same" + seen.pop(key, None) + seen[key] = digest + seen = dict(list(seen.items())[-200:]) + tmp = "%s.%d" % (file, os.getpid()) + with open(tmp, "w", encoding="utf-8") as fh: + json.dump(seen, fh) + os.replace(tmp, file) + return "new" + except OSError: + return "cannot" + + +def digest_of(metrics): + return hashlib.sha1(json.dumps(metrics, sort_keys=True).encode()).hexdigest()[:12] + + +def hook(mode): + """Run one hook. Whatever an artifact holds, a turn is never held up for more than a few seconds.""" + if hasattr(signal, "SIGALRM"): + signal.signal(signal.SIGALRM, lambda *_: os._exit(0)) + signal.alarm(3) + try: + run_hook(mode) + finally: + signal.alarm(0) + else: # Windows has no alarm signal: a timer thread gives up instead + timer = threading.Timer(3, os._exit, [0]) + timer.daemon = True + timer.start() + try: + run_hook(mode) + finally: + timer.cancel() + timer.join(1) + + +def run_hook(mode): + reason = off_reason() + if reason: + return note("%s: not sent, %s" % (mode, reason)) + try: + data = json.loads(sys.stdin.read(1 << 20) or "{}") + except ValueError: + data = {} + data = data if isinstance(data, dict) else {} + cwd = data.get("cwd") if isinstance(data.get("cwd"), str) and os.path.isdir(data.get("cwd")) else os.getcwd() + why = "" + if mode == "command": + metrics = command_metrics(data.get("prompt"), cwd, data.get("permission_mode")) + why = "not one of the plugin's commands" + elif mode == "health": + metrics, why = health_metrics(cwd), "" + elif mode == "failure": + metrics = failure_metrics(data, cwd) + why = "nothing worth counting, or the same kind was already sent this session" + else: + metrics = run_metrics(cwd) if mode == "run" else state_metrics(cwd) + why = "the plugin has left no files here" + if metrics is not None: + key = hashlib.sha1((os.path.realpath(cwd) + mode).encode()).hexdigest()[:16] + status = remember(key, digest_of(ok(metrics))) + if status != "new": + metrics, why = None, "the counts are the same as last time" if status == "same" else "the state file cannot be written" + if metrics: + print(json.dumps({"metrics": ok(metrics)}, separators=(",", ":")), flush=True) + note("%s: sent %d values" % (mode, len(ok(metrics)))) + else: + note("%s: not sent, %s" % (mode, why)) + + +def show(args): + """What the hooks would send for a workspace, in words.""" + cwd, prompt, as_json, i = None, None, False, 0 + while i < len(args): + if args[i] == "--json": + as_json = True + elif args[i] == "--prompt": + prompt, i = args[i + 1] if i + 1 < len(args) else "", i + 1 + elif not args[i].startswith("--") and cwd is None: + cwd = os.path.abspath(args[i]) + i += 1 + cwd = cwd or os.getcwd() + example = prompt is None + prompt = "/code-modernization:modernize-status" if example else prompt + state, command = state_metrics(cwd), command_metrics(prompt, cwd) + if as_json: + print(json.dumps({"off": off_reason(), "state": ok(state) if state else None, "command": ok(command) if command else None})) + return + + def table(title, metrics, empty): + print(title) + if metrics is None: + print(" " + empty + "\n") + return + for k, v in ok(metrics).items(): + note = MEANING[k].split(":")[0] if k in ("cmd", "lang", "done") else MEANING[k] + if k == "done": + note += ": " + (", ".join(n for n, bit in STEPS if v & bit) or "nothing yet") + print(" %-10s %-8d %s" % (k, v, note)) + print() + + reason = off_reason() + print("Usage counts for %s" % cwd) + print("Sending is OFF: %s.\n" % reason if reason else "Sending is on. Turn it off with CODE_MODERNIZATION_TELEMETRY=0 or the plugin's Usage counts option.\n") + table("When a turn ends and these counts have changed:", state, "nothing: the plugin has left no artifacts here yet") + table("When you type %s%s:" % ("a command, for example " if example else "", prompt.split()[0] if prompt.split() else "nothing"), command, + "nothing: that is not one of the plugin's commands") + + +def report_error(err, line): + """The plugin's own script raised: send which kind and where, once, never the message.""" + if off_reason(): + return + code = next((c for kind, c in ERROR_CODES if isinstance(err, kind)), 99) + if remember("err|%s|%s|%s" % (plugin_version(), code, line), "1") == "new": + print(json.dumps({"metrics": ok(collections.OrderedDict([("pv", plugin_version()), ("os", os_code()), ("py", python_status()), + ("pyv", sys.version_info[0] * 100 + sys.version_info[1]), ("err", code), ("err_at", line)]))}, + separators=(",", ":")), flush=True) + + +def main(argv): + mode = argv[1] if len(argv) > 1 else "" + try: + if mode == "show": + show(argv[2:]) + elif mode in ("command", "state", "run", "failure", "health"): + hook(mode) + else: + print(__doc__) + except Exception as err: # a usage count must never break the person's session + if mode == "show": + raise + tb = err.__traceback__ + while tb and tb.tb_next: + tb = tb.tb_next + line = tb.tb_lineno if tb else 0 + note("%s: error %s at line %s" % (mode, type(err).__name__, line)) + try: + report_error(err, line) + except Exception: # reporting a problem must not become one + pass + return 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv)) |
