genetics-mcp 2.0.0

package/skills/genetics-report/assets/visual-baseline.py

@@ -0,0 +1,459 @@
+#!/usr/bin/env python3
+"""일러스트 시각 검수 — **정본 8장이 기준이다.**
+
+왜 있는가
+---------
+2026-08-17 까지 일러스트 검수는 계약 §7 의 「2–8%」라는 숫자로 했다. 그런데 그 숫자를
+**정본으로 검증한 적이 없었다.** 실제로 재 보니 정본은 0.75–1.91% 로 한 장도 그 구간에
+들지 않는다 — 틀린 것은 그림이 아니라 기준이었다. 그 기준을 맞추려던 프롬프트 튜닝이
+정본의 조형 문법을 통째로 지웠다.
+
+그래서 기준을 **문장이 아니라 정본 실물에서 뜬다.** 계약 §7.1 이 이미 그 8장을
+「회귀 기준물로만 보관」이라고 규정해 두었는데, 규정만 있고 **재는 절차가 없었다.**
+
+쓰는 법
+-------
+    python3 tools/visual-baseline.py freeze          # 정본에서 기준선을 뜬다
+    python3 tools/visual-baseline.py check <png>...  # 새 그림을 판정한다
+    python3 tools/visual-baseline.py selftest        # 항등 + 뮤테이션 대조군
+
+`selftest` 가 이 도구의 증명이다 — 정본을 넣으면 **8/8 통과**해야 하고(항등),
+색을 흐트러뜨린 뮤테이션본은 **떨어져야** 한다. 한쪽만 보면 증명이 아니다.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+try:
+    from PIL import Image
+except ImportError:                                    # 검수는 선택 도구가 아니다
+    sys.exit('Pillow 가 필요하다:  python3 -m pip install Pillow')
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.getcwd()          # 표시용 상대경로 기준. 프로젝트마다 다르다.
+
+SAMPLE = 400          # 이 크기로 줄여 세면 충분하다(계약 §7 실측과 같은 조건)
+
+# **팔레트는 문서마다 다르다.** `lim` 은 강조색이 라임 `#B9FF66` 이지만 `korean-navy` 는
+# 금색 `#C9A961` 이다. 색을 상수로 박으면 그 서식에서 전량 오판정한다 —
+# 그래서 네 색은 `private/builder/palette.py` 에서 받는다.
+DEFAULT_PALETTE = None      # **기본 팔레트를 두지 않는다** — 프로젝트마다 다르다.
+DEFAULT_REF = None          # 참조 세트도 마찬가지. 안 주면 물어보게 만든다.
+
+
+def palette_colors(name: str, module: str | None = None) -> dict:
+    """그 팔레트의 네 색(hex).
+
+    **어느 한 저장소의 팔레트에 묶이지 않는다.** 찾는 순서:
+      ① `--palette-module <경로>` 로 준 파일  ② 이 스크립트 옆의 `palette.py`
+    둘 다에 그 이름이 없으면 `--accent/--ink/--surface/--white` 로 직접 주면 된다.
+    """
+    import importlib.util
+    cands = [module] if module else []
+    cands.append(os.path.join(HERE, 'palette.py'))
+    seen = []
+    for c in cands:
+        if not c or not os.path.exists(c):
+            continue
+        spec = importlib.util.spec_from_file_location('_pal', c)
+        m = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(m)
+        pals = getattr(m, 'PALETTES', {})
+        seen += sorted(pals)
+        if name in pals:
+            q = pals[name]
+            return {'white': q.get('bg', '#FFFFFF'), 'surface': q.get('surface', '#F3F3F3'),
+                    'ink': q.get('ink', q['primary']), 'accent': q['secondary']}
+    sys.exit(f'그런 팔레트가 없다: {name}\n'
+             f'  찾아본 곳: {", ".join(c for c in cands if c)}\n'
+             f'  있는 것: {", ".join(sorted(set(seen))) or "(없음)"}\n'
+             f'  또는 색을 직접:  --accent #RRGGBB --ink #RRGGBB --surface #RRGGBB --white #RRGGBB')
+
+
+def _rgb(h: str) -> tuple[int, int, int]:
+    h = h.lstrip('#')
+    return tuple(int(h[i:i + 2], 16) for i in (0, 2, 4))
+
+
+# ── 픽셀을 네 색으로 가른다 ────────────────────────────────────────────────
+# 4색 선화이므로 분류가 곧 계약 §1 의 면적 규칙이다. **거리로 가른다** —
+# 색상(hue) 조건을 손으로 적으면 그 팔레트에서만 맞는다.
+
+def make_classifier(cols: dict):
+    ref = {k: _rgb(v) for k, v in cols.items()}
+
+    def classify(px: tuple[int, int, int]) -> str:
+        best, bd = None, 1e9
+        for k, c in ref.items():
+            d = sum((a - b) ** 2 for a, b in zip(px, c)) ** .5
+            if d < bd:
+                best, bd = k, d
+        # 생성물은 원본 색을 그대로 안 낸다. 너무 멀면 「그 밖」으로 센다.
+        if best == 'white' and bd > 18:
+            return 'other' if bd > 40 else 'white'
+        return best if bd <= 70 else 'other'
+
+    return classify
+
+
+# 시작값 — freeze/check 가 실제 팔레트로 **덮어쓴다**(상수로 쓰라고 둔 것이 아니다).
+_BOOT = {'white': '#FFFFFF', 'surface': '#F3F3F3', 'ink': '#191A23', 'accent': '#B9FF66'}
+classify = make_classifier(_BOOT)
+ACCENT = _rgb(_BOOT['accent'])
+
+
+def measure(path: str) -> dict:
+    """한 장에서 판정에 쓸 지표를 뽑는다."""
+    im = Image.open(path).convert('RGB')
+    w, h = im.size
+    im.thumbnail((SAMPLE, SAMPLE))
+    px = list(im.getdata())
+    W, H = im.size
+    n = len(px)
+
+    count: dict[str, int] = {}
+    acc_px = []
+    for p in px:
+        k = classify(p)
+        count[k] = count.get(k, 0) + 1
+        if k == 'accent':
+            acc_px.append(p)
+
+    pct = {k: round(100 * count.get(k, 0) / n, 3)
+           for k in ('white', 'surface', 'accent', 'ink', 'other')}
+
+    # 대표 강조색 — 목표 hex 와 얼마나 떨어졌나
+    if acc_px:
+        rep = tuple(round(sum(c[i] for c in acc_px) / len(acc_px)) for i in range(3))
+        dist = round(sum((a - b) ** 2 for a, b in zip(rep, ACCENT)) ** .5, 1)
+    else:
+        rep, dist = (0, 0, 0), 999.0
+
+    # 글자리 — 글이 **그림 위에 얹히므로**(계약 4.2절 v1.3) 그 자리가 읽을 수 있어야 한다.
+    #
+    # 「비어 있는가」로 재면 안 된다. 정본 챕터 6장 중 4장이 좌40% 에 잉크를 갖는다
+    # (최대 14.94%) — 그래도 글은 읽힌다. **연하고 고르기** 때문이다.
+    # 그래서 재는 것은 공백이 아니라 **밝기와 균질함**이다:
+    #   · 평균 밝기가 높아야 ink(#191A23, 밝기 25) 글자가 대비를 얻는다
+    #   · 표준편차가 낮아야 글줄이 얼룩 위를 지나지 않는다
+    # 정본 실측(좌46%): 평균 237.7~251.8 · 편차 11.8~51.4.
+    #
+    # 글은 **좌·우 한쪽**에 앉고 장마다 바뀐다(렌더러의 `data-side`). 그래서 두 쪽을 다
+    # 재고, **읽히는 쪽이 하나라도 있으면** 그 그림은 쓸 수 있다. 어느 쪽이 비었는지는
+    # `text_side` 가 말해 주고, 브리프가 지정한 쪽과 같아야 한다.
+    g = im.convert('L')
+    w46 = int(W * .46)
+
+    def band(box):
+        d = list(g.crop(box).getdata())
+        mu = sum(d) / len(d)
+        return round(mu, 1), round((sum((x - mu) ** 2 for x in d) / len(d)) ** .5, 1)
+
+    bg_l, sd_l = band((0, 0, w46, H))
+    bg_r, sd_r = band((W - w46, 0, W, H))
+    left_ink = round(100 * sum(1 for p in list(im.crop((0, 0, int(W * .4), H)).getdata())
+                               if max(p) < 235) / max(1, (int(W * .4) * H)), 2)
+
+    return {
+        'size': [w, h],
+        'aspect': round(w / h, 3),
+        'pct': pct,
+        'accent_rgb': '#%02X%02X%02X' % rep,
+        'accent_dist': dist,
+        'left40_ink': left_ink,
+        'text_bg_l': bg_l, 'text_sd_l': sd_l,   # 왼쪽 46% — 글이 읽히는가
+        'text_bg_r': bg_r, 'text_sd_r': sd_r,   # 오른쪽 46%
+        'text_bg': max(bg_l, bg_r),             # 밝은 쪽 = 글을 앉힐 수 있는 쪽
+        'text_side': 'l' if bg_l >= bg_r else 'r',
+    }
+
+
+# ── 판정 밴드 ─────────────────────────────────────────────────────────────
+# 정본 실측에서 유도한다. **손으로 고른 숫자를 쓰지 않는다** — 그것이 지난 사고의 원인이다.
+# 여유(margin)는 정본 폭에 비례해 준다.
+
+def derive_bands(rows: dict[str, dict]) -> dict:
+    art = {k: v for k, v in rows.items() if not k.startswith('eof')}
+
+    def span(getter, floor=0.0, ceil=100.0, pad=0.25):
+        vals = [getter(v) for v in art.values()]
+        lo, hi = min(vals), max(vals)
+        gap = max((hi - lo) * pad, 0.3)
+        return [round(max(floor, lo - gap), 2), round(min(ceil, hi + gap), 2)]
+
+    out = {
+        'accent':  span(lambda v: v['pct']['accent']),
+        'white': span(lambda v: v['pct']['white'], ceil=100),
+        'surface':  span(lambda v: v['pct']['surface']),
+        'ink':   span(lambda v: v['pct']['ink']),
+        'accent_dist_max': round(max(v['accent_dist'] for v in art.values()) * 1.6, 1),
+    }
+    # hero 안전 영역은 **hero 가 있을 때만** 잰다. 참조 세트에 hero 가 없는 문서도 있고,
+    # 없다고 죽으면 그 프로젝트에서 도구를 아예 못 쓴다(2026-08-17 실측으로 걸렸다).
+    # 글자리 하한 — 두 축을 뜬다. 「비어 있는가」가 아니라 「읽히는가」다
+    # (정본 6장 중 4장은 좌40% 에 잉크가 있고도 글이 읽힌다).
+    #
+    # ① 밝은 쪽    — 어느 쪽이든 하나는 글을 받을 수 있어야 한다.
+    # ② 앉히는 쪽  — 브리프가 정한 쪽이 실제로 그만큼 밝아야 한다.
+    #
+    # ②의 하한을 ①과 같은 값으로 두면 **정본이 자기 기준에 떨어진다** — 정본
+    # chapter-05 는 글이 왼쪽(정본 HTML 의 `chapter-opener` 에 `is-reverse` 없음)인데
+    # 그 왼쪽이 238.9 다. 계약 §7 의 「Lime 2–8%」가 정본 0/7 이었던 것과 같은 함정이라
+    # ②는 **정본이 실제로 글을 앉힌 쪽**의 최솟값에서 뜬다.
+    #
+    # 정본의 좌우는 추정이 아니라 정본 HTML 실측이다:
+    #   1·3·5장 = 글 왼쪽(is-reverse 없음) · 2·4·6장 = 글 오른쪽(is-reverse) · hero = 왼쪽
+    CANON_SIDE = {'1': 'l', '2': 'r', '3': 'l', '4': 'r', '5': 'l', '6': 'r'}
+
+    bgs = [v['text_bg'] for v in art.values()]
+    if bgs:
+        out['text_bg_min'] = round(min(bgs) - 1.0, 1)
+
+    used = []
+    for k, v in art.items():
+        if k.startswith('hero'):
+            sd = 'l'
+        else:
+            digits = [c for c in k if c.isdigit()]
+            sd = CANON_SIDE.get(digits[-1] if digits else '', None)
+        if sd:
+            used.append(v['text_bg_l'] if sd == 'l' else v['text_bg_r'])
+    if used:
+        out['text_side_bg_min'] = round(min(used) - 1.0, 1)
+
+    heroes = [v['left40_ink'] for k, v in art.items() if k.startswith('hero')]
+    if heroes:
+        out['hero_left40_ink_max'] = round(max(heroes) + 0.5, 2)
+    return out
+
+
+def load_baseline(base: str) -> dict:
+    if not os.path.exists(base):
+        sys.exit(f'기준선이 없다: {base}\n  먼저:  python3 tools/visual-baseline.py freeze')
+    d = json.load(open(base, encoding='utf-8'))
+    # 기준선이 **자기 팔레트를 지고 다닌다** — 판정은 뜰 때와 같은 색으로 해야 한다.
+    global classify, ACCENT
+    if d.get('colors'):
+        classify = make_classifier(d['colors'])
+        ACCENT = _rgb(d['colors']['accent'])
+    return d
+
+
+def cmd_freeze(ref: str, pal: str, base: str, module: str | None = None) -> int:
+    return cmd_freeze_cols(ref, palette_colors(pal, module), pal, base)
+
+
+def cmd_freeze_cols(ref: str, cols: dict, pal: str, base: str) -> int:
+    import glob
+    global classify
+    globals()['ACCENT'] = _rgb(cols['accent'])
+    classify = make_classifier(cols)
+    files = sorted(glob.glob(os.path.join(ref, '*.png')))
+    if not files:
+        sys.exit(f'참조 세트가 없다: {ref}')
+    rows = {}
+    for f in files:
+        name = os.path.basename(f)[:-4].replace('lim-report-', '').replace('lim-', '')
+        rows[name] = measure(f)
+        p = rows[name]['pct']
+        print(f"  {name:14} W{p['white']:6.2f}%  S{p['surface']:5.2f}%  "
+              f"A{p['accent']:5.2f}%  I{p['ink']:5.2f}%   {rows[name]['accent_rgb']}")
+
+    out = {
+        'note': '참조 세트에서 뜬 시각 기준선. 손으로 고친 값을 넣지 말 것 — freeze 로만 갱신한다.',
+        'source': os.path.relpath(ref, ROOT) + '/*.png',
+        'palette': pal,
+        'colors': cols,
+        'sample_px': SAMPLE,
+        'assets': rows,
+        'bands': derive_bands(rows),
+    }
+    with open(base, 'w', encoding='utf-8') as fh:
+        json.dump(out, fh, ensure_ascii=False, indent=2)
+        fh.write('\n')
+    b = out['bands']
+    print(f"\n  → {os.path.relpath(base, ROOT)}")
+    print(f"    강조 {b['accent'][0]}–{b['accent'][1]}%  ·  White {b['white'][0]}–{b['white'][1]}%  "
+          f"·  Surface {b['surface'][0]}–{b['surface'][1]}%  ·  Ink {b['ink'][0]}–{b['ink'][1]}%")
+    return 0
+
+
+def judge(path: str, bands: dict, is_hero: bool | None = None) -> tuple[bool, list[str]]:
+    m = measure(path)
+    name = os.path.basename(path)
+    if is_hero is None:
+        is_hero = 'hero' in name.lower()
+    bad = []
+
+    for key, label in (('accent', '강조'), ('white', 'White'), ('surface', 'Surface'), ('ink', 'Ink')):
+        lo, hi = bands[key]
+        v = m['pct'][key]
+        if not (lo <= v <= hi):
+            bad.append(f'{label} {v}% (밴드 {lo}–{hi}%)')
+
+    if m['accent_dist'] > bands['accent_dist_max']:
+        bad.append(f"강조색 {m['accent_rgb']} 거리 {m['accent_dist']} (한도 {bands['accent_dist_max']})")
+
+    # ⚠ 글자리(밝기·쪽) 두 축은 **뺐다**(2026-08-18).
+    #
+    # 그 축은 글이 그림 **위에** 얹힐 때만 뜻이 있었다. 배치가 좌우 분리로 정정되면서
+    # (계약 4.2절 v1.4) 그림 위에는 아무것도 앉지 않는다 — 잴 것이 없다.
+    # 안 재는 것을 재는 척하는 관문은 없는 관문보다 나쁘다: 초록불이 근거로 인용된다.
+    #
+    # 측정 자체(`text_bg_l`·`text_bg_r`·`text_side`)는 남겨 둔다. 판정에는 안 쓰지만
+    # 「이 그림은 어느 쪽이 밝은가」는 배치를 고를 때 사람에게 쓸모가 있다.
+
+    return (not bad), bad
+
+
+def cmd_check(paths: list[str], base: str) -> int:
+    bands = load_baseline(base)['bands']
+    if not paths:
+        sys.exit('검사할 파일을 달라')
+    # `그림.png:r` 은 **더 이상 판정에 안 쓴다**(위 judge 주석). 옛 명령이 죽지 않게
+    # 받아서 떼기만 한다.
+    sides = {}
+    clean = []
+    for raw in paths:
+        if raw.endswith((':l', ':r')) and not os.path.exists(raw):
+            f, sd = raw[:-2], raw[-1]
+            sides[f] = sd
+            clean.append(f)
+        else:
+            clean.append(raw)
+    paths = clean
+    fail = 0
+    for p in paths:
+        # 없는 파일에 예외를 던지면 **관문이 죽는다** — 죽은 관문은 통과로 오독된다.
+        # 생성이 덜 끝났을 때 실제로 그렇게 죽었다(2026-08-17). 없는 것도 실패로 센다.
+        if not os.path.exists(p):
+            print(f'  [실패] {os.path.basename(p)}\n         ✗ 파일이 없다 — 생성이 안 끝났다')
+            fail += 1
+            continue
+        ok, bad = judge(p, bands)
+        mark = '통과' if ok else '실패'
+        m = measure(p)
+        print(f"  [{mark}] {os.path.basename(p)}  (밝은 쪽 {m['text_side']})")
+        for b in bad:
+            print(f'         ✗ {b}')
+        fail += 0 if ok else 1
+    print(f"\n  {len(paths)-fail}/{len(paths)} 통과")
+    return 1 if fail else 0
+
+
+def cmd_selftest(ref: str, base: str) -> int:
+    """대조군 없는 검사는 증명이 아니다 — 양성과 음성을 둘 다 본다."""
+    import glob
+    import io
+    bands = load_baseline(base)['bands']
+    files = sorted(glob.glob(os.path.join(ref, '*.png')))
+    art = [f for f in files if 'eof' not in os.path.basename(f)]
+
+    print('  ① 항등 — 정본을 넣으면 전부 통과해야 한다')
+    ok_n = 0
+    for f in art:
+        ok, bad = judge(f, bands)
+        ok_n += ok
+        if not ok:
+            print(f"     ✗ {os.path.basename(f)}: {'; '.join(bad)}")
+    print(f'     {ok_n}/{len(art)} 통과')
+
+    print('  ② 뮤테이션 — 흐트러뜨린 것은 떨어져야 한다')
+    muts = {
+        '강조색을 흐리게': lambda p: (p[0] - 20, p[1] - 40, p[2] - 10) if classify(p) == 'accent' else p,
+        '강조색을 넓은 면으로':   None,   # 아래에서 따로 만든다
+        '전체를 회색으로':     lambda p: tuple(min(255, int(c * .55 + 90)) for c in p),
+    }
+    caught = 0
+    total = 0
+    src = art[0]
+    tmp = os.path.join(HERE, '.mutation.png')
+    for label, fn in muts.items():
+        im = Image.open(src).convert('RGB')
+        if fn is None:                                # 라임을 프레임의 큰 띠로 칠한다
+            w, h = im.size
+            for y in range(int(h * .40), int(h * .62)):
+                for x in range(0, w):
+                    im.putpixel((x, y), ACCENT)
+        else:
+            im = Image.eval(im, lambda v: v) if False else Image.merge(
+                'RGB', im.split())                      # 사본 확보
+            px = im.load()
+            w, h = im.size
+            for y in range(h):
+                for x in range(w):
+                    px[x, y] = tuple(max(0, min(255, c)) for c in fn(px[x, y]))
+        im.save(tmp)
+        ok, bad = judge(tmp, bands, is_hero=False)
+        total += 1
+        caught += (not ok)
+        print(f"     [{'잡음' if not ok else '놓침'}] {label}"
+              + (f"  ({bad[0]})" if bad else ''))
+    if os.path.exists(tmp):
+        os.remove(tmp)
+    print(f'     {caught}/{total} 잡음')
+
+    good = ok_n == len(art) and caught == total
+    print(f"\n  판정: {'통과' if good else '실패'} "
+          f"— 항등 {ok_n}/{len(art)} · 뮤테이션 {caught}/{total}")
+    return 0 if good else 1
+
+
+def main() -> int:
+    """**어느 프로젝트에서도 돌아간다.** 참조 세트와 색을 인자로 받는다.
+
+        # 팔레트 이름으로 (그 프로젝트의 palette.py 를 가리킨다)
+        python3 visual-baseline.py freeze --ref <원본폴더> \\
+            --palette-module <프로젝트>/palette.py --palette <이름> --base <기준선.json>
+
+        # 팔레트 모듈이 없으면 색을 직접
+        python3 visual-baseline.py freeze --ref <원본폴더> \\
+            --accent '#C9A961' --ink '#141413' --surface '#FAF9F5' --base <기준선.json>
+
+        python3 visual-baseline.py check    --base <기준선.json> <png>...
+        python3 visual-baseline.py selftest --ref <원본폴더> --base <기준선.json>
+
+    `check` 는 기준선이 지고 있는 색으로 판정하므로 인자가 `--base` 하나면 된다.
+    """
+    argv = sys.argv[1:]
+    cmd = argv[0] if argv else ''
+    opt = {'--ref': DEFAULT_REF, '--palette': DEFAULT_PALETTE, '--base': None,
+           '--palette-module': None, '--accent': None, '--ink': None,
+           '--surface': None, '--white': None}
+    files, i = [], 1
+    while i < len(argv):
+        a = argv[i]
+        if a in opt and i + 1 < len(argv):
+            opt[a] = argv[i + 1]; i += 2; continue
+        files.append(a); i += 1
+
+    if cmd in ('freeze', 'selftest') and not opt['--ref']:
+        sys.exit('참조 세트를 달라:  --ref <원본 PNG 들이 있는 폴더>')
+    if not opt['--base']:
+        if cmd == 'freeze':
+            sys.exit('기준선 파일 경로를 달라:  --base <어디에 쓸지>.json')
+        sys.exit('기준선 파일을 달라:  --base <freeze 로 만든>.json')
+
+    if cmd == 'freeze':
+        if opt['--accent']:                      # 색을 직접 준 경우
+            cols = {'white': opt['--white'] or '#FFFFFF',
+                    'surface': opt['--surface'] or '#F3F3F3',
+                    'ink': opt['--ink'] or '#191A23', 'accent': opt['--accent']}
+            return cmd_freeze_cols(opt['--ref'], cols, opt['--palette'] or '(직접 지정)',
+                                   opt['--base'])
+        if not opt['--palette']:
+            sys.exit('팔레트 이름(--palette) 이나 색(--accent …) 중 하나는 줘야 한다')
+        return cmd_freeze(opt['--ref'], opt['--palette'], opt['--base'],
+                          opt['--palette-module'])
+    if cmd == 'check':
+        return cmd_check(files, opt['--base'])
+    if cmd == 'selftest':
+        return cmd_selftest(opt['--ref'], opt['--base'])
+    print(__doc__)
+    return 2
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())