Skip to content

Commit 4f6e04c

Browse files
massu2002claude
andauthored
Organization 監査が標準の Custom Properties の言葉で判定する (#34)
Custom Properties を標準(v1.2 §6)の言葉へ寄せることが決まった。監査は 旧い言葉の組(LIFECYCLE_BY_TYPE)しか知らず、足す 5 つの Property も、 その組も確かめられなかった。寄せる前に監査側を直す。 標準の 8 Property と取りうる値を STANDARD の 1 箇所に置いた。旧い言葉は INFO「寄せる途中」として数え、組の判定は寄せた先の意味で行う。寄せる途中 でも strict の判定などが止まらない。Organization に定義の無い Property は 1 度だけ数え、定義が取れないときは「無い」と言わない。 組の判定を足した。product-core / platform / production_impact=direct は strict(§8)。Public な Repository は data_classification=public で、顧客の 分類が付いていれば Critical。core_version に値があれば知らせる(版の正本は versions.yaml)。 archived の判定は、archived を先に飛ばしていたため一度も動いていなかった。 先に判定するようにした。 実測: テスト 38 件 OK。決めた値の表で所見 0 件、いまの実測値で「寄せる 途中」18 件と「定義が無い」5 件だけ。判定を壊す 13 通りすべてで落ちた。 実 Organization への読み取り実行も同じ 23 件(Critical 0、Exception 6 件は 不変)。 Closes #33 Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 5057924 commit 4f6e04c

2 files changed

Lines changed: 401 additions & 28 deletions

File tree

‎scripts/ci/org_audit.py‎

Lines changed: 144 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -45,15 +45,58 @@
4545
".github/workflows/basic-checks.yml",
4646
)
4747

