Skip to content

meiluosi/rewrite-fidelity-skill

rewrite-fidelity

Verified

Use after any rewrite, simplification, or plain-language pass — English or Chinese — to check that the new text still says what the original said: same numbers, same code and identifiers, same conditions and exceptions, same requirement strength (MUST/SHOULD/MAY, 必须/建议/可以), same hedges (may have / 可能), same negations and scope, same threshold direction (at least vs at most, 以上 vs 以下), same comparison direction (A beats B vs B beats A), no stronger claim (suggests vs proves, 可能 vs 一定). Pairs with asd-ste100, zh-disambiguate, jianming-zhongwen and any other rewrite skill. Triggers: check the rewrite, did the rewrite change the meaning, verify nothing was lost, fidelity check, 改写有没有改意思, 核对改写, 保真检查, 对比原文和改写稿. Not a style checker: it never judges whether the rewrite reads better.

scripts/fidelity.py

View on GitHub
#!/usr/bin/env python3
"""Check that a rewrite kept the meaning-bearing parts of the original.

Style linters (ste-lint.py, zh-lint.py) check the shape of ONE text. This
script compares TWO texts: an original and its rewrite. It extracts the parts
that carry meaning and that a simplifying rewrite tends to lose or change:

    literals     code spans, code blocks, URLs, paths, flags, identifiers,
                 error codes, versions          -> must survive verbatim
    numbers      Arabic, Chinese and English number words, normalized
                 ("三" == "3" == "three")       -> same multiset
    modality     requirement / prohibition / recommendation / permission /
                 ability / possibility / approximation, per language
    conditions   if / unless / until / 如果 / 除非 / 否则 / 仅当 ...
    negation     not / never / 不 / 没有 / 未 ...
    scope        all / only / at least / 所有 / 仅 / 至少 ...
    quoted       "..." “...” 「...」 (UI labels, error text)
    compare.op   each comparison operator counted separately (< > <= >= ≤ ≥); a flipped
                 operator keeps the total count but is still an error
    compare.dir  who beats whom: (winner, loser) pairs from "A is better than B", "A 比 B 更好", "A 优于 B", "A 不如 B", "A > B".
                 A pair that comes back reversed is an error; a lost or new comparison is a warning
    strength     claim-strengthening words (proved, always, definitely, 证明, 一定, 完全 ...):
                 more of them in the rewrite is an error, fewer is a warning

It reports what disappeared or appeared. It cannot prove that meaning is
preserved: a count that matches can still hide a flipped condition. Use it as
the mechanical first pass, then do the claim-by-claim check in SKILL.md.

Usage:
    fidelity.py ORIGINAL REWRITE            # files; "-" reads stdin
    fidelity.py --json ORIGINAL REWRITE
    fidelity.py --strict ORIGINAL REWRITE   # warnings also fail the run
    fidelity.py --selftest

The last line of the text output is `RESULT: FAIL | PASS WITH WARNINGS | PASS`
(also `result` in --json). A pass means "nothing mechanical changed", not "same meaning".

Exit 0 when no error-level finding, 1 otherwise, 2 on usage error.
Stdlib only, Python 3.8+.
"""
import argparse
import json
import re
import sys
from collections import Counter

# ---------------------------------------------------------------------------
# Literal extraction. Each literal is removed from the text after extraction
# so that later passes (numbers, modals) do not count it a second time.
# ---------------------------------------------------------------------------

FENCE_BLOCK = re.compile(r"^[ \t]*(```|~~~)[^\n]*\n(.*?)^[ \t]*\1[ \t]*$", re.M | re.S)
INLINE_CODE = re.compile(r"`([^`\n]+)`")
URL = re.compile(r"\bhttps?://[^\s)\]>\"',。、;)」]+")
PATH = re.compile(
    r"(?<![\w/])(?:~|\.{1,2})?/(?:[\w.\-]+/)*[\w.\-]*[\w\-]"     # /etc/x, ./a/b, ~/x
    r"|(?<![\w/.])[\w\-]+(?:/[\w.\-]*[\w\-])+"                     # src/app/main.py
)
FILENAME = re.compile(
    r"(?<![\w.])[\w\-]+\.(?:py|js|mjs|ts|tsx|jsx|json|ya?ml|md|toml|sh|go|rs|java|"
    r"kt|rb|php|c|h|cpp|txt|log|csv|conf|ini|env|lock|sql|html|css|xml)\b"
)
FLAG = re.compile(r"(?<![\w\-])--?[A-Za-z][\w\-]*(?:=\S+)?")
ERROR_CODE = re.compile(r"\b(?:[A-Z]{1,6}-?\d{2,}|0x[0-9A-Fa-f]{2,})\b")
VERSION = re.compile(r"\bv?\d+(?:\.\d+){2,}(?:[-+][\w.]+)?\b")
CONST = re.compile(r"\b[A-Z][A-Z0-9]*_[A-Z0-9_]+\b")              # ENV_VAR, MAX_RETRY
SNAKE = re.compile(r"\b[a-z][a-z0-9]*_[a-z0-9_]+\b")
CAMEL = re.compile(r"\b[a-z]+[A-Z][A-Za-z0-9]*\b")
CALL = re.compile(r"\b[A-Za-z_][\w.]*\(\)")
QUOTED = re.compile(r"\"([^\"\n]{1,80})\"|“([^”\n]{1,80})”|「([^」\n]{1,80})」|『([^』\n]{1,80})』")

# 中文文本里数字、文件名、参数紧贴汉字是常态(「不超过2048个字节」「使用--force」)。
# Python 默认把汉字当作 \w,会让这些字面量被漏掉,加空格的改写稿又被当成「新增」。
# 所以这些模式的 \w、\b 只认 ASCII。
for _name in ("URL", "PATH", "FILENAME", "FLAG", "ERROR_CODE", "VERSION", "CONST", "SNAKE", "CAMEL", "CALL"):
    globals()[_name] = re.compile(globals()[_name].pattern, re.ASCII)

# (kind, pattern, severity-if-missing). Order matters: wider patterns first.
LITERAL_KINDS = [
    ("code-block", FENCE_BLOCK, "error"),
    ("inline-code", INLINE_CODE, "error"),
    ("url", URL, "error"),
    ("version", VERSION, "error"),
    ("path", PATH, "error"),
    ("filename", FILENAME, "error"),
    ("flag", FLAG, "error"),
    ("call", CALL, "error"),
    ("error-code", ERROR_CODE, "error"),
    ("constant", CONST, "error"),
    ("identifier", SNAKE, "error"),
    ("identifier", CAMEL, "error"),
    ("quoted", QUOTED, "warn"),
]


def _norm_ws(s):
    return re.sub(r"\s+", " ", s).strip()


