docs(clean-architecture-backend-template): 제1부가 채택한 것만 글감으로 남기고 다시 고른다
글감 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>
This commit is contained in:
DongHyeonka
co-authored by
Claude Opus 5
Claude Opus 5
parent
a0ca2bb72a
commit
1f04117bbf
@@ -29,7 +29,8 @@ import techlog # noqa: E402
|
||||
from techlog import KINDS # noqa: E402
|
||||
|
||||
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
DERIVED = ("file", "publication", "status", "studioId", "assets", "evidenceFiles")
|
||||
DERIVED = ("file", "publication", "status", "studioId", "assets", "assetFiles",
|
||||
"evidenceFiles")
|
||||
|
||||
|
||||
def front_matter(path: str) -> tuple[dict, str]:
|
||||
@@ -84,6 +85,10 @@ def build(project: str) -> tuple[dict | None, list[str]]:
|
||||
"studioId": studio_id,
|
||||
"publication": "게시됨" if studio_id else "초안",
|
||||
"assets": re.findall(r"^ - key: (\S+)", text, re.M),
|
||||
# 배정한 SSOT 그림을 기록이 실제로 쓰는지 대조하려면 key 가 아니라 파일이 필요하다
|
||||
"assetFiles": [os.path.basename(f)[:-4] if f.endswith(".svg")
|
||||
else os.path.basename(f)
|
||||
for f in re.findall(r"^ file: (\S+)", text, re.M)],
|
||||
"evidenceFiles": re.findall(r"^ - (\.\./\S+)", text, re.M),
|
||||
})
|
||||
used.add(key)
|
||||
|
||||
@@ -109,7 +109,8 @@ class Fixture:
|
||||
def read(self) -> dict:
|
||||
return json.load(open(self.index_path, encoding="utf-8"))
|
||||
|
||||
def diagram(self, name: str, *, bundled: bool = True, with_source: bool = True) -> None:
|
||||
def diagram(self, name: str, *, bundled: bool = True, with_source: bool = True,
|
||||
cited: bool = False) -> None:
|
||||
assets = os.path.join(self.base, "final/assets")
|
||||
target = os.path.join(assets, name) if bundled else assets
|
||||
os.makedirs(target, exist_ok=True)
|
||||
@@ -118,6 +119,19 @@ class Fixture:
|
||||
src = os.path.join(self.base, "final/.techviz", name)
|
||||
os.makedirs(src, exist_ok=True)
|
||||
open(os.path.join(src, "spec.json"), "w", encoding="utf-8").write("{}")
|
||||
if cited:
|
||||
self.cite(name)
|
||||
|
||||
def cite(self, name: str) -> None:
|
||||
"""그림을 Studio 자리로 복사하고 기록이 그것을 가리키게 한다 — 실제 작업 순서다."""
|
||||
studio_assets = os.path.join(self.base, "final/assets/tech-log-studio")
|
||||
os.makedirs(studio_assets, exist_ok=True)
|
||||
open(os.path.join(studio_assets, f"{name}.svg"), "w", encoding="utf-8").write("<svg/>")
|
||||
record = os.path.join(self.studio, "session-custody/case/case-session-split.md")
|
||||
open(record, "w", encoding="utf-8").write(RECORD.replace(
|
||||
"status: 게시 전\n",
|
||||
f"status: 게시 전\nassets:\n - key: {name}\n"
|
||||
f" file: ../../../final/assets/tech-log-studio/{name}.svg\n"))
|
||||
|
||||
def __enter__(self):
|
||||
self._saved = (verifier.ROOT, builder.ROOT, layout.ROOT)
|
||||
@@ -293,6 +307,36 @@ class ContractTest(unittest.TestCase):
|
||||
self.assertIn("slug 가 두 글감에 있다", verifier.verify("fixture").errors)
|
||||
|
||||
|
||||
class SsotAssetTest(unittest.TestCase):
|
||||
"""SSOT 가 이미 그린 그림을 글감에 배정하고, 기록이 그것을 쓰는지 본다."""
|
||||
|
||||
def _verify(self, fx):
|
||||
with contextlib.redirect_stdout(io.StringIO()):
|
||||
builder.main(["build", "fixture"])
|
||||
return verifier.verify("fixture")
|
||||
|
||||
def test_assigned_diagram_the_record_uses_is_clean(self):
|
||||
with Fixture(mutate(**{"ssot-assets": ["session-custody-map"]})) as fx:
|
||||
fx.diagram("session-custody-map", cited=True)
|
||||
self.assertEqual(self._verify(fx).errors, {})
|
||||
|
||||
def test_assigned_diagram_the_record_never_uses_is_an_error(self):
|
||||
with Fixture(mutate(**{"ssot-assets": ["session-custody-map"]})) as fx:
|
||||
fx.diagram("session-custody-map")
|
||||
self.assertIn("배정한 SSOT 그림을 기록이 쓰지 않는다", self._verify(fx).errors)
|
||||
|
||||
def test_assigned_diagram_that_does_not_exist_is_an_error(self):
|
||||
with Fixture(mutate(**{"ssot-assets": ["never-drawn"]})) as fx:
|
||||
self.assertIn("배정한 SSOT 그림이 final/assets 에 없다", self._verify(fx).errors)
|
||||
|
||||
def test_assigned_evidence_the_record_never_cites_is_an_error(self):
|
||||
with Fixture(mutate(**{"ssot-evidence": ["raw/explain/plan-a.txt"]})) as fx:
|
||||
raw = os.path.join(fx.base, "final/evidence/raw/explain")
|
||||
os.makedirs(raw)
|
||||
open(os.path.join(raw, "plan-a.txt"), "w", encoding="utf-8").write("EXPLAIN\n")
|
||||
self.assertIn("배정한 SSOT 증거를 기록이 쓰지 않는다", self._verify(fx).errors)
|
||||
|
||||
|
||||
class BuildTest(unittest.TestCase):
|
||||
def test_derived_fields_come_from_the_record_file(self):
|
||||
with Fixture():
|
||||
@@ -330,11 +374,23 @@ class BuildTest(unittest.TestCase):
|
||||
class LayoutTest(unittest.TestCase):
|
||||
def test_a_diagram_with_its_source_is_clean(self):
|
||||
with Fixture() as fx:
|
||||
fx.diagram("session-custody-map")
|
||||
fx.diagram("session-custody-map", cited=True)
|
||||
report = layout.verify("fixture")
|
||||
self.assertEqual(report.errors, {}, report.errors)
|
||||
self.assertEqual(report.warns, {}, report.warns)
|
||||
|
||||
def test_ssot_diagram_no_record_cites_is_counted(self):
|
||||
# 배정하지 않은 그림은 글을 쓸 때 새로 그리게 된다. keycloak 이 그렇게 됐다
|
||||
with Fixture() as fx:
|
||||
fx.diagram("session-custody-map")
|
||||
self.assertIn("기록이 쓰지 않는 SSOT 그림", layout.verify("fixture").warns)
|
||||
|
||||
def test_a_project_with_no_record_yet_is_not_counted(self):
|
||||
# 아직 안 쓴 것이지 안 쓰기로 한 것이 아니다
|
||||
with Fixture(with_record=False) as fx:
|
||||
fx.diagram("session-custody-map")
|
||||
self.assertNotIn("기록이 쓰지 않는 SSOT 그림", layout.verify("fixture").warns)
|
||||
|
||||
def test_svg_without_a_techviz_source_is_counted(self):
|
||||
with Fixture() as fx:
|
||||
fx.diagram("hand-drawn", with_source=False)
|
||||
|
||||
@@ -141,12 +141,19 @@ def verify(project: str) -> Report:
|
||||
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:
|
||||
@@ -155,9 +162,28 @@ def verify(project: str) -> Report:
|
||||
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
|
||||
|
||||
|
||||
|
||||
@@ -233,6 +233,25 @@ def verify(project: str) -> Report:
|
||||
rep.error("decision-status 값이 계약에 없다", f"{where} — {status}")
|
||||
if has_contract and not _values(node, "relations"):
|
||||
rep.warn("관계가 없는 노드", where)
|
||||
|
||||
# ── SSOT 가 이미 가진 그림·증거를 이 글감에 배정했는가 ─────────
|
||||
# 배정만 해 두고 기록이 쓰지 않으면 글 쓸 때 새로 그리게 된다. 그것을 여기서 센다
|
||||
for name in _values(node, "ssot-assets"):
|
||||
stem = os.path.basename(name)[:-4] if name.endswith(".svg") else os.path.basename(name)
|
||||
if not glob.glob(os.path.join(base, "final", "assets", "**", f"{stem}.svg"),
|
||||
recursive=True):
|
||||
rep.error("배정한 SSOT 그림이 final/assets 에 없다", f"{where} — {name}")
|
||||
elif node.get("file") and stem not in (node.get("assetFiles") or []):
|
||||
rep.error("배정한 SSOT 그림을 기록이 쓰지 않는다",
|
||||
f"{where} — {stem} — 기록의 assets 가 가리키지 않는다")
|
||||
for name in _values(node, "ssot-evidence"):
|
||||
rel_ev = name[len("final/evidence/"):] if name.startswith("final/evidence/") else name
|
||||
if not os.path.exists(os.path.join(base, "final", "evidence", rel_ev)):
|
||||
rep.error("배정한 SSOT 증거가 final/evidence 에 없다", f"{where} — {name}")
|
||||
elif node.get("file") and not any(
|
||||
f.endswith(rel_ev) for f in (node.get("evidenceFiles") or [])):
|
||||
rep.error("배정한 SSOT 증거를 기록이 쓰지 않는다",
|
||||
f"{where} — {rel_ev} — 기록의 evidence 가 가리키지 않는다")
|
||||
anchors = " ".join(_values(node, "source"))
|
||||
if anchors and ssot_rel not in anchors:
|
||||
rep.warn("근거가 SSOT 밖에만 있다", f"{where} — {anchors[:60]}")
|
||||
|
||||
Reference in New Issue
Block a user