workflow-loop 0.1.0__py3-none-any.whl

workflow_loop/topic.py

@@ -0,0 +1,114 @@
+import os
+import re
+
+from . import artifact_paths as artifact_paths_mod
+from .project import load_project
+from .state import load_state
+from .topic_relations import read_topic_index
+
+
+def topic_file_key(project_root: str, topic: str) -> str:
+    """取得验收主题的稳定文件标识：优先项目映射，缺少时确定性生成（不保存）。
+
+    主题名称是业务标识；文件标识只用于拼路径。文件名清理不改变主题显示名称。
+    """
+    project = load_project(project_root)
+    return artifact_paths_mod.resolve_key_for(project, "topic", topic)
+
+
+def topic_paths(project_root: str, topic: str) -> dict[str, str]:
+    """按统一路径规则返回一个主题的全部正式文档路径（相对项目根）。"""
+    file_key = topic_file_key(project_root, topic)
+    return {
+        "acceptance_plan": artifact_paths_mod.topic_acceptance_plan(file_key),
+        "acceptance_result": artifact_paths_mod.topic_acceptance_result(file_key),
+        "test_plan": artifact_paths_mod.topic_test_plan(file_key),
+        "test_result": artifact_paths_mod.topic_test_result(file_key),
+        "impl_doc": artifact_paths_mod.topic_impl_doc(file_key),
+    }
+
+
+def list_acceptance_index_topics(
+    project_root: str,
+    workflow_id: str | None = None,
+) -> list[str]:
+    """按 acceptance/索引.md 的展示顺序读取验收主题完整显示名称。"""
+
+    state = load_state(project_root)
+    effective_workflow_id = workflow_id or (state.workflow_id if state is not None else None)
+    if effective_workflow_id is None:
+        return []
+    try:
+        relations = read_topic_index(
+            project_root,
+            artifact_paths_mod.ACCEPTANCE_INDEX_DOC,
+            effective_workflow_id,
+        )
+    except ValueError:
+        return []
+    return [relation.topic for relation in relations]
+
+
+def list_reproduce_topics(project_root: str, workflow_id: str | None = None) -> list[str]:
+    """从当前工作流的缺陷复现记录读取验收主题。"""
+    bug_dir = os.path.join(project_root, "bug")
+    if not os.path.isdir(bug_dir):
+        return []
+
+    topics: list[str] = []
+    for filename in sorted(os.listdir(bug_dir)):
+        if (
+            not filename.endswith(".md")
+            or filename == os.path.basename(artifact_paths_mod.BUG_INDEX_DOC)
+        ):
+            continue
+        with open(os.path.join(bug_dir, filename), "r", encoding="utf-8") as f:
+            content = f.read()
+        if workflow_id is not None:
+            workflow_match = re.search(r"^-\s*工作流编号：\s*(.+?)\s*$", content, re.MULTILINE)
+            if workflow_match is None or workflow_match.group(1).strip() != workflow_id:
+                continue
+        topic_match = re.search(r"^-\s*验收主题：\s*(.+?)\s*$", content, re.MULTILINE)
+        if topic_match is not None:
+            topics.append(topic_match.group(1).strip())
+    return topics
+
+
+def current_workflow_topics(project_root: str) -> list[str]:
+    """读取当前 Workflow Run（工作流运行）的主题，兼容旧版单主题状态。"""
+    state = load_state(project_root)
+    if state is None:
+        return []
+    if state.topics:
+        return state.topics
+    return [state.topic] if state.topic else []
+
+
+def candidate_topics(project_root: str) -> list[str]:
+    """返回本次验收计划里的主题：保留当前主题，并接纳未使用过的新主题。"""
+    current = set(current_workflow_topics(project_root))
+    project = load_project(project_root)
+    history = set(project.topic_history if project is not None else [])
+    topics = list_acceptance_index_topics(project_root)
+    return [
+        topic
+        for topic in topics
+        if topic in current or topic not in history
+    ]
+
+
+def missing_topic_documents(
+    project_root: str,
+    kind: str,
+    topics: list[str],
+) -> list[str]:
+    """返回缺失的主题正式文档路径。
+
+    kind 取值：acceptance_plan / acceptance_result / test_plan / test_result / impl_doc。
+    """
+    missing: list[str] = []
+    for topic in topics:
+        relative_path = topic_paths(project_root, topic)[kind]
+        if not os.path.isfile(os.path.join(project_root, relative_path)):
+            missing.append(relative_path)
+    return missing