def extract_literals(text):
    """Return (Counter of (kind, literal), text with literals blanked out)."""
    found = Counter()
    for kind, pattern, _sev in LITERAL_KINDS:
        def take(m, kind=kind):
            if kind == "code-block":
                value = _norm_ws(m.group(2))
            elif kind == "inline-code":
                value = m.group(1).strip()
            elif kind == "quoted":
                value = next(g for g in m.groups() if g is not None).strip()
            else:
                value = m.group(0)
            if kind == "quoted":
                # Quoted prose stays in the text: its words still carry modals,
                # numbers and negation that later passes must count.
                found[(kind, value)] += 1
                return m.group(0)
            if value:
                found[(kind, value)] += 1
            return " ⟨…⟩ "  # visible placeholder; no later pass matches it
        text = pattern.sub(take, text)
    return found, text


# ---------------------------------------------------------------------------
# Numbers
# ---------------------------------------------------------------------------

CN_DIGITS = {"零": 0, "〇": 0, "一": 1, "二": 2, "两": 2, "三": 3, "四": 4,
             "五": 5, "六": 6, "七": 7, "八": 8, "九": 9}
CN_UNITS = {"十": 10, "百": 100, "千": 1000}
CN_BIG = {"万": 10_000, "亿": 100_000_000}


def cn2num(s):
    """Convert a Chinese numeral string (一百二十三, 两千, 十五, 三万) to int."""
    total, section, number = 0, 0, 0
    for ch in s:
        if ch in CN_DIGITS:
            number = CN_DIGITS[ch]
        elif ch in CN_UNITS:
            section += (number or 1) * CN_UNITS[ch]
            number = 0
        elif ch in CN_BIG:
            total += (section + number) * CN_BIG[ch]
            section, number = 0, 0
        else:
            return None
    return total + section + number


# Measure words after which a Chinese numeral is a real quantity.
CN_QTY_UNIT = (r"(?:毫秒|秒钟?|分钟|小时|天|日|周|星期|个月|月|年|次|倍|遍|轮|位|台|条|项|"
               r"行|列|字节?|个字符|字符|层|级|步|种|个|份|张|页|块|核|线程|进程|副本|实例|节点|"
               r"MB|GB|KB|TB|ms|s|%|%)")
# A bare 一/两 is often an article ("一个文件"), so it only counts before
# measure words that make it a quantity.
CN_SINGLE_UNIT = r"(?:毫秒|秒钟?|分钟|小时|天|日|周|星期|个月|月|年|次|倍|遍|轮|副本|实例|节点|MB|GB|KB|TB|%|%)"
CN_NUM = re.compile(
    r"(?<![第周星期礼拜初])(?P<n>[零〇一二两三四五六七八九十百千万亿]{2,}|[三四五六七八九十])(?=\s*" + CN_QTY_UNIT + ")"
    r"|(?<![第周星期礼拜初统唯])(?P<n1>[一两])(?=\s*" + CN_SINGLE_UNIT + ")"
)
CN_PERCENT = re.compile(r"百分之(?P<n>[零〇一二两三四五六七八九十百千]+|\d+(?:\.\d+)?)")

EN_WORDS = {
    "two": 2, "three": 3, "four": 4, "five": 5, "six": 6, "seven": 7,
    "eight": 8, "nine": 9, "ten": 10, "eleven": 11, "twelve": 12,
    "thirteen": 13, "fourteen": 14, "fifteen": 15, "sixteen": 16,
    "seventeen": 17, "eighteen": 18, "nineteen": 19, "twenty": 20,
    "thirty": 30, "forty": 40, "fifty": 50, "sixty": 60, "seventy": 70,
    "eighty": 80, "ninety": 90, "hundred": 100, "thousand": 1000,
    "twice": 2, "thrice": 3,
}
EN_NUM = re.compile(r"\b(" + "|".join(EN_WORDS) + r")\b", re.I)
EN_ONE = re.compile(
    r"\b(one|once)\b(?=\s+(?:second|minute|hour|day|week|month|year|time|retry|"
    r"attempt|byte|request|more|per)|(?:\s*[.,;]|\s*$))", re.I)
EN_ONE_LOOSE = re.compile(r"\bonce\b", re.I)

LIST_MARKER = re.compile(r"^[ \t]*(?:#{1,6}[ \t]+)?(?:\d+[.)]|[-*+])[ \t]+", re.M)   # list items and numbered headings ("## 2. Setup")
ORDINAL = re.compile(r"(?:第\s*\d+\s*[步条项章节个次]?|\b[Ss]tep\s+\d+\b|\b\d+(?:st|nd|rd|th)\b)")
ARABIC = re.compile(r"(?<![\w.])\d+(?:\.\d+)?[eE][+-]?\d+(?![\w])|(?<![\w.])\d{1,3}(?:,\d{3})+(?:\.\d+)?(?![\w])|(?<![\w.])\d+(?:\.\d+)?", re.ASCII)


def _fmt_num(value):
    if isinstance(value, float) and value.is_integer():
        value = int(value)
    return str(value)


def extract_numbers(text):
    """Return Counter of normalized numeric values plus a value->snippet map."""
    text = LIST_MARKER.sub(" ", text)
    text = ORDINAL.sub(" ", text)
    found, where = Counter(), {}

    def add(value, m, src):
        key = _fmt_num(value)
        found[key] += 1
        where.setdefault(key, _context(src, m.start(), m.end()))

    def sub_percent(m):
        raw = m.group("n")
        val = float(raw) if raw[0].isdigit() else cn2num(raw)
        if val is not None:
            add(val, m, text)
        return " \u2063 "
    work = CN_PERCENT.sub(sub_percent, text)

    def sub_cn(m):
        raw = m.group("n") or m.group("n1")
        val = cn2num(raw)
        if val is not None:
            add(val, m, work)
        return " \u2063 "
    work = CN_NUM.sub(sub_cn, work)

    def sub_en(m):
        add(EN_WORDS[m.group(1).lower()], m, work)
        return " "
    work = EN_NUM.sub(sub_en, work)

    def sub_one(m):
        add(1, m, work)
        return " "
    work = EN_ONE.sub(sub_one, work)

    for m in ARABIC.finditer(work):
        add(float(m.group(0).replace(",", "")), m, work)
    return found, where


# ---------------------------------------------------------------------------
# Lexical categories: modality, conditions, negation, scope.
# Patterns are matched longest-first and blanked as they match, so that
# "must not" is not also counted as "must", and 不建议 not also as 建议.
# ---------------------------------------------------------------------------

CJK = r"一-鿿"

