@xiaohuo123212/elench 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +53 -0
  3. package/README.md +298 -2
  4. package/bin/elench.js +69 -0
  5. package/package.json +37 -4
  6. package/scripts/clean-pycache.js +37 -0
  7. package/scripts/npm_smoke.js +88 -0
  8. package/src/README-/345/205/274/345/256/271/345/261/202.md +26 -0
  9. package/src/ast_util.py +111 -0
  10. package/src/bench.py +376 -0
  11. package/src/borrow.py +282 -0
  12. package/src/bound.py +13 -0
  13. package/src/cfg.py +219 -0
  14. package/src/chart.py +209 -0
  15. package/src/check_docs.py +156 -0
  16. package/src/checker.py +2473 -0
  17. package/src/contract_metric.py +87 -0
  18. package/src/cost_check.py +13 -0
  19. package/src/cost_diff.py +533 -0
  20. package/src/cost_domain/__init__.py +32 -0
  21. package/src/cost_domain/bound.py +739 -0
  22. package/src/cost_domain/cost_check.py +394 -0
  23. package/src/cost_domain/cost_interp.py +1998 -0
  24. package/src/cost_domain/symbolic.py +554 -0
  25. package/src/cost_explain.py +503 -0
  26. package/src/cost_interp.py +13 -0
  27. package/src/cxx_map.py +184 -0
  28. package/src/dispatch.py +314 -0
  29. package/src/dsh.py +3980 -0
  30. package/src/dup_scan.py +180 -0
  31. package/src/elench.py +15 -0
  32. package/src/emit.py +56 -0
  33. package/src/ffi_c.py +70 -0
  34. package/src/fmt.py +115 -0
  35. package/src/formatter.py +596 -0
  36. package/src/grammar.py +272 -0
  37. package/src/guarantees.py +116 -0
  38. package/src/highlight.py +156 -0
  39. package/src/interp.py +2119 -0
  40. package/src/isolated.py +161 -0
  41. package/src/jsonval.py +236 -0
  42. package/src/kappa_vs_measured.py +347 -0
  43. package/src/kinds.py +122 -0
  44. package/src/lexer.py +559 -0
  45. package/src/migrate_docs.py +115 -0
  46. package/src/otel.py +579 -0
  47. package/src/otel_dashboard.py +218 -0
  48. package/src/otel_export.py +380 -0
  49. package/src/otel_local_sink.py +141 -0
  50. package/src/otel_view.py +156 -0
  51. package/src/parser.py +1909 -0
  52. package/src/parser.py.bak +1781 -0
  53. package/src/policy.py +271 -0
  54. package/src/rename_ch.py +81 -0
  55. package/src/requires.py +242 -0
  56. package/src/segment_plan.py +150 -0
  57. package/src/shape.py +130 -0
  58. package/src/stdlib.py +1856 -0
  59. package/src/stdlib.py.bak +1751 -0
  60. package/src/symbolic.py +13 -0
  61. package/src/sync_docs.py +225 -0
  62. package/src/test_checker.py.bak +443 -0
  63. package/src/test_formatter.py.bak +201 -0
  64. package/src/test_invalid.py.bak +342 -0
  65. package/src/test_parser.py.bak +423 -0
  66. package/src/typecheck.py +865 -0
  67. package/src/typecheck.py.bak +741 -0
  68. package/src/typenames.py +56 -0
  69. package/src/walk.py +197 -0
