@hunyed15/codecgc 0.1.0

package/scripts/write_codecgc_requirement.py

@@ -0,0 +1,78 @@
+import argparse
+from pathlib import Path
+
+from codecgc_artifact_roots import artifact_output_root
+from codecgc_console_io import configure_utf8_stdio
+from codecgc_console_io import print_json
+from codecgc_governance_dedupe import has_existing_governance_entry
+
+
+SECTION_HEADING = "## 7. Governance Updates"
+
+
+def resolve_requirement_path() -> Path:
+    return artifact_output_root("product") / "requirements" / "codecgc-core-requirements.md"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="把一条长期有效的需求治理更新写入 codecgc/requirements/codecgc-core-requirements.md。"
+    )
+    parser.add_argument("--summary", required=True, help="一行需求更新摘要。")
+    parser.add_argument("--note", default="", help="可选的稳定需求说明。")
+    parser.add_argument("--source", default="", help="可选的来源产物、工作流或讨论引用。")
+    return parser
+
+
+def ensure_governance_section(text: str) -> str:
+    if SECTION_HEADING in text:
+        return text
+    stripped = text.rstrip()
+    suffix = "\n\n" if stripped else ""
+    return f"{stripped}{suffix}{SECTION_HEADING}\n\n"
+
+
+def has_existing_entry(existing: str, summary: str) -> bool:
+    return has_existing_governance_entry(existing, summary, field_labels=["Summary", "摘要"])
+
+
+def append_requirement_update(path: Path, summary: str, note: str, source: str) -> dict[str, str]:
+    existing = path.read_text(encoding="utf-8")
+    ensured = ensure_governance_section(existing)
+    cleaned_summary = summary.strip()
+    if has_existing_entry(ensured, cleaned_summary):
+        return {
+            "path": str(path),
+            "summary": cleaned_summary,
+            "note": note.strip(),
+            "source": source.strip(),
+            "created": "false",
+        }
+
+    lines = [f"### {cleaned_summary}", "", f"- 摘要: {cleaned_summary}"]
+    if note.strip():
+        lines.append(f"- 稳定需求说明: {note.strip()}")
+    if source.strip():
+        lines.append(f"- 来源: {source.strip()}")
+    lines.append("")
+
+    path.write_text(ensured + "\n".join(lines), encoding="utf-8")
+    return {
+        "path": str(path),
+        "summary": cleaned_summary,
+        "note": note.strip(),
+        "source": source.strip(),
+        "created": "true",
+    }
+
+
+def main() -> int:
+    configure_utf8_stdio()
+    args = build_parser().parse_args()
+    result = append_requirement_update(resolve_requirement_path(), args.summary, args.note, args.source)
+    print_json({"success": True, "requirement": result})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/write_codecgc_review.py