CATEGORIES = [
    # --- modality -----------------------------------------------------------
    # 「最好不要」和「不建议」不放进同一个桶:一致率评测里读者的读法不同。
    # 前者常被读成「默认不做」,后者常被读成「由读者决定」。互相替换只给 warning。
    ("modal.not-recommend.soft", "warn", [
        r"\bhad\s+better\s+not\b", r"最好不要", r"最好别", r"尽量不要", r"尽量别", r"尽量避免",
    ]),
    ("modal.not-recommend", "error", [
        r"\bshould\s+not\b", r"\bshouldn't\b", r"\bnot\s+recommended\b",
        r"不建议", r"不推荐", r"不宜",
    ]),
    ("modal.prohibit", "error", [
        r"(?:^|(?<=[.!?:]\s)|(?<=\n))(?:Do\s+not|Don't|Never)\b",
        r"(?<![得])不要(?![求紧])", r"千万别", r"(?<![区类级特分识个告])别(?=[再把在用去让做动删改碰])",
        r"\b(?:must|shall)\s+not\b", r"\b(?:mustn't|shan't)\b", r"\bis\s+not\s+allowed\b",
        r"\bmay\s+not\b", r"\bis\s+(?:forbidden|prohibited)\b",
        r"不得", r"禁止", r"严禁", r"不准", r"不允许", r"不可以", r"切勿", r"请勿", r"不应该?", r"不应当",
        r"不能够?", r"无法", r"不可(?!能|用|读|见|靠|逆)",
    ]),
    ("modal.not-required", "error", [
        r"\b(?:need|needs)\s+not\b", r"\bdo(?:es)?\s+not\s+(?:need|have)\s+to\b",
        r"\bnot\s+required\b", r"不必", r"无需", r"无须", r"不需要", r"不用",
    ]),
    ("modal.possibility", "error", [
        r"\b(?:may|might|could|must)\s+have\b", r"\bmight\b", r"\bcould\b",
        r"\b(?:possibly|probably|likely|unlikely|perhaps|maybe)\b",
        r"\b(?:appears?|seems?)\s+to\b",
        r"不可能", r"可能", r"也许", r"或许", r"大概", r"似乎", r"恐怕", r"估计", r"未必", r"不一定",
    ]),
    ("modal.approx", "error", [
        r"\b(?:about|approximately|around|roughly|nearly|almost)\b(?=\s*[~\d])",
        r"~\s*(?=\d)", r"大约", r"大概(?=\s*\d)", r"约(?=\s*[\d一二两三四五六七八九十百千])",
        r"左右", r"上下(?=[,。,.\s]|$)", r"近(?=\s*\d)",
    ]),
    ("modal.require", "error", [
        r"\bmust\b", r"\bshall\b", r"\b(?:is|are)\s+required\s+to\b", r"\bhave\s+to\b",
        r"\bhas\s+to\b", r"\bneeds?\s+to\b",
        r"必须", r"务必", r"必需", r"须(?!知)", r"应当", r"应该", r"一定要", r"一定得", r"需要(?=[" + CJK + r"])",
        r"(?<![响对适相反供回效答呼感照理])应(?![用答对该当急变付聘届征邀试])",
    ]),
    ("modal.recommend", "warn", [
        r"\bshould\b", r"\b(?:is\s+)?recommended\b", r"\bought\s+to\b",
        r"建议", r"推荐", r"最好", r"尽量", r"(?<![便适合])宜(?![昌宾家人])",
    ]),
    ("modal.may", "warn", [r"\bmay\b"]),               # permission or possibility: ambiguous in English
    ("modal.permit", "warn", [
        r"\b(?:is|are)\s+allowed\s+to\b", r"\bcan\b", r"\boptional(?:ly)?\b",
        r"可以", r"允许", r"可选", r"(?<![不])可(?=[以选])",
    ]),
    ("modal.ability", "warn", [
        r"能够", r"(?<![可功性智技职本潜效体动热电节核才万只未])能(?![力量源耗效手])",
    ]),
    # --- conditions and exceptions ------------------------------------------
    ("condition", "error", [
        r"\bonly\s+if\b", r"\bif\b", r"\bunless\b", r"\bwhen(?:ever)?\b", r"\buntil\b",
        r"\botherwise\b", r"\bexcept\b", r"\bprovided\s+that\b", r"\bin\s+case\b",
        r"\bbefore\b", r"\bafter\b",
        r"仅当", r"只有当?", r"如果", r"假如", r"假设", r"若(?!干)", r"一旦", r"只要", r"除非", r"否则",
        r"除了", r"(?<=[" + CJK + r"])(?:以外|之外)", r"直到", r"前提是", r"条件是",
        r"之前", r"之后", r"以前", r"以后",
        # 「当 X 时,」和「X 时,」都计一次,所以只数「时,」,不数「当」。
        r"(?<=[" + CJK + r"\w%%))])\s*时(?=[,,])",
    ]),
    # --- negation (counted after the modal negations above are consumed) ----
    ("negation", "warn", [
        r"\bnot\b", r"\bn't\b", r"\bnever\b", r"\bno\b", r"\bnone\b", r"\bnothing\b",
        r"\bneither\b", r"\bnor\b", r"\bwithout\b", r"\bcannot\b",
        r"没有", r"没(?![收])", r"未能", r"未(?!来|知)", r"(?<![并])非(?!常|法|凡)", r"别(?=[" + CJK + r"])(?<!区别)(?<!类别)(?<!级别)(?<!特别)(?<!分别)(?<!识别)(?<!个别)(?<!告别)",
        r"勿", r"无(?!论)",
        r"不(?!同|仅|断|久|过|少|错|管|论|如|然|止|但|光|只|外乎)",
    ]),
    # --- scope and quantifiers ----------------------------------------------
    ("scope.limit", "error", [
        r"\bat\s+(?:least|most)\b", r"\bno\s+(?:more|less|fewer)\s+than\b", r"\bup\s+to\b(?=\s*\d)",
        r"\b(?:more|less|fewer)\s+than\b", r"\bonly\b",
        r"至少", r"至多", r"最多", r"最少", r"不超过", r"不少于", r"不低于", r"不高于",
        r"(?<=[\d%%个次天秒时岁元位人台倍行项条BbKkMmGgTt])\s*(?:以上|以下|以内|之内)", r"超过", r"不满", r"不足", r"低于", r"高于",
        r"仅", r"(?<![不])只(?!要|有当)", r"[≥≤]",
        r">=|<=", r"(?<=[\w))%])[ \t]*(?<![-=<>])[<>](?![-=<>])(?=[ \t]*[\w((.\-])",   # < > only between operands
    ]),
    ("scope", "warn", [
        r"\b(?:all|every|each|any|always|some|both|either)\b",
        r"所有", r"全部", r"每(?=[个次一条项位])", r"任何", r"任一", r"总是", r"始终", r"从不", r"永远",
        r"部分", r"某些", r"一些",
    ]),
]

GROWTH_IS_ERROR = {"modal.require", "modal.prohibit"}