@@ -0,0 +1,394 @@
1
+ #!/usr/bin/env python3
2
+ # SPDX-License-Identifier: Apache-2.0
3
+ # Copyright 2026 Elench contributors
4
+
5
+ # -*- coding: utf-8 -*-
6
+ """cost_check.py —— 静态闭环:把算出来的成本式与 spec 的 `target` 比。
7
+
8
+ **这一步是 §7.0.1 说的「静态负责契约」**:
9
+ κ_impl(算出来的) vs κ_target(spec 里声明的)
10
+
11
+ ## `O(...)` 是「至多常数倍」,不是「精确相等」
12
+
13
+ 这一条必须先说清楚,否则结论全错:
14
+
15
+ target { time: { max: O(n) } }
16
+
17
+ 意思是 **∃c, N:∀n > N,κ_impl(n) ≤ c·n**。
18
+ 如果按"精确 ≤"去比,那任何函数都超标——因为任何真实函数都有常数开销
19
+ (`9 + 3n` 在 n = 2 时是 15 > 2)。
20
+
21
+ 所以判据是**比值是否有界**:
22
+
23
+ r(n) = κ_impl(n) / κ_target(n)
24
+ r 在 n 很大时**有界** → 达成
25
+ r **随 n 增长** → 超标(阶不够)
26
+
27
+ ## 怎么判断"有界"
28
+
29
+ 在 n = 2^8 … 2^40 上算 r,对 log2(r) 做最小二乘拟合:
30
+
31
+ 斜率 ≈ 0 → 有界(达成)
32
+ 斜率 > 0.05 → 每翻一倍 n,比值涨 3.5% 以上 → 阶不够(超标)
33
+
34
+ **为什么不用 SMT**:表达式里有 `log2` 与 `max`,SMT 要么编不出来要么很慢;
35
+ 而我们只需要"阶够不够"这个判断,数值拟合足够,而且**错了也不会撒谎**——
36
+ 斜率只说明"观察到的趋势",不宣称"证明了"。
37
+
38
+ ## 多尺寸变量
39
+
40
+ 成本式里有多个尺寸时,本工具**把所有尺寸都设成同一个 n** 再比。
41
+ 这是简化,结论要标注「按同规模假设」——真实的最坏组合可能需要人来判。
42
+ """
43
+
44
+ import math
45
+ import sys
46
+ from typing import Dict, List, Optional, Tuple
47
+
48
+ from .symbolic import Cost
49
+
50
+ # n 的梯子:2^8 .. 2^40。太小会被常数项淹没,太大没必要。
51
+ LADDER = [2 ** k for k in range(8, 41)]
52
+
53
+ # 斜率阈值:log2(比值) 对 k 的斜率。0.05 ≈ 每翻倍涨 3.5%。
54
+ SLOPE_TOL = 0.05
55
+
56
+
57
+ # ---------------------------------------------------------------- 求值
58
+
59
+ def evaluate(c: Optional[Cost], env: Dict[str, float], depth: int = 0) -> float:
60
+ """在给定尺寸赋值下求出成本式的数值;⊤ 视为 +inf。"""
61
+ if c is None:
62
+ return 0.0
63
+ if depth > 200:
64
+ return float("inf")
65
+ k = c.kind
66
+ if k == "num":
67
+ return float(c.value)
68
+ if k == "size":
69
+ return float(env.get(c.value, 1.0))
70
+ if k == "sym":
71
+ # `k(visit)`:**给不出值就是 ⊤**(不许按 1 算——那会低估上界)
72
+ return float(env.get(str(c.value), float("inf")))
73
+ if k == "top":
74
+ return float("inf")
75
+ if k == "add":
76
+ return evaluate(c.args[0], env, depth + 1) + evaluate(c.args[1], env, depth + 1)
77
+ if k == "mul":
78
+ return evaluate(c.args[0], env, depth + 1) * evaluate(c.args[1], env, depth + 1)
79
+ if k == "max":
80
+ return max(evaluate(c.args[0], env, depth + 1), evaluate(c.args[1], env, depth + 1))
81
+ if k == "piece":
82
+ # **分段**:先看 n 落在哪一段,再用那一段的式子。
83
+ # 越界用 `outside`——那正是运行期"表覆盖不到、退回第一个候选"的行为,
84
+ # 所以它仍然是一个成立的上界(而不是像旧实现那样悄悄钉一个常数)。
85
+ var, segs = c.value
86
+ n = float(env.get(var, 1.0))
87
+ for lo, hi, sub in segs:
88
+ if lo <= n <= hi:
89
+ return evaluate(sub, env, depth + 1)
90
+ return evaluate(c.args[0], env, depth + 1)
91
+ if k == "log2":
92
+ x = evaluate(c.args[0], env, depth + 1)
93
+ if x <= 0 or math.isinf(x):
94
+ return 0.0
95
+ return math.log2(x)
96
+ return float("inf")
97
+
98
+
99
+ def cost_vars(c: Optional[Cost]) -> List[str]:
100
+ return [] if c is None else c.variables()
101
+
102
+
103
+ # ---------------------------------------------------------------- 结论
104
+
105
+ class Verdict:
106
+ """一次比较的结论。"""
107
+
108
+ def __init__(self, kind: str, note: str = "", slope=None,
109
+ ratio=None, sample_n=None, impl=None, target=None,
110
+ multi=False):
111
+ self.kind = kind # ok / debt / unknown
112
+ self.note = note
113
+ self.slope = slope
114
+ self.ratio = ratio
115
+ self.sample_n = sample_n
116
+ self.impl = impl
117
+ self.target = target
118
+ self.multi = multi
119
+
120
+ def render(self) -> str:
121
+ if self.kind == "ok":
122
+ r = f",比值 ≈ {self.ratio:.2f}" if self.ratio is not None else ""
123
+ m = "(按同规模假设)" if self.multi else ""
124
+ return f"达成:阶够{r}{m}"
125
+ if self.kind == "debt":
126
+ r = f",比值 ≈ {self.ratio:.2f}" if self.ratio is not None else ""
127
+ s = f",斜率 {self.slope:.3f}" if self.slope is not None else ""
128
+ m = "(按同规模假设)" if self.multi else ""
129
+ return f"**超标**:阶不够{r}{s}{m}"
130
+ return f"无法判定:{self.note}"
131
+
132
+ def __repr__(self) -> str:
133
+ return f"Verdict({self.kind})"
134
+
135
+
136
+ # ---------------------------------------------------------------- 趋势
137
+
138
+ def _ratios(impl: Cost, target: Cost, var: str) -> List[float]:
139
+ out = []
140
+ for n in LADDER:
141
+ a = evaluate(impl, {var: n})
142
+ b = evaluate(target, {var: n})
143
+ if b <= 0 or math.isinf(a) or math.isinf(b) or math.isnan(a) or math.isnan(b):
144
+ return []
145
+ out.append(a / b)
146
+ return out
147
+
148
+
149
+ def _slope(ratios: List[float]) -> float:
150
+ """log2(比值) 对 log2(n) 的斜率(LADDER 就是 2^k,所以 k 直接当 x)。"""
151
+ if len(ratios) < 3:
152
+ return 0.0
153
+ xs = list(range(len(ratios)))
154
+ ys = [math.log2(r) if r > 0 else -50.0 for r in ratios]
155
+ n = len(xs)
156
+ mx = sum(xs) / n
157
+ my = sum(ys) / n
158
+ num = sum((x - mx) * (y - my) for x, y in zip(xs, ys))
159
+ den = sum((x - mx) ** 2 for x in xs)
160
+ return num / den if den else 0.0
161
+
162
+
163
+ def compare_exact(impl: Optional[Cost], target: Optional[Cost]) -> Verdict:
164
+ """**分配维度的比较**:常数之间按**数值**比,不按阶比。
165
+
166
+ 为什么不能复用 `compare`:`allocation: { max: 0 }` 是**数个数**,
167
+ 不是"只要常数就算达成"。`compare` 对两个常数一律判 ok(big-O 意义下都对),
168
+ 那会让"说 0 次分配、实际 1 次"被静默放过——**正是 E36 要消灭的那类洞**。
169
+
170
+ 规则:
171
+ · 两个都是常数 → 数值比(impl ≤ target 才算达成);
172
+ · target 是常数、impl 是符号 → **unknown**(推不出上界就不撒谎);
173
+ · 其它(含 target 带符号)→ 退回 `compare`(按阶)。
174
+ """
175
+ if impl is None:
176
+ return Verdict("unknown", note="没有算出分配上界")
177
+ if target is None:
178
+ return Verdict("unknown", note="spec 没有 allocation 的 target")
179
+ if impl.is_top():
180
+ return Verdict("unknown", note="分配上界是 ⊤(循环轮数推不出)")
181
+ if impl.is_const() and target.is_const():
182
+ if impl.value <= target.value:
183
+ return Verdict("ok", ratio=(float(impl.value) / target.value) if target.value else None)
184
+ return Verdict("debt", ratio=(float(impl.value) / target.value) if target.value else None,
185
+ note=f"分配 {impl.value} 次 > target 的 {target.value} 次")
186
+ if target.is_const() and not impl.is_const():
187
+ # **H3(分配维度)**:target 是常数(例如 `max: 0`)而分配上界带符号
188
+ # (例如 `n(xs)×1`)→ 规模一大就超过任何常数,判 debt。
189
+ # 以前判 unknown,于是"承诺 0 次分配、实际每轮分配"能过门禁。
190
+ return Verdict("debt", note=(f"分配上界 {impl.render()} 随规模增长,"
191
+ f"而 target 是常数 {target.value} 次"))
192
+ return compare(impl, target)
193
+
194
+
195
+ def _has_sym(c) -> bool:
196
+ """成本式里有没有**未解释的符号**(`sym`,例如 `k(f)`)。"""
197
+ if c is None:
198
+ return False
199
+ if c.kind == "sym":
200
+ return True
201
+ for a in (getattr(c, "args", None) or []):
202
+ if _has_sym(a):
203
+ return True
204
+ if c.kind == "piece":
205
+ _v = c.value
206
+ if isinstance(_v, tuple) and len(_v) == 2:
207
+ for _lo, _hi, sub in _v[1]:
208
+ if _has_sym(sub):
209
+ return True
210
+ return False
211
+
212
+
213
+ def _sym_of(node):
214
+ """把 `hi` 或 `xs.length()` 翻成一个尺寸符号名。"""
215
+ if node is None:
216
+ return None
217
+ if getattr(node, "kind", "") == "path":
218
+ return node.name
219
+ if getattr(node, "kind", "") in ("method-call", "call") and \
220
+ (getattr(node, "name", "") or "").split(".")[-1] in ("length", "size", "len"):
221
+ recv = node.children[0] if getattr(node, "children", None) else None
222
+ if getattr(recv, "kind", "") == "path":
223
+ return recv.name
224
+ return None
225
+
226
+
227
+ def facts_of_spec(spec) -> dict:
228
+ """从 spec 的 `requires` 里提取 `A <= B` 事实 → {A: {B, …}}。
229
+
230
+ **这就是"声明的假设"的载体**(A1,2026-11-06):
231
+ 只有写进 `requires` 的才作数,**不从用法推断**(`xs[hi]` 不能推出 `hi < len`)。
232
+ """
233
+ out = {}
234
+ if spec is None:
235
+ return out
236
+ body = next((c for c in (getattr(spec, "children", None) or [])
237
+ if getattr(c, "kind", "") == "spec-body"), None)
238
+ for c in (getattr(body, "children", None) or []):
239
+ if getattr(c, "kind", "") != "clause" or getattr(c, "name", "") != "requires":
240
+ continue
241
+ for k in (getattr(c, "children", None) or []):
242
+ if getattr(k, "kind", "") != "binary" or (getattr(k, "value", "") or "") not in ("<", "<="):
243
+ continue
244
+ a, b = (k.children + [None, None])[:2]
245
+ x, y = _sym_of(a), _sym_of(b)
246
+ if x and y and x != y:
247
+ out.setdefault(x, set()).add(y)
248
+ return out
249
+
250
+
251
+ def _rename_cost(c, mapping):
252
+ """把 Cost 里的 `size(小符号)` 换成 `size(大符号)`。"""
253
+ if c is None:
254
+ return c
255
+ if getattr(c, "kind", "") == "size" and c.value in mapping:
256
+ return type(c).size(mapping[c.value])
257
+ args = getattr(c, "args", ())
258
+ if args:
259
+ return type(c)(c.kind, c.value, [_rename_cost(a, mapping) for a in args])
260
+ return c
261
+
262
+
263
+ def compare(impl: Optional[Cost], target: Optional[Cost], facts: Optional[dict] = None) -> Verdict:
264
+ """把 κ_impl 与 κ_target 按 **big-O** 比。"""
265
+ if impl is None:
266
+ return Verdict("unknown", note="没有算出 κ_impl")
267
+ if target is None:
268
+ return Verdict("unknown", note="spec 没有 time 的 target")
269
+ if impl.is_top():
270
+ return Verdict("unknown", note="κ_impl 是 ⊤(有循环上界推不出)")
271
+ if target.is_top():
272
+ return Verdict("ok", note="target 是 ⊤,任何成本都满足")
273
+
274
+ vs = sorted(set(cost_vars(impl)) | set(cost_vars(target)))
275
+ multi = len(vs) > 1
276
+
277
+ # **E23:κ 与 target 用的尺寸量不一致时,比比值没有意义。**
278
+ # 真例子:`calculator` 的 κ 用局部 `tokens`/`operators`、target 用形参 `text`;
279
+ # `topk` 的 κ 用 `xs`/`k`、target 只有 `xs`(因为 target 里写不了两个尺寸相乘)。
280
+ # 旧行为把所有尺寸设成同一个 n 再比 —— 那是在比两件不同的事,
281
+ # 会给出天文数字(6.6e12 / 3.5e13)并**误报债务**。
282
+ # 新行为:**不判债务,只报尺寸量不一致**;比值只作参考信息。
283
+ ci, ct = set(cost_vars(impl)), set(cost_vars(target))
284
+ # κ 不含任何尺寸量 ⇒ 它是**常数**,big-O 意义下任何阶的 target 都满足。
285
+ # (E22 之后 `calculator.evaluate` 就是这种:定容容器把成本压成了常数。)
286
+ if not ci:
287
+ # **G1**:κ 里没有尺寸量**不等于**它是常数——可能是 `k(f)` 这种
288
+ # 未解释的符号(被调函数是谁要看调用点)。实测 `apply(xs, sq)`
289
+ # (sq 是 O(x²))以前走到这里被判「κ 是常数,任何阶都满足」→ 假的 ✓。
290
+ if _has_sym(impl):
291
+ return Verdict("unknown",
292
+ note="κ 含未解释的符号(如 k(f)):被调函数多大要看调用点,"
293
+ "这里判不了阶,不给你一个假的上界")
294
+ a = evaluate(impl, {})
295
+ b = evaluate(target, {}) if ct else None
296
+ return Verdict("ok", ratio=(a / b) if b else None,
297
+ note="κ 是常数(不含尺寸量),任何阶的 target 都满足")
298
+ if ci != ct and facts:
299
+ # **A1(2026-11-06):用声明的 requires 把 κ 的符号弱化到 target 的符号上。**
300
+ # 例:`requires hi <= xs.length()` ⇒ `n(hi)` 可以按 `n(xs)` 计。
301
+ # **只认 facts**(来自 requires),不推断;弱化不动 target。
302
+ _m = {}
303
+ for _s in ci:
304
+ if _s in ct:
305
+ continue
306
+ _cand = (facts.get(_s) or set()) & ct
307
+ if not _cand:
308
+ _m = None
309
+ break
310
+ _m[_s] = sorted(_cand)[0]
311
+ if _m:
312
+ _w = _rename_cost(impl, _m)
313
+ _v = compare(_w, target, None)
314
+ _used = ", ".join(f"{a}≤{b}" for a, b in sorted(_m.items()))
315
+ _n = f"(按 requires 弱化:{_used})"
316
+ return Verdict(_v.kind, ratio=_v.ratio, multi=_v.multi,
317
+ note=(_v.note or "") + _n)
318
+ if ci != ct:
319
+ # **H3(2026-11-02)**:target 写成常数(O(1))而 κ 含尺寸量时,
320
+ # 过去一律判 unknown —— 于是"声明 O(1)、实现 O(n)"**必然判不出**。
321
+ # 但这不是判不出:任何随规模增长的量都 ≰ O(1),判 debt 即可。
322
+ if not ct:
323
+ rs0 = _ratios(impl, target, vs[0])
324
+ return Verdict("debt", multi=multi,
325
+ ratio=(rs0[-1] if rs0 else None),
326
+ note=("target 是常数(O(1)),而 κ 含尺寸量 "
327
+ + "、".join(sorted(ci)) + ":随规模增长必然超阶"))
328
+ rs0 = _ratios(impl, target, vs[0])
329
+ extra = f";若假设所有尺寸同阶,比值约 {rs0[-1]:.2f}(仅供参考,不作判定)" if rs0 else ""
330
+ return Verdict("unknown", multi=multi,
331
+ ratio=(rs0[-1] if rs0 else None),
332
+ note=(f"κ 用的尺寸量 {sorted(ci)} 与 target 用的 {sorted(ct)} 不一致"
333
+ f"(E23){extra}"))
334
+
335
+ if not vs:
336
+ # 双常量:big-O 意义下任何常数都是 O(1),所以一律达成。
337
+ # 比值只作信息展示——"target 定得松"由作者负责,语言不判(用户定的口径)。
338
+ a = evaluate(impl, {})
339
+ b = evaluate(target, {})
340
+ return Verdict("ok", ratio=(a / b) if b else None)
341
+
342
+ # 多尺寸:全部设成同一个 n(简化,结论要标注)
343
+ var = vs[0]
344
+ rs = _ratios(impl, target, var)
345
+ if not rs:
346
+ return Verdict("unknown", note="求值失败(可能有 ⊤ 或除零)", multi=multi)
347
+
348
+ sl = _slope(rs)
349
+ last = rs[-1]
350
+ if sl > SLOPE_TOL:
351
+ return Verdict("debt", slope=sl, ratio=last, multi=multi)
352
+ return Verdict("ok", slope=sl, ratio=last, multi=multi)
353
+
354
+
355
+ def trend(impl: Optional[Cost], target: Optional[Cost]) -> str:
356
+ v = compare(impl, target)
357
+ if v.kind == "unknown":
358
+ return "—"
359
+ if v.slope is None:
360
+ return "—"
361
+ if v.slope > SLOPE_TOL:
362
+ return f"升(每翻倍涨 {100 * (2 ** v.slope - 1):.1f}%)"
363
+ if v.slope < -SLOPE_TOL:
364
+ return "降(target 很松)"
365
+ return "平(比值稳定)"
366
+
367
+
368
+ # ---------------------------------------------------------------- 自检
369
+
370
+ if __name__ == "__main__":
371
+ from .symbolic import Cost as C
372
+
373
+ n = C.size("xs")
374
+ cases = [
375
+ # (标签, impl, target, 期望)
376
+ ("n vs O(n)", n, n, "ok"),
377
+ ("3n+9 vs O(n)", C.add(C.mul(C.num(3), n), C.num(9)), n, "ok"),
378
+ ("n² vs O(n)", C.mul(n, n), n, "debt"),
379
+ ("n vs O(log n)", n, C.log2(n), "debt"),
380
+ ("log2 n vs O(n)", C.log2(n), n, "ok"),
381
+ ("n log n vs O(n log n)",
382
+ C.mul(n, C.log2(n)), C.mul(n, C.log2(n)), "ok"),
383
+ ("n² vs O(n²)", C.mul(n, n), C.mul(n, n), "ok"),
384
+ ("n² vs O(n log n)", C.mul(n, n), C.mul(n, C.log2(n)), "debt"),
385
+ ("常数 100 vs O(1)", C.num(100), C.num(1), "ok"),
386
+ ]
387
+ bad = 0
388
+ for label, a, b, want in cases:
389
+ v = compare(a, b)
390
+ mark = "✓" if v.kind == want else "✗"
391
+ print(f" {mark} {label:26} → {v.kind:6} 期望 {want:6} | {v.render()}")
392
+ bad += 0 if v.kind == want else 1
393
+ print(f"\n{'全部通过' if not bad else f'失败 {bad} 项'}")
394
+ raise SystemExit(1 if bad else 0)