kcode-pi 0.1.0

package/vendor/kingdee-skills/ok-ksql/scripts/ksql_lint.py

@@ -0,0 +1,363 @@
+#!/usr/bin/env python3
+"""Static checks for ok-ksql generated PostgreSQL data-fix SQL files.
+
+The linter is intentionally dependency-free and conservative: it catches the
+high-risk patterns required by the ok-ksql skill, but it is not a full SQL
+parser. Fix reported ERROR items before delivery. WARN items document style
+preferences that may be acceptable only with an explicit reason.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, Iterator, Sequence
+
+
+TIMESTAMP_RE = re.compile(r"\b\d{12}\b")
+BACKUP_TABLE_RE = re.compile(r"\bbak_[a-zA-Z0-9_]+_(\d{12})\b", re.IGNORECASE)
+FILE_TS_RE = re.compile(r"ksql_[^/\\]*_(\d{12})\.txt$", re.IGNORECASE)
+HEADER_TS_RE = re.compile(r"备份表时间戳[：:]\s*(\d{12})")
+
+
+@dataclass(frozen=True)
+class Finding:
+    severity: str
+    line: int
+    message: str
+
+    def format(self, path: Path) -> str:
+        return f"{path}:{self.line}: {self.severity}: {self.message}"
+
+
+@dataclass(frozen=True)
+class Statement:
+    text: str
+    line: int
+
+
+def strip_comments_and_literals(sql: str) -> str:
+    """Return SQL with comments and quoted literals replaced by spaces.
+
+    This keeps line numbers stable while avoiding false positives from words
+    appearing inside comments or strings.
+    """
+
+    out: list[str] = []
+    i = 0
+    n = len(sql)
+    state = "normal"
+    dollar_tag = ""
+
+    while i < n:
+        ch = sql[i]
+        nxt = sql[i + 1] if i + 1 < n else ""
+
+        if state == "normal":
+            if ch == "-" and nxt == "-":
+                out.extend([" ", " "])
+                i += 2
+                state = "line_comment"
+                continue
+            if ch == "/" and nxt == "*":
+                out.extend([" ", " "])
+                i += 2
+                state = "block_comment"
+                continue
+            if ch == "'":
+                out.append(" ")
+                i += 1
+                state = "single_quote"
+                continue
+            if ch == '"':
+                out.append(" ")
+                i += 1
+                state = "double_quote"
+                continue
+            if ch == "$":
+                match = re.match(r"\$[A-Za-z_][A-Za-z0-9_]*\$|\$\$", sql[i:])
+                if match:
+                    dollar_tag = match.group(0)
+                    out.extend(" " * len(dollar_tag))
+                    i += len(dollar_tag)
+                    state = "dollar_quote"
+                    continue
+            out.append(ch)
+            i += 1
+            continue
+
+        if state == "line_comment":
+            out.append("\n" if ch == "\n" else " ")
+            i += 1
+            if ch == "\n":
+                state = "normal"
+            continue
+
+        if state == "block_comment":
+            if ch == "*" and nxt == "/":
+                out.extend([" ", " "])
+                i += 2
+                state = "normal"
+            else:
+                out.append("\n" if ch == "\n" else " ")
+                i += 1
+            continue
+
+        if state == "single_quote":
+            if ch == "'" and nxt == "'":
+                out.extend([" ", " "])
+                i += 2
+            else:
+                out.append("\n" if ch == "\n" else " ")
+                i += 1
+                if ch == "'":
+                    state = "normal"
+            continue
+
+        if state == "double_quote":
+            if ch == '"' and nxt == '"':
+                out.extend([" ", " "])
+                i += 2
+            else:
+                out.append("\n" if ch == "\n" else " ")
+                i += 1
+                if ch == '"':
+                    state = "normal"
+            continue
+
+        if state == "dollar_quote":
+            if sql.startswith(dollar_tag, i):
+                out.extend(" " * len(dollar_tag))
+                i += len(dollar_tag)
+                state = "normal"
+                dollar_tag = ""
+            else:
+                out.append("\n" if ch == "\n" else " ")
+                i += 1
+            continue
+
+    return "".join(out)
+
+
+def iter_statements(masked_sql: str) -> Iterator[Statement]:
+    start = 0
+    start_line = 1
+    line = 1
+
+    for idx, ch in enumerate(masked_sql):
+        if ch == ";":
+            text = masked_sql[start : idx + 1]
+            if text.strip():
+                yield Statement(text=text, line=start_line)
+            start = idx + 1
+            start_line = line
+        if ch == "\n":
+            line += 1
+            if not masked_sql[start:idx].strip():
+                start_line = line
+
+    tail = masked_sql[start:]
+    if tail.strip():
+        yield Statement(text=tail, line=start_line)
+
+
+def line_of_offset(text: str, base_line: int, offset: int) -> int:
+    return base_line + text[:offset].count("\n")
+
+
+def has_token(statement: str, token: str) -> bool:
+    return re.search(rf"\b{re.escape(token)}\b", statement, re.IGNORECASE) is not None
+
+
+def lint_statement(stmt: Statement) -> list[Finding]:
+    findings: list[Finding] = []
+    compact = " ".join(stmt.text.split())
+    if not compact:
+        return findings
+
+    first = re.match(r"^\s*(\w+)", compact)
+    first_word = first.group(1).upper() if first else ""
+
+    if first_word in {"UPDATE", "DELETE"} and not has_token(stmt.text, "WHERE"):
+        findings.append(
+            Finding(
+                "ERROR",
+                stmt.line,
+                f"{first_word} 语句缺少 WHERE，禁止生成无范围更新/删除。",
+            )
+        )
+
+    select_star_matches = list(re.finditer(r"\bSELECT\s+\*", stmt.text, re.IGNORECASE))
+    if select_star_matches:
+        is_backup = re.search(
+            r"\bSELECT\s+\*\s+INTO\s+bak_[a-zA-Z0-9_]+_\d{12}\s+FROM\b",
+            stmt.text,
+            re.IGNORECASE,
+        )
+        if is_backup:
+            if has_token(stmt.text, "WHERE"):
+                findings.append(
+                    Finding(
+                        "ERROR",
+                        stmt.line,
+                        "备份语句必须整表备份，SELECT * INTO bak_... 不允许带 WHERE。",
+                    )
+                )
+        else:
+            for match in select_star_matches:
+                findings.append(
+                    Finding(
+                        "ERROR",
+                        line_of_offset(stmt.text, stmt.line, match.start()),
+                        "查询/验证语句禁止 SELECT *；只有整表备份 SELECT * INTO bak_... 例外。",
+                    )
+                )
+
+    if re.search(r"\bSELECT\s+\*\s+INTO\b", stmt.text, re.IGNORECASE) and not re.search(
+        r"\bSELECT\s+\*\s+INTO\s+bak_[a-zA-Z0-9_]+_\d{12}\s+FROM\b",
+        stmt.text,
+        re.IGNORECASE,
+    ):
+        findings.append(
+            Finding(
+                "ERROR",
+                stmt.line,
+                "备份表名必须形如 bak_<原表或业务缩写>_<yyyyMMddHHmm>。",
+            )
+        )
+
+    for match in re.finditer(r"\bEXISTS\b", stmt.text, re.IGNORECASE):
+        findings.append(
+            Finding(
+                "WARN",
+                line_of_offset(stmt.text, stmt.line, match.start()),
+                "SQL 可读性偏好：成员关系/半连接默认使用 IN，只有 IN 改变语义时才保留 EXISTS 并说明原因。",
+            )
+        )
+
+    if re.search(r"\bUPDATE\b.+\bJOIN\b", compact, re.IGNORECASE):
+        findings.append(
+            Finding(
+                "WARN",
+                stmt.line,
+                "PostgreSQL 多表更新优先使用 UPDATE ... FROM ... WHERE ...，不要使用 MySQL 风格 UPDATE ... JOIN。",
+            )
+        )
+
+    if re.search(r"=\s*NULL\b|\bNULL\s*=", stmt.text, re.IGNORECASE):
+        findings.append(
+            Finding(
+                "ERROR",
+                stmt.line,
+                "NULL 判断必须使用 IS NULL / IS NOT NULL，不能使用 = NULL。",
+            )
+        )
+
+    if re.search(r"<>|!=", stmt.text) and has_token(stmt.text, "NULL"):
+        findings.append(
+            Finding(
+                "WARN",
+                stmt.line,
+                "涉及 NULL 的不等比较需确认语义；PostgreSQL 可优先使用 IS DISTINCT FROM。",
+            )
+        )
+
+    return findings
+
+
+def lint_timestamps(path: Path, raw_sql: str) -> list[Finding]:
+    findings: list[Finding] = []
+    backup_timestamps = set(BACKUP_TABLE_RE.findall(raw_sql))
+
+    if len(backup_timestamps) > 1:
+        findings.append(
+            Finding(
+                "ERROR",
+                1,
+                "同一 SQL 文件中出现多个备份表时间戳；桌面文件、备份表和文件头时间戳必须一致。",
+            )
+        )
+
+    file_match = FILE_TS_RE.search(path.name)
+    if file_match and backup_timestamps and file_match.group(1) not in backup_timestamps:
+        findings.append(
+            Finding(
+                "ERROR",
+                1,
+                f"文件名时间戳 {file_match.group(1)} 与备份表时间戳 {', '.join(sorted(backup_timestamps))} 不一致。",
+            )
+        )
+
+    header_matches = list(HEADER_TS_RE.finditer(raw_sql))
+    header_timestamps = {m.group(1) for m in header_matches}
+    if len(header_timestamps) > 1:
+        findings.append(Finding("ERROR", 1, "文件头出现多个不同的备份表时间戳。"))
+    if header_timestamps and backup_timestamps and header_timestamps != backup_timestamps:
+        findings.append(
+            Finding(
+                "ERROR",
+                1,
+                f"文件头时间戳 {', '.join(sorted(header_timestamps))} 与备份表时间戳 {', '.join(sorted(backup_timestamps))} 不一致。",
+            )
+        )
+
+    return findings
+
+
+def lint_file(path: Path) -> list[Finding]:
+    raw_sql = path.read_text(encoding="utf-8")
+    masked_sql = strip_comments_and_literals(raw_sql)
+
+    findings: list[Finding] = []
+    findings.extend(lint_timestamps(path, raw_sql))
+    for stmt in iter_statements(masked_sql):
+        findings.extend(lint_statement(stmt))
+    return sorted(findings, key=lambda f: (f.line, f.severity, f.message))
+
+
+def parse_args(argv: Sequence[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Lint ok-ksql generated PostgreSQL data-fix SQL files."
+    )
+    parser.add_argument("paths", nargs="+", type=Path, help="SQL/.txt files to lint")
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="treat WARN findings as failures",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = parse_args(sys.argv[1:] if argv is None else argv)
+    all_findings: list[tuple[Path, Finding]] = []
+
+    for path in args.paths:
+        if not path.exists():
+            print(f"{path}:1: ERROR: 文件不存在。", file=sys.stderr)
+            return 2
+        if path.is_dir():
+            print(f"{path}:1: ERROR: 请输入 SQL/.txt 文件，不能是目录。", file=sys.stderr)
+            return 2
+        for finding in lint_file(path):
+            all_findings.append((path, finding))
+
+    for path, finding in all_findings:
+        print(finding.format(path))
+
+    error_count = sum(1 for _, f in all_findings if f.severity == "ERROR")
+    warn_count = sum(1 for _, f in all_findings if f.severity == "WARN")
+    print(f"SUMMARY: {error_count} error(s), {warn_count} warning(s)")
+
+    if error_count:
+        return 1
+    if args.strict and warn_count:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())