# Threshold directions. scope.limit counts bounds together, so "p < 0.05" -> "p > 0.05" (same total) passed silently.
# Symbols and words share four buckets (>= <= > <), so a rewrite that turns "90% 以上" into "≥ 90%" changes nothing,
# while "不超过 200 元" -> "超过 200 元", "at least 3" -> "at most 3" and "p < 0.05" -> "p > 0.05" each move a count between buckets.
# Longer phrases come first and are blanked as they match ("不超过" before "超过", "大于等于" before "大于").
_THRESHOLDS = [
    ("≥", re.compile(r"大于等于|不小于|不低于|不少于|至少|及以上|或以上|或更高|或更多|或更大|以上|\bat\s+least\b|\bno\s+(?:less|fewer)\s+than\b|\b(?:greater|more)\s+than\s+or\s+equal\s+to\b|>=|≥", re.I)),
    ("≤", re.compile(r"小于等于|不大于|不高于|不多于|不超过|至多|最多|及以下|或以下|或更低|或更少|或更小|以下|以内|之内|\bat\s+most\b|\bno\s+more\s+than\b|\bup\s+to\b(?=\s*\d)|<=|≤", re.I)),
    (">", re.compile(r"超过|大于|高于|多于|\b(?:more|greater|higher|larger)\s+than\b|\bexceed(?:s|ed)?\b|(?<=[\w))%])[ \t]*(?<![-=<>])>(?![-=<>])(?=[ \t]*[\w((.\-])", re.I)),
    ("<", re.compile(r"小于|低于|少于|不足|不满(?!足|意)|\b(?:less|fewer|lower|smaller)\s+than\b|(?<=[\w))%])[ \t]*(?<![-=<>])<(?![-=<>])(?=[ \t]*[\w((.\-])", re.I)),
]
_PLACEHOLDER = re.compile(r"<[^<>\s]{1,30}>")      # <域名>, <prefix>: placeholders and tags, not comparisons


def threshold_counts(text):
    text = _PLACEHOLDER.sub(" ", text)
    c = Counter()
    for sym, pat in _THRESHOLDS:
        text, n = pat.subn(lambda m: " " * len(m.group(0)), text)
        if n:
            c[sym] += n
    return c

# Words that make a claim stronger than a hedge or a plain statement. A rewrite that adds them has changed the claim.
# Unambiguous claim-strengtheners: more of them in the rewrite is an error.
STRENGTH = re.compile(
    r"\b(?:proved?|proves|proven|proof|demonstrates?|definitely|certainly|undoubtedly|guarantees?|guaranteed)\b"
    r"|证明|证实|必然|毫无疑问|显然|确凿",
    re.I)
# Words that often strengthen a claim but have harmless readings (不一定 is a hedge, 绝对值 is a term, 列完全部 is 列完 + 全部).
# More of them is a warning, never an error.
STRENGTH_SOFT = re.compile(
    r"\b(?:clearly|obviously|always|entirely|completely|fully)\b"
    r"|(?<!不)一定(?!程度|的|范围|数量|条件|要|得)|完全(?!部|体)|绝对(?!值)|始终|总是",
    re.I)


def operator_counts(text):
    c = Counter()
    for m in OPERATOR.finditer(text):
        c[_OP_NORM.get(m.group(1), m.group(1))] += 1
    return c


_COMPILED = [
    (name, sev, re.compile("|".join(f"(?:{p})" for p in pats), re.I))
    for name, sev, pats in CATEGORIES
]


def extract_categories(text):
    """Return {category: (count, [snippets])}."""
    out = {}
    work = _PLACEHOLDER.sub(lambda m: " " * len(m.group(0)), text)   # <域名>, <prefix>: placeholders, not operators
    for name, _sev, pattern in _COMPILED:
        hits = []

        def take(m):
            hits.append(_context(text, m.start(), m.end()))  # offsets match: blanks keep length
            return "\u2063" * len(m.group(0))  # keep offsets stable for context
        work = pattern.sub(take, work)
        out[name] = (len(hits), hits)
    return out


def _context(text, start, end, width=14):
    left = text[max(0, start - width):start]
    right = text[end:end + width]
    snippet = (left + "[" + text[start:end] + "]" + right)
    snippet = snippet.replace("\u2063", "").replace("\n", " ")
    return re.sub(r"\s+", " ", snippet).strip()


# ---------------------------------------------------------------------------
# Comparison
# ---------------------------------------------------------------------------

MESSAGES = {
    "modal.prohibit": "Prohibition count changed. A lost 'must not'/'不得' turns a ban into silence.",
    "modal.not-recommend": "'should not'/'不建议' count changed. If it replaced 最好不要/尽量不要, the reading changed (see the .soft finding).",
    "modal.not-recommend.soft": "'最好不要'/'尽量不要' count changed. Readers take these as 'default: do not', but '不建议'/'should not' as 'left to the reader'. If one replaced the other, state the default action.",
    "modal.not-required": "'need not'/'不必' count changed.",
    "modal.possibility": "Hedge count changed. A dropped 'may have'/'可能' promotes a guess to a fact.",
    "modal.approx": "Approximation marker changed. '约 5 秒' -> '5 秒' claims precision the source did not have.",
    "modal.require": "Requirement count changed. Check for MUST<->SHOULD drift (必须/应 vs 建议).",
    "modal.recommend": "Recommendation count changed. Check it was not promoted to a requirement or dropped.",
    "modal.may": "'may' count changed. English 'may' is permission OR possibility. Check which one moved.",
    "modal.permit": "Permission count changed.",
    "modal.ability": "Ability (能/无法) count changed.",
    "condition": "Condition/exception/sequence markers changed. A dropped 'unless'/'除非' widens the instruction.",
    "negation": "Negation count changed. Re-read every negated clause: polarity flips are the costliest error.",
    "scope.limit": "Bound or limit changed (at most/only/至少/不超过/以上). A lost bound turns a limit into an exact value or removes it.",
    "scope": "Quantifier changed (all/every/some/所有/每个/部分).",
}

# ---------------------------------------------------------------------------
# Comparison direction: "A is better than B" -> "B is better than A" keeps every count, operator and number.
# Each comparison is reduced to a (winner, loser) pair of operand strings and the pairs are compared.
# Operand extraction is heuristic (a short span next to the marker), so matching is fuzzy; the check flags, a person decides.
# ---------------------------------------------------------------------------