48-
#: repo_type ごとに期待する lifecycle。 違っていれば棚卸し漏れの可能性。
49-
#: 標準の Target ではなく、 **現行の運用(repository_management.md)**に合わせる。
50-
LIFECYCLE_BY_TYPE = {
51-
"org-config": ("production", "maintenance"),
52-
"docs": ("production", "maintenance"),
53-
"core": ("development", "production", "maintenance"),
54-
"customer": ("development", "production", "maintenance"),
48+
#: 標準(v1.2 §6)の Custom Properties と、 取りうる値。 **決めた Target を
49+
#: ここ 1 箇所に書く。** 監査はこれとの差を所見にする。
50+
#:
51+
#: 標準から変えたところ(development-docs の as_is_inventory.md §9.6 で決定):
52+
#: repo_type `unclassified` を残す。 分類を忘れた新しい
53+
#: Repository を見つける目印(既定値)
54+
#: data_classification `public` を足す。 Public な Repository を表す値が
55+
#: 標準に無かった
56+
#: `owner_team` は標準でも選択肢を閉じていない(「...」)ので、 値の種類は
57+
#: 見ない(None)。
58+
STANDARD = {
59+
"domain": ("visual-inspection", "robotics", "platform", "research",
60+
"internal", "other"),
61+
"repo_type": ("product-core", "application", "customer-project",
62+
"platform", "documentation", "delivery-control", "research",
63+
"unclassified"),
64+
"criticality": ("high", "medium", "low"),
65+
"lifecycle": ("active", "maintenance", "archived"),
66+
"owner_team": None,
67+
"governance_profile": ("strict", "standard", "research"),
68+
"data_classification": ("public", "internal", "customer-confidential",
69+
"restricted"),
70+
"production_impact": ("direct", "indirect", "none"),
5571
}
5672

73+
#: 定義が取れなくても Repository ごとに確かめる Property(前から必須)。
74+
ALWAYS_REQUIRED = ("repo_type", "lifecycle")
75+
76+
#: 標準へ寄せる前の言葉 → 寄せた先。 **移行を確かめたら消す。**
77+
#: 寄せる途中も、 組の判定(strict など)は寄せた先の意味で行う。
78+
#: None は寄せ先を Repository ごとに決めるもの(機械では決まらない)。
79+
#: lifecycle の development / production の区別は production_impact が持つ。
80+
LEGACY = {
81+
"repo_type": {"core": "product-core", "customer": "customer-project",
82+
"docs": "documentation", "org-config": "platform"},
83+
"lifecycle": {"development": "active", "production": "active"},
84+
"owner_team": {"developers": None, "maintainers": None},
85+
}
86+
87+
#: 版を持つ Property。 **値を入れない。** Core の版の正本は customer
88+
#: Repository の versions.yaml(commit SHA)。 Property にも書くと正本が
89+
#: 2 つになり、 片方だけ更新されて食い違う。
90+
VERSION_PROPERTIES = ("core_version",)
91+
92+
#: governance_profile を strict にするもの(標準 §8 の「主対象」)。
93+
#: production_impact=direct も strict(顧客 Repository が該当する)。
94+
STRICT_TYPES = ("product-core", "platform")
95+
96+
#: Public な Repository に付いてはいけない分類。 付いていれば、 顧客の値が
97+
#: 取り消せない形で外へ出ている可能性がある。
98+
NEVER_PUBLIC = ("customer-confidential", "restricted")
99+
57100
#: Plan で使えない機能。 **未実施と区別する。**
58101
PLAN_LIMITED = {
59102
"branch_protection": "Private Repository の branch protection は "
@@ -129,7 +172,8 @@ def audit_org(gh: Gh) -> dict:
129172
org = gh.get(f"/orgs/{ORG}", "Organization の Plan") or {}
130173
out = {
131174
"plan": (org.get("plan") or {}).get("name"),
132-
"properties": {},
175+
# None は「取れなかった」。 {}(定義が無い)と区別する
176+
"properties": None,
133177
"issue_types": [],
134178
"issue_fields": [],
135179
"teams": {},
@@ -208,6 +252,80 @@ def audit_repos(gh: Gh) -> dict:
208252
return out
209253

210254

255+
def _expected_properties(org: dict) -> tuple:
256+
"""Repository ごとに値を確かめる Property。
257+
258+
**Organization に定義が無いものは Repository ごとに数えない。** 定義が
259+
無いことを 1 度だけ数える(6 件に同じ所見を並べると、 直すものが
260+
1 つだと読み取れない)。 定義が取れなかったときは、 前から必須の
261+
ものだけを見る(取れないことを「無い」と言わない)。
262+
"""
263+
defined = org.get("properties")
264+
if defined is None:
265+
return ALWAYS_REQUIRED
266+
return tuple(k for k in STANDARD if k in defined or k in ALWAYS_REQUIRED)
267+
268+
269+
def _new_word(key: str, value):
270+
"""旧い言葉なら寄せた先(決まらなければ None)、 それ以外はそのまま。"""
271+
return LEGACY.get(key, {}).get(value, value)
272+
273+
274+
def _check_properties(name: str, info: dict, expected: tuple, add) -> dict:
275+
"""値を 1 つずつ確かめ、 標準の言葉に寄せた値を返す(組の判定に使う)。"""
276+
p = info["properties"]
277+
now = {}
278+
for key in expected:
279+
v = p.get(key)
280+
if not v:
281+
add(WARNING, "missing_property", name, f"{key} が未設定")
282+
continue
283+
if v in LEGACY.get(key, {}):
284+
to = LEGACY[key][v]
285+
add(INFO, "legacy_value", name,
286+
f"{key}={v} は標準の言葉へ寄せる途中"
287+
+ (f"(→ {to})" if to else "(寄せ先は Repository ごとに決める)"))
288+
if to:
289+
now[key] = to
290+
continue
291+
allowed = STANDARD[key]
292+
if allowed is not None and v not in allowed:
293+
add(WARNING, "unknown_value", name, f"{key}={v} は標準に無い値")
294+
continue
295+
now[key] = v
296+
for key in VERSION_PROPERTIES:
297+
if p.get(key):
298+
add(WARNING, "second_source_of_truth", name,
299+
f"{key}={p[key]}。 版の正本は versions.yaml"
300+
"(2 つにすると片方だけ更新されて食い違う)")
301+
return now
302+
303+
304+
def _check_combinations(name: str, info: dict, now: dict, add) -> None:
305+
"""値どうしの組。 **寄せた先の意味で**判定する。"""
306+
rt, gp = now.get("repo_type"), now.get("governance_profile")
307+
if rt == "unclassified":
308+
add(WARNING, "unclassified_repo", name,
309+
"repo_type が unclassified のまま(暫定値を放置しない)")
310+
if gp and gp != "strict":
311+
why = (f"repo_type={rt}" if rt in STRICT_TYPES else
312+
"production_impact=direct"
313+
if now.get("production_impact") == "direct" else None)
314+
if why:
315+
add(WARNING, "profile_mismatch", name,
316+
f"{why} なのに governance_profile={gp}(標準 §8 は strict)")
317+
dc = now.get("data_classification")
318+
if not info["private"] and dc and dc != "public":
319+
if dc in NEVER_PUBLIC:
320+
add(CRITICAL, "public_classification", name,
321+
f"Public なのに data_classification={dc}"
322+
"(顧客の値が外へ出ている可能性がある)")
323+
else:
324+
add(WARNING, "public_classification", name,
325+
f"Public なのに data_classification={dc}"
326+
"(Public に置けない値を置いてよいことになっている)")
327+
328+
211329
def classify(org: dict, repos: dict, local: dict) -> tuple:
212330
"""所見を組み立てる。 `(findings, exceptions)`。"""
213331
findings, exceptions = [], []
@@ -216,29 +334,24 @@ def add(sev, code, repo, msg):
216334
findings.append({"severity": sev, "code": code,
217335
"repo": repo, "message": msg})
218336

337+
expected = _expected_properties(org)
219338
for name, info in repos.items():
220339
if info["archived"]:
340+
# 棚卸し対象外。 ただし lifecycle が archived でなければ、
341+
# 一覧では稼働中に見えるので知らせる
342+
lc = _new_word("lifecycle", info["properties"].get("lifecycle"))
343+
if lc != "archived":
344+
add(WARNING, "archive_drift", name,
345+
"GitHub では archived だが lifecycle が archived でない")
221346
continue
222347
# --- 必須ファイル ---
223348
for f, present in info["files"].items():
224349
if not present:
225350
add(CRITICAL if f == "CLAUDE.md" else WARNING,
226351
"missing_required_file", name, f"{f} が無い")
227352
# --- Custom Properties ---
228-
p = info["properties"]
229-
for key in ("repo_type", "lifecycle"):
230-
if not p.get(key):
231-
add(WARNING, "missing_property", name, f"{key} が未設定")
232-
rt, lc = p.get("repo_type"), p.get("lifecycle")
233-
if rt == "unclassified":
234-
add(WARNING, "unclassified_repo", name,
235-
"repo_type が unclassified のまま(暫定値を放置しない)")
236-
if rt in LIFECYCLE_BY_TYPE and lc and lc not in LIFECYCLE_BY_TYPE[rt]:
237-
add(INFO, "lifecycle_mismatch", name,
238-
f"repo_type={rt} に対して lifecycle={lc}")
239-
if info["archived"] and lc == "active":
240-
add(WARNING, "archive_drift", name,
241-
"GitHub では archived だが lifecycle が archived でない")
353+
now = _check_properties(name, info, expected, add)
354+
_check_combinations(name, info, now, add)
242355
# --- 保護 ---
243356
for cap in info["plan_limited"]:
244357
exceptions.append({"repo": name, "capability": cap,
@@ -262,6 +375,12 @@ def add(sev, code, repo, msg):
262375
f"書いているが、 実行すると {actual} ケース")
263376

264377
# --- Organization ---
378+
defined = org.get("properties")
379+
if defined is not None:
380+
for key in STANDARD:
381+
if key not in defined:
382+
add(WARNING, "missing_property_definition", f"(org) {ORG}",
383+
f"標準の Property {key} が定義されていない")
265384
if org.get("plan") in ("free",):
266385
exceptions.append({
267386
"repo": f"(org) {ORG}", "capability": "org_rulesets",
@@ -299,7 +418,9 @@ def render(org, repos, findings, exceptions, unknown) -> int:
299418
"""人が読む形。 戻り値は Critical の件数。"""
300419
print(f"Organization: {ORG} Plan: {org.get('plan') or '不明'} "
301420
f"Repository: {len(repos)} 件")
302-
print(f"Custom Properties: {', '.join(org['properties']) or '不明'}")
421+
props = org.get("properties")
422+
print("Custom Properties: "
423+
+ ("不明" if props is None else (", ".join(props) or "なし")))
303424
print(f"Issue Types: {', '.join(org['issue_types']) or '不明'}")
304425
print(f"Issue Fields: {', '.join(org['issue_fields']) or '不明'}")
305426
for slug, names in (org.get("teams") or {}).items():

0 commit comments

Comments
 (0)