@xiaohuo123212/elench 0.0.0-stage → 0.1.0

package/src/chart.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Elench contributors
+"""chart.py —— 极简折线图（纯 SVG，无依赖）。
+
+**为什么自己写**：`otel.to_svg` 是"承诺 vs 实测"那张固定双线图的渲染器，
+它假设了 `rows` 的字段结构。紧度图要画的是**比值**（y 轴线性、两条线），
+复用会逼着我去迁就它的数据结构；画图这件事本来就只有 80 行。
+
+约定：
+- x 用对数刻度（规模天然是 2 的幂）；
+- y 可选线性（比值）或对数（操作数）；
+- 每个系列一条折线 + 图例，**不叠在一张图上讲两件事**——调用方负责拆图。
+"""
+from __future__ import annotations
+
+import math
+from typing import List, Sequence, Tuple
+
+W, H = 820, 480
+L, R, T, B = 92, 210, 58, 64
+PW, PH = W - L - R, H - T - B
+
+COLORS = ["#1f5fa8", "#c0392b", "#2e7d32", "#8e44ad", "#d35400"]
+
+
+def _esc(s: str) -> str:
+    return (s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;"))
+
+
+def line_chart(series: Sequence[Tuple[str, Sequence[Tuple[float, float]]]],
+               title: str, ylabel: str, log_x: bool = True,
+               log_y: bool = False, hline: float = None,
+               annotate: bool = False, vline: float = None,
+               note: str = None, direct_labels: bool = False) -> str:
+    """series = [(名字, [(x, y), ...]), ...] → SVG 文本。"""
+    pts = [(x, y) for _n, xs in series for x, y in xs if y == y and y > 0]
+    if not pts:
+        # **空面板也要有标题**：否则读者只看到一块白板，分不清"没数据"还是"画砸了"
+        return (f'<svg xmlns="http://www.w3.org/2000/svg" width="{W}" height="{H}" '
+                f'font-family="system-ui,Segoe UI,sans-serif" font-size="13">'
+                f'<rect width="{W}" height="{H}" fill="#ffffff"/>'
+                f'<text x="{L}" y="30" font-size="17" font-weight="600" fill="#1a1a1a">'
+                f'{_esc(title)}</text>'
+                f'<text x="{L}" y="{T + 40}" fill="#777">'
+                f'{_esc(note or "（没有可画的数据）")}</text></svg>')
+    xs_all = [p[0] for p in pts]
+    ys_all = [p[1] for p in pts]
+    x0, x1 = min(xs_all), max(xs_all)
+    if x0 == x1:
+        x0, x1 = x0 / 2, x1 * 2
+    y0, y1 = min(ys_all), max(ys_all)
+    if hline is not None and hline > 0:
+        y0, y1 = min(y0, hline), max(y1, hline)
+    y0 = y0 * 0.9 if y0 > 0 else 0
+    y1 = y1 * 1.1
+
+    def sx(x):
+        if log_x and x > 0:
+            return L + PW * (math.log(x / x0) / math.log(x1 / x0))
+        return L + PW * ((x - x0) / (x1 - x0) if x1 > x0 else 0.5)
+
+    def sy(y):
+        if log_y:
+            a, b = math.log(y0), math.log(y1)
+            return T + PH * (1 - (math.log(y) - a) / (b - a if b > a else 1))
+        return T + PH * (1 - (y - y0) / (y1 - y0 if y1 > y0 else 1))
+
+    out = ['<?xml version="1.0" encoding="UTF-8"?>',
+           f'<svg xmlns="http://www.w3.org/2000/svg" width="{W}" height="{H}" '
+           f'font-family="system-ui,Segoe UI,sans-serif" font-size="13">',
+           f'<rect width="{W}" height="{H}" fill="#ffffff"/>',
+           f'<text x="{L}" y="30" font-size="17" font-weight="600" fill="#1a1a1a">'
+           f'{_esc(title)}</text>',
+           f'<text x="18" y="{T + PH / 2}" fill="#444" transform="rotate(-90 18 '
+           f'{T + PH / 2})" text-anchor="middle">{_esc(ylabel)}</text>',
+           f'<rect x="{L}" y="{T}" width="{PW}" height="{PH}" fill="none" '
+           f'stroke="#bbb"/>']
+
+    # x 轴刻度（点很多时抽稀标签，避免叠字；折线仍然逐点画）
+    _xs_sorted = sorted(set(xs_all))
+    _step = max(1, len(_xs_sorted) // 8) if len(_xs_sorted) > 10 else 1
+    for _i, x in enumerate(_xs_sorted):
+        px = sx(x)
+        out.append(f'<line x1="{px:.1f}" y1="{T}" x2="{px:.1f}" y2="{T + PH}" '
+                   f'stroke="#eee"/>')
+        if _i % _step == 0 or _i == len(_xs_sorted) - 1:
+            out.append(f'<text x="{px:.1f}" y="{T + PH + 20}" text-anchor="middle" '
+                       f'fill="#555">{x:g}</text>')
+    # y 轴刻度：对数轴用 1/10/100/… 这样的整十点；线性轴平均分 4 段
+    if log_y:
+        _ticks = []
+        p = 1.0
+        while p < y1 * 10:
+            if y0 * 0.9 <= p <= y1 * 1.1:
+                _ticks.append(p)
+            p *= 10
+        yticks = _ticks or [y0, y1]
+    else:
+        yticks = [y0 + (y1 - y0) * i / 4 for i in range(5)]
+    for y in yticks:
+        py = sy(y)
+        out.append(f'<line x1="{L}" y1="{py:.1f}" x2="{L + PW}" y2="{py:.1f}" '
+                   f'stroke="#f3f3f3"/>')
+        _lab = f"{y:.0f}" if y >= 1 else f"{y:.2f}"
+        out.append(f'<text x="{L - 10}" y="{py + 4:.1f}" text-anchor="end" '
+                   f'fill="#555">{_lab}</text>')
+    # 竖线（例如"常数项不再主导"的 n0）
+    if vline is not None and vline > 0:
+        _vx = sx(vline)
+        out.append(f'<line x1="{_vx:.1f}" y1="{T}" x2="{_vx:.1f}" y2="{T + PH}" '
+                   f'stroke="#999" stroke-dasharray="6 5"/>')
+        out.append(f'<text x="{_vx + 4:.1f}" y="{T + 14}" fill="#777">n0={vline:.0f}</text>')
+
+    # 参照线（例如比值 = 1）
+    if hline is not None and hline > 0:
+        py = sy(hline)
+        out.append(f'<line x1="{L}" y1="{py:.1f}" x2="{L + PW}" y2="{py:.1f}" '
+                   f'stroke="#999" stroke-dasharray="6 5"/>')
+        out.append(f'<text x="{L + PW - 6}" y="{py - 6:.1f}" text-anchor="end" '
+                   f'fill="#777">{hline:g}</text>')
+
+    _seen = set()
+    _dup = []
+    _ends = []          # (末点 x, 末点 y, 名字, 颜色)
+    for i, (name, data) in enumerate(series):
+        _sig = tuple((round(x, 6), round(y, 6)) for x, y in data if y == y)
+        if _sig in _seen:
+            _dup.append(name)
+            continue
+        _seen.add(_sig)
+        color = COLORS[i % len(COLORS)]
+        d = " ".join(f"{sx(x):.1f},{sy(y):.1f}" for x, y in data if y == y and y > 0)
+        if not d:
+            continue
+        out.append(f'<polyline points="{d}" fill="none" stroke="{color}" '
+                   f'stroke-width="2.4"/>')
+        for x, y in data:
+            if y == y and y > 0:
+                out.append(f'<circle cx="{sx(x):.1f}" cy="{sy(y):.1f}" r="3" '
+                           f'fill="{color}"/>')
+                if annotate:
+                    out.append(f'<text x="{sx(x) + 6:.1f}" y="{sy(y) - 6:.1f}" '
+                               f'font-size="11" fill="{color}">{y:.2f}</text>')
+        _pts_ok = [(x, y) for x, y in data if y == y and y > 0]
+        if _pts_ok:
+            _ends.append((sx(_pts_ok[-1][0]), sy(_pts_ok[-1][1]), name, color))
+        if not direct_labels:
+            ly = T + 18 + i * 24
+            out.append(f'<line x1="{L + PW + 18}" y1="{ly}" x2="{L + PW + 52}" '
+                       f'y2="{ly}" stroke="{color}" stroke-width="2.4"/>')
+            out.append(f'<text x="{L + PW + 60}" y="{ly + 5}" fill="#333">'
+                       f'{_esc(name)}</text>')
+
+    if direct_labels and _ends:
+        # 线尾直接写名字：比在图例里对照更直观（眼睛不用来回跳）
+        _ends.sort(key=lambda z: z[1])
+        _prev = None
+        for _ex, _ey, _nm, _col in _ends:
+            _ly2 = _ey
+            if _prev is not None and _ly2 - _prev < 15:
+                _ly2 = _prev + 15
+            _prev = _ly2
+            out.append(f'<text x="{_ex + 8:.1f}" y="{_ly2 + 4:.1f}" fill="{_col}" '
+                       f'font-size="12">{_esc(_nm)}</text>')
+
+    if _dup:
+        out.append(f'<text x="{L + PW + 60}" y="{T + 18 + len(series) * 24}" '
+                   f'fill="#777">（{_esc("、".join(_dup))}与上线重合）</text>')
+    out.append(f'<text x="{L}" y="{H - 18}" fill="#777">x 轴：输入规模'
+               f'　y 轴：{_esc(ylabel)}</text>')
+    out.append("</svg>")
+    return "\n".join(out)
+
+
+def stack_svgs(svgs, titles=None, columns: int = 1) -> str:
+    """把多张图**垂直堆进同一个文件**（每张仍是独立坐标系）。
+
+    SVG 允许嵌套 `<svg>`，所以不需要把各图的坐标系揉在一起——
+    「一个文件」和「一张图」是两件事：这个函数只合并文件，不合并语义。
+    """
+    if not svgs:
+        return '<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"/>'
+    import re as _re
+    total_h = 0
+    parts = []
+    cols = max(1, int(columns))
+    for svg in svgs:
+        body = _re.sub(r"^<\?xml[^>]*\?>\s*", "", svg)
+        m = _re.search(r'width="(\d+)" height="(\d+)"', body)
+        w, h = (int(m.group(1)), int(m.group(2))) if m else (W, H)
+        body = body.replace('<svg xmlns="http://www.w3.org/2000/svg"', '<svg', 1)
+        parts.append((w, h, body))
+        total_h += h
+    import math as _math
+    _rows = _math.ceil(len(parts) / cols)
+    _wcell = max(p[0] for p in parts)
+    _hcell = max(p[1] for p in parts)
+    _W, _H = _wcell * min(cols, len(parts)), _hcell * _rows
+    out = ['<?xml version="1.0" encoding="UTF-8"?>',
+           f'<svg xmlns="http://www.w3.org/2000/svg" width="{_W}" '
+           f'height="{_H}">',
+           f'<rect width="{_W}" height="{_H}" fill="#fff"/>']
+    for _i, (_w, _h, body) in enumerate(parts):
+        _cx = (_i % cols) * _wcell
+        _cy = (_i // cols) * _hcell
+        out.append(f'<g transform="translate({_cx},{_cy})">{body}</g>')
+    out.append("</svg>")
+    return "\n".join(out)

package/src/check_docs.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Elench contributors
+
+# -*- coding: utf-8 -*-
+"""
+check_docs.py —— 文档语法漂移检查
+
+为什么需要它
+------------
+规格改了语法，代码和样例会立刻报错，**文档不会**——
+文档里的代码示例只是文本，改错了没人知道。这个脚本把"文档里的语言"
+当成也编译一遍：凡是出现旧写法的行，全部列出来。
+
+用法
+----
+  python check_docs.py            # 全仓扫描，只报告
+  python check_docs.py --fail     # 有命中就以非零退出（给 CI / 提交前跑）
+
+豁免规则
+--------
+有些命中是**故意的**：语法变更历史里的对照、本文件的规则说明、标准文件里的反例。
+这些行必须带下面的标记之一才放行，否则一律算漂移：
+
+  〔旧〕  〔反例〕  〔已下线〕  〔历史〕
+"""
+
+import io
+import os
+import re
+import sys
+
+sys.stdout.reconfigure(encoding="utf-8")
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.abspath(os.path.join(HERE, ".."))
+
+EXEMPT_MARKERS = ("〔旧〕", "〔反例〕", "〔已下线〕", "〔历史〕")
+
+# 这些围栏标签里的代码不是本语言，跳过
+OTHER_LANGS = {"rust", "cpp", "c++", "c", "python", "py", "dafny",
+               "js", "javascript", "java", "go", "ts", "typescript", "sh"}
+
+# (名字, 正则, 说明)
+RULES = [
+    ("旧 kernel 声明", re.compile(r"^\s*kernel\s+\w+\s*\("),
+     "v0.66 起没有独立 kernel 声明；候选由 spec 里的 over 声明"),
+    ("旧 pending 子句", re.compile(r"pending\s+\{"),
+     "v0.66 起 pending 是 over 里的裸词标记"),
+    ("choose 缺签名", re.compile(r"choose\s+\w+\s*\{"),
+     "choose MUST 带参数表与返回类型：choose L(params) -> R {"),
+    ("旧 let 绑定", re.compile(r"(?<![\w.`])let\s+[a-z_][a-z0-9_]*\s*[:=]"),
+     "v0.65 起用 val"),
+    ("旧 effects pure", re.compile(r"effects\s+pure\s*;"),
+     "v0.62 起写 effects {};"),
+    ("旧 objective 名", re.compile(r"minimize_(expected_time|p99|peak_mem|code_size)"),
+     "v0.65 起用 time / p99 / mem / size"),
+    ("旧 kernel fn", re.compile(r"kernel\s+fn\s"),
+     "v0.62 起去掉 fn；v0.66 起 kernel 关键字整体下线"),
+]
+
+# 结构类检查：表格头后面必须紧跟分隔行
+TABLE_ROW = re.compile(r"^\s*\|.*\|\s*$")
+TABLE_SEP = re.compile(r"^\s*\|[:\s|-]+\|\s*$")
+
+# 整份文件跳过
+SKIP_FILES = {"_标准-语法变更-v0.66.md"}
+
+
+def scan():
+    hits = []
+    for dirpath, _, files in os.walk(ROOT):
+        # 归档目录是历史快照，本来就该保留旧写法，不参与"语法漂移"检查
+        if any(seg in dirpath for seg in (".git", "_internal", "node_modules",
+                                          ".perf", os.sep + "归档")):
+            continue
+        for f in files:
+            if not f.endswith(".md") or f in SKIP_FILES:
+                continue
+            p = os.path.join(dirpath, f)
+            try:
+                text = io.open(p, encoding="utf-8").read()
+            except UnicodeDecodeError:
+                continue
+            rel = os.path.relpath(p, ROOT)
+            fence_tag = None
+            for no, line in enumerate(text.split("\n"), 1):
+                s = line.strip()
+                if s.startswith("```"):
+                    if fence_tag is None:
+                        lang = s[3:].strip().lower()
+                        fence_tag = "" if lang in OTHER_LANGS else None
+                        if lang and lang not in OTHER_LANGS:
+                            fence_tag = None
+                        continue
+                    else:
+                        fence_tag = None
+                        continue
+                if fence_tag == "":
+                    continue          # 外语代码块，不按本语言规则查
+                if any(m in line for m in EXEMPT_MARKERS):
+                    continue
+                for name, rx, why in RULES:
+                    if rx.search(line):
+                        hits.append((rel, no, name, line.strip(), why))
+
+            # 结构：表格头必须紧跟分隔行，否则表格会渲染错乱
+            lines = text.split("\n")
+            fence = False
+            for no in range(len(lines) - 1):
+                cur, nxt = lines[no], lines[no + 1]
+                if cur.strip().startswith("```"):
+                    fence = not fence
+                    continue
+                if fence:
+                    continue
+                if not TABLE_ROW.match(cur) or TABLE_SEP.match(cur):
+                    continue
+                # 只有"表头"才要求分隔行：表头 = 上一行不是表格行
+                if no > 0 and TABLE_ROW.match(lines[no - 1]):
+                    continue
+                if TABLE_SEP.match(nxt):
+                    continue
+                if any(m in cur for m in EXEMPT_MARKERS):
+                    continue
+                hits.append((rel, no + 1, "表格头缺分隔行",
+                             cur.strip()[:80],
+                             "表格头后面必须紧跟 |---| 分隔行（否则表格会散架）"))
+    return hits
+
+
+def main(argv):
+    hits = scan()
+    if not hits:
+        print("✓ 文档没有语法漂移")
+        return 0
+
+    by_file = {}
+    for rel, no, name, line, why in hits:
+        by_file.setdefault(rel, []).append((no, name, line, why))
+
+    for rel in sorted(by_file):
+        print(f"\n{rel}  ({len(by_file[rel])} 处)")
+        for no, name, line, why in by_file[rel][:20]:
+            shown = line if len(line) <= 90 else line[:87] + "..."
+            print(f"  行{no:<5} [{name}] {shown}")
+        print(f"    → {by_file[rel][0][3]}")
+
+    total = len(hits)
+    print(f"\n共 {total} 处，分布在 {len(by_file)} 个文件")
+    print("若某处是故意的对照/反例，在该行加标记：" + " ".join(EXEMPT_MARKERS))
+    return 1 if ("--fail" in argv and total) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))