_UP_EN = r"(?:better|greater|higher|larger|bigger|faster|stronger|longer|more\s+\w+|superior|safer|cheaper)"
_DOWN_EN = r"(?:worse|lower|smaller|slower|weaker|shorter|fewer|less\s+\w+|inferior)"
_EN_THAN = re.compile(r"(?P<a>[^.;:\n]{1,80}?)\s+(?:(?:is|are|was|were|be|being)\s+)?(?:much\s+|far\s+|slightly\s+|significantly\s+|clearly\s+)?(?P<rel>" + _UP_EN + "|" + _DOWN_EN + r")\s+than\s+(?P<b>[^.;:,\n]{1,60})", re.I)
_EN_VERB = re.compile(r"(?P<a>[^.;:\n]{1,60}?)\s+(?P<rel>outperforms?|beats?|surpasses|outperformed|beat|surpassed|underperforms?|trails?|lags?|underperformed|trailed|lagged)(?:\s+behind)?\s+(?P<b>[^.;:,\n]{1,60})", re.I)
_ZH_BI = re.compile(r"(?P<a>[^,。;;,.\n]{1,24}?)(?<![对相])比(?![如较例喻赛率])(?P<b>[^,。;;,.\n]{1,20}?)(?:更|还|要|稍|略|明显|远|都|也)?(?P<rel>好|强|高|大|快|多|长|优|胜|低|差|弱|小|慢|少|短|劣)")
_ZH_REL = re.compile(r"(?P<a>[^,。;;,.\n]{1,24}?)(?P<rel>优于|好于|强于|快于|胜过|优先于|劣于|差于|弱于|慢于|不如|逊于|落后于)(?P<b>[^,。;;,.\n]{1,20})")
_SYM = re.compile(r"(?P<a>[^\s<>=≤≥,。;;,]{1,24})\s*(?P<rel>[<>≤≥]|<=|>=)\s*(?P<b>[^\s<>=≤≥,。;;,]{1,24})")
_UP_WORDS = ("好","强","高","大","快","多","长","优","胜","better","greater","higher","larger","bigger","faster","stronger","longer","more","superior","safer","cheaper","outperform","beat","surpass","优于","好于","强于","快于","胜过","优先于",">","≥")
_STOP = re.compile(r"\b(?:the|a|an|of|in|on|with|that|this|our|its|their)\b|[的这该其而且但是了]")   # lowercase only: "A" / "B" are usually labels, not articles


def _op_norm(s):
    raw = s.strip()
    m = re.search(r"(?:^|[\s((])([A-Za-z0-9])[\s))]*$", raw)      # a trailing label such as "method A" / "方案 2"
    label = m.group(1).lower() if m else ""
    s = _STOP.sub("", s)
    return re.sub(r"[^\w一-鿿]", "", s.lower()) + (("#" + label) if label else "")


def _goes_up(rel):
    r = rel.lower().strip()
    return any(r.startswith(w) for w in _UP_WORDS)


def extract_comparisons(text):
    """Return a list of (winner, loser, snippet). Operands are short normalized strings."""
    out, seen = [], set()
    def add(a, b, up, snip):
        if re.match(r"\s*[-+]?\d", b):                  # numeric right side: a threshold, handled by compare.op
            return
        a, b = _op_norm(a)[-14:], _op_norm(b)[:14]
        if len(a) < 1 or len(b) < 1 or a == b:
            return
        w, l = (a, b) if up else (b, a)
        key = (w, l, snip[:20])
        if key not in seen:
            seen.add(key); out.append((w, l, snip))
    for pat in (_EN_THAN, _EN_VERB, _ZH_BI, _ZH_REL, _SYM):
        for m in pat.finditer(text):
            rel = m.group("rel")
            if pat is _ZH_REL:
                up = rel not in ("劣于", "差于", "弱于", "慢于", "不如", "逊于", "落后于")
            elif pat is _EN_VERB:
                up = rel.lower().rstrip("s") not in ("underperform", "trail", "lag", "underperformed", "trailed", "lagged")
            elif pat is _SYM:
                up = rel in (">", "≥", ">=")
            elif pat is _ZH_BI:
                up = rel in ("好", "强", "高", "大", "快", "多", "长", "优", "胜")
            else:
                up = _goes_up(rel)
            add(m.group("a"), m.group("b"), up, m.group(0).strip())
    return out


def _same(x, y):
    from difflib import SequenceMatcher
    x, lx = (x.split("#") + [""])[:2]
    y, ly = (y.split("#") + [""])[:2]
    if lx and ly and lx != ly:
        return False                                   # "method A" vs "method B": different operands
    if x == y:
        return True
    short, long_ = (x, y) if len(x) <= len(y) else (y, x)
    cjk = bool(re.search(r"[一-鿿]", short))
    if len(short) >= (2 if cjk else 4) and short in long_:
        return True
    if len(short) >= 4:
        m = SequenceMatcher(None, short, long_).find_longest_match(0, len(short), 0, len(long_))
        return m.size / len(short) >= 0.7              # long shared run, so light rewording still matches
    return False


def compare_direction(orig_text, new_text):
    co, cn = extract_comparisons(orig_text), extract_comparisons(new_text)
    findings = []
    matched_new = set()
    for w, l, snip in co:
        same = rev = False
        for j, (w2, l2, s2) in enumerate(cn):
            if _same(w, w2) and _same(l, l2):
                same = True; matched_new.add(j)
            elif _same(w, l2) and _same(l, w2):
                rev = True; matched_new.add(j)
        if rev and not same:
            findings.append({"severity": "error", "check": "compare.dir", "change": "reversed", "original": 1, "rewrite": 1,
                             "items": ["original: " + snip, "rewrite:  " + next(s2 for w2, l2, s2 in cn if _same(w, l2) and _same(l, w2))],
                             "message": "Who beats whom is reversed. Counts, operators and numbers can all match while the claim flips."})
        elif not same:
            findings.append({"severity": "warn", "check": "compare.dir", "change": "lost", "original": 1, "rewrite": 0,
                             "items": ["original: " + snip],
                             "message": "A comparison in the original has no counterpart in the rewrite (it may have been rephrased past the heuristic; read it)."})
    for j, (w2, l2, s2) in enumerate(cn):
        if j not in matched_new:
            findings.append({"severity": "warn", "check": "compare.dir", "change": "added", "original": 0, "rewrite": 1,
                             "items": ["rewrite:  " + s2], "message": "A comparison appears in the rewrite that the original does not state."})
    return findings



