paperfit-cli 1.0.0

package/scripts/overflow_fixers.py

@@ -0,0 +1,656 @@
+#!/usr/bin/env python3
+"""
+Overflow Fixers Module
+
+处理 Category D：溢出与对齐缺陷
+- D1: Overfull hbox（段落文本、表格单元格、公式溢出栏宽）
+- D2: 长公式未合理断行
+- D3: URL/长标识符溢出
+
+该模块被 code-surgeon-agent 调用，执行对 .tex 源码的精确修改。
+所有修复遵循最小修改原则，不改变学术内容。
+"""
+
+import re
+from pathlib import Path
+from dataclasses import dataclass, field
+from typing import List, Dict, Optional, Tuple, Any
+
+
+# ============================================================
+# 数据结构定义
+# ============================================================
+
+@dataclass
+class FixResult:
+    """修复结果"""
+    defect_id: str
+    object_name: str
+    action: str
+    before: str
+    after: str
+    page: int = 0
+    line_number: Optional[int] = None
+    success: bool = False
+
+
+@dataclass
+class OverflowFixReport:
+    """修复报告"""
+    status: str  # success | partial | failed
+    modified_files: List[str] = field(default_factory=list)
+    changes: List[FixResult] = field(default_factory=list)
+    unresolved: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "skill": "overflow-repair",
+            "status": self.status,
+            "modified_files": self.modified_files,
+            "changes": [
+                {
+                    "defect_id": c.defect_id,
+                    "object": c.object_name,
+                    "action": c.action,
+                    "before": c.before,
+                    "after": c.after,
+                    "page": c.page,
+                    "line_number": c.line_number,
+                    "success": c.success,
+                }
+                for c in self.changes
+            ],
+            "unresolved": self.unresolved,
+        }
+
+
+# ============================================================
+# D1: 段落文本溢出修复
+# ============================================================
+
+def fix_paragraph_overflow(
+    tex_content: str,
+    overfull_line: str,
+    overflow_amount: float,
+) -> Tuple[str, Optional[FixResult]]:
+    """
+    修复段落文本溢出
+
+    策略优先级:
+    1. 引入断词点 (\-)
+    2. 调整段落级容差 (\emergencystretch)
+    3. 返回未解决 (需语义改写)
+
+    Args:
+        tex_content: .tex 文件内容
+        overfull_line: 溢出的文本行
+        overflow_amount: 溢出量 (pt)
+
+    Returns:
+        (修改后的内容，修复结果)
+    """
+    # 策略 1: 为长单词添加断词点
+    # 查找长度 > 10 的单词 (可能是复合词或长学术术语)
+    long_words = re.findall(r'\b[a-zA-Z]{10,}\b', overfull_line)
+
+    if long_words:
+        # 为最长的单词添加断词点
+        longest_word = max(long_words, key=len)
+        if len(longest_word) >= 12:
+            # 在音节边界处添加断词点 (简化：每 4-5 个字母)
+            hyphenated = add_hyphenation_points(longest_word)
+            modified_content = tex_content.replace(longest_word, hyphenated, 1)
+            return modified_content, FixResult(
+                defect_id="D1",
+                object_name=f"段落文本",
+                action=f"为长单词 '{longest_word}' 添加断词点",
+                before=longest_word,
+                after=hyphenated,
+                success=True,
+            )
+
+    # 策略 2: 为段落添加\emergencystretch
+    # 查找包含溢出行的段落
+    paragraph_match = re.search(
+        r'((?:^[^\n]*\n)*?)'  # 段落前的内容
+        r'([^\n]*' + re.escape(overfull_line[:50]) + r'[^\n]*(?:\n[^\n]*)*?)'  # 包含溢出行的段落
+        r'((?:\n[^\n]*)*?\n\n|\Z)',  # 段落到段落结束
+        tex_content,
+        re.MULTILINE
+    )
+
+    if paragraph_match:
+        paragraph = paragraph_match.group(0)
+        # 用花括号包裹并添加\emergencystretch
+        wrapped = f"{{\\emergencystretch=1em {paragraph.strip()}}}"
+        modified_content = tex_content.replace(paragraph, wrapped, 1)
+        return modified_content, FixResult(
+            defect_id="D1",
+            object_name="段落文本",
+            action=f"添加\\emergencystretch=1em 以允许额外拉伸",
+            before=overfull_line[:80] + "..." if len(overfull_line) > 80 else overfull_line,
+            after=f"{{\\emergencystretch=1em ...}}",
+            success=True,
+        )
+
+    # 策略 3: 无法自动修复，需要语义改写
+    return tex_content, None
+
+
+def add_hyphenation_points(word: str) -> str:
+    """
+    为长单词添加断词点
+
+    简化实现：在元音 - 辅音边界处添加
+    """
+    if len(word) < 12:
+        return word
+
+    # 简化：每 4-5 个字母添加一个断词点 (在实际应用中应使用更精确的音节划分)
+    vowels = "aeiouAEIOU"
+    result = []
+    i = 0
+    while i < len(word):
+        result.append(word[i])
+        # 在元音后检查是否可以断词
+        if word[i] in vowels and i > 3 and i < len(word) - 3:
+            # 检查下一个字母是否是辅音
+            if i + 1 < len(word) and word[i + 1] not in vowels:
+                result.append(r'\-')
+        i += 1
+
+    return ''.join(result)
+
+
+# ============================================================
+# D1: 表格单元格溢出修复
+# ============================================================
+
+def fix_table_overflow(
+    tex_content: str,
+    table_label: Optional[str] = None,
+    line_number: Optional[int] = None,
+) -> Tuple[str, Optional[FixResult]]:
+    """
+    修复表格单元格溢出
+
+    策略优先级:
+    1. 改用 tabularx 环境
+    2. 手动设置列宽 (p{宽度})
+    3. 精简表头
+    4. 调整字号
+
+    Args:
+        tex_content: .tex 文件内容
+        table_label: 表格标签 (如 "tab:results")
+        line_number: 溢出行号
+
+    Returns:
+        (修改后的内容，修复结果)
+    """
+    # 定位表格环境
+    if table_label:
+        # 通过标签定位表格
+        pattern = r'(\\begin\{(?:table|table\*|sidewaystable)\}(?:\[[htbp]+\])?.*?)(\\begin\{tabular\})(\{[^}]+\})(.*?)(\\end\{tabular\})(.*?\\end\{(?:table|table\*|sidewaystable)\})'
+    else:
+        # 查找最近的 tabular 环境
+        pattern = r'(\\begin\{(?:table|table\*|sidewaystable)\}(?:\[[htbp]+\])?.*?)(\\begin\{tabular\})(\{[^}]+\})(.*?)(\\end\{tabular\})(.*?\\end\{(?:table|table\*|sidewaystable)\})'
+
+    matches = list(re.finditer(pattern, tex_content, re.DOTALL))
+
+    if not matches:
+        return tex_content, None
+
+    # 如果有 line_number，找到最接近的表格
+    target_match = matches[0]
+    if line_number:
+        for match in matches:
+            if match.start() <= line_number <= match.end():
+                target_match = match
+                break
+
+    full_table = target_match.group(0)
+    tabular_start = target_match.group(2)
+    column_spec = target_match.group(3)
+    table_body = target_match.group(4)
+    tabular_end = target_match.group(5)
+
+    # 策略 1: 改用 tabularx
+    # 检查是否有文本列 (l, r, c) 可以改为 X 列
+    if 'l' in column_spec or 'r' in column_spec or 'c' in column_spec:
+        # 将 tabular 改为 tabularx，将部分列改为 X 列
+        new_column_spec = convert_to_tabularx_columns(column_spec)
+        new_table = full_table.replace(
+            f"\\begin{{tabular}}{column_spec}",
+            f"\\begin{{tabularx}}{{\\linewidth}}{new_column_spec}"
+        ).replace(
+            f"\\end{{tabular}}",
+            f"\\end{{tabularx}}"
+        )
+        modified_content = tex_content.replace(full_table, new_table, 1)
+        return modified_content, FixResult(
+            defect_id="D1",
+            object_name=table_label or "表格",
+            action=f"将 tabular 改为 tabularx，列规格从 {column_spec} 改为 {new_column_spec}",
+            before=f"\\begin{{tabular}}{column_spec}",
+            after=f"\\begin{{tabularx}}{{\\linewidth}}{new_column_spec}",
+            line_number=line_number,
+            success=True,
+        )
+
+    # 策略 2: 添加\small 字号
+    if '\\small' not in full_table and '\\footnotesize' not in full_table:
+        # 在表格环境内添加\small
+        table_env_match = re.search(
+            r'\\begin\{(table[^}]*)\}(\[[htbp]+\])?',
+            full_table
+        )
+        if table_env_match:
+            insert_pos = target_match.end(0)
+            before = tex_content[:insert_pos]
+            after = tex_content[insert_pos:]
+            new_content = before + "\n\\small" + after
+            return new_content, FixResult(
+                defect_id="D1",
+                object_name=table_label or "表格",
+                action="添加\\small 字号以压缩表格",
+                before=full_table[:100] + "...",
+                after=full_table[:100] + "...\n\\small",
+                line_number=line_number,
+                success=True,
+            )
+
+    return tex_content, None
+
+
+def convert_to_tabularx_columns(column_spec: str) -> str:
+    """
+    将 tabular 列规格转换为 tabularx 列规格
+
+    策略：将最宽的文本列改为 X 列
+    """
+    # 移除两侧的 { }
+    spec = column_spec.strip('{}')
+
+    # 统计列类型
+    text_columns = []  # l, r, c 列的位置
+    for i, c in enumerate(spec):
+        if c in 'lrc':
+            text_columns.append((i, c))
+
+    if not text_columns:
+        return column_spec
+
+    # 将最后一个文本列改为 X 列 (通常是描述性列)
+    last_text_idx, last_type = text_columns[-1]
+    new_spec = spec[:last_text_idx] + 'X' + spec[last_text_idx + 1:]
+
+    return '{' + new_spec + '}'
+
+
+# ============================================================
+# D2: 长公式溢出修复
+# ============================================================
+
+def fix_equation_overflow(
+    tex_content: str,
+    equation_label: Optional[str] = None,
+    line_number: Optional[int] = None,
+) -> Tuple[str, Optional[FixResult]]:
+    """
+    修复长公式溢出
+
+    策略优先级:
+    1. equation → multline
+    2. equation → align/split
+    3. 引入中间变量简化
+
+    Args:
+        tex_content: .tex 文件内容
+        equation_label: 公式标签
+        line_number: 溢出行号
+
+    Returns:
+        (修改后的内容，修复结果)
+    """
+    # 策略 1: 将 equation 改为 multline
+    if equation_label:
+        pattern = r'(\\begin\{equation\})(.*?\\label\{' + re.escape(equation_label) + r'\}.*?)(\\end\{equation\})'
+    else:
+        pattern = r'(\\begin\{equation\})(.*?)(\\end\{equation\})'
+
+    match = re.search(pattern, tex_content, re.DOTALL)
+    if not match:
+        return tex_content, None
+
+    equation_start = match.group(1)
+    equation_body = match.group(2)
+    equation_end = match.group(3)
+
+    # 检查公式是否包含等号 (适合在等号处断行)
+    if '=' in equation_body:
+        # 策略：改为 split 环境，在等号处对齐
+        # 找到第一个等号位置
+        eq_pos = equation_body.find('=')
+        if eq_pos > 0:
+            before_eq = equation_body[:eq_pos].strip()
+            after_eq = equation_body[eq_pos:].strip()
+
+            # 在 + 或 - 处断行 (如果有)
+            if '+' in after_eq or '-' in after_eq:
+                # 找到合适的断行点
+                break_pos = max(after_eq.rfind('+'), after_eq.rfind('-'))
+                if break_pos > 0:
+                    line1 = after_eq[:break_pos].strip()
+                    line2 = after_eq[break_pos:].strip()
+                    new_body = f"{before_eq} = {line1} \\\\\n        &{line2}"
+
+                    new_equation = f"\\begin{{split}}\n{new_body}\n\\end{{split}}"
+                    modified_content = tex_content.replace(
+                        f"{equation_start}{equation_body}{equation_end}",
+                        new_equation,
+                        1
+                    )
+                    return modified_content, FixResult(
+                        defect_id="D2",
+                        object_name=equation_label or "公式",
+                        action="将 equation 改为 split 环境，在等号处对齐并在运算符处断行",
+                        before=f"\\begin{{equation}}...\\end{{equation}}",
+                        after=f"\\begin{{split}}...\\end{{split}}",
+                        line_number=line_number,
+                        success=True,
+                    )
+
+    # 策略 2: 改为 multline (首行左对齐，末行右对齐)
+    new_equation = f"\\begin{{multline}}\n{equation_body.strip()}\n\\end{{multline}}"
+    modified_content = tex_content.replace(
+        f"{equation_start}{equation_body}{equation_end}",
+        new_equation,
+        1
+    )
+    return modified_content, FixResult(
+        defect_id="D2",
+        object_name=equation_label or "公式",
+        action="将 equation 改为 multline 环境",
+        before=f"\\begin{{equation}}...\\end{{equation}}",
+        after=f"\\begin{{multline}}...\\end{{multline}}",
+        line_number=line_number,
+        success=True,
+    )
+
+
+# ============================================================
+# D3: URL 溢出修复
+# ============================================================
+
+def fix_url_overflow(
+    tex_content: str,
+    url: Optional[str] = None,
+) -> Tuple[str, Optional[FixResult]]:
+    """
+    修复 URL 溢出
+
+    策略优先级:
+    1. 使用\url 命令
+    2. 启用参考文献断行
+    3. 手动添加断行点
+
+    Args:
+        tex_content: .tex 文件内容
+        url: 溢出的 URL
+
+    Returns:
+        (修改后的内容，修复结果)
+    """
+    if url:
+        # 策略 1: 将裸 URL 改为\url 命令
+        # 查找裸 URL (以 http://或 https://开头)
+        url_pattern = r'(?<!\\)(https?://' + re.escape(url.replace('https://', '').replace('http://', '')) + r')'
+        match = re.search(url_pattern, tex_content)
+        if match:
+            bare_url = match.group(1)
+            modified_content = tex_content.replace(bare_url, f"\\url{{{bare_url}}}", 1)
+            return modified_content, FixResult(
+                defect_id="D3",
+                object_name="URL",
+                action=f"将裸 URL 改为\\url 命令",
+                before=bare_url[:50] + "..." if len(bare_url) > 50 else bare_url,
+                after=f"\\url{{{bare_url[:50]}...}}" if len(bare_url) > 50 else f"\\url{{{bare_url}}}",
+                success=True,
+            )
+
+    # 策略 2: 检查导言区是否有 url 宏包和断行设置
+    # 若没有，添加断行设置
+    if '\\usepackage{url}' not in tex_content and '\\usepackage{hyperref}' not in tex_content:
+        # 在\begin{document} 前添加宏包
+        match = re.search(r'\\begin\{document\}', tex_content)
+        if match:
+            insert_pos = match.start()
+            before = tex_content[:insert_pos]
+            after = tex_content[insert_pos:]
+            new_content = before + "\\usepackage{url}\n\\def\\UrlBreaks{\\do\\/\\do-}\n" + after
+            return new_content, FixResult(
+                defect_id="D3",
+                object_name="URL 断行设置",
+                action="添加 url 宏包和断行设置",
+                before="\\begin{document}",
+                after="\\usepackage{url}\n\\def\\UrlBreaks{\\do\\/\\do-}\n\\begin{document}",
+                success=True,
+            )
+
+    return tex_content, None
+
+
+def fix_bibliography_url_breaking(
+    tex_content: str,
+) -> Tuple[str, Optional[FixResult]]:
+    """
+    为参考文献添加 URL 断行设置
+
+    针对 biblatex 或 natbib 的 URL 断行配置
+    """
+    # 检查是否使用 biblatex
+    if '\\usepackage{biblatex}' in tex_content or '\\bibliographystyle{biblatex}' in tex_content:
+        # 添加 biblatex 的 URL 断行计数器
+        if '\\setcounter{biburlnumpenalty}' not in tex_content:
+            match = re.search(r'\\begin\{document\}', tex_content)
+            if match:
+                insert_pos = match.start()
+                before = tex_content[:insert_pos]
+                after = tex_content[insert_pos:]
+                additions = (
+                    "\\setcounter{biburlnumpenalty}{100}\n"
+                    "\\setcounter{biburlucpenalty}{100}\n"
+                    "\\setcounter{biburllcpenalty}{100}\n"
+                )
+                new_content = before + additions + after
+                return new_content, FixResult(
+                    defect_id="D3",
+                    object_name="参考文献 URL 断行",
+                    action="添加 biblatex URL 断行计数器",
+                    before="\\begin{document}",
+                    after=additions + "\\begin{document}",
+                    success=True,
+                )
+
+    return tex_content, None
+
+
+# ============================================================
+# 主修复函数
+# ============================================================
+
+def fix_overflow_defects(
+    tex_file_path: str,
+    defects: List[Dict[str, Any]],
+) -> OverflowFixReport:
+    """
+    修复所有 Category D 缺陷
+
+    Args:
+        tex_file_path: .tex 文件路径
+        defects: 缺陷列表，每个缺陷包含:
+            - defect_id: D1, D2, D3
+            - page: 页码
+            - line_number: 行号 (可选)
+            - object: 对象名称 (如表格标签、公式标签)
+            - description: 描述
+            - overflow_amount: 溢出量 (D1 可选)
+
+    Returns:
+        OverflowFixReport: 修复报告
+    """
+    tex_path = Path(tex_file_path)
+    if not tex_path.exists():
+        return OverflowFixReport(
+            status="failed",
+            unresolved=[f"文件不存在：{tex_file_path}"]
+        )
+
+    try:
+        tex_content = tex_path.read_text(encoding='utf-8')
+    except (OSError, UnicodeDecodeError) as e:
+        return OverflowFixReport(
+            status="failed",
+            unresolved=[f"无法读取文件 {tex_file_path}: {e}"]
+        )
+
+    modified_files = set()
+    changes = []
+    unresolved = []
+
+    for defect in defects:
+        defect_id = defect.get("defect_id", "")
+        page = defect.get("page", 0)
+        line_number = defect.get("line_number")
+        object_name = defect.get("object", "")
+        overflow_amount = defect.get("overflow_amount", 0)
+
+        new_content = tex_content
+        fix_result = None
+
+        if defect_id == "D1":
+            # 判断是段落溢出还是表格溢出
+            if "table" in object_name.lower() or "tab:" in object_name.lower():
+                new_content, fix_result = fix_table_overflow(
+                    tex_content,
+                    table_label=object_name if object_name.startswith("tab:") else None,
+                    line_number=line_number,
+                )
+            else:
+                new_content, fix_result = fix_paragraph_overflow(
+                    tex_content,
+                    overfull_line=defect.get("description", ""),
+                    overflow_amount=overflow_amount,
+                )
+
+        elif defect_id == "D2":
+            new_content, fix_result = fix_equation_overflow(
+                tex_content,
+                equation_label=object_name if object_name.startswith("eq:") else None,
+                line_number=line_number,
+            )
+
+        elif defect_id == "D3":
+            # 尝试修复 URL
+            url = defect.get("url", "")
+            new_content, fix_result = fix_url_overflow(tex_content, url=url)
+            if not fix_result:
+                # 尝试修复参考文献 URL 断行
+                new_content, fix_result = fix_bibliography_url_breaking(tex_content)
+
+        # 检查修复是否成功
+        if fix_result and new_content != tex_content:
+            tex_content = new_content
+            fix_result.page = page
+            fix_result.line_number = line_number
+            changes.append(fix_result)
+            modified_files.add(str(tex_path))
+        else:
+            unresolved.append(
+                f"{defect_id} ({object_name or '未知对象'}): 无法自动修复，可能需要语义改写或人工调整"
+            )
+
+    # 写入修改后的内容
+    if modified_files:
+        try:
+            tex_path.write_text(tex_content, encoding='utf-8')
+        except OSError as e:
+            unresolved.append(f"无法写入文件 {tex_path}: {e}")
+            return OverflowFixReport(
+                status="failed",
+                modified_files=list(modified_files),
+                changes=changes,
+                unresolved=unresolved,
+            )
+
+    status = "success" if not unresolved else ("partial" if changes else "failed")
+
+    return OverflowFixReport(
+        status=status,
+        modified_files=list(modified_files),
+        changes=changes,
+        unresolved=unresolved,
+    )
+
+
+# ============================================================
+# CLI 入口
+# ============================================================
+
+def main():
+    """命令行接口"""
+    import argparse
+    import json
+
+    parser = argparse.ArgumentParser(
+        description="Fix Category D overflow defects in LaTeX documents"
+    )
+    parser.add_argument(
+        "tex_file",
+        help="Path to .tex file"
+    )
+    parser.add_argument(
+        "--defects",
+        type=str,
+        help="JSON string or file path containing defect list"
+    )
+    parser.add_argument(
+        "--json",
+        "-j",
+        action="store_true",
+        help="Output JSON report"
+    )
+
+    args = parser.parse_args()
+
+    # 解析缺陷列表
+    defects = []
+    if args.defects:
+        if Path(args.defects).exists():
+            with open(args.defects, 'r', encoding='utf-8') as f:
+                defects = json.load(f)
+        else:
+            defects = json.loads(args.defects)
+
+    # 执行修复
+    report = fix_overflow_defects(args.tex_file, defects)
+
+    if args.json:
+        print(json.dumps(report.to_dict(), indent=2, ensure_ascii=False))
+    else:
+        print(f"\nOverflow Fix Report")
+        print("=" * 50)
+        print(f"Status: {report.status}")
+        print(f"Modified files: {report.modified_files}")
+        print(f"Changes: {len(report.changes)}")
+        for change in report.changes:
+            print(f"  - [{change.defect_id}] {change.object_name}: {change.action}")
+        if report.unresolved:
+            print(f"\nUnresolved: {len(report.unresolved)}")
+            for u in report.unresolved:
+                print(f"  - {u}")
+
+
+if __name__ == "__main__":
+    main()