workflow-loop 0.1.0__py3-none-any.whl

workflow_loop/__init__.py

@@ -0,0 +1,6 @@
+# 包版本号，用于 pip/uv 安装时版本匹配
+__version__ = "0.1.0"
+# 产品身份标识：workflow --version 输出、安装脚本身份核对和安装事务校验共用同一组常量
+# 本次发布版本为 0.1.0；后续发布使用尚未被 PyPI 占用的新版本号
+PRODUCT_NAME = "workflow-loop"
+PRODUCT_IDENTITY = f"{PRODUCT_NAME} {__version__}"

workflow_loop/acceptance_records.py

@@ -0,0 +1,338 @@
+"""主题验收的结构化记录和当前有效性检查。"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import asdict
+
+from . import artifact_paths as artifact_paths_mod
+from . import state as state_mod
+from .test_mapping import TestPlanItem, parse_test_plan_items
+from .topic import topic_paths
+from .topic_relations import read_topic_index
+
+
+ACCEPTANCE_METHODS = {"自动化测试", "人工验收", "自动化测试 + 人工验收"}
+RESULT_CHOICES = {"passed", "failed", "blocked"}
+
+
+def compute_record_id(record: state_mod.AcceptanceCriterionRecord) -> str:
+    payload = asdict(record)
+    payload["record_id"] = None
+    encoded = json.dumps(payload, ensure_ascii=False, sort_keys=True).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def _criterion_groups(project_root: str, topic: str) -> dict[str, list[TestPlanItem]]:
+    groups: dict[str, list[TestPlanItem]] = {}
+    for item in parse_test_plan_items(project_root, topic):
+        groups.setdefault(item.criterion_id, []).append(item)
+    return groups
+
+
+def criterion_methods(project_root: str, topic: str) -> dict[str, str]:
+    """按一条 AC 的全部测试项归并最终验收方式。"""
+    methods: dict[str, str] = {}
+    for criterion_id, items in _criterion_groups(project_root, topic).items():
+        item_methods = {item.test_method for item in items}
+        if item_methods == {"自动化测试"}:
+            method = "自动化测试"
+        elif item_methods == {"人工验收"}:
+            method = "人工验收"
+        else:
+            method = "自动化测试 + 人工验收"
+        methods[criterion_id] = method
+    return methods
+
+
+def criterion_names(project_root: str, topic: str) -> dict[str, str]:
+    return {
+        criterion_id: items[0].criterion_name
+        for criterion_id, items in _criterion_groups(project_root, topic).items()
+    }
+
+
+def automated_test_ids(project_root: str, topic: str, criterion_id: str) -> list[str]:
+    return [
+        item.test_id
+        for item in _criterion_groups(project_root, topic).get(criterion_id, [])
+        if item.requires_test_code
+    ]
+
+
+def record_is_current(
+    record: state_mod.AcceptanceCriterionRecord,
+    wf_state: state_mod.WorkflowState,
+) -> bool:
+    """判断当前主题记录是否仍被程序保留为有效。
+
+    上游全局哈希只用于发现变化和触发清理，不能直接拿来让所有主题一起失效。
+    用户只退回一个主题时，程序已经清理该主题及其依赖主题；没有被清理的独立
+    主题应继续保留当前验收记录。
+
+    自动化或混合记录还必须逐项指向当前任务的精确机器记录编号；
+    执行记录被替换后，旧验收记录不能继续通过。旧记录缺少编号时同样失效。
+    """
+    if record.result != "passed" or record.record_id != compute_record_id(record):
+        return False
+    if record.method in ("自动化测试", "自动化测试 + 人工验收") and record.test_ids:
+        tasks = wf_state.stages.get(
+            "test_execution",
+            state_mod.StageState(),
+        ).test_tasks.get(record.topic, {})
+        current_ids: list[str] = []
+        for test_id in record.test_ids:
+            task = tasks.get(test_id)
+            if (
+                task is None
+                or task.current_record is None
+                or task.current_record.status != "passed"
+                or not task.current_record.record_id
+            ):
+                return False
+            current_ids.append(task.current_record.record_id)
+        if not record.test_record_ids:
+            return False
+        if sorted(current_ids) != sorted(record.test_record_ids):
+            return False
+    return True
+
+
+def _automated_items_are_current(
+    wf_state: state_mod.WorkflowState,
+    topic: str,
+    test_ids: list[str],
+) -> tuple[bool, str, list[str]]:
+    """核对每个测试项当前机器记录有效，并返回精确记录编号列表。"""
+    stage_state = wf_state.stages.get("test_execution")
+    if stage_state is None:
+        return False, "缺少 test_execution（测试执行阶段）状态", []
+    tasks = stage_state.test_tasks.get(topic, {})
+    record_ids: list[str] = []
+    for test_id in test_ids:
+        task = tasks.get(test_id)
+        if task is None or task.status != "passed" or task.current_record is None:
+            return False, f"{topic} / {test_id} 没有当前有效的通过记录", []
+        record = task.current_record
+        if record.status != "passed" or record.exit_code != 0:
+            return False, f"{topic} / {test_id} 当前测试记录不是通过状态", []
+        if not record.record_id:
+            return False, f"{topic} / {test_id} 的执行记录缺少机器记录编号，必须重新执行", []
+        record_ids.append(record.record_id)
+    return True, "", record_ids
+
+
+def _topic_relations(project_root: str, wf_state: state_mod.WorkflowState):
+    return read_topic_index(
+        project_root,
+        artifact_paths_mod.ACCEPTANCE_INDEX_DOC,
+        wf_state.workflow_id,
+        ["展示顺序", "验收主题", "前置主题", "验收计划", "主题验收结果"],
+    )
+
+
+def topic_records_complete(
+    project_root: str,
+    wf_state: state_mod.WorkflowState,
+    topic: str,
+) -> bool:
+    methods = criterion_methods(project_root, topic)
+    records = wf_state.stages.get(
+        "topic_acceptance",
+        state_mod.StageState(),
+    ).acceptance_records.get(topic, {})
+    return bool(methods) and set(records) == set(methods) and all(
+        records[criterion_id].method == method
+        and record_is_current(records[criterion_id], wf_state)
+        for criterion_id, method in methods.items()
+    )
+
+
+def incomplete_prerequisites(
+    project_root: str,
+    wf_state: state_mod.WorkflowState,
+    topic: str,
+) -> list[str]:
+    relations = {relation.topic: relation for relation in _topic_relations(project_root, wf_state)}
+    relation = relations.get(topic)
+    if relation is None:
+        return [f"验收索引缺少主题：{topic}"]
+    return [
+        prerequisite
+        for prerequisite in relation.prerequisites
+        if not topic_records_complete(project_root, wf_state, prerequisite)
+    ]
+
+
+def ensure_automated_records(
+    project_root: str,
+    wf_state: state_mod.WorkflowState,
+) -> list[state_mod.AcceptanceCriterionRecord]:
+    """为纯自动化 AC 建立当前有效记录，不替代人工验收。"""
+    stage_state = wf_state.stages.get("topic_acceptance")
+    if stage_state is None:
+        return []
+    created: list[state_mod.AcceptanceCriterionRecord] = []
+    for relation in _topic_relations(project_root, wf_state):
+        if incomplete_prerequisites(project_root, wf_state, relation.topic):
+            continue
+        methods = criterion_methods(project_root, relation.topic)
+        topic_records = stage_state.acceptance_records.setdefault(relation.topic, {})
+        for criterion_id, method in methods.items():
+            if method != "自动化测试":
+                continue
+            existing = topic_records.get(criterion_id)
+            if existing is not None and record_is_current(existing, wf_state):
+                continue
+            test_ids = automated_test_ids(project_root, relation.topic, criterion_id)
+            current, detail, machine_record_ids = _automated_items_are_current(
+                wf_state,
+                relation.topic,
+                test_ids,
+            )
+            if not current:
+                continue
+            record = state_mod.AcceptanceCriterionRecord(
+                topic=relation.topic,
+                criterion_id=criterion_id,
+                method=method,
+                result="passed",
+                actual_result=f"对应自动化测试项均有当前有效通过记录：{', '.join(test_ids)}",
+                user_answer=None,
+                evidence=topic_paths(project_root, relation.topic)["test_result"],
+                confirmed_at=state_mod.now_iso(),
+                acceptance_plan_hash=wf_state.verification.acceptance_plan_hash,
+                impl_hash=wf_state.verification.impl_hash,
+                test_result_hash=wf_state.verification.test_result_hash,
+                test_ids=test_ids,
+                test_record_ids=machine_record_ids,
+            )
+            record.record_id = compute_record_id(record)
+            topic_records[criterion_id] = record
+            created.append(record)
+    return created
+
+
+def record_user_result(
+    project_root: str,
+    wf_state: state_mod.WorkflowState,
+    *,
+    topic: str,
+    criterion_id: str,
+    result: str,
+    actual_result: str,
+    user_answer: str,
+    evidence: str,
+) -> state_mod.AcceptanceCriterionRecord:
+    if result not in RESULT_CHOICES:
+        raise ValueError(f"验收结果必须是 {sorted(RESULT_CHOICES)}")
+    if topic not in wf_state.topics:
+        raise ValueError(f"主题不属于当前工作流：{topic}")
+    methods = criterion_methods(project_root, topic)
+    method = methods.get(criterion_id)
+    if method is None:
+        raise ValueError(f"{topic} 没有验收条件 {criterion_id}")
+    if method == "自动化测试":
+        raise ValueError(f"{topic} / {criterion_id} 是纯自动化条件，不需要用户重复确认")
+    prerequisites = incomplete_prerequisites(project_root, wf_state, topic)
+    if prerequisites:
+        raise ValueError(f"前置主题尚未验收通过：{prerequisites}")
+    test_ids = automated_test_ids(project_root, topic, criterion_id)
+    machine_record_ids: list[str] = []
+    if method == "自动化测试 + 人工验收":
+        current, detail, machine_record_ids = _automated_items_are_current(
+            wf_state,
+            topic,
+            test_ids,
+        )
+        if not current:
+            raise ValueError(detail)
+    if not actual_result.strip():
+        raise ValueError("必须记录用户实际观察到的结果")
+    if not user_answer.strip():
+        raise ValueError("必须记录用户实际回答")
+
+    record = state_mod.AcceptanceCriterionRecord(
+        topic=topic,
+        criterion_id=criterion_id,
+        method=method,
+        result=result,
+        actual_result=actual_result.strip(),
+        user_answer=user_answer.strip(),
+        evidence=evidence.strip() or actual_result.strip(),
+        confirmed_at=state_mod.now_iso(),
+        acceptance_plan_hash=wf_state.verification.acceptance_plan_hash,
+        impl_hash=wf_state.verification.impl_hash,
+        test_result_hash=wf_state.verification.test_result_hash,
+        test_ids=test_ids,
+        test_record_ids=machine_record_ids,
+    )
+    record.record_id = compute_record_id(record)
+    stage_state = wf_state.stages["topic_acceptance"]
+    if result == "passed":
+        stage_state.acceptance_records.setdefault(topic, {})[criterion_id] = record
+    else:
+        stage_state.acceptance_records.pop(topic, None)
+        result_path = os.path.join(
+            project_root,
+            topic_paths(project_root, topic)["acceptance_result"],
+        )
+        if os.path.isfile(result_path):
+            os.remove(result_path)
+    return record
+
+
+def clear_topic_records(
+    project_root: str,
+    wf_state: state_mod.WorkflowState,
+    topics: list[str],
+) -> None:
+    stage_state = wf_state.stages.get("topic_acceptance")
+    if stage_state is not None:
+        for topic in topics:
+            stage_state.acceptance_records.pop(topic, None)
+    for topic in topics:
+        result_path = os.path.join(
+            project_root,
+            topic_paths(project_root, topic)["acceptance_result"],
+        )
+        if os.path.isfile(result_path):
+            os.remove(result_path)
+
+
+def acceptance_records_payload(
+    wf_state: state_mod.WorkflowState,
+    topics: list[str],
+) -> dict:
+    stage_state = wf_state.stages.get("topic_acceptance")
+    records = stage_state.acceptance_records if stage_state is not None else {}
+    return {
+        topic: {
+            criterion_id: asdict(record)
+            for criterion_id, record in sorted(records.get(topic, {}).items())
+        }
+        for topic in topics
+    }
+
+
+def acceptance_progress(
+    project_root: str,
+    wf_state: state_mod.WorkflowState,
+) -> list[str]:
+    lines: list[str] = []
+    stage_state = wf_state.stages.get("topic_acceptance", state_mod.StageState())
+    for topic in wf_state.topics:
+        methods = criterion_methods(project_root, topic)
+        records = stage_state.acceptance_records.get(topic, {})
+        remaining = [
+            criterion_id
+            for criterion_id in methods
+            if criterion_id not in records or not record_is_current(records[criterion_id], wf_state)
+        ]
+        if remaining:
+            lines.append(f"{topic}: 待验收 {remaining}")
+        else:
+            lines.append(f"{topic}: 验收条件已全部通过，待生成或复核主题结果文件")
+    return lines

workflow_loop/artifact_paths.py

@@ -0,0 +1,278 @@
+"""正式产物路径的唯一来源。
+
+所有阶段、校验、哈希、追踪、清理和恢复代码都只能调用本模块取得正式产物路径，
+不能自行拼接后缀。面向用户的正式产物固定使用中文文件名；`spec`、`acceptance`、
+`qa`、`impl`、`bug` 等程序固定目录名保持英文。
+
+显示名称与文件标识分离：功能、主题、穿刺项和缺陷在文档标题与正文中保留用户
+确认的完整中文显示名称；进入文件名时使用稳定的中文文件标识。已有映射保存在
+`.workflow_loop/project.json` 的 `artifact_file_keys` 中，后续阶段读取已保存的
+对应关系，不重新猜测。
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import unicodedata
+
+# ─── 固定正式产物路径（相对项目根） ───
+PRODUCT_OVERVIEW_DOC = "spec/产品总说明.md"
+CODE_DESIGN_DOC = "spec/代码架构设计.md"
+DESIGN_INIT_EVIDENCE_DOC = "spec/项目设计初始化证据.md"
+SPIKE_INDEX_DOC = "spec/穿刺清单.md"
+ACCEPTANCE_INDEX_DOC = "acceptance/索引.md"
+QA_INDEX_DOC = "qa/索引.md"
+IMPL_INDEX_DOC = "impl/索引.md"
+BUG_INDEX_DOC = "bug/索引.md"
+TRACEABILITY_DOC = "需求交付追踪表.md"
+
+# 文件标识分类：功能、验收主题、穿刺项、缺陷
+FILE_KEY_CATEGORIES = ("feature", "topic", "spike", "bug")
+
+# 文件标识允许的字符：中文、英文字母、数字、下划线和连字符
+_ALLOWED_CHAR = re.compile(r"[A-Za-z0-9_\-一-鿿㐀-䶿]")
+# 文件标识长度上限（字符数），避免超出各平台路径限制
+MAX_FILE_KEY_LENGTH = 80
+# Windows 保留名称（大小写不敏感；文件标识必须避开）
+_WINDOWS_RESERVED = {
+    "CON", "PRN", "AUX", "NUL",
+    *{f"COM{i}" for i in range(1, 10)},
+    *{f"LPT{i}" for i in range(1, 10)},
+}
+
+
+def make_file_key(display_name: str) -> str:
+    """把显示名称清理成跨平台安全的中文文件标识（纯函数，不查映射）。
+
+    只保留中文字符、英文字母、数字、下划线和连字符；空格、斜杠、反斜杠、冒号、
+    问号、引号、换行和其它标点统一替换为单个下划线；去掉开头与结尾的点、空格、
+    下划线并限制长度；避开 Windows 保留名称。无法得到安全标识时抛 ValueError。
+    """
+    if display_name is None:
+        raise ValueError("显示名称不能为空")
+    # Unicode 规范化：同一个视觉名称在不同输入法下得到同一标识
+    normalized = unicodedata.normalize("NFC", str(display_name))
+
+    pieces: list[str] = []
+    previous_was_placeholder = False
+    for char in normalized:
+        if _ALLOWED_CHAR.fullmatch(char):
+            pieces.append(char)
+            previous_was_placeholder = False
+        else:
+            # 连续的非法字符只折叠成一个下划线
+            if not previous_was_placeholder:
+                pieces.append("_")
+            previous_was_placeholder = True
+    key = "".join(pieces)
+    # 去掉开头与结尾的点、空格和下划线
+    key = key.strip("._ \t")
+    # 限制长度后再清理一次结尾
+    key = key[:MAX_FILE_KEY_LENGTH].strip("._ \t")
+    if not key:
+        raise ValueError(f"显示名称无法生成安全文件标识: {display_name!r}")
+    if key.upper() in _WINDOWS_RESERVED:
+        # 保留名称追加下划线避开，例如 CON → CON_
+        key = key + "_"
+    return key
+
+
+def resolve_file_key(
+    saved_keys: dict[str, str],
+    all_used_keys: set[str],
+    display_name: str,
+) -> str:
+    """在一个分类内解析显示名称的文件标识。
+
+    saved_keys 是该分类已保存的 显示名称→文件标识 映射；all_used_keys 是全部
+    分类已占用的标识（大小写不敏感比较，避免只在大小写上不同的路径冲突）。
+    已保存的名称直接返回旧标识；新名称生成标识，冲突时依次追加 `_2`、`_3`。
+    """
+    if display_name in saved_keys:
+        return saved_keys[display_name]
+    base_key = make_file_key(display_name)
+    used_lower = {key.lower() for key in all_used_keys}
+    candidate = base_key
+    suffix = 2
+    while candidate.lower() in used_lower:
+        candidate = f"{base_key}_{suffix}"
+        suffix += 1
+    return candidate
+
+
+def register_file_keys(project, category: str, display_names: list[str]) -> dict[str, str]:
+    """把一批显示名称的文件标识登记进项目状态（不落盘，调用方负责保存）。
+
+    拒绝两类漂移：同一显示名称改绑到另一标识；一个标识被另一显示名称占用。
+    返回本次新增的 显示名称→文件标识。
+    """
+    if category not in FILE_KEY_CATEGORIES:
+        raise ValueError(f"未知文件标识分类: {category}")
+    keys = project.artifact_file_keys.setdefault(category, {})
+    all_used = {
+        key
+        for mapping in project.artifact_file_keys.values()
+        for key in mapping.values()
+    }
+    reverse = {key: name for name, key in keys.items()}
+    added: dict[str, str] = {}
+    for display_name in display_names:
+        if display_name in keys:
+            continue
+        key = resolve_file_key(keys, all_used, display_name)
+        owner = reverse.get(key)
+        if owner is not None and owner != display_name:
+            raise ValueError(
+                f"文件标识 {key!r} 已被显示名称 {owner!r} 占用，不能再分配给 {display_name!r}"
+            )
+        keys[display_name] = key
+        reverse[key] = display_name
+        all_used.add(key)
+        added[display_name] = key
+    return added
+
+
+def lookup_file_key(project, category: str, display_name: str) -> str | None:
+    """读取已保存的文件标识；没有登记时返回 None。"""
+    if project is None:
+        return None
+    return project.artifact_file_keys.get(category, {}).get(display_name)
+
+
+def resolve_key_for(project, category: str, display_name: str) -> str:
+    """取得显示名称的稳定文件标识：优先已保存映射，否则确定性生成（不保存）。"""
+    saved = project.artifact_file_keys.get(category, {}) if project is not None else {}
+    all_used = (
+        {
+            key
+            for mapping in project.artifact_file_keys.values()
+            for key in mapping.values()
+        }
+        if project is not None
+        else set()
+    )
+    return resolve_file_key(saved, all_used, display_name)
+
+
+# ─── 按文件标识生成动态正式产物路径 ───
+
+
+def feature_doc(file_key: str) -> str:
+    return f"spec/功能_{file_key}.md"
+
+
+def spike_doc(file_key: str) -> str:
+    return f"spec/穿刺_{file_key}.md"
+
+
+def bug_doc(file_key: str) -> str:
+    return f"bug/缺陷_{file_key}.md"
+
+
+def topic_acceptance_plan(file_key: str) -> str:
+    return f"acceptance/{file_key}_验收计划.md"
+
+
+def topic_acceptance_result(file_key: str) -> str:
+    return f"acceptance/{file_key}_验收结果.md"
+
+
+def topic_test_plan(file_key: str) -> str:
+    return f"qa/{file_key}_测试计划.md"
+
+
+def topic_test_result(file_key: str) -> str:
+    return f"qa/{file_key}_测试结果.md"
+
+
+def topic_impl_doc(file_key: str) -> str:
+    return f"impl/{file_key}_实施记录.md"
+
+
+def managed_artifact_paths(project, wf_state=None, project_root: str | None = None) -> list[str]:
+    """列出工作流拥有的正式产物路径，不把目录中的任意 Markdown 算进来。
+
+    固定文档、项目中已经登记的文件标识、当前主题，以及磁盘上使用工作流保留
+    命名格式的文件都属于受管范围。最后一类用于覆盖“文档已经创建、第三道门尚未
+    登记文件标识就作废”的真实场景；`spec/notes.md` 之类用户自有文件不会命中。
+
+    project 可以是 ``ProjectState``，也可以为 None。wf_state 只读取 topics/topic，
+    因此旧状态和当前状态都可安全传入。
+    """
+    paths = {
+        PRODUCT_OVERVIEW_DOC,
+        CODE_DESIGN_DOC,
+        DESIGN_INIT_EVIDENCE_DOC,
+        SPIKE_INDEX_DOC,
+        ACCEPTANCE_INDEX_DOC,
+        QA_INDEX_DOC,
+        IMPL_INDEX_DOC,
+        BUG_INDEX_DOC,
+        TRACEABILITY_DOC,
+    }
+
+    mappings = getattr(project, "artifact_file_keys", {}) if project is not None else {}
+    for file_key in mappings.get("feature", {}).values():
+        paths.add(feature_doc(file_key))
+    for file_key in mappings.get("spike", {}).values():
+        paths.add(spike_doc(file_key))
+    for file_key in mappings.get("bug", {}).values():
+        paths.add(bug_doc(file_key))
+    for file_key in mappings.get("topic", {}).values():
+        paths.update(
+            {
+                topic_acceptance_plan(file_key),
+                topic_acceptance_result(file_key),
+                topic_test_plan(file_key),
+                topic_test_result(file_key),
+                topic_impl_doc(file_key),
+            }
+        )
+
+    topics = list(getattr(wf_state, "topics", []) or []) if wf_state is not None else []
+    legacy_topic = getattr(wf_state, "topic", None) if wf_state is not None else None
+    if not topics and legacy_topic:
+        topics = [legacy_topic]
+    for topic in topics:
+        file_key = resolve_key_for(project, "topic", topic)
+        paths.update(
+            {
+                topic_acceptance_plan(file_key),
+                topic_acceptance_result(file_key),
+                topic_test_plan(file_key),
+                topic_test_result(file_key),
+                topic_impl_doc(file_key),
+            }
+        )
+
+    # 保留命名格式是工作流的正式命名空间。只接纳普通文件名，不递归扫描目录，
+    # 从而不会把用户自己的说明、样本或笔记纳入整轮恢复。
+    reserved_patterns = {
+        "spec": (
+            re.compile(r"^功能_[A-Za-z0-9_\-一-鿿㐀-䶿]+\.md$"),
+            re.compile(r"^穿刺_[A-Za-z0-9_\-一-鿿㐀-䶿]+\.md$"),
+        ),
+        "acceptance": (
+            re.compile(r"^[A-Za-z0-9_\-一-鿿㐀-䶿]+_(?:验收计划|验收结果)\.md$"),
+        ),
+        "qa": (
+            re.compile(r"^[A-Za-z0-9_\-一-鿿㐀-䶿]+_(?:测试计划|测试结果)\.md$"),
+        ),
+        "impl": (
+            re.compile(r"^[A-Za-z0-9_\-一-鿿㐀-䶿]+_实施记录\.md$"),
+        ),
+        "bug": (
+            re.compile(r"^缺陷_[A-Za-z0-9_\-一-鿿㐀-䶿]+\.md$"),
+        ),
+    }
+    if isinstance(project_root, str):
+        for directory, patterns in reserved_patterns.items():
+            full_dir = os.path.join(project_root, directory)
+            if not os.path.isdir(full_dir):
+                continue
+            for filename in os.listdir(full_dir):
+                if any(pattern.fullmatch(filename) for pattern in patterns):
+                    paths.add(f"{directory}/{filename}")
+
+    return sorted(paths)