def compare(original, rewrite):
    findings = []

    lit_o, rest_o = extract_literals(original)
    lit_r, rest_r = extract_literals(rewrite)
    sev_of = {kind: sev for kind, _p, sev in LITERAL_KINDS}
    rewrite_flat = _norm_ws(rewrite)
    for (kind, value), n in sorted((lit_o - lit_r).items()):
        if kind != "code-block" and value in rewrite_flat:
            if kind == "inline-code":
                findings.append({
                    "severity": "warn", "check": "literal.inline-code", "change": "unformatted",
                    "original": n, "rewrite": lit_r.get((kind, value), 0), "items": [value],
                    "message": "Value survived but lost its code formatting. A reader may no longer copy it exactly.",
                })
            continue
        findings.append({
            "severity": sev_of[kind], "check": f"literal.{kind}", "change": "missing",
            "original": n, "rewrite": lit_r.get((kind, value), 0), "items": [value],
            "message": "Literal missing or altered. Code, paths, flags, identifiers and codes must survive verbatim.",
        })
    for (kind, value), n in sorted((lit_r - lit_o).items()):
        if value in _norm_ws(original):
            continue
        findings.append({
            "severity": "warn" if kind == "quoted" else "error", "check": f"literal.{kind}",
            "change": "added", "original": lit_o.get((kind, value), 0), "rewrite": n, "items": [value],
            "message": "Literal not present in the original. A rewrite must not add identifiers or values.",
        })

    num_o, where_o = extract_numbers(rest_o)
    num_r, where_r = extract_numbers(rest_r)
    missing = num_o - num_r
    added = num_r - num_o
    if missing:
        findings.append({
            "severity": "error", "check": "number", "change": "missing",
            "original": sum(num_o.values()), "rewrite": sum(num_r.values()),
            "items": [f"{k} ×{v}  ← {where_o[k]}" for k, v in sorted(missing.items())],
            "message": "Number missing from the rewrite (values are normalized: 三 == 3 == three).",
        })
    if added:
        findings.append({
            "severity": "error", "check": "number", "change": "added",
            "original": sum(num_o.values()), "rewrite": sum(num_r.values()),
            "items": [f"{k} ×{v}  ← {where_r[k]}" for k, v in sorted(added.items())],
            "message": "Number not in the original. A rewrite must not add values.",
        })

    cat_o = extract_categories(rest_o)
    cat_r = extract_categories(rest_r)
    sev_cat = {name: sev for name, sev, _ in CATEGORIES}
    for name, _sev, _pats in CATEGORIES:
        n_o, hits_o = cat_o[name]
        n_r, hits_r = cat_r[name]
        if n_o == n_r:
            continue
        # Losing a marker widens or hardens the claim, so a decrease carries
        # the category's severity. Splitting one sentence into several often
        # repeats a marker ("if ... or otherwise" -> two "If" sentences), so an
        # increase is a warning, except for obligations: a new MUST or MUST NOT
        # is a new instruction.
        decreased = n_r < n_o
        severity = sev_cat[name] if decreased or name in GROWTH_IS_ERROR else "warn"
        findings.append({
            "severity": severity, "check": name,
            "change": "decreased" if decreased else "increased",
            "original": n_o, "rewrite": n_r,
            "items": (["original: " + h for h in hits_o[:6]] + ["rewrite:  " + h for h in hits_r[:6]]),
            "message": MESSAGES[name],
        })

    findings.extend(compare_direction(rest_o, rest_r))

    th_o, th_r = threshold_counts(rest_o), threshold_counts(rest_r)
    n_o, n_r = sum(th_o.values()), sum(th_r.values())
    if th_o != th_r and n_r <= n_o:
        # Same total, different buckets = a flipped bound (error). Fewer thresholds = a lost bound (warning).
        # More thresholds in the rewrite is not reported here: scope.limit already warns about added bounds.
        flipped = n_o == n_r
        findings.append({
            "severity": "error" if flipped else "warn", "check": "compare.op", "change": "flipped" if flipped else "lost",
            "original": n_o, "rewrite": n_r,
            "items": [f"{k}: {th_o.get(k, 0)} → {th_r.get(k, 0)}" for k in ("≥", "≤", ">", "<") if th_o.get(k, 0) != th_r.get(k, 0)],
            "message": ("Threshold directions moved between buckets while the total stayed the same: a flipped bound "
                        "(不超过 ↔ 超过, at least ↔ at most, < ↔ >) reverses the claim. Words and symbols share a bucket, so 以上 → ≥ is fine."
                        if flipped else
                        "A threshold in the original has no counterpart in the rewrite (words such as 以上/超过/at most and symbols such as ≥ > count together). Check that no bound was dropped."),
        })
    st_o, st_r = len(STRENGTH.findall(rest_o)), len(STRENGTH.findall(rest_r))
    so_o, so_r = len(STRENGTH_SOFT.findall(rest_o)), len(STRENGTH_SOFT.findall(rest_r))
    if st_o != st_r or so_o != so_r:
        strong_up = st_r > st_o
        findings.append({
            "severity": "error" if strong_up else "warn", "check": "strength",
            "change": "increased" if (st_r + so_r) > (st_o + so_o) else "decreased",
            "original": st_o + so_o, "rewrite": st_r + so_r,
            "items": ["original: " + _context(rest_o, m.start(), m.end()) for m in list(STRENGTH.finditer(rest_o)) + list(STRENGTH_SOFT.finditer(rest_o))][:6]
                     + ["rewrite:  " + _context(rest_r, m.start(), m.end()) for m in list(STRENGTH.finditer(rest_r)) + list(STRENGTH_SOFT.finditer(rest_r))][:6],
            "message": ("A claim-strengthening word (proved, definitely, 证明, 必然 ...) was added. The rewrite claims more than the source."
                        if strong_up else
                        "Claim-strength words changed (always, 一定, 完全 ...). These often strengthen a claim but have harmless readings: read the context."),
        })

    order = {"error": 0, "warn": 1}
    findings.sort(key=lambda f: (order[f["severity"]], f["check"]))
    return findings


def result_of(findings, strict=False):
    if any(f["severity"] == "error" for f in findings):
        return "FAIL"
    if findings:
        return "FAIL" if strict else "PASS WITH WARNINGS"
    return "PASS"


def render(findings):
    errors = sum(f["severity"] == "error" for f in findings)
    warns = len(findings) - errors
    lines = [f"fidelity: {errors} error(s), {warns} warning(s)"]
    for f in findings:
        lines.append(f"\n{f['severity'].upper():5} {f['check']}  {f['change']}  "
                     f"(original {f['original']} → rewrite {f['rewrite']})")
        lines.append(f"      {f['message']}")
        for item in f["items"]:
            lines.append(f"      · {item}")
    if not findings:
        lines.append("No mechanical differences found. This does not prove the meaning is unchanged.")
    lines.append(f"\nRESULT: {result_of(findings)}")
    return "\n".join(lines)


# ---------------------------------------------------------------------------
# Self-test
# ---------------------------------------------------------------------------

