Skip to content

armgit / peach

Public Imported from GitHub
0

Peach: Local-first video metadata scraper and media manager.

6.1 KB
Raw Blame
"""核对 Python、HTML 与文档文案;JS/TS 由前端语法检查器负责。"""
from __future__ import annotations

import argparse
import ast
from dataclasses import dataclass
from html.parser import HTMLParser
import io
import json
from pathlib import Path
import re
import sys
import tokenize

ROOT = Path(__file__).resolve().parents[1]
DISABLE_MARKER = "copy-lint-disable-line"
RULES = json.loads((ROOT / "scripts/copy-rules.json").read_text(encoding="utf-8"))
SELF_DESCRIBING = frozenset({"scripts/check_copy_final_state.py", "tests/test_copy_final_state.py"})
FENCE_RE = re.compile(r"^\s*(`{3,}|~{3,})")


@dataclass(frozen=True)
class Finding:
    path: str
    line: int
    term: str
    message: str
    severity: str = "error"

    def __str__(self) -> str:
        return f"{self.path}:{self.line}: {self.severity}: 「{self.term}」 — {self.message}"


def _scan_text(path: str, line_no: int, text: str, *, group: str = "prose") -> list[Finding]:
    if DISABLE_MARKER in text:
        return []
    found = [Finding(path, line_no, match.group(0), message, severity)
             for pattern, message, severity in RULES[group]
             for match in re.finditer(pattern, text, re.IGNORECASE)]
    # 同一段明确违规只报错误,避免同一位置出现重复提示。
    return [item for item in found if item.severity == "error"] or found


def scan_lines(path: str, source: str, *, skip_code_fences: bool) -> list[Finding]:
    """Markdown 围栏代码块保留命令与输出原文。"""
    found: list[Finding] = []
    fence = None
    for line_no, raw in enumerate(source.splitlines(), start=1):
        match = FENCE_RE.match(raw) if skip_code_fences else None
        if match:
            delimiter = match.group(1)
            if fence is None:
                fence = delimiter
            elif delimiter[0] == fence[0] and len(delimiter) >= len(fence):
                fence = None
            continue
        if fence is None:
            found.extend(_scan_text(path, line_no, raw))
            # 只查 Markdown;源码注释与界面字串不在此列。
            found.extend(_scan_text(path, line_no, raw, group="doc_terms"))
    return found


def scan_python(path: str, source: str) -> list[Finding]:
    """读取注释和 AST 字符串,包括 f-string 的静态片段。"""
    found: list[Finding] = []
    lines = source.splitlines()

    def scan(text, start, group="prose", end=None):
        for offset, piece in enumerate(text.splitlines()):
            number = min(start + offset, end) if end is not None else start + offset
            if number <= len(lines) and DISABLE_MARKER not in lines[number - 1]:
                found.extend(_scan_text(path, number, piece, group=group))

    try:
        tree = ast.parse(source)
        for token in tokenize.generate_tokens(io.StringIO(source).readline):
            if token.type == tokenize.COMMENT:
                scan(token.string, token.start[0])
    except (tokenize.TokenError, IndentationError, SyntaxError) as error:
        return [Finding(path, getattr(error, "lineno", None) or 1, "syntax", "无法解析 Python 文案")]
    for node in ast.walk(tree):
        if isinstance(node, ast.Constant) and isinstance(node.value, str):
            scan(node.value, node.lineno, end=node.end_lineno)
        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name.startswith("test"):
            scan(node.name, node.lineno, "test_names")
    return found


def scan_html(path: str, source: str) -> list[Finding]:
    """HTML 只读取正文、注释与用户可见属性。"""
    found = []
    lines = source.splitlines()

    class ProseParser(HTMLParser):
        hidden = 0

        def emit(self, text):
            for offset, part in enumerate(text.splitlines()):
                line = self.getpos()[0] + offset
                if line <= len(lines) and DISABLE_MARKER not in lines[line - 1]:
                    found.extend(_scan_text(path, line, part))

        def handle_starttag(self, tag, attrs):
            if tag in {"script", "style"}:
                self.hidden += 1
            for key, value in attrs:
                if key in {"title", "alt", "placeholder", "aria-label"} and value:
                    self.emit(value)

        def handle_endtag(self, tag):
            if tag in {"script", "style"}:
                self.hidden = max(0, self.hidden - 1)

        def handle_data(self, data):
            if not self.hidden:
                self.emit(data)

        def handle_comment(self, data):
            self.emit(data)

    ProseParser().feed(source)
    return found


def targets(root: Path) -> list[Path]:
    picked = [root / name for name in ("AGENTS.md", "CONTRIBUTING.md", "README.md", "README.zh-CN.md")]
    picked.extend(sorted((root / "docs").glob("*.md")))
    picked.extend(sorted((root / ".claude/skills").glob("*/SKILL.md")))
    picked.extend(sorted((root / "web").glob("*.html")))
    for directory in ("src", "scripts", "tests"):
        picked.extend(sorted((root / directory).rglob("*.py")))
    return list(dict.fromkeys(path.resolve() for path in picked if path.is_file()))


def scan_repo(root: Path = ROOT) -> list[Finding]:
    found = []
    for path in targets(root):
        rel = path.relative_to(root).as_posix()
        if rel in SELF_DESCRIBING:
            continue
        source = path.read_text(encoding="utf-8")
        if path.suffix == ".py":
            found.extend(scan_python(rel, source))
        elif path.suffix == ".html":
            found.extend(scan_html(rel, source))
        else:
            found.extend(scan_lines(rel, source, skip_code_fences=True))
    return sorted(found, key=lambda item: (item.path, item.line, item.term))


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--root", default=str(ROOT))
    findings = scan_repo(Path(parser.parse_args(argv).root).resolve())
    for finding in findings:
        print(finding)
    errors = sum(item.severity == "error" for item in findings)
    print(f"文案检查:{errors} 处错误,{len(findings) - errors} 处待人工核对。")
    return int(bool(errors))


if __name__ == "__main__":
    sys.exit(main())