@harmonyos-arkts/d2h 0.1.11 → 0.1.13

package/skills/d2h-page-spec-generate/scripts/build_batch_report.py

@@ -1,227 +1,227 @@
-#!/usr/bin/env python3
-"""Create the initial batch_report.md from a validated pages.json plan."""
-
-from __future__ import annotations
-
-import argparse
-import hashlib
-import json
-import os
-import sys
-import tempfile
-from datetime import datetime
-from pathlib import Path
-
-
-def sha256(path: Path) -> str:
-    digest = hashlib.sha256()
-    with path.open("rb") as stream:
-        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
-            digest.update(chunk)
-    return digest.hexdigest()
-
-
-def markdown_text(value: object) -> str:
-    return str(value).replace("|", "\\|").replace("\n", " ")
-
-
-def require_int(value: object, where: str) -> int:
-    if not isinstance(value, int) or isinstance(value, bool):
-        raise ValueError(f"{where} must be an integer")
-    return value
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--pages-plan", required=True, type=Path)
-    parser.add_argument("--output-root", required=True, type=Path)
-    args = parser.parse_args()
-
-    pages_plan = args.pages_plan.resolve()
-    output_root = args.output_root.resolve()
-    report_path = output_root / "batch_report.md"
-    if not pages_plan.is_file():
-        raise FileNotFoundError(f"missing page plan: {pages_plan}")
-    if report_path.exists():
-        raise FileExistsError(
-            f"refusing to overwrite existing execution history: {report_path}; update it in place"
-        )
-
-    payload = json.loads(pages_plan.read_text(encoding="utf-8"))
-    if not isinstance(payload, dict) or payload.get("schema_version") != "d2h-page-plan/v1":
-        raise ValueError("pages plan must use schema d2h-page-plan/v1")
-    pages = payload.get("pages")
-    if not isinstance(pages, list) or not pages:
-        raise ValueError("pages plan must contain a non-empty pages array")
-
-    normalized: list[dict[str, object]] = []
-    seen_packages: set[str] = set()
-    seen_page_ids: set[str] = set()
-    for index, page in enumerate(pages):
-        if not isinstance(page, dict):
-            raise ValueError(f"pages[{index}] must be an object")
-        order = require_int(page.get("order"), f"pages[{index}].order")
-        if order != index + 1:
-            raise ValueError(f"pages[{index}].order must be {index + 1}")
-
-        package = page.get("package")
-        page_id = page.get("page_id")
-        if not isinstance(package, str) or not package:
-            raise ValueError(f"pages[{index}].package must be a non-empty string")
-        if Path(package).name != package or not package.startswith(f"page_{order:04d}_"):
-            raise ValueError(
-                f"pages[{index}].package must be a single directory named page_{order:04d}_<name>-<id>"
-            )
-        if package in seen_packages:
-            raise ValueError(f"duplicate package: {package}")
-        seen_packages.add(package)
-        if not isinstance(page_id, str) or not page_id:
-            raise ValueError(f"pages[{index}].page_id must be a non-empty string")
-        if page_id in seen_page_ids:
-            raise ValueError(f"duplicate page_id: {page_id}")
-        seen_page_ids.add(page_id)
-
-        spec_path = output_root / package / "spec.md"
-        if not spec_path.is_file():
-            raise FileNotFoundError(
-                f"all page specs must exist before batch report generation; missing {spec_path}"
-            )
-        package_files = sorted(path.name for path in spec_path.parent.iterdir() if path.is_file())
-        if package_files != ["spec.md"]:
-            raise ValueError(
-                f"page package must contain only spec.md: {spec_path.parent} contains {package_files}"
-            )
-
-        ledger = page.get("decision_ledger")
-        if not isinstance(ledger, dict):
-            raise ValueError(f"pages[{index}].decision_ledger must be an object")
-        dimensions: dict[str, int] = {}
-        for dimension in ("enablement", "ordinary_reachability", "shallowness"):
-            item = ledger.get(dimension)
-            if not isinstance(item, dict):
-                raise ValueError(f"pages[{index}].decision_ledger.{dimension} must be an object")
-            dimensions[dimension] = require_int(
-                item.get("rating"), f"pages[{index}].decision_ledger.{dimension}.rating"
-            )
-
-        normalized.append(
-            {
-                "order": order,
-                "task_id": f"PAGE-{order:04d}",
-                "page_id": page_id,
-                "kind": page.get("kind", "page"),
-                "page_score": require_int(page.get("page_score"), f"pages[{index}].page_score"),
-                "package": package,
-                "page_path": page.get("page_path", []),
-                **dimensions,
-            }
-        )
-
-    created_at = datetime.now().astimezone().isoformat(timespec="seconds")
-    plan_link = Path(os.path.relpath(pages_plan, output_root)).as_posix()
-    lines = [
-        "# 页面开发批次执行记录",
-        "",
-        f"- 页面计划：[pages.json]({plan_link})",
-        f"- 页面计划 SHA-256：`{sha256(pages_plan)}`",
-        f"- 记录创建时间：`{created_at}`",
-        "- 更新规则：后续开发直接更新本文件；不要重新生成或覆盖已有执行历史。",
-        "",
-        "## 状态约定",
-        "",
-        "- 开发状态：`pending | in_progress | implemented | blocked`",
-        "- 构建状态：`not_run | passed | failed | blocked`",
-        "- 验证状态：`not_run | passed | failed | blocked`",
-        "- 完成条件：开发为 `implemented`，且构建、验证均为 `passed`。",
-        "",
-        "## 批次汇总",
-        "",
-        f"- 总任务：{len(normalized)}",
-        f"- 待开始：{len(normalized)}",
-        "- 进行中：0",
-        "- 已完成：0",
-        "- 阻塞：0",
-        "",
-        "## 执行队列",
-        "",
-        "| 任务 | 顺序 | 页面 | 类型 | 分数 | Spec | 开发 | 构建 | 验证 |",
-        "|---|---:|---|---|---:|---|---|---|---|",
-    ]
-    for page in normalized:
-        spec_link = f"./{page['package']}/spec.md"
-        lines.append(
-            "| {task} | {order} | {page_id} | {kind} | {score} | "
-            "[spec.md]({spec}) | `pending` | `not_run` | `not_run` |".format(
-                task=page["task_id"],
-                order=page["order"],
-                page_id=markdown_text(page["page_id"]),
-                kind=markdown_text(page["kind"]),
-                score=page["page_score"],
-                spec=spec_link,
-            )
-        )
-
-    lines.extend(["", "## 任务记录"])
-    for page in normalized:
-        page_path = page["page_path"]
-        path_text = (
-            " → ".join(markdown_text(value) for value in page_path)
-            if isinstance(page_path, list)
-            else "—"
-        )
-        spec_link = f"./{page['package']}/spec.md"
-        lines.extend(
-            [
-                "",
-                f"### {page['task_id']} · {markdown_text(page['page_id'])}",
-                "",
-                f"- 执行顺序：{page['order']}",
-                f"- 页面路径：{path_text or '—'}",
-                f"- 页面分数：{page['page_score']}（enablement={page['enablement']}，ordinary_reachability={page['ordinary_reachability']}，shallowness={page['shallowness']}）",
-                f"- 任务 Spec：[spec.md]({spec_link})",
-                "- 开发状态：`pending`",
-                "- 构建状态：`not_run`",
-                "- 验证状态：`not_run`",
-                "- 实现文件：—",
-                "- 测试文件：—",
-                "- 代码提交 / 源码快照：—",
-                "- 构建证据：—",
-                "- 测试证据：—",
-                "- 最后更新：—",
-                "- 阻塞原因：—",
-                "",
-                "#### 执行记录",
-                "",
-                "- 尚未开始。",
-            ]
-        )
-
-    output_root.mkdir(parents=True, exist_ok=True)
-    report_text = "\n".join(lines) + "\n"
-    with tempfile.NamedTemporaryFile(
-        mode="w", encoding="utf-8", dir=output_root, prefix=".batch-report-", delete=False
-    ) as stream:
-        stream.write(report_text)
-        temporary_path = Path(stream.name)
-    os.replace(temporary_path, report_path)
-    print(
-        json.dumps(
-            {
-                "ok": True,
-                "task_count": len(normalized),
-                "pages_plan": str(pages_plan),
-                "batch_report": str(report_path),
-            },
-            ensure_ascii=False,
-            indent=2,
-        )
-    )
-    return 0
-
-
-if __name__ == "__main__":
-    try:
-        raise SystemExit(main())
-    except (FileNotFoundError, FileExistsError, ValueError, KeyError, json.JSONDecodeError) as error:
-        print(f"error: {error}", file=sys.stderr)
-        raise SystemExit(2)
+#!/usr/bin/env python3
+"""Create the initial batch_report.md from a validated pages.json plan."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import sys
+import tempfile
+from datetime import datetime
+from pathlib import Path
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def markdown_text(value: object) -> str:
+    return str(value).replace("|", "\\|").replace("\n", " ")
+
+
+def require_int(value: object, where: str) -> int:
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise ValueError(f"{where} must be an integer")
+    return value
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--pages-plan", required=True, type=Path)
+    parser.add_argument("--output-root", required=True, type=Path)
+    args = parser.parse_args()
+
+    pages_plan = args.pages_plan.resolve()
+    output_root = args.output_root.resolve()
+    report_path = output_root / "batch_report.md"
+    if not pages_plan.is_file():
+        raise FileNotFoundError(f"missing page plan: {pages_plan}")
+    if report_path.exists():
+        raise FileExistsError(
+            f"refusing to overwrite existing execution history: {report_path}; update it in place"
+        )
+
+    payload = json.loads(pages_plan.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict) or payload.get("schema_version") != "d2h-page-plan/v1":
+        raise ValueError("pages plan must use schema d2h-page-plan/v1")
+    pages = payload.get("pages")
+    if not isinstance(pages, list) or not pages:
+        raise ValueError("pages plan must contain a non-empty pages array")
+
+    normalized: list[dict[str, object]] = []
+    seen_packages: set[str] = set()
+    seen_page_ids: set[str] = set()
+    for index, page in enumerate(pages):
+        if not isinstance(page, dict):
+            raise ValueError(f"pages[{index}] must be an object")
+        order = require_int(page.get("order"), f"pages[{index}].order")
+        if order != index + 1:
+            raise ValueError(f"pages[{index}].order must be {index + 1}")
+
+        package = page.get("package")
+        page_id = page.get("page_id")
+        if not isinstance(package, str) or not package:
+            raise ValueError(f"pages[{index}].package must be a non-empty string")
+        if Path(package).name != package or not package.startswith(f"page_{order:04d}_"):
+            raise ValueError(
+                f"pages[{index}].package must be a single directory named page_{order:04d}_<name>-<id>"
+            )
+        if package in seen_packages:
+            raise ValueError(f"duplicate package: {package}")
+        seen_packages.add(package)
+        if not isinstance(page_id, str) or not page_id:
+            raise ValueError(f"pages[{index}].page_id must be a non-empty string")
+        if page_id in seen_page_ids:
+            raise ValueError(f"duplicate page_id: {page_id}")
+        seen_page_ids.add(page_id)
+
+        spec_path = output_root / package / "spec.md"
+        if not spec_path.is_file():
+            raise FileNotFoundError(
+                f"all page specs must exist before batch report generation; missing {spec_path}"
+            )
+        package_files = sorted(path.name for path in spec_path.parent.iterdir() if path.is_file())
+        if package_files != ["spec.md"]:
+            raise ValueError(
+                f"page package must contain only spec.md: {spec_path.parent} contains {package_files}"
+            )
+
+        ledger = page.get("decision_ledger")
+        if not isinstance(ledger, dict):
+            raise ValueError(f"pages[{index}].decision_ledger must be an object")
+        dimensions: dict[str, int] = {}
+        for dimension in ("enablement", "ordinary_reachability", "shallowness"):
+            item = ledger.get(dimension)
+            if not isinstance(item, dict):
+                raise ValueError(f"pages[{index}].decision_ledger.{dimension} must be an object")
+            dimensions[dimension] = require_int(
+                item.get("rating"), f"pages[{index}].decision_ledger.{dimension}.rating"
+            )
+
+        normalized.append(
+            {
+                "order": order,
+                "task_id": f"PAGE-{order:04d}",
+                "page_id": page_id,
+                "kind": page.get("kind", "page"),
+                "page_score": require_int(page.get("page_score"), f"pages[{index}].page_score"),
+                "package": package,
+                "page_path": page.get("page_path", []),
+                **dimensions,
+            }
+        )
+
+    created_at = datetime.now().astimezone().isoformat(timespec="seconds")
+    plan_link = Path(os.path.relpath(pages_plan, output_root)).as_posix()
+    lines = [
+        "# 页面开发批次执行记录",
+        "",
+        f"- 页面计划：[pages.json]({plan_link})",
+        f"- 页面计划 SHA-256：`{sha256(pages_plan)}`",
+        f"- 记录创建时间：`{created_at}`",
+        "- 更新规则：后续开发直接更新本文件；不要重新生成或覆盖已有执行历史。",
+        "",
+        "## 状态约定",
+        "",
+        "- 开发状态：`pending | in_progress | implemented | blocked`",
+        "- 构建状态：`not_run | passed | failed | blocked`",
+        "- 验证状态：`not_run | passed | failed | blocked`",
+        "- 完成条件：开发为 `implemented`，且构建、验证均为 `passed`。",
+        "",
+        "## 批次汇总",
+        "",
+        f"- 总任务：{len(normalized)}",
+        f"- 待开始：{len(normalized)}",
+        "- 进行中：0",
+        "- 已完成：0",
+        "- 阻塞：0",
+        "",
+        "## 执行队列",
+        "",
+        "| 任务 | 顺序 | 页面 | 类型 | 分数 | Spec | 开发 | 构建 | 验证 |",
+        "|---|---:|---|---|---:|---|---|---|---|",
+    ]
+    for page in normalized:
+        spec_link = f"./{page['package']}/spec.md"
+        lines.append(
+            "| {task} | {order} | {page_id} | {kind} | {score} | "
+            "[spec.md]({spec}) | `pending` | `not_run` | `not_run` |".format(
+                task=page["task_id"],
+                order=page["order"],
+                page_id=markdown_text(page["page_id"]),
+                kind=markdown_text(page["kind"]),
+                score=page["page_score"],
+                spec=spec_link,
+            )
+        )
+
+    lines.extend(["", "## 任务记录"])
+    for page in normalized:
+        page_path = page["page_path"]
+        path_text = (
+            " → ".join(markdown_text(value) for value in page_path)
+            if isinstance(page_path, list)
+            else "—"
+        )
+        spec_link = f"./{page['package']}/spec.md"
+        lines.extend(
+            [
+                "",
+                f"### {page['task_id']} · {markdown_text(page['page_id'])}",
+                "",
+                f"- 执行顺序：{page['order']}",
+                f"- 页面路径：{path_text or '—'}",
+                f"- 页面分数：{page['page_score']}（enablement={page['enablement']}，ordinary_reachability={page['ordinary_reachability']}，shallowness={page['shallowness']}）",
+                f"- 任务 Spec：[spec.md]({spec_link})",
+                "- 开发状态：`pending`",
+                "- 构建状态：`not_run`",
+                "- 验证状态：`not_run`",
+                "- 实现文件：—",
+                "- 测试文件：—",
+                "- 代码提交 / 源码快照：—",
+                "- 构建证据：—",
+                "- 测试证据：—",
+                "- 最后更新：—",
+                "- 阻塞原因：—",
+                "",
+                "#### 执行记录",
+                "",
+                "- 尚未开始。",
+            ]
+        )
+
+    output_root.mkdir(parents=True, exist_ok=True)
+    report_text = "\n".join(lines) + "\n"
+    with tempfile.NamedTemporaryFile(
+        mode="w", encoding="utf-8", dir=output_root, prefix=".batch-report-", delete=False
+    ) as stream:
+        stream.write(report_text)
+        temporary_path = Path(stream.name)
+    os.replace(temporary_path, report_path)
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "task_count": len(normalized),
+                "pages_plan": str(pages_plan),
+                "batch_report": str(report_path),
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except (FileNotFoundError, FileExistsError, ValueError, KeyError, json.JSONDecodeError) as error:
+        print(f"error: {error}", file=sys.stderr)
+        raise SystemExit(2)