DongHyeonkaandClaude Opus 5
1f04117bbf
글감 1,001개 중 제1부(§3~§11) 앵커를 하나라도 가진 것은 112개뿐이었다. 나머지 889개는
제2부 모듈 분석 65편의 절 제목에서 나온 것이고, 그것이 재판정이 필요했던 이유다.
주제 44 → 16 (43개가 독자 질문 없이 있었다. 지금은 전부 있다)
글감 1,001 → 123 (제1부 앵커 112 + 제1부가 채택했는데 비어 있던 자리 11)
후보 965 → 1,088 · PENDING 905 → 0
error 3,042 → 0
내려온 889개는 후보 대장에 KEEP_IN_SSOT 로 남는다 — 버린 것이 아니라 분석에 남기고 독립
기록으로 만들지 않기로 한 것이다. 그 글감을 받치던 기록 파일 828개는 지웠다. 계약이 정본이고,
파일이 남아 있다는 이유로 계약에서 뺀 주제가 되살아나면 안 된다. 이력에는 그대로 있다 —
git checkout a0ca2bb -- <경로>.
제1부가 채택했는데 글감이 없던 자리 열하나를 채웠다: mongo high-water mark 가 재전달 이벤트를
삼킨 P1, admin plane 이 가드만 켜고 서비스는 켜지 않은 것과 그 짝인 결정, 실패 어휘 세 층과
SQLState 매트릭스 병합 규칙, 부하 아래에서만 새는 admission 경계, 발행 증거와 완료 판정의
분리, keyset·JSONB 결정 둘.
Concept 17개에 basis-version 을 채우고, 계약 제목과 기록 제목이 갈라져 있던 23건을 기록 쪽에
맞췄다. candidateScope 에 excludedAnchorPattern 을 적어 제2부 앵커만 가진 글감이 다시 올라올
수 없게 한다.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
229 lines
12 KiB
Python
Executable File
229 lines
12 KiB
Python
Executable File
#!/usr/bin/env python3
|
|
"""프로젝트 문서 폴더가 같은 모양인지 본다.
|
|
|
|
프로젝트 하나가 폴더 하나다. 그 안의 배치는 `docs/_templates/` 가 정본이고
|
|
CLAUDE.md 「문서 위치」가 같은 것을 말로 적은 것이다.
|
|
|
|
docs/<프로젝트>/
|
|
├── source/ 밖에서 가져온 원본
|
|
├── state.json · source-index.md
|
|
├── analysis/ · notes/ · checkpoints/
|
|
├── final/ SSOT
|
|
│ ├── document.md
|
|
│ ├── assets/<이름>/ 그림 하나가 폴더 하나
|
|
│ ├── assets/tech-log-studio/ Studio 에 올릴 표현물
|
|
│ ├── .techviz/<이름>/ 그림의 정본
|
|
│ └── evidence/{raw,meta,rendered,browser}
|
|
└── tech-log-studio/
|
|
|
|
python3 scripts/verify-project-layout.py [프로젝트 ...] [--strict] [--samples N]
|
|
|
|
**SVG 는 정본이 아니다.** `.techviz/<이름>/` 없이 남은 그림은 다시 만들 수 없다.
|
|
이 검사기는 그것을 세지만 실패로 만들지는 않는다 — 언제 다시 만들지는 편집 판단이다.
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
import argparse
|
|
import glob
|
|
import json
|
|
import os
|
|
import re
|
|
import sys
|
|
|
|
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
|
from techlog import Report # noqa: E402
|
|
|
|
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
|
|
|
EVIDENCE_DIRS = {"raw", "meta", "rendered", "browser"}
|
|
# 분석하는 동안에만 있는 작업 재료. 분석이 끝나면 final/document.md 로 합치고 지운다.
|
|
# 끝난 프로젝트의 폴더는 final/ 과 tech-log-studio/ (밖에서 가져왔으면 source/) 뿐이다
|
|
WORKING_MATERIAL = ("analysis", "notes", "checkpoints", "state.json", "source-index.md")
|
|
# 밖에서 가져올 때만 있는 재료. final/ 이 그 내용을 담으면 원본은 사본이 된다
|
|
IMPORT_MATERIAL = "source"
|
|
# Studio 에 올릴 표현물이 사는 곳. 여기 SVG 는 그림의 정본을 따로 갖지 않는다
|
|
STUDIO_ASSETS = "tech-log-studio"
|
|
|
|
|
|
def _svg_stems(assets: str) -> list[tuple[str, str]]:
|
|
"""(stem, 상대경로). assets/tech-log-studio/ 아래는 표현물이라 뺀다."""
|
|
out = []
|
|
for path in sorted(glob.glob(os.path.join(assets, "**", "*.svg"), recursive=True)):
|
|
rel = os.path.relpath(path, assets)
|
|
if rel.split(os.sep)[0] == STUDIO_ASSETS:
|
|
continue
|
|
out.append((os.path.basename(path)[:-4], rel))
|
|
return out
|
|
|
|
|
|
def verify(project: str) -> Report:
|
|
rep = Report(project)
|
|
base = os.path.join(ROOT, "docs", project)
|
|
final = os.path.join(base, "final")
|
|
studio = os.path.join(base, "tech-log-studio")
|
|
|
|
# ── SSOT ───────────────────────────────────────────────────────
|
|
if not os.path.exists(os.path.join(final, "document.md")):
|
|
rep.error("final/document.md 가 없다", project)
|
|
return rep
|
|
|
|
# ── 분석 작업 재료 ─────────────────────────────────────────────
|
|
# 분석 중이면 있어야 하고, 끝났으면 final 로 합치고 없어야 한다
|
|
left = [n for n in WORKING_MATERIAL if os.path.exists(os.path.join(base, n))]
|
|
status = None
|
|
state_path = os.path.join(base, "state.json")
|
|
if os.path.exists(state_path):
|
|
try:
|
|
status = json.load(open(state_path, encoding="utf-8")).get("analysisStatus")
|
|
except (json.JSONDecodeError, OSError):
|
|
rep.error("state.json 을 읽지 못했다", project)
|
|
if os.path.isdir(os.path.join(base, "analysis")):
|
|
for name in ("state.json", "source-index.md"):
|
|
if not os.path.exists(os.path.join(base, name)):
|
|
rep.error(f"analysis/ 가 있는데 {name} 이 없다", project)
|
|
if left:
|
|
rep.facts["analysis"] = status or "진행 중"
|
|
if status == "COMPLETE":
|
|
rep.warn("분석이 끝났는데 작업 재료가 남아 있다",
|
|
f"{' · '.join(left)} — final/document.md 로 합치고 지운다")
|
|
imported = os.path.join(base, IMPORT_MATERIAL)
|
|
if os.path.isdir(imported):
|
|
n = sum(1 for _ in glob.iglob(os.path.join(imported, "**", "*"), recursive=True))
|
|
rep.warn("반입 원본이 남아 있다",
|
|
f"source/ {n}개 — final/ 이 그 내용을 담고 있으면 사본이다")
|
|
|
|
# ── 증거 ───────────────────────────────────────────────────────
|
|
evidence = os.path.join(final, "evidence")
|
|
if os.path.isdir(evidence):
|
|
for name in sorted(os.listdir(evidence)):
|
|
if os.path.isdir(os.path.join(evidence, name)) and name not in EVIDENCE_DIRS:
|
|
rep.error("evidence 하위 폴더 이름이 규약 밖이다",
|
|
f"final/evidence/{name} — raw · meta · rendered · browser")
|
|
raw = os.path.join(evidence, "raw")
|
|
counts = {}
|
|
for name in EVIDENCE_DIRS:
|
|
d = os.path.join(evidence, name)
|
|
counts[name] = len(glob.glob(os.path.join(d, "**", "*"), recursive=True)) \
|
|
if os.path.isdir(d) else 0
|
|
rep.facts["evidence"] = counts
|
|
# 6개월 뒤에 파일 이름만으로는 못 읽는다
|
|
for d in sorted(glob.glob(os.path.join(raw, "*"))):
|
|
if os.path.isdir(d) and not os.path.exists(os.path.join(d, "README.txt")):
|
|
rep.warn("evidence/raw 하위 폴더에 README.txt 가 없다",
|
|
os.path.relpath(d, base))
|
|
if counts.get("rendered") and not counts.get("meta"):
|
|
rep.error("터미널 SVG 는 있는데 meta 가 없다",
|
|
"실행한 명령의 원문과 메타데이터가 정본이다")
|
|
elif counts.get("raw") and not counts.get("meta"):
|
|
rep.warn("raw 는 있는데 meta 가 없다",
|
|
f"raw {counts['raw']}건 — command·cwd·executedAt·exitCode·revision 이 없다")
|
|
|
|
# ── 그림 ───────────────────────────────────────────────────────
|
|
assets = os.path.join(final, "assets")
|
|
techviz = os.path.join(final, ".techviz")
|
|
if os.path.isdir(assets):
|
|
# 정본은 그림 이름 폴더다. .techviz 에 놓인 파일은 정본이 아니다
|
|
sources = {n for n in os.listdir(techviz)
|
|
if os.path.isdir(os.path.join(techviz, n))} \
|
|
if os.path.isdir(techviz) else set()
|
|
svgs = _svg_stems(assets)
|
|
rep.facts["diagrams"] = {"svg": len(svgs), "techviz": len(sources)}
|
|
for stem, rel in svgs:
|
|
if stem not in sources:
|
|
rep.warn("techviz 정본이 없는 그림", f"final/assets/{rel}")
|
|
if os.path.dirname(rel) in ("", "diagrams"):
|
|
rep.warn("그림이 이름 폴더로 묶여 있지 않다", f"final/assets/{rel}")
|
|
stems = {s for s, _ in svgs}
|
|
for name in sorted(sources - stems):
|
|
rep.warn("정본만 있고 그림이 없다", f"final/.techviz/{name}")
|
|
|
|
# ── 기록이 가리키는 그림 ───────────────────────────────────────
|
|
if os.path.isdir(studio):
|
|
wrong = 0
|
|
broken = 0
|
|
records = 0
|
|
cited_figures: set[str] = set()
|
|
cited_evidence: set[str] = set()
|
|
for path in sorted(glob.glob(os.path.join(studio, "*", "*", "*.md"))):
|
|
if os.path.basename(os.path.dirname(os.path.dirname(path))).startswith("_"):
|
|
continue
|
|
records += 1
|
|
text = open(path, encoding="utf-8").read()
|
|
for m in re.finditer(r"^ file: (\S+)$", text, re.M):
|
|
target = os.path.normpath(os.path.join(os.path.dirname(path), m.group(1)))
|
|
# 이름이 같으면 같은 그림이다. tech-log-studio/ 사본도 SSOT 원본을 쓴 것으로 센다
|
|
cited_figures.add(os.path.basename(target)[:-4]
|
|
if target.endswith(".svg") else os.path.basename(target))
|
|
if not os.path.exists(target):
|
|
broken += 1
|
|
if broken <= 5:
|
|
rep.error("기록이 가리키는 그림이 없다",
|
|
f"{os.path.relpath(path, base)} — {m.group(1)}")
|
|
continue
|
|
if f"assets{os.sep}{STUDIO_ASSETS}{os.sep}" not in target:
|
|
wrong += 1
|
|
for m in re.finditer(r"^ - (\.\./\S*final/evidence/\S+)$", text, re.M):
|
|
cited_evidence.add(
|
|
os.path.normpath(os.path.join(os.path.dirname(path), m.group(1))))
|
|
if wrong:
|
|
rep.warn("Studio 자산이 assets/tech-log-studio/ 밖에 있다",
|
|
f"{wrong}건 — 다른 프로젝트는 전부 그 폴더를 쓴다")
|
|
|
|
# ── SSOT 가 만들어 둔 것을 기록이 쓰고 있나 ────────────────────
|
|
# 기록이 하나도 없는 프로젝트는 아직 안 쓴 것이지 안 쓰기로 한 것이 아니다
|
|
if records:
|
|
unused_figures = [rel for stem, rel in _svg_stems(assets)
|
|
if stem not in cited_figures]
|
|
for rel in unused_figures:
|
|
rep.warn("기록이 쓰지 않는 SSOT 그림", f"final/assets/{rel}")
|
|
unused_evidence = [
|
|
p for p in sorted(glob.glob(os.path.join(evidence, "raw", "**", "*"),
|
|
recursive=True))
|
|
if os.path.isfile(p)
|
|
and os.path.basename(p) != "README.txt"
|
|
and p not in cited_evidence]
|
|
for p_ev in unused_evidence:
|
|
rep.warn("기록이 인용하지 않는 raw 증거", os.path.relpath(p_ev, base))
|
|
return rep
|
|
|
|
|
|
def render(rep: Report, samples: int) -> None:
|
|
facts = " · ".join(f"{k}={json.dumps(v, ensure_ascii=False) if isinstance(v, dict) else v}"
|
|
for k, v in rep.facts.items())
|
|
print(f" [{rep.project}] {facts or '—'}")
|
|
for label, bucket, mark in (("error", rep.errors, "✗"), ("warn", rep.warns, "!")):
|
|
for rule, details in sorted(bucket.items(), key=lambda kv: -len(kv[1])):
|
|
print(f" {mark} {label} {len(details):>4} {rule}")
|
|
for d in details[:samples]:
|
|
if d:
|
|
print(f" · {d}")
|
|
if samples and len(details) > samples:
|
|
print(f" … 외 {len(details) - samples}건")
|
|
|
|
|
|
def main() -> int:
|
|
ap = argparse.ArgumentParser(description="프로젝트 문서 폴더 배치를 본다.")
|
|
ap.add_argument("projects", nargs="*")
|
|
ap.add_argument("--samples", type=int, default=3)
|
|
ap.add_argument("--strict", action="store_true")
|
|
args = ap.parse_args()
|
|
|
|
projects = args.projects or sorted(
|
|
name for name in (
|
|
os.path.basename(os.path.dirname(os.path.dirname(p)))
|
|
for p in glob.glob(os.path.join(ROOT, "docs/*/final/document.md"))
|
|
) if not name.startswith("_")
|
|
)
|
|
reports = [verify(p) for p in projects]
|
|
e = sum(r.error_count for r in reports)
|
|
w = sum(r.warn_count for r in reports)
|
|
print(f"PROJECT LAYOUT: {'FAIL' if e or (args.strict and w) else 'PASS'}"
|
|
f" — 프로젝트 {len(reports)} · error {e} · warn {w}")
|
|
for r in reports:
|
|
render(r, args.samples)
|
|
return 1 if e or (args.strict and w) else 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
raise SystemExit(main())
|