@@ -0,0 +1,291 @@
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from codecgc_artifact_roots import flow_root
+from codecgc_artifact_roots import normalize_artifact_class
+from codecgc_console_io import configure_utf8_stdio
+from codecgc_console_io import print_json
+from codecgc_review_control import ACTION_KIND_LABELS
+from codecgc_review_control import FALLBACK_STAGE_LABELS
+from codecgc_review_control import display_policy_reason
+from codecgc_review_control import evaluate_review
+from codecgc_step_control import update_step_status
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="把 CodeCGC 审核结果回写到功能验收或问题修复说明产物中。"
+    )
+    parser.add_argument(
+        "--audit-file",
+        required=True,
+        help="执行审计 JSON 文件路径。",
+    )
+    parser.add_argument(
+        "--decision",
+        choices=["accepted", "changes-requested"],
+        required=True,
+        help="审核决策。",
+    )
+    parser.add_argument(
+        "--risk",
+        action="append",
+        default=[],
+        help="可选：补充剩余风险说明。",
+    )
+    parser.add_argument(
+        "--next-step",
+        default="",
+        help="可选：未通过或未完成时的下一步说明。",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="允许覆盖已有的非 TODO 审核内容。",
+    )
+    return parser
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        raise FileNotFoundError(f"未找到审计文件：{path}")
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError("审计文件必须包含一个 JSON 对象。")
+    return data
+
+
+def resolve_artifact_path(audit: dict[str, Any]) -> tuple[str, Path]:
+    source = audit.get("source")
+    if not isinstance(source, dict):
+        raise ValueError("审计文件缺少有效的 source 区块。")
+
+    artifact_type = str(source.get("artifact_type", ""))
+    artifact_class = normalize_artifact_class(str(source.get("artifact_class", "product")))
+    artifact_slug = str(source.get("artifact_slug", ""))
+    if not artifact_type or not artifact_slug:
+        raise ValueError("审计 source 缺少 artifact_type 或 artifact_slug。")
+
+    if artifact_type == "feature":
+        base_slug = artifact_slug[11:] if len(artifact_slug) > 11 and artifact_slug[4] == "-" else artifact_slug
+        return artifact_type, flow_root("feature", artifact_class) / artifact_slug / f"{base_slug}-acceptance.md"
+
+    if artifact_type == "issue":
+        base_slug = artifact_slug[11:] if len(artifact_slug) > 11 and artifact_slug[4] == "-" else artifact_slug
+        return artifact_type, flow_root("issue", artifact_class) / artifact_slug / f"{base_slug}-fix-note.md"
+
+    raise ValueError(f"不支持的产物类型：{artifact_type}")
+
+
+def resolve_checklist_path_from_audit(audit: dict[str, Any]) -> Path:
+    source = audit.get("source")
+    if not isinstance(source, dict):
+        raise ValueError("审计文件缺少有效的 source 区块。")
+    artifact_file = str(source.get("artifact_file", ""))
+    if not artifact_file:
+        raise ValueError("审计 source 缺少 artifact_file。")
+    return Path(artifact_file)
+
+
+def resolve_step_number_from_audit(audit: dict[str, Any]) -> int:
+    source = audit.get("source")
+    if not isinstance(source, dict):
+        raise ValueError("审计文件缺少有效的 source 区块。")
+    step_number = int(source.get("step_number", 0))
+    if step_number < 1:
+        raise ValueError("审计 source 缺少有效的 step_number。")
+    return step_number
+
+
+def extract_review_values(audit: dict[str, Any], decision: str, risks: list[str], next_step: str) -> dict[str, str]:
+    return evaluate_review(audit, decision, risks, next_step)
+
+
+def ensure_overwrite_allowed(text: str, force: bool) -> None:
+    if force:
+        return
+    if "TODO" not in text:
+        raise ValueError("目标产物已经包含非 TODO 审核内容。如需覆盖，请使用 --force。")
+
+
+def render_review_decision(value: str) -> str:
+    return {
+        "accepted": "通过",
+        "changes-requested": "需修改",
+    }.get(value.strip(), value.strip() or "未知")
+
+
+def render_action_kind(value: str) -> str:
+    cleaned = value.strip()
+    return ACTION_KIND_LABELS.get(cleaned, cleaned or "未知")
+
+
+def render_fallback_stage(value: str) -> str:
+    cleaned = value.strip()
+    return FALLBACK_STAGE_LABELS.get(cleaned, cleaned or "未知")
+
+
+def render_feature_acceptance(original: str, values: dict[str, str]) -> str:
+    frontmatter, body = split_frontmatter(original)
+    title = extract_title(body)
+    return "\n".join(
+        [
+            frontmatter.strip(),
+            "",
+            title,
+            "",
+            "## 1. 范围检查",
+            "",
+            values["scope_check"],
+            "",
+            "## 2. 执行器检查",
+            "",
+            values["executor_check"],
+            "",
+            "## 3. 验证结果",
+            "",
+            values["verification"],
+            "",
+            "## 4. 剩余风险",
+            "",
+            values["remaining_risk"],
+            "",
+            "## 5. 审核结论",
+            "",
+            f"- 审核结果: {render_review_decision(str(values['final_decision']))}",
+            f"- 审核 task_id: {values['reviewed_task_id'] or '未知'}",
+            f"- 审核步骤序号: {values['reviewed_step_number'] or '未知'}",
+            f"- 审核动作类型: {render_action_kind(str(values.get('recommended_action_kind', '')))}",
+            f"- 审核回退阶段: {render_fallback_stage(str(values.get('fallback_stage', '')))}",
+            f"- 审核策略原因: {display_policy_reason(str(values.get('policy_reason', '')))}",
+            f"- 下一步: {values['next_step']}",
+            "",
+        ]
+    )
+
+
+def render_issue_fix_note(original: str, values: dict[str, str]) -> str:
+    frontmatter, body = split_frontmatter(original)
+    title = extract_title(body)
+    return "\n".join(
+        [
+            frontmatter.strip(),
+            "",
+            title,
+            "",
+            "## 1. 已应用修复",
+            "",
+            values["verification"],
+            "",
+            "## 2. 验证结果",
+            "",
+            values["scope_check"],
+            "",
+            "## 3. 执行器检查",
+            "",
+            values["executor_check"],
+            "",
+            "## 4. 剩余风险",
+            "",
+            values["remaining_risk"],
+            "",
+            "## 5. 审核结论",
+            "",
+            f"- 审核结果: {render_review_decision(str(values['final_decision']))}",
+            f"- 审核 task_id: {values['reviewed_task_id'] or '未知'}",
+            f"- 审核步骤序号: {values['reviewed_step_number'] or '未知'}",
+            f"- 审核动作类型: {render_action_kind(str(values.get('recommended_action_kind', '')))}",
+            f"- 审核回退阶段: {render_fallback_stage(str(values.get('fallback_stage', '')))}",
+            f"- 审核策略原因: {display_policy_reason(str(values.get('policy_reason', '')))}",
+            f"- 下一步: {values['next_step']}",
+            "",
+        ]
+    )
+
+
+def split_frontmatter(text: str) -> tuple[str, str]:
+    if not text.startswith("---\n"):
+        return "", text
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return "", text
+    return text[: end + 5], text[end + 5 :].lstrip("\n")
+
+
+def extract_title(body: str) -> str:
+    for line in body.splitlines():
+        if line.startswith("# "):
+            return line
+    return "# 审核结果"
+
+
+def write_review(audit_path: Path, decision: str, risks: list[str], next_step: str, force: bool) -> dict[str, str]:
+    audit = load_json(audit_path)
+    artifact_type, artifact_path = resolve_artifact_path(audit)
+    checklist_path = resolve_checklist_path_from_audit(audit)
+    step_number = resolve_step_number_from_audit(audit)
+    if not artifact_path.exists():
+        raise FileNotFoundError(f"未找到目标产物：{artifact_path}")
+
+    original = artifact_path.read_text(encoding="utf-8")
+    if not force:
+        ensure_overwrite_allowed(original, force=False)
+
+    values = extract_review_values(audit, decision, risks, next_step)
+    if artifact_type == "feature":
+        rendered = render_feature_acceptance(original, values)
+    else:
+        rendered = render_issue_fix_note(original, values)
+
+    artifact_path.write_text(rendered, encoding="utf-8")
+    update_step_status(
+        checklist_path,
+        step_number,
+        "done" if values["final_decision"] == "accepted" else "pending",
+    )
+    return {
+        "artifact_type": artifact_type,
+        "artifact_path": str(artifact_path),
+        "checklist_path": str(checklist_path),
+        "step_number": str(step_number),
+        "step_status": "done" if values["final_decision"] == "accepted" else "pending",
+    }
+
+
+def main() -> int:
+    configure_utf8_stdio()
+    parser = build_parser()
+    args = parser.parse_args()
+
+    try:
+        result = write_review(
+            audit_path=Path(args.audit_file),
+            decision=args.decision,
+            risks=args.risk,
+            next_step=args.next_step,
+            force=args.force,
+        )
+    except Exception as error:
+        print_json(
+            {
+                "success": False,
+                "error": str(error),
+            },
+            file=sys.stderr,
+        )
+        return 1
+
+    print_json(
+        {
+            "success": True,
+            **result,
+        }
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/write_codecgc_roadmap.py

@@ -0,0 +1,122 @@
+import argparse
+import re
+from pathlib import Path
+
+from codecgc_artifact_roots import artifact_output_root
+from codecgc_console_io import configure_utf8_stdio
+from codecgc_console_io import print_json
+from codecgc_workflow_runtime import run_json_script
+
+
+def normalize_slug(value: str) -> str:
+    normalized = value.strip().lower()
+    normalized = re.sub(r"[^a-z0-9]+", "-", normalized)
+    normalized = re.sub(r"-{2,}", "-", normalized).strip("-")
+    return normalized or "roadmap-item"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="根据治理请求在 codecgc/roadmap/ 下初始化长期 roadmap 产物。"
+    )
+    parser.add_argument("--summary", required=True, help="一行 roadmap 摘要。")
+    parser.add_argument("--goal", default="", help="可选的 roadmap 目标。")
+    parser.add_argument("--source", default="", help="可选的来源产物、工作流或讨论引用。")
+    parser.add_argument("--force", action="store_true")
+    return parser
+
+
+def resolve_roadmap_directory(slug: str) -> Path:
+    return artifact_output_root("product") / "roadmap" / slug
+
+
+def append_source_note(path: Path, source: str) -> None:
+    if not source.strip() or not path.exists():
+        return
+    content = path.read_text(encoding="utf-8")
+    note = f"\n## 7. 治理来源\n\n- 来源: {source.strip()}\n"
+    if "## 7. Governance Source" in content or "## 7. 治理来源" in content or f"- Source: {source.strip()}" in content or f"- 来源: {source.strip()}" in content:
+        return
+    path.write_text(content.rstrip() + note, encoding="utf-8")
+
+
+def init_roadmap(summary: str, goal: str, source: str, force: bool) -> dict[str, object]:
+    slug = normalize_slug(summary)
+    roadmap_dir = resolve_roadmap_directory(slug)
+    result = run_json_script(
+        "init_codecgc_roadmap.py",
+        "--slug",
+        slug,
+        "--summary",
+        summary.strip(),
+        "--goal",
+        goal.strip() or summary.strip(),
+        *([] if not force else ["--force"]),
+    )
+    if not result.get("success") and roadmap_dir.exists() and not force:
+        overview_path = roadmap_dir / "overview.md"
+        append_source_note(overview_path, source)
+        return {
+            "success": True,
+            "roadmap": {
+                "slug": slug,
+                "directory": str(roadmap_dir),
+                "files": {
+                    "overview": str(roadmap_dir / "overview.md"),
+                    "phases": str(roadmap_dir / "phases.md"),
+                    "delivery_plan": str(roadmap_dir / "delivery-plan.md"),
+                },
+                "source": source.strip(),
+                "created": "false",
+            },
+        }
+    if not result.get("success"):
+        return result
+
+    files = result.get("files", {}) if isinstance(result.get("files"), dict) else {}
+    overview_path = Path(str(files.get("overview", ""))) if files.get("overview") else roadmap_dir / "overview.md"
+    append_source_note(overview_path, source)
+    return {
+        "success": True,
+        "roadmap": {
+            "slug": slug,
+            "directory": result.get("directory", str(roadmap_dir)),
+            "files": files,
+            "source": source.strip(),
+            "created": "true",
+        },
+    }
+
+
+def main() -> int:
+    configure_utf8_stdio()
+    args = build_parser().parse_args()
+    slug = normalize_slug(args.summary)
+    roadmap_dir = resolve_roadmap_directory(slug)
+    if roadmap_dir.exists() and not args.force:
+        append_source_note(roadmap_dir / "overview.md", args.source)
+        print_json(
+            {
+                "success": True,
+                "roadmap": {
+                    "slug": slug,
+                    "directory": str(roadmap_dir),
+                    "files": {
+                        "overview": str(roadmap_dir / "overview.md"),
+                        "phases": str(roadmap_dir / "phases.md"),
+                        "delivery_plan": str(roadmap_dir / "delivery-plan.md"),
+                    },
+                    "source": args.source.strip(),
+                    "created": "false",
+                },
+            }
+        )
+        return 0
+
+    result = init_roadmap(args.summary, args.goal, args.source, args.force)
+    print_json(result)
+    return 0 if result.get("success") else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/write_codecgc_trick.py

