372 lines
14 KiB
Python
372 lines
14 KiB
Python
#!/usr/bin/env python3
|
||
"""把 branch/tag read-only diff 轉成真相來源分類草案。
|
||
|
||
此工具只讀取已脫敏的 ref detail diff snapshot，不呼叫遠端 Git、不 fetch、
|
||
不 push、不刪 branch/tag。輸出用途是人工 review 與 AwoooP mirror。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
import argparse
|
||
import json
|
||
from pathlib import Path
|
||
from typing import Any
|
||
|
||
|
||
DEFAULT_STILL_FORBIDDEN = [
|
||
"fetch",
|
||
"push refs",
|
||
"force push",
|
||
"delete refs",
|
||
"create GitHub repo",
|
||
"change repo visibility",
|
||
"switch GitHub primary",
|
||
"disable Gitea",
|
||
"move secret values",
|
||
]
|
||
|
||
DEFAULT_ALLOWED_NOW = [
|
||
"mirror_classification",
|
||
"display_review_lane",
|
||
"request_single_ref_owner_decision",
|
||
"update_read_only_evidence",
|
||
]
|
||
|
||
|
||
def load_json(path: Path) -> dict[str, Any]:
|
||
return json.loads(path.read_text(encoding="utf-8"))
|
||
|
||
|
||
def risk_for_repo(gitea_repo: str) -> str:
|
||
if gitea_repo == "wooo/awoooi":
|
||
return "HIGH"
|
||
return "MEDIUM"
|
||
|
||
|
||
def short_sha(value: str) -> str:
|
||
return value[:8] if value else "無"
|
||
|
||
|
||
def classification_item(
|
||
*,
|
||
ref_type: str,
|
||
ref_name: str,
|
||
lane: str,
|
||
risk: str,
|
||
proposed_truth_source: str,
|
||
classification: str,
|
||
reason: str,
|
||
next_review: str,
|
||
gitea_sha: str = "",
|
||
github_sha: str = "",
|
||
) -> dict[str, Any]:
|
||
return {
|
||
"ref_type": ref_type,
|
||
"ref_name": ref_name,
|
||
"lane": lane,
|
||
"risk": risk,
|
||
"proposed_truth_source": proposed_truth_source,
|
||
"classification": classification,
|
||
"reason": reason,
|
||
"next_review": next_review,
|
||
"gitea_sha": gitea_sha,
|
||
"github_sha": github_sha,
|
||
"allowed_now": DEFAULT_ALLOWED_NOW,
|
||
"forbidden_actions": DEFAULT_STILL_FORBIDDEN,
|
||
}
|
||
|
||
|
||
def classify_branch_only_gitea(item: dict[str, str], repo_risk: str) -> dict[str, Any]:
|
||
name = item["name"]
|
||
sha = item["sha"]
|
||
if name.startswith("drift/adopt-"):
|
||
return classification_item(
|
||
ref_type="branch",
|
||
ref_name=name,
|
||
lane="archive_or_deprecate_candidate",
|
||
risk="LOW",
|
||
proposed_truth_source="deprecated_candidate",
|
||
classification="manual_review_deprecated_candidate",
|
||
reason="drift/adopt 類分支疑似為漂移承接或暫存分支，先標為可能封存/降級候選，但不得自動刪除。",
|
||
next_review="由 repo owner 確認是否仍有部署、PR、回滾或稽核用途；確認前保留。",
|
||
gitea_sha=sha,
|
||
)
|
||
if name == "dev":
|
||
return classification_item(
|
||
ref_type="branch",
|
||
ref_name=name,
|
||
lane="active_branch_truth_required",
|
||
risk=repo_risk,
|
||
proposed_truth_source="manual_required",
|
||
classification="manual_truth_required",
|
||
reason="`dev` 可能是仍在使用的開發分支，GitHub 缺少此 ref 前不得判定 GitHub ready。",
|
||
next_review="確認 dev 是否仍為有效工作流；若有效，再決定單 branch 同步策略。",
|
||
gitea_sha=sha,
|
||
)
|
||
return classification_item(
|
||
ref_type="branch",
|
||
ref_name=name,
|
||
lane="manual_review",
|
||
risk=repo_risk,
|
||
proposed_truth_source="manual_required",
|
||
classification="manual_review",
|
||
reason="此 Gitea-only branch 不符合已知低風險規則，需要人工判定用途。",
|
||
next_review="確認 ref owner、是否 active、是否需保留到 GitHub 或改列封存。",
|
||
gitea_sha=sha,
|
||
)
|
||
|
||
|
||
def classify_branch_only_github(item: dict[str, str], repo_risk: str) -> dict[str, Any]:
|
||
name = item["name"]
|
||
return classification_item(
|
||
ref_type="branch",
|
||
ref_name=name,
|
||
lane="github_only_manual_review",
|
||
risk=repo_risk,
|
||
proposed_truth_source="manual_required",
|
||
classification="manual_review_github_only",
|
||
reason="GitHub-only branch 可能代表 GitHub 端曾有獨立工作，不能用 Gitea 覆蓋或刪除。",
|
||
next_review="確認該 branch 是否為有效 refactor/feature 線，並判定是否回補到 Gitea 或保留 GitHub-only。",
|
||
github_sha=item["sha"],
|
||
)
|
||
|
||
|
||
def classify_tag_only_gitea(item: dict[str, str], repo_risk: str) -> dict[str, Any]:
|
||
return classification_item(
|
||
ref_type="tag",
|
||
ref_name=item["name"],
|
||
lane="release_tag_missing_on_github",
|
||
risk=repo_risk,
|
||
proposed_truth_source="manual_required",
|
||
classification="manual_review_release_tag",
|
||
reason="Gitea-only release tag 可能是正式版本證據；GitHub primary 前需確認是否補 tag。",
|
||
next_review="確認 tag 對應 release / artifact / deploy marker，再以單 repo approval 決定是否同步。",
|
||
gitea_sha=item["sha"],
|
||
)
|
||
|
||
|
||
def classify_tag_only_github(item: dict[str, str], repo_risk: str) -> dict[str, Any]:
|
||
name = item["name"]
|
||
if name.startswith("uat-"):
|
||
lane = "github_only_uat_tag"
|
||
reason = "GitHub-only UAT tag 可能是舊驗收或臨時發布標記，不得自動刪除或搬回 Gitea。"
|
||
next_review = "確認 UAT tag 是否仍需保留為稽核 evidence；若已過期，再列入封存決策。"
|
||
else:
|
||
lane = "github_only_manual_review"
|
||
reason = "GitHub-only tag 可能代表 GitHub 端 release evidence，需要人工判定。"
|
||
next_review = "確認 tag owner、release 用途與是否需要與 Gitea 對齊。"
|
||
return classification_item(
|
||
ref_type="tag",
|
||
ref_name=name,
|
||
lane=lane,
|
||
risk=repo_risk,
|
||
proposed_truth_source="manual_required",
|
||
classification="manual_review_github_only",
|
||
reason=reason,
|
||
next_review=next_review,
|
||
github_sha=item["sha"],
|
||
)
|
||
|
||
|
||
def classify_main_mismatch(item: dict[str, str], repo_risk: str) -> dict[str, Any]:
|
||
return classification_item(
|
||
ref_type="branch",
|
||
ref_name=item["name"],
|
||
lane="main_truth_required",
|
||
risk=repo_risk,
|
||
proposed_truth_source="manual_required",
|
||
classification="manual_truth_required",
|
||
reason="兩端 main SHA 不一致，這是 GitHub primary / deploy control plane 的硬阻塞。",
|
||
next_review="先確認目前 production deploy 真相來源、deploy marker、rollback 點，再決定單 repo reconcile。",
|
||
gitea_sha=item["gitea_sha"],
|
||
github_sha=item["github_sha"],
|
||
)
|
||
|
||
|
||
def classify_repo(repo: dict[str, Any]) -> dict[str, Any]:
|
||
repo_risk = risk_for_repo(str(repo["gitea_repo"]))
|
||
items: list[dict[str, Any]] = []
|
||
branch = repo["branch_diff"]
|
||
tag = repo["tag_diff"]
|
||
|
||
for mismatch in branch["sha_mismatch"]:
|
||
if mismatch["name"] == "main":
|
||
items.append(classify_main_mismatch(mismatch, repo_risk))
|
||
else:
|
||
items.append(
|
||
classification_item(
|
||
ref_type="branch",
|
||
ref_name=mismatch["name"],
|
||
lane="manual_review",
|
||
risk=repo_risk,
|
||
proposed_truth_source="manual_required",
|
||
classification="manual_truth_required",
|
||
reason="Branch 兩端皆存在但 SHA 不一致，需要人工判定哪一端為真相來源。",
|
||
next_review="確認是否 active、是否有 PR / deploy / rollback 依賴，再進單 branch reconcile。",
|
||
gitea_sha=mismatch["gitea_sha"],
|
||
github_sha=mismatch["github_sha"],
|
||
)
|
||
)
|
||
|
||
for item in branch["only_gitea"]:
|
||
items.append(classify_branch_only_gitea(item, repo_risk))
|
||
for item in branch["only_github"]:
|
||
items.append(classify_branch_only_github(item, repo_risk))
|
||
for item in tag["only_gitea"]:
|
||
items.append(classify_tag_only_gitea(item, repo_risk))
|
||
for item in tag["only_github"]:
|
||
items.append(classify_tag_only_github(item, repo_risk))
|
||
|
||
return {
|
||
"gitea_repo": repo["gitea_repo"],
|
||
"github_repo": repo["github_repo"],
|
||
"risk": repo_risk,
|
||
"awooop_consumption": "approval_candidate",
|
||
"item_count": len(items),
|
||
"items": items,
|
||
}
|
||
|
||
|
||
def build_snapshot(args: argparse.Namespace) -> dict[str, Any]:
|
||
source_path = Path(args.source_snapshot)
|
||
source = load_json(source_path)
|
||
repos = [classify_repo(repo) for repo in source["repos"]]
|
||
all_items = [item for repo in repos for item in repo["items"]]
|
||
return {
|
||
"schema_version": "source_control_ref_truth_classification_v1",
|
||
"status": "draft_blocked",
|
||
"date": args.date,
|
||
"default_mode": "classification_only",
|
||
"source_snapshot": str(source_path),
|
||
"summary": {
|
||
"repo_count": len(repos),
|
||
"total_items": len(all_items),
|
||
"manual_truth_required_count": sum(
|
||
1 for item in all_items if item["classification"] == "manual_truth_required"
|
||
),
|
||
"deprecated_candidate_count": sum(
|
||
1 for item in all_items if item["classification"] == "manual_review_deprecated_candidate"
|
||
),
|
||
"release_tag_review_count": sum(
|
||
1 for item in all_items if item["classification"] == "manual_review_release_tag"
|
||
),
|
||
"github_only_review_count": sum(
|
||
1 for item in all_items if item["classification"] == "manual_review_github_only"
|
||
),
|
||
},
|
||
"still_forbidden": DEFAULT_STILL_FORBIDDEN,
|
||
"repos": repos,
|
||
}
|
||
|
||
|
||
def write_markdown(snapshot: dict[str, Any], path: Path, *, list_limit: int) -> None:
|
||
summary = snapshot["summary"]
|
||
lines = [
|
||
"# Source Control Ref Truth Classification",
|
||
"",
|
||
"| 項目 | 內容 |",
|
||
"|------|------|",
|
||
f"| 日期 | {snapshot['date']} |",
|
||
f"| 狀態 | `{snapshot['status']}` |",
|
||
f"| 預設模式 | `{snapshot['default_mode']}` |",
|
||
f"| 來源 snapshot | `{snapshot['source_snapshot']}` |",
|
||
f"| repo count | `{summary['repo_count']}` |",
|
||
f"| total items | `{summary['total_items']}` |",
|
||
"",
|
||
"## 0. 核心結論",
|
||
"",
|
||
"本檔把 branch/tag diff 轉成「人工審核分類」：哪些 ref 需要真相來源判定、哪些可能是 deprecated 候選、哪些 release / UAT tags 需要保留判定。它不是同步計畫，也不授權 fetch、push、delete refs 或 GitHub primary 切換。",
|
||
"",
|
||
"## 1. 摘要",
|
||
"",
|
||
"| 指標 | 數量 |",
|
||
"|------|------|",
|
||
f"| 需要人工指定真相來源 | `{summary['manual_truth_required_count']}` |",
|
||
f"| 可能 deprecated / archive 候選 | `{summary['deprecated_candidate_count']}` |",
|
||
f"| release tag 待審核 | `{summary['release_tag_review_count']}` |",
|
||
f"| GitHub-only ref 待審核 | `{summary['github_only_review_count']}` |",
|
||
"",
|
||
"## 2. Repo 分類",
|
||
"",
|
||
]
|
||
|
||
for repo in snapshot["repos"]:
|
||
lines.extend(
|
||
[
|
||
f"### {repo['gitea_repo']} -> {repo['github_repo']}",
|
||
"",
|
||
f"- Risk：`{repo['risk']}`",
|
||
f"- AwoooP consumption：`{repo['awooop_consumption']}`",
|
||
f"- Item count：`{repo['item_count']}`",
|
||
"",
|
||
"| Ref | Type | Lane | Classification | Gitea | GitHub | 下一步 |",
|
||
"|-----|------|------|----------------|-------|--------|--------|",
|
||
]
|
||
)
|
||
visible_items = repo["items"] if list_limit <= 0 else repo["items"][:list_limit]
|
||
for item in visible_items:
|
||
lines.append(
|
||
"| "
|
||
+ " | ".join(
|
||
[
|
||
f"`{item['ref_name']}`",
|
||
f"`{item['ref_type']}`",
|
||
f"`{item['lane']}`",
|
||
f"`{item['classification']}`",
|
||
f"`{short_sha(item['gitea_sha'])}`",
|
||
f"`{short_sha(item['github_sha'])}`",
|
||
item["next_review"],
|
||
]
|
||
)
|
||
+ " |"
|
||
)
|
||
if list_limit > 0 and repo["item_count"] > list_limit:
|
||
lines.append(
|
||
f"| 另有 `{repo['item_count'] - list_limit}` 筆 | | | 完整清單見 JSON snapshot | | | |"
|
||
)
|
||
lines.append("")
|
||
|
||
lines.extend(
|
||
[
|
||
"## 3. AwoooP 消費方式",
|
||
"",
|
||
"1. 只 mirror `source_control_ref_truth_classification_v1`。",
|
||
"2. 可顯示 review lane 與 owner decision queue。",
|
||
"3. 可產生單 repo / 單 ref approval candidate，但不得自動批准。",
|
||
"4. 不得新增 refs sync、delete、force-push、primary switch action。",
|
||
"",
|
||
"## 4. 仍然禁止",
|
||
"",
|
||
]
|
||
)
|
||
for value in snapshot["still_forbidden"]:
|
||
lines.append(f"- {value}")
|
||
lines.append("")
|
||
path.write_text("\n".join(lines), encoding="utf-8")
|
||
|
||
|
||
def main() -> int:
|
||
parser = argparse.ArgumentParser()
|
||
parser.add_argument("--date", required=True)
|
||
parser.add_argument("--source-snapshot", required=True)
|
||
parser.add_argument("--output-json", required=True)
|
||
parser.add_argument("--output-md", required=True)
|
||
parser.add_argument("--md-list-limit", type=int, default=40)
|
||
args = parser.parse_args()
|
||
|
||
snapshot = build_snapshot(args)
|
||
Path(args.output_json).write_text(
|
||
json.dumps(snapshot, ensure_ascii=False, indent=2) + "\n",
|
||
encoding="utf-8",
|
||
)
|
||
write_markdown(snapshot, Path(args.output_md), list_limit=args.md_list_limit)
|
||
print(
|
||
"OK source-control ref truth classification "
|
||
f"repos={snapshot['summary']['repo_count']} items={snapshot['summary']['total_items']}"
|
||
)
|
||
return 0
|
||
|
||
|
||
if __name__ == "__main__":
|
||
raise SystemExit(main())
|