From 75f89d91553a339d6d1a28795c8e9705e25d3b4d Mon Sep 17 00:00:00 2001 From: shen Date: Thu, 29 Oct 2026 21:17:55 +0800 Subject: [PATCH] feat: add cancellable document checks with source navigation --- docs/architecture.md | 4 ++ mdhelper/doc_check.py | 78 +++++++++++++++++++++++------- mdhelper/document_check_dialog.py | 78 ++++++++++++++++++++++++++++++ mdhelper/main_window.py | 62 ++++++++++++++++++++++++ tests/test_document_check_panel.py | 47 ++++++++++++++++++ 5 files changed, 252 insertions(+), 17 deletions(-) create mode 100644 mdhelper/document_check_dialog.py create mode 100644 tests/test_document_check_panel.py diff --git a/docs/architecture.md b/docs/architecture.md index 0c57762..b86e58f 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -50,3 +50,7 @@ MHTML 的浏览器加载与归档转换分开。`mhtml_archive.py` 分别处理 每个重构阶段独立提交。运行单元测试,并按改动范围运行 `gui_smoke.py`、`improvements_smoke.py` 和 `reliability_smoke.py`。涉及浏览器生命周期的调整必须检查欢迎页、首次打开文件、标签切换以及预览滚动;涉及保存的调整必须检查保存失败、取消、另存为和后台标签。 `startup_smoke.py` 验证从启动到首次打开文件只有一次主窗口显示、没有隐藏或窗口句柄变化,阅读器保持固定父容器。设置 `MDHELPER_SMOKE_NATIVE=1` 可在真实 Windows 窗口后端执行。`pdf_export_smoke.py` 检查实际 PDF 输出。 +# 文档检查 + +`doc_check.py` 使用统一资源分析器检查全项目本地引用和实际渲染锚点;调用者可传入编辑器快照、取消信号和进度回调。`document_check_dialog.py` 只在用户打开时启动后台扫描,通过主窗口的源码定位入口打开结果,不参与启动流程。 + diff --git a/mdhelper/doc_check.py b/mdhelper/doc_check.py index c9ef26b..7f4ac1b 100644 --- a/mdhelper/doc_check.py +++ b/mdhelper/doc_check.py @@ -3,7 +3,10 @@ from __future__ import annotations import argparse from dataclasses import dataclass from pathlib import Path +from html.parser import HTMLParser +from urllib.parse import unquote, urlsplit from .document_resources import analyze_document, resolve_local_reference +from .document_tree import discover_documents @dataclass(frozen=True) @@ -16,33 +19,58 @@ class LinkIssue: def discover_markdown_files(project_root: Path) -> list[Path]: - files: set[Path] = set() - - for pattern in ("*.md", "*.markdown"): - files.update(path.resolve() for path in project_root.glob(pattern) if path.is_file()) - - docs_root = project_root / "docs" - if docs_root.exists(): - for pattern in ("*.md", "*.markdown"): - files.update(path.resolve() for path in docs_root.rglob(pattern) if path.is_file()) - - return sorted(files) + return [entry.path for entry in discover_documents(project_root, ("markdown",))] -def check_documents(project_root: Path) -> list[LinkIssue]: +def check_documents(project_root: Path, sources=None, cancel=None, progress=None) -> list[LinkIssue]: root = project_root.resolve() issues: list[LinkIssue] = [] + cache, sources = {}, sources or {} for markdown_path in discover_markdown_files(root): - issues.extend(check_markdown_file(markdown_path)) + from .export_jobs import check_cancelled + check_cancelled(cancel) + if progress: + progress(f"正在检查:{markdown_path.relative_to(root)}") + issues.extend(check_markdown_file(markdown_path, sources=sources, cache=cache)) return issues -def check_markdown_file(markdown_path: Path) -> list[LinkIssue]: +class _HtmlAnchors(HTMLParser): + def __init__(self): + super().__init__() + self.anchors = set() + + def handle_starttag(self, tag, attrs): + for name, value in attrs: + if value and (name == "id" or (name == "name" and tag == "a")): + self.anchors.add(value) + + +def document_anchors(analysis) -> set[str]: + parser = _HtmlAnchors() + anchors = set() + for token in analysis.tokens: + if token.attrGet("id"): + anchors.add(token.attrGet("id")) + for item in [token, *(token.children or [])]: + if item.type in {"html_inline", "html_block"}: + parser.feed(item.content) + return anchors | parser.anchors + + +def check_markdown_file(markdown_path: Path, *, sources=None, cache=None) -> list[LinkIssue]: issues: list[LinkIssue] = [] + sources = sources or {} + cache = {} if cache is None else cache + def load(path): + if path not in cache: + text = sources[path] if path in sources else path.read_text(encoding="utf-8-sig") + cache[path] = analyze_document(text) + return cache[path] try: - source = markdown_path.read_text(encoding="utf-8") + analysis = load(markdown_path) except (OSError, UnicodeDecodeError) as error: return [ LinkIssue( @@ -54,10 +82,26 @@ def check_markdown_file(markdown_path: Path) -> list[LinkIssue]: ) ] - for reference in analyze_document(source).references: - resolved = resolve_local_reference(markdown_path, reference.url) + for reference in analysis.references: + try: + url = urlsplit(reference.url) + resolved = resolve_local_reference(markdown_path, reference.url) + except ValueError: + issues.append(LinkIssue(markdown_path, reference.line, reference.url, markdown_path, "链接格式无效")) + continue if resolved is not None and not resolved.exists(): issues.append(LinkIssue(markdown_path, reference.line, reference.url, resolved, "本地目标不存在")) + continue + if reference.image or not url.fragment or url.scheme not in {"", "file"} or url.netloc and url.scheme != "file": + continue + target = resolved or markdown_path + if target.suffix.lower() not in {".md", ".markdown", ".html", ".htm", ".xhtml"} or not target.is_file(): + continue + try: + if unquote(url.fragment) not in document_anchors(load(target)): + issues.append(LinkIssue(markdown_path, reference.line, reference.url, target, "章节锚点不存在")) + except (OSError, UnicodeError): + issues.append(LinkIssue(markdown_path, reference.line, reference.url, target, "无法读取链接目标")) return issues diff --git a/mdhelper/document_check_dialog.py b/mdhelper/document_check_dialog.py new file mode 100644 index 0000000..fac70cf --- /dev/null +++ b/mdhelper/document_check_dialog.py @@ -0,0 +1,78 @@ +"""On-demand project validation; workers never read widgets or settings.""" +from PySide6.QtCore import QThreadPool, Qt, Slot +from PySide6.QtWidgets import QDialog, QHBoxLayout, QLabel, QPushButton, QTreeWidget, QTreeWidgetItem, QVBoxLayout +from .doc_check import check_documents +from .export_jobs import ExportJob + + +class DocumentCheckDialog(QDialog): + def __init__(self, parent, root, sources, navigate): + super().__init__(parent) + self.root, self.sources, self.navigate = root, sources, navigate + self.job = None + self.closed = False + self.setWindowTitle("文档检查") + self.resize(1000, 600) + layout = QVBoxLayout(self) + layout.addWidget(QLabel(f"检查文件夹:{root}\n使用当前已打开编辑器的内容。双击问题可定位源码。")) + self.results = QTreeWidget() + self.results.setHeaderLabels(["文件", "行", "问题", "目标"]) + self.results.setColumnWidth(0, 230) + self.results.setColumnWidth(1, 45) + self.results.setColumnWidth(2, 170) + self.results.itemActivated.connect(self.open_issue) + layout.addWidget(self.results) + self.status = QLabel() + layout.addWidget(self.status) + actions = QHBoxLayout() + self.scan_button, self.cancel_button = QPushButton("重新检查"), QPushButton("停止检查") + close = QPushButton("关闭") + self.scan_button.clicked.connect(self.start) + self.cancel_button.clicked.connect(self.cancel) + close.clicked.connect(self.close) + for button in (self.scan_button, self.cancel_button, close): actions.addWidget(button) + layout.addLayout(actions) + self.start() + + def start(self): + if self.job is not None: + return + self.results.clear() + self.scan_button.setEnabled(False) + self.cancel_button.setEnabled(True) + snapshot = dict(self.sources()) + self.job = ExportJob(lambda cancel, progress: check_documents(self.root, snapshot, cancel, progress)) + self.job.signals.progress.connect(self.status.setText) + self.job.signals.finished.connect(self.finished_scan) + QThreadPool.globalInstance().start(self.job) + + @Slot(object, str) + def finished_scan(self, issues, error): + cancelled = self.job is not None and self.job.cancel.is_set() + self.job = None + if self.closed: + return + self.scan_button.setEnabled(True) + self.cancel_button.setEnabled(False) + if cancelled or error: + self.status.setText("已停止检查" if cancelled else f"检查失败:{error}") + return + for issue in issues or []: + item = QTreeWidgetItem([str(issue.source.relative_to(self.root)), str(issue.line_number), issue.message, issue.target]) + item.setData(0, Qt.ItemDataRole.UserRole, issue) + self.results.addTopLevelItem(item) + self.status.setText(f"检查完成,发现 {len(issues or [])} 个问题。" if issues else "检查完成,未发现失效链接、缺失图片或无效章节锚点。") + + def open_issue(self, item, column=0): + issue = item.data(0, Qt.ItemDataRole.UserRole) + if issue: + self.navigate(issue.source, issue.line_number) + + def cancel(self): + if self.job is not None: + self.job.cancel.set() + + def closeEvent(self, event): + self.closed = True + self.cancel() + super().closeEvent(event) diff --git a/mdhelper/main_window.py b/mdhelper/main_window.py index 57f74bf..d572cd9 100644 --- a/mdhelper/main_window.py +++ b/mdhelper/main_window.py @@ -446,6 +446,10 @@ class MainWindow(QMainWindow): self.settings_action.triggered.connect(self.open_settings_dialog) self.tools_menu.addAction(self.settings_action) + self.check_documents_action = QAction("检查文档链接与图片", self) + self.check_documents_action.triggered.connect(self.show_document_check) + self.tools_menu.addAction(self.check_documents_action) + self.manage_external_apps_action = QAction("管理外部打开程序", self) self.manage_external_apps_action.triggered.connect(self.manage_external_applications) self.tools_menu.addAction(self.manage_external_apps_action) @@ -3758,10 +3762,65 @@ class MainWindow(QMainWindow): self._scroll_to_position(self.pending_scroll_y) self.pending_scroll_y = None + def _editor_sources(self) -> dict[Path, str]: + return {widget.session.path.resolve(): widget.source_text() + for index in range(self.tabs.count()) + if isinstance((widget := self.tabs.widget(index)), RichMarkdownEditorDialog)} + + def show_document_check(self) -> None: + if not self.has_project: + return + existing = getattr(self, "_document_check_dialog", None) + if existing is not None and existing.isVisible(): + existing.raise_() + existing.activateWindow() + return + from .document_check_dialog import DocumentCheckDialog + self._document_check_dialog = DocumentCheckDialog( + self, self.project_root, self._editor_sources, self._open_source_location) + self._document_check_dialog.show() + + def _open_source_location(self, path: Path, line: int) -> None: + if not path.is_file(): + QMessageBox.warning(self, "无法定位", "文件已被移动或删除。") + return + if path.suffix.lower() in {".md", ".markdown"}: + index = self._tab_index_for_path(path) + if index >= 0: + self.tabs.setCurrentIndex(index) + else: + self.open_document(path, new_tab=True) + if not isinstance(self.tabs.currentWidget(), RichMarkdownEditorDialog): + self.edit_current_markdown() + widget = self.tabs.currentWidget() + if not isinstance(widget, RichMarkdownEditorDialog): + return + editor = widget.editor + else: + from PySide6.QtWidgets import QPlainTextEdit + dialog = QDialog(self) + dialog.setWindowTitle(f"查看源码(只读)— {path.name}") + dialog.resize(900, 650) + layout = QVBoxLayout(dialog) + editor = QPlainTextEdit(dialog) + editor.setReadOnly(True) + editor.setPlainText(self._read_text_preview(path)) + layout.addWidget(editor) + dialog.show() + self._source_location_dialog = dialog + cursor = editor.textCursor() + block = editor.document().findBlockByNumber(max(0, line - 1)) + if block.isValid(): + cursor.setPosition(block.position()) + editor.setTextCursor(cursor) + editor.ensureCursorVisible() + editor.setFocus() + def _update_actions(self) -> None: history = self._current_history() self.back_action.setEnabled(history.can_go_back) self.forward_action.setEnabled(history.can_go_forward) + self.check_documents_action.setEnabled(self.has_project) if hasattr(self, "new_file_action"): self.new_file_action.setEnabled(self.has_project) if hasattr(self, "edit_current_action"): @@ -4202,6 +4261,9 @@ class MainWindow(QMainWindow): if self.has_project and not self._restoring_workspace: self.workspaces.save(self.project_root, *self._workspace_snapshot()) self.exports.cancel_all() + check_dialog = getattr(self, "_document_check_dialog", None) + if check_dialog is not None: + check_dialog.close() self.watch.reset() self.directory_poll_timer.stop() self._startup_generation += 1 diff --git a/tests/test_document_check_panel.py b/tests/test_document_check_panel.py new file mode 100644 index 0000000..56f71b2 --- /dev/null +++ b/tests/test_document_check_panel.py @@ -0,0 +1,47 @@ +import threading +import time +import pytest +from PySide6.QtCore import QSettings +from mdhelper.doc_check import check_documents +from mdhelper.export_jobs import ExportCancelled +from mdhelper import main_window + + +def test_nested_documents_anchors_and_buffer_snapshot(tmp_path): + folder = tmp_path / 'notes'; folder.mkdir() + source = folder / 'source.md' + target = folder / 'target.md' + target.write_text('# 中文\n\n# 中文\n\nSetext\n------\n', encoding='utf-8') + source.write_text('[a](target.md#%E4%B8%AD%E6%96%87-2)\n[b](target.md#setext)\n[c](#absent)\n![d](lost.png)\n`[ignored](lost.md)`', encoding='utf-8') + page = folder / 'page.html' + page.write_text('okbad', encoding='utf-8') + excluded = tmp_path / 'build'; excluded.mkdir() + (excluded / 'ignore.md').write_text('[bad](gone.md)') + issues = check_documents(tmp_path) + assert [(i.source.name, i.line_number, i.message) for i in issues] == [ + ('page.html', 1, '章节锚点不存在'), ('source.md', 3, '章节锚点不存在'), ('source.md', 4, '本地目标不存在')] + assert not check_documents(tmp_path, {source: '# absent', page: 'ok'}) + cancel = threading.Event(); cancel.set() + with pytest.raises(ExportCancelled): check_documents(tmp_path, cancel=cancel) + + +def test_panel_scans_and_opens_source_line(qt_application, tmp_path, monkeypatch): + settings = QSettings(str(tmp_path / 'settings.ini'), QSettings.Format.IniFormat) + monkeypatch.setattr(main_window, 'QSettings', lambda *_: settings) + source = tmp_path / 'note.md'; source.write_text('# Note\n\n[broken](gone.md)') + window = main_window.MainWindow(tmp_path) + try: + window.show_document_check() + panel = window._document_check_dialog + deadline = time.monotonic() + 10 + while panel.job is not None and time.monotonic() < deadline: + qt_application.processEvents(); time.sleep(.01) + assert panel.job is None and panel.results.topLevelItemCount() == 1 + panel.open_issue(panel.results.topLevelItem(0)) + editor = window.tabs.currentWidget() + assert editor.session.path == source and editor.editor.textCursor().blockNumber() == 2 + editor.replace_source_undoable('# Buffered\n\n[other](other.md)') + assert window._editor_sources()[source].startswith('# Buffered') + editor.mark_saved(source, editor.source_text(), window._file_signature(source)) + finally: + window.close()