@@ -0,0 +1,123 @@
+import argparse
+from pathlib import Path
+
+from codecgc_artifact_roots import artifact_output_root
+from codecgc_console_io import configure_utf8_stdio
+from codecgc_console_io import print_json
+from codecgc_governance_dedupe import has_existing_governance_entry
+
+
+def resolve_trick_path() -> Path:
+    return artifact_output_root("product") / "compound" / "codecgc-tricks.md"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="把一条可复用技巧或技术处方写入 codecgc/compound/codecgc-tricks.md。"
+    )
+    parser.add_argument("--summary", required=True, help="一行 trick 摘要。")
+    parser.add_argument("--kind", choices=["pattern", "library", "technique"], default="technique")
+    parser.add_argument("--instruction", default="", help="简短的默认做法或使用建议。")
+    parser.add_argument("--source", default="", help="可选的来源产物、工作流或讨论引用。")
+    parser.add_argument("--artifact-path", default="", help="已有 trick 文件路径；传入时进入补充完善模式。")
+    parser.add_argument("--practice", default="", help="补充默认做法。")
+    parser.add_argument("--scope", default="", help="补充适用范围。")
+    parser.add_argument("--counterexample", default="", help="补充反例或误用。")
+    parser.add_argument("--append-note", default="", help="无法结构化时，附加到 trick 条目的补充说明。")
+    return parser
+
+
+def ensure_document(path: Path) -> None:
+    if path.exists():
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        "# CodeCGC Tricks\n\n"
+        "该文件用于记录可复用的模式、库用法与技术技巧。\n\n"
+        "## 条目\n\n",
+        encoding="utf-8",
+    )
+
+
+def has_existing_entry(existing: str, summary: str) -> bool:
+    return has_existing_governance_entry(existing, summary, field_labels=["摘要"])
+
+
+def append_trick(path: Path, summary: str, kind: str, instruction: str, source: str) -> dict[str, str]:
+    ensure_document(path)
+    cleaned_summary = summary.strip()
+    existing = path.read_text(encoding="utf-8")
+    if has_existing_entry(existing, cleaned_summary):
+        return {
+            "path": str(path),
+            "summary": cleaned_summary,
+            "kind": kind.strip(),
+            "instruction": instruction.strip(),
+            "source": source.strip(),
+            "created": "false",
+        }
+
+    lines = [f"### {cleaned_summary}", "", f"- 类型: {kind.strip()}", f"- 摘要: {cleaned_summary}"]
+    if instruction.strip():
+        lines.append(f"- 默认做法: {instruction.strip()}")
+    if source.strip():
+        lines.append(f"- 来源: {source.strip()}")
+    lines.append("")
+
+    path.write_text(existing + "\n".join(lines), encoding="utf-8")
+    return {
+        "path": str(path),
+        "summary": cleaned_summary,
+        "kind": kind.strip(),
+        "instruction": instruction.strip(),
+        "source": source.strip(),
+        "created": "true",
+    }
+
+
+def update_trick(path: Path, practice: str, scope: str, counterexample: str, append_note: str) -> dict[str, str]:
+    if not path.exists():
+        raise FileNotFoundError(f"Trick file not found: {path}")
+    content = path.read_text(encoding="utf-8")
+    lines: list[str] = []
+    if practice.strip():
+        lines.append(f"- 默认做法补充: {practice.strip()}")
+    if scope.strip():
+        lines.append(f"- 适用范围: {scope.strip()}")
+    if counterexample.strip():
+        lines.append(f"- 反例或误用: {counterexample.strip()}")
+    if append_note.strip():
+        lines.append(f"- 补充说明: {append_note.strip()}")
+    if lines:
+        content = content.rstrip() + "\n" + "\n".join(lines) + "\n"
+        path.write_text(content, encoding="utf-8")
+    return {
+        "path": str(path),
+        "updated": "true",
+        "practice": practice.strip(),
+        "scope": scope.strip(),
+        "counterexample": counterexample.strip(),
+        "append_note": append_note.strip(),
+    }
+
+
+def main() -> int:
+    configure_utf8_stdio()
+    args = build_parser().parse_args()
+    if args.artifact_path.strip():
+        result = update_trick(
+            Path(args.artifact_path),
+            args.practice,
+            args.scope,
+            args.counterexample,
+            args.append_note,
+        )
+        print_json({"success": True, "trick": result})
+        return 0
+    result = append_trick(resolve_trick_path(), args.summary, args.kind, args.instruction, args.source)
+    print_json({"success": True, "trick": result})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())