workflow_loop/topic_relations.py

@@ -0,0 +1,202 @@
+"""读取各阶段索引中的验收主题关系。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+import re
+
+from . import artifact_paths as artifact_paths_mod
+from .project import load_project
+
+
+BASE_INDEX_HEADERS = ["展示顺序", "验收主题", "前置主题"]
+
+
+@dataclass(frozen=True)
+class TopicRelation:
+    """一个验收主题及其前置主题。"""
+
+    order: int
+    topic: str
+    prerequisites: tuple[str, ...]
+    links: dict[str, str]
+
+
+def _workflow_section(content: str, workflow_id: str) -> str:
+    match = re.search(
+        rf"^##\s+{re.escape(workflow_id)}\s*$\n(.*?)(?=^##\s+|\Z)",
+        content,
+        re.MULTILINE | re.DOTALL,
+    )
+    if match is None:
+        raise ValueError(f"索引缺少当前工作流章节: {workflow_id}")
+    return match.group(1)
+
+
+def _table_cells(line: str) -> list[str] | None:
+    stripped = line.strip()
+    if not stripped.startswith("|") or not stripped.endswith("|"):
+        return None
+    cells = [cell.strip() for cell in stripped.strip("|").split("|")]
+    if not cells or all(re.fullmatch(r"[-:]+", cell) for cell in cells):
+        return None
+    return cells
+
+
+def _link_path(cell: str, allowed_text: set[str] | None = None) -> str:
+    if allowed_text is not None and cell.strip() in allowed_text:
+        return cell.strip()
+    match = re.fullmatch(r"\[[^\]]+\]\(([^)]+)\)", cell.strip())
+    if match is None:
+        raise ValueError(f"索引单元格不是单一 Markdown 链接: {cell}")
+    return match.group(1).strip()
+
+
+def _prerequisites(cell: str) -> tuple[str, ...]:
+    value = cell.strip()
+    if value == "无":
+        return ()
+    topics = tuple(part.strip() for part in re.split(r"[、,，]", value) if part.strip())
+    if not topics:
+        raise ValueError("前置主题不能为空；没有依赖时写“无”")
+    return topics
+
+
+def read_topic_index(
+    project_root: str,
+    relative_path: str,
+    workflow_id: str,
+    expected_headers: list[str] | None = None,
+    allowed_text_values: dict[str, set[str]] | None = None,
+) -> list[TopicRelation]:
+    """读取一个主题索引，返回按展示顺序排列的关系。"""
+
+    full_path = os.path.join(project_root, relative_path)
+    if not os.path.isfile(full_path):
+        raise ValueError(f"{relative_path} 不存在")
+    with open(full_path, "r", encoding="utf-8") as stream:
+        section = _workflow_section(stream.read(), workflow_id)
+
+    lines = section.splitlines()
+    header_index = next(
+        (
+            index
+            for index, line in enumerate(lines)
+            if _has_index_headers(_table_cells(line), expected_headers)
+        ),
+        None,
+    )
+    if header_index is None:
+        raise ValueError(f"{relative_path} 缺少主题关系表")
+
+    relations: list[TopicRelation] = []
+    for line in lines[header_index + 1 :]:
+        cells = _table_cells(line)
+        if cells is None:
+            continue
+        headers = _table_cells(lines[header_index])
+        if headers is None or len(cells) != len(headers):
+            raise ValueError(f"{relative_path} 主题关系表列数与表头不一致")
+        try:
+            order = int(cells[0])
+        except ValueError as exc:
+            raise ValueError(f"{relative_path} 展示顺序必须是整数: {cells[0]}") from exc
+
+        allowed_values = allowed_text_values or {}
+        link_cells = {
+            header: _link_path(cells[index], allowed_values.get(header))
+            for index, header in enumerate(headers[3:], start=3)
+        }
+        plan_path = link_cells.get("验收计划")
+        if plan_path is None:
+            raise ValueError(f"{relative_path} 缺少验收计划链接列")
+        # 验收主题以显示名称列为准；文件标识只用于核对链接路径，
+        # 不再从文件名反推业务名称（显示名称与文件标识分离）。
+        topic = cells[1].strip()
+        if not topic:
+            raise ValueError(f"{relative_path} 验收主题不能为空")
+        project = load_project(project_root)
+        expected_key = artifact_paths_mod.resolve_key_for(project, "topic", topic)
+        expected_plan_name = os.path.basename(
+            artifact_paths_mod.topic_acceptance_plan(expected_key)
+        )
+        if os.path.basename(plan_path) != expected_plan_name:
+            raise ValueError(
+                f"{relative_path} 主题“{topic}”的验收计划链接应指向 {expected_plan_name}，"
+                f"实际是 {plan_path}"
+            )
+        relations.append(
+            TopicRelation(
+                order=order,
+                topic=topic,
+                prerequisites=_prerequisites(cells[2]),
+                links=link_cells,
+            )
+        )
+
+    if not relations:
+        raise ValueError(f"{relative_path} 主题关系表没有数据行")
+
+    topics = [relation.topic for relation in relations]
+    if len(topics) != len(set(topics)):
+        raise ValueError(f"{relative_path} 存在重复验收主题")
+    orders = [relation.order for relation in relations]
+    if len(orders) != len(set(orders)):
+        raise ValueError(f"{relative_path} 展示顺序不能重复")
+
+    known = set(topics)
+    order_by_topic = {relation.topic: relation.order for relation in relations}
+    dependencies = {relation.topic: relation.prerequisites for relation in relations}
+    for relation in relations:
+        for prerequisite in relation.prerequisites:
+            if prerequisite not in known:
+                raise ValueError(
+                    f"{relative_path} 主题“{relation.topic}”引用了不存在的前置主题“{prerequisite}”"
+                )
+            if prerequisite == relation.topic:
+                raise ValueError(f"{relative_path} 主题“{relation.topic}”不能依赖自己")
+            if order_by_topic[prerequisite] >= relation.order:
+                raise ValueError(
+                    f"{relative_path} 主题“{relation.topic}”的前置主题“{prerequisite}”必须排在前面"
+                )
+
+    visiting: set[str] = set()
+    visited: set[str] = set()
+
+    def visit(topic: str) -> None:
+        if topic in visiting:
+            raise ValueError(f"{relative_path} 的主题前置关系存在循环")
+        if topic in visited:
+            return
+        visiting.add(topic)
+        for prerequisite in dependencies[topic]:
+            visit(prerequisite)
+        visiting.remove(topic)
+        visited.add(topic)
+
+    for topic in topics:
+        visit(topic)
+    return relations
+
+
+def _has_index_headers(
+    cells: list[str] | None,
+    expected_headers: list[str] | None,
+) -> bool:
+    if cells is None or len(cells) < len(BASE_INDEX_HEADERS) + 2:
+        return False
+    if cells[: len(BASE_INDEX_HEADERS)] != BASE_INDEX_HEADERS:
+        return False
+    return expected_headers is None or cells == expected_headers
+
+
+def relation_signature(
+    relations: list[TopicRelation],
+) -> list[tuple[int, str, tuple[str, ...]]]:
+    """返回用于比较不同阶段主题关系的稳定表示。"""
+
+    return [
+        (relation.order, relation.topic, relation.prerequisites)
+        for relation in relations
+    ]