SELFTEST = [
    # (name, original, rewrite, checks that must be errors, checks that must
    # not be errors). {"*"} as the last field means: no finding at all.
    ("identical text is clean",
     "If the job fails, retry 3 times. Do not use `--force`.",
     "If the job fails, retry 3 times. Do not use `--force`.", set(), {"*"}),
    ("dropped hedge is an error (en)",
     "The request may have failed.", "The request failed.",
     {"modal.possibility"}, set()),
    ("dropped hedge is an error (zh)",
     "请求可能已经失败。", "请求失败了。", {"modal.possibility"}, set()),
    ("Chinese numeral equals Arabic numeral",
     "如果超时,重试三次。", "如果超时,重试 3 次。", set(), {"number", "condition"}),
    ("dropped condition is an error",
     "如果超时,重试 3 次。", "重试 3 次。", {"condition"}, {"number"}),
    ("splitting a sentence may repeat 'if' without an error",
     "If the job fails or otherwise stalls, page the owner.",
     "If the job fails, page the owner. If the job stalls, page the owner.", set(), {"condition"}),
    ("不要 equals 不得 (both prohibit)",
     "注意不要删除正在写入的日志。", "不得删除正在写入的日志。", set(), {"modal.prohibit"}),
    ("如果…的话 equals …时,",
     "如果目标文件已存在的话,跳过。", "目标文件已存在时,跳过。", set(), {"condition"}),
    ("以下步骤 is not a bound",
     "清理日志目录。", "按以下步骤清理日志目录:", set(), {"scope.limit"}),
    ("最好不要 -> 不建议 is a warning, not an error",
     "最好不要覆盖文件。", "不建议覆盖文件。", set(), {"modal.prohibit"}),
    ("最好不要 kept as 尽量不要 is still a warning only",
     "最好不要覆盖文件。", "尽量不要覆盖文件。", set(), {"modal.prohibit", "modal.not-recommend"}),
    ("90% 以上 is a bound",
     "使用率 90% 以上时,清理。", "使用率 ≥ 90% 时,清理。", set(), {"scope.limit"}),
    ("dropped 'Do not' is an error",
     "Do not run the migration twice.", "Run the migration twice.", {"modal.prohibit"}, set()),
    ("'does not match' is not a prohibition",
     "The format does not match.", "The format is different.", set(), {"modal.prohibit"}),
    ("lost upper bound is an error",
     "Retry at most 3 times.", "Retry 3 times.", {"scope.limit"}, {"number"}),
    ("'while processing' is not a condition",
     "An error occurred while processing the request.", "The request failed.", set(), {"condition"}),
    ("digits next to Chinese text are numbers (no space needed)",
     "文件大小不超过2048个字节。", "文件大小不超过 2048 字节。", set(), {"number", "scope.limit"}),
    ("a 100km range written without spaces",
     "规划100km以内的步行方案。", "工具规划 100 km 以内的步行方案。", set(), {"number"}),
    ("file name glued to Chinese text",
     "编辑config.yaml文件。", "编辑 config.yaml 文件。", set(), {"literal.filename", "literal.path"}),
    ("identifier glued to Chinese text",
     "把user_id传入函数。", "把 user_id 传入函数。", set(), {"literal.identifier"}),
    ("flag glued to Chinese text",
     "使用--force参数。", "使用 --force 参数。", set(), {"literal.flag"}),
    ("dropped unless is an error",
     "Delete the cache unless the job is running.", "Delete the cache.", {"condition"}, set()),
    ("missing flag is an error",
     "Run `deploy --dry-run` first.", "Run deploy first.", {"literal.inline-code"}, set()),
    ("added number is an error",
     "Wait for the sync to finish.", "Wait 30 seconds for the sync to finish.", {"number"}, set()),
    ("MUST to SHOULD drift is an error",
     "调用方必须先获取令牌。", "建议调用方先获取令牌。", {"modal.require"}, set()),
    ("approximation removed is an error",
     "超时时间约 5 秒。", "超时时间是 5 秒。", {"modal.approx"}, {"number"}),
    ("应用 / 响应 are not modals",
     "应用会返回响应。", "应用返回响应。", set(), {"modal.require"}),
    ("added list numbering is not a number change",
     "Open the file, then read line 3.", "1. Open the file.\n2. Read line 3.", set(), {"number"}),
    ("不同 / 不仅 are not negations",
     "两个参数不同,不仅类型不一样。", "两个参数不同,类型不一样。", set(), {"modal.prohibit"}),
    ("prohibition lost is an error",
     "不得在生产环境运行此命令。", "在生产环境运行此命令前先备份。", {"modal.prohibit"}, set()),
    ("English number word equals digit",
     "Retry twice, then wait ten seconds.", "Retry 2 times. Then wait 10 seconds.", set(), {"number"}),
    ("an article 一个 is not a number",
     "读取一个配置文件。", "读取配置文件。", set(), {"number"}),
    ("path survives as plain text",
     "Edit `config/app.yaml`.", "Edit config/app.yaml.", set(), {"literal.path"}),
    ("flipped comparison keeps the count but is an error",
     "The effect is significant when p < 0.05.", "The effect is significant when p > 0.05.", {"compare.op"}, set()),
    ("<= and ≤ are the same operator",
     "Use at most 3 retries when n <= 3.", "Use at most 3 retries when n ≤ 3.", set(), {"compare.op"}),
    ("arrows are not comparisons",
     "A -> B => C", "A to B to C", set(), {"compare.op"}),
    ("added strong word is an error (en)",
     "The result suggests the method helps.", "The result proves the method always helps.", {"strength"}, set()),
    ("added strong word is an error (zh)",
     "结果表明方法有帮助。", "结果证明方法完全有效。", {"strength"}, set()),
    ("'一定程度' is not a strong word",
     "在一定程度上有效。", "在一定程度上有效。", set(), {"strength"}),
    ("a lost strong word is only a warning",
     "The method always helps.", "The method helps.", set(), {"strength"}),
    ("scientific notation equals decimal",
     "The learning rate is 1e-3.", "The learning rate is 0.001.", set(), {"number"}),
    ("heading numbering is not a number change",
     "## Setup\n\nThe run took 30 seconds.", "## 2. Setup\n\nThe run took 30 seconds.", set(), {"number"}),
    ("reversed comparison is an error (en)",
     "Method A is better than method B.", "Method B is better than method A.", {"compare.dir"}, set()),
    ("same comparison, different words (en)",
     "Method A is better than method B.", "Method A outperforms method B.", set(), {"compare.dir"}),
    ("reversed comparison is an error (zh)",
     "随机稀疏连线比真实连线更好。", "真实连线比随机稀疏连线更好。", {"compare.dir"}, set()),
    ("比 and 优于 agree",
     "方案 A 比方案 B 好。", "方案 A 优于方案 B。", set(), {"compare.dir"}),
    ("优于 reversed into 不如 is an error",
     "方案 A 优于方案 B。", "方案 A 不如方案 B。", {"compare.dir"}, set()),
    ("A worse than B equals B better than A",
     "方案 A 比方案 B 差。", "方案 B 比方案 A 好。", set(), {"compare.dir"}),
    ("symbolic comparison flipped keeps the operator count",
     "Accuracy: A > B on all sets.", "Accuracy: B > A on all sets.", {"compare.dir"}, set()),
    ("比如 / 比较 are not comparisons",
     "比如这个参数;比较两个版本。", "例如这个参数;对照两个版本。", set(), {"compare.dir"}),
    ("以上 and ≥ are one bucket",
     "磁盘使用率达到 90% 以上时清理。", "磁盘使用率 ≥ 90% 时清理。", set(), {"compare.op"}),
    ("超过 and > are one bucket",
     "文件数超过 1000 个时变慢。", "文件数 > 1000 个时变慢。", set(), {"compare.op"}),
    ("不超过 and ≤ are one bucket",
     "单笔不超过 200 元可直接退款。", "单笔 ≤ 200 元可直接退款。", set(), {"compare.op"}),
    ("at most and no more than are one bucket",
     "Use at most 3 retries.", "Use no more than 3 retries.", set(), {"compare.op"}),
    ("不超过 -> 超过 is a flipped bound",
     "单笔不超过 200 元可以直接退款。", "单笔超过 200 元可以直接退款。", {"compare.op"}, set()),
    ("小于 -> 不小于 is a flipped bound",
     "剩余天数小于 14 才处理。", "剩余天数不小于 14 才处理。", {"compare.op"}, set()),
    ("at least -> at most is a flipped bound",
     "Retry at least 3 times.", "Retry at most 3 times.", {"compare.op"}, set()),
    ("以上 -> 以下 is a flipped bound",
     "磁盘使用率 90% 以上时清理。", "磁盘使用率 90% 以下时清理。", {"compare.op"}, set()),
    ("或更高 is the same bound as 以上; 不满足 is not a bound",
     "请加 Maintainer 以上的角色。", "请加 Maintainer 或更高的角色。Developer 不满足要求。", set(), {"compare.op"}),
    ("placeholders like <域名> are not comparison operators",
     "执行脚本并传入 <域名>。", "执行脚本,传入 <域名>。", set(), {"compare.op"}),
    ("a Markdown blockquote > is not a comparison operator",
     "> 注意:先备份。\n删除旧文件。", "注意:先备份。\n删除旧文件。", set(), {"compare.op"}),
    ("不一定 is a hedge, not a strong word",
     "修好这一处不一定能通过。", "只改这一个字段,不一定能通过校验。", set(), {"strength"}),
    ("绝对值 is a term, not a strong word",
     "差额的绝对值不超过 0.01 元。", "差额绝对值不超过 0.01 元。", set(), {"strength"}),
    ("列完全部 is not 完全",
     "如果一页没列完,继续翻页。", "如果一页没有列完全部文件,继续翻页。", set(), {"strength"}),
    ("an ambiguous strengthener only warns",
     "这个设置总是生效。", "这个设置始终生效,而且完全可靠。", set(), {"strength"}),
    ("a Markdown blockquote > is not a bound (scope.limit)",
     "> 注意:先备份。\n删除旧文件。", "注意:先备份。\n删除旧文件。", set(), {"scope.limit"}),
    ("a <placeholder> is not a bound (scope.limit)",
     "执行脚本并传入 <域名>。", "执行脚本,传入 <域名>。", set(), {"scope.limit"}),
    ("a < between operands is still a bound",
     "The effect holds when p < 0.05.", "The effect holds.", {"scope.limit"}, set()),
    ("一定要 and 必须 are the same requirement",
     "这一步一定要先备份。", "这一步必须先备份。", set(), {"modal.require", "strength"}),
    ("dropping 一定要 is a lost requirement",
     "这一步一定要先备份。", "这一步先备份。", {"modal.require"}, set()),
    ("trailing period is not part of a path",
     "Edit config/app.yaml.", "Open and edit config/app.yaml.", set(), {"literal.path", "literal.filename"}),
]


