max / quasi

8.5 KB · 208 lines History Blame Raw

1	#!/usr/bin/env python3
2	"""The declaration transition's burn-down, as one number.
3
4	The transition converts hand-written shape functions into `declare!` blocks.
5	`population.py` counts what is still hand-written, so as conversion proceeds its
6	number falls; this counts the other side and prints both, per tree and per file.
7
8	declared 12, remaining 502 of 514 (2.3%)
9
10	That line is the progress of the whole programme. Every task in the transition
11	should move it, and a task that cannot say how much it moves it is not shaped
12	right.
13
14	python3 scripts/progress.py # the burn-down
15	python3 scripts/progress.py --files # per file, converted files hidden
16	python3 scripts/progress.py --next # the smallest unconverted files first
17
18	`--next` is the working queue: converting a whole small file is worth more than
19	converting scattered functions, because a file that is fully declared stops
20	needing its imports and its helpers can move with it.
21	"""
22
23	from __future__ import annotations
24
25	import argparse
26	import importlib.util
27	import re
28	from pathlib import Path
29
30	ROOT = Path.home() / "Code"
31	HERE = Path(__file__).resolve().parent
32
33	spec = importlib.util.spec_from_file_location("population", HERE / "population.py")
34	pop = importlib.util.module_from_spec(spec)
35	spec.loader.exec_module(pop)
36
37	TREES = {
38	"MNW/server/src/quasi": "mnw",
39	"Apps/goingson/src-tauri/src/quasi": "goingson",
40	"Apps/audiofiles/crates/audiofiles-browser/src/quasi": "audiofiles",
41	}
42
43	# `declare! {` or `quasi_declare::declare! {`, one per declared shape.
44	DECLARED = re.compile(r"\b(?:quasi_declare\s::\s)?declare\s!\s[{(]")
45
46	# The ratified starting point, so the percentage has a fixed denominator even
47	# once conversion has moved the population count. Measured 2026-09-01 and
48	# reproduced by population.py.
49	BASELINE = {"mnw": 173, "goingson": 184, "audiofiles": 157}
50
51	# COUNTED, AND NOT WORK.
52	#
53	# `population.py`'s predicate counts a function returning a description type as
54	# a shape to convert. Three kinds of thing match it and never will be converted,
55	# so they sit at the head of `--next` forever and a session not told to skip
56	# them converts nothing and reports a stall. Settled 2026-09-04 (GoingsOn
57	# `95017e31`, option (a)): the predicate does not change and the denominator
58	# stays the ratified 514, because the number's whole value is that it is
59	# comparable across waves and reproducible from the tree. They are reported
60	# instead.
61	#
62	# Two of the three categories cannot be detected mechanically and are listed
63	# here by hand, with the reason. The third -- a shape `declare!` cannot emit at
64	# all -- is detected in `unemittable()` below.
65	NOT_WORK = {
66	"MNW/server/src/quasi/tip.rs": {
67	"checkout": "`Action::with` is refused as a production; `doing` is the remedy",
68	},
69	"MNW/server/src/quasi/item_sales.rs": {"badge": "a supplier a conversion wrote"},
70	"MNW/server/src/quasi/media_picker.rs": {
71	"folder_choices": "a supplier a conversion wrote",
72	},
73	"MNW/server/src/quasi/payout_summary.rs": {
74	"figures": "a supplier a conversion wrote",
75	},
76	"MNW/server/src/quasi/widgets/carousel.rs": {
77	"region": "refused on the hard limit: a closure holding a `let mut` and an `if let`",
78	},
79	}
80
81	# The shaped types `declare!` can return. A shape function whose return type is
82	# not one of these cannot be emitted at all, whatever the form grows.
83	SHAPED = {"Node", "Screen", "Slot", "Row", "Cells", "Field", "Act"}
84
85
86	def unemittable(shape):
87	"""Whether `declare!` could never emit this shape, and why.
88
89	THE TEST IS WHETHER IT IS WORK, NOT WHETHER IT COMPILES TODAY. A shape no
90	restructuring inside its own file can make declarable is not work; one that
91	only needs restructuring is work, and most of the transition has been
92	exactly that.
93
94	So this is one rule and deliberately not three. A return type outside
95	`SHAPED` is a leaf the form has to be handed -- an `Action`, a `Tag`, a
96	`Choice`, a `Column` -- and no production reaches it. `feeds.rs`'s
97	`Surface::address` is also a method, which is a second reason for the same
98	shape: a declaration is a `fn`, never an `impl` item.
99
100	Two rules were here on 2026-09-04 and came out the same day, because both
101	answered the wrong question:
102
103	- `-> Result<T, E>` was called unemittable. Not work-free: the read is
104	hoisted out and the shape becomes infallible, which is what every
105	converted MNW screen does (`user_analytics::read`, then `pane`). It
106	flagged 49 ordinary conversions.
107	- `-> Vec<Row>` was called unemittable because R2 has no case for it. Also
108	not work-free: the rows are written at the call site inside the `list`
109	that consumes them and the supplier is deleted, which is wave 4's rule.
110	It flagged 19.
111	"""
112	ret = " ".join(shape["returns"].split())
113	head = pop.head_type(ret) or ""
114	if head not in SHAPED:
115	return f"`declare!` returns one of {'/'.join(sorted(SHAPED))}, not `{head}`"
116	return None
117
118
119	def scan():
120	per_file = {}
121	for rel in TREES:
122	for f in sorted((ROOT / rel).rglob("*.rs")):
123	parts = f.relative_to(ROOT).parts
124	if f.name in ("tests.rs", "parity.rs") or "tests" in parts:
125	continue
126	raw = f.read_text(encoding="utf-8", errors="replace")
127	blanked = pop.strip_cfg_test(pop.blank_noncode(raw))
128	key = str(f.relative_to(ROOT))
129	hand = pop.shapes_in(f)
130	per_file[key] = {
131	"tree": TREES[rel],
132	"shapes": hand,
133	"hand": len(hand),
134	"declared": len(DECLARED.findall(blanked)),
135	"lines": sum(h.get("lines", 0) for h in hand),
136	}
137	return per_file
138
139
140	def counted_but_not_work(per_file):
141	"""Every counted shape that no conversion will ever remove, with its reason.
142
143	`NOT_WORK` holds the two categories that need a human to say so; the third
144	is derived, so a new method returning an `Action` is reported the day it is
145	written rather than the day somebody notices.
146	"""
147	out = []
148	for path, v in sorted(per_file.items()):
149	for shape in v["shapes"]:
150	why = NOT_WORK.get(path, {}).get(shape["fn"]) or unemittable(shape)
151	if why:
152	out.append((path, shape["fn"], why))
153	return out
154
155
156	def main() -> int:
157	ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
158	ap.add_argument("--files", action="store_true", help="per file, fully converted files hidden")
159	ap.add_argument("--next", action="store_true", help="the smallest unconverted files first")
160	ap.add_argument("--parked", action="store_true",
161	help="the shapes the predicate counts that are not work, and why")
162	args = ap.parse_args()
163
164	per_file = scan()
165	total_base = sum(BASELINE.values())
166	declared = sum(v["declared"] for v in per_file.values())
167	remaining = sum(v["hand"] for v in per_file.values())
168	pct = 100.0 * declared / total_base if total_base else 0.0
169
170	for tree, base in BASELINE.items():
171	d = sum(v["declared"] for v in per_file.values() if v["tree"] == tree)
172	h = sum(v["hand"] for v in per_file.values() if v["tree"] == tree)
173	print(f" {tree:11} declared {d:4}, remaining {h:4} of {base}")
174	print(f"\ndeclared {declared}, remaining {remaining} of {total_base} ({pct:.1f}%)")
175
176	parked = counted_but_not_work(per_file)
177	if parked:
178	print(f"of which counted but not work: {len(parked)}")
179
180	if args.parked:
181	print("\nCounted, and not work. Never take one of these off the queue.\n")
182	for path, name, why in parked:
183	print(f" {path}:{name}\n {why}")
184
185	if args.next:
186	skip = {(path, name) for path, name, _ in parked}
187	todo = []
188	for k, v in per_file.items():
189	left = [s for s in v["shapes"] if (k, s["fn"]) not in skip]
190	if left:
191	todo.append((k, len(left), sum(s.get("lines", 0) for s in left)))
192	todo.sort(key=lambda row: (row[2], row[1]))
193	print("\nSmallest unconverted files first. A whole file is the unit worth taking.")
194	print("The counted-but-not-work shapes are already out; `--parked` lists them.\n")
195	for path, hand, lines in todo[:20]:
196	print(f" {hand:3} shapes {lines:5}L {path}")
197
198	if args.files:
199	print()
200	for k, v in sorted(per_file.items()):
201	if v["hand"]:
202	print(f" {v['declared']:3}/{v['declared'] + v['hand']:3} {k}")
203	return 0
204
205
206	if __name__ == "__main__":
207	raise SystemExit(main())
208