diff --git a/scripts/studio-save.py b/scripts/studio-save.py index 3b9827d..bde50e7 100644 --- a/scripts/studio-save.py +++ b/scripts/studio-save.py @@ -59,8 +59,16 @@ REPLAYED_HEADER = "Idempotency-Replayed" FIELD_MAP = { "CASE": {"문제": "problem", "결론": "conclusion", "검증 환경": "environment", "재현 조건": "reproduction", "본문": "bodyMarkdown"}, + # **`basisVersion` 은 절이 아니라 frontmatter 에 있다.** `required` 인데 어댑터가 + # 절만 봐서 빠졌다 — `422 /basisVersion must not be null` (C 가 V-009 의 + # `P-CONCEPT-01`·`02` 에서 맞았다). `_concept_shape` 가 frontmatter 에서 가져온다 "CONCEPT": {"본문": "bodyMarkdown"}, - "REFERENCE": {"목적": "purpose", "규칙": "rules", "적용 조건": "appliesWhen", + # **REFERENCE 는 셋이 한꺼번에 틀려 있었다** (`studio-v1.yaml:955-963`). + # 이름 — `appliesWhen` 이 아니라 **`applyWhen`** 이다. nextValidation 과 같은 자리다 + # 모양 — `rules` 는 `ReferenceRule` 배열, `applyWhen`·`exceptions`·`examples` 는 + # `OrderedText` 배열이다. 문자열로 보내면 MismatchedInputException 이다 + # 없는 칸 — `verifiedOn` 이 required 인데 아예 없었다 + "REFERENCE": {"목적": "purpose", "규칙": "rules", "적용 조건": "applyWhen", "예외": "exceptions", "예시": "examples"}, # **QUESTION 의 칸은 문자열이 아니다.** `facts`·`assumptions`·`unknowns`·`constraints` 는 # `OrderedText` 배열이고 `options` 는 `QuestionOption` 배열이며, 마지막 칸의 이름은 @@ -342,6 +350,49 @@ def _question_options(chunk: str) -> list[dict]: return out +def _ordered(slug: str, field: str, raw) -> list[dict]: + """`- ` 항목을 `OrderedText` 배열로. 빈 칸도 `[]` 로 남긴다 — required 다.""" + items = _bullets(raw) if isinstance(raw, str) else [] + return [{"id": _ordered_id(slug, field, i), "text": t, "order": i} + for i, t in enumerate(items)] + + +def _titled(slug: str, field: str, raw) -> list[dict]: + """`### N. 제목` 과 그 아래 문단을 `{제목, 본문}` 쌍으로.""" + out: list[dict] = [] + parts = re.split(r"^###\s+(.+)$", raw, flags=re.M) if isinstance(raw, str) else [] + for i in range(1, len(parts), 2): + title = re.sub(r"^\d+[.)]\s*", "", parts[i].strip()) + out.append({"id": _ordered_id(slug, field, len(out)), "title": title[:120], + "body": parts[i + 1].strip(), "order": len(out)}) + return out + + +def _concept_shape(doc: dict, fm: dict) -> dict: + """`basisVersion` 은 frontmatter 에 있다. 절만 보면 빠진다.""" + basis = (fm.get("basisVersion") or "").strip() + if len(basis) > 120: + # **조용히 자르지 않는다.** 무엇을 보고 쓴 글인지가 잘리면 읽는 사람이 모른다 + raise Refused(f"basisVersion 이 {len(basis)}자다. 상한 120자 " + f"(studio-v1.yaml:990) — 기록에서 줄인다") + doc["basisVersion"] = basis # 비워도 되지만 **빠지면 안 된다** + return doc + + +def _reference_shape(doc: dict, fm: dict) -> dict: + """REFERENCE 의 칸을 서버 스키마의 모양으로. `purpose` 만 문자열이다.""" + slug = doc.get("slug") or "" + doc["rules"] = _titled(slug, "rules", doc.get("rules")) + for field in ("applyWhen", "exceptions", "examples"): + doc[field] = _ordered(slug, field, doc.get(field)) + if not isinstance(doc.get("purpose"), str): + doc["purpose"] = "" + # required 이고 `[string, "null"]` 이다. **기록이 안 적었으면 지어내지 않는다** + on = (fm.get("verifiedOn") or fm.get("lastVerifiedOn") or "").strip() + doc["verifiedOn"] = on or None + return doc + + def _question_shape(doc: dict, fm: dict) -> dict: """QUESTION 의 칸을 서버 스키마의 **모양**으로 바꾼다. @@ -349,11 +400,8 @@ def _question_shape(doc: dict, fm: dict) -> dict: """ slug = doc.get("slug") or "" for field in ("facts", "assumptions", "unknowns", "constraints"): - raw = doc.get(field) - items = _bullets(raw) if isinstance(raw, str) else [] # **빈 배열이지 빠뜨리는 것이 아니다.** 넷 다 required 다 (`studio-v1.yaml:1023`) - doc[field] = [{"id": _ordered_id(slug, field, i), "text": t, "order": i} - for i, t in enumerate(items)] + doc[field] = _ordered(slug, field, doc.get(field)) raw = doc.get("options") opts = _question_options(raw) if isinstance(raw, str) else [] doc["options"] = [{"id": _ordered_id(slug, "options", i), "title": o["title"], @@ -405,6 +453,10 @@ def build_input(record_path: str) -> dict: doc["lastVerifiedOn"] = fm.get("lastVerifiedOn") or None if kind == "QUESTION": doc = _question_shape(doc, fm) + if kind == "CONCEPT": + doc = _concept_shape(doc, fm) + if kind == "REFERENCE": + doc = _reference_shape(doc, fm) return doc @@ -777,6 +829,26 @@ NOT_COMPARED = { "relations": "서버가 순서를 다시 매긴다. 목록 비교는 따로 만들어야 한다", } +# 항목 배열의 **`id` 만** 못 본다. 보내는 것은 `uuid5(slug|칸|순번)` 이고 서버는 저장하면서 +# 새 uuid4 를 발급한다 — C 가 V-009 의 `P-QUESTION-02` 에서 갈랐다(`text`·`order` 는 같고 +# `id` 만 달랐다). 칸 전체를 빼면 **모든 QUESTION·REFERENCE 저장이 「차이 있음」으로 보고되거나 +# 반대로 항목이 빠진 것을 못 보게 된다.** 그래서 `id` 만 빼고 나머지는 계속 대조한다. +ITEM_ID_REISSUED = { + "facts", "assumptions", "unknowns", "constraints", "options", + "rules", "applyWhen", "exceptions", "examples", "consequences", +} +ITEM_ID_NOTE = ("항목 `id` 만 못 본다 — 보낸 것은 uuid5 이고 서버가 새 uuid4 를 발급한다. " + "`text`·`title`·`body`·`order` 는 그대로 대조한다 — 항목이 빠지거나 " + "순서가 바뀌는 것은 여전히 걸린다") + + +def _without_item_ids(value): + """항목 배열에서 `id` 만 뺀다. 나머지 칸은 그대로 둔다.""" + if not isinstance(value, list): + return value + return [{k: v for k, v in x.items() if k != "id"} if isinstance(x, dict) else x + for x in value] + def normalize(value) -> str: """되읽어 견주기 전에 줄 끝 공백과 줄바꿈 표기만 맞춘다. @@ -804,10 +876,16 @@ def compare_saved(sent: dict, fetched: dict) -> dict: 적이 있다. 앞이 같고 뒤가 없는 모양은 바뀐 것과 다르게 읽힌다. """ differences, whitespace_only, truncated = [], [], [] + item_ids_skipped = [] for field, want in sent.items(): if field in NOT_COMPARED: continue got = fetched.get(field) + if field in ITEM_ID_REISSUED and isinstance(want, list): + # **빼먹은 것이 아니라 못 보는 것**이므로 무엇을 왜 안 보는지 값에 적는다 + item_ids_skipped.append({"field": field, "items": len(want), + "note": ITEM_ID_NOTE}) + want, got = _without_item_ids(want), _without_item_ids(got) nw, ng = normalize(want), normalize(got) raw_same = str(want or "") == str(got or "") if nw != ng: @@ -828,6 +906,7 @@ def compare_saved(sent: dict, fetched: dict) -> dict: "truncated": truncated, "whitespaceOnly": whitespace_only, "notCompared": NOT_COMPARED, + "itemIdsNotCompared": item_ids_skipped, "unexpected": unexpected, "comparedFields": [f for f in sent if f not in NOT_COMPARED], } diff --git a/scripts/tests/test_studio_save.py b/scripts/tests/test_studio_save.py index d50482f..5782cc5 100644 --- a/scripts/tests/test_studio_save.py +++ b/scripts/tests/test_studio_save.py @@ -667,6 +667,72 @@ class HarnessTestPlanTest(unittest.TestCase): out = ss._question_shape({"slug": "s"}, {}) self.assertIsNone(out["questionStatus"]) + def test_concept_carries_basis_version_from_frontmatter(self): + """`basisVersion` 은 절이 아니라 frontmatter 에 있다. required 라 빠지면 422 다 + (C 의 `P-CONCEPT-01`·`02`).""" + import tempfile, os + with tempfile.TemporaryDirectory() as d: + f = os.path.join(d, "c.md") + open(f, "w", encoding="utf-8").write( + "---\nkind: CONCEPT\ntitle: t\nslug: s\n" + "basisVersion: Keycloak 26.7.0\n---\n\n## 본문\n\n가.\n") + doc = ss.build_input(f) + self.assertEqual("Keycloak 26.7.0", doc["basisVersion"]) + + def test_concept_refuses_an_overlong_basis_version(self): + """상한 120자. **조용히 자르지 않는다** — 무엇을 보고 쓴 글인지가 잘리면 모른다.""" + with self.assertRaises(ss.Refused): + ss._concept_shape({}, {"basisVersion": "가" * 121}) + + def test_concept_keeps_the_field_even_when_empty(self): + """비워도 되지만 **빠지면 안 된다**.""" + self.assertEqual("", ss._concept_shape({}, {})["basisVersion"]) + + def test_reference_uses_the_contract_field_name(self): + """계약은 `applyWhen` 이다. 어댑터가 `appliesWhen` 을 보내고 있었다 — + `nextVerification` → `nextValidation` 과 같은 자리다.""" + doc = ss._reference_shape({"slug": "s", "applyWhen": "- 하나"}, {}) + self.assertIn("applyWhen", doc) + self.assertNotIn("appliesWhen", doc) + self.assertEqual("하나", doc["applyWhen"][0]["text"]) + + def test_reference_shapes_are_arrays(self): + """`rules` 는 `ReferenceRule`, 나머지 셋은 `OrderedText` 다. `purpose` 만 문자열.""" + doc = ss._reference_shape( + {"slug": "s", "purpose": "무엇을 위한 것인가", "rules": "### 1. 첫 규칙\n\n몸통이다.", + "applyWhen": "- 하나", "exceptions": "", "examples": ""}, {}) + self.assertEqual({"id", "title", "body", "order"}, set(doc["rules"][0])) + self.assertEqual("첫 규칙", doc["rules"][0]["title"]) + self.assertEqual({"id", "text", "order"}, set(doc["applyWhen"][0])) + self.assertEqual([], doc["exceptions"]) # required — 비어도 [] 다 + self.assertEqual([], doc["examples"]) + self.assertIsInstance(doc["purpose"], str) + + def test_reference_verified_on_is_not_invented(self): + """required 이고 `[string, "null"]` 이다. 기록이 안 적었으면 지어내지 않는다.""" + self.assertIsNone(ss._reference_shape({"slug": "s"}, {})["verifiedOn"]) + self.assertEqual("2026-08-30", + ss._reference_shape({"slug": "s"}, + {"lastVerifiedOn": "2026-08-30"})["verifiedOn"]) + + def test_item_ids_are_not_compared_but_text_and_order_are(self): + """서버가 항목 `id` 를 새로 발급한다. 칸 전체를 빼면 항목이 빠진 것도 못 본다.""" + sent = {"facts": [{"id": "a5", "text": "하나", "order": 0}, + {"id": "b5", "text": "둘", "order": 1}]} + same = {"facts": [{"id": "x4", "text": "하나", "order": 0}, + {"id": "y4", "text": "둘", "order": 1}]} + self.assertTrue(ss.compare_saved(sent, same)["same"]) + # **못 보는 것을 값에 적는다** — 빼먹은 것이 아니다 + skipped = ss.compare_saved(sent, same)["itemIdsNotCompared"] + self.assertEqual("facts", skipped[0]["field"]) + self.assertIn("order", skipped[0]["note"]) + # 항목이 빠지거나 순서가 바뀌면 여전히 걸린다 + dropped = {"facts": [{"id": "x4", "text": "하나", "order": 0}]} + self.assertFalse(ss.compare_saved(sent, dropped)["same"]) + swapped = {"facts": [{"id": "x4", "text": "둘", "order": 0}, + {"id": "y4", "text": "하나", "order": 1}]} + self.assertFalse(ss.compare_saved(sent, swapped)["same"]) + def test_a_harness_plan_still_has_no_publish_path(self): steps = ss.plan_requests("docs/p/t/case/x.md", dict(SENT), None, None, harness_test=True)