def selftest():
    failed = 0
    for name, original, rewrite, must_have, must_not in SELFTEST:
        got = {f["check"] for f in compare(original, rewrite) if f["severity"] == "error"}
        got_all = {f["check"] for f in compare(original, rewrite)}
        ok = must_have <= got
        if "*" in must_not:
            ok = ok and not got_all
        else:
            ok = ok and not (must_not & got)
        if not ok:
            failed += 1
            print(f"FAIL  {name}\n      expected errors {sorted(must_have)}, "
                  f"forbidden {sorted(must_not)}\n      got {sorted(got_all)}")
            print("      " + render(compare(original, rewrite)).replace("\n", "\n      "))
        else:
            print(f"ok    {name}")
    # 软推荐被替换时必须有 warning:不能静默通过。
    swap = {(f["severity"], f["check"]) for f in compare("最好不要覆盖文件。", "不建议覆盖文件。")}
    total = len(SELFTEST) + 1
    # RESULT line and severity mapping
    rr = result_of(compare("The result suggests it helps.", "The result proves it helps."))
    if rr != "FAIL":
        failed += 1
        print("FAIL  strengthened claim must give RESULT: FAIL, got", rr)
    total += 1
    if ("warn", "modal.not-recommend.soft") in swap:
        print("ok    最好不要 -> 不建议 produces a warning")
    else:
        failed += 1
        print("FAIL  最好不要 -> 不建议 produced no soft-recommend warning:", sorted(swap))
    print(f"\n{total - failed}/{total} passed")
    return 1 if failed else 0


def _read(path):
    if path == "-":
        return sys.stdin.read()
    with open(path, encoding="utf-8") as fh:
        return fh.read()


def main(argv=None):
    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
    ap.add_argument("original", nargs="?")
    ap.add_argument("rewrite", nargs="?")
    ap.add_argument("--json", action="store_true", help="machine-readable output")
    ap.add_argument("--strict", action="store_true", help="warnings also fail the run")
    ap.add_argument("--ignore", default="", help="comma-separated check names to skip (prefix match)")
    ap.add_argument("--selftest", action="store_true")
    args = ap.parse_args(argv)

    if args.selftest:
        return selftest()
    if not args.original or not args.rewrite:
        ap.print_usage(sys.stderr)
        return 2
    if args.original == "-" and args.rewrite == "-":
        print("Only one of ORIGINAL/REWRITE can be stdin.", file=sys.stderr)
        return 2

    findings = compare(_read(args.original), _read(args.rewrite))
    ignore = [s.strip() for s in args.ignore.split(",") if s.strip()]
    findings = [f for f in findings if not any(f["check"].startswith(i) for i in ignore)]

    if args.json:
        print(json.dumps({"result": result_of(findings, args.strict), "findings": findings}, ensure_ascii=False, indent=2))
    else:
        print(render(findings))
    failing = [f for f in findings if f["severity"] == "error" or args.strict]
    return 1 if failing else 0


if __name__ == "__main__":
    sys.exit(main())
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall