summaryrefslogtreecommitdiff
path: root/plugins/code-modernization/scripts/telemetry.py
blob: 5079e684e29c3a5b36935f648afdd608dc2bccbe (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
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))